Merge branch '4.0' into 4.1

* 4.0:
  Improved the front controller of the HttpCache
  Better docs about overriding third-party translations
  event constant mistake
  Updated the default values of some Cache config options
  add legacy labels
  Update Best Practices about service config format
  Update simple-example.rst to use const for jQuery
  Update shared-entry.rst to use Bootstrap 4's SCSS
  Removed an extra blank line
  Reword and added a note
  Link to proxy configuration docs from the routing scheme page
  Fixed typos
  Fixed security expression testing user
  Update messenger.rst
  Fix a configuration block in the Doctrine Associations page
  Fix numbering
  Mentioned Debian explicitly

Author: javiereguiluz

best_practices/business-logic.rst

@@ -96,11 +96,13 @@ all services are private by default.
 Service Format: YAML
 --------------------
 
-In the previous section, YAML was used to define the service.
+If you use the :ref:`default services.yaml configuration <service-container-services-load-example>`,
+most services will be configured automatically. However, in some edge cases
+you'll need to configure services (or parts of them) manually.
 
 .. best-practice::
 
-    Use the YAML format to define your own services.
+    Use the YAML format to configure your own services.
 
 This is controversial, and in our experience, YAML and XML usage is evenly
 distributed among developers, with a slight preference towards YAML.

bundles/override.rst

@@ -149,8 +149,12 @@ instead of the original ones.
 Translations
 ------------
 
-Translations are not related to bundles, but to domains. That means that you
-can override the translations from any translation file, as long as it is in
-:ref:`the correct domain <using-message-domains>`.
+Translations are not related to bundles, but to :ref:`translation domains <using-message-domains>`.
+For this reason, you can override any bundle translation file from the main
+``translations/`` directory, as long as the new file uses the same domain.
+
+For example, to override the translations defined in the
+``Resources/translations/FOSUserBundle.es.yml`` file of the FOSUserBundle,
+create a``<your-project>/translations/FOSUserBundle.es.yml`` file.
 
 .. _`the Doctrine documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/inheritance-mapping.html#overrides

components/cache/adapters/chain_adapter.rst

@@ -46,7 +46,7 @@ slowest storage engines, :class:`Symfony\\Component\\Cache\\Adapter\\ApcuAdapter
     ));
 
 When calling this adapter's :method:`Symfony\\Component\\Cache\\ChainAdapter::prune` method,
-the call is deligated to all its compatibe cache adapters. It is safe to mix both adapters
+the call is delegated to all its compatible cache adapters. It is safe to mix both adapters
 that *do* and do *not* implement :class:`Symfony\\Component\\Cache\\PruneableInterface`, as
 incompatible adapters are silently ignored::
 

components/cache/cache_pools.rst

@@ -160,18 +160,18 @@ Pruning Cache Items
 -------------------
 
 Some cache pools do not include an automated mechanism for pruning expired cache items.
-For example, the :ref:`FilesystemAdaper <component-cache-filesystem-adapter>` cache
+For example, the :ref:`FilesystemAdapter <component-cache-filesystem-adapter>` cache
 does not remove expired cache items *until an item is explicitly requested and determined to
 be expired*, for example, via a call to ``Psr\\Cache\\CacheItemPoolInterface::getItem``.
 Under certain workloads, this can cause stale cache entries to persist well past their
 expiration, resulting in a sizable consumption of wasted disk or memory space from excess,
 expired cache items.
 
-This shortcomming has been solved through the introduction of
+This shortcoming has been solved through the introduction of
 :class:`Symfony\\Component\\Cache\\PruneableInterface`, which defines the abstract method
 :method:`Symfony\\Component\\Cache\\PruneableInterface::prune`. The
 :ref:`ChainAdapter <component-cache-chain-adapter>`,
-:ref:`FilesystemAdaper <component-cache-filesystem-adapter>`,
+:ref:`FilesystemAdapter <component-cache-filesystem-adapter>`,
 :ref:`PdoAdapter <pdo-doctrine-adapter>`, and
 :ref:`PhpFilesAdapter <component-cache-files-adapter>` all implement this new interface,
 allowing manual removal of stale cache items::
@@ -185,7 +185,7 @@ allowing manual removal of stale cache items::
 The :ref:`ChainAdapter <component-cache-chain-adapter>` implementation does not directly
 contain any pruning logic itself. Instead, when calling the chain adapter's
 :method:`Symfony\\Component\\Cache\\ChainAdapter::prune` method, the call is delegated to all
-its compatibe cache adapters (and those that do not implement ``PruneableInterface`` are
+its compatible cache adapters (and those that do not implement ``PruneableInterface`` are
 silently ignored)::
 
     use Symfony\Component\Cache\Adapter\ApcuAdapter;

components/console/events.rst

@@ -149,7 +149,7 @@ Listeners receive a
 .. tip::
 
     This event is also dispatched when an exception is thrown by the command.
-    It is then dispatched just after the ``ConsoleEvents::EXCEPTION`` event.
+    It is then dispatched just after the ``ConsoleEvents::ERROR`` event.
     The exit code received in this case is the exception code.
 
 .. _`reserved exit codes`: http://www.tldp.org/LDP/abs/html/exitcodes.html

components/http_foundation/session_configuration.rst

@@ -166,8 +166,8 @@ the ``php.ini`` directive ``session.gc_maxlifetime``. The meaning in this contex
 that any stored session that was saved more than ``gc_maxlifetime`` ago should be
 deleted. This allows one to expire records based on idle time.
 
-However, some operating systems do their own session handling and set the
-``session.gc_probability`` variable to ``0`` to stop PHP doing garbage
+However, some operating systems (e.g. Debian) do their own session handling and set
+the ``session.gc_probability`` variable to ``0`` to stop PHP doing garbage
 collection. That's why Symfony now overwrites this value to ``1``.
 
 If you wish to use the original value set in your ``php.ini``, add the following

components/messenger.rst

@@ -165,7 +165,7 @@ First, create your receiver::
        private $serializer;
        private $filePath;
 
-       public function __construct(SerializerInteface $serializer, string $filePath)
+       public function __construct(SerializerInterface $serializer, string $filePath)
        {
            $this->serializer = $serializer;
            $this->filePath = $filePath;

configuration/override_dir_structure.rst

@@ -129,6 +129,54 @@ own templates directory (or directories):
             ),
         ));
 
+Override the Translations Directory
+-----------------------------------
+
+If your translation files are not stored in the default ``translations/``
+directory, use the :ref:`framework.translator.paths <reference-translator-paths>`
+configuration option to define your own translations directory (or directories):
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/translation.yaml
+        framework:
+            translator:
+                # ...
+                paths: ["%kernel.project_dir%/i18n"]
+
+    .. code-block:: xml
+
+        <!-- config/packages/translation.xml -->
+        <?xml version="1.0" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:twig="http://symfony.com/schema/dic/twig"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/twig
+                http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+
+            <framework:config>
+                <framework:translator>
+                    <framework:path>%kernel.project_dir%/i18n</framework:path>
+                </framework:translator>
+            </framework:config>
+
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/translation.php
+        $container->loadFromExtension('framework', array(
+            'translator' => array(
+                'paths' => array(
+                    '%kernel.project_dir%/i18n',
+                ),
+            ),
+        ));
+
 .. _override-web-dir:
 .. _override-the-web-directory:
 

doctrine/associations.rst

@@ -200,9 +200,9 @@ This ``ManyToOne`` mapping is required. It tells Doctrine to use the ``category_
 column on the ``product`` table to relate each record in that table with
 a record in the ``category`` table.
 
-Next, since a *one* ``Category`` object will relate to *many* ``Product`` objects,
+Next, since *one* ``Category`` object will relate to *many* ``Product`` objects,
 the ``make:entity`` command *also* added a ``products`` property to the ``Category``
-class that will hold these objects::
+class that will hold these objects:
 
 .. configuration-block::
 

frontend/encore/legacy-apps.rst

@@ -19,7 +19,7 @@ Using Libraries that Expect jQuery to be Global
 Some legacy JavaScript applications use programming practices that don't play
 well with the new practices promoted by Webpack. The most common of these
 problems is using code (e.g. jQuery plugins) that assume that jQuery is already
-available via the the ``$`` or ``jQuery`` global variables. If those variables
+available via the ``$`` or ``jQuery`` global variables. If those variables
 are not defined, you'll get these errors:
 
 .. code-block:: text