From 7f003459e34a294008e5d29e9db0b1d5b3627d3e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 10 Nov 2017 12:12:40 +0100 Subject: [PATCH 1/3] Updated Bundles Best Practices for Symfony 4 --- bundles/best_practices.rst | 96 ++++++++++++++++++++++---------------- 1 file changed, 57 insertions(+), 39 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 5381acd5951..e75c4c8d48c 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -4,21 +4,10 @@ Best Practices for Reusable Bundles =================================== -There are two types of bundles: - -* Application-specific bundles: only used to build your application; -* Reusable bundles: meant to be shared across many projects. - This article is all about how to structure your **reusable bundles** so that -they're easy to configure and extend. Many of these recommendations do not -apply to application bundles because you'll want to keep those as simple -as possible. For application bundles, just follow the practices shown throughout -the guides. - -.. seealso:: - - The best practices for application-specific bundles are discussed in - :doc:`/best_practices/introduction`. +they're easy to configure and extend. Reusable bundles are those meant to be +shared privately across many company projects or publicly so any Symfony project +can install them. .. index:: pair: Bundle; Naming conventions @@ -28,10 +17,10 @@ the guides. Bundle Name ----------- -A bundle is also a PHP namespace. The namespace must follow the `PSR-0`_ or -`PSR-4`_ interoperability standards for PHP namespaces and class names: it starts -with a vendor segment, followed by zero or more category segments, and it ends -with the namespace short name, which must end with ``Bundle``. +A bundle is also a PHP namespace. The namespace must follow the `PSR-4`_ +interoperability standard for PHP namespaces and class names: it starts with a +vendor segment, followed by zero or more category segments, and it ends with the +namespace short name, which must end with ``Bundle``. A namespace becomes a bundle as soon as you add a bundle class to it. The bundle class name must follow these simple rules: @@ -116,21 +105,21 @@ The following classes and files have specific emplacements (some are mandatory and others are just conventions followed by most developers): =================================================== ======================================== -Type Directory +Type Directory =================================================== ======================================== -Commands ``Command/`` -Controllers ``Controller/`` -Service Container Extensions ``DependencyInjection/`` +Commands ``Command/`` +Controllers ``Controller/`` +Service Container Extensions ``DependencyInjection/`` Doctrine ORM entities (when not using annotations) ``Entity/`` Doctrine ODM documents (when not using annotations) ``Document/`` -Event Listeners ``EventListener/`` -Configuration ``Resources/config/`` -Web Resources (CSS, JS, images) ``Resources/public/`` -Translation files ``Resources/translations/`` +Event Listeners ``EventListener/`` +Configuration (routes, services, etc.) ``Resources/config/`` +Web Assets (CSS, JS, images) ``Resources/public/`` +Translation files ``Resources/translations/`` Validation (when not using annotations) ``Resources/config/validation/`` Serialization (when not using annotations) ``Resources/config/serialization/`` -Templates ``Resources/views/`` -Unit and Functional Tests ``Tests/`` +Templates ``Resources/views/`` +Unit and Functional Tests ``Tests/`` =================================================== ======================================== Classes @@ -177,16 +166,23 @@ the ``Tests/`` directory. Tests should follow the following principles: A test suite must not contain ``AllTests.php`` scripts, but must rely on the existence of a ``phpunit.xml.dist`` file. +Installation +------------ + +Bundles must define a `Symfony Flex recipe`_ to automate their integration +in Symfony applications. If some initial configuration is needed to execute +the bundle, including some environment variables, provide them in the recipe. + Documentation ------------- All classes and functions must come with full PHPDoc. -Extensive documentation should also be provided in the ``Resources/doc/`` +Extensive documentation should also be provided in the ``Resources/doc/`` directory. -The index file (for example ``Resources/doc/index.rst`` or -``Resources/doc/index.md``) is the only mandatory file and must be the entry -point for the documentation. The +The index file (for example ``Resources/doc/index.rst`` or +``Resources/doc/index.md``) is the only mandatory file and must be the entry +point for the documentation. The :doc:`reStructuredText (rST) ` is the format used to render the documentation on symfony.com. @@ -203,8 +199,19 @@ following standardized instructions in your ``README.md`` file. Installation ============ - Step 1: Download the Bundle - --------------------------- + Applications that use Symfony Flex + ---------------------------------- + + Open a command console, enter your project directory and execute: + + ```console + $ composer require + ``` + + Applications that don't use Symfony Flex + ---------------------------------------- + + ### Step 1: Download the Bundle Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle: @@ -217,8 +224,7 @@ following standardized instructions in your ``README.md`` file. in the [installation chapter](https://getcomposer.org/doc/00-intro.md) of the Composer documentation. - Step 2: Enable the Bundle - ------------------------- + ### Step 2: Enable the Bundle Then, enable the bundle by adding it to the list of registered bundles in the `app/AppKernel.php` file of your project: @@ -249,8 +255,20 @@ following standardized instructions in your ``README.md`` file. Installation ============ + Applications that use Symfony Flex + ---------------------------------- + + Open a command console, enter your project directory and execute: + + .. code-block:: terminal + + $ composer require + + Applications that don't use Symfony Flex + ---------------------------------------- + Step 1: Download the Bundle - --------------------------- + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle: @@ -263,7 +281,7 @@ following standardized instructions in your ``README.md`` file. in the `installation chapter`_ of the Composer documentation. Step 2: Enable the Bundle - ------------------------- + ~~~~~~~~~~~~~~~~~~~~~~~~~ Then, enable the bundle by adding it to the list of registered bundles in the ``app/AppKernel.php`` file of your project: @@ -450,8 +468,8 @@ Learn more * :doc:`/bundles/extension` * :doc:`/bundles/configuration` -.. _`PSR-0`: http://www.php-fig.org/psr/psr-0/ .. _`PSR-4`: http://www.php-fig.org/psr/psr-4/ +.. _`Symfony Flex recipe`: https://github.com/symfony/recipes .. _`Semantic Versioning Standard`: http://semver.org/ .. _`Packagist`: https://packagist.org/ .. _`choose any license`: http://choosealicense.com/ From 1f433dae6bbb489539330d353600143f7e2a1dc6 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 10 Nov 2017 14:51:50 +0100 Subject: [PATCH 2/3] Fixed a missing reference --- bundles/best_practices.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index e75c4c8d48c..553523aeacf 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -440,9 +440,8 @@ The ``composer.json`` file should include at least the following metadata: a string (or array of strings) with a `valid license identifier`_, such as ``MIT``. ``autoload`` - This information is used by Symfony to load the classes of the bundle. The - `PSR-4`_ autoload standard is recommended for modern bundles, but `PSR-0`_ - standard is also supported. + This information is used by Symfony to load the classes of the bundle. It's + recommended to use the `PSR-4`_ autoload standard. In order to make it easier for developers to find your bundle, register it on `Packagist`_, the official repository for Composer packages. From 9e6d75d2f71aae78c02b6b9204d928fdc03425ca Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 16 Nov 2017 15:21:58 +0100 Subject: [PATCH 3/3] Fixes by reviewers --- bundles/best_practices.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 553523aeacf..2e997beefe8 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -169,9 +169,12 @@ the ``Tests/`` directory. Tests should follow the following principles: Installation ------------ -Bundles must define a `Symfony Flex recipe`_ to automate their integration -in Symfony applications. If some initial configuration is needed to execute -the bundle, including some environment variables, provide them in the recipe. +Bundles should set ``"type": "symfony-bundle"`` in their ``composer.json`` file. +With this, :doc:`Symfony Flex ` will be able to automatically +enable your bundle when it's installed. + +If your bundle requires any setup (e.g. configuration, new files, changes to +`.gitignore`, etc), then you should create a `Symfony Flex recipe`_. Documentation ------------- @@ -260,7 +263,7 @@ following standardized instructions in your ``README.md`` file. Open a command console, enter your project directory and execute: - .. code-block:: terminal + .. code-block:: bash $ composer require