Skip to content

Commit 6c05874

Browse files
weaverryanweaverryan
committed
feature #5166 Proposed a new article about using pure PHP libraries with 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
2 parents 4d413cb + f5c4d93 commit 6c05874

File tree

3 files changed

+207
-0
lines changed

3 files changed

+207
-0
lines changed

‎cookbook/assetic/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ Assetic
55
:maxdepth: 2
66

77
asset_management
8+
php
89
uglifyjs
910
yuicompressor
1011
jpeg_optimize

‎cookbook/assetic/php.rst

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
.. index::
2+
single: Front-end; Assetic, Bootstrap
3+
4+
Combining, Compiling and Minimizing Web Assets with PHP Libraries
5+
=================================================================
6+
7+
The official Symfony Best Practices recommend to use Assetic to
8+
:doc:`manage web assets </best_practices/web-assets>`, unless you are
9+
comfortable with JavaScript-based front-end tools.
10+
11+
Even if those JavaScript-based solutions are the most suitable ones from a
12+
technical point of view, using pure PHP alternative libraries can be useful in
13+
some scenarios:
14+
15+
* If you can't install or use ``npm`` and the other JavaScript solutions;
16+
* If you prefer to limit the amount of different technologies used in your
17+
applications;
18+
* If you want to simplify application deployment.
19+
20+
In this article, you'll learn how to combine and minimize CSS and JavaScript files
21+
and how to compile Sass files using PHP only libraries with Assetic.
22+
23+
Installing the Third-Party Compression Libraries
24+
------------------------------------------------
25+
26+
Assetic includes a lot of ready-to-use filters, but it doesn't include their
27+
associated libraries. Therefore, before enabling the filters used in this article,
28+
you must install two libraries. Open a command console, browse to your project
29+
directory and execute the following commands:
30+
31+
.. code-block:: bash
32+
33+
$ composer require leafo/scssphp
34+
$ composer require patchwork/jsqueeze:"~1.0"
35+
36+
It's very important to maintain the ``~1.0`` version constraint for the ``jsqueeze``
37+
dependency because the most recent stable version is not compatible with Assetic.
38+
39+
Organizing your Web Asset Files
40+
-------------------------------
41+
42+
This example shows the common scenario of using the Bootstrap framework, the
43+
jQuery library, the FontAwesome icon fonts and some regular CSS and JavaScript
44+
application files (called ``main.css`` and ``main.js``). The recommended directory
45+
structure for this set-up is the following:
46+
47+
.. code-block:: text
48+
49+
web/assets/
50+
├── css
51+
│   ├── main.css
52+
│   └── code-highlight.css
53+
├── js
54+
│   ├── bootstrap.js
55+
│   ├── jquery.js
56+
│   └── main.js
57+
└── scss
58+
├── bootstrap
59+
│   ├── _alerts.scss
60+
│   ├── ...
61+
│   ├── _variables.scss
62+
│   ├── _wells.scss
63+
│   └── mixins
64+
│   ├── _alerts.scss
65+
│   ├── ...
66+
│   └── _vendor-prefixes.scss
67+
├── bootstrap.scss
68+
├── font-awesome
69+
│   ├── _animated.scss
70+
│   ├── ...
71+
│   └── _variables.scss
72+
└── font-awesome.scss
73+
74+
Combining and Minimizing CSS Files and Compiling SCSS Files
75+
-----------------------------------------------------------
76+
77+
First, configure a new ``scssphp`` Assetic filter as follows:
78+
79+
.. configuration-block::
80+
81+
.. code-block:: yaml
82+
83+
# app/config/config.yml
84+
assetic:
85+
filters:
86+
scssphp:
87+
formatter: 'Leafo\ScssPhp\Formatter\Compressed'
88+
# ...
89+
90+
.. code-block:: xml
91+
92+
<!-- app/config/config.xml -->
93+
<?xml version="1.0" charset="UTF-8" ?>
94+
<container xmlns="http://symfony.com/schema/dic/services"
95+
xmlns:assetic="http://symfony.com/schema/dic/assetic">
96+
97+
<assetic:config>
98+
<filter name="scssphp" formatter="Leafo\ScssPhp\Formatter\Compressed" />
99+
<!-- ... -->
100+
</assetic:config>
101+
</container>
102+
103+
.. code-block:: php
104+
105+
// app/config/config.php
106+
$container->loadFromExtension('assetic', array(
107+
'filters' => array(
108+
'scssphp' => array(
109+
'formatter' => 'Leafo\ScssPhp\Formatter\Compressed',
110+
),
111+
// ...
112+
),
113+
));
114+
115+
The value of the ``formatter`` option is the fully qualified class name of the
116+
formatter used by the filter to produce the compiled CSS file. Using the
117+
compressed formatter allows to minimize the resulting file, no matter if the
118+
original files are regular CSS files or SCSS files.
119+
120+
Then, update the code of your Twig template to add the ``{% stylesheets %}`` tag
121+
defined by Assetic:
122+
123+
.. code-block:: html+jinja
124+
125+
{# app/Resources/views/base.html.twig #}
126+
<!DOCTYPE html>
127+
<html>
128+
<head>
129+
<!-- ... -->
130+
131+
{% stylesheets filter="scssphp" output="css/app.css"
132+
"assets/scss/bootstrap.scss"
133+
"assets/scss/font-awesome.scss"
134+
"assets/css/*.css"
135+
%}
136+
<link rel="stylesheet" href="{{ asset_url }}" />
137+
{% endstylesheets %}
138+
139+
This simple configuration compiles, combines and minifies the SCSS files into a
140+
regular CSS file that's put in ``web/css/app.css``. This is the only CSS file
141+
which will be served to your visitors.
142+
143+
Combining and Minimizing JavaScript Files
144+
-----------------------------------------
145+
146+
First, configure a new ``jsqueeze`` Assetic filter as follows:
147+
148+
.. configuration-block::
149+
150+
.. code-block:: yaml
151+
152+
# app/config/config.yml
153+
assetic:
154+
filters:
155+
jsqueeze: ~
156+
# ...
157+
158+
.. code-block:: xml
159+
160+
<!-- app/config/config.xml -->
161+
<?xml version="1.0" charset="UTF-8" ?>
162+
<container xmlns="http://symfony.com/schema/dic/services"
163+
xmlns:assetic="http://symfony.com/schema/dic/assetic">
164+
165+
<assetic:config>
166+
<filter name="jsqueeze" />
167+
<!-- ... -->
168+
</assetic:config>
169+
</container>
170+
171+
.. code-block:: php
172+
173+
// app/config/config.php
174+
$container->loadFromExtension('assetic', array(
175+
'filters' => array(
176+
'jsqueeze' => null,
177+
// ...
178+
),
179+
));
180+
181+
Then, update the code of your Twig template to add the ``{% javascripts %}`` tag
182+
defined by Assetic:
183+
184+
.. code-block:: html+jinja
185+
186+
<!-- ... -->
187+
188+
{% javascripts filter="?jsqueeze" output="js/app.js"
189+
"assets/js/jquery.js"
190+
"assets/js/bootstrap.js"
191+
"assets/js/main.js"
192+
%}
193+
<script src="{{ asset_url }}"></script>
194+
{% endjavascripts %}
195+
196+
</body>
197+
</html>
198+
199+
This simple configuration combines all the JavaScript files, minimizes the contents
200+
and saves the output in the ``web/js/app.js`` file, which is the one that is
201+
served to your visitors.
202+
203+
The leading ``?`` character in the ``jsqueeze`` filter name indicates that it must
204+
be applied only when the ``debug`` mode is disabled in the application, which
205+
usually occurs in the production environment.

‎cookbook/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
* :doc:`/cookbook/assetic/index`
22

33
* :doc:`/cookbook/assetic/asset_management`
4+
* :doc:`/cookbook/assetic/php`
45
* :doc:`/cookbook/assetic/uglifyjs`
56
* :doc:`/cookbook/assetic/yuicompressor`
67
* :doc:`/cookbook/assetic/jpeg_optimize`

0 commit comments

Comments
 (0)