minor #12354 Explain Symfony packs (javiereguiluz)

This PR was squashed before being merged into the 4.3 branch (closes #12354).

Discussion
----------

Explain Symfony packs

Fixes #12130.

Commits
-------

9d07ac3 Explain Symfony packs

Author: javiereguiluz

best_practices/business-logic.rst

@@ -123,9 +123,9 @@ library or strategy you want for this.
 In practice, many Symfony applications rely on the independent
 `Doctrine project`_ to define their model using entities and repositories.
 
-Doctrine support is not enabled by default in Symfony. So to use Doctrine
-as shown in the examples below you will need to install :doc:`Doctrine ORM support </doctrine>`
-by executing the following command:
+:doc:`Doctrine </doctrine>` support is not enabled by default in Symfony, so you
+must install it first by adding the ``orm`` :ref:`Symfony pack <symfony-packs>`
+to your application:
 
 .. code-block:: terminal
 

doctrine.rst

@@ -25,8 +25,8 @@ Databases are a broad topic, so the documentation is divided in three articles:
 Installing Doctrine
 -------------------
 
-First, install Doctrine support via the ORM pack, as well as the MakerBundle,
-which will help generate some code:
+First, install Doctrine support via the ``orm`` :ref:`Symfony pack <symfony-packs>`,
+as well as the MakerBundle, which will help generate some code:
 
 .. code-block:: terminal
 
@@ -570,8 +570,8 @@ the :ref:`doctrine-queries` section.
     If the number of database queries is too high, the icon will turn yellow to
     indicate that something may not be correct. Click on the icon to open the
     Symfony Profiler and see the exact queries that were executed. If you don't
-    see the web debug toolbar, try running ``composer require --dev symfony/profiler-pack``
-    to install it.
+    see the web debug toolbar, install the ``profiler`` :ref:`Symfony pack <symfony-packs>`
+    by running this command: ``composer require --dev symfony/profiler-pack``.
 
 Automatically Fetching Objects (ParamConverter)
 -----------------------------------------------

doctrine/dbal.rst

@@ -22,7 +22,7 @@ data manipulations.
     Read the official Doctrine `DBAL Documentation`_ to learn all the details
     and capabilities of Doctrine's DBAL library.
 
-First, install the Doctrine ORM pack:
+First, install the Doctrine ``orm`` :ref:`Symfony pack <symfony-packs>`:
 
 .. code-block:: terminal
 

page_creation.rst

@@ -182,8 +182,9 @@ The Web Debug Toolbar: Debugging Dream
 --------------------------------------
 
 One of Symfony's *killer* features is the Web Debug Toolbar: a bar that displays
-a *huge* amount of debugging information along the bottom of your page while developing. This is all
-included out of the box using a package called ``symfony/profiler-pack``.
+a *huge* amount of debugging information along the bottom of your page while
+developing. This is all included out of the box using a :ref:`Symfony pack <symfony-packs>`
+called ``symfony/profiler-pack``.
 
 You will see a black bar along the bottom of the page. You'll learn more about all the information it holds
 along the way, but feel free to experiment: hover over and click

profiler.rst

@@ -9,7 +9,7 @@ Installation
 ------------
 
 In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
-install the profiler before using it:
+install the ``profiler`` :ref:`Symfony pack <symfony-packs>` before using it:
 
 .. code-block:: terminal
 

quick_tour/flex_recipes.rst

@@ -181,9 +181,9 @@ But for a *truly* rich API, try installing `API Platform`_:
 
     $ composer require api
 
-This is an alias to ``api-platform/api-pack``, which has dependencies on several
-other packages, like Symfony's Validator and Security components, as well as the Doctrine
-ORM. In fact, Flex installed *5* recipes!
+This is an alias to ``api-platform/api-pack`` :ref:`Symfony pack <symfony-packs>`,
+which has dependencies on several other packages, like Symfony's Validator and
+Security components, as well as the Doctrine ORM. In fact, Flex installed *5* recipes!
 
 But like usual, we can immediately start using the new library. Want to create a
 rich API for a ``product`` table? Create a ``Product`` entity and give it the

serializer.rst

@@ -15,7 +15,7 @@ Installation
 ------------
 
 In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
-install the serializer before using it:
+install the ``serializer`` :ref:`Symfony pack <symfony-packs>` before using it:
 
 .. code-block:: terminal
 

setup.rst

@@ -179,6 +179,27 @@ two public repositories:
 Read the `Symfony Recipes documentation`_ to learn everything about how to
 create recipes for your own packages.
 
+.. _symfony-packs:
+
+Symfony Packs
+~~~~~~~~~~~~~
+
+Sometimes a single feature requires installing several packages and bundles.
+Instead of installing them individually, Symfony provides **packs**, which are
+Composer metapackages that include several dependencies.
+
+For example, to add debugging features in your application, you can run the
+``composer require --dev debug`` command. This installs the ``symfony/debug-pack``,
+which in turn installs several packages like ``symfony/debug-bundle``,
+``symfony/monolog-bundle``, ``"symfony/var-dumper"``, etc.
+
+By default, when installing Symfony packs, your ``composer.json`` file shows the
+pack dependency (e.g. ``"symfony/debug-pack": "^1.0"``) instead of the actual
+packages installed. To show the packages, add the ``--unpack`` option when
+installing a pack (e.g. ``composer require debug --dev --unpack``) or run this
+command to unpack the already installed packs: ``composer unpack PACK_NAME``
+(e.g. ``composer unpack debug``).
+
 .. _security-checker:
 
 Checking Security Vulnerabilities

setup/web_server_configuration.rst

@@ -35,13 +35,14 @@ to use PHP :ref:`with Nginx <web-server-nginx>`.
 Adding Rewrite Rules
 --------------------
 
-The easiest way is to install the Apache recipe by executing the following command:
+The easiest way is to install the ``apache`` :ref:`Symfony pack <symfony-packs>`
+by executing the following command:
 
 .. code-block:: terminal
 
     $ composer require symfony/apache-pack
 
-This recipe installs a ``.htaccess`` file in the ``public/`` directory that contains
+This pack installs a ``.htaccess`` file in the ``public/`` directory that contains
 the rewrite rules.
 
 .. tip::

testing.rst

@@ -278,7 +278,7 @@ document::
 .. tip::
 
     Instead of installing each testing dependency individually, you can use the
-    Symfony Test pack to install all those dependencies at once:
+    ``test`` :ref:`Symfony pack <symfony-packs>` to install all those dependencies at once:
 
     .. code-block:: terminal