ORM Attributes Reference

In Osumi Framework, database mappings are defined using PHP Attributes on model class properties. This document details all available attributes, their parameters, and expected behaviors.

`#[OPK]`

Defines a Primary Key field. Every model must have at least one.

Parameter	Type	Default	Description
`type`	`string`	`OField::NUMBER`	Data type (see Types below).
`incr`	`bool`	`true`	Whether the field is auto-incremental.
`comment`	`string`	`''`	Comment for the database column.
`ref`	`string`	`''`	Foreign key reference (format: `'table.field'`).
`nullable`	`bool`	`true`	Whether the field can store `null` values.
`default`	`mixed`	`null`	Default value for the column.

`#[OField]`

Defines a standard database column.

Parameter	Type	Default	Description
`type`	`string`	`null`	Data type (Mandatory).
`nullable`	`bool`	`true`	Whether the field can store `null` values.
`default`	`mixed`	`null`	Default value for the column.
`max`	`int`	`50`	Maximum size/length for the field.
`comment`	`string`	`''`	Comment for the database column.
`visible`	`bool`	`true`	Whether the field is included when serializing the model.
`ref`	`string`	`''`	Foreign key reference (format: `'table.field'`).

Temporal Attributes

These attributes handle automatic timestamping. Each model must have exactly one #[OCreatedAt] and one #[OUpdatedAt].

`#[OCreatedAt]`

Automatically set when a record is first created (INSERT).

Parameter: comment (string) - Column comment.

`#[OUpdatedAt]`

Automatically updated whenever the record is modified (UPDATE).

Parameter: comment (string) - Column comment.

`#[ODeletedAt]`

Used for soft-delete functionality (tracking when a record was "removed").

Parameter: comment (string) - Column comment.

Data Types (`OField` Constants)

When defining type in #[OPK] or #[OField], use these constants from the Osumi\OsumiFramework\ORM\OField class:

OField::NUMBER: Integer values.
OField::TEXT: Short strings (usually mapped to VARCHAR).
OField::LONGTEXT: Large text blocks (usually mapped to LONGTEXT).
OField::FLOAT: Floating-point numbers.
OField::BOOL: Boolean values.
OField::DATE: Date/Time strings.

Usage Example

use Osumi\OsumiFramework\ORM\OModel;
use Osumi\OsumiFramework\ORM\OPK;
use Osumi\OsumiFramework\ORM\OField;
use Osumi\OsumiFramework\ORM\OCreatedAt;
use Osumi\OsumiFramework\ORM\OUpdatedAt;

class Product extends OModel {
    #[OPK(comment: 'Unique product ID')]
    public ?int $id = null;

    #[OField(type: OField::TEXT, max: 150, nullable: false, comment: 'Product name')]
    public ?string $name = null;

    #[OField(type: OField::NUMBER, ref: 'category.id', comment: 'Link to category')]
    public ?int $id_category = null;

    #[OCreatedAt(comment: 'Creation timestamp')]
    public ?string $created_at = null;

    #[OUpdatedAt(comment: 'Last update timestamp')]
    public ?string $updated_at = null;
}

Validation Logic

The OModel base class uses these attributes during the save() process:

Length Check: If a property string exceeds the max value, an exception is thrown.
Nullability: If a property is null but nullable is set to false, an exception is thrown.
Primary Key: Ensures at least one #[OPK] is defined before proceeding.

ORM Attributes Reference

#[OPK]

#[OField]

Temporal Attributes

#[OCreatedAt]

#[OUpdatedAt]

#[ODeletedAt]

Data Types (OField Constants)