diff --git a/cookbook/assetic/index.rst b/cookbook/assetic/index.rst index a4b084c22f0..c37efdc16ee 100644 --- a/cookbook/assetic/index.rst +++ b/cookbook/assetic/index.rst @@ -5,6 +5,7 @@ Assetic :maxdepth: 2 asset_management + php uglifyjs yuicompressor jpeg_optimize diff --git a/cookbook/assetic/php.rst b/cookbook/assetic/php.rst new file mode 100644 index 00000000000..b4ce591079e --- /dev/null +++ b/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 `, 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 + + + + + + + + + + + + .. 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 #} + + + + + + {% stylesheets filter="scssphp" output="css/app.css" + "assets/scss/bootstrap.scss" + "assets/scss/font-awesome.scss" + "assets/css/*.css" + %} + + {% 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 + + + + + + + + + + + + .. 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" + %} + + {% endjavascripts %} + + + + +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. diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 6c8e5d59d89..448b2868e6d 100644 --- a/cookbook/map.rst.inc +++ b/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`