]> Raphaƫl G. Git Repositories - packbundle/blob - README.md
3998c89a9180a7667e3146ee3f6a84b2844a429a
[packbundle] / README.md
1 Installation
2 ============
3
4 Applications that use Symfony Flex
5 ----------------------------------
6
7 Add bundle custom repository to your project's `composer.json` file:
8
9 ```json
10 {
11 ...,
12 "repositories": [
13 {
14 "type": "package",
15 "package": {
16 "name": "rapsys/packbundle",
17 "version": "dev-master",
18 "source": {
19 "type": "git",
20 "url": "https://git.rapsys.eu/packbundle",
21 "reference": "master"
22 },
23 "autoload": {
24 "psr-4": {
25 "Rapsys\\PackBundle\\": ""
26 }
27 },
28 "require": {
29 "symfony/asset": "^4.4",
30 "symfony/flex": "^1.5",
31 "symfony/framework-bundle": "^4.4",
32 "symfony/process": "^4.4",
33 "symfony/twig-bundle": "^4.4",
34 "twig/extensions": "^1.5"
35 }
36 }
37 }
38 ],
39 ...
40 }
41 ```
42
43 Then open a command console, enter your project directory and execute:
44
45 ```console
46 $ composer require rapsys/packbundle dev-master
47 ```
48
49 Applications that don't use Symfony Flex
50 ----------------------------------------
51
52 ### Step 1: Download the Bundle
53
54 Open a command console, enter your project directory and execute the
55 following command to download the latest stable version of this bundle:
56
57 ```console
58 $ composer require rapsys/packbundle dev-master
59 ```
60
61 This command requires you to have Composer installed globally, as explained
62 in the [installation chapter](https://getcomposer.org/doc/00-intro.md)
63 of the Composer documentation.
64
65 ### Step 2: Enable the Bundle
66
67 Then, enable the bundle by adding it to the list of registered bundles
68 in the `app/AppKernel.php` file of your project:
69
70 ```php
71 <?php
72 // app/AppKernel.php
73
74 // ...
75 class AppKernel extends Kernel
76 {
77 public function registerBundles()
78 {
79 $bundles = array(
80 // ...
81 new Rapsys\PackBundle\RapsysPackBundle(),
82 );
83
84 // ...
85 }
86
87 // ...
88 }
89 ```
90
91 ### Step 3: Configure the Bundle
92
93 Setup configuration file `config/packages/rapsys_pack.yaml` with the following
94 content available in `Resources/config/packages/rapsys_pack.yaml`:
95
96 ```yaml
97 #Services configuration
98 services:
99 #Replace assets.packages definition
100 assets.packages:
101 class: 'Symfony\Component\Asset\Packages'
102 arguments: [ '@rapsys_pack.path_package' ]
103 #Replace assets.context definition
104 assets.context:
105 class: 'Rapsys\PackBundle\Context\RequestStackContext'
106 arguments: [ '@request_stack', '%asset.request_context.base_path%', '%asset.request_context.secure%' ]
107 #Register assets pack package
108 rapsys_pack.path_package:
109 class: 'Rapsys\PackBundle\Package\PathPackage'
110 arguments: [ '/', '@assets.empty_version_strategy', '@assets.context' ]
111 public: true
112 #Register twig pack extension
113 rapsys_pack.pack_extension:
114 class: 'Rapsys\PackBundle\Extension\PackExtension'
115 arguments: [ '@file_locator', '@service_container', '@rapsys_pack.path_package', '@rapsys_pack.slugger_util' ]
116 tags: [ 'twig.extension' ]
117 #Register slugger util service
118 rapsys_pack.slugger_util:
119 class: 'Rapsys\PackBundle\Util\SluggerUtil'
120 arguments: [ '%kernel.secret%' ]
121 public: true
122 #Register slugger util class alias
123 Rapsys\PackBundle\Util\SluggerUtil:
124 alias: 'rapsys_pack.slugger_util'
125 ```
126
127 Open a command console, enter your project directory and execute the following
128 command to see default bundle configuration:
129
130 ```console
131 $ php bin/console config:dump-reference RapsysPackBundle
132 ```
133
134 Open a command console, enter your project directory and execute the following
135 command to see current bundle configuration:
136
137 ```console
138 $ php bin/console debug:config RapsysPackBundle
139 ```
140
141 ### Step 4: Use the twig extension in your Template
142
143 You can use a template like this to generate your first `rapsys_pack` enabled
144 template:
145
146 ```twig
147 <!DOCTYPE html>
148 <html>
149 <head>
150 <meta charset="UTF-8" />
151 <title>{% block title %}Welcome!{% endblock %}</title>
152 {% stylesheet '//fonts.googleapis.com/css?family=Irish+Grover|La+Belle+Aurore' '@NamedBundle/Resources/public/css/{reset,screen}.css' '@Short/css/example.css' %}
153 <link rel="stylesheet" type="text/css" href="{{ asset_url }}" />
154 {% endstylesheet %}
155 </head>
156 <body>
157 {% block body %}{% endblock %}
158 {% javascript '@Short/js/*.js' %}
159 <script type="text/javascript" src="{{ asset_url }}"></script>
160 {% endjavascript %}
161 </body>
162 </html>
163 ```
164
165 ### Step 5: Make sure you have local binary installed
166
167 You need to have cpack and jpack scripts from https://git.rapsys.eu/packer/ repository
168 set as executable and installed in /usr/local/bin.
169
170 To install cpack and jpack required packages open a root console and execute the
171 following command:
172
173 ```console
174 # urpmi perl-base perl-CSS-Packer perl-JavaScript-Packer
175 ```
176
177 or stone age distributions:
178
179 ```console
180 # apt-get install libcss-packer-perl libjavascript-packer-perl
181 ```
182
183 or other distributions through cpan:
184
185 ```console
186 # cpan App::cpanminus
187 # cpanm CSS::Packer
188 # cpanm JavaScript::Packer
189 ```
190
191 ### Step 6: Create your own filter
192
193 You can create you own mypackfilter class which call a mypack binary:
194
195 ```php
196 <?php
197
198 namespace Rapsys\PackBundle\Filter;
199
200 use Twig\Error\Error;
201
202 //This class will be defined in the parameter rapsys_pack.filters.(css|img|js).[x].class string
203 class MyPackFilter implements FilterInterface {
204 //The constructor arguments ... will be replaced defined in the parameter rapsys_pack.filters.(css|img|js).[x].args array
205 public function __construct(string $fileName, int $line, string $bin = 'mypack', ...) {
206 //Set fileName
207 $this->fileName = $fileName;
208
209 //Set line
210 $this->line = $line;
211
212 //Set bin
213 $this->bin = $bin;
214
215 //Check argument presence
216 if (!empty($this->...)) {
217 //Append argument
218 if ($this->... == '...') {
219 $this->bin .= ' ...';
220 } else {
221 //Throw an error on ...
222 throw new Error(sprintf('Got ... for %s: %s', $this->bin, $this->...), $this->line, $this->fileName);
223 }
224 }
225 }
226
227 //Pass merge of all inputs in content
228 public function process(string $content): string {
229 //Create descriptors
230 $descriptorSpec = array(
231 0 => array('pipe', 'r'),
232 1 => array('pipe', 'w'),
233 2 => array('pipe', 'w')
234 );
235
236 //Open process
237 if (is_resource($proc = proc_open($this->bin, $descriptorSpec, $pipes))) {
238 //Set stderr as non blocking
239 stream_set_blocking($pipes[2], false);
240
241 //Send content to stdin
242 fwrite($pipes[0], $content);
243
244 //Close stdin
245 fclose($pipes[0]);
246
247 //Read content from stdout
248 if ($stdout = stream_get_contents($pipes[1])) {
249 $content = $stdout;
250 }
251
252 //Close stdout
253 fclose($pipes[1]);
254
255 //Read content from stderr
256 if (($stderr = stream_get_contents($pipes[2]))) {
257 throw new Error(sprintf('Got unexpected strerr for %s: %s', $this->bin, $stderr), $this->line, $this->fileName);
258 }
259
260 //Close stderr
261 fclose($pipes[2]);
262
263 //Close process
264 if (($ret = proc_close($proc))) {
265 throw new Error(sprintf('Got unexpected non zero return code %s: %d', $this->bin, $ret), $this->line, $this->fileName);
266 }
267 }
268
269 //Return content
270 return $content;
271 }
272 }
273 ```
274
275 The class must implements FilterInterface and get it's arguments through constructor.