<?php
/**
* CAssetManager class file.
*
* @author Qiang Xue <[email protected]>
* @link http://www.yiiframework.com/
* @copyright Copyright © 2008-2011 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
/**
* 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 {@link publish()}.
*
* The Web-accessible directory holding the published files is specified
* by {@link setBasePath basePath}, which defaults to the "assets" directory
* under the directory containing the application entry script file.
* The property {@link setBaseUrl baseUrl} refers to the URL for accessing
* the {@link setBasePath basePath}.
*
* @property string $basePath The root directory storing the published asset files. Defaults to 'WebRoot/assets'.
* @property string $baseUrl The base url that the published asset files can be accessed.
* Note, the ending slashes are stripped off. Defaults to '/AppBaseUrl/assets'.
*
* @author Qiang Xue <[email protected]>
* @package system.web
* @since 1.0
*/
class CAssetManager extends CApplicationComponent
{
/**
* Default web accessible base path for storing private files
*/
const DEFAULT_BASEPATH='assets';
/**
* @var boolean 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:
* <pre>
* Options FollowSymLinks
* </pre>
*
* Note that this property cannot be true when {@link $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 {@link $forceCopy} documentation
* for more details.
*
* @since 1.1.5
*/
public $linkAssets=false;
/**
* @var array 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 {@link linkAssets} is enabled.
* @since 1.1.6
**/
public $excludeFiles=array('.svn','.gitignore');
/**
* @var integer 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.
* @since 1.1.8
*/
public $newFileMode=0666;
/**
* @var integer 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.
* @since 1.1.8
*/
public $newDirMode=0777;
/**
* @var boolean 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 {@link 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 {@link $linkAssets}) or we don't want to use them.
* This property sets the default value of the $forceCopy parameter in {@link 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 {@link $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 {@link $linkAssets} documentation
* for more details.
*
* @since 1.1.11
*/
public $forceCopy=false;
/**
* @var string base web accessible path for storing private files
*/
private $_basePath;
/**
* @var string base URL for accessing the publishing directory.
*/
private $_baseUrl;
/**
* @var array published assets
*/
private $_published=array();
/**
* @return string the root directory storing the published asset files. Defaults to 'WebRoot/assets'.
*/
public function getBasePath()
{
if($this->_basePath===null)
{
$request=Yii::app()->getRequest();
$this->setBasePath(dirname($request->getScriptFile()).DIRECTORY_SEPARATOR.self::DEFAULT_BASEPATH);
}
return $this->_basePath;
}
/**
* Sets the root directory storing published asset files.
* @param string $value the root directory storing published asset files
* @throws CException if the base path is invalid
*/
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)));
}
/**
* @return string the base url that the published asset files can be accessed.
* Note, the ending slashes are stripped off. Defaults to '/AppBaseUrl/assets'.
*/
public function getBaseUrl()
{
if($this->_baseUrl===null)
{
$request=Yii::app()->getRequest();
$this->setBaseUrl($request->getBaseUrl().'/'.self::DEFAULT_BASEPATH);
}
return $this->_baseUrl;
}
/**
* @param string $value the base url that the published asset files can be accessed
*/
public function setBaseUrl($value)
{
$this->_baseUrl=rtrim($value,'/');
}
/**
* 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.
* <ul>
* <li>If the asset is a file, its file modification time will be checked
* to avoid unnecessary file copying;</li>
* <li>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.</li>
* </ul>
*
* 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
*
* @param string $path the asset (file or directory) to be published
* @param boolean $hashByName 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.
* @param integer $level 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.
* @param boolean $forceCopy 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 {@link $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 {@link $linkAssets} property has true value too. Otherwise
* an exception would be thrown. Using this parameter with {@link $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 {@link $linkAssets} documentation for more details.
* @return string an absolute URL to the published asset
* @throws CException if the asset to be published does not exist.
*/
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(($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)));
}
/**
* 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.
* @param string $path directory or file path being published
* @param boolean $hashByName 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
*/
public function getPublishedPath($path,$hashByName=false)
{
if(($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 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.
* @param string $path directory or file path being published
* @param boolean $hashByName 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.
*/
public function getPublishedUrl($path,$hashByName=false)
{
if(isset($this->_published[$path]))
return $this->_published[$path];
if(($path=realpath($path))!==false)
{
$base=$this->getBaseUrl().'/'.$this->generatePath($path,$hashByName);
return is_file($path) ? $base.'/'.basename($path) : $base;
}
else
return false;
}
/**
* Generate a CRC32 hash for the directory path. Collisions are higher
* than MD5 but generates a much smaller hash string.
* @param string $path string to be hashed.
* @return string hashed string.
*/
protected function hash($path)
{
return sprintf('%x',crc32($path.Yii::getVersion()));
}
/**
* Generates path segments relative to basePath.
* @param string $file for which public path will be created.
* @param bool $hashByName whether the published directory should be named as the hashed basename.
* @return string path segments without basePath.
* @since 1.1.13
*/
protected function generatePath($file,$hashByName=false)
{
if (is_file($file))
$pathForHashing=$hashByName ? basename($file) : dirname($file).filemtime($file);
else
$pathForHashing=$hashByName ? basename($file) : $file.filemtime($file);
return $this->hash($pathForHashing);
}
}