2010-11-02 00:03:50 +03:00
|
|
|
Basic Mapping
|
|
|
|
=============
|
|
|
|
|
2013-09-10 22:55:06 +04:00
|
|
|
This guide explains the basic mapping of entities and properties.
|
|
|
|
After working through this guide you should know:
|
|
|
|
|
|
|
|
- How to create PHP classes that can be saved in the database with Doctrine
|
|
|
|
- How to configure the mapping between columns on tables and properties on
|
2013-09-11 00:08:54 +04:00
|
|
|
entities.
|
|
|
|
- What Doctrine Mapping types are
|
2013-09-10 22:55:06 +04:00
|
|
|
- Defining primary keys and how identifiers are generated by Doctrine
|
2013-09-11 00:08:54 +04:00
|
|
|
- How quoting of reserved symbols works in Doctrine
|
2013-09-10 22:55:06 +04:00
|
|
|
|
2013-08-31 17:46:10 +04:00
|
|
|
Mapping of associations will be covered in the next chapter on
|
|
|
|
:doc:`Association Mapping <association-mapping>`.
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2013-09-10 22:55:06 +04:00
|
|
|
Guide Assumptions
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
You should have already :doc:`installed and configure <configuration>`
|
|
|
|
Doctrine.
|
|
|
|
|
2013-09-10 23:39:40 +04:00
|
|
|
Creating Classes for the Database
|
|
|
|
---------------------------------
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2013-09-10 23:39:40 +04:00
|
|
|
Every PHP Class that you want to save in the database using Doctrine
|
|
|
|
need to be marked as "Entity". The term "Entity" describes objects
|
|
|
|
that have 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
|
|
|
|
example Entity:
|
|
|
|
|
|
|
|
.. code-block:: php
|
|
|
|
|
|
|
|
<?php
|
|
|
|
class Message
|
|
|
|
{
|
|
|
|
private $id;
|
|
|
|
private $text;
|
|
|
|
private $postedAt;
|
|
|
|
}
|
|
|
|
|
|
|
|
Because Doctrine is a generic library, it can only know about your
|
|
|
|
entities when you are describing their existance and structure using
|
2013-09-11 00:08:54 +04:00
|
|
|
Metadata Mapping, a pattern `described by Martin Fowler in PoEAA
|
|
|
|
<http://martinfowler.com/eaaCatalog/metadataMapping.html>`_. Because
|
|
|
|
of this pattern the documentation will often speak of "mapping something",
|
|
|
|
which means that we use the metadata mapping pattern to use this feature.
|
2013-09-10 23:39:40 +04:00
|
|
|
|
|
|
|
Doctrine provides several different ways for specifying object-relational
|
|
|
|
mapping metadata:
|
|
|
|
|
|
|
|
- :doc:`Docblock Annotations <annotations-reference>`
|
|
|
|
- :doc:`XML <xml-mapping>`
|
|
|
|
- :doc:`YAML <yml-mapping>`
|
2013-08-31 17:46:10 +04:00
|
|
|
- PHP code
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2013-08-31 17:46:10 +04:00
|
|
|
This manual usually mentions docblock annotations in all the examples that are
|
|
|
|
spread throughout all chapters, however for many examples alternative YAML and
|
2013-09-10 23:39:40 +04:00
|
|
|
XML examples are given as well.
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2010-11-02 00:03:50 +03:00
|
|
|
.. note::
|
|
|
|
|
2013-09-10 23:39:40 +04:00
|
|
|
All metadata drivers perform equally. Once the metadata of a class has been
|
|
|
|
read from the source (annotations, xml or yaml) it is stored in an instance
|
|
|
|
of the ``Doctrine\ORM\Mapping\ClassMetadata`` class and these instances are
|
|
|
|
stored in the metadata cache. If you're not using a metadata cache (not
|
|
|
|
recommended!) then the XML driver is the fastest by using PHP's native XML
|
|
|
|
support.
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2013-09-10 23:39:40 +04:00
|
|
|
Marking our ``Message`` entity for Doctrine is straightforward:
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2011-06-13 01:07:21 +04:00
|
|
|
.. configuration-block::
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2011-06-13 01:07:21 +04:00
|
|
|
.. code-block:: php
|
|
|
|
|
|
|
|
<?php
|
|
|
|
/** @Entity */
|
2013-09-10 23:39:40 +04:00
|
|
|
class Message
|
2011-06-13 01:07:21 +04:00
|
|
|
{
|
|
|
|
//...
|
|
|
|
}
|
|
|
|
|
|
|
|
.. code-block:: xml
|
|
|
|
|
|
|
|
<doctrine-mapping>
|
2013-09-10 23:39:40 +04:00
|
|
|
<entity name="Message">
|
2011-06-16 23:27:20 +04:00
|
|
|
<!-- ... -->
|
2011-06-13 01:07:21 +04:00
|
|
|
</entity>
|
|
|
|
</doctrine-mapping>
|
|
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
2013-09-10 23:39:40 +04:00
|
|
|
Message:
|
2011-06-13 01:07:21 +04:00
|
|
|
type: entity
|
|
|
|
# ...
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2013-08-31 17:46:10 +04:00
|
|
|
With no additional information given Doctrine expects the entity to be saved
|
2013-09-10 23:39:40 +04:00
|
|
|
into a table with the same name as the class in our case ``Message``.
|
|
|
|
You can change this by configuring information about the table:
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2011-06-13 01:07:21 +04:00
|
|
|
.. configuration-block::
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2011-06-13 01:07:21 +04:00
|
|
|
.. code-block:: php
|
|
|
|
|
|
|
|
<?php
|
|
|
|
/**
|
|
|
|
* @Entity
|
2013-09-10 23:39:40 +04:00
|
|
|
* @Table(name="message")
|
2011-06-13 01:07:21 +04:00
|
|
|
*/
|
2013-09-10 23:39:40 +04:00
|
|
|
class Message
|
2011-06-13 01:07:21 +04:00
|
|
|
{
|
|
|
|
//...
|
|
|
|
}
|
|
|
|
|
|
|
|
.. code-block:: xml
|
|
|
|
|
|
|
|
<doctrine-mapping>
|
2013-09-10 23:39:40 +04:00
|
|
|
<entity name="Message" table="message">
|
2011-06-16 23:27:20 +04:00
|
|
|
<!-- ... -->
|
2011-06-13 01:07:21 +04:00
|
|
|
</entity>
|
|
|
|
</doctrine-mapping>
|
|
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
2013-09-10 23:39:40 +04:00
|
|
|
Message:
|
2011-06-13 01:07:21 +04:00
|
|
|
type: entity
|
2013-09-10 23:39:40 +04:00
|
|
|
table: message
|
2011-06-13 01:07:21 +04:00
|
|
|
# ...
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2013-09-10 23:39:40 +04:00
|
|
|
Now the class ``Message`` will be saved and fetched from the table ``message``.
|
|
|
|
|
|
|
|
Property Mapping
|
|
|
|
----------------
|
|
|
|
|
|
|
|
The next step after defining a PHP class as entity is mapping of properties
|
|
|
|
to columns in a table.
|
|
|
|
|
|
|
|
To configure a property use the ``@Column`` docblock annotation. The ``type``
|
|
|
|
attribute specifies the Doctrine Mapping Type to use for the field. If the type
|
|
|
|
is not specified, ``string`` is used as the default mapping type.
|
|
|
|
|
|
|
|
.. configuration-block::
|
|
|
|
|
|
|
|
.. code-block:: php
|
|
|
|
|
|
|
|
<?php
|
|
|
|
/** @Entity */
|
|
|
|
class Message
|
|
|
|
{
|
|
|
|
/** @Column(type="integer") */
|
|
|
|
private $id;
|
|
|
|
/** @Column(length=140) */
|
|
|
|
private $text;
|
|
|
|
/** @Column(type="datetime", name="posted_at") */
|
|
|
|
private $postedAt;
|
|
|
|
}
|
|
|
|
|
|
|
|
.. code-block:: xml
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
|
|
Message:
|
|
|
|
type: entity
|
|
|
|
fields:
|
|
|
|
id:
|
|
|
|
type: integer
|
|
|
|
text:
|
|
|
|
length: 140
|
|
|
|
postedAt:
|
|
|
|
type: datetime
|
|
|
|
name: posted_at
|
|
|
|
|
|
|
|
Because we don't explicitly specify a column name, Doctrine assumes the field
|
|
|
|
name is also the column name. In the example we configured the property ``id`` to map to the column ``id``
|
|
|
|
using the mapping type ``integer``. The field ``text`` is mapped to the column
|
|
|
|
``text`` with the default mapping type ``string`` and ``postedAt`` is of the
|
|
|
|
datetime type, but mapped to a column called ``posted_at``.
|
|
|
|
|
|
|
|
The Column annotation has some more attributes. Here is a complete
|
|
|
|
list:
|
|
|
|
|
|
|
|
- ``type``: (optional, defaults to 'string') The mapping type to
|
|
|
|
use for the column.
|
|
|
|
- ``name``: (optional, defaults to field name) The name of the
|
|
|
|
column in the database.
|
|
|
|
- ``length``: (optional, default 255) The length of the column in
|
|
|
|
the database. (Applies only if a string-valued column is used).
|
|
|
|
- ``unique``: (optional, default FALSE) Whether the column is a
|
|
|
|
unique key.
|
|
|
|
- ``nullable``: (optional, default FALSE) Whether the database
|
|
|
|
column is nullable.
|
|
|
|
- ``precision``: (optional, default 0) The precision for a decimal
|
|
|
|
(exact numeric) column. (Applies only if a decimal column is used.)
|
|
|
|
- ``scale``: (optional, default 0) The scale for a decimal (exact
|
|
|
|
numeric) column. (Applies only if a decimal column is used.)
|
|
|
|
- ``columnDefinition``: (optional) 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``: (optional) Key-value pairs of options that get passed
|
|
|
|
to the underlying database platform when generating DDL statements.
|
2010-11-01 23:16:12 +03:00
|
|
|
|
|
|
|
Doctrine Mapping Types
|
|
|
|
----------------------
|
|
|
|
|
2013-09-11 00:08:54 +04:00
|
|
|
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, indepedant from the database vendor
|
|
|
|
you are using. All Mapping Types that ship with Doctrine are fully portable
|
|
|
|
between the supported database systems.
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2013-08-31 17:46:10 +04:00
|
|
|
As an example the Doctrine Mapping Type ``string`` defines the
|
2013-03-24 12:16:00 +04:00
|
|
|
mapping from a PHP string to a SQL VARCHAR (or VARCHAR2 etc.
|
2010-11-01 23:16:12 +03:00
|
|
|
depending on the RDBMS brand). Here is a quick overview of the
|
|
|
|
built-in mapping types:
|
|
|
|
|
2013-03-24 12:16:00 +04:00
|
|
|
- ``string``: Type that maps a SQL VARCHAR to a PHP string.
|
|
|
|
- ``integer``: Type that maps a SQL INT to a PHP integer.
|
2010-11-01 23:16:12 +03:00
|
|
|
- ``smallint``: Type that maps a database SMALLINT to a PHP
|
|
|
|
integer.
|
|
|
|
- ``bigint``: Type that maps a database BIGINT to a PHP string.
|
2013-09-11 00:08:54 +04:00
|
|
|
- ``boolean``: Type that maps a SQL boolean or equivalent (TINYINT) to a PHP boolean.
|
2013-03-24 12:16:00 +04:00
|
|
|
- ``decimal``: Type that maps a SQL DECIMAL to a PHP string.
|
|
|
|
- ``date``: Type that maps a SQL DATETIME to a PHP DateTime
|
2010-11-01 23:16:12 +03:00
|
|
|
object.
|
2013-03-24 12:16:00 +04:00
|
|
|
- ``time``: Type that maps a SQL TIME to a PHP DateTime object.
|
|
|
|
- ``datetime``: Type that maps a SQL DATETIME/TIMESTAMP to a PHP
|
2010-11-01 23:16:12 +03:00
|
|
|
DateTime object.
|
2013-03-24 12:16:00 +04:00
|
|
|
- ``datetimetz``: Type that maps a SQL DATETIME/TIMESTAMP to a PHP
|
2013-01-26 19:18:45 +04:00
|
|
|
DateTime object with timezone.
|
2013-03-24 12:16:00 +04:00
|
|
|
- ``text``: Type that maps a SQL CLOB to a PHP string.
|
2010-11-01 23:16:12 +03:00
|
|
|
- ``object``: Type that maps a SQL CLOB to a PHP object using
|
|
|
|
``serialize()`` and ``unserialize()``
|
2012-09-20 15:11:36 +04:00
|
|
|
- ``array``: Type that maps a SQL CLOB to a PHP array using
|
2010-11-01 23:16:12 +03:00
|
|
|
``serialize()`` and ``unserialize()``
|
2013-01-26 19:18:45 +04:00
|
|
|
- ``simple_array``: Type that maps a SQL CLOB to a PHP array using
|
|
|
|
``implode()`` and ``explode()``, with a comma as delimiter. *IMPORTANT*
|
|
|
|
Only use this type if you are sure that your values cannot contain a ",".
|
|
|
|
- ``json_array``: Type that maps a SQL CLOB to a PHP array using
|
|
|
|
``json_encode()`` and ``json_decode()``
|
2010-11-01 23:16:12 +03:00
|
|
|
- ``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.
|
2013-01-21 18:03:46 +04:00
|
|
|
- ``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.
|
2013-03-24 12:16:00 +04:00
|
|
|
- ``blob``: Type that maps a SQL BLOB to a PHP resource stream
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2013-09-11 00:08:54 +04:00
|
|
|
A cookbook article shows how to define :doc:`your own custom mapping types
|
|
|
|
<../cookbook/custom-mapping-types>`.
|
|
|
|
|
2011-08-06 21:12:42 +04:00
|
|
|
.. note::
|
|
|
|
|
2013-09-11 00:08:54 +04:00
|
|
|
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.
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2010-11-02 00:03:50 +03:00
|
|
|
.. warning::
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2011-02-26 18:29:11 +03:00
|
|
|
All Date types assume that you are exclusively using the default timezone
|
|
|
|
set by `date_default_timezone_set() <http://docs.php.net/manual/en/function.date-default-timezone-set.php>`_
|
|
|
|
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.
|
2011-10-31 20:10:30 +04:00
|
|
|
There is also a :doc:`cookbook entry <../cookbook/working-with-datetime>`
|
2011-02-26 18:29:11 +03:00
|
|
|
on working with datetimes that gives hints for implementing
|
|
|
|
multi timezone applications.
|
2010-11-01 23:16:12 +03:00
|
|
|
|
|
|
|
Identifiers / Primary Keys
|
|
|
|
--------------------------
|
|
|
|
|
2013-09-11 00:08:54 +04:00
|
|
|
Every entity class requires an identifier/primary key. You can select
|
2013-08-31 17:46:10 +04:00
|
|
|
the field that serves as the identifier with the ``@Id``
|
2013-09-11 00:08:54 +04:00
|
|
|
annotation.
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2011-06-13 01:07:21 +04:00
|
|
|
.. configuration-block::
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2011-06-13 01:07:21 +04:00
|
|
|
.. code-block:: php
|
|
|
|
|
|
|
|
<?php
|
2013-09-11 00:08:54 +04:00
|
|
|
class Message
|
2011-06-13 01:07:21 +04:00
|
|
|
{
|
|
|
|
/**
|
|
|
|
* @Id @Column(type="integer")
|
|
|
|
* @GeneratedValue
|
|
|
|
*/
|
|
|
|
private $id;
|
2013-09-11 00:08:54 +04:00
|
|
|
//...
|
2011-06-13 01:07:21 +04:00
|
|
|
}
|
|
|
|
|
|
|
|
.. code-block:: xml
|
|
|
|
|
|
|
|
<doctrine-mapping>
|
2013-09-11 00:08:54 +04:00
|
|
|
<entity name="Message">
|
2011-06-13 01:07:21 +04:00
|
|
|
<id name="id" type="integer">
|
|
|
|
<generator strategy="AUTO" />
|
|
|
|
</id>
|
2013-09-11 00:08:54 +04:00
|
|
|
<!-- -->
|
2011-06-13 01:07:21 +04:00
|
|
|
</entity>
|
|
|
|
</doctrine-mapping>
|
|
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
2013-09-11 00:08:54 +04:00
|
|
|
Message:
|
2011-06-13 01:07:21 +04:00
|
|
|
type: entity
|
|
|
|
id:
|
|
|
|
id:
|
|
|
|
type: integer
|
|
|
|
generator:
|
|
|
|
strategy: AUTO
|
|
|
|
fields:
|
2013-09-11 00:08:54 +04:00
|
|
|
# fields here
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2013-09-11 00:08:54 +04:00
|
|
|
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, SERIAL with PostgreSQL,
|
|
|
|
Sequences with Oracle and so on.
|
2010-11-01 23:16:12 +03:00
|
|
|
|
|
|
|
Identifier Generation Strategies
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
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 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 and MsSQL and SEQUENCE for Oracle
|
|
|
|
and PostgreSQL. This strategy provides full portability.
|
|
|
|
- ``SEQUENCE``: Tells Doctrine to use a database sequence for ID
|
|
|
|
generation. This strategy does currently not provide full
|
|
|
|
portability. Sequences are supported by Oracle and PostgreSql.
|
|
|
|
- ``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
|
|
|
|
(AUTO\_INCREMENT), MSSQL (IDENTITY) and PostgreSQL (SERIAL).
|
|
|
|
- ``TABLE``: Tells Doctrine to use a separate table for ID
|
|
|
|
generation. This strategy provides full portability.
|
|
|
|
***This strategy is not yet implemented!***
|
|
|
|
- ``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 to ``EntityManager#persist``. NONE is the
|
|
|
|
same as leaving off the @GeneratedValue entirely.
|
|
|
|
|
|
|
|
Sequence Generator
|
|
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
2011-06-13 01:07:21 +04:00
|
|
|
.. configuration-block::
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2011-06-13 01:07:21 +04:00
|
|
|
.. code-block:: php
|
|
|
|
|
|
|
|
<?php
|
|
|
|
class User
|
|
|
|
{
|
|
|
|
/**
|
|
|
|
* @Id
|
|
|
|
* @GeneratedValue(strategy="SEQUENCE")
|
2011-09-13 22:32:04 +04:00
|
|
|
* @SequenceGenerator(sequenceName="tablename_seq", initialValue=1, allocationSize=100)
|
2011-06-13 01:07:21 +04:00
|
|
|
*/
|
|
|
|
protected $id = null;
|
|
|
|
}
|
|
|
|
|
|
|
|
.. code-block:: xml
|
|
|
|
|
|
|
|
<doctrine-mapping>
|
|
|
|
<entity name="User">
|
|
|
|
<id name="id" type="integer">
|
|
|
|
<generator strategy="SEQUENCE" />
|
|
|
|
<sequence-generator sequence-name="tablename_seq" allocation-size="100" initial-value="1" />
|
|
|
|
</id>
|
|
|
|
</entity>
|
|
|
|
</doctrine-mapping>
|
2011-06-13 01:22:28 +04:00
|
|
|
|
2011-06-13 01:07:21 +04:00
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
|
|
MyPersistentClass:
|
|
|
|
type: entity
|
|
|
|
id:
|
|
|
|
id:
|
|
|
|
type: integer
|
|
|
|
generator:
|
|
|
|
strategy: SEQUENCE
|
|
|
|
sequenceGenerator:
|
|
|
|
sequenceName: tablename_seq
|
|
|
|
allocationSize: 100
|
|
|
|
initialValue: 1
|
2010-11-01 23:16:12 +03:00
|
|
|
|
|
|
|
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 2 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.*
|
|
|
|
|
2010-12-03 22:13:10 +03:00
|
|
|
.. caution::
|
|
|
|
|
|
|
|
The allocationSize is detected by SchemaTool and
|
2010-11-01 23:16:12 +03:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
2010-11-02 00:03:50 +03:00
|
|
|
.. note::
|
|
|
|
|
|
|
|
It is possible to use strategy="AUTO" and at the same time
|
2010-11-01 23:16:12 +03:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
Composite Keys
|
|
|
|
~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
Doctrine 2 allows to use composite primary keys. There are however
|
|
|
|
some restrictions opposed to using a single identifier. The use of
|
|
|
|
the ``@GeneratedValue`` annotation is only supported for simple
|
|
|
|
(not composite) primary keys, which means you can only use
|
|
|
|
composite keys if you generate the primary key values yourself
|
|
|
|
before calling ``EntityManager#persist()`` on the entity.
|
|
|
|
|
|
|
|
To designate a composite primary key / identifier, simply put the
|
|
|
|
@Id marker annotation on all fields that make up the primary key.
|
|
|
|
|
|
|
|
Quoting Reserved Words
|
|
|
|
----------------------
|
|
|
|
|
2013-08-31 17:46:10 +04:00
|
|
|
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 then it would solve. Quoting tables and column names
|
|
|
|
needs to be done explicitly using ticks in the definition.
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2010-12-03 22:13:10 +03:00
|
|
|
.. code-block:: php
|
2010-11-01 23:16:12 +03:00
|
|
|
|
|
|
|
<?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.
|
|
|
|
|
2010-11-02 00:03:50 +03:00
|
|
|
.. warning::
|
|
|
|
|
2013-08-31 17:46:10 +04:00
|
|
|
Identifier Quoting does not work for join column names or discriminator
|
2013-09-08 14:13:47 +04:00
|
|
|
column names unless you are using a custom ``QuoteStrategy``.
|
2010-11-01 23:16:12 +03:00
|
|
|
|
2013-08-31 17:46:10 +04:00
|
|
|
.. _reference-basic-mapping-custom-mapping-types:
|
|
|
|
|
2013-09-08 14:13:47 +04:00
|
|
|
.. versionadded: 2.3
|
|
|
|
|
|
|
|
For more control over column quoting the ``Doctrine\ORM\Mapping\QuoteStrategy`` interface
|
|
|
|
was introduced in 2.3. 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()``.
|
|
|
|
|
|
|
|
.. versionadded: 2.4
|
|
|
|
|
|
|
|
The ANSI Quote Strategy was added, which assumes quoting is not necessary for any SQL name.
|
|
|
|
You can use it with the following code:
|
|
|
|
|
|
|
|
.. code-block:: php
|
|
|
|
|
|
|
|
<?php
|
|
|
|
use Doctrine\ORM\Mapping\AnsiQuoteStrategy;
|
|
|
|
|
|
|
|
$configuration->setQuoteStrategy(new AnsiQuoteStrategy());
|