minor #7193 Documented addAnnotatedClassesToCompile() and the use of class patterns (javiereguiluz)

xabbuh · xabbuh · commit e1b48e96e47c · 2017-05-17T09:18:29.000+02:00
This PR was squashed before being merged into the 3.2 branch (closes #7193). Discussion ---------- Documented addAnnotatedClassesToCompile() and the use of class patterns This fixes #7175. Commits ------- e2a67cd Documented addAnnotatedClassesToCompile() and the use of class patterns
diff --git a/bundles/extension.rst b/bundles/extension.rst
@@ -133,9 +133,14 @@ Symfony creates a big ``classes.php`` file in the cache directory to aggregate
 the contents of the PHP classes that are used in every request. This reduces the
 I/O operations and increases the application performance.
 
+.. versionadded:: 3.2
+   The ``addAnnotatedClassesToCompile()`` method was added in Symfony 3.2.
+
 Your bundles can also add their own classes into this file thanks to the
-``addClassesToCompile()`` method. Define the classes to compile as an array of
-their fully qualified class names::
+``addClassesToCompile()`` and ``addAnnotatedClassesToCompile()`` methods (both
+work in the same way, but the second one is for classes that contain PHP
+annotations). Define the classes to compile as an array of their fully qualified
+class names::
 
     use AppBundle\Manager\UserManager;
     use AppBundle\Utils\Slugger;
@@ -145,22 +150,52 @@ their fully qualified class names::
     {
         // ...
 
+        // this method can't compile classes that contain PHP annotations
         $this->addClassesToCompile(array(
             UserManager::class,
             Slugger::class,
             // ...
         ));
+
+        // add here only classes that contain PHP annotations
+        $this->addAnnotatedClassesToCompile(array(
+            'AppBundle\\Controller\\DefaultController',
+            // ...
+        ));
     }
 
 .. note::
 
     If some class extends from other classes, all its parents are automatically
     included in the list of classes to compile.
 
-Beware that this technique **can't be used in some cases**:
+.. versionadded:: 3.2
+   The option to add classes to compile using patterns was introduced in Symfony 3.2.
+
+The classes to compile can also be added using file path patterns::
+
+    // ...
+    public function load(array $configs, ContainerBuilder $container)
+    {
+        // ...
+
+        $this->addClassesToCompile(array(
+            '**Bundle\\Manager\\',
+            // ...
+        ));
+
+        $this->addAnnotatedClassesToCompile(array(
+            '**Bundle\\Controller\\',
+            // ...
+        ));
+    }
+
+Patterns are transformed into the actual class namespaces using the classmap
+generated by Composer. Therefore, before using these patterns, you must generate
+the full classmap executing the ``dump-autoload`` command of Composer.
+
+.. caution::
 
-* When classes contain annotations, such as controllers with ``@Route``
-  annotations and entities with ``@ORM`` or ``@Assert`` annotations, because
-  the file location retrieved from PHP reflection changes;
-* When classes use the ``__DIR__`` and ``__FILE__`` constants, because their
-  values will change when loading these classes from the ``classes.php`` file.
+    This technique can't be used when the classes to compile use the ``__DIR__``
+    or ``__FILE__`` constants, because their values will change when loading
+    these classes from the ``classes.php`` file.
