]> Raphaƫl G. Git Repositories - packbundle/blob - README.md
Version 0.5.0
[packbundle] / README.md
1 Contribute
2 ==========
3
4 You may buy me a Beer, a Tea or help with Server fees with a paypal donation to
5 the address <paypal@rapsys.eu>.
6
7 Don't forget to show your love for this project, feel free to report bugs to
8 the author, issues which are security relevant should be disclosed privately
9 first.
10
11 Patches are welcomed and grant credit when requested.
12
13 Installation
14 ============
15
16 Applications that use Symfony Flex
17 ----------------------------------
18
19 Add bundle custom repository to your project's `composer.json` file:
20
21 ```json
22 {
23 ...,
24 "repositories": [
25 {
26 "type": "package",
27 "package": {
28 "name": "rapsys/packbundle",
29 "version": "dev-master",
30 "source": {
31 "type": "git",
32 "url": "https://git.rapsys.eu/packbundle",
33 "reference": "master"
34 },
35 "autoload": {
36 "psr-4": {
37 "Rapsys\\PackBundle\\": ""
38 }
39 },
40 "require": {
41 "symfony/asset": "^4.0|^5.0|^6.0|^7.0",
42 "symfony/flex": "^1.0|^2.0",
43 "symfony/framework-bundle": "^4.0|^5.0|^6.0|^7.0",
44 "symfony/process": "^4.0|^5.0|^6.0|^7.0",
45 "symfony/twig-bundle": "^4.0|^5.0|^6.0|^7.0"
46 }
47 }
48 }
49 ],
50 ...
51 }
52 ```
53
54 Then open a command console, enter your project directory and execute:
55
56 ```console
57 $ composer require rapsys/packbundle dev-master
58 ```
59
60 Applications that don't use Symfony Flex
61 ----------------------------------------
62
63 ### Step 1: Download the Bundle
64
65 Open a command console, enter your project directory and execute the
66 following command to download the latest stable version of this bundle:
67
68 ```console
69 $ composer require rapsys/packbundle dev-master
70 ```
71
72 This command requires you to have Composer installed globally, as explained
73 in the [installation chapter](https://getcomposer.org/doc/00-intro.md)
74 of the Composer documentation.
75
76 ### Step 2: Enable the Bundle
77
78 Then, enable the bundle by adding it to the list of registered bundles
79 in the `app/AppKernel.php` file of your project:
80
81 ```php
82 <?php
83 // app/AppKernel.php
84
85 // ...
86 class AppKernel extends Kernel
87 {
88 public function registerBundles()
89 {
90 $bundles = array(
91 // ...
92 new Rapsys\PackBundle\RapsysPackBundle(),
93 );
94
95 // ...
96 }
97
98 // ...
99 }
100 ```
101
102 ### Step 3: Configure the Bundle
103
104 Setup configuration file `config/packages/rapsys_pack.yaml` with the following
105 content available in `Resources/config/packages/rapsys_pack.yaml`:
106
107 ```yaml
108 #Services configuration
109 services:
110 #Replace assets.packages definition
111 assets.packages:
112 class: 'Symfony\Component\Asset\Packages'
113 arguments: [ '@rapsys_pack.path_package' ]
114 #Replace assets.context definition
115 assets.context:
116 class: 'Rapsys\PackBundle\Context\RequestStackContext'
117 arguments: [ '@request_stack', '%asset.request_context.base_path%', '%asset.request_context.secure%' ]
118 #Register assets pack package
119 rapsys_pack.path_package:
120 class: 'Rapsys\PackBundle\Package\PathPackage'
121 arguments: [ '/', '@assets.empty_version_strategy', '@assets.context' ]
122 public: true
123 #Register twig pack extension
124 rapsys_pack.pack_extension:
125 class: 'Rapsys\PackBundle\Extension\PackExtension'
126 arguments: [ '@service_container', '@rapsys_pack.intl_util', '@file_locator', '@rapsys_pack.path_package', '@rapsys_pack.slugger_util' ]
127 tags: [ 'twig.extension' ]
128 #Register intl util service
129 rapsys_pack.intl_util:
130 class: 'Rapsys\PackBundle\Util\IntlUtil'
131 public: true
132 #Register facebook event subscriber
133 Rapsys\PackBundle\Subscriber\FacebookSubscriber:
134 arguments: [ '@router', [] ]
135 tags: [ 'kernel.event_subscriber' ]
136 #Register intl util class alias
137 Rapsys\PackBundle\Util\IntlUtil:
138 alias: 'rapsys_pack.intl_util'
139 #Register facebook util service
140 rapsys_pack.facebook_util:
141 class: 'Rapsys\PackBundle\Util\FacebookUtil'
142 arguments: [ '@router', '%kernel.project_dir%/var/cache', '%rapsys_pack.path%' ]
143 public: true
144 #Register facebook util class alias
145 Rapsys\PackBundle\Util\FacebookUtil:
146 alias: 'rapsys_pack.facebook_util'
147 #Register image util service
148 rapsys_pack.image_util:
149 class: 'Rapsys\PackBundle\Util\ImageUtil'
150 arguments: [ '@router', '@rapsys_pack.slugger_util', '%kernel.project_dir%/var/cache', '%rapsys_pack.path%' ]
151 public: true
152 #Register image util class alias
153 Rapsys\PackBundle\Util\ImageUtil:
154 alias: 'rapsys_pack.image_util'
155 #Register map util service
156 rapsys_pack.map_util:
157 class: 'Rapsys\PackBundle\Util\MapUtil'
158 arguments: [ '@router', '@rapsys_pack.slugger_util' ]
159 public: true
160 #Register map util class alias
161 Rapsys\PackBundle\Util\MapUtil:
162 alias: 'rapsys_pack.map_util'
163 #Register slugger util service
164 rapsys_pack.slugger_util:
165 class: 'Rapsys\PackBundle\Util\SluggerUtil'
166 arguments: [ '%kernel.secret%' ]
167 public: true
168 #Register slugger util class alias
169 Rapsys\PackBundle\Util\SluggerUtil:
170 alias: 'rapsys_pack.slugger_util'
171 #Register image controller
172 Rapsys\PackBundle\Controller\ImageController:
173 arguments: [ '@service_container', '@rapsys_pack.image_util', '@rapsys_pack.slugger_util', '%kernel.project_dir%/var/cache', '%rapsys_pack.path%' ]
174 tags: [ 'controller.service_arguments' ]
175 #Register map controller
176 Rapsys\PackBundle\Controller\MapController:
177 arguments: [ '@service_container', '@rapsys_pack.map_util', '@rapsys_pack.slugger_util', '%kernel.project_dir%/var/cache', '%rapsys_pack.path%' ]
178 tags: [ 'controller.service_arguments' ]
179 Rapsys\PackBundle\Form\CaptchaType:
180 arguments: [ '@rapsys_pack.image_util', '@rapsys_pack.slugger_util', '@translator' ]
181 tags: [ 'form.type' ]
182 ```
183
184 Setup configuration file `config/packages/myproject.yaml` with the following
185 content available in `Resources/config/packages/rapsys_pack.yaml`:
186
187 ```yaml
188 #Services configuration
189 services:
190 #Register facebook event subscriber
191 Rapsys\PackBundle\Subscriber\FacebookSubscriber:
192 arguments: [ '@router', [ 'en', 'en_gb', 'en_us', 'fr', 'fr_fr' ] ]
193 tags: [ 'kernel.event_subscriber' ]
194 #Register facebook util service
195 rapsys_blog.facebook_util:
196 class: 'Rapsys\PackBundle\Util\FacebookUtil'
197 arguments: [ '@router', '%kernel.project_dir%/var/cache', '%rapsys_pack.path%', 'facebook', '%kernel.project_dir%/public/png/facebook.png' ]
198 public: true
199 ```
200
201 Open a command console, enter your project directory and execute the following
202 command to see default bundle configuration:
203
204 ```console
205 $ bin/console config:dump-reference RapsysPackBundle
206 ```
207
208 Open a command console, enter your project directory and execute the following
209 command to see current bundle configuration:
210
211 ```console
212 $ bin/console debug:config RapsysPackBundle
213 ```
214
215 ### Step 4: Use the twig extension in your Template
216
217 You can use a template like this to generate your first `rapsys_pack` enabled
218 template:
219
220 ```twig
221 <!DOCTYPE html>
222 <html>
223 <head>
224 <meta charset="UTF-8" />
225 <title>{% block title %}Welcome!{% endblock %}</title>
226 {% stylesheet '//fonts.googleapis.com/css?family=Irish+Grover|La+Belle+Aurore' '@NamedBundle/Resources/public/css/{reset,screen}.css' '@Short/css/example.css' %}
227 <link rel="stylesheet" type="text/css" href="{{ asset_url }}" />
228 {% endstylesheet %}
229 </head>
230 <body>
231 {% block body %}{% endblock %}
232 {% javascript '@Short/js/*.js' %}
233 <script type="text/javascript" src="{{ asset_url }}"></script>
234 {% endjavascript %}
235 </body>
236 </html>
237 ```
238
239 ### Step 5: Make sure you have local binary installed
240
241 You need to have cpack and jpack scripts from https://git.rapsys.eu/packer/ repository
242 set as executable and installed in /usr/local/bin.
243
244 To install cpack and jpack required packages open a root console and execute the
245 following command:
246
247 ```console
248 # urpmi perl-base perl-CSS-Packer perl-JavaScript-Packer
249 ```
250
251 or stone age distributions:
252
253 ```console
254 # apt-get install libcss-packer-perl libjavascript-packer-perl
255 ```
256
257 or other distributions through cpan:
258
259 ```console
260 # cpan App::cpanminus
261 # cpanm CSS::Packer
262 # cpanm JavaScript::Packer
263 ```
264
265 ### Step 6: Create your own filter
266
267 You can create you own mypackfilter class which call a mypack binary:
268
269 ```php
270 <?php
271
272 namespace Rapsys\PackBundle\Filter;
273
274 use Twig\Error\Error;
275
276 //This class will be defined in the parameter rapsys_pack.filters.(css|img|js).[x].class string
277 class MyPackFilter implements FilterInterface {
278 //The constructor arguments ... will be replaced with values defined in the parameter rapsys_pack.filters.(css|img|js).[x].args array
279 public function __construct(string $fileName, int $line, string $bin = 'mypack', ...) {
280 //Set fileName
281 $this->fileName = $fileName;
282
283 //Set line
284 $this->line = $line;
285
286 //Set bin
287 $this->bin = $bin;
288
289 //Check argument presence
290 if (!empty($this->...)) {
291 //Append argument
292 if ($this->... == '...') {
293 $this->bin .= ' ...';
294 } else {
295 //Throw an error on ...
296 throw new Error(sprintf('Got ... for %s: %s', $this->bin, $this->...), $this->line, $this->fileName);
297 }
298 }
299 }
300
301 //Pass merge of all inputs in content
302 public function process(string $content): string {
303 //Create descriptors
304 $descriptorSpec = array(
305 0 => array('pipe', 'r'),
306 1 => array('pipe', 'w'),
307 2 => array('pipe', 'w')
308 );
309
310 //Open process
311 if (is_resource($proc = proc_open($this->bin, $descriptorSpec, $pipes))) {
312 //Set stderr as non blocking
313 stream_set_blocking($pipes[2], false);
314
315 //Send content to stdin
316 fwrite($pipes[0], $content);
317
318 //Close stdin
319 fclose($pipes[0]);
320
321 //Read content from stdout
322 if ($stdout = stream_get_contents($pipes[1])) {
323 $content = $stdout;
324 }
325
326 //Close stdout
327 fclose($pipes[1]);
328
329 //Read content from stderr
330 if (($stderr = stream_get_contents($pipes[2]))) {
331 throw new Error(sprintf('Got unexpected strerr for %s: %s', $this->bin, $stderr), $this->line, $this->fileName);
332 }
333
334 //Close stderr
335 fclose($pipes[2]);
336
337 //Close process
338 if (($ret = proc_close($proc))) {
339 throw new Error(sprintf('Got unexpected non zero return code %s: %d', $this->bin, $ret), $this->line, $this->fileName);
340 }
341 }
342
343 //Return content
344 return $content;
345 }
346 }
347 ```
348
349 The class must implements FilterInterface and get it's arguments through constructor.