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