doctrine2/manual/en/limitations-and-known-issues.txt

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:

    [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`.

    [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):

    [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:

    [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:

    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.