4. Basic Mapping¶
This guide explains the basic mapping of entities and properties. After working through this guide you should know:
How to create PHP objects that can be saved to the database with Doctrine;
Doctrine でデータベースに保存できる PHP オブジェクトを作成する方法;How to configure the mapping between columns on tables and properties on entities;
テーブルの列とエンティティのプロパティ間のマッピングを構成する方法。What Doctrine mapping types are;
Doctrine マッピング タイプとは;Defining primary keys and how identifiers are generated by Doctrine;
主キーの定義と、Doctrine による識別子の生成方法。How quoting of reserved symbols works in Doctrine.
Doctrine で予約済みシンボルの引用がどのように機能するか。
Mapping of associations will be covered in the next chapter on Association Mapping.
4.1. 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:
<?php
class Message
{
private $id;
private $text;
private $postedAt;
}
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:
- 属性
- XML
- PHP コード
Docblock Annotations (deprecated and
Docblock アノテーション (非推奨および
will be removed in
doctrine/orm3.0)doctrine/orm 3.0 で削除されます)
YAML (deprecated and will be removed in
doctrine/orm3.0.)YAML (非推奨であり、doctrine/orm 3.0 で削除されます。)
This manual will usually show mapping metadata via attributes, though many examples also show the equivalent configuration in annotations, YAML and XML.
Note
All metadata drivers perform equally. Once the metadata of a class has been
read from the source (attributes, annotations, XML, etc.) it is stored in an instance
of the Doctrine\ORM\Mapping\ClassMetadata class which are
stored in the metadata cache. If you’re not using a metadata cache (not
recommended!) then the XML driver is the fastest.
Marking our Message class as an entity for Doctrine is straightforward:
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:
Now the class Message will be saved and fetched from the table message.
4.2. 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.
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
idproperty will map to the columnidusing the typeinteger;id プロパティは、整数型を使用して列 id にマップされます。the
textproperty will map to the columntextwith the default mapping typestring;text プロパティは、デフォルトのマッピング タイプ文字列で列テキストにマッピングされます。the
postedAtproperty will map to theposted_atcolumn with thedatetimetype.postedAt プロパティは、datetime タイプの posted_at 列にマップされます。
Here is a complete list of ``Column``s attributes (all optional):
type(default: ‘string’): The mapping type to use for the column.type (デフォルト: 'string'): 列に使用するマッピング タイプ。name(default: name of property): The name of the column in the database.name (デフォルト: プロパティの名前): データベース内の列の名前。length(default: 255): The length of the column in the database. Applies only if a string-valued column is used.length (デフォルト: 255): データベース内の列の長さ。文字列値の列が使用されている場合にのみ適用されます。unique(default:false): Whether the column is a unique key.unique (デフォルト: false): 列が一意のキーかどうか。nullable(default:false): Whether the column is nullable.nullable (デフォルト: false): 列が null 可能かどうか。insertable(default:true): Whether the column should be inserted.insertable (デフォルト: true): 列を挿入するかどうか。updatable(default:true): Whether the column should be updated.updateable (デフォルト: true): 列を更新するかどうか。enumType(requires PHP 8.1 anddoctrine/orm2.11): The PHP enum class name to convert the database value into.enumType (PHP 8.1 および doctrine/orm 2.11 が必要): データベース値を変換する PHP enum クラス名。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.精度 (デフォルト: 0): 10 進数 (正確な数値) 列の精度 (10 進数列にのみ適用されます)。これは、値に対して格納される最大桁数です。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 thanprecision.scale (デフォルト: 0): 10 進数 (正確な数値) 列の位取り (10 進数列にのみ適用)。これは小数点以下の桁数を表し、精度を超えてはなりません。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.columnDefinition: 列の作成に使用される customDDL スニペットを定義できます。警告: これは通常、SchemaTool を混乱させ、常に列が変更されていることを検出します。options: Key-value pairs of options that get passed to the underlying database platform when generating DDL statements.options: DDL ステートメントの生成時に基礎となるデータベース プラットフォームに渡されるオプションのキーと値のペア。
4.2.1. PHP Types Mapping¶
New in version 2.9.
The column types can be inferred automatically from PHP’s property types.
However, when the property type is nullable this has no effect on the nullable Column attribute.
These are the “automatic” mapping rules:
PHP property type PHP プロパティ タイプ |
Doctrine column type 教義列タイプ |
|---|---|
日付間隔 |
タイプ::DATEINTERVAL |
日付時刻 |
タイプ::DATETIME_MUTABLE |
DateTime不変 |
タイプ::DATETIME_IMMUTABLE |
配列 |
タイプ::JSON |
ブール |
タイプ::ブール値 |
浮く |
タイプ::FLOAT |
整数 |
タイプ::INTEGER |
Any other type その他のタイプ |
タイプ::STRING |
As of version 2.11 Doctrine can also automatically map typed properties using a
PHP 8.1 enum to set the right type and enumType.
New in version 2.14.
Since version 2.14 you can specify custom typed field mapping between PHP type and DBAL type using Configuration
and a custom Doctrine\ORM\Mapping\TypedFieldMapper implementation.
Read more about TypedFieldMapper.
4.3. Doctrine Mapping Types¶
The type option used in the @Column accepts any of the existing
Doctrine types or even your own custom types. A Doctrine type defines
the conversion between PHP and SQL types, independent from the database vendor
you are using. All Mapping Types that ship with Doctrine are fully portable
between the supported database systems.
As an example, the Doctrine Mapping Type string defines the
mapping from a PHP string to a SQL VARCHAR (or VARCHAR2 etc.
depending on the RDBMS brand). Here is a quick overview of the
built-in mapping types:
string: Type that maps a SQL VARCHAR to a PHP string.string: SQL VARCHAR を PHP 文字列にマップする型。integer: Type that maps a SQL INT to a PHP integer.integer: SQL INT を PHP 整数にマップする型。smallint: Type that maps a database SMALLINT to a PHP integer.smallint: データベースの SMALLINT を PHPinteger にマップする型。bigint: Type that maps a database BIGINT to a PHP string.bigint: データベース BIGINT を PHP 文字列にマップする型。boolean: Type that maps a SQL boolean or equivalent (TINYINT) to a PHP boolean.boolean: SQL ブール値または同等の値 (TINYINT) を PHP ブール値にマップする型。decimal: Type that maps a SQL DECIMAL to a PHP string.decimal: SQL DECIMAL を PHP 文字列にマップする型。date: Type that maps a SQL DATETIME to a PHP DateTime object.date: SQL DATETIME を PHP DateTime オブジェクトにマップする型。time: Type that maps a SQL TIME to a PHP DateTime object.time: SQL TIME を PHP DateTime オブジェクトにマップする型。datetime: Type that maps a SQL DATETIME/TIMESTAMP to a PHP DateTime object.datetime: SQL DATETIME/TIMESTAMP を PHPDateTime オブジェクトにマップする型。datetimetz: Type that maps a SQL DATETIME/TIMESTAMP to a PHP DateTime object with timezone.datetimetz: SQL DATETIME/TIMESTAMP をタイムゾーン付きの PHPDateTime オブジェクトにマップする型。text: Type that maps a SQL CLOB to a PHP string.text: SQL CLOB を PHP 文字列にマップする型。object: Type that maps a SQL CLOB to a PHP object usingserialize()andunserialize()object: SQL CLOB を PHP オブジェクトにマップする型で、serialize() と unserialize() を使用しますarray: Type that maps a SQL CLOB to a PHP array usingserialize()andunserialize()array: SQL CLOB を PHP 配列にマップする型で、serialize() と unserialize() を使用しますsimple_array: Type that maps a SQL CLOB to a PHP array usingimplode()andexplode(), with a comma as delimiter. IMPORTANT Only use this type if you are sure that your values cannot contain a “,”.simple_array: implode() と destroy() を使用して SQL CLOB を PHP 配列にマップする型で、コンマを区切り文字として使用します。重要値に「,」を含めることができないことが確実な場合にのみ、このタイプを使用してください。json_array: Type that maps a SQL CLOB to a PHP array usingjson_encode()andjson_decode()json_array: json_encode() および json_decode() を使用して SQL CLOB を PHP 配列にマップする型float: Type that maps a SQL Float (Double Precision) to a PHP double. IMPORTANT: Works only with locale settings that use decimal points as separator.float: SQL Float (倍精度) を PHP の double にマップする型。重要: 区切り記号として小数点を使用するロケール設定でのみ機能します。guid: Type that maps a database GUID/UUID to a PHP string. Defaults to varchar but uses a specific type if the platform supports it.guid: データベース GUID/UUID を PHP 文字列にマップする型。デフォルトは varchar ですが、プラットフォームがサポートしている場合は特定の型を使用します。blob: Type that maps a SQL BLOB to a PHP resource streamblob: SQL BLOB を PHP リソース ストリームにマップする型
A cookbook article shows how to define your own custom mapping types.
Note
DateTime and Object types are compared by reference, not by value. Doctrine updates this values if the reference changes and therefore behaves as if these objects are immutable value objects.
Warning
All Date types assume that you are exclusively using the default timezone
set by date_default_timezone_set()
or by the php.ini configuration date.timezone. Working with
different timezones will cause troubles and unexpected behavior.
If you need specific timezone handling you have to handle this in your domain, converting all the values back and forth from UTC. There is also a cookbook entry on working with datetimes that gives hints for implementing multi timezone applications.
4.4. 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.
In most cases using the automatic generator strategy (#[GeneratedValue]) is
what you want. It defaults to the identifier generation mechanism your current
database vendor prefers: AUTO_INCREMENT with MySQL, sequences with PostgreSQL
and Oracle and so on.
The previous example showed how to use the default identifier generation strategy without knowing the underlying database with the AUTO-detection strategy. It is also possible to specify the identifier generation strategy more explicitly, which allows you to make use of some additional features.
Here is the list of possible generation strategies:
AUTO(default): Tells Doctrine to pick the strategy that is preferred by the used database platform. The preferred strategies are IDENTITY for MySQL, SQLite, MsSQL and SQL Anywhere and SEQUENCE for Oracle and PostgreSQL. This strategy provides full portability.AUTO (デフォルト): Doctrine に、使用されているデータベース プラットフォームで優先される戦略を選択するように指示します。推奨される戦略は、MySQL、SQLite、MsSQL、および SQL Anywhere の IDENTITY と、Oracle および PostgreSQL の SEQUENCE です。この戦略は、完全な移植性を提供します。SEQUENCE: Tells Doctrine to use a database sequence for ID generation. This strategy does currently not provide full portability. Sequences are supported by Oracle, PostgreSql and SQL Anywhere.SEQUENCE: ID生成にデータベースシーケンスを使用するようDoctrineに指示します。この戦略は現在、完全な移植性を提供していません。シーケンスは、Oracle、PostgreSql、SQL Anywhere でサポートされています。IDENTITY: Tells Doctrine to use special identity columns in the database that generate a value on insertion of a row. This strategy does currently not provide full portability and is supported by the following platforms: MySQL/SQLite/SQL Anywhere (AUTO_INCREMENT), MSSQL (IDENTITY) and PostgreSQL (SERIAL).IDENTITY: 行の挿入時に値を生成する、データベース内の特別な ID 列を使用するよう Doctrine に指示します。この戦略は現在、完全な移植性を提供しておらず、次のプラットフォームでサポートされています: MySQL/SQLite/SQL Anywhere (AUTO_INCREMENT)、MSSQL (IDENTITY)、および PostgreSQL (SERIAL)。UUID(deprecated): Tells Doctrine to use the built-in Universally Unique Identifier generator. This strategy provides full portability.UUID (非推奨): Doctrine に組み込みの UniversallyUnique Identifier ジェネレーターを使用するように指示します。この戦略は、完全な移植性を提供します。NONE: Tells Doctrine that the identifiers are assigned (and thus generated) by your code. The assignment must take place before a new entity is passed toEntityManager#persist. NONE is the same as leaving off the#[GeneratedValue]entirely.NONE: 識別子がコードによって割り当てられている (したがって生成されている) ことを Doctrine に伝えます。新しいエンティティが EntityManager#persist に渡される前に、割り当てを行う必要があります。 NONE は #[GeneratedValue] を完全に除外することと同じです。CUSTOM: With this option, you can use the#[CustomIdGenerator]attribute. It will allow you to pass a class of your own to generate the identifiers.CUSTOM: このオプションでは、#[CustomIdGenerator] 属性を使用できます。独自のクラスを渡して識別子を生成できます。
The Sequence Generator can currently be used in conjunction with Oracle or Postgres and allows some additional configuration options besides specifying the sequence’s name:
The initial value specifies at which value the sequence should start.
The allocationSize is a powerful feature to optimize INSERT
performance of Doctrine. The allocationSize specifies by how much
values the sequence is incremented whenever the next value is
retrieved. If this is larger than 1 (one) Doctrine can generate
identifier values for the allocationSizes amount of entities. In
the above example with allocationSize=100 Doctrine ORM would only
need to access the sequence once to generate the identifiers for
100 new entities.
The default allocationSize for a @SequenceGenerator is currently 10.
Caution
The allocationSize is detected by SchemaTool and transformed into an “INCREMENT BY “ clause in the CREATE SEQUENCE statement. For a database schema created manually (and not SchemaTool) you have to make sure that the allocationSize configuration option is never larger than the actual sequences INCREMENT BY value, otherwise you may get duplicate keys.
Note
It is possible to use strategy=”AUTO” and at the same time specifying a @SequenceGenerator. In such a case, your custom sequence settings are used in the case where the preferred strategy of the underlying platform is SEQUENCE, such as for Oracle and PostgreSQL.
With Doctrine ORM you can use composite primary keys, using #[Id] on
more than one column. Some restrictions exist opposed to using a single
identifier in this case: The use of the #[GeneratedValue] attribute
is not supported, which means you can only use composite keys if you
generate the primary key values yourself before calling
EntityManager#persist() on the entity.
More details on composite primary keys are discussed in a dedicated tutorial.
4.5. 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.
<?php
#[Column(name: '`number`', type: 'integer')]
private $number;
Doctrine will then quote this column name in all SQL statements according to the used database platform.
Warning
Identifier Quoting does not work for join column names or discriminator
column names unless you are using a custom QuoteStrategy.
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:
<?php
use Doctrine\ORM\Mapping\AnsiQuoteStrategy;
$configuration->setQuoteStrategy(new AnsiQuoteStrategy());
