268 lines
8.7 KiB
ReStructuredText
268 lines
8.7 KiB
ReStructuredText
Limitations and Known Issues
|
|
============================
|
|
|
|
We try to make using Doctrine2 a very pleasant experience.
|
|
Therefore we think it is very important to be honest about the
|
|
current limitations to our users. Much like every other piece of
|
|
software Doctrine2 is not perfect and far from feature complete.
|
|
This section should give you an overview of current limitations of
|
|
Doctrine 2 as well as critical known issues that you should know
|
|
about.
|
|
|
|
Current Limitations
|
|
-------------------
|
|
|
|
There is a set of limitations that exist currently which might be
|
|
solved in the future. Any of this limitations now stated has at
|
|
least one ticket in the Tracker and is discussed for future
|
|
releases.
|
|
|
|
Foreign Keys as Identifiers
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
There are many use-cases where you would want to use an
|
|
Entity-Attribute-Value approach to modelling and define a
|
|
table-schema like the following:
|
|
|
|
.. code-block:: sql
|
|
|
|
CREATE TABLE product (
|
|
id INTEGER,
|
|
name VARCHAR,
|
|
PRIMARY KEY(id)
|
|
);
|
|
|
|
CREATE TABLE product_attributes (
|
|
product_id INTEGER,
|
|
attribute_name VARCHAR,
|
|
attribute_value VARCHAR,
|
|
PRIMARY KEY (product_id, attribute_name)
|
|
);
|
|
|
|
This is currently *NOT* possible with Doctrine2. You have to define
|
|
a surrogate key on the ``product_attributes`` table and use a
|
|
unique-constraint for the ``product_id`` and ``attribute_name``.
|
|
|
|
.. code-block:: sql
|
|
|
|
CREATE TABLE product_attributes (
|
|
attribute_id, INTEGER,
|
|
product_id INTEGER,
|
|
attribute_name VARCHAR,
|
|
attribute_value VARCHAR,
|
|
PRIMARY KEY (attribute_id),
|
|
UNIQUE (product_id, attribute_name)
|
|
);
|
|
|
|
Although we state that we support composite primary keys that does
|
|
not currently include foreign keys as primary key columns. To see
|
|
the fundamental difference between the two different
|
|
``product_attributes`` tables you should see how they translate
|
|
into a Doctrine Mapping (Using Annotations):
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
/**
|
|
* Scenario 1: THIS IS NOT POSSIBLE CURRENTLY
|
|
* @Entity @Table(name="product_attributes")
|
|
*/
|
|
class ProductAttribute
|
|
{
|
|
/** @Id @ManyToOne(targetEntity="Product") */
|
|
private $product;
|
|
|
|
/** @Id @Column(type="string", name="attribute_name") */
|
|
private $name;
|
|
|
|
/** @Column(type="string", name="attribute_value") */
|
|
private $value;
|
|
}
|
|
|
|
/**
|
|
* Scenario 2: Using the surrogate key workaround
|
|
* @Entity
|
|
* @Table(name="product_attributes", uniqueConstraints={@UniqueConstraint(columns={"product_id", "attribute_name"})}))
|
|
*/
|
|
class ProductAttribute
|
|
{
|
|
/** @Id @Column(type="integer") @GeneratedValue */
|
|
private $id;
|
|
|
|
/** @ManyToOne(targetEntity="Product") */
|
|
private $product;
|
|
|
|
/** @Column(type="string", name="attribute_name") */
|
|
private $name;
|
|
|
|
/** @Column(type="string", name="attribute_value") */
|
|
private $value;
|
|
}
|
|
|
|
The following Jira Issue
|
|
`contains the feature request to allow @ManyToOne and @OneToOne annotations along the @Id annotation <http://www.doctrine-project.org/jira/browse/DDC-117>`_.
|
|
|
|
Mapping Arrays to a Join Table
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Related to the previous limitation with "Foreign Keys as
|
|
Identifier" you might be interested in mapping the same table
|
|
structure as given above to an array. However this is not yet
|
|
possible either. See the following example:
|
|
|
|
.. code-block:: sql
|
|
|
|
CREATE TABLE product (
|
|
id INTEGER,
|
|
name VARCHAR,
|
|
PRIMARY KEY(id)
|
|
);
|
|
|
|
CREATE TABLE product_attributes (
|
|
product_id INTEGER,
|
|
attribute_name VARCHAR,
|
|
attribute_value VARCHAR,
|
|
PRIMARY KEY (product_id, attribute_name)
|
|
);
|
|
|
|
This schema should be mapped to a Product Entity as follows:
|
|
|
|
.. code-block:: php
|
|
|
|
class Product
|
|
{
|
|
private $id;
|
|
private $name;
|
|
private $attributes = array();
|
|
}
|
|
|
|
Where the ``attribute_name`` column contains the key and
|
|
``attribute_value`` contains the value of each array element in
|
|
``$attributes``.
|
|
|
|
The feature request for persistence of primitive value arrays
|
|
`is described in the DDC-298 ticket <http://www.doctrine-project.org/jira/browse/DDC-298>`_.
|
|
|
|
Value Objects
|
|
~~~~~~~~~~~~~
|
|
|
|
There is currently no native support value objects in Doctrine
|
|
other than for ``DateTime`` instances or if you serialize the
|
|
objects using ``serialize()/deserialize()`` which the DBAL Type
|
|
"object" supports.
|
|
|
|
The feature request for full value-object support
|
|
`is described in the DDC-93 ticket <http://www.doctrine-project.org/jira/browse/DDC-93>`_.
|
|
|
|
Applying Filter Rules to any Query
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
There are scenarios in many applications where you want to apply
|
|
additional filter rules to each query implicitly. Examples
|
|
include:
|
|
|
|
|
|
- In I18N Applications restrict results to a entities annotated
|
|
with a specific locale
|
|
- For a large collection always only return objects in a specific
|
|
date range/where condition applied.
|
|
- Soft-Delete
|
|
|
|
There is currently no way to achieve this consistently across both
|
|
DQL and Repository/Persister generated queries, but as this is a
|
|
pretty important feature we plan to add support for it in the
|
|
future.
|
|
|
|
Custom Persisters
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
A Persister in Doctrine is an object that is responsible for the
|
|
hydration and write operations of an entity against the database.
|
|
Currently there is no way to overwrite the persister implementation
|
|
for a given entity, however there are several use-cases that can
|
|
benefit from custom persister implementations:
|
|
|
|
|
|
- `Add Upsert Support <http://www.doctrine-project.org/jira/browse/DDC-668>`_
|
|
- `Evaluate possible ways in which stored-procedures can be used <http://www.doctrine-project.org/jira/browse/DDC-445>`_
|
|
- The previous Filter Rules Feature Request
|
|
|
|
Persist Keys of Collections
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
PHP Arrays are ordered hash-maps and so should be the
|
|
``Doctrine\Common\Collections\Collection`` interface. We plan to
|
|
evaluate a feature that optionally persists and hydrates the keys
|
|
of a Collection instance.
|
|
|
|
`Ticket DDC-213 <http://www.doctrine-project.org/jira/browse/DDC-213>`_
|
|
|
|
Mapping many tables to one entity
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
It is not possible to map several equally looking tables onto one
|
|
entity. For example if you have a production and an archive table
|
|
of a certain business concept then you cannot have both tables map
|
|
to the same entity.
|
|
|
|
Behaviors
|
|
~~~~~~~~~
|
|
|
|
Doctrine 2 *will never* include a behavior system like Doctrine 1
|
|
in the core library. We don't think behaviors add more value than
|
|
they cost pain and debugging hell. Please see the many different
|
|
blog posts we have written on this topics:
|
|
|
|
|
|
- `Doctrine2 "Behaviors" in a Nutshell <http://www.doctrine-project.org/blog/doctrine2-behaviours-nutshell>`_
|
|
- `A re-usable Versionable behavior for Doctrine2 <http://www.doctrine-project.org/blog/doctrine2-versionable>`_
|
|
- `Write your own ORM on top of Doctrine2 <http://www.doctrine-project.org/blog/your-own-orm-doctrine2>`_
|
|
|
|
Doctrine 2 has enough hooks and extension points so that *you* can
|
|
add whatever you want on top of it. None of this will ever become
|
|
core functionality of Doctrine2 however, you will have to rely on
|
|
third party extensions for magical behaviors.
|
|
|
|
Nested Set
|
|
~~~~~~~~~~
|
|
|
|
NestedSet was offered as a behavior in Doctrine 1 and will not be
|
|
included in the core of Doctrine 2. However there are already two
|
|
extensions out there that offer support for Nested Set with
|
|
Doctrine 2:
|
|
|
|
|
|
- `Doctrine2 Hierachical-Structural Behavior <http://github.com/guilhermeblanco/Doctrine2-Hierarchical-Structural-Behavior>`_
|
|
- `Doctrine2 NestedSet <http://github.com/blt04/doctrine2-nestedset>`_
|
|
|
|
Known Issues
|
|
------------
|
|
|
|
The Known Issues section describes critical/blocker bugs and other
|
|
issues that are either complicated to fix, not fixable due to
|
|
backwards compatibility issues or where no simple fix exists (yet).
|
|
We don't plan to add every bug in the tracker there, just those
|
|
issues that can potentially cause nightmares or pain of any sort.
|
|
|
|
Identifier Quoting and Legacy Databases
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
For compatibility reasons between all the supported vendors and
|
|
edge case problems Doctrine 2 does *NOT* do automatic identifier
|
|
quoting. This can lead to problems when trying to get
|
|
legacy-databases to work with Doctrine 2.
|
|
|
|
|
|
- You can quote column-names as described in the
|
|
`Basic-Mapping <basic-mapping>`_ section.
|
|
- You cannot quote join column names.
|
|
- You cannot use non [a-zA-Z0-9\_]+ characters, they will break
|
|
several SQL statements.
|
|
|
|
Having problems with these kind of column names? Many databases
|
|
support all CRUD operations on views that semantically map to
|
|
certain tables. You can create views for all your problematic
|
|
tables and column names to avoid the legacy quoting nightmare.
|
|
|
|
|