Skip to content
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

Reviewed the Bundles cookbook articles #5095

Merged
merged 5 commits into from
Jun 9, 2015
Merged

Reviewed the Bundles cookbook articles #5095

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8254761
Reviewed the Bundles cookbook articles
javiereguiluz Mar 19, 2015
3dd40b2
Fixed an internal link reference
javiereguiluz Mar 19, 2015
c0637b6
Implemented the changes suggested by reviewers
javiereguiluz Mar 25, 2015
8861215
Replace phpDocumentor by the standard PHPDoc
javiereguiluz Mar 25, 2015
8008ac6
Implemented the suggestions made by Christian and Wouter
javiereguiluz May 29, 2015
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
47 changes: 19 additions & 28 deletions cookbook/bundles/best_practices.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
Best Practices for Reusable Bundles
===================================

There are 2 types of 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.
Expand All @@ -13,12 +13,8 @@ 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 book and cookbook.

.. seealso::

The best practices for application-specific bundles are discussed in
:doc:`/best_practices/introduction`.
the :doc:`book </book/index>`, the :doc:`cookbook </cookbook/index>` and the
:doc:`best practices </best_practices/index>` book.

.. index::
pair: Bundle; Naming conventions
Expand All @@ -38,7 +34,7 @@ bundle class name must follow these simple rules:

* Use only alphanumeric characters and underscores;
* Use a CamelCased name;
* Use a descriptive and short name (no more than 2 words);
* Use a descriptive and short name (no more than two words);
* Prefix the name with the concatenation of the vendor (and optionally the
category namespaces);
* Suffix the name with ``Bundle``.
Expand Down Expand Up @@ -112,7 +108,7 @@ The following files are mandatory:
structure to work.

The depth of sub-directories should be kept to the minimal for most used
classes and files (2 levels at a maximum). More levels can be defined for
classes and files (two levels at a maximum). More levels can be defined for
non-strategic, less-used files.

The bundle directory is read-only. If you need to write temporary files, store
Expand Down Expand Up @@ -158,7 +154,7 @@ instance, a ``HelloController`` controller is stored in
``Bundle/HelloBundle/Controller/HelloController.php`` and the fully qualified
class name is ``Bundle\HelloBundle\Controller\HelloController``.

All classes and files must follow the Symfony coding :doc:`standards </contributing/code/standards>`.
All classes and files must follow the :doc:`Symfony coding standards </contributing/code/standards>`.

Some classes should be seen as facades and should be as short as possible, like
Commands, Helpers, Listeners, and Controllers.
Expand All @@ -181,7 +177,7 @@ Tests
-----

A bundle should come with a test suite written with PHPUnit and stored under
the ``Tests/`` directory. Tests should follow the following principles:
the ``Tests/`` directory. Tests should follow these principles:

* The test suite must be executable with a simple ``phpunit`` command run from
a sample application;
Expand All @@ -190,13 +186,14 @@ the ``Tests/`` directory. Tests should follow the following principles:
* The tests should cover at least 95% of the code base.

.. note::

A test suite must not contain ``AllTests.php`` scripts, but must rely on the
existence of a ``phpunit.xml.dist`` file.

Documentation
-------------

All classes and functions must come with full PHPDoc.
All classes and functions must be fully documented using `PHPDoc`_ tags.

Extensive documentation should also be provided in the
:doc:`reStructuredText </contributing/documentation/format>` format, under
Expand Down Expand Up @@ -306,8 +303,11 @@ following standardized instructions in your ``README.md`` file.

.. _`installation chapter`: https://getcomposer.org/doc/00-intro.md

This template assumes that your bundle is in its ``1.x`` version. If not, change
the ``"~1"`` installation version accordingly (``"~2"``, ``"~3"``, etc.)
The example above assumes that you are installing the latest stable version of
the bundle, where you don't have to provide the package version number
(e.g. ``composer require friendsofsymfony/user-bundle``). If the installation
instructions refer to some past bundle version or to some inestable version,
include the version constraint (e.g. ``composer require friendsofsymfony/user-bundle "~2.0@dev"``).

Optionally, you can add more installation steps (*Step 3*, *Step 4*, etc.) to
explain other required installation tasks, such as registering routes or
Expand All @@ -330,7 +330,8 @@ Translation Files
-----------------

If a bundle provides message translations, they must be defined in the XLIFF
format; the domain should be named after the bundle name (``bundle.hello``).
format; the :ref:`translation domain <using-message-domains>` should be named
after the bundle name (``bundle.hello``).

A bundle must not override existing messages from another bundle.

Expand Down Expand Up @@ -369,27 +370,17 @@ The end user can provide values in any configuration file:
// app/config/config.php
$container->setParameter('acme_hello.email.from', '[email protected]');

.. code-block:: ini

; app/config/config.ini
[parameters]
acme_hello.email.from = [email protected]

Retrieve the configuration parameters in your code from the container::

$container->getParameter('acme_hello.email.from');

Even if this mechanism is simple enough, you are highly encouraged to use the
semantic configuration described in the cookbook.
:doc:`semantic bundle configuration </cookbook/bundles/extension>` instead.

.. note::

If you are defining services, they should also be prefixed with the bundle
alias.

Learn more from the Cookbook
----------------------------

* :doc:`/cookbook/bundles/extension`

.. _standards: http://www.php-fig.org/psr/psr-4/
.. _`standards`: http://www.php-fig.org/psr/psr-0/
.. _`PHPDoc`: https://en.wikipedia.org/wiki/PHPDoc
8 changes: 4 additions & 4 deletions cookbook/bundles/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ How to Create Friendly Configuration for a Bundle
=================================================

If you open your application configuration file (usually ``app/config/config.yml``),
you'll see a number of different configuration "namespaces", such as ``framework``,
you'll see a number of different configuration sections, such as ``framework``,
``twig`` and ``doctrine``. Each of these configures a specific bundle, allowing
you to configure things at a high level and then let the bundle make all the
you to define options at a high level and then let the bundle make all the
low-level, complex changes based on your settings.

For example, the following tells the FrameworkBundle to enable the form
integration, which involves the definition of quite a few services as well
For example, the following configuration tells the FrameworkBundle to enable the
form integration, which involves the definition of quite a few services as well
as integration of other related components:

.. configuration-block::
Expand Down
4 changes: 2 additions & 2 deletions cookbook/bundles/extension.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ How to Load Service Configuration inside a Bundle
=================================================

In Symfony, you'll find yourself using many services. These services can be
registered in the `app/config` directory of your application. But when you
registered in the ``app/config/`` directory of your application. But when you
want to decouple the bundle for use in other projects, you want to include the
service configuration in the bundle itself. This article will teach you how to
do that.
Expand All @@ -15,7 +15,7 @@ Creating an Extension Class
---------------------------

In order to load service configuration, you have to create a Dependency
Injection Extension for your bundle. This class has some conventions in order
Injection (DI) Extension for your bundle. This class has some conventions in order
Copy link
Member

Choose a reason for hiding this comment

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

I don't really get why this change is usefull

Copy link
Member Author

Choose a reason for hiding this comment

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

A good practice when using acronyms is to introduce them properly before the first time they are used. In this article, we talk about Dependency Injection and suddenly, the article talks about DI. I know that Symfony developers are smart enough to infere that DI means Dependency Injection, but the usual good practice is to show the full words + its acronym just before starting to use the acronym exclusively.

Copy link
Member

Choose a reason for hiding this comment

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

We could also just avoid using DI in the docs (which imho were a better practice). But as long as we use them it's imho indeed a good idea to introduce it properly.

to be detected automatically. But you'll later see how you can change it to
your own preferences. By default, the Extension has to comply with the
following conventions:
Expand Down
24 changes: 12 additions & 12 deletions cookbook/bundles/inheritance.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,16 +12,16 @@ things like controllers, templates, and other files in a bundle's

For example, suppose that you're installing the `FOSUserBundle`_, but you
want to override its base ``layout.html.twig`` template, as well as one of
its controllers. Suppose also that you have your own AcmeUserBundle
where you want the overridden files to live. Start by registering the FOSUserBundle
as the "parent" of your bundle::
its controllers. Suppose also that you have your own UserBundle where you want
the overridden files to live. Start by registering the FOSUserBundle as the
"parent" of your bundle::

// src/Acme/UserBundle/AcmeUserBundle.php
namespace Acme\UserBundle;
// src/UserBundle/UserBundle.php
namespace UserBundle;

use Symfony\Component\HttpKernel\Bundle\Bundle;

class AcmeUserBundle extends Bundle
class UserBundle extends Bundle
{
public function getParent()
{
Expand All @@ -45,8 +45,8 @@ Suppose you want to add some functionality to the ``registerAction`` of a
just create your own ``RegistrationController.php`` file, override the bundle's
original method, and change its functionality::

// src/Acme/UserBundle/Controller/RegistrationController.php
namespace Acme\UserBundle\Controller;
// src/UserBundle/Controller/RegistrationController.php
namespace UserBundle\Controller;

use FOS\UserBundle\Controller\RegistrationController as BaseController;

Expand Down Expand Up @@ -82,17 +82,17 @@ location as your parent bundle.
For example, it's very common to need to override the FOSUserBundle's
``layout.html.twig`` template so that it uses your application's base layout.
Since the file lives at ``Resources/views/layout.html.twig`` in the FOSUserBundle,
you can create your own file in the same location of AcmeUserBundle.
Symfony will ignore the file that lives inside the FOSUserBundle entirely,
and use your file instead.
you can create your own file in the same location of UserBundle. Symfony will
ignore the file that lives inside the FOSUserBundle entirely, and use your file
instead.

The same goes for routing files and some other resources.

.. note::

The overriding of resources only works when you refer to resources with
the ``@FOSUserBundle/Resources/config/routing/security.xml`` method.
If you refer to resources without using the @BundleName shortcut, they
If you refer to resources without using the ``@BundleName`` shortcut, they
can't be overridden in this way.

.. caution::
Expand Down
54 changes: 41 additions & 13 deletions cookbook/bundles/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,16 +15,16 @@ A) Add Composer Dependencies
----------------------------

Dependencies are managed with Composer, so if Composer is new to you, learn
some basics in `their documentation`_. This has 2 steps:
some basics in `their documentation`_. This involves two steps:

1) Find out the Name of the Bundle on Packagist
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The README for a bundle (e.g. `FOSUserBundle`_) usually tells you its name
(e.g. ``friendsofsymfony/user-bundle``). If it doesn't, you can search for
the library on the `Packagist.org`_ site.
the bundle on the `Packagist.org`_ site.

.. note::
.. tip::

Looking for bundles? Try searching at `KnpBundles.com`_: the unofficial
archive of Symfony Bundles.
Expand All @@ -39,9 +39,12 @@ Now that you know the package name, you can install it via Composer:
$ composer require friendsofsymfony/user-bundle

This will choose the best version for your project, add it to ``composer.json``
and download the library into the ``vendor/`` directory. If you need a specific
version, add a ``:`` and the version right after the library name (see
`composer require`_).
and download its code into the ``vendor/`` directory. If you need a specific
version, include it as the second argument of the `composer require`_ command:

.. code-block:: bash

$ composer require friendsofsymfony/user-bundle "~2.0"

B) Enable the Bundle
--------------------
Expand All @@ -60,30 +63,55 @@ The only thing you need to do now is register the bundle in ``AppKernel``::
public function registerBundles()
{
$bundles = array(
// ...,
// ...
new FOS\UserBundle\FOSUserBundle(),
);

// ...
}
}

By default, Symfony bundles are registered in all the application
:doc:`execution environments </cookbook/configuration/environments>`. If the bundle
is meant to be used only in some environment, register it within an ``if`` statement,
like the following example, where the FOSUserBundle is only enabled for the
``dev`` and ``test`` environments::

// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
// ...

public function registerBundles()
{
$bundles = array(
// ...
);

if (in_array($this->getEnvironment(), array('dev', 'test'))) {
$bundles[] = new FOS\UserBundle\FOSUserBundle();
}

// ...
}
}

C) Configure the Bundle
-----------------------

It's pretty common for a bundle to need some additional setup or configuration
in ``app/config/config.yml``. The bundle's documentation will tell you about
the configuration, but you can also get a reference of the bundle's config
via the ``config:dump-reference`` command.

For instance, in order to look the reference of the ``assetic`` config you
can use this:
the configuration, but you can also get a reference of the bundle's configuration
via the ``config:dump-reference`` command:

.. code-block:: bash

$ app/console config:dump-reference AsseticBundle

or this:
Instead of the full bundle name, you can also pass the short name used as the root
of the bundle's configuration:

.. code-block:: bash

Expand Down