CModule
Package | system.base |
---|---|
Inheritance | abstract class CModule » CComponent |
Subclasses | CApplication, CWebModule |
Source Code | framework/base/CModule.php |
CModule mainly manages application components and sub-modules.
Public Properties
Property | Type | Description | Defined By |
---|---|---|---|
basePath | string | Returns the root directory of the module. | CModule |
behaviors | array | the behaviors that should be attached to the module. | CModule |
components | array | Returns the application components. | CModule |
id | string | Returns the module ID. | CModule |
modulePath | string | Returns the directory that contains the application modules. | CModule |
modules | array | Returns the configuration of the currently installed modules. | CModule |
params | CAttributeCollection | Returns user-defined parameters. | CModule |
parentModule | CModule | Returns the parent module. | CModule |
preload | array | the IDs of the application components that should be preloaded. | CModule |
Public Methods
Method | Description | Defined By |
---|---|---|
__call() | Calls the named method which is not a class method. | CComponent |
__construct() | Constructor. | CModule |
__get() | Getter magic method. | CModule |
__isset() | Checks if a property value is null. | CModule |
__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 |
configure() | Configures the module with the specified configuration. | CModule |
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 of the module. | CModule |
getComponent() | Retrieves the named application component. | CModule |
getComponents() | Returns the application components. | CModule |
getEventHandlers() | Returns the list of attached event handlers for an event. | CComponent |
getId() | Returns the module ID. | CModule |
getModule() | Retrieves the named application module. | CModule |
getModulePath() | Returns the directory that contains the application modules. | CModule |
getModules() | Returns the configuration of the currently installed modules. | CModule |
getParams() | Returns user-defined parameters. | CModule |
getParentModule() | Returns the parent module. | CModule |
hasComponent() | Checks whether the named component exists. | CModule |
hasEvent() | Determines whether an event is defined. | CComponent |
hasEventHandler() | Checks whether the named event has attached handlers. | CComponent |
hasModule() | Returns a value indicating whether the specified module is installed. | CModule |
hasProperty() | Determines whether a property is defined. | CComponent |
raiseEvent() | Raises an event. | CComponent |
setAliases() | Defines the root aliases. | CModule |
setBasePath() | Sets the root directory of the module. | CModule |
setComponent() | Puts a component under the management of the module. | CModule |
setComponents() | Sets the application components. | CModule |
setId() | Sets the module ID. | CModule |
setImport() | Sets the aliases that are used in the module. | CModule |
setModulePath() | Sets the directory that contains the application modules. | CModule |
setModules() | Configures the sub-modules of this module. | CModule |
setParams() | Sets user-defined parameters. | CModule |
Protected Methods
Method | Description | Defined By |
---|---|---|
init() | Initializes the module. | CModule |
preinit() | Preinitializes the module. | CModule |
preloadComponents() | Loads static application components. | CModule |
Property Details
basePath property
public string getBasePath()
public void setBasePath(string $path)
Returns the root directory of the module.
behaviors property
public array $behaviors;
the behaviors that should be attached to the module. The behaviors will be attached to the module when init is called. Please refer to CModel::behaviors on how to specify the value of this property.
components property
public array getComponents(boolean $loadedOnly=true)
public void setComponents(array $components, boolean $merge=true)
Returns the application components.
id property
public string getId()
public void setId(string $id)
Returns the module ID.
modulePath property
public string getModulePath()
public void setModulePath(string $value)
Returns the directory that contains the application modules.
modules property
public array getModules()
public void setModules(array $modules, boolean $merge=true)
Returns the configuration of the currently installed modules.
params property
public CAttributeCollection getParams()
public void setParams(array $value)
Returns user-defined parameters.
parentModule property read-only
public CModule getParentModule()
Returns the parent module.
preload property
public array $preload;
the IDs of the application components that should be preloaded.
Method Details
__construct() method
public void __construct(string $id, CModule $parent, mixed $config=NULL) | ||
$id | string | the ID of this module |
$parent | CModule | the parent module (if any) |
$config | mixed | the module configuration. It can be either an array or the path of a PHP file returning the configuration array. |
public function __construct($id,$parent,$config=null)
{
$this->_id=$id;
$this->_parentModule=$parent;
// set basePath as early as possible to avoid trouble
if(is_string($config))
$config=require($config);
if(isset($config['basePath']))
{
$this->setBasePath($config['basePath']);
unset($config['basePath']);
}
Yii::setPathOfAlias($id,$this->getBasePath());
$this->preinit();
$this->configure($config);
$this->attachBehaviors($this->behaviors);
$this->preloadComponents();
$this->init();
}
Constructor.
__get() method
public mixed __get(string $name) | ||
$name | string | application component or property name |
{return} | mixed | the named property value |
public function __get($name)
{
if($this->hasComponent($name))
return $this->getComponent($name);
else
return parent::__get($name);
}
Getter magic method. This method is overridden to support accessing application components like reading module properties.
__isset() method
public boolean __isset(string $name) | ||
$name | string | the property name or the event name |
{return} | boolean | whether the property value is null |
public function __isset($name)
{
if($this->hasComponent($name))
return $this->getComponent($name)!==null;
else
return parent::__isset($name);
}
Checks if a property value is null. This method overrides the parent implementation by checking if the named application component is loaded.
configure() method
public void configure(array $config) | ||
$config | array | the configuration array |
public function configure($config)
{
if(is_array($config))
{
foreach($config as $key=>$value)
$this->$key=$value;
}
}
Configures the module with the specified configuration.
getBasePath() method
public string getBasePath() | ||
{return} | string | the root directory of the module. Defaults to the directory containing the module class. |
public function getBasePath()
{
if($this->_basePath===null)
{
$class=new ReflectionClass(get_class($this));
$this->_basePath=dirname($class->getFileName());
}
return $this->_basePath;
}
Returns the root directory of the module.
getComponent() method
public IApplicationComponent getComponent(string $id, boolean $createIfNull=true) | ||
$id | string | application component ID (case-sensitive) |
$createIfNull | boolean | whether to create the component if it doesn't exist yet. |
{return} | IApplicationComponent | the application component instance, null if the application component is disabled or does not exist. |
public function getComponent($id,$createIfNull=true)
{
if(isset($this->_components[$id]))
return $this->_components[$id];
elseif(isset($this->_componentConfig[$id]) && $createIfNull)
{
$config=$this->_componentConfig[$id];
if(!isset($config['enabled']) || $config['enabled'])
{
Yii::trace("Loading \"$id\" application component",'system.CModule');
unset($config['enabled']);
$component=Yii::createComponent($config);
$component->init();
return $this->_components[$id]=$component;
}
}
}
Retrieves the named application component.
See Also
getComponents() method
public array getComponents(boolean $loadedOnly=true) | ||
$loadedOnly | boolean | whether to return the loaded components only. If this is set false, then all components specified in the configuration will be returned, whether they are loaded or not. Loaded components will be returned as objects, while unloaded components as configuration arrays. This parameter has been available since version 1.1.3. |
{return} | array | the application components (indexed by their IDs) |
public function getComponents($loadedOnly=true)
{
if($loadedOnly)
return $this->_components;
else
return array_merge($this->_componentConfig, $this->_components);
}
Returns the application components.
getId() method
public string getId() | ||
{return} | string | the module ID. |
Returns the module ID.
getModule() method
public CModule getModule(string $id) | ||
$id | string | application module ID (case-sensitive) |
{return} | CModule | the module instance, null if the module is disabled or does not exist. |
public function getModule($id)
{
if(isset($this->_modules[$id]) || array_key_exists($id,$this->_modules))
return $this->_modules[$id];
elseif(isset($this->_moduleConfig[$id]))
{
$config=$this->_moduleConfig[$id];
if(!isset($config['enabled']) || $config['enabled'])
{
Yii::trace("Loading \"$id\" module",'system.base.CModule');
$class=$config['class'];
unset($config['class'], $config['enabled']);
if($this===Yii::app())
$module=Yii::createComponent($class,$id,null,$config);
else
$module=Yii::createComponent($class,$this->getId().'/'.$id,$this,$config);
return $this->_modules[$id]=$module;
}
}
}
Retrieves the named application module. The module has to be declared in modules. A new instance will be created when calling this method with the given ID for the first time.
getModulePath() method
public string getModulePath() | ||
{return} | string | the directory that contains the application modules. Defaults to the 'modules' subdirectory of basePath. |
public function getModulePath()
{
if($this->_modulePath!==null)
return $this->_modulePath;
else
return $this->_modulePath=$this->getBasePath().DIRECTORY_SEPARATOR.'modules';
}
Returns the directory that contains the application modules.
getModules() method
public array getModules() | ||
{return} | array | the configuration of the currently installed modules (module ID => configuration) |
public function getModules()
{
return $this->_moduleConfig;
}
Returns the configuration of the currently installed modules.
getParams() method
public CAttributeCollection getParams() | ||
{return} | CAttributeCollection | the list of user-defined parameters |
public function getParams()
{
if($this->_params!==null)
return $this->_params;
else
{
$this->_params=new CAttributeCollection;
$this->_params->caseSensitive=true;
return $this->_params;
}
}
Returns user-defined parameters.
getParentModule() method
public CModule getParentModule() | ||
{return} | CModule | the parent module. Null if this module does not have a parent. |
public function getParentModule()
{
return $this->_parentModule;
}
Returns the parent module.
hasComponent() method
public boolean hasComponent(string $id) | ||
$id | string | application component ID |
{return} | boolean | whether the named application component exists (including both loaded and disabled.) |
public function hasComponent($id)
{
return isset($this->_components[$id]) || isset($this->_componentConfig[$id]);
}
Checks whether the named component exists.
hasModule() method (available since v1.1.2)
public boolean hasModule(string $id) | ||
$id | string | the module ID |
{return} | boolean | whether the specified module is installed. |
public function hasModule($id)
{
return isset($this->_moduleConfig[$id]) || isset($this->_modules[$id]);
}
Returns a value indicating whether the specified module is installed.
init() method
protected void init() |
Initializes the module. This method is called at the end of the module constructor. Note that at this moment, the module has been configured, the behaviors have been attached and the application components have been registered.
See Also
preinit() method
protected void preinit() |
Preinitializes the module. This method is called at the beginning of the module constructor. You may override this method to do some customized preinitialization work. Note that at this moment, the module is not configured yet.
See Also
preloadComponents() method
protected void preloadComponents() |
protected function preloadComponents()
{
foreach($this->preload as $id)
$this->getComponent($id);
}
Loads static application components.
setAliases() method
public void setAliases(array $mappings) | ||
$mappings | array | list of aliases to be defined. The array keys are root aliases, while the array values are paths or aliases corresponding to the root aliases. For example, array( 'models'=>'application.models', // an existing alias 'extensions'=>'application.extensions', // an existing alias 'backend'=>dirname(__FILE__).'/../backend', // a directory ) |
public function setAliases($mappings)
{
foreach($mappings as $name=>$alias)
{
if(($path=Yii::getPathOfAlias($alias))!==false)
Yii::setPathOfAlias($name,$path);
else
Yii::setPathOfAlias($name,$alias);
}
}
Defines the root aliases.
setBasePath() method
public void setBasePath(string $path) | ||
$path | string | the root directory of the module. |
public function setBasePath($path)
{
if(($this->_basePath=realpath($path))===false || !is_dir($this->_basePath))
throw new CException(Yii::t('yii','Base path "{path}" is not a valid directory.',
array('{path}'=>$path)));
}
Sets the root directory of the module. This method can only be invoked at the beginning of the constructor.
setComponent() method
public void setComponent(string $id, array|IApplicationComponent $component, boolean $merge=true) | ||
$id | string | component ID |
$component | array|IApplicationComponent | application component (either configuration array or instance). If this parameter is null, component will be unloaded from the module. |
$merge | boolean | whether to merge the new component configuration with the existing one. Defaults to true, meaning the previously registered component configuration with the same ID will be merged with the new configuration. If set to false, the existing configuration will be replaced completely. This parameter is available since 1.1.13. |
public function setComponent($id,$component,$merge=true)
{
if($component===null)
{
unset($this->_components[$id]);
return;
}
elseif($component instanceof IApplicationComponent)
{
$this->_components[$id]=$component;
if(!$component->getIsInitialized())
$component->init();
return;
}
elseif(isset($this->_components[$id]))
{
if(isset($component['class']) && get_class($this->_components[$id])!==$component['class'])
{
unset($this->_components[$id]);
$this->_componentConfig[$id]=$component; //we should ignore merge here
return;
}
foreach($component as $key=>$value)
{
if($key!=='class')
$this->_components[$id]->$key=$value;
}
}
elseif(isset($this->_componentConfig[$id]['class'],$component['class'])
&& $this->_componentConfig[$id]['class']!==$component['class'])
{
$this->_componentConfig[$id]=$component; //we should ignore merge here
return;
}
if(isset($this->_componentConfig[$id]) && $merge)
$this->_componentConfig[$id]=CMap::mergeArray($this->_componentConfig[$id],$component);
else
$this->_componentConfig[$id]=$component;
}
Puts a component under the management of the module. The component will be initialized by calling its init() method if it has not done so.
setComponents() method
public void setComponents(array $components, boolean $merge=true) | ||
$components | array | application components(id=>component configuration or instances) |
$merge | boolean | whether to merge the new component configuration with the existing one. Defaults to true, meaning the previously registered component configuration of the same ID will be merged with the new configuration. If false, the existing configuration will be replaced completely. |
public function setComponents($components,$merge=true)
{
foreach($components as $id=>$component)
$this->setComponent($id,$component,$merge);
}
Sets the application components.
When a configuration is used to specify a component, it should consist of the component's initial property values (name-value pairs). Additionally, a component can be enabled (default) or disabled by specifying the 'enabled' value in the configuration.
If a configuration is specified with an ID that is the same as an existing component or configuration, the existing one will be replaced silently.
The following is the configuration for two components:
array( 'db'=>array( 'class'=>'CDbConnection', 'connectionString'=>'sqlite:path/to/file.db', ), 'cache'=>array( 'class'=>'CDbCache', 'connectionID'=>'db', 'enabled'=>!YII_DEBUG, // enable caching in non-debug mode ), )
setId() method
public void setId(string $id) | ||
$id | string | the module ID |
Sets the module ID.
setImport() method
public void setImport(array $aliases) | ||
$aliases | array | list of aliases to be imported |
public function setImport($aliases)
{
foreach($aliases as $alias)
Yii::import($alias);
}
Sets the aliases that are used in the module.
setModulePath() method
public void setModulePath(string $value) | ||
$value | string | the directory that contains the application modules. |
public function setModulePath($value)
{
if(($this->_modulePath=realpath($value))===false || !is_dir($this->_modulePath))
throw new CException(Yii::t('yii','The module path "{path}" is not a valid directory.',
array('{path}'=>$value)));
}
Sets the directory that contains the application modules.
setModules() method
public void setModules(array $modules, boolean $merge=true) | ||
$modules | array | module configurations. |
$merge | boolean | whether to merge the new module configuration with the existing one. Defaults to true, meaning the previously registered module configuration with the same ID will be merged with the new configuration. If set to false, the existing configuration will be replaced completely. This parameter is available since 1.1.16. |
public function setModules($modules,$merge=true)
{
foreach($modules as $id=>$module)
{
if(is_int($id))
{
$id=$module;
$module=array();
}
if(isset($this->_moduleConfig[$id]) && $merge)
$this->_moduleConfig[$id]=CMap::mergeArray($this->_moduleConfig[$id],$module);
else
{
if(!isset($module['class']))
{
if (Yii::getPathOfAlias($id)===false)
Yii::setPathOfAlias($id,$this->getModulePath().DIRECTORY_SEPARATOR.$id);
$module['class']=$id.'.'.ucfirst($id).'Module';
}
$this->_moduleConfig[$id]=$module;
}
}
}
Configures the sub-modules of this module.
Call this method to declare sub-modules and configure them with their initial property values. The parameter should be an array of module configurations. Each array element represents a single module, which can be either a string representing the module ID or an ID-configuration pair representing a module with the specified ID and the initial property values.
For example, the following array declares two modules:
array( 'admin', // a single module ID 'payment'=>array( // ID-configuration pair 'server'=>'paymentserver.com', ), )
By default, the module class is determined using the expression
ucfirst($moduleID).'Module'
. And the class file is located under modules/$moduleID
. You may override this default by explicitly specifying the 'class' option in the configuration. You may also enable or disable a module by specifying the 'enabled' option in the configuration.
setParams() method
public void setParams(array $value) | ||
$value | array | user-defined parameters. This should be in name-value pairs. |
public function setParams($value)
{
$params=$this->getParams();
foreach($value as $k=>$v)
$params->add($k,$v);
}
Sets user-defined parameters.
© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc/api/1.1/CModule