0 follower

CModule

Package system.base
Inheritance abstract class CModule » CComponent
Subclasses CApplication, CWebModule
Since 1.0.4
Version $Id$
Source Code framework/base/CModule.php
CModule is the base class for module and application classes.

CModule mainly manages application components and sub-modules.

Public Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
basePath string the root directory of the module. CModule
behaviors array the behaviors that should be attached to the module. CModule
components array the currently loaded components (indexed by their IDs) CModule
id string the module ID. CModule
modulePath string the directory that contains the application modules. CModule
modules array the configuration of the currently installed modules (module ID => configuration) CModule
params CAttributeCollection the list of user-defined parameters CModule
parentModule CModule the parent module. CModule
preload array the IDs of the application components that should be preloaded. CModule

Public Methods

Hide inherited methods

MethodDescriptionDefined 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
getBasePath() Returns the root directory of the module. Defaults to the directory containing the module class. CModule
getComponent() Retrieves the named application component. CModule
getComponents() Returns the currently loaded components (indexed by their IDs) 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. Defaults to the 'modules' subdirectory of basePath. CModule
getModules() Returns the configuration of the currently installed modules (module ID => configuration) CModule
getParams() Returns the list of user-defined parameters CModule
getParentModule() Returns the parent module. Null if this module does not have a parent. CModule
hasComponent() Determines whether the named application component exists (including both loaded and disabled.) CModule
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
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. This should be in name-value pairs. CModule

Protected Methods

Hide inherited methods

MethodDescriptionDefined 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)

the root directory of the module. Defaults to the directory containing the module class.

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()
public void setComponents(array $components)

the currently loaded components (indexed by their IDs)

id property
public string getId()
public void setId(string $id)

the module ID.

modulePath property
public string getModulePath()
public void setModulePath(string $value)

the directory that contains the application modules. Defaults to the 'modules' subdirectory of basePath.

modules property
public array getModules()
public void setModules(array $modules)

the configuration of the currently installed modules (module ID => configuration)

params property
public CAttributeCollection getParams()
public void setParams(array $value)

the list of user-defined parameters

parentModule property read-only
public CModule getParentModule()

the parent module. Null if this module does not have a parent.

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.
Source Code: framework/base/CModule.php#52 (show)
public function __construct($id,$parent,$config=null)
{
    
$this->_id=$id;
    
$this->_parentModule=$parent;

    
// set basePath at early as possible to avoid trouble
    
if(is_string($config))
        
$config=require($config);
    if(isset(
$config['basePath']))
    {
        
$this->setBasePath($config['basePath']);
        unset(
$config['basePath']);
    }
    else
    {
        
$class=new ReflectionClass(get_class($this));
        
$this->setBasePath(dirname($class->getFileName()));
    }
    
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
Source Code: framework/base/CModule.php#88 (show)
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
Source Code: framework/base/CModule.php#103 (show)
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
Source Code: framework/base/CModule.php#426 (show)
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.
Source Code: framework/base/CModule.php#130 (show)
public function getBasePath()
{
    if(
$this->_basePath===null)
    {
        
$class=new ReflectionClass(get_class($this));
        
$this->_basePath=dirname($class->getFileName());
    }
    return 
$this->_basePath;
}

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. This parameter has been available since version 1.0.6.
{return} IApplicationComponent the application component instance, null if the application component is disabled or does not exist.
Source Code: framework/base/CModule.php#340 (show)
public function getComponent($id,$createIfNull=true)
{
    if(isset(
$this->_components[$id]))
        return 
$this->_components[$id];
    else if(isset(
$this->_componentConfig[$id]) && $createIfNull)
    {
        
$config=$this->_componentConfig[$id];
        unset(
$this->_componentConfig[$id]);
        if(!isset(
$config['enabled']) || $config['enabled'])
        {
            
Yii::trace("Loading \"$id\" application component",'system.web.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()
{return} array the currently loaded components (indexed by their IDs)
Source Code: framework/base/CModule.php#376 (show)
public function getComponents()
{
    return 
$this->_components;
}

getId() method
public string getId()
{return} string the module ID.
Source Code: framework/base/CModule.php#114 (show)
public function getId()
{
    return 
$this->_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.
Source Code: framework/base/CModule.php#246 (show)
public function getModule($id)
{
    if(isset(
$this->_modules[$id]) || array_key_exists($id,$this->_modules))
        return 
$this->_modules[$id];
    else if(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.
Source Code: framework/base/CModule.php#177 (show)
public function getModulePath()
{
    if(
$this->_modulePath!==null)
        return 
$this->_modulePath;
    else
        return 
$this->_modulePath=$this->getBasePath().DIRECTORY_SEPARATOR.'modules';
}

getModules() method
public array getModules()
{return} array the configuration of the currently installed modules (module ID => configuration)
Source Code: framework/base/CModule.php#270 (show)
public function getModules()
{
    return 
$this->_moduleConfig;
}

getParams() method
public CAttributeCollection getParams()
{return} CAttributeCollection the list of user-defined parameters
Source Code: framework/base/CModule.php#156 (show)
public function getParams()
{
    if(
$this->_params!==null)
        return 
$this->_params;
    else
        return 
$this->_params=new CAttributeCollection;
}

getParentModule() method
public CModule getParentModule()
{return} CModule the parent module. Null if this module does not have a parent.
Source Code: framework/base/CModule.php#234 (show)
public function getParentModule()
{
    return 
$this->_parentModule;
}

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.)
Source Code: framework/base/CModule.php#327 (show)
public function hasComponent($id)
{
    return isset(
$this->_components[$id]) || isset($this->_componentConfig[$id]);
}

init() method
protected void init()
Source Code: framework/base/CModule.php#462 (show)
protected function 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()
Source Code: framework/base/CModule.php#451 (show)
protected function 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()
Source Code: framework/base/CModule.php#438 (show)
protected function preloadComponents()
{
    foreach(
$this->preload as $id)
        
$this->getComponent($id);
}

Loads static application components.

setAliases() method (available since v1.0.5)
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
)
Source Code: framework/base/CModule.php#220 (show)
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.
Source Code: framework/base/CModule.php#146 (show)
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, IApplicationComponent $component)
$id string component ID
$component IApplicationComponent the component
Source Code: framework/base/CModule.php#366 (show)
public function setComponent($id,$component)
{
    
$this->_components[$id]=$component;
    if(!
$component->getIsInitialized())
        
$component->init();
}

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)
$components array application components(id=>component configuration or instances)
Source Code: framework/base/CModule.php#409 (show)
public function setComponents($components)
{
    foreach(
$components as $id=>$component)
    {
        if(
$component instanceof IApplicationComponent)
            
$this->setComponent($id,$component);
        else if(isset(
$this->_componentConfig[$id]))
            
$this->_componentConfig[$id]=CMap::mergeArray($this->_componentConfig[$id],$component);
        else
            
$this->_componentConfig[$id]=$component;
    }
}

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
Source Code: framework/base/CModule.php#122 (show)
public function setId($id)
{
    
$this->_id=$id;
}

setImport() method
public void setImport(array $aliases)
$aliases array list of aliases to be imported
Source Code: framework/base/CModule.php#200 (show)
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.
Source Code: framework/base/CModule.php#189 (show)
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)));
}

setModules() method
public void setModules(array $modules)
$modules array module configurations.
Source Code: framework/base/CModule.php#301 (show)
public function setModules($modules)
{
    foreach(
$modules as $id=>$module)
    {
        if(
is_int($id))
        {
            
$id=$module;
            
$module=array();
        }
        if(!isset(
$module['class']))
        {
            
Yii::setPathOfAlias($id,$this->getModulePath().DIRECTORY_SEPARATOR.$id);
            
$module['class']=$id.'.'.ucfirst($id).'Module';
        }

        if(isset(
$this->_moduleConfig[$id]))
            
$this->_moduleConfig[$id]=CMap::mergeArray($this->_moduleConfig[$id],$module);
        else
            
$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.
Source Code: framework/base/CModule.php#167 (show)
public function setParams($value)
{
    
$params=$this->getParams();
    foreach(
$value as $k=>$v)
        
$params->add($k,$v);
}