Has One (One-to-One)

The HasOne relationship in CycleORM signifies that an entity exclusively owns another entity in a parent-child relationship. This can be seen as a form of decomposition, with the ability to store child entity data in an external table. The HasOne relationship is used to define a connection to one child object, which will be automatically saved with its parent unless the cascade option is set to false.

app/Entities/User.php

<?php
 
declare(strict_types=1);
 
namespace App\Entities;
 
use Cycle\Annotated\Annotation\Entity;
use Cycle\Annotated\Annotation\Relation\HasOne;
 
#[Entity]
class User
{
    // ...
 
    #[HasOne(target: Profile::class, nullable: true)]
    private ?Profile $profile;
 
    public function __construct(?Profile $profile = null)
    {
        $this->profile = $profile;
    }
 
    public function profile(): ?Profile
    {
        return $this->profile;
    }
 
    public function setProfile(?Profile $profile): void
    {
        $this->profile = $profile;
    }
}

Inverse side of the relationship can be defined in the Profile entity:

app/Entities/Profile.php

<?php
 
declare(strict_types=1);
 
namespace App\Entities;
 
use Cycle\Annotated\Annotation\Entity;
use Cycle\Annotated\Annotation\Relation\BelongsTo;
 
#[Entity]
class Profile
{
    // ...
 
    #[BelongsTo(target: User::class)]
    private User $user;
 
    public function user(): User
    {
        return $this->user;
    }
 
    public function changeUser(User $user): void
    {
        $this->user = $user;
    }
 
    // ...
}

It's important to handle cases where the relation is not initialized (null).

By default, the ORM generates an outer key in the child object using the parent entity's role and inner key (usually the primary key). As a result, a column and foreign key will be added to the child entity (e.g., Profile) on a column like user_id.

Usage

To attach a child object to the parent entity, simply set the value on the designated property. For example:

$user = new User();
$user->setProfile(new Profile());
 
// or, directly,
// if public properties are used
$user->profile = new Profile();

The related object can be immediately saved into the database by persisting the parent entity:

$manager = app(EntityManagerInterface::class);
 
$manager->persist($user);
$manager->run();

To delete a previously associated object simply set the property value to null:

$user->setProfile(null);
 
// or, directly,
// if public properties are used
$user->profile = null;
 
$manager->persist($user);
$manager->run();

The child object will be removed during the persist operation.

To avoid child object removal (detach) set nullable to true. In this case, child outer key will be reset to null.

💡

Detailed explanation of One-to-One (HasOne) relationships in CycleORM documentation.

Working with Relationships Has Many (One-to-Many)