Frequently Asked Questions

How do I set the charset and collation for MySQL tables?

You can't set these values with attributes, annotations or inside yml or xml mapping files. To make a database work with the default charset and collation you should configure MySQL to use it as default charset, or create the database with charset and collation details. This way they get inherited to all newly created database tables and columns.

How can I add default values to a column?

Doctrine does not support to set the default values in columns through the "DEFAULT" keyword in SQL. This is not necessary however, you can just use your class properties as default values. These are then used upon insert:

1
class User
{
    private const STATUS_DISABLED = 0;
    private const STATUS_ENABLED = 1;

    private string $algorithm = "sha1";
    /** @var self::STATUS_* */
    private int $status = self::STATUS_DISABLED;
}
2
3
4
5
6
7
8
9

.

Why do I get exceptions about unique constraint failures during $em->flush()?

Doctrine does not check if you are re-adding entities with a primary key that already exists or adding entities to a collection twice. You have to check for both conditions yourself in the code before calling $em->flush() if you know that unique constraint failures can occur.

In Symfony2 for example there is a Unique Entity Validator to achieve this task.

For collections you can check with $collection->contains($entity) if an entity is already part of this collection. For a FETCH=LAZY collection this will initialize the collection, however for FETCH=EXTRA_LAZY this method will use SQL to determine if this entity is already part of the collection.

What is wrong when I get an InvalidArgumentException "A new entity was found through the relationship.."?

This exception is thrown during EntityManager#flush() when there exists an object in the identity map that contains a reference to an object that Doctrine does not know about. Say for example you grab a "User"-entity from the database with a specific id and set a completely new object into one of the associations of the User object. If you then call EntityManager#flush() without letting Doctrine know about this new object using EntityManager#persist($newObject) you will see this exception.

You can solve this exception by:

• Calling EntityManager#persist($newObject) on the new object
• Using cascade=persist on the association that contains the new object

How can I filter an association?

You should use DQL queries to query for the filtered set of entities.

I call clear() on a One-To-Many collection but the entities are not deleted

This is an expected behavior that has to do with the inverse/owning side handling of Doctrine. By definition a One-To-Many association is on the inverse side, that means changes to it will not be recognized by Doctrine.

If you want to perform the equivalent of the clear operation you have to iterate the collection and set the owning side many-to-one reference to NULL as well to detach all entities from the collection. This will trigger the appropriate UPDATE statements on the database.

How can I add columns to a many-to-many table?

The many-to-many association is only supporting foreign keys in the table definition To work with many-to-many tables containing extra columns you have to use the foreign keys as primary keys feature of Doctrine ORM.

See the tutorial on composite primary keys for more information.

How can i paginate fetch-joined collections?

If you are issuing a DQL statement that fetches a collection as well you cannot easily iterate over this collection using a LIMIT statement (or vendor equivalent).

Doctrine does not offer a solution for this out of the box but there are several extensions that do:

• DoctrineExtensions
• Pagerfanta

Why does pagination not work correctly with fetch joins?

Pagination in Doctrine uses a LIMIT clause (or vendor equivalent) to restrict the results. However when fetch-joining this is not returning the correct number of results since joining with a one-to-many or many-to-many association multiplies the number of rows by the number of associated entities.

See the previous question for a solution to this task.

Can I use Inheritance with Doctrine ORM?

Yes, you can use Single- or Joined-Table Inheritance in ORM.

See the documentation chapter on inheritance mapping for the details.

Why does Doctrine not create proxy objects for my inheritance hierarchy?

If you set a many-to-one or one-to-one association target-entity to any parent class of an inheritance hierarchy Doctrine does not know what PHP class the foreign is actually of. To find this out it has to execute a SQL query to look this information up in the database.

Why does the EntityGenerator not do X?

The EntityGenerator is not a full fledged code-generator that solves all tasks. Code-Generation is not a first-class priority in Doctrine 2 anymore (compared to Doctrine 1). The EntityGenerator is supposed to kick-start you, but not towards 100%.

Why does the EntityGenerator not generate inheritance correctly?

Just from the details of the discriminator map the EntityGenerator cannot guess the inheritance hierarchy. This is why the generation of inherited entities does not fully work. You have to adjust some additional code to get this one working correctly.

Why is an extra SQL query executed every time I fetch an entity with a one-to-one relation?

If Doctrine detects that you are fetching an inverse side one-to-one association it has to execute an additional query to load this object, because it cannot know if there is no such object (setting null) or if it should set a proxy and which id this proxy has.

To solve this problem currently a query has to be executed to find out this information.

What is DQL?

DQL stands for Doctrine Query Language, a query language that very much looks like SQL but has some important benefits when using Doctrine:

• It uses class names and fields instead of tables and columns, separating concerns between backend and your object model.
• It utilizes the metadata defined to offer a range of shortcuts when writing. For example you do not have to specify the ON clause of joins, since Doctrine already knows about them.
• It adds some functionality that is related to object management and transforms them into SQL.

It also has some drawbacks of course:

• The syntax is slightly different to SQL so you have to learn and remember the differences.
• To be vendor independent it can only implement a subset of all the existing SQL dialects. Vendor specific functionality and optimizations cannot be used through DQL unless implemented by you explicitly.
• For some DQL constructs subselects are used which are known to be slow in MySQL.

Can I sort by a function (for example ORDER BY RAND()) in DQL?

No, it is not supported to sort by function in DQL. If you need this functionality you should either use a native-query or come up with another solution. As a side note: Sorting with ORDER BY RAND() is painfully slow starting with 1000 rows.

Is it better to write DQL or to generate it with the query builder?

The purpose of the QueryBuilder is to generate DQL dynamically, which is useful when you have optional filters, conditional joins, etc.

But the QueryBuilder is not an alternative to DQL, it actually generates DQL queries at runtime, which are then interpreted by Doctrine. This means that using the QueryBuilder to build and run a query is actually always slower than only running the corresponding DQL query.

So if you only need to generate a query and bind parameters to it, you should use plain DQL, as this is a simpler and much more readable solution. You should only use the QueryBuilder when you can't achieve what you want to do with a DQL query.