Raphaël G. Git Repositories - packbundle/blob - 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",
  42                                         "symfony/flex": "^1.0",
  43                                         "symfony/framework-bundle": "^4.0|^5.0",
  44                                         "symfony/process": "^4.0|^5.0",
  45                                         "symfony/twig-bundle": "^4.0|^5.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', '%rapsys_air.locales%' ]
 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 Open a command console, enter your project directory and execute the following
 185 command to see default bundle configuration:
 186
 187 ```console
 188 $ php bin/console config:dump-reference RapsysPackBundle
 189 ```
 190
 191 Open a command console, enter your project directory and execute the following
 192 command to see current bundle configuration:
 193
 194 ```console
 195 $ php bin/console debug:config RapsysPackBundle
 196 ```
 197
 198 ### Step 4: Use the twig extension in your Template
 199
 200 You can use a template like this to generate your first `rapsys_pack` enabled
 201 template:
 202
 203 ```twig
 204 <!DOCTYPE html>
 205 <html>
 206         <head>
 207                 <meta charset="UTF-8" />
 208                 <title>{% block title %}Welcome!{% endblock %}</title>
 209                 {% stylesheet '//fonts.googleapis.com/css?family=Irish+Grover|La+Belle+Aurore' '@NamedBundle/Resources/public/css/{reset,screen}.css' '@Short/css/example.css' %}
 210                         <link rel="stylesheet" type="text/css" href="{{ asset_url }}" />
 211                 {% endstylesheet %}
 212         </head>
 213         <body>
 214                 {% block body %}{% endblock %}
 215                 {% javascript '@Short/js/*.js' %}
 216                         <script type="text/javascript" src="{{ asset_url }}"></script>
 217                 {% endjavascript %}
 218         </body>
 219 </html>
 220 ```
 221
 222 ### Step 5: Make sure you have local binary installed
 223
 224 You need to have cpack and jpack scripts from https://git.rapsys.eu/packer/ repository
 225 set as executable and installed in /usr/local/bin.
 226
 227 To install cpack and jpack required packages open a root console and execute the
 228 following command:
 229
 230 ```console
 231 # urpmi perl-base perl-CSS-Packer perl-JavaScript-Packer
 232 ```
 233
 234 or stone age distributions:
 235
 236 ```console
 237 # apt-get install libcss-packer-perl libjavascript-packer-perl
 238 ```
 239
 240 or other distributions through cpan:
 241
 242 ```console
 243 # cpan App::cpanminus
 244 # cpanm CSS::Packer
 245 # cpanm JavaScript::Packer
 246 ```
 247
 248 ### Step 6: Create your own filter
 249
 250 You can create you own mypackfilter class which call a mypack binary:
 251
 252 ```php
 253 <?php
 254
 255 namespace Rapsys\PackBundle\Filter;
 256
 257 use Twig\Error\Error;
 258
 259 //This class will be defined in the parameter rapsys_pack.filters.(css|img|js).[x].class string
 260 class MyPackFilter implements FilterInterface {
 261         //The constructor arguments ... will be replaced defined in the parameter rapsys_pack.filters.(css|img|js).[x].args array
 262         public function __construct(string $fileName, int $line, string $bin = 'mypack', ...) {
 263                 //Set fileName
 264                 $this->fileName = $fileName;
 265
 266                 //Set line
 267                 $this->line = $line;
 268
 269                 //Set bin
 270                 $this->bin = $bin;
 271
 272                 //Check argument presence
 273                 if (!empty($this->...)) {
 274                         //Append argument
 275                         if ($this->... == '...') {
 276                                 $this->bin .= ' ...';
 277                         } else {
 278                                 //Throw an error on ...
 279                                 throw new Error(sprintf('Got ... for %s: %s', $this->bin, $this->...), $this->line, $this->fileName);
 280                         }
 281                 }
 282         }
 283
 284         //Pass merge of all inputs in content
 285         public function process(string $content): string {
 286                 //Create descriptors
 287                 $descriptorSpec = array(
 288                         0 => array('pipe', 'r'),
 289                         1 => array('pipe', 'w'),
 290                         2 => array('pipe', 'w')
 291                 );
 292
 293                 //Open process
 294                 if (is_resource($proc = proc_open($this->bin, $descriptorSpec, $pipes))) {
 295                         //Set stderr as non blocking
 296                         stream_set_blocking($pipes[2], false);
 297
 298                         //Send content to stdin
 299                         fwrite($pipes[0], $content);
 300
 301                         //Close stdin
 302                         fclose($pipes[0]);
 303
 304                         //Read content from stdout
 305                         if ($stdout = stream_get_contents($pipes[1])) {
 306                                 $content = $stdout;
 307                         }
 308
 309                         //Close stdout
 310                         fclose($pipes[1]);
 311
 312                         //Read content from stderr
 313                         if (($stderr = stream_get_contents($pipes[2]))) {
 314                                 throw new Error(sprintf('Got unexpected strerr for %s: %s', $this->bin, $stderr), $this->line, $this->fileName);
 315                         }
 316
 317                         //Close stderr
 318                         fclose($pipes[2]);
 319
 320                         //Close process
 321                         if (($ret = proc_close($proc))) {
 322                                 throw new Error(sprintf('Got unexpected non zero return code %s: %d', $this->bin, $ret), $this->line, $this->fileName);
 323                         }
 324                 }
 325
 326                 //Return content
 327                 return $content;
 328         }
 329 }
 330 ```
 331
 332 The class must implements FilterInterface and get it's arguments through constructor.