Merge branch 'master' of github.com:doctrine/orm-documentation

en/cookbook/mysql-enums.rst

@@ -34,7 +34,7 @@ will even detect this match correctly when using SchemaTool update commands.
 
     <?php
     $conn = $em->getConnection();
-    $conn->getDatabasePlatform()->registerDoctrineTypeMapping('enum', 'varchar');
+    $conn->getDatabasePlatform()->registerDoctrineTypeMapping('enum', 'string');
 
 In this case you have to ensure that each varchar field that is an enum in the
 database only gets passed the allowed values. You can easily enforce this in your

en/reference/annotations-reference.rst

@@ -401,7 +401,6 @@ Optional attributes:
 -  **nullable**: Determine if the related entity is required, or if
    null is an allowed state for the relation. Defaults to true.
 -  **onDelete**: Cascade Action (Database-level)
--  **onUpdate**: Cascade Action (Database-level)
 -  **columnDefinition**: DDL SQL snippet that starts after the column
    name and specifies the complete (non-portable!) column definition.
    This attribute allows to make use of advanced RMDBS features. Using

en/reference/events.rst

@@ -570,7 +570,9 @@ postUpdate, postRemove, postPersist
 
 The three post events are called inside ``EntityManager#flush()``.
 Changes in here are not relevant to the persistence in the
-database, but you can use this events to
+database, but you can use these events to alter non-persistable items,
+like non-mapped fields, logging or even associated classes that are
+directly mapped by Doctrine.
 
 postLoad
 ~~~~~~~~

en/reference/query-builder.rst

@@ -240,10 +240,10 @@ To simplify some of these efforts, we introduce what we call as
 The Expr class
 ^^^^^^^^^^^^^^
 
-To workaround most of the issues that ``add()`` method may cause,
+To workaround some of the issues that ``add()`` method may cause,
 Doctrine created a class that can be considered as a helper for
-building queries. This class is called ``Expr``, which provides a
-set of useful static methods to help building queries:
+building expressions. This class is called ``Expr``, which provides a
+set of useful methods to help build expressions:
 
 .. code-block:: php
 
@@ -251,13 +251,13 @@ set of useful static methods to help building queries:
     // $qb instanceof QueryBuilder
     
     // example8: QueryBuilder port of: "SELECT u FROM User u WHERE u.id = ? OR u.nickname LIKE ? ORDER BY u.surname DESC" using Expr class
-    $qb->add('select', $qb->expr()->select('u'))
-       ->add('from', $qb->expr()->from('User', 'u'))
-       ->add('where', $qb->expr()->orx(
+    $qb->add('select', new Expr\Select(array('u')))
+       ->add('from', new Expr\From('User', 'u'))
+       ->add('where', $qb->expr()->orX(
            $qb->expr()->eq('u.id', '?1'),
            $qb->expr()->like('u.nickname', '?2')
        ))
-       ->add('orderBy', $qb->expr()->orderBy('u.surname', 'ASC'));
+       ->add('orderBy', new Expr\OrderBy('u.name', 'ASC'));
 
 Although it still sounds complex, the ability to programmatically
 create conditions are the main feature of ``Expr``. Here it is a
@@ -270,11 +270,11 @@ complete list of supported helper methods available:
     {
         /** Conditional objects **/        
     
-        // Example - $qb->expr()->andx($cond1 [, $condN])->add(...)->...
-        public function andx($x = null); // Returns Expr\Andx instance
+        // Example - $qb->expr()->andX($cond1 [, $condN])->add(...)->...
+        public function andX($x = null); // Returns Expr\AndX instance
     
-        // Example - $qb->expr()->orx($cond1 [, $condN])->add(...)->...
-        public function orx($x = null); // Returns Expr\Orx instance
+        // Example - $qb->expr()->orX($cond1 [, $condN])->add(...)->...
+        public function orX($x = null); // Returns Expr\OrX instance
     
     
         /** Comparison objects **/
@@ -296,6 +296,12 @@ complete list of supported helper methods available:
     
         // Example - $qb->expr()->gte('u.id', '?1') => u.id >= ?1
         public function gte($x, $y); // Returns Expr\Comparison instance
+
+        // Example - $qb->expr()->isNull('u.id') => u.id IS NULL
+        public function isNull($x); // Returns string
+
+        // Example - $qb->expr()->isNotNull('u.id') => u.id IS NOT NULL
+        public function isNotNull($x); // Returns string
     
     
         /** Arithmetic objects **/
@@ -425,7 +431,7 @@ suggested standard way to build queries:
     // example8: QueryBuilder port of: "SELECT u FROM User u WHERE u.id = ?1 OR u.nickname LIKE ?2 ORDER BY u.surname DESC" using QueryBuilder helper methods
     $qb->select(array('u')) // string 'u' is converted to array internally
        ->from('User', 'u')
-       ->where($qb->expr()->orx(
+       ->where($qb->expr()->orX(
            $qb->expr()->eq('u.id', '?1'),
            $qb->expr()->like('u.nickname', '?2')
        ))
@@ -469,11 +475,11 @@ Here is a complete list of helper methods available in
         // NOTE: ->where() overrides all previously set conditions
         //
         // Example - $qb->where('u.firstName = ?1', $qb->expr()->eq('u.surname', '?2'))
-        // Example - $qb->where($qb->expr()->andx($qb->expr()->eq('u.firstName', '?1'), $qb->expr()->eq('u.surname', '?2')))
+        // Example - $qb->where($qb->expr()->andX($qb->expr()->eq('u.firstName', '?1'), $qb->expr()->eq('u.surname', '?2')))
         // Example - $qb->where('u.firstName = ?1 AND u.surname = ?2')    
         public function where($where);
     
-        // Example - $qb->andWhere($qb->expr()->orx($qb->expr()->lte('u.age', 40), 'u.numChild = 0'))    
+        // Example - $qb->andWhere($qb->expr()->orX($qb->expr()->lte('u.age', 40), 'u.numChild = 0'))
         public function andWhere($where);
     
         // Example - $qb->orWhere($qb->expr()->between('u.id', 1, 10));

en/reference/working-with-associations.rst

@@ -246,8 +246,8 @@ the database permanently.
 
 Notice how both sides of the bidirectional association are always
 updated. Unidirectional associations are consequently simpler to
-handle. Also note that if you type-hint your methods, i.e.
-``setAddress(Address $address)``, then PHP does only allows null
+handle. Also note that if you use type-hinting in your methods, i.e.
+``setAddress(Address $address)``, PHP will only allow null
 values if ``null`` is set as default value. Otherwise
 setAddress(null) will fail for removing the association. If you
 insist on type-hinting a typical way to deal with this is to
@@ -279,8 +279,9 @@ entities that have been re-added to the collection.
 
 Say you clear a collection of tags by calling
 ``$post->getTags()->clear();`` and then call
-``$post->getTags()->add($tag)``. This will not recognize tag being
-already added before and issue two database calls.
+``$post->getTags()->add($tag)``. This will not recognize the tag having 
+already been added previously and will consequently issue two separate database 
+calls.
 
 Association Management Methods
 ------------------------------
@@ -380,9 +381,9 @@ as your preferences.
 Synchronizing Bidirectional Collections
 ---------------------------------------
 
-In the case of Many-To-Many associations you as the developer are
-responsible to keep the collections on the owning and inverse side
-up in sync, when you apply changes to them. Doctrine can only
+In the case of Many-To-Many associations you as the developer have the 
+responsibility of keeping the collections on the owning and inverse side
+ in sync when you apply changes to them. Doctrine can only
 guarantee a consistent state for the hydration, not for your client
 code.
 
@@ -468,7 +469,7 @@ code would fail if you removed the call to
 cascade the persist operation to all nested entities that are new
 as well.
 
-More complicated is the deletion of all a users comments when he is
+More complicated is the deletion of all of a user's comments when he is
 removed from the system:
 
 .. code-block:: php
@@ -590,7 +591,7 @@ and StandingData:
         }
     }
 
-Now two examples what happens when you remove the references:
+Now two examples of what happens when you remove the references:
 
 .. code-block:: php
 
@@ -602,7 +603,8 @@ Now two examples what happens when you remove the references:
 
     $em->flush();
 
-In this case you have only changed the ``Contact`` entity but you removed
-the references for standing data and one address reference. When flush is called
-not only are the references removed but both the old standing data and the one
-address entity are also deleted from the database.
+In this case you have not only changed the ``Contact`` entity itself but 
+you have also removed the references for standing data and as well as one 
+address reference. When flush is called not only are the references removed 
+but both the old standing data and the one address entity are also deleted 
+from the database.

en/tutorials/getting-started-xml-edition.rst

@@ -126,8 +126,8 @@ or collections of all the relations that haven't been explicitly
 retrieved from the database yet.
 
 To be able to use lazyload with collections, simple PHP arrays have
-to be replaced by a generic collection interface Doctrine which
-tries to act as array as much as possible using ArrayAccess,
+to be replaced by a generic collection interface for Doctrine which
+tries to act as as much like an array as possible by using ArrayAccess,
 IteratorAggregate and Countable interfaces. The class is the most
 simple implementation of this interface.