Database Schema Reference

FW uses a strictly typed compile-time Data Mapper instead of Active Record. The schema is defined centrally in database/schema.yaml.

Running fw build:db compiles this file into:

1. class [Entity]Model: A strongly typed DTO.
2. Base[Entity]Repository: Pre-compiled raw SQL mapping exactly to the schema, preventing N+1 queries.
3. SQL Migration Scripts in database/migrations/.

Writing schema.yaml

models:
  User:
    id: uuid @primary
    email: string @unique
    age: int?
    is_active: bool

Supported Data Types

FW maps simple YAML data types directly into PHP primitive types and SQL column structures.

• string: Standard VARCHAR(255). Maps to PHP string.
• int: Standard INTEGER. Maps to PHP int.
• float: Standard DECIMAL or FLOAT. Maps to PHP float.
• bool: Standard TINYINT(1) or BOOLEAN. Maps to PHP bool.
• uuid: Character length 36 VARCHAR(36). Maps to PHP string.

Nullable Types

Appending a ? to any type marks it as optional/nullable.

• int? -> mapped to SQL INTEGER NULL -> mapped to PHP ?int.

Modifiers (Annotations)

Modifiers are appended to the type definition using the @ symbol:

• @primary: Marks the field as the PRIMARY KEY.
• @unique: Applies a UNIQUE constraint to the SQL column.

Relationships (Foreign Keys)

FW does not dynamically load relations like Eloquent (e.g., $user->posts). This design actively prevents hidden queries.

To define a schema relationship:

  Post:
    id: int @primary
    title: string
    user_id: int @foreign(User.id)

• @foreign(Entity.column): Generates an SQL Application-Level Foreign Key constraint in the migrations.

When querying relationships, the developer must explicitly define a repository method (e.g., findWithPosts(int $userId)) that performs a JOIN and returns an aggregate array of PostModel DTOs.