3. Frequently Asked Questions¶
Note
This FAQ is a work in progress. We will add lots of questions and not answer them right away just to remember what is often asked. If you stumble across an unanswered question please write a mail to the mailing-list or join the #doctrine channel on Freenode IRC.
3.1. Database Schema¶
3.1.1. 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.
3.2. Entity Classes¶
3.2.1. 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:
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;
}
.
3.3. Mapping¶
3.3.1. 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.
3.4. Associations¶
3.4.1. 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新しいオブジェクトで EntityManager#persist($newObject) を呼び出すUsing cascade=persist on the association that contains the new object
新しいオブジェクトを含む関連付けで cascade=persist を使用する
3.4.2. How can I filter an association?¶
You should use DQL queries to query for the filtered set of entities.
3.4.3. 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.
3.4.4. 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.
3.4.5. 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:
- 教義拡張
- ページャーファンタ
3.4.6. 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.
3.5. Inheritance¶
3.5.1. 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.
3.5.2. 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.
3.6. EntityGenerator¶
3.6.1. 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%.
3.6.2. 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.
3.7. Performance¶
3.7.1. 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.
3.8. Doctrine Query Language¶
3.8.1. 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.
定義されたメタデータを利用して、書き込み時にさまざまなショートカットを提供します。たとえば、結合の ON 句を指定する必要はありません。Doctrine は結合について既に知っているからです。It adds some functionality that is related to object management and transforms them into SQL.
オブジェクト管理に関連するいくつかの機能を追加し、それらを SQL に変換します。
It also has some drawbacks of course:
The syntax is slightly different to SQL so you have to learn and remember the differences.
構文は SQL とは少し異なるため、違いを学び、覚えておく必要があります。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.
ベンダーに依存しないようにするために、既存のすべての SQL ダイアレクトのサブセットのみを実装できます。明示的に実装しない限り、ベンダー固有の機能と最適化を DQL で使用することはできません。For some DQL constructs subselects are used which are known to be slow in MySQL.
一部の DQL コンストラクトでは、MySQL で遅いことが知られているサブセレクトが使用されます。
3.8.2. 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.
3.8.3. 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.
3.9. A Query fails, how can I debug it?¶
First, if you are using the QueryBuilder you can use
$queryBuilder->getDQL() to get the DQL string of this query. The
corresponding SQL you can get from the Query instance by calling
$query->getSQL().
<?php
$dql = "SELECT u FROM User u";
$query = $entityManager->createQuery($dql);
var_dump($query->getSQL());
$qb = $entityManager->createQueryBuilder();
$qb->select('u')->from('User', 'u');
var_dump($qb->getDQL());
