diff --git a/bundles.rst b/bundles.rst index 19dd8c31aa8..c937b1ac69f 100644 --- a/bundles.rst +++ b/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 `. 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/" } } } diff --git a/bundles/configuration.rst b/bundles/configuration.rst index 4a2224429ed..c155fe8a56a 100644 --- a/bundles/configuration.rst +++ b/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/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() ` @@ -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'; } } diff --git a/bundles/extension.rst b/bundles/extension.rst index 5c71fa18cfd..861c7b60807 100644 --- a/bundles/extension.rst +++ b/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\\**', // ... ]); diff --git a/templates.rst b/templates.rst index ba716427367..1373d671669 100644 --- a/templates.rst +++ b/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 -``/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 +``/vendor/acme/blog-bundle/Resources/views/user/profile.html.twig``, +you can refer to it as ``@AcmeBlog/user/profile.html.twig``. .. tip::