Class yii\web\AssetManager

继承yii\web\AssetManager » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/web/AssetManager.php

AssetManager 管理资源包的配置和加载.

默认配置下, AssetManager 在 yii\web\Application 中配置为应用程序组件. 你可以通过Yii::$app->assetManager访问该实例.

你可以通过在components下的应用程序配置中添加一个数组来修改其配置, 如以下示例所示:

'assetManager' => [
    'bundles' => [
        // 你可以在此处覆盖 AssetBundle 配置
    ],
]

有关 AssetManager 的更多详细信息和使用信息, 请参见 guide article on assets.

公共属性

隐藏继承的属性

属性类型描述定义在
$afterCopy callback 在成功复制子目录或文件后调用的 PHP 回调. yii\web\AssetManager
$appendTimestamp boolean 是否在每个已发布资源的 URL 上添加时间戳. yii\web\AssetManager
$assetMap array 从源资源文件(键)到目标资源文件(值)的映射. yii\web\AssetManager
$basePath string 存储已发布资源文件的根目录. yii\web\AssetManager
$baseUrl string 通过其可以访问已发布的资源文件的基本 URL. yii\web\AssetManager
$beforeCopy callback 在复制每个子目录或文件之前调用的 PHP 回调. yii\web\AssetManager
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$bundles array|boolean 资源包配置列表. yii\web\AssetManager
$converter yii\web\AssetConverterInterface 资源转换器. 请注意, 该属性的类型在 getter 和 setter 中有所不同. 有关详细信息, 请参阅 getConverter()setConverter(). yii\web\AssetManager
$dirMode integer 为新生成的资源目录设置权限. yii\web\AssetManager
$fileMode integer 为新发布的资源文件设置权限. yii\web\AssetManager
$forceCopy boolean 即使在目标目录中找到已发布的目录, 是否也应该复制该目录. yii\web\AssetManager
$hashCallback callable 一个将被调用来生成资源目录生成哈希的回调. yii\web\AssetManager
$linkAssets boolean 是否使用符号链接发布资源文件. yii\web\AssetManager

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\BaseObject
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__unset() 将组件属性设置为null. yii\base\Component
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
checkBasePathPermission() 检查basePath是否存在并且可写. yii\web\AssetManager
className() 返回此类的完全限定名称. yii\base\BaseObject
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
getActualAssetUrl() 返回指定资源的实际URL. 没有参数. yii\web\AssetManager
getAssetPath() 返回指定资源的实际文件路径. yii\web\AssetManager
getAssetUrl() 返回指定资源的实际 URL. yii\web\AssetManager
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getBundle() 返回指定的资源包. yii\web\AssetManager
getConverter() 返回资源转换器. yii\web\AssetManager
getPublishedPath() 返回文件路径的已发布路径. yii\web\AssetManager
getPublishedUrl() 返回已发布的文件路径的 URL. yii\web\AssetManager
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
init() 初始化组件. yii\web\AssetManager
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
publish() 发布文件或目录. yii\web\AssetManager
setConverter() 设置资源转换器. yii\web\AssetManager
trigger() 触发事件. yii\base\Component

受保护的方法

隐藏继承的方法

方法描述定义在
hash() 为目录路径生成一个 CRC32 哈希值. 冲突高于 MD5, 但生成更小的散列字符串. yii\web\AssetManager
loadBundle() 通过名称加载资源依赖类. yii\web\AssetManager
loadDummyBundle() 根据名称加载虚拟包. yii\web\AssetManager
publishDirectory() 发布一个目录. yii\web\AssetManager
publishFile() 发布文件. yii\web\AssetManager
resolveAsset() yii\web\AssetManager

属性详情

$afterCopy public 属性

在成功复制子目录或文件后调用的 PHP 回调. 仅在发布目录时使用该选项. 回调的签名与 $beforeCopy 相同. 这作为参数afterCopy传递给 yii\helpers\FileHelper::copyDirectory().

public callback $afterCopy null
$appendTimestamp public 属性 (可用自版本: 2.0.3)

是否在每个已发布资源的 URL 上添加时间戳. 如果为true, 则发布的资源的 URL 可能类似于/path/to/asset?v=timestamp, 其中timestamp是发布的资源文件的最后修改时间. 通常, 在为资源启用 HTTP 缓存时, 你希望将此属性设置为true, 因为它允许你在更新资源时进行缓存.

public boolean $appendTimestamp false
$assetMap public 属性

从源资源文件(键)到目标资源文件(值)的映射.

提供此属性以支持修复某些资源包中错误的资源文件路径. 在视图中注册资源包时, 将对照此映射检查其 cssjs 数组中的每个相关资源文件. 如果发现任何键是资源文件的最后一部分(如果可用, 则以 yii\web\AssetBundle::$sourcePath 为前缀), 则对应的值将替换资源并注册到视图中. 例如, 资源文件my/path/to/jquery.js匹配键jquery.js.

Note: 目标资源文件应该是绝对 URL, 相对于域的 URL(从/开始)或相对于 $baseUrl$basePath 的路径.

在以下示例中, 所有以jquery.min.js结尾的资源将被替换为相对于 $baseUrl$basePathjquery/dist/jquery.js.

[
    'jquery.min.js' => 'jquery/dist/jquery.js',
]

你也可以在指定映射值时使用别名, 例如:

[
    'jquery.min.js' => '@web/js/jquery/jquery.js',
]
public array $assetMap = []
$basePath public 属性

存储已发布资源文件的根目录.

public string $basePath '@webroot/assets'
$baseUrl public 属性

通过其可以访问已发布的资源文件的基本 URL.

public string $baseUrl '@web/assets'
$beforeCopy public 属性

在复制每个子目录或文件之前调用的 PHP 回调. 仅在发布目录时使用该选项. 如果回调返回false, 则将取消对子目录或文件的复制操作. 回调的签名应该是: function ($from, $to), 其中$from是要复制的子目录或文件, 而$to是复制目标. 这作为参数beforeCopy传递给 yii\helpers\FileHelper::copyDirectory().

public callback $beforeCopy null
$bundles public 属性

资源包配置列表. 提供此属性以自定义资源依赖包. 当通过 getBundle() 加载依赖时, 如果在此处指定了相应的配置, 则该配置将应用到依赖包.

数组键是资源包名称, 通常是不带前导反斜杠的资源包的类名称. 数组值是相应的配置. 如果值为false, 则意味着相应的资源包被禁用, getBundle() 应该返回null.

如果此属性为false, 则意味着整个资源捆绑功能被禁用, getBundle() 将始终返回null.

以下示例显示如何禁用 Bootstrap 小部件使用的 bootstrap css 文件(因为你想使用自己的样式):

[
    'yii\bootstrap\BootstrapAsset' => [
        'css' => [],
    ],
]
public array|boolean $bundles = []
$converter public 属性

资源转换器. 请注意, 该属性的类型在 getter 和 setter 中有所不同. 有关详细信息, 请参阅 getConverter()setConverter().

$dirMode public 属性

为新生成的资源目录设置权限. 此值将由 PHP chmod() 函数使用. 不使用umask. 默认为0775, 这意味着目录是所有者和组可读写的, 但对其他用户是只读的.

public integer $dirMode 0775
$fileMode public 属性

为新发布的资源文件设置权限. 此值将由 PHP chmod() 函数使用. 不使用umask. 如果未设置, 则权限将由当前环境决定.

public integer $fileMode null
$forceCopy public 属性

即使在目标目录中找到已发布的目录, 是否也应该复制该目录. 仅在发布目录时使用该选项. 你可能需要在开发阶段将其设置为true, 以确保发布的目录始终处于最新状态. 不要在生产服务器上将其设置为true, 因为这会严重降低性能.

public boolean $forceCopy false
$hashCallback public 属性 (可用自版本: 2.0.6)

一个将被调用来生成资源目录生成哈希的回调. 回调的签名应该如下:

function ($path)

其中$path是资源路径. 请注意$path可以是资源文件所在的目录, 也可以是单个文件. 对于在url()中使用的相对路径的 CSS 文件, 哈希实现应使用文件的目录路径而不是文件路径来包含复制中的相关资源文件.

如果未设置, 资源管理器将在hash方法中使用默认的 CRC32 和 filemtime.

使用 MD4 哈希的实现示例:

function ($path) {
    return hash('md4', $path);
}
public callable $hashCallback null
$linkAssets public 属性

是否使用符号链接发布资源文件. 默认为false, 意味着资源文件被复制到 $basePath. 使用符号链接的好处时发布的资源将始终与源资源一致, 并且不需要复制操作. 这在开发过程中特别有用.

但是, 为了使用符号链接, 托管环境也有特殊要求. 特别是符号链接仅在 Linux/Unix 和 Windows Vista/2008 或更高版本上受支持.

此外, 一些 Web 服务器需要进行适当的配置, 以便 Web 用户可以访问链接的资源. 例如, 对于 Apache Web 服务器, 应为 Web 文件夹添加以下配置指令:

Options FollowSymLinks
public boolean $linkAssets false

方法详情

checkBasePathPermission() public 方法 (可用自版本: 2.0.40)

检查basePath是否存在并且可写.

public void checkBasePathPermission ( )
getActualAssetUrl() public 方法 (可用自版本: 2.0.39)

返回指定资源的实际URL. 没有参数.

通过在 yii\web\AssetBundle::$baseUrlyii\web\AssetManager::$baseUrl 之前添加到给的的资源路径来获得实际的URL.

public string getActualAssetUrl ( $bundle, $asset )
$bundle yii\web\AssetBundle

资源文件所属的资源包.

$asset string

资源路径. 这应该是 yii\web\AssetBundle::$jsyii\web\AssetBundle::$css 中列出的资源之一.

return string

指定资源的实际URL.

getAssetPath() public 方法

返回指定资源的实际文件路径.

public string|false getAssetPath ( $bundle, $asset )
$bundle yii\web\AssetBundle

资源文件所属的资源包.

$asset string

资源路径. 这应该是 yii\web\AssetBundle::$jsyii\web\AssetBundle::$css 中列出的资源之一.

return string|false

实际的文件路径, 如果将资源指定为绝对 URL, 则为false.

getAssetUrl() public 方法

返回指定资源的实际 URL.

通过在 yii\web\AssetBundle::$baseUrlyii\web\AssetManager::$baseUrl 之前添加到给定的资源路径来获得实际的 URL.

public string getAssetUrl ( $bundle, $asset )
$bundle yii\web\AssetBundle

资源文件所属的资源包.

$asset string

资源路径. 这应该是 yii\web\AssetBundle::$jsyii\web\AssetBundle::$css 中列出的资源之一.

return string

指定资源的实际 URL.

getBundle() public 方法

返回指定的资源包.

该方法将首先在 $bundles 中查找该包. 如果没有找到, 它会把$name作为资源包的类, 并创建一个新的实例.

public yii\web\AssetBundle getBundle ( $name, $publish true )
$name string

资源依赖包的类名(不带反斜杠).

$publish boolean

是否在返回之前在资源包中发布资源文件. 如果设置为false, 则必须手动调用AssetBundle::publish()来发布资源文件.

return yii\web\AssetBundle

资源包实例.

throws yii\base\InvalidConfigException

如果 $name 没有引用有效的资源包.

getConverter() public 方法

返回资源转换器.

public yii\web\AssetConverterInterface getConverter ( )
return yii\web\AssetConverterInterface

资源转换器.

getPublishedPath() public 方法

返回文件路径的已发布路径.

此方法不执行任何发布. 它只是告诉你, 如果文件或目录已发布, 它将指向哪里.

public string|false getPublishedPath ( $path )
$path string

正在发布的目录或文件路径.

return string|false

发布的文件路径字符串. 如果文件或目录不存在, 则为false.

getPublishedUrl() public 方法

返回已发布的文件路径的 URL.

此方法不执行任何发布. 它仅告诉你, 如果文件路径已发布, 将访问该 URL 的 URL.

public string|false getPublishedUrl ( $path )
$path string

正在已发布的目录或文件路径.

return string|false

为文件或目录发布的 URL. 如果文件或目录不存在, 则为false.

hash() protected 方法

为目录路径生成一个 CRC32 哈希值. 冲突高于 MD5, 但生成更小的散列字符串.

protected string hash ( $path )
$path string

被散列的字符串.

return string

散列字符串.

init() public 方法

初始化组件.

public void init ( )
throws yii\base\InvalidConfigException

如果 $basePath 无效.

loadBundle() protected 方法

通过名称加载资源依赖类.

protected yii\web\AssetBundle loadBundle ( $name, $config = [], $publish true )
$name string

包名称.

$config array

依赖对象配置.

$publish boolean

是否应发布依赖资源包.

throws yii\base\InvalidConfigException

如果配置无效.

loadDummyBundle() protected 方法

根据名称加载虚拟包.

protected yii\web\AssetBundle loadDummyBundle ( $name )
$name string
publish() public 方法

发布文件或目录.

该方法会将指定的文件或目录复制到 $basePath, 以便可以通过 Web 服务器访问它.

如果资源是文件, 则会检查其文件修改时间, 以避免不必要的文件复制.

如果资源是一个目录, 则将以递归的形式发布资源包下的所有文件和子目录.

Note: 如果 $forceCopy 为false, 则该方法仅检查目标目录的存在以避免重复复制(这是非常昂贵的).

默认情况下, 发布目录时, 名称以点.开头的子目录和文件将不会被发布. 如果你想改变这种行为, 你可以按$options参数中的说明指定"beforeCopy"选项.

Note: 在极少数情况下, 可能会形成竞争状况, 这将导致一次性创建包含已发布资源的目录中的非严重问题. 通过提前'requesting'所有应该触发'publish()'调用的资源, 并在系统上线之前在应用程序部署阶段进行操作, 可以完全避免此问题. 在以下讨论中查看更多信息: http://code.google.com/p/yii/issues/detail?id=2579

public array publish ( $path, $options = [] )
$path string

要发布的资源(文件或目录).

$options array

发布目录时要应用的选项. 支持以下选项:

  • only: array, 如果要复制文件路径, 则应匹配的模式列表.
  • except: array, 如果要从复制的文件或目录中排除文件或目录, 则应匹配的模式列表.
  • caseSensitive: boolean, 在"only"或"except"中指定的模式应区分大小写. 默认为false.
  • beforeCopy: callback, 在复制每个子目录或文件之前调用的 PHP 回调. 如果设置, 则覆盖 $beforeCopy.
  • afterCopy: callback, 在成功复制子目录或文件后调用的 PHP 回调. 如果设置, 则覆盖 $afterCopy.
  • forceCopy: boolean, 即使在目标目录中找到发布后的目录, 是否应复制该目录. 仅在发布目录时使用此选项. 如果设置, 则覆盖 $forceCopy.
return array

该资源被发布的路径(目录或文件路径)和 URL.

throws yii\base\InvalidArgumentException

如果要发布的资源不存在.

throws yii\base\InvalidConfigException

如果目标目录 $basePath 是不可写的.

publishDirectory() protected 方法

发布一个目录.

protected string[] publishDirectory ( $src, $options )
$src string

要发布的资源目录.

$options array

发布目录时要应用的选项. 支持以下选项:

  • only: array, 如果要复制文件路径, 则应匹配的模式列表.
  • except: array, 如果要从复制的文件或目录中排除文件或目录, 则应匹配的模式列表.
  • caseSensitive: boolean, 在"only"或"except"中指定的模式应区分大小写. 默认为false.
  • beforeCopy: callback, 在复制每个子目录或文件之前调用的 PHP 回调. 如果设置, 则覆盖 $beforeCopy.
  • afterCopy: callback, 在成功复制子目录或文件后调用的 PHP 回调. 如果设置, 则覆盖 $afterCopy.
  • forceCopy: boolean, 即使在目标目录中找到发布后的目录, 是否应复制该目录. 仅在发布目录时使用此选项. 如果设置, 则覆盖 $forceCopy.
return string[]

路径目录和资源发布的 URL.

throws yii\base\InvalidArgumentException

如果要发布的资源不存在.

publishFile() protected 方法

发布文件.

protected string[] publishFile ( $src )
$src string

要发布的资源文件.

return string[]

资源发布后的路径和 URL.

throws yii\base\InvalidArgumentException

如果要发布的资源不存在.

resolveAsset() protected 方法

protected string|boolean resolveAsset ( $bundle, $asset )
$bundle yii\web\AssetBundle
$asset string
setConverter() public 方法

设置资源转换器.

public void setConverter ( $value )
$value array|yii\web\AssetConverterInterface

资源转换器. 这可以是: