Annotations Reference

Annotations define how entities map to database tables, relationships, indexes, and lifecycle behavior.

Table and Column Mapping

The @Orm\Table and @Orm\Column annotations define basic entity structure:

<?php
namespace App\Entity;

use Quellabs\ObjectQuel\Annotations\Orm;

/**
 * @Orm\Table(name="products")
 */
class ProductEntity {

    /**
     * @Orm\Column(name="product_id", type="integer", primary_key=true)
     * @Orm\PrimaryKeyStrategy(strategy="identity")
     */
    private ?int $productId = null;

    /**
     * @Orm\Column(name="name", type="string", limit=255)
     */
    private string $name;

    /**
     * @Orm\Column(name="price", type="decimal", limit="10,2")
     */
    private float $price;

    public function getProductId(): ?int { return $this->productId; }
    public function getName(): string { return $this->name; }
    public function setName(string $name): void { $this->name = $name; }
    public function getPrice(): float { return $this->price; }
    public function setPrice(float $price): void { $this->price = $price; }
}

@Orm\Table

Maps an entity class to a database table:

/**
 * @Orm\Table(name="products")
 */
class ProductEntity { }

@Orm\Column

Maps a property to a database column. The name and type parameters are required:

/**
 * @Orm\Column(name="product_name", type="string", limit=255)
 */
private string $name;

/**
 * @Orm\Column(name="price", type="decimal", limit="10,2", unsigned=true)
 */
private float $price;

/**
 * @Orm\Column(name="description", type="text", nullable=true)
 */
private ?string $description = null;

JSON Columns

Columns with type="json" store structured data as a JSON string in the database. ObjectQuel automatically decodes the value to a PHP array on hydration and re-encodes it to a JSON string on persist — no manual serialization is needed.

class ProductEntity {

    /**
     * @Orm\Column(name="attributes", type="json", nullable=true)
     */
    private ?array $attributes = null;

    public function getAttributes(): ?array { return $this->attributes; }
    public function setAttributes(?array $attributes): void { $this->attributes = $attributes; }
}

The PHP property must be declared as array or ?array. ObjectQuel handles the JSON encode/decode boundary transparently; the application always works with plain PHP arrays.

Database engine mapping

The ORM type json is engine-independent. make:migrations translates it to the correct DDL type for the connected database:

@Orm\SourceField

Marks a property as receiving its value from an external source range (such as a JSON source) during hydration. When a query joins a database entity against a json_source() range, ObjectQuel writes the matching field value directly onto the entity property — no manual mapping is needed after the query.

class OrderEntity {

    /**
     * Populated from the JSON source field "name" when a matching record is found.
     * @Orm\SourceField(field="name")
     */
    private ?string $productName = null;

    /**
     * Explicit range — required when the query contains multiple JSON sources.
     * @Orm\SourceField(field="displayName", range="profile")
     */
    private ?string $displayName = null;
}

@Orm\PrimaryKeyStrategy

Defines how primary key values are generated. When omitted, ObjectQuel defaults to identity.

Relationship Annotations

@Orm\ManyToOne

Defines a many-to-one relationship where many entities reference one target entity:

class ProductEntity {
    /**
     * @Orm\ManyToOne(targetEntity="CategoryEntity", fetch="EAGER")
     * @Orm\RequiredRelation
     */
    private ?CategoryEntity $category = null;

    /**
     * @Orm\Column(name="category_id", type="integer")
     */
    private int $categoryId;
}

@Orm\OneToMany

Defines a one-to-many relationship where one entity has many related entities:

use Quellabs\ObjectQuel\Collections\EntityCollection;

class CategoryEntity {
    /**
     * @Orm\OneToMany(targetEntity="ProductEntity", mappedBy="categoryId", orderBy="productId ASC")
     */
    public EntityCollection $products;

    public function __construct() {
        $this->products = new EntityCollection();
    }
}

@Orm\OneToOne

Defines a one-to-one relationship between two entities:

// Owning side (has the foreign key)
class UserEntity {
    /**
     * @Orm\OneToOne(targetEntity="ProfileEntity", inversedBy="user", relationColumn="profile_id", fetch="EAGER")
     */
    private ?ProfileEntity $profile = null;
}

// Inverse side (referenced by foreign key)
class ProfileEntity {
    /**
     * @Orm\OneToOne(targetEntity="UserEntity", mappedBy="profileId", relationColumn="profile_id")
     */
    private ?UserEntity $user = null;
}

@Orm\EntityBridge

ObjectQuel handles many-to-many relationships using explicit entity bridges rather than hidden join tables. This gives you full control over the relationship, including the ability to add metadata:

/**
 * @Orm\Table(name="product_categories")
 * @Orm\EntityBridge
 */
class ProductCategoryEntity {
    /**
     * @Orm\ManyToOne(targetEntity="ProductEntity")
     */
    private ProductEntity $product;

    /**
     * @Orm\ManyToOne(targetEntity="CategoryEntity")
     */
    private CategoryEntity $category;

    /**
     * @Orm\Column(name="assigned_at", type="datetime")
     */
    private \DateTime $assignedAt;

    // You can add any additional metadata to the relationship
    /**
     * @Orm\Column(name="assigned_by", type="integer")
     */
    private int $assignedBy;
}

Entity bridges are regular entities - you can query them, add business logic, and include relationship-specific data.

@Orm\RequiredRelation

Marks a relationship as required, using INNER JOIN instead of LEFT JOIN for better performance:

class ProductEntity {
    /**
     * @Orm\ManyToOne(targetEntity="CategoryEntity", fetch="EAGER")
     * @Orm\RequiredRelation
     */
    private CategoryEntity $category;
}

Use this when the relationship must always exist (e.g., every product must have a category).

Index Annotations

Index annotations are placed at the class level and define database indexes to improve query performance:

/**
 * @Orm\Table(name="products")
 * @Orm\Index(name="idx_product_search", columns={"name", "description"})
 * @Orm\Index(name="idx_price", columns={"price"})
 * @Orm\UniqueIndex(name="idx_unique_sku", columns={"sku"})
 * @Orm\FullTextIndex(name="idx_contents", columns={"contents"})
 */
class ProductEntity { }

@Orm\Index

Creates a regular index on one or more columns to speed up frequently queried fields:

/**
 * @Orm\Table(name="products")
 * @Orm\Index(name="idx_price", columns={"price"})
 */
class ProductEntity { }

@Orm\UniqueIndex

Creates a unique index that prevents duplicate values across the indexed columns:

/**
 * @Orm\Table(name="products")
 * @Orm\UniqueIndex(name="idx_unique_sku", columns={"sku"})
 */
class ProductEntity { }

@Orm\FullTextIndex

Creates a full-text search index for efficient text search across large content fields:

/**
 * @Orm\Table(name="articles")
 * @Orm\FullTextIndex(name="idx_contents", columns={"contents"})
 */
class ArticleEntity { }