Merge branch '2.3' into 2.6

Conflicts:
	cookbook/form/data_transformers.rst
	cookbook/security/form_login_setup.rst
	cookbook/security/remember_me.rst

Author: xabbuh

best_practices/creating-the-project.rst

@@ -110,6 +110,11 @@ Symfony documentation uses the AppBundle name.
     There is no need to prefix the AppBundle with your own vendor (e.g.
     AcmeAppBundle), because this application bundle is never going to be
     shared.
+    
+.. note::
+    
+    Another reason to create a new bundle is when you're overriding something 
+    in a vendor's bundle (e.g. a controller). See :doc:`/cookbook/bundles/inheritance`.
 
 All in all, this is the typical directory structure of a Symfony application
 that follows these best practices:

components/dom_crawler.rst

@@ -301,6 +301,12 @@ and :phpclass:`DOMNode` objects:
 
     The ``html`` method is new in Symfony 2.3.
 
+    .. caution::
+
+        Due to an issue in PHP, the ``html()`` method returns wrongly decoded HTML
+        entities in PHP versions lower than 5.3.6 (for example, it returns ``•``
+        instead of ``•``).
+
 Links
 ~~~~~
 

contributing/code/bugs.rst

@@ -14,8 +14,8 @@ Before submitting a bug:
 * Double-check the official :doc:`documentation </index>` to see if you're not misusing the
   framework;
 
-* Ask for assistance on the `users mailing-list`_, the `forum`_, or on the
-  #symfony `IRC channel`_ if you're not sure if your issue is really a bug.
+* Ask for assistance on `Stack Overflow`_ or on the #symfony `IRC channel`_
+  if you're not sure if your issue is really a bug.
 
 If your problem definitely looks like a bug, report it using the official bug
 `tracker`_ and follow some basic rules:
@@ -34,8 +34,7 @@ If your problem definitely looks like a bug, report it using the official bug
 
 * *(optional)* Attach a :doc:`patch <patches>`.
 
-.. _users mailing-list: http://groups.google.com/group/symfony2
-.. _forum: http://forum.symfony-project.org/
-.. _IRC channel: irc://irc.freenode.net/symfony
+.. _`Stack Overflow`: http://stackoverflow.com/questions/tagged/symfony2
+.. _IRC channel: http://symfony.com/irc
 .. _tracker: https://github.com/symfony/symfony/issues
 .. _Symfony Standard Edition: https://github.com/symfony/symfony-standard/

contributing/code/patches.rst

@@ -110,7 +110,7 @@ work:
 * ``2.3``, if you are fixing a bug for an existing feature (you may have
   to choose a higher branch if the feature you are fixing was introduced
   in a later version);
-* ``2.7``, if you are adding a new feature which is backward compatible;
+* ``2.8``, if you are adding a new feature which is backward compatible;
 * ``master``, if you are adding a new and backward incompatible feature.
 
 .. note::

contributing/code/security.rst

@@ -9,9 +9,9 @@ Reporting a Security Issue
 --------------------------
 
 If you think that you have found a security issue in Symfony, don't use the
-mailing-list or the bug tracker and don't publish it publicly. Instead, all
-security issues must be sent to **security [at] symfony.com**. Emails sent to
-this address are forwarded to the Symfony core-team private mailing-list.
+bug tracker and don't publish it publicly. Instead, all security issues must
+be sent to **security [at] symfony.com**. Emails sent to this address are
+forwarded to the Symfony core-team private mailing-list.
 
 Resolving Process
 -----------------

contributing/code/standards.rst

@@ -100,6 +100,8 @@ Structure
 
 * Place unary operators (``!``, ``--``, ...) adjacent to the affected variable;
 
+* Always use `identical comparison`_ unless you need type juggling;
+
 * Add a comma after each array item in a multi-line array, even after the
   last one;
 
@@ -186,3 +188,4 @@ License
 .. _`PSR-1`: http://www.php-fig.org/psr/psr-1/
 .. _`PSR-2`: http://www.php-fig.org/psr/psr-2/
 .. _`PSR-4`: http://www.php-fig.org/psr/psr-4/
+.. _`identical comparison`: https://php.net/manual/en/language.operators.comparison.php

cookbook/assetic/index.rst

@@ -5,6 +5,7 @@ Assetic
     :maxdepth: 2
 
     asset_management
+    php
     uglifyjs
     yuicompressor
     jpeg_optimize

cookbook/assetic/php.rst

@@ -0,0 +1,203 @@
+.. index::
+    single: Front-end; Assetic, Bootstrap
+
+Combining, Compiling and Minimizing Web Assets with PHP Libraries
+=================================================================
+
+The official Symfony Best Practices recommend to use Assetic to
+:doc:`manage web assets </best_practices/web-assets>`, unless you are
+comfortable with JavaScript-based front-end tools.
+
+Even if those JavaScript-based solutions are the most suitable ones from a
+technical point of view, using pure PHP alternative libraries can be useful in
+some scenarios:
+
+* If you can't install or use ``npm`` and the other JavaScript solutions;
+* If you prefer to limit the amount of different technologies used in your
+  applications;
+* If you want to simplify application deployment.
+
+In this article, you'll learn how to combine and minimize CSS and JavaScript files
+and how to compile Sass files using PHP-only libraries with Assetic.
+
+Installing the Third-Party Compression Libraries
+------------------------------------------------
+
+Assetic includes a lot of ready-to-use filters, but it doesn't include their
+associated libraries. Therefore, before enabling the filters used in this article,
+you must install two libraries. Open a command console, browse to your project
+directory and execute the following commands:
+
+.. code-block:: bash
+
+    $ composer require leafo/scssphp
+    $ composer require patchwork/jsqueeze:"~1.0"
+
+It's very important to maintain the ``~1.0`` version constraint for the ``jsqueeze``
+dependency because the most recent stable version is not compatible with Assetic.
+
+Organizing your Web Asset Files
+-------------------------------
+
+This example will include a setup using the Bootstrap CSS framework, jQuery, FontAwesome
+and some regular CSS and and JavaScript application files (called ``main.css`` and
+``main.js``). The recommended directory structure for this set-up looks like this:
+
+.. code-block:: text
+
+    web/assets/
+    ├── css
+    │   ├── main.css
+    │   └── code-highlight.css
+    ├── js
+    │   ├── bootstrap.js
+    │   ├── jquery.js
+    │   └── main.js
+    └── scss
+        ├── bootstrap
+        │   ├── _alerts.scss
+        │   ├── ...
+        │   ├── _variables.scss
+        │   ├── _wells.scss
+        │   └── mixins
+        │       ├── _alerts.scss
+        │       ├── ...
+        │       └── _vendor-prefixes.scss
+        ├── bootstrap.scss
+        ├── font-awesome
+        │   ├── _animated.scss
+        │   ├── ...
+        │   └── _variables.scss
+        └── font-awesome.scss
+
+Combining and Minimizing CSS Files and Compiling SCSS Files
+-----------------------------------------------------------
+
+First, configure a new ``scssphp`` Assetic filter:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        assetic:
+            filters:
+                scssphp:
+                    formatter: 'Leafo\ScssPhp\Formatter\Compressed'
+                # ...
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" charset="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:assetic="http://symfony.com/schema/dic/assetic">
+
+            <assetic:config>
+                <filter name="scssphp" formatter="Leafo\ScssPhp\Formatter\Compressed" />
+                <!-- ... -->
+            </assetic:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('assetic', array(
+            'filters' => array(
+                 'scssphp' => array(
+                     'formatter' => 'Leafo\ScssPhp\Formatter\Compressed',
+                 ),
+                 // ...
+            ),
+        ));
+
+The value of the ``formatter`` option is the fully qualified class name of the
+formatter used by the filter to produce the compiled CSS file. Using the
+compressed formatter will minimize the the resulting file, regardless of whether
+the original files are regular CSS files or SCSS files.
+
+Next, your Twig template to add the ``{% stylesheets %}`` tag defined by Assetic:
+
+.. code-block:: html+jinja
+
+    {# app/Resources/views/base.html.twig #}
+    <!DOCTYPE html>
+    <html>
+        <head>
+            <!-- ... -->
+
+            {% stylesheets filter="scssphp" output="css/app.css"
+                "assets/scss/bootstrap.scss"
+                "assets/scss/font-awesome.scss"
+                "assets/css/*.css"
+            %}
+                <link rel="stylesheet" href="{{ asset_url }}" />
+            {% endstylesheets %}
+
+This simple configuration compiles, combines and minifies the SCSS files into a
+regular CSS file that's put in ``web/css/app.css``. This is the only CSS file
+which will be served to your visitors.
+
+Combining and Minimizing JavaScript Files
+-----------------------------------------
+
+First, configure a new ``jsqueeze`` Assetic filter as follows:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        assetic:
+            filters:
+                jsqueeze: ~
+                # ...
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" charset="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:assetic="http://symfony.com/schema/dic/assetic">
+
+            <assetic:config>
+                <filter name="jsqueeze" />
+                <!-- ... -->
+            </assetic:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('assetic', array(
+            'filters' => array(
+                 'jsqueeze' => null,
+                 // ...
+            ),
+        ));
+
+Next, update the code of your Twig template to add the ``{% javascripts %}`` tag
+defined by Assetic:
+
+.. code-block:: html+jinja
+
+    <!-- ... -->
+
+        {% javascripts filter="?jsqueeze" output="js/app.js"
+            "assets/js/jquery.js"
+            "assets/js/bootstrap.js"
+            "assets/js/main.js"
+        %}
+            <script src="{{ asset_url }}"></script>
+        {% endjavascripts %}
+
+        </body>
+    </html>
+
+This simple configuration combines all the JavaScript files, minimizes the contents
+and saves the output in the ``web/js/app.js`` file, which is the one that is
+served to your visitors.
+
+The leading ``?`` character in the ``jsqueeze`` filter name tells Assetic to only
+apply the filter when *not* in ``debug`` mode. In practice, this means that you'll
+see unminified files while developing and minimized files in the ``prod`` environment.

cookbook/bundles/override.rst

@@ -192,7 +192,10 @@ can override the translations from any translation file, as long as it is in
     sure that the bundle containing *your* translations is loaded after any
     bundle whose translations you're overriding. This is done in ``AppKernel``.
 
+    Translation files are also not aware of :doc:`bundle inheritance </cookbook/bundles/inheritance>`.
+    If you want to override translations from the parent bundle, be sure that the
+    parent bundle is loaded before the child bundle in the ``AppKernel`` class.
+
     The file that always wins is the one that is placed in
     ``app/Resources/translations``, as those files are always loaded last.
-
 .. _`the Doctrine documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/inheritance-mapping.html#overrides

cookbook/controller/error_pages.rst

@@ -136,7 +136,7 @@ The cause of this problem is that routing is done before security. If a 404 erro
 occurs, the security layer isn't loaded and thus, the ``is_granted()`` function
 is undefined. The solution is to add the following check before using this function:
 
-.. code-block:: twig
+.. code-block:: jinja
 
     {% if app.user and is_granted('...') %}
         {# ... #}