CAssetManager

所有包 | 属性 | 方法

包	system.web
继承	class CAssetManager » CApplicationComponent » CComponent
实现	IApplicationComponent
可用自	1.0
源码	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.

公共属性

隐藏继承的属性

属性	类型	描述	被定义在
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

公共方法

隐藏继承的方法

方法	描述	被定义在
__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

受保护的方法

隐藏继承的方法

方法	描述	被定义在
generatePath()	Generates path segments relative to basePath.	CAssetManager
hash()	Generate a CRC32 hash for the directory path. Collisions are higher	CAssetManager

属性详情

basePath 属性

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

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

baseUrl 属性

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 属性（自版本 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 属性（自版本 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 属性（自版本 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 属性（自版本 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 属性（自版本 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.

方法详情

generatePath() 方法（自版本 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.

源码： framework/web/CAssetManager.php#325 (显示)


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

public string getBasePath()
{return}	string	the root directory storing the published asset files. Defaults to 'WebRoot/assets'.

源码： framework/web/CAssetManager.php#118 (显示)


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

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'.

源码： framework/web/CAssetManager.php#146 (显示)


public function getBaseUrl()
{
    if($this->_baseUrl===null)
    {
        $request=Yii::app()->getRequest();
        $this->setBaseUrl($request->getBaseUrl().'/'.self::DEFAULT_BASEPATH);
    }
    return $this->_baseUrl;
}

getPublishedPath() 方法

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

源码： framework/web/CAssetManager.php#272 (显示)


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

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.

源码： framework/web/CAssetManager.php#294 (显示)


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

protected string hash(string $path)
$path	string	string to be hashed.
{return}	string	hashed string.

源码： framework/web/CAssetManager.php#313 (显示)


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

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

源码： framework/web/CAssetManager.php#206 (显示)


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

public void setBasePath(string $value)
$value	string	the root directory storing published asset files

源码： framework/web/CAssetManager.php#133 (显示)


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

public void setBaseUrl(string $value)
$value	string	the base url that the published asset files can be accessed

源码： framework/web/CAssetManager.php#159 (显示)


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