Basic Mapping

Creating Classes for the Database

Every PHP object that you want to save in the database using Doctrine is called an Entity. The term "Entity" describes objects that have an identity over many independent requests. This identity is usually achieved by assigning a unique identifier to an entity. In this tutorial the following Message PHP class will serve as the example Entity:

1
<?php
class Message
{
    private $id;
    private $text;
    private $postedAt;
}
2
3
4
5
6
7

Because Doctrine is a generic library, it only knows about your entities because you will describe their existence and structure using mapping metadata, which is configuration that tells Doctrine how your entity should be stored in the database. The documentation will often speak of "mapping something", which means writing the mapping metadata that describes your entity.

Doctrine provides several different ways to specify object-relational mapping metadata:

• Attributes
• XML
• PHP code

This manual will usually show mapping metadata via attributes, though many examples also show the equivalent configuration in XML.

Marking our Message class as an entity for Doctrine is straightforward:

1
<?php
use Doctrine\ORM\Mapping\Entity;

#[Entity]
class Message
{
    // ...
}
2
3
4
5
6
7
8

1
<doctrine-mapping>
  <entity name="Message">
      <!-- ... -->
  </entity>
</doctrine-mapping>
2
3
4
5

With no additional information, Doctrine expects the entity to be saved into a table with the same name as the class in our case Message. You can change this by configuring information about the table:

1
<?php
use Doctrine\ORM\Mapping\Entity;
use Doctrine\ORM\Mapping\Table;

#[Entity]
#[Table(name: 'message')]
class Message
{
    // ...
}
2
3
4
5
6
7
8
9
10

1
<doctrine-mapping>
  <entity name="Message" table="message">
      <!-- ... -->
  </entity>
</doctrine-mapping>
2
3
4
5

Now the class Message will be saved and fetched from the table message.

Property Mapping

The next step is mapping its properties to columns in the table.

To configure a property use the Column attribute. The type argument specifies the Doctrine Mapping Type to use for the field. If the type is not specified, string is used as the default.

1
<?php
use Doctrine\ORM\Mapping\Column;
use Doctrine\DBAL\Types\Types;

#[Entity]
class Message
{
    #[Column(type: Types::INTEGER)]
    private $id;
    #[Column(length: 140)]
    private $text;
    #[Column(name: 'posted_at', type: Types::DATETIME)]
    private $postedAt;
}
2
3
4
5
6
7
8
9
10
11
12
13
14

1
<doctrine-mapping>
  <entity name="Message">
    <field name="id" type="integer" />
    <field name="text" length="140" />
    <field name="postedAt" column="posted_at" type="datetime" />
  </entity>
</doctrine-mapping>
2
3
4
5
6
7

When we don't explicitly specify a column name via the name option, Doctrine assumes the field name is also the column name. So in this example:

• the id property will map to the column id using the type integer;
• the text property will map to the column text with the default mapping type string;
• the postedAt property will map to the posted_at column with the datetime type.

Here is a complete list of Columns attributes (all optional):

• type (default: 'string'): The mapping type to use for the column.
• name (default: name of property): The name of the column in the database.
• length (default: 255): The length of the column in the database. Applies only if a string-valued column is used.
• unique (default: false): Whether the column is a unique key.
• nullable (default: false): Whether the column is nullable.
• insertable (default: true): Whether the column should be inserted.
• updatable (default: true): Whether the column should be updated.
• generated (default: null): Whether the generated strategy should be 'NEVER', 'INSERT' and ALWAYS.
• enumType (requires PHP 8.1 and doctrine/orm 2.11): The PHP enum class name to convert the database value into.
• precision (default: 0): The precision for a decimal (exact numeric) column (applies only for decimal column), which is the maximum number of digits that are stored for the values.
• scale (default: 0): The scale for a decimal (exact numeric) column (applies only for decimal column), which represents the number of digits to the right of the decimal point and must not be greater than precision.
• columnDefinition: Allows to define a custom DDL snippet that is used to create the column. Warning: This normally confuses the SchemaTool to always detect the column as changed.
• options: Key-value pairs of options that get passed to the underlying database platform when generating DDL statements.

Doctrine Mapping Types

The type option used in the @Column accepts any of the existing Doctrine DBAL types or your own custom mapping types. A Doctrine type defines the conversion between PHP and SQL types, independent from the database vendor you are using.

Identifiers / Primary Keys

Every entity class must have an identifier/primary key. You can select the field that serves as the identifier with the #[Id] attribute.

1
<?php
class Message
{
    #[Id]
    #[Column(type: 'integer')]
    #[GeneratedValue]
    private int|null $id = null;
    // ...
}
2
3
4
5
6
7
8
9

1
<doctrine-mapping>
  <entity name="Message">
    <id name="id" type="integer">
        <generator strategy="AUTO" />
    </id>
    <!-- -->
  </entity>
</doctrine-mapping>
2
3
4
5
6
7
8

In most cases using the automatic generator strategy (#[GeneratedValue]) is what you want, but for backwards-compatibility reasons it might not. It defaults to the identifier generation mechanism your current database vendor preferred at the time that strategy was introduced: AUTO_INCREMENT with MySQL, sequences with PostgreSQL and Oracle and so on. If you are using doctrine/dbal 4, we now recommend using IDENTITY for PostgreSQL, and AUTO resolves to it because of that. You can stick with SEQUENCE while still using the AUTO strategy, by configuring what it defaults to.

1
<?php
use Doctrine\DBAL\Platforms\PostgreSQLPlatform;
use Doctrine\ORM\Configuration;

$config = new Configuration();
$config->setIdentityGenerationPreferences([
    PostgreSQLPlatform::class => ClassMetadata::GENERATOR_TYPE_SEQUENCE,
]);
2
3
4
5
6
7
8

1
<?php
class Message
{
    #[Id]
    #[GeneratedValue(strategy: 'SEQUENCE')]
    #[SequenceGenerator(sequenceName: 'message_seq', initialValue: 1, allocationSize: 100)]
    protected int|null $id = null;
    // ...
}
2
3
4
5
6
7
8
9

1
<doctrine-mapping>
  <entity name="Message">
    <id name="id" type="integer">
        <generator strategy="SEQUENCE" />
        <sequence-generator sequence-name="message_seq" allocation-size="100" initial-value="1" />
    </id>
  </entity>
</doctrine-mapping>
2
3
4
5
6
7
8

Quoting Reserved Words

Sometimes it is necessary to quote a column or table name because of reserved word conflicts. Doctrine does not quote identifiers automatically, because it leads to more problems than it would solve. Quoting tables and column names needs to be done explicitly using ticks in the definition.

1
<?php

#[Column(name: '`number`', type: 'integer')]
private $number;
2
3
4

Doctrine will then quote this column name in all SQL statements according to the used database platform.

For more control over column quoting the Doctrine\ORM\Mapping\QuoteStrategy interface was introduced in ORM. It is invoked for every column, table, alias and other SQL names. You can implement the QuoteStrategy and set it by calling Doctrine\ORM\Configuration#setQuoteStrategy().

The ANSI Quote Strategy was added, which assumes quoting is not necessary for any SQL name. You can use it with the following code:

1
<?php
use Doctrine\ORM\Mapping\AnsiQuoteStrategy;

$configuration->setQuoteStrategy(new AnsiQuoteStrategy());
2
3
4