Documented addAnnotatedClassesToCompile() and the use of class patterns

bundles/extension.rst

@@ -133,31 +133,66 @@ 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::
 
     // ...
     public function load(array $configs, ContainerBuilder $container)
     {
         // ...
 
+        // this method can't compile classes that contain PHP annotations
         $this->addClassesToCompile(array(
             'AppBundle\\Manager\\UserManager',
             'AppBundle\\Utils\\Slugger',
             // ...
         ));
+
+        // 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.