Skip to content

Updated Bundles Best Practices for Symfony 4 #8616

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 16, 2017
Merged

Updated Bundles Best Practices for Symfony 4 #8616

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7f00345
Updated Bundles Best Practices for Symfony 4
javiereguiluz Nov 10, 2017
1f433da
Fixed a missing reference
javiereguiluz Nov 10, 2017
9e6d75d
Fixes by reviewers
javiereguiluz Nov 16, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 59 additions & 42 deletions bundles/best_practices.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems way to strict and unwanted in my opinion. You only need to add a flex recipe if you need logic to be executed when installing your bundle. Otherwise, type: symfony-bundle is enough to have auto registration.

We shouldn't want to have many empty manifests in the contrib repository.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. How about:

Bundles should set ``"type": "symfony-bundle"`` in their ``composer.json`` file. With this,
`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 `Flex recipe`_.

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) </contributing/documentation/format>` is the format
used to render the documentation on symfony.com.

Expand All @@ -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 <package-name>
```

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:
Expand All @@ -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:
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have to use bash here, as terminal is a special Symfony docs only lexer.


$ composer require <package-name>

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:
Expand All @@ -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:
Expand Down Expand Up @@ -422,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.
Expand All @@ -450,8 +467,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/
Expand Down