minor symfony#12201 [Validator] Fixed: The state of the XML/YAML loaders was changed even if an exception was thrown upon loading (webmozart)

This PR was merged into the 2.3 branch.

Discussion
----------

[Validator] Fixed: The state of the XML/YAML loaders was changed even if an exception was thrown upon loading

| Q             | A
| ------------- | ---
| Bug fix?      | yes
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | symfony#12158
| License       | MIT
| Doc PR        | -

Commits
-------

85d464a [Validator] Fixed: The state of the XML/YAML loaders was changed even if an exception was thrown upon loading

Author: fabpot

src/Symfony/Component/Validator/Mapping/Loader/AbstractLoader.php

@@ -14,18 +14,39 @@
 use Symfony\Component\Validator\Exception\MappingException;
 use Symfony\Component\Validator\Constraint;
 
+/**
+ * Base loader for validation metadata.
+ *
+ * This loader supports the loading of constraints from Symfony's default
+ * namespace (see {@link DEFAULT_NAMESPACE}) using the short class names of
+ * those constraints. Constraints can also be loaded using their fully
+ * qualified class names. At last, namespace aliases can be defined to load
+ * constraints with the syntax "alias:ShortName".
+ *
+ * @author Bernhard Schussek <[email protected]>
+ */
 abstract class AbstractLoader implements LoaderInterface
 {
     /**
-     * Contains all known namespaces indexed by their prefix.
-     *
+     * The namespace to load constraints from by default.
+     */
+    const DEFAULT_NAMESPACE = '\\Symfony\\Component\\Validator\\Constraints\\';
+
+    /**
      * @var array
      */
     protected $namespaces;
 
     /**
      * Adds a namespace alias.
      *
+     * The namespace alias can be used to reference constraints from specific
+     * namespaces in {@link newConstraint()}:
+     *
+     *     $this->addNamespaceAlias('mynamespace', '\\Acme\\Package\\Constraints\\');
+     *
+     *     $constraint = $this->newConstraint('mynamespace:NotNull');
+     *
      * @param string $alias     The alias
      * @param string $namespace The PHP namespace
      */
@@ -37,16 +58,19 @@ protected function addNamespaceAlias($alias, $namespace)
     /**
      * Creates a new constraint instance for the given constraint name.
      *
-     * @param string $name    The constraint name. Either a constraint relative
-     *                        to the default constraint namespace, or a fully
-     *                        qualified class name
-     * @param mixed  $options The constraint options
+     * @param string $name   The constraint name. Either a constraint relative
+     *                       to the default constraint namespace, or a fully
+     *                       qualified class name. Alternatively, the constraint
+     *                       may be preceded by a namespace alias and a colon.
+     *                       The namespace alias must have been defined using
+     *                       {@link addNamespaceAlias()}.
+     * @param mixed $options The constraint options
      *
      * @return Constraint
      *
      * @throws MappingException If the namespace prefix is undefined
      */
-    protected function newConstraint($name, $options)
+    protected function newConstraint($name, $options = null)
     {
         if (strpos($name, '\\') !== false && class_exists($name)) {
             $className = (string) $name;
@@ -59,7 +83,7 @@ protected function newConstraint($name, $options)
 
             $className = $this->namespaces[$prefix].$className;
         } else {
-            $className = 'Symfony\\Component\\Validator\\Constraints\\'.$name;
+            $className = self::DEFAULT_NAMESPACE.$name;
         }
 
         return new $className($options);

src/Symfony/Component/Validator/Mapping/Loader/AnnotationLoader.php

@@ -18,23 +18,40 @@
 use Symfony\Component\Validator\Constraints\GroupSequenceProvider;
 use Symfony\Component\Validator\Constraint;
 
+/**
+ * Loads validation metadata using a Doctrine annotation {@link Reader}.
+ *
+ * @author Bernhard Schussek <[email protected]>
+ */
 class AnnotationLoader implements LoaderInterface
 {
+    /**
+     * @var Reader
+     */
     protected $reader;
 
+    /**
+     * Creates a new loader.
+     *
+     * @param Reader $reader The annotation reader to use.
+     */
     public function __construct(Reader $reader)
     {
         $this->reader = $reader;
     }
 
     /**
-     * {@inheritdoc}
+     * Loads the metadata using annotations defined in the class.
+     *
+     * @param ClassMetadata $metadata The class metadata to load
+     *
+     * @return bool Whether the loader succeeded
      */
     public function loadClassMetadata(ClassMetadata $metadata)
     {
         $reflClass = $metadata->getReflectionClass();
         $className = $reflClass->name;
-        $loaded = false;
+        $success = false;
 
         foreach ($this->reader->getClassAnnotations($reflClass) as $constraint) {
             if ($constraint instanceof GroupSequence) {
@@ -45,7 +62,7 @@ public function loadClassMetadata(ClassMetadata $metadata)
                 $metadata->addConstraint($constraint);
             }
 
-            $loaded = true;
+            $success = true;
         }
 
         foreach ($reflClass->getProperties() as $property) {
@@ -55,7 +72,7 @@ public function loadClassMetadata(ClassMetadata $metadata)
                         $metadata->addPropertyConstraint($property->name, $constraint);
                     }
 
-                    $loaded = true;
+                    $success = true;
                 }
             }
         }
@@ -71,11 +88,11 @@ public function loadClassMetadata(ClassMetadata $metadata)
                         }
                     }
 
-                    $loaded = true;
+                    $success = true;
                 }
             }
         }
 
-        return $loaded;
+        return $success;
     }
 }

src/Symfony/Component/Validator/Mapping/Loader/FileLoader.php

@@ -13,26 +13,42 @@
 
 use Symfony\Component\Validator\Exception\MappingException;
 
+/**
+ * Base loader for loading validation metadata from a file.
+ *
+ * @author Bernhard Schussek <[email protected]>
+ *
+ * @see YamlFileLoader
+ * @see XmlFileLoader
+ */
 abstract class FileLoader extends AbstractLoader
 {
+    /**
+     * The file to load.
+     *
+     * @var string
+     */
     protected $file;
 
     /**
-     * Constructor.
+     * Creates a new loader.
      *
      * @param string $file The mapping file to load
      *
-     * @throws MappingException if the mapping file does not exist
-     * @throws MappingException if the mapping file is not readable
+     * @throws MappingException If the file does not exist or is not readable
      */
     public function __construct($file)
     {
         if (!is_file($file)) {
-            throw new MappingException(sprintf('The mapping file %s does not exist', $file));
+            throw new MappingException(sprintf('The mapping file "%s" does not exist', $file));
         }
 
         if (!is_readable($file)) {
-            throw new MappingException(sprintf('The mapping file %s is not readable', $file));
+            throw new MappingException(sprintf('The mapping file "%s" is not readable', $file));
+        }
+
+        if (!stream_is_local($this->file)) {
+            throw new MappingException(sprintf('The mapping file "%s" is not a local file', $file));
         }
 
         $this->file = $file;

src/Symfony/Component/Validator/Mapping/Loader/FilesLoader.php

@@ -12,37 +12,42 @@
 namespace Symfony\Component\Validator\Mapping\Loader;
 
 /**
- * Creates mapping loaders for array of files.
- *
- * Abstract class, used by
+ * Base loader for loading validation metadata from a list of files.
  *
  * @author Bulat Shakirzyanov <[email protected]>
+ * @author Bernhard Schussek <[email protected]>
  *
+<<<<<<< HEAD
  * @see YamlFileLoader
  * @see XmlFileLoader
+=======
+ * @see YamlFilesLoader
+ * @see XmlFilesLoader
+>>>>>>> pull/12201
  */
 abstract class FilesLoader extends LoaderChain
 {
     /**
-     * Array of mapping files.
+     * Creates a new loader.
      *
-     * @param array $paths Array of file paths
+     * @param array $paths An array of file paths
      */
     public function __construct(array $paths)
     {
         parent::__construct($this->getFileLoaders($paths));
     }
 
     /**
-     * Array of mapping files.
+     * Returns an array of file loaders for the given file paths.
      *
-     * @param array $paths Array of file paths
+     * @param array $paths An array of file paths
      *
-     * @return LoaderInterface[] Array of metadata loaders
+     * @return LoaderInterface[] The metadata loaders
      */
     protected function getFileLoaders($paths)
     {
         $loaders = array();
+
         foreach ($paths as $path) {
             $loaders[] = $this->getFileLoaderInstance($path);
         }
@@ -51,11 +56,11 @@ protected function getFileLoaders($paths)
     }
 
     /**
-     * Takes mapping file path.
+     * Creates a loader for the given file path.
      *
-     * @param string $file
+     * @param string $path The file path
      *
-     * @return LoaderInterface
+     * @return LoaderInterface The created loader
      */
-    abstract protected function getFileLoaderInstance($file);
+    abstract protected function getFileLoaderInstance($path);
 }

src/Symfony/Component/Validator/Mapping/Loader/LoaderChain.php

@@ -15,25 +15,25 @@
 use Symfony\Component\Validator\Mapping\ClassMetadata;
 
 /**
- * Calls multiple LoaderInterface instances in a chain.
+ * Loads validation metadata from multiple {@link LoaderInterface} instances.
  *
- * This class accepts multiple instances of LoaderInterface to be passed to the
- * constructor. When loadClassMetadata() is called, the same method is called
- * in <em>all</em> of these loaders, regardless of whether any of them was
- * successful or not.
+ * Pass the loaders when constructing the chain. Once
+ * {@link loadClassMetadata()} is called, that method will be called on all
+ * loaders in the chain.
  *
  * @author Bernhard Schussek <[email protected]>
  */
 class LoaderChain implements LoaderInterface
 {
+    /**
+     * @var LoaderInterface[]
+     */
     protected $loaders;
 
     /**
-     * Accepts a list of LoaderInterface instances.
-     *
-     * @param LoaderInterface[] $loaders An array of LoaderInterface instances
+     * @param LoaderInterface[] $loaders The metadata loaders to use
      *
-     * @throws MappingException If any of the loaders does not implement LoaderInterface
+     * @throws MappingException If any of the loaders has an invalid type
      */
     public function __construct(array $loaders)
     {
@@ -47,7 +47,12 @@ public function __construct(array $loaders)
     }
 
     /**
-     * {@inheritdoc}
+     * Calls {@link LoaderInterface::loadClassMetadata()} on all loaders in
+     * the chain.
+     *
+     * @param ClassMetadata $metadata The metadata to load
+     *
+     * @return bool Whether the loader succeeded
      */
     public function loadClassMetadata(ClassMetadata $metadata)
     {

src/Symfony/Component/Validator/Mapping/Loader/LoaderInterface.php

@@ -13,14 +13,19 @@
 
 use Symfony\Component\Validator\Mapping\ClassMetadata;
 
+/**
+ * Loads validation metadata into {@link ClassMetadata} instances.
+ *
+ * @author Bernhard Schussek <[email protected]>
+ */
 interface LoaderInterface
 {
     /**
-     * Load a Class Metadata.
+     * Loads validation metadata into a {@link ClassMetadata} instance.
      *
-     * @param ClassMetadata $metadata A metadata
+     * @param ClassMetadata $metadata The metadata to load
      *
-     * @return bool
+     * @return bool Whether the loader succeeded
      */
     public function loadClassMetadata(ClassMetadata $metadata);
 }

src/Symfony/Component/Validator/Mapping/Loader/StaticMethodLoader.php

@@ -14,17 +14,38 @@
 use Symfony\Component\Validator\Exception\MappingException;
 use Symfony\Component\Validator\Mapping\ClassMetadata;
 
+/**
+ * Loads validation metadata by calling a static method on the loaded class.
+ *
+ * @author Bernhard Schussek <[email protected]>
+ */
 class StaticMethodLoader implements LoaderInterface
 {
+    /**
+     * The name of the method to call.
+     *
+     * @var string
+     */
     protected $methodName;
 
+    /**
+     * Creates a new loader.
+     *
+     * @param string $methodName The name of the static method to call
+     */
     public function __construct($methodName = 'loadValidatorMetadata')
     {
         $this->methodName = $methodName;
     }
 
     /**
-     * {@inheritdoc}
+     * Loads validation metadata by calling a static method in the class.
+     *
+     * The name of the static method is passed to {@link __construct()}.
+     *
+     * @param ClassMetadata $metadata The metadata to load
+     *
+     * @return bool Whether the loader succeeded
      */
     public function loadClassMetadata(ClassMetadata $metadata)
     {