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|^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 $ php 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 $ php 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.