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

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)

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()

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()

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)

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)

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)

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)

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.

setBasePath() method

public void setBasePath(string $value)

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)

public function setBaseUrl($value)
{
    $this->_baseUrl=rtrim($value,'/');
}