Merge remote-tracking branch 'upstream/3.3' into 3.3

javiereguiluz · javiereguiluz · commit bd360d534fc4 · 2017-11-17T10:09:22.000+01:00
diff --git a/configuration/micro_kernel_trait.rst b/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).
diff --git a/contributing/code/standards.rst b/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
 -------------
diff --git a/frontend/encore/simple-example.rst b/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``
+Let's consider that the project follows the recommended practice of importing
+the CSS files for their associated JavaScript files:
+
+.. 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,17 @@ 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()
@@ -83,7 +90,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 +100,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 +131,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');
@@ -141,32 +148,23 @@ That's it! When you build your assets, jQuery and ``greet.js`` will automaticall
 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.
 
-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 application grows, you'll need to
+define more entries with the JavaScript and CSS code of some specific sections
+(homepage, blog, store, etc.)
 
 .. 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:
-
-.. code-block:: diff
-
-    <link rel="stylesheet" href="{{ asset('build/global.css') }}">
-    + <link rel="stylesheet" href="{{ asset('build/app.css') }}">
+If those entries include CSS/Sass files (e.g. ``homepage.js`` requires
+``assets/css/homepage.scss``), two files will be generated for each of them
+(e.g. ``build/homepage.js`` and ``build/homepage.css``).
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -102,7 +102,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>`
@@ -114,6 +114,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`_
@@ -1637,6 +1639,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
 .......
 
@@ -1762,6 +1766,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
 ~~~~~~~~~~
 
