@ -10,6 +10,9 @@ namespace yii\web;
use Yii;
use yii\base\Component;
use yii\base\InvalidConfigException;
use yii\base\InvalidParamException;
use yii\helpers\FileHelper;
use yii\helpers\Url;
/**
* AssetManager manages asset bundle configuration and loading.
@ -67,13 +70,18 @@ class AssetManager extends Component
public $baseUrl = '@web/assets';
/**
* @var array mapping from source asset files (keys) to target asset files (values).
* When an asset bundle is being loaded by [[getBundle()]], each of its asset files (listed in either
* [[AssetBundle::css]] or [[AssetBundle::js]] will be examined to see if it matches any key
* in this map. If so, the corresponding value will be used to replace the asset file.
*
* This property is provided to support fixing incorrect asset file paths in some asset bundles.
* When an asset bundle is registered with a view, each relative asset file in its [[AssetBundle::css|css]]
* and [[AssetBundle::js|js]] arrays will be examined against this map. If any of the keys is found
* to be the last part of an asset file (which is prefixed with [[AssetBundle::sourcePath]] if available),
* the corresponding value will replace the asset and be registered with the view.
* For example, an asset file `my/path/to/jquery.js` matches a key `jquery.js`.
*
* Note that the target asset files should be either absolute URLs or paths relative to [[baseUrl]] and [[basePath]].
*
* In the following example, any occurrence of `jquery.min.js` will be replaced with `jquery/dist/jquery.js`.
* In the following example, any assets ending with `jquery.min.js` will be replaced with `jquery/dist/jquery.js`
* which is relative to [[baseUrl]] and [[basePath]].
*
* ```php
* [
@ -82,6 +90,63 @@ class AssetManager extends Component
* ```
*/
public $assetMap = [];
/**
* @var boolean whether to use symbolic link to publish asset files. Defaults to false, meaning
* asset files are copied to [[basePath]]. Using symbolic links has the benefit that the published
* assets will always be consistent with the source assets and there is no copy operation required.
* 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.
*
* 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
* ~~~
*/
public $linkAssets = false;
/**
* @var integer the permission to be set for newly published asset files.
* This value will be used by PHP chmod() function. No umask will be applied.
* If not set, the permission will be determined by the current environment.
*/
public $fileMode;
/**
* @var integer the permission to be set for newly generated asset directories.
* This value will be used by PHP chmod() function. No umask will be applied.
* Defaults to 0775, meaning the directory is read-writable by owner and group,
* but read-only for other users.
*/
public $dirMode = 0775;
/**
* @var callback a PHP callback that is called before copying each sub-directory or file.
* This option is used only when publishing a directory. If the callback returns false, the copy
* operation for the sub-directory or file will be cancelled.
*
* The signature of the callback should be: `function ($from, $to)`, where `$from` is the sub-directory or
* file to be copied from, while `$to` is the copy target.
*
* This is passed as a parameter `beforeCopy` to [[\yii\helpers\FileHelper::copyDirectory()]].
*/
public $beforeCopy;
/**
* @var callback a PHP callback that is called after a sub-directory or file is successfully copied.
* This option is used only when publishing a directory. The signature of the callback is the same as
* for [[beforeCopy]].
* This is passed as a parameter `afterCopy` to [[\yii\helpers\FileHelper::copyDirectory()]].
*/
public $afterCopy;
/**
* @var boolean whether the directory being published should be copied even if
* it is found in the target directory. This option is used only when publishing a directory.
* You may want to set this to be `true` during the development stage to make sure the published
* directory is always up-to-date. Do not set this to true on production servers as it will
* significantly degrade the performance.
*/
public $forceCopy = false;
private $_dummyBundles = [];
@ -94,10 +159,12 @@ class AssetManager extends Component
{
parent::init();
$this->basePath = Yii::getAlias($this->basePath);
if (is_dir($this->basePath)) {
$this->basePath = realpath($this->basePath);
} else {
if (!is_dir($this->basePath)) {
throw new InvalidConfigException("The directory does not exist: {$this->basePath}");
} elseif (!is_writable($this->basePath)) {
throw new InvalidConfigException("The directory is not writable by the Web process: {$this->basePath}");
} else {
$this->basePath = realpath($this->basePath);
}
$this->baseUrl = rtrim(Yii::getAlias($this->baseUrl), '/');
}
@ -109,19 +176,21 @@ class AssetManager extends Component
* it will treat `$name` as the class of the asset bundle and create a new instance of it.
*
* @param string $name the class name of the asset bundle
* @param boolean $publish whether to publish the asset files in the asset bundle before it is returned.
* If you set this false, you must manually call `AssetBundle::publish()` to publish the asset files.
* @return AssetBundle the asset bundle instance
* @throws InvalidConfigException if $name does not refer to a valid asset bundle
*/
public function getBundle($name)
public function getBundle($name, $publish = true )
{
if ($this->bundles === false) {
return $this->loadDummyBundle($name);
} elseif (!isset($this->bundles[$name])) {
return $this->bundles[$name] = $this->loadBundle($name);
return $this->bundles[$name] = $this->loadBundle($name, [], $publish );
} elseif ($this->bundles[$name] instanceof AssetBundle) {
return $this->bundles[$name];
} elseif (is_array($this->bundles[$name])) {
return $this->bundles[$name] = $this->loadBundle($name, $this->bundles[$name]);
return $this->bundles[$name] = $this->loadBundle($name, $this->bundles[$name], $publish );
} elseif ($this->bundles[$name] === false) {
return $this->loadDummyBundle($name);
} else {
@ -129,17 +198,15 @@ class AssetManager extends Component
}
}
protected function loadBundle($name, $config = [])
protected function loadBundle($name, $config = [], $publish = true )
{
if (!isset($config['class'])) {
$config['class'] = $name;
}
/* @var $bundle AssetBundle */
$bundle = Yii::createObject($config);
if ($bundle->basePath === null) {
$bundle->basePath = $this->basePath;
}
if ($bundle->baseUrl === null) {
$bundle->baseUrl = $this->baseUrl;
if ($publish) {
$bundle->publish($this);
}
return $bundle;
}
@ -156,11 +223,50 @@ class AssetManager extends Component
return $this->_dummyBundles[$name];
}
public function resolveAsset($asset)
/**
* Returns the actual URL for the specified asset.
* The actual URL is obtained by prepending either [[baseUrl]] or [[AssetManager::baseUrl]] to the given asset path.
* @param AssetBundle $bundle the asset bundle which the asset file belongs to
* @param string $asset the asset path. This should be one of the assets listed in [[js]] or [[css]].
* @return string the actual URL for the specified asset.
*/
public function getAssetUrl($bundle, $asset)
{
if (($actualAsset = $this->resolveAsset($bundle, $asset)) !== false) {
return Url::isRelative($actualAsset) ? $this->baseUrl . '/' . $actualAsset : $actualAsset;
} else {
return Url::isRelative($asset) ? $bundle->baseUrl . '/' . $asset : $asset;
}
}
/**
* Returns the actual file path for the specified asset.
* @param AssetBundle $bundle the asset bundle which the asset file belongs to
* @param string $asset the asset path. This should be one of the assets listed in [[js]] or [[css]].
* @return string|boolean the actual file path, or false if the asset is specified as an absolute URL
*/
public function getAssetPath($bundle, $asset)
{
if (($actualAsset = $this->resolveAsset($bundle, $asset)) !== false) {
return Url::isRelative($actualAsset) ? $this->basePath . '/' . $actualAsset : false;
} else {
return Url::isRelative($asset) ? $bundle->basePath . '/' . $asset : false;
}
}
/**
* @param AssetBundle $bundle
* @param string $asset
* @return string|boolean
*/
protected function resolveAsset($bundle, $asset)
{
if (isset($this->assetMap[$asset])) {
return $this->assetMap[$asset];
}
if ($bundle->sourcePath !== null & & Url::isRelative($asset)) {
$asset = $bundle->sourcePath . '/' . $asset;
}
$n = strlen($asset);
foreach ($this->assetMap as $from => $to) {
@ -173,13 +279,240 @@ class AssetManager extends Component
return false;
}
public function getAssetUrl($asset)
private $_converter;
/**
* Returns the asset converter.
* @return AssetConverterInterface the asset converter.
*/
public function getConverter()
{
if ($this->_converter === null) {
$this->_converter = Yii::createObject(AssetConverter::className());
} elseif (is_array($this->_converter) || is_string($this->_converter)) {
if (is_array($this->_converter) & & !isset($this->_converter['class'])) {
$this->_converter['class'] = AssetConverter::className();
}
$this->_converter = Yii::createObject($this->_converter);
}
return $this->_converter;
}
/**
* Sets the asset converter.
* @param array|AssetConverterInterface $value the asset converter. This can be either
* an object implementing the [[AssetConverterInterface]], or a configuration
* array that can be used to create the asset converter object.
*/
public function setConverter($value)
{
return $this->baseUrl . '/' . ltrim($asset, '/');
$this->_converter = $value ;
}
public function getAssetPath($asset)
/**
* @var array published assets
*/
private $_published = [];
/**
* Publishes a file or a directory.
*
* This method will copy the specified file or directory to [[basePath]] so that
* it can be accessed via the Web server.
*
* 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 (which is very expensive).
*
* By default, when publishing a directory, subdirectories and files whose name starts with a dot "."
* will NOT be published. If you want to change this behavior, you may specify the "beforeCopy" option
* as explained in the `$options` parameter.
*
* 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 array $options the options to be applied when publishing a directory.
* The following options are supported:
*
* - beforeCopy: callback, a PHP callback that is called before copying each sub-directory or file.
* This overrides [[beforeCopy]] if set.
* - afterCopy: callback, a PHP callback that is called after a sub-directory or file is successfully copied.
* This overrides [[afterCopy]] if set.
* - forceCopy: boolean, whether the directory being published should be copied even if
* it is found in the target directory. This option is used only when publishing a directory.
* This overrides [[forceCopy]] if set.
*
* @return array the path (directory or file path) and the URL that the asset is published as.
* @throws InvalidParamException if the asset to be published does not exist.
*/
public function publish($path, $options = [])
{
$path = Yii::getAlias($path);
if (isset($this->_published[$path])) {
return $this->_published[$path];
}
if (!is_string($path) || ($src = realpath($path)) === false) {
throw new InvalidParamException("The file or directory to be published does not exist: $path");
}
if (is_file($src)) {
return $this->_published[$path] = $this->publishFile($src);
} else {
return $this->_published[$path] = $this->publishDirectory($src, $options);
}
}
/**
* Publishes a file.
* @param string $src the asset file to be published
* @return array the path and the URL that the asset is published as.
* @throws InvalidParamException if the asset to be published does not exist.
*/
protected function publishFile($src)
{
$dir = $this->hash(dirname($src) . filemtime($src));
$fileName = basename($src);
$dstDir = $this->basePath . DIRECTORY_SEPARATOR . $dir;
$dstFile = $dstDir . DIRECTORY_SEPARATOR . $fileName;
if (!is_dir($dstDir)) {
FileHelper::createDirectory($dstDir, $this->dirMode, true);
}
if ($this->linkAssets) {
if (!is_file($dstFile)) {
symlink($src, $dstFile);
}
} elseif (@filemtime($dstFile) < @filemtime($src)) {
copy($src, $dstFile);
if ($this->fileMode !== null) {
@chmod($dstFile, $this->fileMode);
}
}
return [$dstFile, $this->baseUrl . "/$dir/$fileName"];
}
/**
* Publishes a directory.
* @param string $src the asset directory to be published
* @param array $options the options to be applied when publishing a directory.
* The following options are supported:
*
* - beforeCopy: callback, a PHP callback that is called before copying each sub-directory or file.
* This overrides [[beforeCopy]] if set.
* - afterCopy: callback, a PHP callback that is called after a sub-directory or file is successfully copied.
* This overrides [[afterCopy]] if set.
* - forceCopy: boolean, whether the directory being published should be copied even if
* it is found in the target directory. This option is used only when publishing a directory.
* This overrides [[forceCopy]] if set.
*
* @return array the path directory and the URL that the asset is published as.
* @throws InvalidParamException if the asset to be published does not exist.
*/
protected function publishDirectory($src, $options)
{
$dir = $this->hash($src . filemtime($src));
$dstDir = $this->basePath . DIRECTORY_SEPARATOR . $dir;
if ($this->linkAssets) {
if (!is_dir($dstDir)) {
symlink($src, $dstDir);
}
} elseif (!is_dir($dstDir) || !empty($options['forceCopy']) || (!isset($options['forceCopy']) & & $this->forceCopy)) {
$opts = [
'dirMode' => $this->dirMode,
'fileMode' => $this->fileMode,
];
if (isset($options['beforeCopy'])) {
$opts['beforeCopy'] = $options['beforeCopy'];
} elseif ($this->beforeCopy !== null) {
$opts['beforeCopy'] = $this->beforeCopy;
} else {
$opts['beforeCopy'] = function ($from, $to) {
return strncmp(basename($from), '.', 1) !== 0;
};
}
if (isset($options['afterCopy'])) {
$opts['afterCopy'] = $options['afterCopy'];
} elseif ($this->afterCopy !== null) {
$opts['afterCopy'] = $this->afterCopy;
}
FileHelper::copyDirectory($src, $dstDir, $opts);
}
return [$dstDir, $this->baseUrl . '/' . $dir];
}
/**
* 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
* @return string the published file path. False if the file or directory does not exist
*/
public function getPublishedPath($path)
{
$path = Yii::getAlias($path);
if (isset($this->_published[$path])) {
return $this->_published[$path][0];
}
if (is_string($path) & & ($path = realpath($path)) !== false) {
$base = $this->basePath . DIRECTORY_SEPARATOR;
if (is_file($path)) {
return $base . $this->hash(dirname($path) . filemtime($path)) . DIRECTORY_SEPARATOR . basename($path);
} else {
return $base . $this->hash($path . filemtime($path));
}
} 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
* @return string the published URL for the file or directory. False if the file or directory does not exist.
*/
public function getPublishedUrl($path)
{
$path = Yii::getAlias($path);
if (isset($this->_published[$path])) {
return $this->_published[$path][1];
}
if (is_string($path) & & ($path = realpath($path)) !== false) {
if (is_file($path)) {
return $this->baseUrl . '/' . $this->hash(dirname($path) . filemtime($path)) . '/' . basename($path);
} else {
return $this->baseUrl . '/' . $this->hash($path . filemtime($path));
}
} 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 $this->basePath . '/' . ltrim($asset, '/');
return sprintf('%x', crc32($path . Yii::getVersion()) );
}
}
Qiang Xue
10 years ago