Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork5.3k
Promoting new bundle directory structure as best practice#14993
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.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Merged
Uh oh!
There was an error while loading.Please reload this page.
Merged
Changes fromall commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Jump to file
Failed to load files.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
107 changes: 68 additions & 39 deletionsbundles/best_practices.rst
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -68,30 +68,47 @@ The basic directory structure of an AcmeBlogBundle must read as follows: | ||
| .. code-block:: text | ||
| <your-bundle>/ | ||
| ├── config/ | ||
| ├── docs/ | ||
| │ └─ index.md | ||
| ├── public/ | ||
| ├── src/ | ||
| │ ├── Controller/ | ||
| │ ├── DependencyInjection/ | ||
| │ └── AcmeBlogBundle.php | ||
| ├── templates/ | ||
| ├── tests/ | ||
| ├── translations/ | ||
| ├── LICENSE | ||
| └── README.md | ||
| .. versionadded:: 4.4 | ||
| This directory convention was introduced in Symfony 4.4 and can be used only when requiring | ||
| ``symfony/http-kernel`` 4.4 or superior. | ||
| and the bundle path must be adjusted to the root directory:: | ||
| class AcmeBlogBundle extends Bundle | ||
| { | ||
| public function getPath(): string | ||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. BTW, should we deprecate not overriding this method, so that we can make this the default in sf 6.0? MemberAuthor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. I was wondering the same thing, I think we can do that when we decide to start depreciating the old structure. | ||
| { | ||
| 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); | ||
| * ``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``); | ||
| * ``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`_; | ||
| * ``docs/index.md``: The root file for the Bundle documentation. | ||
| The depth of subdirectories should be kept to a minimum for the most used | ||
| classes and files. Two levels is the maximum. | ||
| @@ -107,27 +124,27 @@ and others are just conventions followed by most developers): | ||
| =================================================== ======================================== | ||
| Type Directory | ||
| =================================================== ======================================== | ||
| Commands ``src/Command/`` | ||
| Controllers ``src/Controller/`` | ||
| Service Container Extensions ``src/DependencyInjection/`` | ||
| Doctrine ORM entities (when not using annotations) ``src/Entity/`` | ||
| Doctrine ODM documents (when not using annotations) ``src/Document/`` | ||
| Event Listeners ``src/EventListener/`` | ||
| Configuration (routes, services, etc.) ``config/`` | ||
| Web Assets (CSS, JS, images) ``public/`` | ||
| Translation files ``translations/`` | ||
| Validation (when not using annotations) ``config/validation/`` | ||
| Serialization (when not using annotations) ``config/serialization/`` | ||
| Templates ``templates/`` | ||
| Unit and Functional Tests ``tests/`` | ||
| =================================================== ======================================== | ||
| 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 :doc:`Symfony coding standards </contributing/code/standards>`. | ||
| @@ -153,7 +170,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 test suite must be executable with a simple ``phpunit`` command run from | ||
| a sample application; | ||
| @@ -240,10 +257,10 @@ 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 | ||
| :doc:`reStructuredText (rST) </contributing/documentation/format>` is the format | ||
| used to render the documentation on the Symfony website. | ||
| @@ -480,10 +497,22 @@ The ``composer.json`` file should include at least the following metadata: | ||
| 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: | ||
| .. code-block:: json | ||
| { | ||
| "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. | ||
| @@ -493,15 +522,15 @@ 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 :ref:`http-kernel-resource-locator` | ||
| 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 theAcmeBlogBundle, is referenced as ``@AcmeBlog/Default/index.html.twig``. | ||
| Learn more | ||
| ---------- | ||
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.