Entities and fields¶
Class attributes¶
#[OrmEntity] is mandatory. #[Collection(MyCollection::class)] optionally selects a custom EntityCollection implementation for manager results.
#[NoLastInsertId] tells SQL drivers not to request a database-generated identifier. Use it for UUID, ULID or other application-generated primary keys.
#[OrmEntity]
#[NoLastInsertId]
final class DocumentEntity extends AbstractEntity
{
#[PrimaryKey]
private ?string $id = null;
}
Primary keys¶
The core supports more than one #[PrimaryKey] property. Composite keys are exposed through getPrimaryKeys() and are included in update/delete predicates.
A database field name can be specified explicitly:
For auto-increment keys, leave the value null before the first insert. For application-generated keys, combine a non-null value with #[NoLastInsertId].
Fields¶
#[Field(
type: FieldValueType::string,
defaultValue: 'draft',
dbFieldName: 'publication_status',
)]
private ?string $status = null;
Field parameters are:
type: one of the supportedFieldValueTypecases;format: conversion information for dates, booleans and JSON;defaultValue: applied when a new entity is created;dbFieldName: overrides the default camel-case to snake-case mapping.
Supported value types:
stringintfloatbooleandatedateTimetimestampjson
Date and time fields¶
#[Field(type: FieldValueType::date, format: 'Y-m-d')]
private ?\DateTimeInterface $publicationDate = null;
#[Field(type: FieldValueType::dateTime, format: 'Y-m-d H:i:s.u')]
private ?\DateTimeInterface $updatedAt = null;
#[Field(type: FieldValueType::timestamp)]
private ?\DateTimeInterface $expiresAt = null;
Database hydration accepts second or microsecond precision for date-time values. Invalid database values produce an explicit conversion exception instead of silently returning false.
Boolean fields¶
The default SQL representation is [0, 1]. A custom pair can be supplied as the field format:
JSON fields¶
use Small\SwooleEntityManager\EntityManager\Enum\JsonFormatType;
#[Field(type: FieldValueType::json, format: JsonFormatType::array)]
private ?array $metadata = null;
#[Field(type: FieldValueType::json, format: JsonFormatType::stdClass)]
private ?\stdClass $settings = null;
Small Forms metadata¶
ORM mapping and input validation can coexist on the same property. Small Forms 2.3 exposes all of its built-in validators and modifiers as property attributes, so persistence metadata, input type, normalization and validation can remain colocated without coupling Core persistence to form validation.
use Small\Forms\Form\Field\Type\StringType;
use Small\Forms\Modifier\TrimModifier;
use Small\Forms\ValidationRule\ValidateNotEmpty;
#[Field(type: FieldValueType::string)]
#[StringType]
#[TrimModifier]
#[ValidateNotEmpty]
private ?string $name = null;
Explicit Small Forms types are recommended for nullable ORM fields because nullable scalar types are not reliably inferred by the attribute adapter. See Small Forms: Entity attributes and type resolution for the complete attribute workflow and the validation / modifier catalogs.
Automatic entity lifecycle hooks¶
Entities can implement OnNewInterface to initialize application-generated keys and initial values when a manager creates a new entity, and OnLoadInterface to react after database hydration. Persistence hooks cover inserts, updates and deletes. These interfaces are optional and callbacks are dispatched by the manager, not the controller.
See Lifecycle hooks for all ten interfaces, their execution order, complete examples and the Core version requirements.
Serialization and selective persistence¶
$array = $entity->toArray();
$arrayWithRelations = $entity->toArray(withDependencies: true);
$object = $entity->toStdClass(withDependencies: true);
$entity->notPersist('updatedAt')->persist();
notPersist() excludes one mapped field from the next persistence payload. It only accepts properties carrying #[Field].