Skip to content

[Bundles] Improve the wording about mapping best practices #15849

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 1 commit into from
Oct 22, 2021
Merged

[Bundles] Improve the wording about mapping best practices #15849

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
11 changes: 7 additions & 4 deletions best_practices.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,17 +194,20 @@ you'll need to configure services (or parts of them) manually.
YAML is the format recommended to configure services because it's friendly to
newcomers and concise, but Symfony also supports XML and PHP configuration.

Use Annotations to Define the Doctrine Entity Mapping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use Attributes to Define the Doctrine Entity Mapping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Doctrine entities are plain PHP objects that you store in some "database".
Doctrine only knows about your entities through the mapping metadata configured
for your model classes.

Doctrine supports several metadata formats, but it's recommended to use
annotations because they are by far the most convenient and agile way of setting
Doctrine supports several metadata formats, but it's recommended to use PHP
attributes because they are by far the most convenient and agile way of setting
up and looking for mapping information.

If your PHP version doesn't support attributes yet, use annotations, which is
similar but requires installing some extra dependencies in your project.

Controllers
-----------

Expand Down
13 changes: 11 additions & 2 deletions bundles/best_practices.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,8 +123,8 @@ 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/``
Doctrine ORM entities ``src/Entity/``
Doctrine ODM documents ``src/Document/``
Event Listeners ``src/EventListener/``
Configuration (routes, services, etc.) ``config/``
Web Assets (CSS, JS, images) ``public/``
Expand Down Expand Up @@ -162,6 +162,15 @@ 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
:doc:`standard Symfony mechanism to override bundle parts </bundles/override>`.
This is not possible when using annotations/attributes to define the mapping.

Tests
-----

Expand Down