Code beautification and docblocks enhancements.

lib/Doctrine/ORM/Event/EntityEventDelegator.php

@@ -19,13 +19,15 @@
 
 namespace Doctrine\ORM\Event;
 
-use \Doctrine\Common\EventSubscriber;
+use Doctrine\Common\EventSubscriber;
-use \LogicException;
+use LogicException;
 
 /**
  * Delegate events only for certain entities they are registered for.
  *
+ * @link    www.doctrine-project.org
  * @author  Benjamin Eberlei <kontakt@beberlei.de>
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
  * @since   2.2
  */
 class EntityEventDelegator implements EventSubscriber
@@ -54,17 +56,23 @@ class EntityEventDelegator implements EventSubscriber
     public function addEventListener($events, $entities, $listener)
     {
         if ($this->frozen) {
-            throw new LogicException("Cannot add event listeners after EntityEventDelegator::getSubscribedEvents() " .
+            throw new LogicException(
-                "is called once. This happens when you register the delegator with the event manager.");
+                "Cannot add event listeners after EntityEventDelegator::getSubscribedEvents() " .
+                "is called once. This happens when you register the delegator with the event manager."
+            );
         }
 
         // Picks the hash code related to that listener
         $hash     = spl_object_hash($listener);
+        $entities = array_flip((array) $entities);
 
         foreach ((array) $events as $event) {
             // Overrides listener if a previous one was associated already
             // Prevents duplicate listeners on same event (same instance only)
-            $this->listeners[$event][$hash] = array('listener' => $listener, 'entities' => array_flip((array)$entities));
+            $this->listeners[$event][$hash] = array(
+                'listener' => $listener, 
+                'entities' => $entities
+            );
         }
     }
 
@@ -73,6 +81,7 @@ class EntityEventDelegator implements EventSubscriber
      * interested in and added as a listener for these events.
      *
      * @param Doctrine\Common\EventSubscriber $subscriber The subscriber.
+     * @param array $entities
      */
     public function addEventSubscriber(EventSubscriber $subscriber, $entities)
     {
@@ -87,24 +96,27 @@ class EntityEventDelegator implements EventSubscriber
     public function getSubscribedEvents()
     {
         $this->frozen = true;
+        
         return array_keys($this->listeners);
     }
 
     /**
      * Delegate the event to an appropriate listener
      *
-     * @param $eventName
+     * @param string $eventName
-     * @param $event
+     * @param array $args
      * @return void
      */
     public function __call($eventName, $args)
     {
         $event = $args[0];
+        
         foreach ($this->listeners[$eventName] AS $listenerData) {
             $class = get_class($event->getEntity());
-            if (isset($listenerData['entities'][$class])) {
+            
+            if ( ! isset($listenerData['entities'][$class])) continue;
+            
             $listenerData['listener']->$eventName($event);
         }
     }
-    }
 }

lib/Doctrine/ORM/Event/LifecycleEventArgs.php

@@ -19,42 +19,59 @@
 
 namespace Doctrine\ORM\Event;
 
+use Doctrine\Common\EventArgs;
+use Doctrine\ORM\EntityManager;
+
 /**
  * Lifecycle Events are triggered by the UnitOfWork during lifecycle transitions
  * of entities.
  *
+ * @link   www.doctrine-project.org
  * @since  2.0
  * @author Roman Borschel <roman@code-factory.de>
  * @author Benjamin Eberlei <kontakt@beberlei.de>
  */
-class LifecycleEventArgs extends \Doctrine\Common\EventArgs
+class LifecycleEventArgs extends EventArgs
 {
     /**
-     * @var EntityManager
+     * @var Doctrine\ORM\EntityManager
      */
-    private $_em;
+    private $em;
 
     /**
      * @var object
      */
-    private $_entity;
+    private $entity;
     
-    public function __construct($entity, $em)
+    /**
+     * Constructor
+     * 
+     * @param object $entity
+     * @param Doctrine\ORM\EntityManager $em 
+     */
+    public function __construct($entity, EntityManager $em)
     {
-        $this->_entity = $entity;
+        $this->entity = $entity;
-        $this->_em = $em;
+        $this->em     = $em;
-    }
-    
-    public function getEntity()
-    {
-        return $this->_entity;
     }
     
     /**
-     * @return EntityManager
+     * Retireve associated Entity.
+     * 
+     * @return object 
+     */
+    public function getEntity()
+    {
+        return $this->entity;
+    }
+
+    /**
+     * Retrieve associated EntityManager.
+     * 
+     * @return Doctrine\ORM\EntityManager
      */
     public function getEntityManager()
     {
-        return $this->_em;
+        return $this->em;
     }
 }

lib/Doctrine/ORM/Event/LoadClassMetadataEventArgs.php

@@ -1,9 +1,25 @@
 <?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the LGPL. For more information, see
+ * <http://www.doctrine-project.org>.
+ */
 
 namespace Doctrine\ORM\Event;
 
 use Doctrine\Common\EventArgs;
-
 use Doctrine\ORM\Mapping\ClassMetadataInfo;
 use Doctrine\ORM\EntityManager;
 
@@ -16,18 +32,20 @@ use Doctrine\ORM\EntityManager;
 class LoadClassMetadataEventArgs extends EventArgs
 {
     /**
-     * @var ClassMetadata
+     * @var Doctrine\ORM\Mapping\ClassMetadata
      */
     private $classMetadata;
 
     /**
-     * @var EntityManager
+     * @var Doctrine\ORM\EntityManager
      */
     private $em;
 
     /**
-     * @param ClassMetadataInfo $classMetadata
+     * Constructor.
-     * @param EntityManager $em
+     * 
+     * @param Doctrine\ORM\Mapping\ClassMetadataInfo $classMetadata
+     * @param Doctrine\ORM\EntityManager $em
      */
     public function __construct(ClassMetadataInfo $classMetadata, EntityManager $em)
     {
@@ -36,7 +54,9 @@ class LoadClassMetadataEventArgs extends EventArgs
     }
 
     /**
-     * @return ClassMetadataInfo
+     * Retrieve associated ClassMetadata.
+     *  
+     * @return Doctrine\ORM\Mapping\ClassMetadataInfo
      */
     public function getClassMetadata()
     {
@@ -44,7 +64,9 @@ class LoadClassMetadataEventArgs extends EventArgs
     }
 
     /**
-     * @return EntityManager
+     * Retrieve associated EntityManager.
+     * 
+     * @return Doctrine\ORM\EntityManager
      */
     public function getEntityManager()
     {

lib/Doctrine/ORM/Event/OnClearEventArgs.php

@@ -15,7 +15,7 @@
  * This software consists of voluntary contributions made by many individuals
  * and is licensed under the LGPL. For more information, see
  * <http://www.doctrine-project.org>.
-*/
+ */
 
 namespace Doctrine\ORM\Event;
 
@@ -23,16 +23,15 @@ namespace Doctrine\ORM\Event;
  * Provides event arguments for the onClear event.
  *
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
- * @link        www.doctrine-project.com
+ * @link        www.doctrine-project.org
  * @since       2.0
- * @version     $Revision$
  * @author      Roman Borschel <roman@code-factory.de>
  * @author      Benjamin Eberlei <kontakt@beberlei.de>
  */
 class OnClearEventArgs extends \Doctrine\Common\EventArgs
 {
     /**
-     * @var \Doctrine\ORM\EntityManager
+     * @var Doctrine\ORM\EntityManager
      */
     private $em;
 
@@ -42,7 +41,10 @@ class OnClearEventArgs extends \Doctrine\Common\EventArgs
     private $entityClass;
 
     /**
-     * @param \Doctrine\ORM\EntityManager $em
+     * Constructor.
+     * 
+     * @param Doctrine\ORM\EntityManager $em
+     * @param string $entityClass Optional entity class
      */
     public function __construct($em, $entityClass = null)
     {
@@ -51,7 +53,9 @@ class OnClearEventArgs extends \Doctrine\Common\EventArgs
     }
 
     /**
-     * @return \Doctrine\ORM\EntityManager
+     * Retrieve associated EntityManager.
+     * 
+     * @return Doctrine\ORM\EntityManager
      */
     public function getEntityManager()
     {
@@ -75,6 +79,6 @@ class OnClearEventArgs extends \Doctrine\Common\EventArgs
      */
     public function clearsAllEntities()
     {
-        return $this->entityClass === null;
+        return ($this->entityClass === null);
     }
 }

lib/Doctrine/ORM/Event/OnFlushEventArgs.php

@@ -21,37 +21,45 @@
 
 namespace Doctrine\ORM\Event;
 
+use Doctrine\ORM\EntityManager;
+
 /**
  * Provides event arguments for the preFlush event.
  *
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
- * @link        www.doctrine-project.com
+ * @link        www.doctrine-project.org
  * @since       2.0
- * @version     $Revision$
  * @author      Roman Borschel <roman@code-factory.de>
  * @author      Benjamin Eberlei <kontakt@beberlei.de>
  */
 class OnFlushEventArgs extends \Doctrine\Common\EventArgs
 {
     /**
-     * @var EntityManager
+     * @var Doctirne\ORM\EntityManager
      */
-    private $_em;
+    private $em;
     
-    //private $_entitiesToPersist = array();
+    //private $entitiesToPersist = array();
-    //private $_entitiesToRemove = array();
+    //private $entitiesToRemove = array();
     
-    public function __construct($em)
+    /**
+     * Constructor.
+     * 
+     * @param Doctrine\ORM\EntityManager $em 
+     */
+    public function __construct(EntityManager $em)
     {
-        $this->_em = $em;
+        $this->em = $em;
     }
 
     /**
-     * @return EntityManager
+     * Retrieve associated EntityManager.
+     * 
+     * @return Doctrine\ORM\EntityManager
      */
     public function getEntityManager()
     {
-        return $this->_em;
+        return $this->em;
     }
     
     /*

lib/Doctrine/ORM/Event/PostFlushEventArgs.php

@@ -17,9 +17,10 @@
  * This software consists of voluntary contributions made by many individuals
  * and is licensed under the LGPL. For more information, see
  * <http://www.doctrine-project.org>.
-*/
+ */
 
 namespace Doctrine\ORM\Event;
+
 use Doctrine\ORM\EntityManager;
 use Doctrine\Common\EventArgs;
 
@@ -27,20 +28,21 @@ use Doctrine\Common\EventArgs;
  * Provides event arguments for the postFlush event.
  *
  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
- * @link        www.doctrine-project.com
+ * @link        www.doctrine-project.org
  * @since       2.0
- * @version     $Revision$
  * @author      Daniel Freudenberger <df@rebuy.de>
  */
 class PostFlushEventArgs extends EventArgs
 {
     /**
-     * @var EntityManager
+     * @var Doctrine\ORM\EntityManager
      */
     private $em;
 
     /**
-     * @param EntityManager $em
+     * Constructor.
+     * 
+     * @param Doctrine\ORM\EntityManager $em
      */
     public function __construct(EntityManager $em)
     {
@@ -48,7 +50,9 @@ class PostFlushEventArgs extends EventArgs
     }
 
     /**
-     * @return EntityManager
+     * Retrieve associated EntityManager.
+     * 
+     * @return Doctrine\ORM\EntityManager
      */
     public function getEntityManager()
     {

lib/Doctrine/ORM/Event/PreUpdateEventArgs.php

@@ -1,4 +1,23 @@
 <?php
+/*
+ *  $Id$
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the LGPL. For more information, see
+ * <http://www.doctrine-project.org>.
+ */
 
 namespace Doctrine\ORM\Event;
 
@@ -8,6 +27,7 @@ use Doctrine\Common\EventArgs,
 /**
  * Class that holds event arguments for a preInsert/preUpdate event.
  *
+ * @author Guilherme Blanco <guilehrmeblanco@hotmail.com>
  * @author Roman Borschel <roman@code-factory.org>
  * @author Benjamin Eberlei <kontakt@beberlei.de>
  * @since  2.0
@@ -17,33 +37,40 @@ class PreUpdateEventArgs extends LifecycleEventArgs
     /**
      * @var array
      */
-    private $_entityChangeSet;
+    private $entityChangeSet;
 
     /**
+     * Constructor.
      * 
      * @param object $entity
-     * @param EntityManager $em
+     * @param Doctrine\ORM\EntityManager $em
      * @param array $changeSet
      */
-    public function __construct($entity, $em, array &$changeSet)
+    public function __construct($entity, EntityManager $em, array &$changeSet)
     {
         parent::__construct($entity, $em);
-        $this->_entityChangeSet = &$changeSet;
-    }
         
-    public function getEntityChangeSet()
+        $this->entityChangeSet = &$changeSet;
-    {
-        return $this->_entityChangeSet;
     }
 
     /**
-     * Field has a changeset?
+     * Retrieve entity changeset.
      * 
-     * @return bool
+     * @return array
+     */
+    public function getEntityChangeSet()
+    {
+        return $this->entityChangeSet;
+    }
+
+    /**
+     * Check if field has a changeset.
+     *
+     * @return boolean
      */
     public function hasChangedField($field)
     {
-        return isset($this->_entityChangeSet[$field]);
+        return isset($this->entityChangeSet[$field]);
     }
 
     /**
@@ -54,9 +81,9 @@ class PreUpdateEventArgs extends LifecycleEventArgs
      */
     public function getOldValue($field)
     {
-    	$this->_assertValidField($field);
+    	$this->assertValidField($field);
 
-        return $this->_entityChangeSet[$field][0];
+        return $this->entityChangeSet[$field][0];
     }
 
     /**
@@ -67,9 +94,9 @@ class PreUpdateEventArgs extends LifecycleEventArgs
      */
     public function getNewValue($field)
     {
-        $this->_assertValidField($field);
+        $this->assertValidField($field);
 
-        return $this->_entityChangeSet[$field][1];
+        return $this->entityChangeSet[$field][1];
     }
 
     /**
@@ -80,18 +107,24 @@ class PreUpdateEventArgs extends LifecycleEventArgs
      */
     public function setNewValue($field, $value)
     {
-        $this->_assertValidField($field);
+        $this->assertValidField($field);
 
-        $this->_entityChangeSet[$field][1] = $value;
+        $this->entityChangeSet[$field][1] = $value;
     }
 
-    private function _assertValidField($field)
+    /**
+     * Assert the field exists in changeset.
+     * 
+     * @param string $field 
+     */
+    private function assertValidField($field)
     {
-    	if (!isset($this->_entityChangeSet[$field])) {
+    	if ( ! isset($this->entityChangeSet[$field])) {
-            throw new \InvalidArgumentException(
+            throw new \InvalidArgumentException(sprintf(
-                "Field '".$field."' is not a valid field of the entity ".
+                'Field "%s" is not a valid field of the entity "%s" in PreUpdateEventArgs.',
-                "'".get_class($this->getEntity())."' in PreUpdateEventArgs."
+                $field,
-            );
+                get_class($this->getEntity())
+            ));
         }
     }
 }