Struct: date structurate

Leto\Data\Struct este o clasă abstractă pentru containere de date tipizate. Oferă serializare automată în array și JSON, reflection și auto-documentare.

Citește această pagină înainte de ORM: Model extinde Struct, deci toate metodele toArray(), fromArray(), toJson(), fromJson() și describe() de mai jos sunt moștenite de fiecare model.

Definirea unui Struct

Un Struct este o clasă cu proprietăți publice tipate:

use Leto\Data\Struct;

class ColumnDefinition extends Struct
{
    public string $name;
    public string $type;
    public bool $isPrimaryKey;
    public bool $isAutoIncrement;
    public bool $isNullable;
    public bool $hasDefault;
    public ?string $default;
}

Nu ai nevoie de getteri, setteri sau array-uri de configurare, doar proprietăți PHP tipate. Tipurile sunt deduse automat.

Creare și populare

// Instanțiere directă
$col = new ColumnDefinition();
$col->name = 'id';
$col->type = 'BIGINT(20)';
$col->isPrimaryKey = true;
$col->isAutoIncrement = true;
$col->isNullable = false;
$col->hasDefault = false;
$col->default = null;

Serializare

Array

$col = new ColumnDefinition();
$col->name = 'email';
$col->type = 'VARCHAR(255)';

// Convertire în array
$data = $col->toArray();
// ['name' => 'email', 'type' => 'VARCHAR(255)']
// Implicit apar doar proprietățile INIȚIALIZATE; câmpurile tipate încă nesetate
// (isPrimaryKey, default etc.) sunt omise, nu apar ca null.

// Creare din array
$col2 = ColumnDefinition::fromArray($data);

// Actualizare din array
$col->updateFromArray(['isNullable' => true]);

JSON

// Convertire în JSON
$json = $col->toJson();
// '{"name":"email","type":"VARCHAR(255)",...}'

// JSON formatat
$json = $col->toJson(pretty: true);

// Creare din JSON
$col2 = ColumnDefinition::fromJson($json);

// Actualizare din JSON
$col->updateFromJson($json);

Array-uri tipizate cu `#[ArrayOf]`

Când un câmp este un array de Struct-uri, folosește #[ArrayOf] pentru a specifica tipul elementelor:

use Leto\Data\Attributes\ArrayOf;

class TableDefinition extends Struct
{
    public string $name;

    #[ArrayOf(ColumnDefinition::class)]
    public array $columns;
}

Serializarea și deserializarea merg recursiv: array-ul de ColumnDefinition este automat convertit.

`describe()`: reflection automat

Fiecare Struct expune metoda statică describe() care returnează metadate despre toate proprietățile:

$desc = ColumnDefinition::describe();

// $desc->name → 'ColumnDefinition'      (numele complet al clasei, cu namespace dacă are unul)
// $desc->className → 'ColumnDefinition'
// $desc->attributes → [
//     'name' => StructAttributeDescription { name: 'name', type: 'string', ... },
//     'type' => StructAttributeDescription { name: 'type', type: 'string', ... },
//     ...
// ]

Pentru fiecare atribut, StructAttributeDescription oferă:

Câmp	Descriere
`name`	Numele proprietății
`type`	Tipul PHP (`string`, `int`, `bool`, `DateTimeImmutable`, etc.)
`nullable`	Dacă acceptă `null`
`hasDefault`	Dacă are valoare implicită
`default`	Valoarea implicită
`defaultIsExpression`	Dacă valoarea implicită e o expresie SQL raw (nu un literal)
`arrayType`	Tipul elementelor (dacă e array cu `#[ArrayOf]`)
`virtual`	Dacă e un câmp virtual (nu stocat)

Cazuri reale de utilizare

Struct este folosit în proiectele Workleto ca bază pentru:

Definiții de tabele și coloane: ColumnDefinition și TableDefinition moștenesc Struct pentru a reprezenta schema bazei de date
Job-uri: clasa abstractă Job extinde Struct, iar clasele concrete adaugă proprietățile specifice fiecărui job; Struct oferă serialize/deserialize pentru starea job-ului
Model (ORM): Model extinde Struct, adăugând capabilități de interogare, relații și persistență. Toate metodele toArray(), fromArray(), toJson(), fromJson() sunt moștenite din Struct.

De ce Struct și nu array-uri simple?

Array simplu	Struct
`$data['name']`, fără autocompletare	`$obj->name`, completare IDE
Fără verificare de tip	Tipuri PHP native (`string`, `int`, `bool`)
Nedocumentat, greu de înțeles	`describe()` oferă schema completă
Serializare manuală	`toArray()` / `toJson()` automat
Fără `#[ArrayOf]` recursiv	Arrays tipizate, serializare recursivă

Validare