- {% block body %}{% endblock %}
-
- {% if self.comments()|trim %}
-
- {% block comments %}{% endblock %}
-
- {% endif%}
- 
++ + Online version + + | + + Components + + | + + Screencasts + +
+ +Contributing +------------ + +We love contributors! For more information on how you can contribute, please read +the [Symfony Docs Contributing Guide](https://symfony.com/doc/current/contributing/documentation/overview.html). + +> [!IMPORTANT] +> Use `6.4` branch as the base of your pull requests, unless you are documenting a +> feature that was introduced *after* Symfony 6.4 (e.g. in Symfony 7.2). + +Build Documentation Locally +--------------------------- + +This is not needed for contributing, but it's useful if you would like to debug some +issue in the docs or if you want to read Symfony Documentation offline. + +```bash +$ git clone git@github.com:symfony/symfony-docs.git + +$ cd symfony-docs/ +$ cd _build/ + +$ composer install + +$ php build.php +``` + +After generating docs, serve them with the internal PHP server: + +```bash +$ php -S localhost:8000 -t output/ +``` + +Browse `http://localhost:8000` to read the docs. diff --git a/_build/.requirements.txt b/_build/.requirements.txt deleted file mode 100644 index 430bce090b0..00000000000 --- a/_build/.requirements.txt +++ /dev/null @@ -1,13 +0,0 @@ -alabaster==0.7.10 -Babel==2.4.0 -docutils==0.13.1 -imagesize==0.7.1 -Jinja2==2.9.6 -MarkupSafe==1.0 -Pygments==2.2.0 -pytz==2017.2 -requests==2.20.0 -six==1.10.0 -snowballstemmer==1.2.1 -Sphinx==1.3.6 -git+https://github.com/fabpot/sphinx-php.git@7312eccce9465640752e51373a480da700e02345#egg_name=sphinx-php diff --git a/_build/Makefile b/_build/Makefile deleted file mode 100644 index 25b660056fe..00000000000 --- a/_build/Makefile +++ /dev/null @@ -1,153 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = . - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -c $(BUILDDIR) -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) ../ -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make{{ _('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.') }}
- {% endif %} - {% endif %} -{{ context|e }}
-- Displaying the {{ constant('NUMBER_OF_ITEMS', post) }} most recent results. -
- -And Doctrine entities and repositories can now easily access these values, -whereas they cannot access the container parameters:: - - namespace App\Repository; - - use App\Entity\Post; - use Doctrine\ORM\EntityRepository; - - class PostRepository extends EntityRepository - { - public function findLatest($limit = Post::NUMBER_OF_ITEMS) - { - // ... - } - } - -The only notable disadvantage of using constants for this kind of configuration -values is that you cannot redefine them easily in your tests. - -Parameter Naming ----------------- - -.. best-practice:: - - The name of your configuration parameters should be as short as possible and - should include a common prefix for the entire application. - -Using ``app.`` as the prefix of your parameters is a common practice to avoid -collisions with Symfony and third-party bundles/libraries parameters. Then, use -just one or two words to describe the purpose of the parameter: - -.. code-block:: yaml - - # config/services.yaml - parameters: - # don't do this: 'dir' is too generic and it doesn't convey any meaning - app.dir: '...' - # do this: short but easy to understand names - app.contents_dir: '...' - # it's OK to use dots, underscores, dashes or nothing, but always - # be consistent and use the same format for all the parameters - app.dir.contents: '...' - app.contents-dir: '...' - ----- - -Next: :doc:`/best_practices/business-logic` - -.. _`feature toggles`: https://en.wikipedia.org/wiki/Feature_toggle -.. _`constant() function`: https://twig.symfony.com/doc/2.x/functions/constant.html diff --git a/best_practices/controllers.rst b/best_practices/controllers.rst deleted file mode 100644 index 0ef6fd1d3bc..00000000000 --- a/best_practices/controllers.rst +++ /dev/null @@ -1,236 +0,0 @@ -Controllers -=========== - -Symfony follows the philosophy of *"thin controllers and fat models"*. This -means that controllers should hold just the thin layer of *glue-code* -needed to coordinate the different parts of the application. - -Your controller methods should just call to other services, trigger some events -if needed and then return a response, but they should not contain any actual -business logic. If they do, refactor it out of the controller and into a service. - -.. best-practice:: - - Make your controller extend the ``AbstractController`` base controller - provided by Symfony and use annotations to configure routing, caching and - security whenever possible. - -Coupling the controllers to the underlying framework allows you to leverage -all of its features and increases your productivity. - -And since your controllers should be thin and contain nothing more than a -few lines of *glue-code*, spending hours trying to decouple them from your -framework doesn't benefit you in the long run. The amount of time *wasted* -isn't worth the benefit. - -In addition, using annotations for routing, caching and security simplifies -configuration. You don't need to browse tens of files created with different -formats (YAML, XML, PHP): all the configuration is just where you need it -and it only uses one format. - -Overall, this means you should aggressively decouple your business logic -from the framework while, at the same time, aggressively coupling your controllers -and routing *to* the framework in order to get the most out of it. - -Controller Action Naming ------------------------- - -.. best-practice:: - - Don't add the ``Action`` suffix to the methods of the controller actions. - -The first Symfony versions required that controller method names ended in -``Action`` (e.g. ``newAction()``, ``showAction()``). This suffix became optional -when annotations were introduced for controllers. In modern Symfony applications -this suffix is neither required nor recommended, so you can safely remove it. - -Routing Configuration ---------------------- - -To load routes defined as annotations in your controllers, add the following -configuration to the main routing configuration file: - -.. code-block:: yaml - - # config/routes.yaml - controllers: - resource: '../src/Controller/' - type: annotation - -This configuration will load annotations from any controller stored inside the -``src/Controller/`` directory and even from its subdirectories. So if your application -defines lots of controllers, it's perfectly ok to reorganize them into subdirectories: - -.. code-block:: text - -
+
This practice is no longer recommended unless the web application is extremely
simple. Hardcoding URLs can be a disadvantage because:
@@ -30,7 +26,7 @@ simple. Hardcoding URLs can be a disadvantage because:
is essential for some applications because it allows you to control how
the assets are cached. The Asset component allows you to define different
versioning strategies for each package;
-* **Moving assets location** is cumbersome and error-prone: it requires you to
+* **Moving assets' location** is cumbersome and error-prone: it requires you to
carefully update the URLs of all assets included in all templates. The Asset
component allows to move assets effortlessly just by changing the base path
value associated with the package of assets;
@@ -46,13 +42,13 @@ Installation
$ composer require symfony/asset
-Alternatively, you can clone the `