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

We try to make using Doctrine2 a very pleasant experience. Therefore it is our believe
that being honest about the limitations to our users as early as possible is very important.
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 currently 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 Perister 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

+++ Order 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)

++ 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. *Luckily this section is empty right now!*