Class CAssetManager
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 CAssetManager::publish().
The Web-accessible directory holding the published files is specified by
setBasePath basePath, which defaults to the "assets" directory under the
directory containing the application entry script file. The property setBaseUrl baseUrl refers to the URL for accessing the setBasePath
basePath.
-
CComponent
-
CApplicationComponent
implements
IApplicationComponent
-
CAssetManager
Methods summary
public
string
|
#
getBasePath( )
Returns
string
the root directory storing the published asset files. Defaults to
'WebRoot/assets'.
|
public
|
#
setBasePath( string $value )
Sets the root directory storing published asset files.
Sets the root directory storing published asset files.
Parameters
- $value
string
$value the root directory storing published asset files Throws
|
public
string
|
#
getBaseUrl( )
Returns
string
the base url that the published asset files can be accessed. Note, the ending
slashes are stripped off. Defaults to '/AppBaseUrl/assets'.
|
public
|
#
setBaseUrl( string $value )
Parameters
- $value
string
$value the base url that the published asset files can be accessed
|
public
string
|
#
publish( string $path, boolean $hashByName = false, integer $level = -1, boolean $forceCopy = null )
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.
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
Parameters
- $path
string
$path the asset (file or directory) to be published- $hashByName
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.- $level
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.- $forceCopy
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
CAssetManager::$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 CAssetManager::$linkAssets property has true value too.
Otherwise an exception would be thrown. Using this parameter with CAssetManager::$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 CAssetManager::$linkAssets documentation for more details. Returns
string
an absolute URL to the published asset
Throws
CExceptionif the asset to be published does not exist.
|
public
string
|
#
getPublishedPath( string $path, boolean $hashByName = 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.
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.
Parameters
- $path
string
$path directory or file path being published- $hashByName
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. Returns
string
the published file path. False if the file or directory does not exist
|
public
string
|
#
getPublishedUrl( string $path, boolean $hashByName = 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.
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.
Parameters
- $path
string
$path directory or file path being published- $hashByName
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. Returns
string
the published URL for the file or directory. False if the file or directory does
not exist.
|
protected
string
|
#
hash( string $path )
Generate a CRC32 hash for the directory path. Collisions are higher than MD5
but generates a much smaller hash string.
Generate a CRC32 hash for the directory path. Collisions are higher than MD5
but generates a much smaller hash string.
Parameters
- $path
string
$path string to be hashed. Returns
string
hashed string.
|
protected
string
|
#
generatePath( string $file, boolean $hashByName = false )
Generates path segments relative to basePath.
Generates path segments relative to basePath.
Parameters
- $file
string
$file for which public path will be created.- $hashByName
boolean
$hashByName whether the published directory should be named as the hashed
basename. Returns
string
path segments without basePath.
Since
1.1.13
|
Methods inherited from CComponent
__call(),
__get(),
__isset(),
__set(),
__unset(),
asa(),
attachBehavior(),
attachBehaviors(),
attachEventHandler(),
canGetProperty(),
canSetProperty(),
detachBehavior(),
detachBehaviors(),
detachEventHandler(),
disableBehavior(),
disableBehaviors(),
enableBehavior(),
enableBehaviors(),
evaluateExpression(),
getEventHandlers(),
hasEvent(),
hasEventHandler(),
hasProperty(),
raiseEvent()
|
Constants summary
string |
DEFAULT_BASEPATH
|
'assets' |
#
Default web accessible base path for storing private files
Default web accessible base path for storing private files
|
Properties summary
public
boolean
|
$linkAssets
|
false |
#
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 CAssetManager::$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 CAssetManager::$forceCopy documentation for more
details.
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 CAssetManager::$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 CAssetManager::$forceCopy documentation for more
details.
Since
1.1.5
|
public
array
|
$excludeFiles
|
array('.svn','.gitignore') |
#
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 CAssetManager::$linkAssets is enabled.
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 CAssetManager::$linkAssets is enabled.
Since
1.1.6
|
public
integer
|
$newFileMode
|
0666 |
#
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.
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
integer
|
$newDirMode
|
0777 |
#
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.
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
boolean
|
$forceCopy
|
false |
#
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 CAssetManager::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 CAssetManager::$linkAssets) or we don't want to use them. This property
sets the default value of the $forceCopy parameter in CAssetManager::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 CAssetManager::$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 CAssetManager::$linkAssets documentation for more
details.
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 CAssetManager::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 CAssetManager::$linkAssets) or we don't want to use them. This property
sets the default value of the $forceCopy parameter in CAssetManager::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 CAssetManager::$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 CAssetManager::$linkAssets documentation for more
details.
Since
1.1.11
|
Magic properties summary
public
string
|
$basePath
|
#
The root directory storing the published asset files. Defaults to
'WebRoot/assets'.
The root directory storing the published asset files. Defaults to
'WebRoot/assets'.
|
public
string
|
$baseUrl
|
#
The base url that the published asset files can be accessed. Note, the ending
slashes are stripped off. Defaults to '/AppBaseUrl/assets'.
The base url that the published asset files can be accessed. Note, the ending
slashes are stripped off. Defaults to '/AppBaseUrl/assets'.
|