[Validator] Improved inline documentation of the metadata classes

symfony · fabpot · Mar 31, 2014 · Feb 12, 2014 · Feb 17, 2014 · Feb 17, 2014
commit 79387a7d5e80ab3e0bbce6f35e275c778a9f9c85
diff --git a/src/Symfony/Component/Validator/Mapping/BlackholeMetadataFactory.php b/src/Symfony/Component/Validator/Mapping/BlackholeMetadataFactory.php
@@ -11,25 +11,30 @@
 
 namespace Symfony\Component\Validator\Mapping;
 
+use Symfony\Component\Validator\Exception\NoSuchMetadataException;
 use Symfony\Component\Validator\MetadataFactoryInterface;
 
 /**
- * Simple implementation of MetadataFactoryInterface that can be used when using ValidatorInterface::validateValue().
+ * Metadata factory that does not store metadata.
+ *
+ * This implementation is useful if you want to validate values against
+ * constraints only and you don't need to add constraints to classes and
+ * properties.
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
 class BlackholeMetadataFactory implements MetadataFactoryInterface
 {
     /**
-     * @inheritdoc
+     * {@inheritdoc}
      */
     public function getMetadataFor($value)
     {
-        throw new \LogicException('BlackholeClassMetadataFactory only works with ValidatorInterface::validateValue().');
+        throw new NoSuchMetadataException('This class does not support metadata.');
     }
 
     /**
-     * @inheritdoc
+     * {@inheritdoc}
      */
     public function hasMetadataFor($value)
     {

diff --git a/src/Symfony/Component/Validator/Mapping/ClassMetadata.php b/src/Symfony/Component/Validator/Mapping/ClassMetadata.php
@@ -22,7 +22,9 @@
 use Symfony\Component\Validator\Exception\GroupDefinitionException;
 
 /**
- * Represents all the configured constraints on a given class.
+ * Default implementation of {@link ClassMetadataInterface}.
+ *
+ * This class supports serialization and cloning.
  *
  * @author Bernhard Schussek <bschussek@gmail.com>
  * @author Fabien Potencier <fabien@symfony.com>
@@ -31,36 +33,64 @@ class ClassMetadata extends ElementMetadata implements LegacyMetadataInterface,
 {
     /**
      * @var string
+     *
+     * @internal This property is public in order to reduce the size of the
+     *           class' serialized representation. Do not access it. Use
+     *           {@link getClassName()} instead.
      */
     public $name;
 
     /**
      * @var string
+     *
+     * @internal This property is public in order to reduce the size of the
+     *           class' serialized representation. Do not access it. Use
+     *           {@link getDefaultGroup()} instead.
      */
     public $defaultGroup;
 
     /**
      * @var MemberMetadata[]
+     *
+     * @internal This property is public in order to reduce the size of the
+     *           class' serialized representation. Do not access it. Use
+     *           {@link getPropertyMetadata()} instead.
      */
     public $members = array();
 
     /**
      * @var PropertyMetadata[]
+     *
+     * @internal This property is public in order to reduce the size of the
+     *           class' serialized representation. Do not access it. Use
+     *           {@link getPropertyMetadata()} instead.
      */
     public $properties = array();
 
     /**
      * @var GetterMetadata[]
+     *
+     * @internal This property is public in order to reduce the size of the
+     *           class' serialized representation. Do not access it. Use
+     *           {@link getPropertyMetadata()} instead.
      */
     public $getters = array();
 
     /**
      * @var array
+     *
+     * @internal This property is public in order to reduce the size of the
+     *           class' serialized representation. Do not access it. Use
+     *           {@link getGroupSequence()} instead.
      */
     public $groupSequence = array();
 
     /**
      * @var Boolean
+     *
+     * @internal This property is public in order to reduce the size of the
+     *           class' serialized representation. Do not access it. Use
+     *           {@link isGroupSequenceProvider()} instead.
      */
     public $groupSequenceProvider = false;
 
@@ -70,6 +100,10 @@ class ClassMetadata extends ElementMetadata implements LegacyMetadataInterface,
      * By default, only instances of {@link \Traversable} are traversed.
      *
      * @var integer
+     *
+     * @internal This property is public in order to reduce the size of the
+     *           class' serialized representation. Do not access it. Use
+     *           {@link getTraversalStrategy()} instead.
      */
     public $traversalStrategy = TraversalStrategy::IMPLICIT;
 
@@ -94,6 +128,11 @@ public function __construct($class)
         }
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * @deprecated Deprecated since version 2.5, to be removed in Symfony 3.0.
+     */
     public function accept(ValidationVisitorInterface $visitor, $value, $group, $propertyPath, $propagatedGroup = null)
     {
         if (null === $propagatedGroup && Constraint::DEFAULT_GROUP === $group
@@ -129,9 +168,7 @@ public function accept(ValidationVisitorInterface $visitor, $value, $group, $pro
     }
 
     /**
-     * Returns the properties to be serialized
-     *
-     * @return array
+     * {@inheritdoc}
      */
     public function __sleep()
     {
@@ -152,9 +189,7 @@ public function __sleep()
     }
 
     /**
-     * Returns the fully qualified name of the class
-     *
-     * @return string  The fully qualified class name
+     * {@inheritdoc}
      */
     public function getClassName()
     {
@@ -356,9 +391,7 @@ public function getPropertyMetadata($property)
     }
 
     /**
-     * Returns all properties for which constraints are defined.
-     *
-     * @return array An array of property names
+     * {@inheritdoc}
      */
     public function getConstrainedProperties()
     {
@@ -398,19 +431,15 @@ public function setGroupSequence($groupSequence)
     }
 
     /**
-     * Returns whether this class has an overridden default group sequence.
-     *
-     * @return Boolean
+     * {@inheritdoc}
      */
     public function hasGroupSequence()
     {
         return count($this->groupSeque
F438
nce) > 0;
     }
 
     /**
-     * Returns the default group sequence for this class.
-     *
-     * @return GroupSequence The group sequence or null
+     * {@inheritdoc}
      */
     public function getGroupSequence()
     {
@@ -452,9 +481,7 @@ public function setGroupSequenceProvider($active)
     }
 
     /**
-     * Returns whether the class is a group sequence provider.
-     *
-     * @return Boolean
+     * {@inheritdoc}
      */
     public function isGroupSequenceProvider()
     {

diff --git a/src/Symfony/Component/Validator/Mapping/ClassMetadataFactory.php b/src/Symfony/Component/Validator/Mapping/ClassMetadataFactory.php
@@ -17,34 +17,81 @@
 use Symfony\Component\Validator\Mapping\Cache\CacheInterface;
 
 /**
- * A factory for creating metadata for PHP classes.
+ * Creates new {@link ClassMetadataInterface} instances.
+ *
+ * Whenever {@link getMetadataFor()} is called for the first time with a given
+ * class name or object of that class, a new metadata instance is created and
+ * returned. On subsequent requests for the same class, the same metadata
+ * instance will be returned.
+ *
+ * You can optionally pass a {@link LoaderInterface} instance to the constructor.
+ * Whenever a new metadata instance, it will be passed to the loader, which can
+ * configure the metadata based on configuration loaded from the filesystem or
+ * a database. If you want to use multiple loaders, wrap them in a
+ * {@link Loader\LoaderChain}.
+ *
+ * You can also optionally pass a {@link CacheInterface} instance to the
+ * constructor. This cache will be used for persisting the generated metadata
+ * between multiple PHP requests.
  *
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
 class ClassMetadataFactory implements MetadataFactoryInterface
 {
     /**
      * The loader for loading the class metadata
+     *
      * @var LoaderInterface
      */
     protected $loader;
 
     /**
      * The cache for caching class metadata
+     *
      * @var CacheInterface
      */
     protected $cache;
 
+    /**
+     * The loaded metadata, indexed by class name
+     *
+     * @var ClassMetadata[]
+     */
     protected $loadedClasses = array();
 
+    /**
+     * Creates a new metadata factory.
+     *
+     * @param LoaderInterface|null $loader The loader for configuring new metadata
+     * @param CacheInterface|null  $cache  The cache for persisting metadata
+     *                                     between multiple PHP requests
+     */
     public function __construct(LoaderInterface $loader = null, CacheInterface $cache = null)
     {
         $this->loader = $loader;
         $this->cache = $cache;
     }
 
     /**
-     * {@inheritdoc}
+     * Returns the metadata for the given class name or object.
+     *
+     * If the method was called with the same class name (or an object of that
+     * class) before, the same metadata instance is returned.
+     *
+     * If the factory was configured with a cache, this method will first look
+     * for an existing metadata instance in the cache. If an existing instance
+     * is found, it will be returned without further ado.
+     *
+     * Otherwise, a new metadata instance is created. If the factory was
+     * configured with a loader, the metadata is passed to the
+     * {@link LoaderInterface::loadClassMetadata()} method for further
+     * configuration. At last, the new object is returned.
+     *
+     * @param string|object $value A class name or an object
+     *
+     * @return MetadataInterface The metadata for the value
+     *
+     * @throws NoSuchMetadataException If no metadata exists for the given value
      */
     public function getMetadataFor($value)
     {
@@ -93,7 +140,12 @@ public function getMetadataFor($value)
     }
 
     /**
-     * {@inheritdoc}
+     * Returns whether the factory is able to return metadata for the given
+     * class name or object.
+     *
+     * @param string|object $value A class name or an object
+     *
+     * @return Boolean Whether metadata can be returned for that class
      */
     public function hasMetadataFor($value)
     {

diff --git a/src/Symfony/Component/Validator/Mapping/ClassMetadataInterface.php b/src/Symfony/Component/Validator/Mapping/ClassMetadataInterface.php
@@ -15,16 +15,66 @@
 use Symfony\Component\Validator\PropertyMetadataContainerInterface as LegacyPropertyMetadataContainerInterface;;
 
 /**
- * @since  %%NextVersion%%
+ * Stores all metadata needed for validating objects of specific class.
+ *
+ * Most importantly, the metadata stores the constraints against which an object
+ * and its properties should be validated.
+ *
+ * Additionally, the metadata stores whether the "Default" group is overridden
+ * by a group sequence for that class and whether instances of that class
+ * should be traversed or not.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
+ *
+ * @see MetadataInterface
+ * @see \Symfony\Component\Validator\Constraints\GroupSequence
+ * @see \Symfony\Component\Validator\GroupSequenceProviderInterface
+ * @see TraversalStrategy
  */
 interface ClassMetadataInterface extends MetadataInterface, LegacyPropertyMetadataContainerInterface, ClassBasedInterface
 {
+    /**
+     * Returns the names of all constrained properties.
+     *
+     * @return string[] A list of property names
+     */
     public function getConstrainedProperties();
 
+    /**
+     * Returns whether the "Default" group is overridden by a group sequence.
+     *
+     * If it is, you can access the group sequence with {@link getGroupSequence()}.
+     *
+     * @return Boolean Returns true if the "Default" group is overridden
+     *
+     * @see \Symfony\Component\Validator\Constraints\GroupSequence
+     */
     public function hasGroupSequence();
 
+    /**
+     * Returns the group sequence that overrides the "Default" group for this
+     * class.
+     *
+     * @return \Symfony\Component\Validator\Constraints\GroupSequence|null The group sequence or null
+     *
+     * @see \Symfony\Component\Validator\Constraints\GroupSequence
+     */
     public function getGroupSequence();
 
+    /**
+     * Returns whether the "Default" group is overridden by a dynamic group
+     * sequence obtained by the validated objects.
+     *
+     * If this method returns true, the class must implement
+     * {@link \Symfony\Component\Validator\GroupSequenceProviderInterface}.
+     * This interface will be used to obtain the group sequence when an object
+     * of this class is validated.
+     *
+     * @return Boolean Returns true if the "Default" group is overridden by
+     *                 a dynamic group sequence
+     *
+     * @see \Symfony\Component\Validator\GroupSequenceProviderInterface
+     */
     public function isGroupSequenceProvider();
 }
diff --git a/src/Symfony/Component/Validator/Mapping/ElementMetadata.php b/src/Symfony/Component/Validator/Mapping/ElementMetadata.php
@@ -11,6 +11,14 @@
 
 namespace Symfony\Component\Validator\Mapping;
 
+/**
+ * Contains the metadata of a structural element.
+ *
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ *
+ * @deprecated Deprecated since version 2.5, to be removed in Symfony 3.0.
+ *             Extend {@link GenericMetadata} instead.
+ */
 abstract class ElementMetadata extends GenericMetadata
 {
 }