Assets Management

Assets - 图1

Overview

Phalcon\Assets is a component that allows you to manage static assets such as CSS stylesheets or JavaScript libraries in a web application.

Phalcon\Assets\Manager is the component you can use to register your assets and use them throughout your application. If you are using the Phalcon\Di\FactoryDefault container, the Assets Manager is already registered for you. You can access it using the assets key from your Di container.

  1. <?php
  3. use Phalcon\Di\FactoryDefault();
  5. $container = new FactoryDefault();
  6. $manager   = $container->get('assets')

Assets

Assets can be added to the manager or a collection using the Asset related classes. The Assets class. The object accepts the necessary data to create the asset.

  • type: can be css, js or something else, depending on whether you want to extend the functionality of the component.
  • path : the path of the asset
  • local: whether this is a local asset or not
  • filter: any filter attached to this asset
  • attributes: attributes relative to the asset
  • version: version of the asset
  • autoVersion: let the component auto version this asset or not
  1. <?php
  3. use Phalcon\Assets\Asset;
  5. $asset = new Asset(
  6.     'css',
  7.     'css/bootstrap.css',
  8.     true,
  9.     null,
  10.     [],
  11.     '1.0',
  12.     true
  13. );

CSS

You can also use the CSS class to create a CSS asset. This class is a helper class that extends the Asset class and internally sets the first parameter to css.

  1. <?php
  3. use Phalcon\Assets\Asset\Css;
  5. $asset = new Css(
  6.     'css/bootstrap.css',
  7.     true,
  8.     null,
  9.     [],
  10.     '1.0',
  11.     true
  12. );

JS

You can also use the JS class to create a JS asset. This class is a helper class that extends the Asset class and internally sets the first parameter to js.

  1. <?php
  3. use Phalcon\Assets\Asset\Js;
  5. $asset = new Js(
  6.     'js/bootstrap.js',
  7.     true,
  8.     null,
  9.     [],
  10.     '1.0',
  11.     true
  12. );

Inline

There are times that the application needs generated CSS or JS to be injected into the view. You can use the Inline class to generate this content. The object can be created with the following parameters:

  • type: can be css, js or something else, depending on whether you want to extend the functionality of the component.
  • content: the content to be injected
  • filter: any filter attached to this asset
  • attributes: attributes relative to the asset
  1. <?php
  3. use Phalcon\Assets\Inline;
  5. $asset = new Inline(
  6.     'css',
  7.     '.spinner {color: blue; }'
  8. );

CSS

You can also use the CSS class to create an inline CSS asset. This class is a helper class that extends the InlineAsset class and internally sets the first parameter to css.

  1. <?php
  3. use Phalcon\Assets\Inline\Css;
  5. $asset = new Css(
  6.     '.spinner {color: blue; }'
  7. );

JS

You can also use the JS class to create an inline JS asset. This class is a helper class that extends the Inline class and internally sets the first parameter to js.

  1. <?php
  3. use Phalcon\Assets\Asset\Js;
  5. $asset = new Js(
  6.     'alert("hello");'
  7. );

Custom

Implementing the AssetInterface enables you to create different asset classes that can be handled by the Asset Manager.

Exception

Any exceptions thrown in the Assets Manager component will be of type Phalcon\Assets\Exception. You can use this exception to selectively catch exceptions thrown only from this component.

  1. <?php
  3. use Phalcon\Assets\Exception;
  4. use Phalcon\Mvc\Controller;
  6. class IndexController extends Controller
  7. {
  8.     public function index()
  9.     {
  10.         try {
  11.             // Add some local CSS assets
  12.             $this->assets->addCss('css/style.css');
  13.             $this->assets->addCss('css/index.css');
  14.         } catch (Exception $ex) {
  15.             echo $ex->getMessage();
  16.         }
  17.     }
  18. }

Adding Assets

Files

Assets supports two built-in assets: CSS and JavaScript assets. You can also create other asset types if you need. The assets manager internally stores two default collections of assets - one for JavaScript and another for CSS.

You can easily add assets to these collections:

  1. <?php
  3. use Phalcon\Mvc\Controller;
  5. class IndexController extends Controller
  6. {
  7.     public function index()
  8.     {
  9.         // Add some local CSS assets
  10.         $this->assets->addCss('css/style.css');
  11.         $this->assets->addCss('css/index.css');
  13.         // And some local JavaScript assets
  14.         $this->assets->addJs('js/jquery.js');
  15.         $this->assets->addJs('js/bootstrap.min.js');
  16.     }
  17. }

For better page load performance, it is recommended to place JavaScript links at the end of the HTML instead of in the <head> element. However this might not be always feasible based on the Javascript files you need to load and their dependencies.

You can also add assets to the manager by using Asset objects:

  1. <?php
  3. use Phalcon\Assets\Asset\Css;
  4. use Phalcon\Assets\Asset\Js;
  5. use Phalcon\Mvc\Controller;
  7. class IndexController extends Controller
  8. {
  9.     public function index()
  10.     {
  11.         $css1 = new Css('css/style.css');
  12.         $css2 = new Css(('css/index.css');
  14.         $this->assets->addAsset($css1);
  15.         $this->assets->addAssetByType('css', $css2);
  17.         $js1 = new Js('js/jquery.js');
  18.         $js2 = new Js('js/bootstrap.min.js');
  19.         $this->assets->addAsset($css1);
  21.         $this->assets->addAssetByType('css', $css2);
  22.     }
  23. }

Inline

You can also add inline assets to the manager. Inline assets represent strings of CSS or JS that need to be injected in your views dynamically (not from an asset file). addInlineCode(), addInlineCodeByType(), addInlineCss() and addInlineJs() are available for your use.

  1. <?php
  3. use Phalcon\Assets\Manager;
  4. use Phalcon\Assets\Inline;
  6. $css      = '.spinner {color: blue; }';
  7. $js       = 'alert("hello")';
  8. $manager  = new Manager();
  9. $assetCss = new Inline('css', $css};
  10. $assetJs  = new Inline('js', $js};
  12. $manager
  13.     ->addInlineCode($assetCss)
  14.     ->addInlineCode($assetJs)
  15. ;
  17. $manager
  18.     ->addInlineByType('css', $assetCss)
  19.     ->addInlineByType('js', $assetJs)
  20. ;
  22. $manager
  23.     ->addInlineCss($css)
  24.     ->addInlineJs($js)
  25. ;

Local/Remote assets

Local assets are those who are provided by the same application and they are located in a public location (usually public). The URLs for local assets are generated using the url service.

Remote assets are those such as common libraries like jQuery, Bootstrap, etc. that are provided by a CDN.

The second parameter of addCss() and addJs() signifies whether asset is local or not (true is local, false is remote). By default, the assets manager will assume the asset is local:

  1. <?php
  3. public function indexAction()
  4. {
  5.     $this->assets->addCss(
  6.         '//cdn.assets.com/bootstrap/4/css/library.min.css', 
  7.         false
  8.     );
  10.     $this->assets->addCss('css/style.css', true);
  11.     $this->assets->addCss('css/extra.css');
  12. }

Collections

Collections are objects that group assets of the same type. The assets manager implicitly creates two collections: css and js. You can create additional collections to group specific assets to make it easier to place those assets in the views:

  1. <?php
  4. // Javascript - header
  5. $headerCollection = $this->assets->collection('headerJs');
  7. $headerCollection->addJs('js/jquery.js');
  8. $headerCollection->addJs('js/bootstrap.min.js');
  10. // Javascript - footer
  11. $footerCollection = $this->assets->collection('footerJs');
  13. $footerCollection->addJs('js/jquery.js');
  14. $footerCollection->addJs('js/bootstrap.min.js');

Get

The getter methods exposed by the component, allow you to get the collection from anywhere in your code and manipulate it according to your needs. The manager offers get(), getCollection(), getCss() and getJs(). These methods will return back the collection that the manager stores. The getCss() and getJs() will return the built in - pre registered - collections.

The collection() method acts as a creator and getter at the same time. It allows you to create a collection and get it back so that you can then add assets to it. The getCss() and getJs() perform the same function i.e. create the collection if it does not exist and return it. Those two collections set the predefined css and js collections in the manager.

  1. <?php
  3. $headerCollection = $this->assets->collection('headerJs');
  5. $headerCollection = $this->assets->get('headerJs');

Exists

The exists method allows you to check if a particular collection exists in the manager;

  1. <?php
  3. $headerCollection = $this->assets->collection('headerJs');
  5. echo $this->assets->has('headerJs'); // true

Set

If the built in css and js collections are not sufficient for your needs, you can attach a new collection to the manager by using se().

  1. <?php
  3. use Phalcon\Assets\Collection;
  5. $collection = new Collection();
  7. $this->assets->set('outputJs', $collection);

URL Prefixes

Collections can be URL-prefixed, allowing you to change the prefix easily based on the needs of your application. An example of this can be changing from local to production environments and using a different CDN URL for your assets:

  1. <?php
  3. $footerCollection = $this->assets->collection('footer');
  5. if ($config->environment === 'development') {
  6.     $footerCollection->setPrefix('/');
  7. } else {
  8.     $footerCollection->setPrefix('http:://cdn.example.com/');
  9. }
  11. $footerCollection->addJs('js/jquery.js');
  12. $footerCollection->addJs('js/bootstrap.min.js');

You can also chain the method calls if that syntax is more preferable:

  1. <?php
  3. $headerCollection = $this
  4.     ->assets
  5.     ->collection('header')
  6.     ->setPrefix('https://cdn.example.com/')
  7.     ->setLocal(false)
  8.     ->addJs('js/jquery.js')
  9.     ->addJs('js/bootstrap.min.js');

Built-In Filters

Assets can be filtered i.e. manipulated before their output to the view. Although Phalcon v3 offered minifiers for JavaScript and CSS, license limitations do not allow us to continue using those libraries. For v4 we are offering only the None filter (which does not change the asset contents) and the FilterInterface interface, offering the ability to create custom filters.

Custom Filters

Creating custom filters is very easy. You can use this extensibility to take advantage of existing and more advanced filtering/minification tools like YUI, Sass, Closure, etc.:

  1. <?php
  3. use Phalcon\Assets\FilterInterface;
  5. /**
  6.  * Filters CSS content using YUI
  7.  *
  8.  * @param string $contents
  9.  * @return string
  10.  */
  11. class CssYUICompressor implements FilterInterface
  12. {
  13.     protected $options;
  15.     /**
  16.      * CssYUICompressor constructor
  17.      *
  18.      * @param array $options
  19.      */
  20.     public function __construct(array $options)
  21.     {
  22.         $this->options = $options;
  23.     }
  25.     /**
  26.      * @param string $contents
  27.      *
  28.      * @return string
  29.      */
  30.     public function filter($contents)
  31.     {
  32.         // Write the string contents into a temporal file
  33.         file_put_contents('temp/my-temp-1.css', $contents);
  35.         system(
  36.             $this->options['java-bin'] .
  37.             ' -jar ' .
  38.             $this->options['yui'] .
  39.             ' --type css ' .
  40.             'temp/my-temp-file-1.css ' .
  41.             $this->options['extra-options'] .
  42.             ' -o temp/my-temp-file-2.css'
  43.         );
  45.         // Return the contents of file
  46.         return file_get_contents('temp/my-temp-file-2.css');
  47.     }
  48. }

Usage:

  1. <?php
  3. // Get some CSS collection
  4. $css = $this->assets->get('head');
  6. // Add/Enable the YUI compressor filter in the collection
  7. $css->addFilter(
  8.     new CssYUICompressor(
  9.         [
  10.             'java-bin'      => '/usr/local/bin/java',
  11.             'yui'           => '/some/path/yuicompressor-x.y.z.jar',
  12.             'extra-options' => '--charset utf8',
  13.         ]
  14.     )
  15. );

In a previous example, we used a custom filter called LicenseStamper, which adds the license message at the top of the file:

  1. <?php
  3. use Phalcon\Assets\FilterInterface;
  5. /**
  6.  * @param string $contents
  7.  *
  8.  * @return string
  9.  */
  10. class LicenseStamper implements FilterInterface
  11. {
  12.     /**
  13.      * Do the filtering
  14.      *
  15.      * @param string $contents
  16.      * @return string
  17.      */
  18.     public function filter($contents)
  19.     {
  20.         $license = '/* (c) 2019 Your Name Here */';
  22.         return $license . PHP_EOL . PHP_EOL . $contents;
  23.     }
  24. }

Output

After all the assets have been added to their relevant collections you can use the output methods to print HTML in your views. These methods are output(), outputCss(), outputJs(), outputInline(), outputInlineCss() and outputInlineJs().

To output files:

  1. <?php
  3. // Javascript - header
  4. $headerCollection = $this->assets->collection('headerJs');
  6. $headerCollection->addJs('js/jquery.js');
  7. $headerCollection->addJs('js/bootstrap.min.js');
  9. // Javascript - footer
  10. $footerCollection = $this->assets->collection('footerJs');
  12. $footerCollection->addJs('js/jquery.js');
  13. $footerCollection->addJs('js/bootstrap.min.js');

Then in the views:

  1. <html>
  2.     <head>
  3.         <title>Some amazing website</title>
  5.         <?php $this->assets->outputJs('headerJs'); ?>
  6.     </head>
  8.     <body>
  9.         <!-- ... -->
  11.         <?php $this->assets->outputJs('footerJs'); ?>
  12.     </body>
  13. <html>

Volt syntax:

  1. <html>
  2.     <head>
  3.         <title>Some amazing website</title>
  5.         {{ assets.outputCss('header') }}
  6.     </head>
  8.     <body>
  9.         <!-- ... -->
  11.         {{ assets.outputJs('footer') }}
  12.     </body>
  13. <html>

To output inline:

  1. <?php
  3. $css      = '.spinner {color: blue; }';
  4. $js       = 'alert("hello")';
  5. $assetCss = new Inline('css', $css};
  6. $assetJs  = new Inline('js', $js};
  8. $this
  9.     ->assets
  10.     ->addInlineCss($css)
  11.     ->addInlineJs($js)
  12. ;

Then in the views:

  1. <html>
  2.     <head>
  3.         <title>Some amazing website</title>
  4.     </head>
  5.     <?php $this->assets->outputInlineCss(); ?>
  6.     <body>
  8.         <!-- ... -->
  10.         <?php $this->assets->outputInlineJs(); ?>
  11.     </body>
  12. <html>

Volt syntax:

  1. <html>
  2.     <head>
  3.         <title>Some amazing website</title>
  5.         {{ assets.outputInlineCss() }}
  6.     </head>
  8.     <body>
  9.         <!-- ... -->
  11.         {{ assets.outputInlineJs() }}
  12.     </body>
  13. <html>

The lines above will be translated to:

  1. <html>
  2.     <head>
  3.         <title>Some amazing website</title>
  5.         <style>.spinner {color: blue; }</style>
  6.     </head>
  8.     <body>
  9.         <!-- ... -->
  11.         <script type="application/javascript">alert("hello")</script>
  12.     </body>
  13. <html>

Custom Output

The outputJs() and outputCss() methods are available to generate the necessary HTML code according to each type of assets. You can override this method or print the assets manually in the following way:

  1. <?php
  3. use Phalcon\Tag;
  5. $jsCollection = $this->assets->collection('js');
  7. foreach ($jsCollection as $asset) {
  8.     echo Tag::javascriptInclude(
  9.         $asset->getPath()
  10.     );
  11. }

Implicit vs Explicit output

There are times that you might need to implicitly output the output of the manager. To do this, you can use the useImplicitOutput() method. Calling output() after that will echo the HTML on the screen.

  1. <?php
  3. $this
  4.     ->assets
  5.     ->useImplicitOutput(true)
  6.     ->addCss('css/style.css')
  7.     ->output()
  8. ;

Versioning

The Assets components also support versioning (automatic or manual). Versioning of assets is also known as cache busting. In short, CSS and JS files can easily be cached at the browser level. As such any updates that are pushed to the production system with a release, could include updated CSS and JS files. Since browsers cache those assets, the updated content will not be delivered to the user’s browser immediately, resulting in potential loss of functionality. By versioning assets, we ensure that the browsers are instructed to download the asset files again and thus receive the latest CSS and JS code from the server.

To add a version number to your assets, you need to add the version string while creating the asset object:

  1. <?php
  3. use Phalcon\Assets\Asset\Css;
  5. $asset = new Css(
  6.     'css/bootstrap.css',
  7.     true,
  8.     null,
  9.     [],
  10.     '1.0'
  11. );

The above will result in the following script as the output:

  1. <link rel="stylesheet" href="css/bootstrap.css?ver=1.0"

You can then store the version in your configuration file or any other storage and update it when a new release is pushed to production.

Auto versioning

You can also use the file time of the asset file to control the versioning of your assets.

  1. <?php
  3. use Phalcon\Assets\Asset\Css;
  5. $asset = new Css(
  6.     'css/bootstrap.css',
  7.     true,
  8.     null,
  9.     [],
  10.     null,
  11.     true
  12. );

The above will result in the following script as the output (assuming that your file was modified in May 20th 2019):Assuming that your file was last modified in May 20, the version

  1. <link rel="stylesheet" href="css/bootstrap.css?ver=1558392141">

NOTE Using the auto version feature is not recommended for production environments, since Phalcon will need to read the modification time of the asset file for every request. This will result to unecessary read operations on the file system.

Improving performance

There are many ways to optimize processing assets. One method is to allow your web server to handle the assets, thus improving response time. First we need to set up the Assets Manager. We will use a base controller, but you can use the manager anywhere you need to, accessing it from the Di container:

  1. <?php
  3. namespace App\Controllers;
  5. use Phalcon\Mvc\Controller;
  7. /**
  8.  * App\Controllers\ControllerBase
  9.  *
  10.  * This is the base controller for all controllers in the application.
  11.  */
  12. class ControllerBase extends Controller
  13. {
  14.     public function onConstruct()
  15.     {
  16.         $this
  17.             ->assets
  18.             ->useImplicitOutput(false)
  19.             ->collection('global')
  20.             ->addJs('https://code.jquery.com/jquery-4.0.1.js', false, true)
  21.         ;
  22.     }
  23. }

Then we need to configure the routing:

  1. <?php
  3. /**
  4.  * Define custom routes.
  5.  * This file gets included in the router service definition.
  6.  */
  7. $router = new Phalcon\Mvc\Router();
  9. $router->addGet(
  10.     '/assets/(css|js)/([\w.-]+)\.(css|js)',
  11.     [
  12.         'controller' => 'assets',
  13.         'action'     => 'serve',
  14.         'type'       => 1,
  15.         'collection' => 2,
  16.         'extension'  => 3,
  17.     ]
  18. );
  20. // Other routes...

Finally, we need to create a controller to handle asset requests:

  1. <?php
  3. namespace App\Controllers;
  5. use Phalcon\Http\Response;
  7. /**
  8.  * Serve site assets.
  9.  */
  10. class AssetsController extends ControllerBase
  11. {
  12.     public function serveAction() : Response
  13.     {
  14.         // Getting a response instance
  15.         $response = new Response();
  17.         // Prepare output path
  18.         $collectionName = $this->dispatcher->getParam('collection');
  19.         $extension      = $this->dispatcher->getParam('extension');
  20.         $type           = $this->dispatcher->getParam('type');
  21.         $targetPath     = "assets/{$type}/{$collectionName}.{$extension}";
  23.         // Setting up the content type
  24.         $contentType = $type == 'js' ? 'application/javascript' : 'text/css';
  25.         $response->setContentType($contentType, 'UTF-8');
  27.         // Check collection existence
  28.         if (!$this->assets->exists($collectionName)) {
  29.             return $response->setStatusCode(404, 'Not Found');
  30.         }
  32.         // Setting up the Assets Collection
  33.         $collection = $this->assets
  34.             ->collection($collectionName)
  35.             ->setTargetUri($targetPath)
  36.             ->setTargetPath($targetPath);
  38.         // Store content to the disk and return fully qualified file path
  39.         $contentPath = $this->assets->output(
  40.             $collection,
  41.             function (array $parameters) {
  42.                 return BASE_PATH . '/public/' . $parameters[0];
  43.             },
  44.             $type
  45.         );
  47.         // Set the content of the response
  48.         $response->setContent(
  49.             file_get_contents($contentPath)
  50.         );
  52.         // Return the response
  53.         return $response;
  54.     }
  55. }

If precompiled assets exist in the file system they must be served directly by web server. So to get the benefit of static assets we have to update our server configuration. We will use an example configuration for Nginx. For Apache it will be a little different:

  1. location ~ ^/assets/ {
  2.     expires 1y;
  3.     add_header Cache-Control public;
  4.     add_header ETag "";
  6.     # If the file exists as a static file serve it directly without
  7.     # running all the other rewrite tests on it
  8.     try_files $uri $uri/ @phalcon;
  9. }
  11. location / {
  12.     try_files $uri $uri/ @phalcon;
  13. }
  15. location @phalcon {
  16.     rewrite ^(.*)$ /index.php?_url=$1;
  17. }
  19. # Other configuration directoves

We need to create assets/js and assets/css directories in the document root of the application (eg. public).

Every time the application requests assets such as /assets/js/global.js the application will check whether the asset exists. If yes, it will be handled by the web server. Alternatively it will be redirected to the AssetsController for handling from the application.

We do not recommend to use the above example in production environments and for high load applications. However, the example does show what is possible using this component. The implementation you choose depends on the needs of your application.

In most cases, your web server, CDN or services such as Varnish HTTP Cache would be more preferable.