feature #5166 Proposed a new article about using pure PHP libraries w…

…ith Assetic (javiereguiluz)

This PR was merged into the 2.3 branch.

Discussion
----------

Proposed a new article about using pure PHP libraries with Assetic

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | all
| Fixed tickets | -

In #5159 @wouterj proposes to create a new Cookbook section dedicated to frontend articles. I think it's a great idea and in this pull request I propose an article showing how to use pure PHP libraries to combine, compile and minimize CSS, SCSS and JS files.

Commits
-------

f5c4d93 Fixed an indentation problem
4b8b3fb Moved the article back to the Assetic section
07087dd Avoid the ugly double back slashes
85e6a54 Added more configuration formats
bc6ffbe Rewords and code improvements
3ea9c86 Fixed some typos and grammar issues
1f6e16c Minor fixes
cc5b630 Reworded some wrong statements
044cd73 The file extension is not needed
14d0346 Fixed the Twig lexer name
798b5b5 Added the missin index file
86da338 Proposed a new article about using pure PHP libraries with Assetic

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,205 @@
+.. 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 shows the common scenario of using the Bootstrap framework, the
+jQuery library, the FontAwesome icon fonts and some regular CSS and JavaScript
+application files (called ``main.css`` and ``main.js``). The recommended directory
+structure for this set-up is the following:
+
+.. 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 as follows:
+
+.. 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 allows to minimize the resulting file, no matter if the
+original files are regular CSS files or SCSS files.
+
+Then, update the code of 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,
+                 // ...
+            ),
+        ));
+
+Then, 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 indicates that it must
+be applied only when the ``debug`` mode is disabled in the application, which
+usually occurs in the production environment.

cookbook/map.rst.inc

@@ -1,6 +1,7 @@
 * :doc:`/cookbook/assetic/index`
 
   * :doc:`/cookbook/assetic/asset_management`
+  * :doc:`/cookbook/assetic/php`
   * :doc:`/cookbook/assetic/uglifyjs`
   * :doc:`/cookbook/assetic/yuicompressor`
   * :doc:`/cookbook/assetic/jpeg_optimize`