From 86da33885b25c4dc072d44cc17d234b42efe0b59 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 10 Apr 2015 17:38:10 +0200 Subject: [PATCH 01/12] Proposed a new article about using pure PHP libraries with Assetic --- cookbook/frontend/assetic_php.rst | 156 ++++++++++++++++++++++++++++++ cookbook/index.rst | 1 + cookbook/map.rst.inc | 5 + 3 files changed, 162 insertions(+) create mode 100644 cookbook/frontend/assetic_php.rst diff --git a/cookbook/frontend/assetic_php.rst b/cookbook/frontend/assetic_php.rst new file mode 100644 index 00000000000..5d19ffe8e42 --- /dev/null +++ b/cookbook/frontend/assetic_php.rst @@ -0,0 +1,156 @@ +.. index:: + single: Front-end; Assetic, Bootstrap + +Combining, Compiling and Minimizing Web Assets with Pure PHP Libraries +====================================================================== + +The official Symfony Best Practices recommend to use Assetic to +:doc:`manage web assets `, unless you are +comfortable with JavaScript-based frontend 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 SCSS files using pure PHP 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 very common scenario of using the Bootstrap framework, the +jQuery library, the FontAwesome icon font 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: + +.. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + scssphp: + 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:: jinja+html + + + + + + + {% stylesheets filter="?scssphp" output="css/app.css" + "assets/scss/bootstrap.scss" + "assets/scss/font-awesome.scss" + "assets/css/*.css" + %} + + {% endstylesheets %} + +This simple configuration compiles the SCSS files into regular CSS files, combines +all of them, minimizes the contents and saves the output in the ``web/css/app.css`` +file, which is the one that is served to your visitors. + +The leading ``?`` character in the ``scssphp`` 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. + +Combining and Minimizing JavaScript Files +----------------------------------------- + +First, configure a new ``jsqueeze`` Assetic filter as follows: + +.. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + jsqueeze: ~ + # ... + +Then, update the code of your Twig template to add the ``{% javascripts %}`` tag +defined by Assetic: + +.. code-block:: jinja+html + + + + {% 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. + +Similarly to the ``scssphp`` filter, 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/index.rst b/cookbook/index.rst index 03d29060c7f..7ad4360e21b 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -17,6 +17,7 @@ The Cookbook email/index event_dispatcher/index form/index + frontend/index logging/index profiler/index request/index diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 6c8e5d59d89..40798c22a05 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -107,6 +107,11 @@ * (validation) :doc:`/cookbook/validation/custom_constraint` * (doctrine) :doc:`/cookbook/doctrine/file_uploads` + +* :doc:`/cookbook/frontend/index` + + * :doc:`/cookbook/frontend/assetic_php` + * :doc:`/cookbook/logging/index` * :doc:`/cookbook/logging/monolog` From 798b5b5e549c5561f374710e85491047430cb72a Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 10 Apr 2015 20:04:36 +0200 Subject: [PATCH 02/12] Added the missin index file --- cookbook/frontend/index.rst | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 cookbook/frontend/index.rst diff --git a/cookbook/frontend/index.rst b/cookbook/frontend/index.rst new file mode 100644 index 00000000000..8e72b465c59 --- /dev/null +++ b/cookbook/frontend/index.rst @@ -0,0 +1,7 @@ +Form +==== + +.. toctree:: + :maxdepth: 2 + + assetic_php From 14d03462ad9d89317a57c8a5440e4e465b703839 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 10 Apr 2015 20:15:31 +0200 Subject: [PATCH 03/12] Fixed the Twig lexer name --- cookbook/frontend/assetic_php.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/frontend/assetic_php.rst b/cookbook/frontend/assetic_php.rst index 5d19ffe8e42..85c7047201c 100644 --- a/cookbook/frontend/assetic_php.rst +++ b/cookbook/frontend/assetic_php.rst @@ -93,7 +93,7 @@ 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:: jinja+html +.. code-block:: html+jinja @@ -132,7 +132,7 @@ First, configure a new ``jsqueeze`` Assetic filter as follows: Then, update the code of your Twig template to add the ``{% javascripts %}`` tag defined by Assetic: -.. code-block:: jinja+html +.. code-block:: html+jinja From 044cd73a66200ce57aec3de77083bc41fac49844 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 10 Apr 2015 20:25:11 +0200 Subject: [PATCH 04/12] The file extension is not needed --- cookbook/frontend/assetic_php.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/frontend/assetic_php.rst b/cookbook/frontend/assetic_php.rst index 85c7047201c..fd2f6c5202f 100644 --- a/cookbook/frontend/assetic_php.rst +++ b/cookbook/frontend/assetic_php.rst @@ -5,7 +5,7 @@ Combining, Compiling and Minimizing Web Assets with Pure PHP Libraries ====================================================================== The official Symfony Best Practices recommend to use Assetic to -:doc:`manage web assets `, unless you are +:doc:`manage web assets `, unless you are comfortable with JavaScript-based frontend tools. Even if those JavaScript-based solutions are the most suitable ones from a From cc5b630442f53d590d734a12b8ce608ab133d0d7 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 10 Apr 2015 20:35:16 +0200 Subject: [PATCH 05/12] Reworded some wrong statements --- cookbook/frontend/assetic_php.rst | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/cookbook/frontend/assetic_php.rst b/cookbook/frontend/assetic_php.rst index fd2f6c5202f..2856ae5a81e 100644 --- a/cookbook/frontend/assetic_php.rst +++ b/cookbook/frontend/assetic_php.rst @@ -100,7 +100,7 @@ defined by Assetic: - {% stylesheets filter="?scssphp" output="css/app.css" + {% stylesheets filter="scssphp" output="css/app.css" "assets/scss/bootstrap.scss" "assets/scss/font-awesome.scss" "assets/css/*.css" @@ -112,10 +112,6 @@ This simple configuration compiles the SCSS files into regular CSS files, combin all of them, minimizes the contents and saves the output in the ``web/css/app.css`` file, which is the one that is served to your visitors. -The leading ``?`` character in the ``scssphp`` 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. - Combining and Minimizing JavaScript Files ----------------------------------------- @@ -151,6 +147,6 @@ This simple configuration combines all the JavaScript files, minimizes the conte and saves the output in the ``web/js/app.js`` file, which is the one that is served to your visitors. -Similarly to the ``scssphp`` filter, 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. +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. From 1f6e16cc324e0fe140d84c08c6a1e8091ddb593f Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 13 Apr 2015 16:50:15 +0200 Subject: [PATCH 06/12] Minor fixes --- cookbook/frontend/assetic_php.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookbook/frontend/assetic_php.rst b/cookbook/frontend/assetic_php.rst index 2856ae5a81e..9340d3f832f 100644 --- a/cookbook/frontend/assetic_php.rst +++ b/cookbook/frontend/assetic_php.rst @@ -1,8 +1,8 @@ .. index:: single: Front-end; Assetic, Bootstrap -Combining, Compiling and Minimizing Web Assets with Pure PHP Libraries -====================================================================== +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 @@ -18,7 +18,7 @@ some scenarios: * 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 SCSS files using pure PHP libraries with Assetic. +and how to compile Sass SCSS files using PHP only libraries with Assetic. Installing the Third-Party Compression Libraries ------------------------------------------------ @@ -40,7 +40,7 @@ Organizing Your Web Asset Files ------------------------------- This example shows the very common scenario of using the Bootstrap framework, the -jQuery library, the FontAwesome icon font and some regular CSS and JavaScript +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: From 3ea9c86165eb353088c3fda67f9622f3b9f5feed Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 14 Apr 2015 13:14:03 +0200 Subject: [PATCH 07/12] Fixed some typos and grammar issues --- cookbook/frontend/assetic_php.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cookbook/frontend/assetic_php.rst b/cookbook/frontend/assetic_php.rst index 9340d3f832f..f7bf02e69f2 100644 --- a/cookbook/frontend/assetic_php.rst +++ b/cookbook/frontend/assetic_php.rst @@ -6,7 +6,7 @@ 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 frontend tools. +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 @@ -17,14 +17,14 @@ some scenarios: 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 SCSS files using PHP only libraries with Assetic. +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 +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: From bc6ffbe307071a5aa6998daea6c1b3ee1d3af602 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 14 Apr 2015 13:26:33 +0200 Subject: [PATCH 08/12] Rewords and code improvements --- cookbook/frontend/assetic_php.rst | 48 ++++++++++++++++++++++++------- 1 file changed, 37 insertions(+), 11 deletions(-) diff --git a/cookbook/frontend/assetic_php.rst b/cookbook/frontend/assetic_php.rst index f7bf02e69f2..b2751d464e7 100644 --- a/cookbook/frontend/assetic_php.rst +++ b/cookbook/frontend/assetic_php.rst @@ -36,10 +36,10 @@ directory and execute the following commands: 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 +Organizing your Web Asset Files ------------------------------- -This example shows the very common scenario of using the Bootstrap framework, the +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: @@ -95,6 +95,7 @@ defined by Assetic: .. code-block:: html+jinja + {# app/Resources/views/base.html.twig #} @@ -108,22 +109,47 @@ defined by Assetic: {% endstylesheets %} -This simple configuration compiles the SCSS files into regular CSS files, combines -all of them, minimizes the contents and saves the output in the ``web/css/app.css`` -file, which is the one that is served to your visitors. +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: -.. code-block:: yaml +.. configuration-block:: - # app/config/config.yml - assetic: - filters: - jsqueeze: ~ - # ... + .. 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: From 85e6a543c0676c33988f840a4e8be7b5637374aa Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 14 Apr 2015 13:27:51 +0200 Subject: [PATCH 09/12] Added more configuration formats --- cookbook/frontend/assetic_php.rst | 43 +++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 8 deletions(-) diff --git a/cookbook/frontend/assetic_php.rst b/cookbook/frontend/assetic_php.rst index b2751d464e7..7c24d19fad2 100644 --- a/cookbook/frontend/assetic_php.rst +++ b/cookbook/frontend/assetic_php.rst @@ -76,14 +76,41 @@ Combining and Minimizing CSS Files and Compiling SCSS Files First, configure a new ``scssphp`` Assetic filter as follows: -.. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - scssphp: - formatter: "Leafo\\ScssPhp\\Formatter\\Compressed" - # ... +.. 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 From 07087dd57b123f2b49131254ba614b373eafa228 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 14 Apr 2015 13:28:51 +0200 Subject: [PATCH 10/12] Avoid the ugly double back slashes --- cookbook/frontend/assetic_php.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/frontend/assetic_php.rst b/cookbook/frontend/assetic_php.rst index 7c24d19fad2..6124e50f960 100644 --- a/cookbook/frontend/assetic_php.rst +++ b/cookbook/frontend/assetic_php.rst @@ -84,7 +84,7 @@ First, configure a new ``scssphp`` Assetic filter as follows: assetic: filters: scssphp: - formatter: "Leafo\\ScssPhp\\Formatter\\Compressed" + formatter: 'Leafo\ScssPhp\Formatter\Compressed' # ... .. code-block:: xml From 4b8b3fbc501f982e6b29cb92ffc88e130bf202e5 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 14 Apr 2015 13:30:53 +0200 Subject: [PATCH 11/12] Moved the article back to the Assetic section --- cookbook/assetic/index.rst | 1 + cookbook/{frontend/assetic_php.rst => assetic/php.rst} | 0 cookbook/frontend/index.rst | 7 ------- cookbook/index.rst | 1 - cookbook/map.rst.inc | 6 +----- 5 files changed, 2 insertions(+), 13 deletions(-) rename cookbook/{frontend/assetic_php.rst => assetic/php.rst} (100%) delete mode 100644 cookbook/frontend/index.rst 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/frontend/assetic_php.rst b/cookbook/assetic/php.rst similarity index 100% rename from cookbook/frontend/assetic_php.rst rename to cookbook/assetic/php.rst diff --git a/cookbook/frontend/index.rst b/cookbook/frontend/index.rst deleted file mode 100644 index 8e72b465c59..00000000000 --- a/cookbook/frontend/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -Form -==== - -.. toctree:: - :maxdepth: 2 - - assetic_php diff --git a/cookbook/index.rst b/cookbook/index.rst index 7ad4360e21b..03d29060c7f 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -17,7 +17,6 @@ The Cookbook email/index event_dispatcher/index form/index - frontend/index logging/index profiler/index request/index diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 40798c22a05..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` @@ -107,11 +108,6 @@ * (validation) :doc:`/cookbook/validation/custom_constraint` * (doctrine) :doc:`/cookbook/doctrine/file_uploads` - -* :doc:`/cookbook/frontend/index` - - * :doc:`/cookbook/frontend/assetic_php` - * :doc:`/cookbook/logging/index` * :doc:`/cookbook/logging/monolog` From f5c4d930559f740107934f43129c5ef8d5d35e61 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 14 Apr 2015 13:32:31 +0200 Subject: [PATCH 12/12] Fixed an indentation problem --- cookbook/assetic/php.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/cookbook/assetic/php.rst b/cookbook/assetic/php.rst index 6124e50f960..b4ce591079e 100644 --- a/cookbook/assetic/php.rst +++ b/cookbook/assetic/php.rst @@ -89,28 +89,28 @@ First, configure a new ``scssphp`` Assetic filter as follows: .. code-block:: xml - - - + + + - - - - - + + + + + .. code-block:: php - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'scssphp' => array( - 'formatter' => 'Leafo\ScssPhp\Formatter\Compressed', - ), - // ... - ), - )); + // 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