Relations

The Cycle Annotated package provides multiple attributes designed to describe entity relations. Each relation must be associated with specific entity properties in order to work. In addition, most of the relation options (such as the name of inner, outer keys) will be generated automatically.

You can read more about relation configuration and usage in the dedicated relation documentation pages linked below.

#Common Configuration

Each relation must have a proper target option. The target must point to either the related entity role, or to the class name. You are able to specify class names in a fully qualified (Namespace\Class) or using current entity namespace as the base path. You can use both / and \ namespace separators.

#Common Relation Parameters

Most relation types share these common parameters:

#Foreign Key Parameters

Relations that create foreign keys support these additional parameters:

Read more about foreign key configuration below.

#Relation Types

#Embedded

Embeds another entity's columns into the parent table. Embedded entities are always loaded with the parent.

Documentation: Embedded Relations

use Cycle\Annotated\Annotation\Relation\Embedded;

#[Embedded(target: Address::class)]
private Address $address;

Key Parameters:

Read more about Embeddable entities.

#BelongsTo

Defines that an entity belongs to a parent entity. The child stores the foreign key.

Documentation: BelongsTo Relations

use Cycle\Annotated\Annotation\Relation\BelongsTo;

#[BelongsTo(target: User::class)]
private User $author;

Key Parameters:

Supports foreign key parameters.

#RefersTo

Similar to BelongsTo but used for multiple relations to the same entity or cyclic references.

Documentation: RefersTo Relations

use Cycle\Annotated\Annotation\Relation\RefersTo;

#[RefersTo(target: Comment::class)]
private ?Comment $lastComment;

Key Parameters:

Entity is persisted before related entity, then updated. Supports foreign key parameters.

#HasOne

Defines a one-to-one relationship where the child entity stores the foreign key.

Documentation: HasOne Relations

use Cycle\Annotated\Annotation\Relation\HasOne;

#[HasOne(target: Profile::class)]
private ?Profile $profile;

Key Parameters:

Supports foreign key parameters.

#HasMany

Defines a one-to-many relationship where children store the foreign key.

Documentation: HasMany Relations

use Cycle\Annotated\Annotation\Relation\HasMany;

#[HasMany(target: Post::class)]
private array $posts = [];

Key Parameters:

Supports foreign key parameters.

#ManyToMany

Defines a many-to-many relationship using a pivot (junction) table.

Documentation: ManyToMany Relations

use Cycle\Annotated\Annotation\Relation\ManyToMany;

#[ManyToMany(target: Tag::class, through: PostTag::class)]
private array $tags = [];

Key Parameters:

Supports foreign key parameters for pivot table constraints.

#Morphed Relations

Polymorphic relations allow an entity to belong to multiple entity types. These relations use an interface as target.

Documentation: Morphed Relations

#BelongsToMorphed

Child belongs to any parent implementing an interface.

use Cycle\Annotated\Annotation\Relation\Morphed\BelongsToMorphed;

#[BelongsToMorphed(target: ImageHolderInterface::class)]
private ImageHolderInterface $owner;

Key Parameters:

#MorphedHasOne

Parent owns one child through polymorphic relation.

use Cycle\Annotated\Annotation\Relation\Morphed\MorphedHasOne;

#[MorphedHasOne(target: Image::class)]
private ?Image $avatar;

Key Parameters:

#MorphedHasMany

Parent owns many children through polymorphic relation.

use Cycle\Annotated\Annotation\Relation\Morphed\MorphedHasMany;

#[MorphedHasMany(target: Comment::class)]
private array $comments = [];

Key Parameters:

Note:
Morphed relations do not support foreign key constraints since the target can be multiple entity types.

#Inverse Relations

Many relation types support inverse (bidirectional) relations using the #[Inverse] attribute or inverse parameter:

use Cycle\Annotated\Annotation\Relation\HasMany;
use Cycle\Annotated\Annotation\Relation\Inverse;

#[Entity]
class User
{
    #[HasMany(target: Post::class, inverse: new Inverse(as: 'author', type: 'belongsTo'))]
    private array $posts = [];
}

// Equivalent to defining on the Post entity:
#[Entity]
class Post
{
    #[BelongsTo(target: User::class)]
    private User $author;
}

Inverse Attribute Parameters:

Read more about inverse relations in individual relation documentation pages.

#Foreign Key Configuration

Most relations automatically create foreign key constraints. You can control this behavior:

#Default Behavior

#[BelongsTo(target: User::class)]
private User $user;
// Creates FK: post.user_id -> user.id with CASCADE

#Custom FK Actions

#[BelongsTo(
    target: User::class,
    fkAction: 'SET NULL',        // Both DELETE and UPDATE
    fkOnDelete: 'CASCADE'        // Overrides fkAction for DELETE only
)]
private ?User $user;

#Disable FK Creation

#[HasMany(target: Post::class, fkCreate: false)]
private array $posts = [];

#Disable Index Creation

#[BelongsTo(target: User::class, indexCreate: false)]
private User $user;

#Loading Strategies

Relations support two primary loading strategies:

#Lazy Loading (Default)

Relations are loaded on-demand when accessed:

#[BelongsTo(target: User::class, load: 'lazy')]
private User $author;

// Query to load post
$post = $orm->getRepository(Post::class)->findByPK(1);
// Separate query when accessing author
$author = $post->getAuthor();

#Eager Loading

Relations are loaded immediately with parent entity:

#[BelongsTo(target: User::class, load: 'eager')]
private User $author;

// Single query loads both post and author
$post = $orm->getRepository(Post::class)->findByPK(1);

Best Practice: Use lazy loading by default and explicitly load relations when needed:

php

$posts = $orm->getRepository(Post::class)->select()->load('author')->fetchAll();

Read more about loading strategies in Query Builder.

#See Also

• Embeddable Entities
• Composite Primary Keys
• Relation Collections
• Query Builder - Relations