0 follower

CAssetManager

Package system.web
Inheritance class CAssetManager » CApplicationComponent » CComponent
Implements IApplicationComponent
Since 1.0
Source Code framework/web/CAssetManager.php
CAssetManager is a Web application component that manages private files (called assets) and makes them accessible by Web clients.

It achieves this goal by copying assets to a Web-accessible directory and returns the corresponding URL for accessing them.

To publish an asset, simply call publish().

The Web-accessible directory holding the published files is specified by basePath, which defaults to the "assets" directory under the directory containing the application entry script file. The property baseUrl refers to the URL for accessing the basePath.

Public Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
basePath string the root directory storing the published asset files. CAssetManager
baseUrl string the base url that the published asset files can be accessed. CAssetManager
behaviors array the behaviors that should be attached to this component. CApplicationComponent
excludeFiles array list of directories and files which should be excluded from the publishing process. CAssetManager
forceCopy boolean whether we should copy the asset files and directories even if they already published before. CAssetManager
isInitialized boolean Checks if this application component has been initialized. CApplicationComponent
linkAssets boolean whether to use symbolic link to publish asset files. CAssetManager
newDirMode integer the permission to be set for newly generated asset directories. CAssetManager
newFileMode integer the permission to be set for newly generated asset files. CAssetManager

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__call() Calls the named method which is not a class method. CComponent
__get() Returns a property value, an event handler list or a behavior based on its name. CComponent
__isset() Checks if a property value is null. CComponent
__set() Sets value of a component property. CComponent
__unset() Sets a component property to be null. CComponent
asa() Returns the named behavior object. CComponent
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
getBasePath() Returns the root directory storing the published asset files. Defaults to 'WebRoot/assets'. CAssetManager
getBaseUrl() Returns the base url that the published asset files can be accessed. Note, the ending slashes are stripped off. Defaults to '/AppBaseUrl/assets'. CAssetManager
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getIsInitialized() Checks if this application component has been initialized. CApplicationComponent
getPublishedPath() Returns the published path of a file path. CAssetManager
getPublishedUrl() Returns the URL of a published file path. CAssetManager
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasProperty() Determines whether a property is defined. CComponent
init() Initializes the application component. CApplicationComponent
publish() Publishes a file or a directory. CAssetManager
raiseEvent() Raises an event. CComponent
setBasePath() Sets the root directory storing published asset files. CAssetManager
setBaseUrl() Sets the base url that the published asset files can be accessed CAssetManager

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
generatePath() Generates path segments relative to basePath. CAssetManager
hash() Generate a CRC32 hash for the directory path. Collisions are higher CAssetManager

Property Details

basePath property
public string getBasePath()
public void setBasePath(string $value)

the root directory storing the published asset files. Defaults to 'WebRoot/assets'.

baseUrl property
public string getBaseUrl()
public void setBaseUrl(string $value)

the base url that the published asset files can be accessed. Note, the ending slashes are stripped off. Defaults to '/AppBaseUrl/assets'.

excludeFiles property (available since v1.1.6)
public array $excludeFiles;

list of directories and files which should be excluded from the publishing process. Defaults to exclude '.svn' and '.gitignore' files only. This option has no effect if linkAssets is enabled.

forceCopy property (available since v1.1.11)
public boolean $forceCopy;

whether we should copy the asset files and directories even if they already published before. This property is used only during development stage. The main use case of this property is when you need to force the original assets always copied by changing only one value without searching needed publish method calls across the application codebase. Also it is useful in operating systems which does not fully support symbolic links (therefore it is not possible to use $linkAssets) or we don't want to use them. This property sets the default value of the $forceCopy parameter in publish method. Default value of this property is false meaning that the assets will be published only in case they don't exist in webroot assets directory.

Note that this property cannot be true when $linkAssets property has true value too. Otherwise an exception would be thrown. Using both properties at the same time is illogical because both of them are solving similar tasks but in a different ways. Please refer to the $linkAssets documentation for more details.

linkAssets property (available since v1.1.5)
public boolean $linkAssets;

whether to use symbolic link to publish asset files. Defaults to false, meaning asset files are copied to public folders. Using symbolic links has the benefit that the published assets will always be consistent with the source assets. This is especially useful during development.

However, there are special requirements for hosting environments in order to use symbolic links. In particular, symbolic links are supported only on Linux/Unix, and Windows Vista/2008 or greater. The latter requires PHP 5.3 or greater.

Moreover, some Web servers need to be properly configured so that the linked assets are accessible to Web users. For example, for Apache Web server, the following configuration directive should be added for the Web folder: 

Options FollowSymLinks


Note that this property cannot be true when $forceCopy property has true value too. Otherwise an exception would be thrown. Using both properties at the same time is illogical because both of them are solving similar tasks but in a different ways. Please refer to the $forceCopy documentation for more details.
newDirMode property (available since v1.1.8)
public integer $newDirMode;

the permission to be set for newly generated asset directories. This value will be used by PHP chmod function. Defaults to 0777, meaning the directory can be read, written and executed by all users.

newFileMode property (available since v1.1.8)
public integer $newFileMode;

the permission to be set for newly generated asset files. This value will be used by PHP chmod function. Defaults to 0666, meaning the file is read-writable by all users.

Method Details

generatePath() method (available since v1.1.13)
protected string generatePath(string $file, bool $hashByName=false)
$file string for which public path will be created.
$hashByName bool whether the published directory should be named as the hashed basename.
{return} string path segments without basePath.
Source Code: framework/web/CAssetManager.php#325 (show)
protected function generatePath($file,$hashByName=false)
{
    if (is_file($file))
        $pathForHashing=$hashByName ? dirname($file) : dirname($file).filemtime($file);
    else
        $pathForHashing=$hashByName ? $file : $file.filemtime($file);

    return $this->hash($pathForHashing);
}

Generates path segments relative to basePath.

getBasePath() method
public string getBasePath()
{return} string the root directory storing the published asset files. Defaults to 'WebRoot/assets'.
Source Code: framework/web/CAssetManager.php#118 (show)
public function getBasePath()
{
    if($this->_basePath===null)
    {
        $request=Yii::app()->getRequest();
        $this->setBasePath(dirname($request->getScriptFile()).DIRECTORY_SEPARATOR.self::DEFAULT_BASEPATH);
    }
    return $this->_basePath;
}

getBaseUrl() method
public string getBaseUrl()
{return} string the base url that the published asset files can be accessed. Note, the ending slashes are stripped off. Defaults to '/AppBaseUrl/assets'.
Source Code: framework/web/CAssetManager.php#146 (show)
public function getBaseUrl()
{
    if($this->_baseUrl===null)
    {
        $request=Yii::app()->getRequest();
        $this->setBaseUrl($request->getBaseUrl().'/'.self::DEFAULT_BASEPATH);
    }
    return $this->_baseUrl;
}

getPublishedPath() method
public string getPublishedPath(string $path, boolean $hashByName=false)
$path string directory or file path being published
$hashByName boolean whether the published directory should be named as the hashed basename. If false, the name will be the hash taken from dirname of the path being published and path mtime. Defaults to false. Set true if the path being published is shared among different extensions.
{return} string the published file path. False if the file or directory does not exist
Source Code: framework/web/CAssetManager.php#272 (show)
public function getPublishedPath($path,$hashByName=false)
{
    if(is_string($path) && ($path=realpath($path))!==false)
    {
        $base=$this->getBasePath().DIRECTORY_SEPARATOR.$this->generatePath($path,$hashByName);
        return is_file($path) ? $base.DIRECTORY_SEPARATOR.basename($path) : $base ;
    }
    else
        return false;
}

Returns the published path of a file path. This method does not perform any publishing. It merely tells you if the file or directory is published, where it will go.

getPublishedUrl() method
public string getPublishedUrl(string $path, boolean $hashByName=false)
$path string directory or file path being published
$hashByName boolean whether the published directory should be named as the hashed basename. If false, the name will be the hash taken from dirname of the path being published and path mtime. Defaults to false. Set true if the path being published is shared among different extensions.
{return} string the published URL for the file or directory. False if the file or directory does not exist.
Source Code: framework/web/CAssetManager.php#294 (show)
public function getPublishedUrl($path,$hashByName=false)
{
    if(isset($this->_published[$path]))
        return $this->_published[$path];
    if(is_string($path) && ($path=realpath($path))!==false)
    {
        $base=$this->getBaseUrl().'/'.$this->generatePath($path,$hashByName);
        return is_file($path) ? $base.'/'.basename($path) : $base;
    }
    else
        return false;
}

Returns the URL of a published file path. This method does not perform any publishing. It merely tells you if the file path is published, what the URL will be to access it.

hash() method
protected string hash(string $path)
$path string string to be hashed.
{return} string hashed string.
Source Code: framework/web/CAssetManager.php#313 (show)
protected function hash($path)
{
    return sprintf('%x',crc32($path.Yii::getVersion()));
}

Generate a CRC32 hash for the directory path. Collisions are higher than MD5 but generates a much smaller hash string.

publish() method
public string publish(string $path, boolean $hashByName=false, integer $level=-1, boolean $forceCopy=NULL)
$path string the asset (file or directory) to be published
$hashByName boolean whether the published directory should be named as the hashed basename. If false, the name will be the hash taken from dirname of the path being published and path mtime. Defaults to false. Set true if the path being published is shared among different extensions.
$level integer level of recursive copying when the asset is a directory. Level -1 means publishing all subdirectories and files; Level 0 means publishing only the files DIRECTLY under the directory; level N means copying those directories that are within N levels.
$forceCopy boolean whether we should copy the asset file or directory even if it is already published before. In case of publishing a directory old files will not be removed. This parameter is set true mainly during development stage when the original assets are being constantly changed. The consequence is that the performance is degraded, which is not a concern during development, however. Default value of this parameter is null meaning that it's value is controlled by $forceCopy class property. This parameter has been available since version 1.1.2. Default value has been changed since 1.1.11. Note that this parameter cannot be true when $linkAssets property has true value too. Otherwise an exception would be thrown. Using this parameter with $linkAssets property at the same time is illogical because both of them are solving similar tasks but in a different ways. Please refer to the $linkAssets documentation for more details.
{return} string an absolute URL to the published asset
Source Code: framework/web/CAssetManager.php#206 (show)
public function publish($path,$hashByName=false,$level=-1,$forceCopy=null)
{
    if($forceCopy===null)
        $forceCopy=$this->forceCopy;
    if($forceCopy && $this->linkAssets)
        throw new CException(Yii::t('yii','The "forceCopy" and "linkAssets" cannot be both true.'));
    if(isset($this->_published[$path]))
        return $this->_published[$path];
    elseif(is_string($path) && ($src=realpath($path))!==false)
    {
        $dir=$this->generatePath($src,$hashByName);
        $dstDir=$this->getBasePath().DIRECTORY_SEPARATOR.$dir;
        if(is_file($src))
        {
            $fileName=basename($src);
            $dstFile=$dstDir.DIRECTORY_SEPARATOR.$fileName;

            if(!is_dir($dstDir))
            {
                mkdir($dstDir,$this->newDirMode,true);
                @chmod($dstDir,$this->newDirMode);
            }

            if($this->linkAssets && !is_file($dstFile)) symlink($src,$dstFile);
            elseif(@filemtime($dstFile)<@filemtime($src))
            {
                copy($src,$dstFile);
                @chmod($dstFile,$this->newFileMode);
            }

            return $this->_published[$path]=$this->getBaseUrl()."/$dir/$fileName";
        }
        elseif(is_dir($src))
        {
            if($this->linkAssets && !is_dir($dstDir))
            {
                symlink($src,$dstDir);
            }
            elseif(!is_dir($dstDir) || $forceCopy)
            {
                CFileHelper::copyDirectory($src,$dstDir,array(
                    'exclude'=>$this->excludeFiles,
                    'level'=>$level,
                    'newDirMode'=>$this->newDirMode,
                    'newFileMode'=>$this->newFileMode,
                ));
            }

            return $this->_published[$path]=$this->getBaseUrl().'/'.$dir;
        }
    }
    throw new CException(Yii::t('yii','The asset "{asset}" to be published does not exist.',
        array('{asset}'=>$path)));
}

Publishes a file or a directory. This method will copy the specified asset to a web accessible directory and return the URL for accessing the published asset.

  • If the asset is a file, its file modification time will be checked to avoid unnecessary file copying;
  • If the asset is a directory, all files and subdirectories under it will be published recursively. Note, in case $forceCopy is false the method only checks the existence of the target directory to avoid repetitive copying.


Note: On rare scenario, a race condition can develop that will lead to a one-time-manifestation of a non-critical problem in the creation of the directory that holds the published assets. This problem can be avoided altogether by 'requesting' in advance all the resources that are supposed to trigger a 'publish()' call, and doing that in the application deployment phase, before system goes live. See more in the following discussion: http://code.google.com/p/yii/issues/detail?id=2579
setBasePath() method
public void setBasePath(string $value)
$value string the root directory storing published asset files
Source Code: framework/web/CAssetManager.php#133 (show)
public function setBasePath($value)
{
    if(($basePath=realpath($value))!==false && is_dir($basePath) && is_writable($basePath))
        $this->_basePath=$basePath;
    else
        throw new CException(Yii::t('yii','CAssetManager.basePath "{path}" is invalid. Please make sure the directory exists and is writable by the Web server process.',
            array('{path}'=>$value)));
}

Sets the root directory storing published asset files.

setBaseUrl() method
public void setBaseUrl(string $value)
$value string the base url that the published asset files can be accessed
Source Code: framework/web/CAssetManager.php#159 (show)
public function setBaseUrl($value)
{
    $this->_baseUrl=rtrim($value,'/');
}