minor #19185 [Bundle] Sync doc pages with current Symfony codebase (smnandre)

This PR was submitted for the 6.4 branch but it was squashed and merged into the 6.3 branch instead.

Discussion
----------

[Bundle] Sync doc pages with current Symfony codebase

A group of updates related to bundles, mainly about namespaces, source paths and code sample sync with the current Symfony codebase / best practices.

I won't mind a second look :)

Commits
-------

2d0af9c [Bundle] Sync doc pages with current Symfony codebase

Author: javiereguiluz

bundles.rst

@@ -22,13 +22,15 @@ file::
     return [
         // 'all' means that the bundle is enabled for any Symfony environment
         Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
-        Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
-        Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
-        Symfony\Bundle\MonologBundle\MonologBundle::class => ['all' => true],
-        Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
-        Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle::class => ['all' => true],
+        // ...
+
+        // this bundle is enabled only in 'dev'
+        Symfony\Bundle\DebugBundle\DebugBundle::class => ['dev' => true],
+        // ...
+
         // this bundle is enabled only in 'dev' and 'test', so you can't use it in 'prod'
         Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true],
+        // ...
     ];
 
 .. tip::
@@ -41,18 +43,18 @@ Creating a Bundle
 -----------------
 
 This section creates and enables a new bundle to show there are only a few steps required.
-The new bundle is called AcmeTestBundle, where the ``Acme`` portion is an example
+The new bundle is called AcmeBlogBundle, where the ``Acme`` portion is an example
 name that should be replaced by some "vendor" name that represents you or your
-organization (e.g. AbcTestBundle for some company named ``Abc``).
+organization (e.g. AbcBlogBundle for some company named ``Abc``).
 
-Start by creating a new class called ``AcmeTestBundle``::
+Start by creating a new class called ``AcmeBlogBundle``::
 
-    // src/AcmeTestBundle.php
-    namespace Acme\TestBundle;
+    // src/AcmeBlogBundle.php
+    namespace Acme\BlogBundle;
 
     use Symfony\Component\HttpKernel\Bundle\AbstractBundle;
 
-    class AcmeTestBundle extends AbstractBundle
+    class AcmeBlogBundle extends AbstractBundle
     {
     }
 
@@ -68,10 +70,10 @@ Start by creating a new class called ``AcmeTestBundle``::
 
 .. tip::
 
-    The name AcmeTestBundle follows the standard
+    The name AcmeBlogBundle follows the standard
     :ref:`Bundle naming conventions <bundles-naming-conventions>`. You could
-    also choose to shorten the name of the bundle to simply TestBundle by naming
-    this class TestBundle (and naming the file ``TestBundle.php``).
+    also choose to shorten the name of the bundle to simply BlogBundle by naming
+    this class BlogBundle (and naming the file ``BlogBundle.php``).
 
 This empty class is the only piece you need to create the new bundle. Though
 commonly empty, this class is powerful and can be used to customize the behavior
@@ -80,10 +82,10 @@ of the bundle. Now that you've created the bundle, enable it::
     // config/bundles.php
     return [
         // ...
-        Acme\TestBundle\AcmeTestBundle::class => ['all' => true],
+        Acme\BlogBundle\AcmeBlogBundle::class => ['all' => true],
     ];
 
-And while it doesn't do anything yet, AcmeTestBundle is now ready to be used.
+And while it doesn't do anything yet, AcmeBlogBundle is now ready to be used.
 
 Bundle Directory Structure
 --------------------------
@@ -92,31 +94,31 @@ The directory structure of a bundle is meant to help to keep code consistent
 between all Symfony bundles. It follows a set of conventions, but is flexible
 to be adjusted if needed:
 
-``src/``
-    Contains all PHP classes related to the bundle logic (e.g. ``Controller/RandomController.php``).
+``assets/``
+    Contains the web asset sources like JavaScript and TypeScript files, CSS and
+    Sass files, but also images and other assets related to the bundle that are
+    not in ``public/`` (e.g. Stimulus controllers).
 
 ``config/``
-    Houses configuration, including routing configuration (e.g. ``routing.yaml``).
-
-``templates/``
-    Holds templates organized by controller name (e.g. ``random/index.html.twig``).
-
-``translations/``
-    Holds translations organized by domain and locale (e.g. ``AcmeTestBundle.en.xlf``).
+    Houses configuration, including routing configuration (e.g. ``routes.php``).
 
 ``public/``
     Contains web assets (images, compiled CSS and JavaScript files, etc.) and is
     copied or symbolically linked into the project ``public/`` directory via the
     ``assets:install`` console command.
 
-``assets/``
-    Contains the web asset sources (JavaScript and TypeScript files, CSS and Sass
-    files, etc.), images and other assets related to the bundle that are not in
-    ``public/`` (e.g. Stimulus controllers)
+``src/``
+    Contains all PHP classes related to the bundle logic (e.g. ``Controller/CategoryController.php``).
+
+``templates/``
+    Holds templates organized by controller name (e.g. ``category/show.html.twig``).
 
 ``tests/``
     Holds all tests for the bundle.
 
+``translations/``
+    Holds translations organized by domain and locale (e.g. ``AcmeBlogBundle.en.xlf``).
+
 .. caution::
 
     The recommended bundle structure was changed in Symfony 5, read the
@@ -127,7 +129,7 @@ to be adjusted if needed:
     new structure. Override the ``Bundle::getPath()`` method to change to
     the old structure::
 
-        class AcmeTestBundle extends AbstractBundle
+        class AcmeBlogBundle extends AbstractBundle
         {
             public function getPath(): string
             {
@@ -146,12 +148,12 @@ to be adjusted if needed:
         {
             "autoload": {
                 "psr-4": {
-                    "Acme\\TestBundle\\": "src/"
+                    "Acme\\BlogBundle\\": "src/"
                 }
             },
             "autoload-dev": {
                 "psr-4": {
-                    "Acme\\TestBundle\\Tests\\": "tests/"
+                    "Acme\\BlogBundle\\Tests\\": "tests/"
                 }
             }
         }

bundles/configuration.rst

@@ -175,7 +175,7 @@ of your bundle's configuration.
 
 The ``Configuration`` class to handle the sample configuration looks like::
 
-    // src/Acme/SocialBundle/DependencyInjection/Configuration.php
+    // src/DependencyInjection/Configuration.php
     namespace Acme\SocialBundle\DependencyInjection;
 
     use Symfony\Component\Config\Definition\Builder\TreeBuilder;
@@ -216,7 +216,7 @@ This class can now be used in your ``load()`` method to merge configurations and
 force validation (e.g. if an additional option was passed, an exception will be
 thrown)::
 
-    // src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
+    // src/DependencyInjection/AcmeSocialExtension.php
     public function load(array $configs, ContainerBuilder $container): void
     {
         $configuration = new Configuration();
@@ -236,7 +236,7 @@ For example, imagine your bundle has the following example config:
 
 .. code-block:: xml
 
-    <!-- src/Acme/SocialBundle/Resources/config/services.xml -->
+    <!-- src/config/services.xml -->
     <?xml version="1.0" encoding="UTF-8" ?>
     <container xmlns="http://symfony.com/schema/dic/services"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -253,8 +253,8 @@ For example, imagine your bundle has the following example config:
 
 In your extension, you can load this and dynamically set its arguments::
 
-    // src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
-    // ...
+    // src/DependencyInjection/AcmeSocialExtension.php
+    namespace Acme\SocialBundle\DependencyInjection;
 
     use Symfony\Component\Config\FileLocator;
     use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
@@ -279,7 +279,7 @@ In your extension, you can load this and dynamically set its arguments::
     :class:`Symfony\\Component\\HttpKernel\\DependencyInjection\\ConfigurableExtension`
     to do this automatically for you::
 
-        // src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php
+        // src/DependencyInjection/HelloExtension.php
         namespace Acme\HelloBundle\DependencyInjection;
 
         use Symfony\Component\DependencyInjection\ContainerBuilder;
@@ -375,6 +375,7 @@ logic to the bundle class directly::
     configuration definition from one or more files::
 
         // src/AcmeSocialBundle.php
+        namespace Acme\SocialBundle;
 
         // ...
         class AcmeSocialBundle extends AbstractBundle
@@ -417,7 +418,7 @@ The ``config:dump-reference`` command dumps the default configuration of a
 bundle in the console using the Yaml format.
 
 As long as your bundle's configuration is located in the standard location
-(``YourBundle\DependencyInjection\Configuration``) and does not have
+(``<YourBundle>/src/DependencyInjection/Configuration``) and does not have
 a constructor, it will work automatically. If you
 have something different, your ``Extension`` class must override the
 :method:`Extension::getConfiguration() <Symfony\\Component\\DependencyInjection\\Extension\\Extension::getConfiguration>`
@@ -451,7 +452,8 @@ URL nor does it need to exist). By default, the namespace for a bundle is
 ``http://example.org/schema/dic/DI_ALIAS``, where ``DI_ALIAS`` is the DI alias of
 the extension. You might want to change this to a more professional URL::
 
-    // src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php
+    // src/DependencyInjection/AcmeHelloExtension.php
+    namespace Acme\HelloBundle\DependencyInjection;
 
     // ...
     class AcmeHelloExtension extends Extension
@@ -480,10 +482,11 @@ namespace is then replaced with the XSD validation base path returned from
 method. This namespace is then followed by the rest of the path from the base
 path to the file itself.
 
-By convention, the XSD file lives in the ``Resources/config/schema/``, but you
+By convention, the XSD file lives in ``config/schema/`` directory, but you
 can place it anywhere you like. You should return this path as the base path::
 
-    // src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php
+    // src/DependencyInjection/AcmeHelloExtension.php
+    namespace Acme\HelloBundle\DependencyInjection;
 
     // ...
     class AcmeHelloExtension extends Extension
@@ -492,7 +495,7 @@ can place it anywhere you like. You should return this path as the base path::
 
         public function getXsdValidationBasePath(): string
         {
-            return __DIR__.'/../Resources/config/schema';
+            return __DIR__.'/../config/schema';
         }
     }
 

bundles/extension.rst

@@ -173,9 +173,9 @@ performance. Define the list of annotated classes to compile in the
 
         $this->addAnnotatedClassesToCompile([
             // you can define the fully qualified class names...
-            'App\\Controller\\DefaultController',
+            'Acme\\BlogBundle\\Controller\\AuthorController',
             // ... but glob patterns are also supported:
-            '**Bundle\\Controller\\',
+            'Acme\\BlogBundle\\Form\\**',
 
             // ...
         ]);

templates.rst

@@ -1417,10 +1417,10 @@ may include their own Twig templates (in the ``Resources/views/`` directory of
 each bundle). To avoid messing with your own templates, Symfony adds bundle
 templates under an automatic namespace created after the bundle name.
 
-For example, the templates of a bundle called ``AcmeFooBundle`` are available
-under the ``AcmeFoo`` namespace. If this bundle includes the template
-``<your-project>/vendor/acmefoo-bundle/Resources/views/user/profile.html.twig``,
-you can refer to it as ``@AcmeFoo/user/profile.html.twig``.
+For example, the templates of a bundle called ``AcmeBlogBundle`` are available
+under the ``AcmeBlog`` namespace. If this bundle includes the template
+``<your-project>/vendor/acme/blog-bundle/Resources/views/user/profile.html.twig``,
+you can refer to it as ``@AcmeBlog/user/profile.html.twig``.
 
 .. tip::