You are browsing a version that is no longer maintained.

Separating Concerns using Embeddables

Embeddables are classes which are not entities themselves, but are embedded in entities and can also be queried in DQL. You'll mostly want to use them to reduce duplication or separating concerns. Value objects such as date range or address are the primary use case for this feature.

Embeddables can only contain properties with basic @Column mapping.

For the purposes of this tutorial, we will assume that you have a User class in your application and you would like to store an address in the User class. We will model the Address class as an embeddable instead of simply adding the respective columns to the User class.

1 <?php

#[Entity]
class User
{
    #[Embedded(class: Address::class)]
    private Address $address;
}

#[Embeddable]
class Address
{
    #[Column(type: "string")]
    private string $street;

    #[Column(type: "string")]
    private string $postalCode;

    #[Column(type: "string")]
    private string $city;

    #[Column(type: "string")]
    private string $country;
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

1 <?php

/** @Entity */
class User
{
    /** @Embedded(class = "Address") */
    private Address $address;
}

/** @Embeddable */
class Address
{
    /** @Column(type = "string") */
    private string $street;

    /** @Column(type = "string") */
    private string $postalCode;

    /** @Column(type = "string") */
    private string $city;

    /** @Column(type = "string") */
    private string $country;
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

1 <doctrine-mapping>
    <entity name="User">
        <embedded name="address" class="Address" />
    </entity>

    <embeddable name="Address">
        <field name="street" type="string" />
        <field name="postalCode" type="string" />
        <field name="city" type="string" />
        <field name="country" type="string" />
    </embeddable>
</doctrine-mapping>
2
3
4
5
6
7
8
9
10
11
12

1 User:
  type: entity
  embedded:
    address:
      class: Address

Address:
  type: embeddable
  fields:
    street: { type: string }
    postalCode: { type: string }
    city: { type: string }
    country: { type: string }
2
3
4
5
6
7
8
9
10
11
12
13

In terms of your database schema, Doctrine will automatically inline all columns from the Address class into the table of the User class, just as if you had declared them directly there.

Initializing embeddables

In case all fields in the embeddable are nullable, you might want to initialize the embeddable, to avoid getting a null value instead of the embedded object.

1 public function __construct()
{
    $this->address = new Address();
}
2
3
4

Column Prefixing

By default, Doctrine names your columns by prefixing them, using the value object name.

Following the example above, your columns would be named as address_street, address_postalCode...

You can change this behaviour to meet your needs by changing the columnPrefix attribute in the @Embedded notation.

The following example shows you how to set your prefix to myPrefix_:

1 <?php

#[Entity]
class User
{
    #[Embedded(class: Address::class, columnPrefix: "myPrefix_")]
    private Address $address;
}
2
3
4
5
6
7
8

1 <?php

/** @Entity */
class User
{
    /** @Embedded(class = "Address", columnPrefix = "myPrefix_") */
    private $address;
}
2
3
4
5
6
7
8

1 <entity name="User">
    <embedded name="address" class="Address" column-prefix="myPrefix_" />
</entity>
2
3

1 User:
  type: entity
  embedded:
    address:
      class: Address
      columnPrefix: myPrefix_
2
3
4
5
6

To have Doctrine drop the prefix and use the value object's property name directly, set columnPrefix=false (use-column-prefix="false" for XML):

1 <?php

#[Entity]
class User
{
    #[Embedded(class: Address::class, columnPrefix: false)]
    private Address $address;
}
2
3
4
5
6
7
8

1 <?php

/** @Entity */
class User
{
    /** @Embedded(class = "Address", columnPrefix = false) */
    private Address $address;
}
2
3
4
5
6
7
8

1 <entity name="User">
    <embedded name="address" class="Address" use-column-prefix="false" />
</entity>
2
3

1 User:
  type: entity
  embedded:
    address:
      class: Address
      columnPrefix: false
2
3
4
5
6

DQL

You can also use mapped fields of embedded classes in DQL queries, just as if they were declared in the User class:

1 SELECT u FROM User u WHERE u.address.city = :myCity

1	<?php #[Entity] class User { #[Embedded(class: Address::class)] private Address $address; } #[Embeddable] class Address { #[Column(type: "string")] private string $street; #[Column(type: "string")] private string $postalCode; #[Column(type: "string")] private string $city; #[Column(type: "string")] private string $country; }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

1	<?php /** @Entity / class User { /* @Embedded(class = "Address") / private Address $address; } /* @Embeddable / class Address { /* @Column(type = "string") / private string $street; /* @Column(type = "string") / private string $postalCode; /* @Column(type = "string") / private string $city; /* @Column(type = "string") */ private string $country; }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

1	<doctrine-mapping> <entity name="User"> <embedded name="address" class="Address" /> </entity> <embeddable name="Address"> <field name="street" type="string" /> <field name="postalCode" type="string" /> <field name="city" type="string" /> <field name="country" type="string" /> </embeddable> </doctrine-mapping>
2
3
4
5
6
7
8
9
10
11
12

1	User: type: entity embedded: address: class: Address Address: type: embeddable fields: street: { type: string } postalCode: { type: string } city: { type: string } country: { type: string }
2
3
4
5
6
7
8
9
10
11
12
13

1	public function __construct() { $this->address = new Address(); }
2
3
4

1	<entity name="User"> <embedded name="address" class="Address" column-prefix="myPrefix_" /> </entity>
2
3

Maintained

Unmaintained

Separating Concerns using Embeddables

Initializing embeddables

Column Prefixing

DQL