Reusing chained driver now available in common, fixing cs/code smells and removing duplicate docs.

lib/Doctrine/ORM/Mapping/ClassMetadata.php

@@ -20,22 +20,9 @@
 namespace Doctrine\ORM\Mapping;
 
 /**
- * A <tt>ClassMetadata</tt> instance holds all the object-relational mapping metadata
+ * {@inheritDoc}
- * of an entity and it's associations.
  *
- * Once populated, ClassMetadata instances are usually cached in a serialized form.
+ * @todo remove or rename ClassMetadataInfo to ClassMetadata
- *
- * <b>IMPORTANT NOTE:</b>
- *
- * The fields of this class are only public for 2 reasons:
- * 1) To allow fast READ access.
- * 2) To drastically reduce the size of a serialized instance (private/protected members
- *    get the whole class name, namespace inclusive, prepended to every property in
- *    the serialized representation).
- *
- * @author Roman Borschel <roman@code-factory.org>
- * @author Jonathan H. Wage <jonwage@gmail.com>
- * @since 2.0
  */
 class ClassMetadata extends ClassMetadataInfo
 {

lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php

@@ -926,9 +926,7 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * Gets the ReflectionClass instance of the mapped class.
+     * {@inheritDoc}
-     *
-     * @return ReflectionClass
      */
     public function getReflectionClass()
     {
@@ -1547,9 +1545,7 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * Gets the identifier (primary key) field names of the class.
+     * {@inheritDoc}
-     *
-     * @return mixed
      */
     public function getIdentifierFieldNames()
     {
@@ -1607,10 +1603,7 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * Checks whether the class has a (mapped) field with a certain name.
+     * {@inheritDoc}
-     *
-     * @param string $fieldName
-     * @return bool
      */
     public function hasField($fieldName)
     {
@@ -2080,7 +2073,7 @@ class ClassMetadataInfo implements ClassMetadata
      * Adds a field mapping without completing/validating it.
      * This is mainly used to add inherited field mappings to derived classes.
      *
-     * @internal param array $fieldMapping
+     * @param array $fieldMapping
      * @return void
      */
     public function addInheritedFieldMapping(array $fieldMapping)
@@ -2292,7 +2285,8 @@ class ClassMetadataInfo implements ClassMetadata
     /**
      * Registers a custom repository class for the entity class.
      *
-     * @param string $mapperClassName  The class name of the custom mapper.
+     * @param string $repositoryClassName The class name of the custom mapper.
+     * @return void
      */
     public function setCustomRepositoryClass($repositoryClassName)
     {
@@ -2474,10 +2468,7 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * Checks whether the class has a mapped association with the given field name.
+     * {@inheritDoc}
-     *
-     * @param string $fieldName
-     * @return boolean
      */
     public function hasAssociation($fieldName)
     {
@@ -2485,11 +2476,7 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * Checks whether the class has a mapped association for the specified field
+     * {@inheritDoc}
-     * and if yes, checks whether it is a single-valued association (to-one).
-     *
-     * @param string $fieldName
-     * @return boolean TRUE if the association exists and is single-valued, FALSE otherwise.
      */
     public function isSingleValuedAssociation($fieldName)
     {
@@ -2498,11 +2485,7 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * Checks whether the class has a mapped association for the specified field
+     * {@inheritDoc}
-     * and if yes, checks whether it is a collection-valued association (to-many).
-     *
-     * @param string $fieldName
-     * @return boolean TRUE if the association exists and is collection-valued, FALSE otherwise.
      */
     public function isCollectionValuedAssociation($fieldName)
     {
@@ -2681,11 +2664,7 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * A numerically indexed list of field names of this persistent class.
+     * {@inheritDoc}
-     *
-     * This array includes identifier fields if present on this class.
-     *
-     * @return array
      */
     public function getFieldNames()
     {
@@ -2693,11 +2672,7 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * A numerically indexed list of association names of this persistent class.
+     * {@inheritDoc}
-     *
-     * This array includes identifier associations if present on this class.
-     *
-     * @return array
      */
     public function getAssociationNames()
     {
@@ -2705,11 +2680,8 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * Returns the target class name of the given association.
+     * {@inheritDoc}
-     *
-     * @param string $assocName
      * @throws InvalidArgumentException
-     * @return string
      */
     public function getAssociationTargetClass($assocName)
     {
@@ -2721,9 +2693,7 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * Get fully-qualified class name of this persistent class.
+     * {@inheritDoc}
-     *
-     * @return string
      */
     public function getName()
     {
@@ -2812,8 +2782,7 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * @param string $fieldName
+     * {@inheritDoc}
-     * @return bool
      */
     public function isAssociationInverseSide($fieldName)
     {
@@ -2821,8 +2790,7 @@ class ClassMetadataInfo implements ClassMetadata
     }
 
     /**
-     * @param string $fieldName
+     * {@inheritDoc}
-     * @return string
      */
     public function getAssociationMappedByTargetField($fieldName)
     {

lib/Doctrine/ORM/Mapping/Driver/AnnotationDriver.php

@@ -38,7 +38,7 @@ use Doctrine\Common\Annotations\AnnotationReader,
 class AnnotationDriver extends AbstractAnnotationDriver
 {
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     protected $entityAnnotationClasses = array(
         'Doctrine\ORM\Mapping\Entity' => 1,
@@ -46,10 +46,11 @@ class AnnotationDriver extends AbstractAnnotationDriver
     );
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadMetadataForClass($className, ClassMetadata $metadata)
     {
+        /* @var $metadata \Doctrine\ORM\Mapping\ClassMetadataInfo */
         $class = $metadata->getReflectionClass();
         if ( ! $class) {
             // this happens when running annotation driver in combination with
@@ -264,6 +265,7 @@ class AnnotationDriver extends AbstractAnnotationDriver
         }
 
         // Evaluate annotations on properties/fields
+        /* @var $property \ReflectionProperty */
         foreach ($class->getProperties() as $property) {
             if ($metadata->isMappedSuperclass && ! $property->isPrivate()
                 ||
@@ -437,7 +439,6 @@ class AnnotationDriver extends AbstractAnnotationDriver
             }
         }
 
-         $attributeOverrides = array();
         // Evaluate AttributeOverrides annotation
         if (isset($classAnnotations['Doctrine\ORM\Mapping\AttributeOverrides'])) {
             $attributeOverridesAnnot = $classAnnotations['Doctrine\ORM\Mapping\AttributeOverrides'];
@@ -449,6 +450,7 @@ class AnnotationDriver extends AbstractAnnotationDriver
 
         // Evaluate @HasLifecycleCallbacks annotation
         if (isset($classAnnotations['Doctrine\ORM\Mapping\HasLifecycleCallbacks'])) {
+            /* @var $method \ReflectionMethod */
             foreach ($class->getMethods() as $method) {
                 // filter for the declaring class only, callbacks from parents will already be registered.
                 if ($method->isPublic() && $method->getDeclaringClass()->getName() == $class->name) {
@@ -576,8 +578,8 @@ class AnnotationDriver extends AbstractAnnotationDriver
     {
         if ($reader == null) {
             $reader = new AnnotationReader();
-            $reader->setDefaultAnnotationNamespace('Doctrine\ORM\Mapping\\');
         }
+
         return new self($reader, $paths);
     }
 }

lib/Doctrine/ORM/Mapping/Driver/DatabaseDriver.php

@@ -152,7 +152,7 @@ class DatabaseDriver implements MappingDriver
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadMetadataForClass($className, ClassMetadata $metadata)
     {
@@ -318,7 +318,7 @@ class DatabaseDriver implements MappingDriver
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function isTransient($className)
     {
@@ -326,11 +326,7 @@ class DatabaseDriver implements MappingDriver
     }
 
     /**
-     * Return all the class names supported by this driver.
+     * {@inheritDoc}
-     *
-     * IMPORTANT: This method must return an array of class not tables names.
-     *
-     * @return array
      */
     public function getAllClassNames()
     {

lib/Doctrine/ORM/Mapping/Driver/DriverChain.php

@@ -20,6 +20,7 @@
 namespace Doctrine\ORM\Mapping\Driver;
 
 use Doctrine\Common\Persistence\Mapping\Driver\MappingDriver,
+    Doctrine\Common\Persistence\Mapping\Driver\MappingDriverChain,
     Doctrine\Common\Persistence\Mapping\ClassMetadata,
     Doctrine\ORM\Mapping\MappingException;
 
@@ -32,15 +33,9 @@ use Doctrine\Common\Persistence\Mapping\Driver\MappingDriver,
  * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
  * @author Jonathan H. Wage <jonwage@gmail.com>
  * @author Roman Borschel <roman@code-factory.org>
- * @todo Rename: MappingDriverChain or MetadataDriverChain
  */
-class DriverChain implements MappingDriver
+class DriverChain extends MappingDriverChain
 {
-    /**
-     * @var array
-     */
-    private $drivers = array();
-
     /**
      * The default driver
      *
@@ -51,7 +46,7 @@ class DriverChain implements MappingDriver
     /**
      * Get the default driver.
      *
-     * @return MappingDriver
+     * @return MappingDriver|null
      */
     public function getDefaultDriver()
     {
@@ -69,37 +64,13 @@ class DriverChain implements MappingDriver
     }
 
     /**
-     * Add a nested driver.
+     * {@inheritDoc}
-     *
-     * @param MappingDriver $nestedDriver
-     * @param string $namespace
-     */
-    public function addDriver(MappingDriver $nestedDriver, $namespace)
-    {
-        $this->drivers[$namespace] = $nestedDriver;
-    }
-
-    /**
-     * Get the array of nested drivers.
-     *
-     * @return array $drivers
-     */
-    public function getDrivers()
-    {
-        return $this->drivers;
-    }
-
-    /**
-     * Loads the metadata for the specified class into the provided container.
-     *
-     * @param string $className
-     * @param ClassMetadata $metadata
      * @throws MappingException
-     * @return
      */
     public function loadMetadataForClass($className, ClassMetadata $metadata)
     {
-        foreach ($this->drivers as $namespace => $driver) {
+        /* @var $driver MappingDriver */
+        foreach ($this->getDrivers() as $namespace => $driver) {
             if (strpos($className, $namespace) === 0) {
                 $driver->loadMetadataForClass($className, $metadata);
                 return;
@@ -115,50 +86,18 @@ class DriverChain implements MappingDriver
     }
 
     /**
-     * Gets the names of all mapped classes known to this driver.
+     * {@inheritDoc}
-     *
-     * @return array The names of all mapped classes known to this driver.
-     */
-    public function getAllClassNames()
-    {
-        $classNames = array();
-        $driverClasses = array();
-        foreach ($this->drivers as $namespace => $driver) {
-            $oid = spl_object_hash($driver);
-            if (!isset($driverClasses[$oid])) {
-                $driverClasses[$oid] = $driver->getAllClassNames();
-            }
-
-            foreach ($driverClasses[$oid] as $className) {
-                if (strpos($className, $namespace) === 0) {
-                    $classNames[$className] = true;
-                }
-            }
-        }
-        return array_keys($classNames);
-    }
-
-    /**
-     * Whether the class with the specified name should have its metadata loaded.
-     *
-     * This is only the case for non-transient classes either mapped as an Entity or MappedSuperclass.
-     *
-     * @param string $className
-     * @return boolean
      */
     public function isTransient($className)
     {
-        foreach ($this->drivers as $namespace => $driver) {
+        if (!parent::isTransient($className)) {
-            if (strpos($className, $namespace) === 0) {
+            return false;
-                return $driver->isTransient($className);
-            }
         }
 
         if ($this->defaultDriver !== null) {
             return $this->defaultDriver->isTransient($className);
         }
 
-        // class isTransient, i.e. not an entity or mapped superclass
         return true;
     }
 }

lib/Doctrine/ORM/Mapping/Driver/PHPDriver.php

@@ -34,7 +34,6 @@ use Doctrine\Common\Persistence\Mapping\ClassMetadata,
  * @author		Guilherme Blanco <guilhermeblanco@hotmail.com>
  * @author      Jonathan H. Wage <jonwage@gmail.com>
  * @author      Roman Borschel <roman@code-factory.org>
- * @todo Rename: PHPDriver
  */
 class PHPDriver extends FileDriver
 {
@@ -47,7 +46,7 @@ class PHPDriver extends FileDriver
     protected $_metadata;
     
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function __construct($locator, $fileExtension = self::DEFAULT_FILE_EXTENSION)
     {
@@ -55,7 +54,7 @@ class PHPDriver extends FileDriver
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadMetadataForClass($className, ClassMetadata $metadata)
     {
@@ -64,7 +63,7 @@ class PHPDriver extends FileDriver
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     protected function loadMappingFile($file)
     {

lib/Doctrine/ORM/Mapping/Driver/SimplifiedXmlDriver.php

@@ -33,7 +33,7 @@ class SimplifiedXmlDriver extends XmlDriver
     const DEFAULT_FILE_EXTENSION = '.orm.xml';
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function __construct($prefixes, $fileExtension = self::DEFAULT_FILE_EXTENSION)
     {

lib/Doctrine/ORM/Mapping/Driver/SimplifiedYamlDriver.php

@@ -33,7 +33,7 @@ class SimplifiedYamlDriver extends YamlDriver
     const DEFAULT_FILE_EXTENSION = '.orm.yml';
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function __construct($prefixes, $fileExtension = self::DEFAULT_FILE_EXTENSION)
     {

lib/Doctrine/ORM/Mapping/Driver/StaticPHPDriver.php

@@ -58,18 +58,28 @@ class StaticPHPDriver implements MappingDriver
      */
     private $_fileExtension = '.php';
 
+    /**
+     * Constructor
+     *
+     * @param array $paths Paths where to look for mappings
+     */
     public function __construct($paths)
     {
         $this->addPaths((array) $paths);
     }
 
+    /**
+     * Add paths where to look for mappings
+     *
+     * @param array $paths
+     */
     public function addPaths(array $paths)
     {
         $this->_paths = array_unique(array_merge($this->_paths, $paths));
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadMetadataForClass($className, ClassMetadata $metadata)
     {
@@ -78,7 +88,6 @@ class StaticPHPDriver implements MappingDriver
 
     /**
      * {@inheritDoc}
-     * @todo Same code exists in AnnotationDriver, should we re-use it somehow or not worry about it?
      */
     public function getAllClassNames()
     {
@@ -99,8 +108,8 @@ class StaticPHPDriver implements MappingDriver
             }
 
             $iterator = new \RecursiveIteratorIterator(
-                            new \RecursiveDirectoryIterator($path),
+                new \RecursiveDirectoryIterator($path),
-                            \RecursiveIteratorIterator::LEAVES_ONLY
+                \RecursiveIteratorIterator::LEAVES_ONLY
             );
 
             foreach ($iterator as $file) {
@@ -130,7 +139,7 @@ class StaticPHPDriver implements MappingDriver
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function isTransient($className)
     {

lib/Doctrine/ORM/Mapping/Driver/XmlDriver.php

@@ -40,7 +40,7 @@ class XmlDriver extends FileDriver
     const DEFAULT_FILE_EXTENSION = '.dcm.xml';
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function __construct($locator, $fileExtension = self::DEFAULT_FILE_EXTENSION)
     {
@@ -48,10 +48,12 @@ class XmlDriver extends FileDriver
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadMetadataForClass($className, ClassMetadata $metadata)
     {
+        /* @var $metadata \Doctrine\ORM\Mapping\ClassMetadataInfo */
+        /* @var $xmlRoot SimpleXMLElement */
         $xmlRoot = $this->getElement($className);
 
         if ($xmlRoot->getName() == 'entity') {
@@ -557,6 +559,7 @@ class XmlDriver extends FileDriver
     {
         $array = array();
 
+        /* @var $option SimpleXMLElement */
         foreach ($options as $option) {
             if ($option->count()) {
                 $value = $this->_parseOptions($option->children());
@@ -673,6 +676,7 @@ class XmlDriver extends FileDriver
     private function _getCascadeMappings($cascadeElement)
     {
         $cascades = array();
+        /* @var $action SimpleXmlElement */
         foreach ($cascadeElement->children() as $action) {
             // According to the JPA specifications, XML uses "cascade-persist"
             // instead of "persist". Here, both variations
@@ -685,7 +689,7 @@ class XmlDriver extends FileDriver
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     protected function loadMappingFile($file)
     {

lib/Doctrine/ORM/Mapping/Driver/YamlDriver.php

@@ -38,7 +38,7 @@ class YamlDriver extends FileDriver
     const DEFAULT_FILE_EXTENSION = '.dcm.yml';
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function __construct($locator, $fileExtension = self::DEFAULT_FILE_EXTENSION)
     {
@@ -46,10 +46,11 @@ class YamlDriver extends FileDriver
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadMetadataForClass($className, ClassMetadata $metadata)
     {
+        /* @var $metadata \Doctrine\ORM\Mapping\ClassMetadataInfo */
         $element = $this->getElement($className);
 
         if ($element['type'] == 'entity') {
@@ -326,9 +327,9 @@ class YamlDriver extends FileDriver
                     if (isset($oneToOneElement['joinColumn'])) {
                         $joinColumns[] = $this->joinColumnToArray($oneToOneElement['joinColumn']);
                     } else if (isset($oneToOneElement['joinColumns'])) {
-                        foreach ($oneToOneElement['joinColumns'] as $name => $joinColumnElement) {
+                        foreach ($oneToOneElement['joinColumns'] as $joinColumnName => $joinColumnElement) {
                             if ( ! isset($joinColumnElement['name'])) {
-                                $joinColumnElement['name'] = $name;
+                                $joinColumnElement['name'] = $joinColumnName;
                             }
 
                             $joinColumns[] = $this->joinColumnToArray($joinColumnElement);
@@ -408,9 +409,9 @@ class YamlDriver extends FileDriver
                 if (isset($manyToOneElement['joinColumn'])) {
                     $joinColumns[] = $this->joinColumnToArray($manyToOneElement['joinColumn']);
                 } else if (isset($manyToOneElement['joinColumns'])) {
-                    foreach ($manyToOneElement['joinColumns'] as $name => $joinColumnElement) {
+                    foreach ($manyToOneElement['joinColumns'] as $joinColumnName => $joinColumnElement) {
                         if ( ! isset($joinColumnElement['name'])) {
-                            $joinColumnElement['name'] = $name;
+                            $joinColumnElement['name'] = $joinColumnName;
                         }
 
                         $joinColumns[] = $this->joinColumnToArray($joinColumnElement);
@@ -452,17 +453,17 @@ class YamlDriver extends FileDriver
                         $joinTable['schema'] = $joinTableElement['schema'];
                     }
 
-                    foreach ($joinTableElement['joinColumns'] as $name => $joinColumnElement) {
+                    foreach ($joinTableElement['joinColumns'] as $joinColumnName => $joinColumnElement) {
                         if ( ! isset($joinColumnElement['name'])) {
-                            $joinColumnElement['name'] = $name;
+                            $joinColumnElement['name'] = $joinColumnName;
                         }
 
                         $joinTable['joinColumns'][] = $this->joinColumnToArray($joinColumnElement);
                     }
 
-                    foreach ($joinTableElement['inverseJoinColumns'] as $name => $joinColumnElement) {
+                    foreach ($joinTableElement['inverseJoinColumns'] as $joinColumnName => $joinColumnElement) {
                         if ( ! isset($joinColumnElement['name'])) {
-                            $joinColumnElement['name'] = $name;
+                            $joinColumnElement['name'] = $joinColumnName;
                         }
 
                         $joinTable['inverseJoinColumns'][] = $this->joinColumnToArray($joinColumnElement);
@@ -671,7 +672,7 @@ class YamlDriver extends FileDriver
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     protected function loadMappingFile($file)
     {