Merge branch '3.4'

* 3.4: (34 commits)
  Removed a deprecated feature in a testing article
  Some fixes for testing/* articles in 2.7 docs
  A few tiny encore tweaks
  Fixed some issues in PHPUnit XML config examples
  Minor typos in session articles
  Removed a wrong note about controllers as services
  Removed lots of redundant contents
  fix typo
  Update micro_kernel_trait.rst
  Update micro_kernel_trait.rst
  [#8650] Minor rewording
  [#8649] Small reword
  Improved the link to the Symfony events reference
  Minor fixes for upload_file.rst
  added commas for php code section
  [Workflow] minor tweaks
  Fixed a typo
  Fix minor typo
  Added getSubscribedEvents() to UserLocaleSubscriber
  [Config] Add missing paranthesis of `arrayPrototype` method
  ...

Author: weaverryan

components/config/definition.rst

@@ -569,7 +569,7 @@ tree with ``append()``::
             ->isRequired()
             ->requiresAtLeastOneElement()
             ->useAttributeAsKey('name')
-            ->arrayPrototype
+            ->arrayPrototype()
                 ->children()
                     ->scalarNode('value')->isRequired()->end()
                 ->end()

configuration/micro_kernel_trait.rst

@@ -94,7 +94,7 @@ that define your bundles, your services and your routes:
     This is the same ``registerBundles()`` that you see in a normal kernel.
 
 **configureContainer(ContainerBuilder $c, LoaderInterface $loader)**
-    This methods builds and configures the container. In practice, you will use
+    This method builds and configures the container. In practice, you will use
     ``loadFromExtension`` to configure different bundles (this is the equivalent
     of what you see in a normal ``config.yml`` file). You can also register services
     directly in PHP or load external configuration files (shown below).

contributing/code/standards.rst

@@ -222,7 +222,10 @@ Service Naming Conventions
 * Use lowercase letters for service and parameter names (except when referring
   to environment variables with the ``%env(VARIABLE_NAME)%`` syntax);
 
-* A group name uses the underscore notation.
+* A group name uses the underscore notation;
+
+* Add class aliases for public services (e.g. alias ``Symfony\Component\Something\ClassName``
+  to ``something.service_name``).
 
 Documentation
 -------------

doctrine.rst

@@ -184,8 +184,8 @@ can automatically generate an empty ``test_project`` database for you:
                 'dbal' => array(
                     'charset' => 'utf8mb4',
                     'default_table_options' => array(
-                        'charset' => 'utf8mb4'
-                        'collate' => 'utf8mb4_unicode_ci'
+                        'charset' => 'utf8mb4',
+                        'collate' => 'utf8mb4_unicode_ci',
                     )
                 ),
             ));

event_dispatcher.rst

@@ -64,8 +64,8 @@ The most common way to listen to an event is to register an **event listener**::
 
     Each event receives a slightly different type of ``$event`` object. For
     the ``kernel.exception`` event, it is :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`.
-    To see what type of object each event listener receives, see :class:`Symfony\\Component\\HttpKernel\\KernelEvents`
-    or the documentation about the specific event you're listening to.
+    Check out the :doc:`Symfony events reference </reference/events>` to see
+    what type of object each event provides.
 
 Now that the class is created, you just need to register it as a service and
 notify Symfony that it is a "listener" on the ``kernel.exception`` event by

form/events.rst

@@ -282,7 +282,7 @@ Creating and binding an event listener to the form is very easy::
                 return;
             }
 
-            // Check whether the user has chosen to display his email or not.
+            // Check whether the user has chosen to display their email or not.
             // If the data was submitted previously, the additional value that is
             // included in the request variables needs to be removed.
             if (true === $user['show_email']) {
@@ -363,7 +363,7 @@ Event subscribers have different uses:
             $form = $event->getForm();
 
             // Check whether the user from the initial data has chosen to
-            // display his email or not.
+            // display their email or not.
             if (true === $user->isShowEmail()) {
                 $form->add('email', EmailType::class);
             }
@@ -378,7 +378,7 @@ Event subscribers have different uses:
                 return;
             }
 
-            // Check whether the user has chosen to display his email or not.
+            // Check whether the user has chosen to display their email or not.
             // If the data was submitted previously, the additional value that
             // is included in the request variables needs to be removed.
             if (true === $user['show_email']) {

frontend.rst

@@ -25,6 +25,8 @@ to solve the most common Webpack use cases.
     Encore is made by `Symfony`_ and works *beautifully* in Symfony applications.
     But it can easily be used in any application... in any language!
 
+.. _encore-toc:
+
 Encore Documentation
 --------------------
 

frontend/encore/simple-example.rst

@@ -4,10 +4,20 @@ First Example
 Imagine you have a simple project with one CSS and one JS file, organized into
 an ``assets/`` directory:
 
-* ``assets/js/main.js``
-* ``assets/css/global.scss``
+* ``assets/js/app.js``
+* ``assets/css/app.scss``
 
-With Encore, we can easily minify these files, pre-process ``global.scss``
+With Encore, you should think of CSS as a *dependency* of your JavaScript. This means,
+you will *require* whatever CSS you need from inside JavaScript:
+
+.. code-block:: javascript
+
+    // assets/js/app.js
+    require('../css/app.scss');
+
+    // ...rest of JavaScript code here
+
+With Encore, we can easily minify these files, pre-process ``app.scss``
 through Sass and a *lot* more.
 
 Configuring Encore/Webpack
@@ -22,20 +32,14 @@ Inside, use Encore to help generate your Webpack configuration.
     var Encore = require('@symfony/webpack-encore');
 
     Encore
-        // directory where all compiled assets will be stored
+        // the project directory where all compiled assets will be stored
         .setOutputPath('web/build/')
 
-        // what's the public path to this directory (relative to your project's document root dir)
+        // the public path used by the web server to access the previous directory
         .setPublicPath('/build')
 
-        // empty the outputPath dir before each build
-        .cleanupOutputBeforeBuild()
-
-        // will output as web/build/app.js
-        .addEntry('app', './assets/js/main.js')
-
-        // will output as web/build/global.css
-        .addStyleEntry('global', './assets/css/global.scss')
+        // will create web/build/app.js and web/build/app.css
+        .addEntry('app', './assets/js/app.js')
 
         // allow sass/scss files to be processed
         .enableSassLoader()
@@ -45,6 +49,12 @@ Inside, use Encore to help generate your Webpack configuration.
 
         .enableSourceMaps(!Encore.isProduction())
 
+        // empty the outputPath dir before each build
+        .cleanupOutputBeforeBuild()
+
+        // show OS notifications when builds finish/fail
+        .enableBuildNotifications()
+
         // create hashed filenames (e.g. app.abc123.css)
         // .enableVersioning()
     ;
@@ -83,7 +93,7 @@ Actually, to use ``enableSassLoader()``, you'll need to install a few
 more packages. But Encore will tell you *exactly* what you need.
 
 After running one of these commands, you can now add ``script`` and ``link`` tags
-to the new, compiled assets (e.g. ``/build/global.css`` and ``/build/app.js``).
+to the new, compiled assets (e.g. ``/build/app.css`` and ``/build/app.js``).
 In Symfony, use the ``asset()`` helper:
 
 .. code-block:: twig
@@ -93,7 +103,7 @@ In Symfony, use the ``asset()`` helper:
     <html>
         <head>
             <!-- ... -->
-            <link rel="stylesheet" href="{{ asset('build/global.css') }}">
+            <link rel="stylesheet" href="{{ asset('build/app.css') }}">
         </head>
         <body>
             <!-- ... -->
@@ -124,7 +134,7 @@ Great! Use ``require()`` to import ``jquery`` and ``greet.js``:
 
 .. code-block:: javascript
 
-    // assets/js/main.js
+    // assets/js/app.js
 
     // loads the jquery package from node_modules
     var $ = require('jquery');
@@ -139,34 +149,31 @@ Great! Use ``require()`` to import ``jquery`` and ``greet.js``:
 
 That's it! When you build your assets, jQuery and ``greet.js`` will automatically
 be added to the output file (``app.js``). For common libraries like jQuery, you
-may want also to :doc:`create a shared entry </frontend/encore/shared-entry>` for better performance.
+may want to :doc:`create a shared entry </frontend/encore/shared-entry>` for better
+performance.
 
-Requiring CSS Files from JavaScript
------------------------------------
+Multiple JavaScript Entries
+---------------------------
 
-Above, you created an entry called ``app`` that pointed to ``main.js``:
+The previous example is the best way to deal with SPA (Single Page Applications)
+and very simple applications. However, as your app grows, you may want to have
+page-specific JavaScript or CSS (e.g. homepage, blog, store, etc.). To handle this,
+add a new "entry" for each page that needs custom JavaScript or CSS:
 
 .. code-block:: javascript
 
     Encore
         // ...
-        .addEntry('app', './assets/js/main.js')
+        .addEntry('homepage', './assets/js/homepage.js')
+        .addEntry('blog', './assets/js/blog.js')
+        .addEntry('store', './assets/js/store.js')
     ;
 
-Once inside ``main.js``, you can even require CSS files:
-
-.. code-block:: javascript
-
-    // assets/js/main.js
-    // ...
-
-    // a CSS file with the same name as the entry js will be output
-    require('../css/main.scss');
-
-Now, both an ``app.js`` **and** an ``app.css`` file will be created. You'll need
-to add a link tag to the ``app.css`` file in your templates:
+If those entries include CSS/Sass files (e.g. ``homepage.js`` requires
+``assets/css/homepage.scss``), two files will be generated for each:
+(e.g. ``build/homepage.js`` and ``build/homepage.css``).
 
-.. code-block:: diff
+Keep Going!
+-----------
 
-    <link rel="stylesheet" href="{{ asset('build/global.css') }}">
-    + <link rel="stylesheet" href="{{ asset('build/app.css') }}">
+Go back to the :ref:`Encore Top List <encore-toc>` to learn more and add new features.

reference/configuration/framework.rst

@@ -98,7 +98,7 @@ Configuration
     * :ref:`enable_annotations <reference-validation-enable_annotations>`
     * `translation_domain`_
     * `strict_email`_
-    * `mapping`_
+    * :ref:`mapping <reference-validation-mapping>`
         * :ref:`paths <reference-validation-mapping-paths>`
 * `annotations`_
     * :ref:`cache <reference-annotations-cache>`
@@ -110,6 +110,8 @@ Configuration
     * :ref:`enable_annotations <reference-serializer-enable_annotations>`
     * :ref:`name_converter <reference-serializer-name_converter>`
     * :ref:`circular_reference_handler <reference-serializer-circular_reference_handler>`
+    * :ref:`mapping <reference-serializer-mapping>`
+        * :ref:`paths <reference-serializer-mapping-paths>`
 * `php_errors`_
     * `log`_
     * `throw`_
@@ -1591,6 +1593,8 @@ If this option is enabled, the `egulias/email-validator`_ library will be
 used by the :doc:`/reference/constraints/Email` constraint validator. Otherwise,
 the validator uses a simple regular expression to validate email addresses.
 
+.. _reference-validation-mapping:
+
 mapping
 .......
 
@@ -1716,6 +1720,21 @@ method.
     For more information, see
     :ref:`component-serializer-handling-circular-references`.
 
+.. _reference-serializer-mapping:
+
+mapping
+.......
+
+.. _reference-serializer-mapping-paths:
+
+paths
+"""""
+
+**type**: ``array`` **default**: ``[]``
+
+This option allows to define an array of paths with files or directories where
+the component will look for additional serialization files.
+
 php_errors
 ~~~~~~~~~~
 

reference/configuration/security.rst

@@ -462,7 +462,7 @@ dn_string
 **type**: ``string`` **default**: ``{username}``
 
 This is the string which will be used as the bind DN. The ``{username}``
-placeholder will be replaced with the user-provided value (his login).
+placeholder will be replaced with the user-provided value (their login).
 Depending on your LDAP server's configuration, you may need to override
 this value.
 

reference/configuration/twig.rst

@@ -58,7 +58,6 @@ TwigBundle Configuration ("twig")
             paths:
                 '%kernel.project_dir%/vendor/acme/foo-bar/templates': foo_bar
 
-            # The following were added in Symfony 2.7.
             date:
                 format: d.m.Y, H:i:s
                 interval_format: '%%d days'

reference/dic_tags.rst

@@ -1,16 +1,12 @@
-The Dependency Injection Tags
+Built-in Symfony Service Tags
 =============================
 
-Dependency Injection Tags are little strings that can be applied to a service
-to "flag" it to be used in some special way. For example, if you have a
-service that you would like to register as a listener to one of Symfony's
-core events, you can flag it with the ``kernel.event_listener`` tag.
+:doc:`Service tags </service_container/tags>` are the mechanism used by the
+:doc:`DependencyInjection component </components/dependency_injection>` to flag
+services that require special processing, like console commands or Twig extensions.
 
-You can learn a little bit more about "tags" by reading the ":doc:`/service_container/tags`"
-article.
-
-Below is information about all of the tags available inside Symfony. There
-may also be tags in other bundles you use that aren't listed here.
+These are the most common tags provided by Symfony components, but in your
+application there could be more tags available provided by third-party bundles:
 
 ========================================  ========================================================================
 Tag Name                                  Usage