ASSETS 129 To use this command, you should rst create a conguration le to

describe what asset bundles should be combined and how they should be grouped. You can use the asset/template sub-command to generate a tem-plate rst and then modify it to t for your needs.

yii asset/template assets.php

The command generates a le named assets.php in the current directory.

The content of this le looks like the following:

<?php /**

* Configuration file for the "yii asset" console command.

* Note that in the console environment, some path aliases like '@webroot' and '@web' may not exist.

* Please define these missing path aliases.

*/

return [

// Adjust command/callback for JavaScript files compressing:

'jsCompressor' => 'java -jar compiler.jar --js {from} --js_output_file { to}',

// Adjust command/callback for CSS files compressing:

'cssCompressor' => 'java -jar yuicompressor.jar --type css {from} -o {to }',

// The list of asset bundles to compress:

'bundles' => [

// 'yii\web\YiiAsset', // 'yii\web\JqueryAsset',

],// Asset bundle for compression output:

'targets' => [

],// Asset manager configuration:

'assetManager' => [ ],

];

You should modify this le and specify which bundles you plan to combine in thebundlesoption. In thetargetsoption you should specify how the bundles should be divided into groups. You can specify one or multiple groups, as aforementioned.

Note: Because the alias ^@webroot and ^@web are not available in the console application, you should explicitly dene them in the conguration.

130 CHAPTER 3. APPLICATION STRUCTURE JavaScript les are combined, compressed and written to js/all-{hash}.js

where {hash} is replaced with the hash of the resulting le.

ThejsCompressorandcssCompressoroptions specify the console commands or PHP callbacks for performing JavaScript and CSS combining/compress-ing. By default, Yii uses Closure Compiler³⁶ for combining JavaScript les and YUI Compressor³⁷ for combining CSS les. You should install those tools manually or adjust these options to use your favorite tools.

With the conguration le, you can run the asset command to combine and compress the asset les and then generate a new asset bundle congu-ration leassets-prod.php:

yii asset assets.php config/assets-prod.php

The generated conguration le can be included in the application congu-ration, like described in the last subsection.

Info: Using theassetcommand is not the only option to automate the asset combining and compressing process. You can use the excellent task runner tool grunt³⁸ to achieve the same goal.

Grouping Asset Bundles

In the last subsection, we have explained how to combine all asset bundles into a single one in order to minimize the HTTP requests for asset les referenced in an application. This is not always desirable in practice. For example, imagine your application has a front end as well as a back end, each of which uses a dierent set of JavaScript and CSS les. In this case, combining all asset bundles from both ends into a single one does not make sense, because the asset bundles for the front end are not used by the back end and it would be a waste of network bandwidth to send the back end

assets when a front end page is requested.

To solve the above problem, you can divide asset bundles into groups and combine asset bundles for each group. The following conguration shows how you can group asset bundles:

return [

...// Specify output bundles with groups:

'targets' => [ 'allShared' => [

'js' => 'js/all-shared-{hash}.js', 'css' => 'css/all-shared-{hash}.css', 'depends' => [

// Include all assets shared between 'backend' and 'frontend '

36https://developers.google.com/closure/compiler/

37https://github.com/yui/yuicompressor/

38http://gruntjs.com/

3.12. EXTENSIONS 131

'yii\web\YiiAsset', 'app\assets\SharedAsset', ], ],

'allBackEnd' => [

'js' => 'js/all-{hash}.js', 'css' => 'css/all-{hash}.css', 'depends' => [

// Include only 'backend' assets:

'app\assets\AdminAsset' ], ],

'allFrontEnd' => [

'js' => 'js/all-{hash}.js', 'css' => 'css/all-{hash}.css',

'depends' => [], // Include all remaining assets ],

],...

];

As you can see, the asset bundles are divided into three groups: ^allShared,

allBackEndandallFrontEnd. They each depends on an appropriate set of asset bundles. For example, allBackEnd depends on app\assets\AdminAsset. When running^assetcommand with this conguration, it will combine asset bundles according to the above specication.

Info: You may leave the ^depends conguration empty for one of the target bundle. By doing so, that particular asset bundle will depend on all of the remaining asset bundles that other target bundles do not depend on.

3.12 Extensions

Extensions are redistributable software packages specically designed to be used in Yii applications and provide ready-to-use features. For example, the yiisoft/yii2-debug extension adds a handy debug toolbar at the bottom of every page in your application to help you more easily grasp how the pages are generated. You can use extensions to accelerate your development process. You can also package your code as extensions to share with other people your great work.

Info: We use the term extension to refer to Yii-specic software packages. For general purpose software packages that can be used without Yii, we will refer to them using the term package or

library.

132 CHAPTER 3. APPLICATION STRUCTURE 3.12.1 Using Extensions

To use an extension, you need to install it rst. Most extensions are dis-tributed as Composer³⁹ packages which can be installed by taking the fol-lowing two simple steps:

1. modify thecomposer.jsonle of your application and specify which ex-tensions (Composer packages) you want to install.

2. runcomposer install to install the specied extensions.

Note that you may need to install Composer⁴⁰ if you do not have it.

By default, Composer installs packages registered on Packagist⁴¹ - the biggest repository for open source Composer packages. You can look for extensions on Packagist. You may also create your own repository⁴² and congure Composer to use it. This is useful if you are developing private extensions that you want to share within your projects only.

Extensions installed by Composer are stored in theBasePath/vendor direc-tory, whereBasePathrefers to the application's base path. Because Composer is a dependency manager, when it installs a package, it will also install all its dependent packages.

For example, to install the yiisoft/yii2-imagine extension, modify your

composer.jsonlike the following:

{

// ...

"require": {

// ... other dependencies

"yiisoft/yii2-imagine": "*"

} }

After the installation, you should see the directoryyiisoft/yii2-imagineunder

BasePath/vendor. You should also see another directoryimagine/imaginewhich contains the installed dependent package.

Info: Theyiisoft/yii2-imagine is a core extension developed and maintained by the Yii developer team. All core extensions are hosted on Packagist⁴³and named likeyiisoft/yii2-xyz, wherexyz

varies for dierent extensions.

39https://getcomposer.org/

40https://getcomposer.org/

41https://packagist.org/

42https://getcomposer.org/doc/05-repositories.md#repository

43https://packagist.org/

3.12. EXTENSIONS 133