Raphaël G. Git Repositories - packbundle/blob - 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.