Skip to content

Commit 86da338

Browse files
javiereguiluzjaviereguiluz
committed
Proposed a new article about using pure PHP libraries with Assetic
1 parent 73ccc8b commit 86da338

File tree

3 files changed

+162
-0
lines changed

3 files changed

+162
-0
lines changed

‎cookbook/frontend/assetic_php.rst

+156
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
.. index::
2+
single: Front-end; Assetic, Bootstrap
3+
4+
Combining, Compiling and Minimizing Web Assets with Pure PHP Libraries
5+
======================================================================
6+
7+
The official Symfony Best Practices recommend to use Assetic to
8+
:doc:`manage web assets </best_practices/web-assets.rst>`, unless you are
9+
comfortable with JavaScript-based frontend 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 SCSS files using pure PHP 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 very common scenario of using the Bootstrap framework, the
43+
jQuery library, the FontAwesome icon font 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+
.. code-block:: yaml
80+
81+
# app/config/config.yml
82+
assetic:
83+
filters:
84+
scssphp:
85+
formatter: "Leafo\\ScssPhp\\Formatter\\Compressed"
86+
# ...
87+
88+
The value of the ``formatter`` option is the fully qualified class name of the
89+
formatter used by the filter to produce the compiled CSS file. Using the
90+
compressed formatter allows to minimize the resulting file, no matter if the
91+
original files are regular CSS files or SCSS files.
92+
93+
Then, update the code of your Twig template to add the ``{% stylesheets %}`` tag
94+
defined by Assetic:
95+
96+
.. code-block:: jinja+html
97+
98+
<!DOCTYPE html>
99+
<html>
100+
<head>
101+
<!-- ... -->
102+
103+
{% stylesheets filter="?scssphp" output="css/app.css"
104+
"assets/scss/bootstrap.scss"
105+
"assets/scss/font-awesome.scss"
106+
"assets/css/*.css"
107+
%}
108+
<link rel="stylesheet" href="{{ asset_url }}" />
109+
{% endstylesheets %}
110+
111+
This simple configuration compiles the SCSS files into regular CSS files, combines
112+
all of them, minimizes the contents and saves the output in the ``web/css/app.css``
113+
file, which is the one that is served to your visitors.
114+
115+
The leading ``?`` character in the ``scssphp`` filter name indicates that it must
116+
be applied only when the ``debug`` mode is disabled in the application, which
117+
usually occurs in the production environment.
118+
119+
Combining and Minimizing JavaScript Files
120+
-----------------------------------------
121+
122+
First, configure a new ``jsqueeze`` Assetic filter as follows:
123+
124+
.. code-block:: yaml
125+
126+
# app/config/config.yml
127+
assetic:
128+
filters:
129+
jsqueeze: ~
130+
# ...
131+
132+
Then, update the code of your Twig template to add the ``{% javascripts %}`` tag
133+
defined by Assetic:
134+
135+
.. code-block:: jinja+html
136+
137+
<!-- ... -->
138+
139+
{% javascripts filter="?jsqueeze" output="js/app.js"
140+
"assets/js/jquery.js"
141+
"assets/js/bootstrap.js"
142+
"assets/js/main.js"
143+
%}
144+
<script src="{{ asset_url }}"></script>
145+
{% endjavascripts %}
146+
147+
</body>
148+
</html>
149+
150+
This simple configuration combines all the JavaScript files, minimizes the contents
151+
and saves the output in the ``web/js/app.js`` file, which is the one that is
152+
served to your visitors.
153+
154+
Similarly to the ``scssphp`` filter, the leading ``?`` character in the ``jsqueeze``
155+
filter name indicates that it must be applied only when the ``debug`` mode is
156+
disabled in the application, which usually occurs in the production environment.

‎cookbook/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ The Cookbook
1717
email/index
1818
event_dispatcher/index
1919
form/index
20+
frontend/index
2021
logging/index
2122
profiler/index
2223
request/index

‎cookbook/map.rst.inc

+5
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,11 @@
107107
* (validation) :doc:`/cookbook/validation/custom_constraint`
108108
* (doctrine) :doc:`/cookbook/doctrine/file_uploads`
109109

110+
111+
* :doc:`/cookbook/frontend/index`
112+
113+
* :doc:`/cookbook/frontend/assetic_php`
114+
110115
* :doc:`/cookbook/logging/index`
111116

112117
* :doc:`/cookbook/logging/monolog`

0 commit comments

Comments
 (0)