Skip to content

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:

#[PrimaryKey(dbFieldName: 'document_id')]
private ?string $id = null;

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 supported FieldValueType cases;
  • 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:

  • string
  • int
  • float
  • boolean
  • date
  • dateTime
  • timestamp
  • json

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:

#[Field(type: FieldValueType::boolean, format: ['N', 'Y'])]
private ?bool $enabled = null;

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;

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].

Next chapter: Relations and entity collections