The following is a typical asset bundle, which references files from an arbitrary folder in the code base:

class YiiAsset extends AssetBundle
{
    public $sourcePath = '@yii/assets';
    public $js = [
        'yii.js',
    ];
    public $depends = [
        'yiiwebJqueryAsset',
    ];
}

It's a built-in asset bundle, which is required for any built-in widget of Yii 2 to work. It extends the AssetBundle class, and has the following properties defined:

This is, of course, not the complete list of properties. A complete description of the AssetBundle class can be found in the Yii 2 source code, in the yii2/web/AssetBundle.php file.

What does it mean to "register" a few CSS or JavaScript files? It means to put the corresponding HTML element into the resulting page and fill its href or src attribute. However, if we store the asset files in some arbitrary folder in the code base, maybe in a place inaccessible by the web server, what URLs do we use?

To answer the questions just asked, Yii has the AssetManager class and the concept of asset publishing. When you use AssetBundle with the sourcePath property defined, the Yii application utilizes the AssetManager component to copy the directory specified by sourcePath to some directory specified in the AssetManager.basePath parameter. By default, AssetManager.basePath is equal to @webroot/assets, and so in effect, the AssetBundle directory will be copied to some web-accessible location. It will be renamed to a unique, timestamp-dependent hash so that AssetManager will not unnecessarily republish the AssetBundle folder if it has not changed any content at all.

Asset publishing is a very complex part of the Yii framework and, surely, a very important and useful feature. You can get into details of it by reading the official documentation for Yii 2. We will now concentrate on the practical consequences of publishing assets, which are as follows:

You can publish any folder or file from the code base by making the following call:

list($dir, $url) = Yii:$app->assetManager->publish($path)

Here is the example AssetBundle definition, which references files that already lie in the web-accessible folder:

class MyUiAsset extends yiiwebAssetBundle
{
    public $basePath = '@webroot/ui';
    public $baseUrl = '@web/ui';
    public $css = ['main.css'];
    public $js = ['main.js'];
}

Dependencies were omitted for brevity.

Here, we see the basePath and baseUrl properties. The base path is the path alias to the folder that contains the files relevant to this bundle. The base URL is the absolute URL prefix that should be appended to all the file references so that the browser will be able to properly request it. Note that the alias system can also be applied to URLs.

Usually, the base URL and base path are similar as we utilize the ability of a web server to serve files directly using the path in any filesystem. However, in more complex cases, you may have complicated URL rewriting in place or maybe routes that dynamically generate CSS or JavaScript code on the fly. All of these are pretty rare, of course, but Yii provides the capabilities anyway.

The point is that when you use the sourcePath property in your asset bundle, Yii first publishes this source folder and modifies the basePath and baseUrl properties of the asset bundle in question for you. As a side effect, it's pointless to use all three properties at the same time as sourcePath will have precedence anyway.

This usage is meaningful when you can tolerate the folders that pre-exist in your web root directory. However, the whole reason to use the asset bundle is to contain the assets relevant to a single library inside a single folder. If you use a lot of asset bundles based on the base path, you will inevitably fill your web root with a lot of different folders from different libraries. And this can become really ugly really fast.

However, nothing will stop you from using the same base path for all the asset bundles (for example @webroot) and just referencing different files in each bundle. This will lead to a tangled mess of interrelated files and is a maintenance nightmare waiting to happen.

Thus, asset bundles based on the source path, in spite of the cumbersome change-republish cycle, look like a more maintainable and idiomatic solution.

Given the system of asset bundles, you probably will never really need to register assets manually, but in case you do, here's a list of methods you can use for it:

All these methods are in the View class, so you can use them as $this->registerCss($css) inside the view files and as Yii::$app->view->registerCss($css) anywhere else.

Note that we did not list exact function declarations, only the parts most useful in practice.

For JavaScript files, there's the concept of positions. Here's a list of the possible positions for JavaScript files:

There's a really useful trick with asset bundles related to manually registering the JavaScript and CSS files described in the previous section.

By default, when registering an asset bundle, all JavaScript files mentioned in it will be placed at the bottom of the body element. However, there's a method to change this position. Unfortunately, you cannot specify the position for each individual JavaScript file, only for the whole asset bundle.

There's a property called jsOptions in the AssetBundle class. It holds the parameters that will be passed to the registerJsFile call as the $options argument when each of the JavaScript files in the asset bundle will be registered. So you can add the following line to your AssetBundle definition:

public $jsOptions = ['position' => View::POS_HEAD];

All JavaScript files mentioned in the js property will be placed in the <head> element of the resulting HTML page instead of at the end of <body>.

There is also the cssOptions property that can be used to set options for the registerCssFile calls for CSS files. Using these options, you can set the media property of the resulting <link> tag, for example:

public $cssOptions = ['media' => 'print,aural,tty'];

Let's create our own asset bundle so that we can initialize our styles and client-side behavior with just a single call.

Create a directory called assets in the root of the code base. Inside it, create a file called ApplicationUiAssetBundle.php with the following definition:

namespace appassets;

use yiiwebAssetBundle;

class ApplicationUiAssetBundle extends AssetBundle
{
    public $sourcePath = '@app/assets/ui';
    public $css = [
        'css/main.css'
    ];
    public $js = [
        'js/main.js'
    ];
    public $depends = [
        'yiiootstrapBootstrapAsset',
        'yiiwebYiiAsset'
    ];
}

Hopefully, this definition completely makes sense. For it to not be a lie, we need to create two asset files in the code base root, which will be empty for now: assets/ui/css/main.css and assets/ui/js/main.js.

As we declared that our assets depend on YiiAsset and BootstrapAsset, we can replace the option of registering them with registering our asset bundle. Inside the main layout file, consider the following line:

yiiootstrapBootstrapAsset::register($this);
yiiwebYiiAsset::register($this);

We can replace these lines with the following:

appassetsApplicationUiAssetBundle::register($this);

Now we have the foundation to write custom styles for our example application.