Best Practices for Reusable Bundles ¶

Bundle Name ¶

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 (which is a class that extends Bundle). The bundle class name must follow these rules:

• Use only alphanumeric characters and underscores;
  英数字とアンダースコアのみを使用してください。
• Use a StudlyCaps name (i.e. camelCase with an uppercase first letter);
  StudlyCaps 名を使用します (つまり、最初の文字が大文字のキャメルケース)。
• Use a descriptive and short name (no more than two words);
  説明的で短い名前 (2 語以内) を使用してください。
• Prefix the name with the concatenation of the vendor (and optionally the category namespaces);
  名前の前にベンダー (およびオプションでカテゴリ名前空間) を連結したものを付けます。
• Suffix the name with Bundle.
  名前の末尾に Bundle を付けます。

Here are some valid bundle namespaces and class names:

By convention, the getName() method of the bundle class should return the class name.

Each bundle has an alias, which is the lower-cased short version of the bundle name using underscores (acme_blog for AcmeBlogBundle). This alias is used to enforce uniqueness within a project and for defining bundle's configuration options (see below for some usage examples).

Directory Structure ¶

The following is the recommended directory structure of an AcmeBlogBundle:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

/
├── config/
├── docs/
│   └─ index.md
├── public/
├── src/
│   ├── Controller/
│   ├── DependencyInjection/
│   └── AcmeBlogBundle.php
├── templates/
├── tests/
├── translations/
├── LICENSE
└── README.md

This directory structure requires to configure the bundle path to its root directory as follows:

1
2
3
4
5
6
7

class AcmeBlogBundle extends Bundle
{
    public function getPath(): string
    {
        return \dirname(__DIR__);
    }
}

The following files are mandatory, because they ensure a structure convention that automated tools can rely on:

• src/AcmeBlogBundle.php: This is the class that transforms a plain directory into a Symfony bundle (change this to your bundle's name);
  src/AcmeBlogBu​​ndle.php: これはプレーン ディレクトリを Symfony バンドルに変換するクラスです (これをバンドルの名前に変更します)。
• README.md: This file contains the basic description of the bundle and it usually shows some basic examples and links to its full documentation (it can use any of the markup formats supported by GitHub, such as README.rst);
  README.md: このファイルには、バンドルの基本的な説明が含まれており、通常、いくつかの基本的な例と完全なドキュメントへのリンクが示されています (README.rst など、GitHub でサポートされている任意のマークアップ形式を使用できます)。
• LICENSE: The full contents of the license used by the code. Most third-party bundles are published under the MIT license, but you can choose any license;
  LICENSE: コードで使用されるライセンスの完全な内容。ほとんどのサードパーティ バンドルは MIT ライセンスの下で公開されていますが、任意のライセンスを選択できます。
• docs/index.md: The root file for the Bundle documentation.
  docs/index.md: バンドル ドキュメントのルート ファイル。

The depth of subdirectories should be kept to a minimum for the most used classes and files. Two levels is the maximum.

The bundle directory is read-only. If you need to write temporary files, store them under the cache/ or log/ directory of the host application. Tools can generate files in the bundle directory structure, but only if the generated files are going to be part of the repository.

The following classes and files have specific emplacements (some are mandatory and others are just conventions followed by most developers):

Classes ¶

The bundle directory structure is used as the namespace hierarchy. For instance, a ContentController controller which is stored in src/Controller/ContentController.php would have the fully qualified class name of Acme\BlogBundle\Controller\ContentController.

All classes and files must follow the Symfony coding standards.

Some classes should be seen as facades and should be as short as possible, like Commands, Helpers, Listeners and Controllers.

Classes that connect to the event dispatcher should be suffixed with Listener.

Exception classes should be stored in an Exception sub-namespace.

Vendors ¶

A bundle must not embed third-party PHP libraries. It should rely on the standard Symfony autoloading instead.

A bundle should also not embed third-party libraries written in JavaScript, CSS or any other language.

Doctrine Entities/Documents ¶

If the bundle includes Doctrine ORM entities and/or ODM documents, it's recommended to define their mapping using XML files stored in Resources/config/doctrine/. This allows to override that mapping using the standard Symfony mechanism to override bundle parts. This is not possible when using annotations/attributes to define the mapping.

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 test suite must be executable with a simple phpunit command run from a sample application;
  テスト スイートは、サンプル アプリケーションから実行される単純な phpunit コマンドで実行可能である必要があります。
• The functional tests should only be used to test the response output and some profiling information if you have some;
  機能テストは、応答出力とプロファイリング情報 (ある場合) をテストするためにのみ使用する必要があります。
• The tests should cover at least 95% of the code base.
  テストは、コード ベースの少なくとも 95% をカバーする必要があります。

Continuous Integration ¶

Testing bundle code continuously, including all its commits and pull requests, is a good practice called Continuous Integration. There are several services providing this feature for free for open source projects, like GitHub Actions and Travis CI.

A bundle should at least test:

• The lower bound of their dependencies (by running composer update --prefer-lowest);
  依存関係の下限 (composer update --prefer-lowest を実行)。
• The supported PHP versions;
  サポートされている PHP バージョン。
• All supported major Symfony versions (e.g. both 4.x and 5.x if support is claimed for both).
  サポートされているすべての主要な Symfony バージョン (例: 4.x と 5.x の両方がサポートされている場合)。

Thus, a bundle supporting PHP 7.3, 7.4 and 8.0, and Symfony 4.4 and 5.x should have at least this test matrix:

1
2
3
4
5
6
7
8
9
10
11
12

# this requires Symfony 5.x for all Symfony packages
export SYMFONY_REQUIRE=5.*
# alternatively you can run this command to update composer.json config
# composer config extra.symfony.require "5.*"

# install Symfony Flex in the CI environment
composer global config --no-plugins allow-plugins.symfony/flex true
composer global require --no-progress --no-scripts --no-plugins symfony/flex

# install the dependencies (using --prefer-dist and --no-progress is
# recommended to have a better output and faster download time)
composer update --prefer-dist --no-progress

Installation ¶

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 Symfony Flex recipe.

Documentation ¶

All classes and functions must come with full PHPDoc.

Extensive documentation should also be provided in the docs/ directory. The index file (for example docs/index.rst or docs/index.md) is the only mandatory file and must be the entry point for the documentation. The reStructuredText (rST) is the format used to render the documentation on the Symfony website.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

Installation
============

Make sure Composer is installed globally, as explained in the
[installation chapter](https://getcomposer.org/doc/00-intro.md)
of the Composer documentation.

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:

```console
$ composer require <package-name>
```

### Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles
in the `config/bundles.php` file of your project:

```php
// config/bundles.php

return [
    // ...
    <vendor>\<bundle-name>\<bundle-long-name>::class => ['all' => true],
];
```

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

Installation
============

Make sure Composer is installed globally, as explained in the
`installation chapter`_ of the Composer documentation.

----------------------------------

Open a command console, enter your project directory and execute:

.. code-block:: bash

    $ 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:

.. code-block:: terminal

    $ composer require <package-name>

Step 2: Enable the Bundle
~~~~~~~~~~~~~~~~~~~~~~~~~

Then, enable the bundle by adding it to the list of registered bundles
in the ``config/bundles.php`` file of your project::

    // config/bundles.php
    return [
        // ...
        <vendor>\<bundle-name>\<bundle-long-name>::class => ['all' => true],
    ];

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

Routing ¶

If the bundle provides routes, they must be prefixed with the bundle alias. For example, if your bundle is called AcmeBlogBundle, all its routes must be prefixed with acme_blog_.

Templates ¶

If a bundle provides templates, they must use Twig. A bundle must not provide a main layout, except if it provides a full working application.

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 (acme_blog).

A bundle must not override existing messages from another bundle.

Configuration ¶

To provide more flexibility, a bundle can provide configurable settings by using the Symfony built-in mechanisms.

For simple configuration settings, rely on the default parameters entry of the Symfony configuration. Symfony parameters are simple key/value pairs; a value being any valid PHP value. Each parameter name should start with the bundle alias, though this is just a best-practice suggestion. The rest of the parameter name will use a period (.) to separate different parts (e.g. acme_blog.author.email).

The end user can provide values in any configuration file:

1
2
3

# config/services.yaml
parameters:
    acme_blog.author.email: 'fabien@example.com'

1
2
3
4
5
6
7
8
9
10
11
12

<!-- 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"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd"
>
    <parameters>
        <parameter key="acme_blog.author.email">fabien@example.com</parameter>
    </parameters>

</container>

1
2
3
4
5
6
7
8

// config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return static function (ContainerConfigurator $container) {
    $container->parameters()
        ->set('acme_blog.author.email', 'fabien@example.com')
    ;
};

Retrieve the configuration parameters in your code from the container:

1

$container->getParameter('acme_blog.author.email');

While this mechanism requires the least effort, you should consider using the more advanced semantic bundle configuration to make your configuration more robust.

Versioning ¶

Bundles must be versioned following the Semantic Versioning Standard.

Services ¶

If the bundle defines services, they must be prefixed with the bundle alias instead of using fully qualified class names like you do in your project services. For example, AcmeBlogBundle services must be prefixed with acme_blog. The reason is that bundles shouldn't rely on features such as service autowiring or autoconfiguration to not impose an overhead when compiling application services.

In addition, services not meant to be used by the application directly, should be defined as private. For public services, aliases should be created from the interface/class to the service id. For example, in MonologBundle, an alias is created from Psr\Log\LoggerInterface to logger so that the LoggerInterface type-hint can be used for autowiring.

Services should not use autowiring or autoconfiguration. Instead, all services should be defined explicitly.

Composer Metadata ¶

The composer.json file should include at least the following metadata:

name

Consists of the vendor and the short bundle name. If you are releasing the bundle on your own instead of on behalf of a company, use your personal name (e.g. johnsmith/blog-bundle). Exclude the vendor name from the bundle short name and separate each word with a hyphen. For example: AcmeBlogBundle is transformed into blog-bundle and AcmeSocialConnectBundle is transformed into social-connect-bundle.

ベンダーと短いバンドル名で構成されます。会社を代表するのではなく、自分でバンドルをリリースする場合は、個人名 (例: johnsmith/blog-bundle) を使用してください。 bundleshort 名からベンダー名を除外し、各単語をハイフンで区切ります。例: AcmeBlogBu​​ndle は blog-bundle に変換され、AcmeSocialConnectBundle は social-connect-bundle に変換されます。

description

A brief explanation of the purpose of the bundle.

バンドルの目的の簡単な説明。

type

Use the symfony-bundle value.

symfony-bundle 値を使用します。

license

a string (or array of strings) with a valid license identifier, such as MIT.

MIT などの有効なライセンス識別子を含む文字列 (または文字列の配列)。

autoload

This information is used by Symfony to load the classes of the bundle. It's recommended to use the PSR-4 autoload standard: use the namespace as key, and the location of the bundle's main class (relative to composer.json) as value. As the main class is located in the src/ directory of the bundle:

この情報は、バンドルのクラスをロードするために Symfony によって使用されます。 PSR-4 autoload 標準を使用することをお勧めします。名前空間をキーとして使用し、バンドルのメイン クラスの場所 (composer.json からの相対位置) を値として使用します。メインクラスはバンドルの src/ ディレクトリにあるため:

1 2 3 4 5 6 7 8 9 10 11 12

{ "autoload": { "psr-4": { "Acme\\BlogBundle\\": "src/" } }, "autoload-dev": { "psr-4": { "Acme\\BlogBundle\\Tests\\": "tests/" } } }

In order to make it easier for developers to find your bundle, register it on Packagist, the official repository for Composer packages.

Resources ¶

If the bundle references any resources (config files, translation files, etc.), don't use physical paths (e.g. __DIR__/config/services.xml) but logical paths (e.g. @AcmeBlogBundle/config/services.xml).

The logical paths are required because of the bundle overriding mechanism that lets you override any resource/file of any bundle. See The HttpKernel Component for more details about transforming physical paths into logical paths.

Beware that templates use a simplified version of the logical path shown above. For example, an index.html.twig template located in the templates/Default/ directory of the AcmeBlogBundle, is referenced as @AcmeBlog/Default/index.html.twig.

Learn more ¶

• How to Load Service Configuration inside a Bundle
  バンドル内にサービス構成をロードする方法
• How to Create Friendly Configuration for a Bundle
  バンドルのフレンドリ構成を作成する方法