@ -16,13 +16,19 @@ use yii\util\FileHelper;
/** /**
* Module is the base class for module and application classes. * Module is the base class for module and application classes.
* *
* Module mainly manages application components and sub-modules that belongs to a module. * A module represents a sub-application which contains MVC elements by itself, such as
* models, views, controllers, etc.
*
* A module may consist of [[modules|sub-modules]].
*
* [[components|Components]] may be registered with the module so that they are globally
* accessible within the module.
* *
* @property string $uniqueId An ID that uniquely identifies this module among all modules within * @property string $uniqueId An ID that uniquely identifies this module among all modules within
* the current application. * the current application.
* @property string $basePath The root directory of the module. Defaults to the directory containing the module class. * @property string $basePath The root directory of the module. Defaults to the directory containing the module class.
* @property array $modules The configuration of the currently installed modules (module ID => configuration). * @property array $modules The configuration of the currently installed modules (module ID => configuration).
* @property array $components The application components (indexed by their IDs). * @property array $components The components (indexed by their IDs) registered within this module .
* @property array $import List of aliases to be imported. This property is write-only. * @property array $import List of aliases to be imported. This property is write-only.
* @property array $aliases List of aliases to be defined. This property is write-only. * @property array $aliases List of aliases to be defined. This property is write-only.
* *
@ -36,7 +42,7 @@ abstract class Module extends Component
*/ */
public $params = array(); public $params = array();
/** /**
* @var array the IDs of the application components that should be preloaded when this module is created. * @var array the IDs of the components that should be preloaded when this module is created.
*/ */
public $preload = array(); public $preload = array();
/** /**
@ -88,27 +94,27 @@ abstract class Module extends Component
/** /**
* @var string the root directory of the module. * @var string the root directory of the module.
*/ */
protected $_basePath; private $_basePath;
/** /**
* @var string the root directory that contains view files for this module * @var string the root directory that contains view files for this module
*/ */
protected $_viewPath; private $_viewPath;
/** /**
* @var string the root directory that contains layout view files for this module. * @var string the root directory that contains layout view files for this module.
*/ */
protected $_layoutPath; private $_layoutPath;
/** /**
* @var string the directory containing controller classes in the module. * @var string the directory containing controller classes in the module.
*/ */
protected $_controllerPath; private $_controllerPath;
/** /**
* @var array child modules of this module * @var array child modules of this module
*/ */
protected $_modules = array(); private $_modules = array();
/** /**
* @var array application components of this module * @var array components registered under this module
*/ */
protected $_components = array(); private $_components = array();
/** /**
* Constructor. * Constructor.
@ -125,9 +131,9 @@ abstract class Module extends Component
/** /**
* Getter magic method. * Getter magic method.
* This method is overridden to support accessing application components * This method is overridden to support accessing components
* like reading module properties. * like reading module properties.
* @param string $name application component or property name * @param string $name component or property name
* @return mixed the named property value * @return mixed the named property value
*/ */
public function __get($name) public function __get($name)
@ -142,7 +148,7 @@ abstract class Module extends Component
/** /**
* Checks if a property value is null. * Checks if a property value is null.
* This method overrides the parent implementation by checking * This method overrides the parent implementation by checking
* if the named application component is loaded. * if the named component is loaded.
* @param string $name the property name or the event name * @param string $name the property name or the event name
* @return boolean whether the property value is null * @return boolean whether the property value is null
*/ */
@ -163,7 +169,7 @@ abstract class Module extends Component
*/ */
public function init() public function init()
{ {
\ Yii::setAlias('@' . $this->id, $this->getBasePath()); Yii::setAlias('@' . $this->id, $this->getBasePath());
$this->preloadComponents(); $this->preloadComponents();
} }
@ -282,19 +288,19 @@ abstract class Module extends Component
/** /**
* Imports the specified path aliases. * Imports the specified path aliases.
* This method is provided so that you can import a set of path aliases when configuring a module. * This method is provided so that you can import a set of path aliases when configuring a module.
* The path aliases will be imported by calling [[\ Yii::import()]]. * The path aliases will be imported by calling [[Yii::import()]].
* @param array $aliases list of path aliases to be imported * @param array $aliases list of path aliases to be imported
*/ */
public function setImport($aliases) public function setImport($aliases)
{ {
foreach ($aliases as $alias) { foreach ($aliases as $alias) {
\ Yii::import($alias); Yii::import($alias);
} }
} }
/** /**
* Defines path aliases. * Defines path aliases.
* This method calls [[\ Yii::setAlias()]] to register the path aliases. * This method calls [[Yii::setAlias()]] to register the path aliases.
* This method is provided so that you can define path aliases when configuring a module. * This method is provided so that you can define path aliases when configuring a module.
* @param array $aliases list of path aliases to be defined. The array keys are alias names * @param array $aliases list of path aliases to be defined. The array keys are alias names
* (must start with '@') and the array values are the corresponding paths or aliases. * (must start with '@') and the array values are the corresponding paths or aliases.
@ -302,7 +308,7 @@ abstract class Module extends Component
* *
* ~~~ * ~~~
* array( * array(
* '@models' => '@app/models', // an existing alias * '@models' => '@application /models', // an existing alias
* '@backend' => __DIR__ . '/../backend', // a directory * '@backend' => __DIR__ . '/../backend', // a directory
* ) * )
* ~~~ * ~~~
@ -310,7 +316,7 @@ abstract class Module extends Component
public function setAliases($aliases) public function setAliases($aliases)
{ {
foreach ($aliases as $name => $alias) { foreach ($aliases as $name => $alias) {
\ Yii::setAlias($name, $alias); Yii::setAlias($name, $alias);
} }
} }
@ -339,8 +345,8 @@ abstract class Module extends Component
if ($this->_modules[$id] instanceof Module) { if ($this->_modules[$id] instanceof Module) {
return $this->_modules[$id]; return $this->_modules[$id];
} elseif ($load) { } elseif ($load) {
\ Yii::trace("Loading \"$id\" module", __CLASS__); Yii::trace("Loading module: $id ", __CLASS__);
return $this->_modules[$id] = \ Yii::createObject($this->_modules[$id], $id, $this); return $this->_modules[$id] = Yii::createObject($this->_modules[$id], $id, $this);
} }
} }
return null; return null;
@ -393,7 +399,7 @@ abstract class Module extends Component
* *
* Each sub-module should be specified as a name-value pair, where * Each sub-module should be specified as a name-value pair, where
* name refers to the ID of the module and value the module or a configuration * name refers to the ID of the module and value the module or a configuration
* array that can be used to create the module. In the latter case, [[\ Yii::createObject()]] * array that can be used to create the module. In the latter case, [[Yii::createObject()]]
* will be used to create the module. * will be used to create the module.
* *
* If a new sub-module has the same ID as an existing one, the existing one will be overwritten silently. * If a new sub-module has the same ID as an existing one, the existing one will be overwritten silently.
@ -423,8 +429,8 @@ abstract class Module extends Component
/** /**
* Checks whether the named component exists. * Checks whether the named component exists.
* @param string $id application component ID * @param string $id component ID
* @return boolean whether the named application component exists. Both loaded and unloaded components * @return boolean whether the named component exists. Both loaded and unloaded components
* are considered. * are considered.
*/ */
public function hasComponent($id) public function hasComponent($id)
@ -433,11 +439,10 @@ abstract class Module extends Component
} }
/** /**
* Retrieves the named application component. * Retrieves the named component.
* @param string $id application component ID (case-sensitive) * @param string $id component ID (case-sensitive)
* @param boolean $load whether to load the component if it is not yet loaded. * @param boolean $load whether to load the component if it is not yet loaded.
* @return Component|null the application component instance, null if the application component * @return Component|null the component instance, null if the component does not exist.
* does not exist.
* @see hasComponent() * @see hasComponent()
*/ */
public function getComponent($id, $load = true) public function getComponent($id, $load = true)
@ -446,22 +451,22 @@ abstract class Module extends Component
if ($this->_components[$id] instanceof Component) { if ($this->_components[$id] instanceof Component) {
return $this->_components[$id]; return $this->_components[$id];
} elseif ($load) { } elseif ($load) {
\ Yii::trace("Loading \"$id\" application component", __CLASS__); Yii::trace("Loading component: $id ", __CLASS__);
return $this->_components[$id] = \ Yii::createObject($this->_components[$id]); return $this->_components[$id] = Yii::createObject($this->_components[$id]);
} }
} }
return null; return null;
} }
/** /**
* Registers an application component in this module. * Registers a component with this module.
* @param string $id component ID * @param string $id component ID
* @param Component|array|null $component the component to be added to the module. This can * @param Component|array|null $component the component to be registered with the module. This can
* be one of the followings: * be one of the followings:
* *
* - a [[Component]] object * - a [[Component]] object
* - a configuration array: when [[getComponent()]] is called initially for this component, the array * - a configuration array: when [[getComponent()]] is called initially for this component, the array
* will be used to instantiate the component * will be used to instantiate the component via [[Yii::createObject()]].
* - null: the named component will be removed from the module * - null: the named component will be removed from the module
*/ */
public function setComponent($id, $component) public function setComponent($id, $component)
@ -474,11 +479,11 @@ abstract class Module extends Component
} }
/** /**
* Returns the application components. * Returns the registered components.
* @param boolean $loadedOnly whether to return the loaded components only. If this is set false, * @param boolean $loadedOnly 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. * 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. * Loaded components will be returned as objects, while unloaded components as configuration arrays.
* @return array the application components (indexed by their IDs) * @return array the components (indexed by their IDs)
*/ */
public function getComponents($loadedOnly = false) public function getComponents($loadedOnly = false)
{ {
@ -496,11 +501,11 @@ abstract class Module extends Component
} }
/** /**
* Registers a set of application components in this module. * Registers a set of components in this module.
* *
* Each application component should be specified as a name-value pair, where * Each component should be specified as a name-value pair, where
* name refers to the ID of the component and value the component or a configuration * name refers to the ID of the component and value the component or a configuration
* array that can be used to create the component. In the latter case, [[\ Yii::createObject()]] * array that can be used to create the component. In the latter case, [[Yii::createObject()]]
* will be used to create the component. * will be used to create the component.
* *
* If a new component has the same ID as an existing one, the existing one will be overwritten silently. * If a new component has the same ID as an existing one, the existing one will be overwritten silently.
@ -520,7 +525,7 @@ abstract class Module extends Component
* ) * )
* ~~~ * ~~~
* *
* @param array $components application components (id => component configuration or instance) * @param array $components components (id => component configuration or instance)
*/ */
public function setComponents($components) public function setComponents($components)
{ {
@ -530,7 +535,7 @@ abstract class Module extends Component
} }
/** /**
* Loads application components that are declared in [[preload]]. * Loads components that are declared in [[preload]].
*/ */
public function preloadComponents() public function preloadComponents()
{ {
@ -540,54 +545,47 @@ abstract class Module extends Component
} }
/** /**
* Perform s a controller action specified by a route. * Run s a controller action specified by a route.
* This method parses the specified route and creates the corresponding controller and action * This method parses the specified route and creates the corresponding child module(s), c ontroller and action
* instances under the context of the specified module. It then runs the created action * instances. It then calls [[Controller::runAction()]] to run the action with the given parameters.
* with the given parameters . * If the route is empty, the method will use [[defaultRoute]] .
* @param string $route the route that specifies the action. * @param string $route the route that specifies the action.
* @param array $params the parameters to be passed to the action * @param array $params the parameters to be passed to the action
* @return integer the action * @return integer the status code returned by the action execution. 0 means normal, and other values mean abnormal.
* @throws InvalidConfigException if the module's defaultRoute is empty or the controller's defaultAction is empty * @throws InvalidRouteException if the requested route cannot be resolved into an action successfully
* @throws InvalidRequestException if the requested route cannot be resolved into an action successfully
*/ */
public function runAction($route, $params = array()) public function runAction($route, $params = array())
{ {
$route = trim($route, '/'); $route = trim($route, '/');
if ($route === '') { if ($route === '') {
$route = trim($this->defaultRoute, '/'); $route = trim($this->defaultRoute, '/');
if ($route == '') {
throw new InvalidConfigException(get_class($this) . '::defaultRoute cannot be empty.');
}
} }
if (($pos = strpos($route, '/')) !== false) { if (($pos = strpos($route, '/')) !== false) {
$id = substr($route, 0, $pos); $id = substr($route, 0, $pos);
$route = substr($route, $pos + 1); $route2 = substr($route, $pos + 1);
} else { } else {
$id = $route; $id = $route;
$route = ''; $route2 = '';
} }
$module = $this->getModule($id); $module = $this->getModule($id);
if ($module !== null) { if ($module !== null) {
return $module->runAction($route, $params); return $module->runAction($route2 , $params);
} }
$controller = $this->createController($id); $controller = $this->createController($id);
if ($controller !== null) { if ($controller !== null) {
if ($route === '') { $oldController = Yii::$application->controller;
$route = $controller->defaultAction; Yii::$application->controller = $controller;
if ($route == '') {
throw new InvalidConfigException(get_class($controller) . '::defaultAction cannot be empty.');
}
}
$action = $controller->createAction($route); $status = $controller->runAction($route2, $params);
if ($action !== null) {
return $action->runWithParams($params);
}
}
throw new InvalidRequestException('Unable to resolve the request: ' . ltrim($this->getUniqueId() . '/' . $route, '/')); Yii::$application->controller = $oldController;
return $status;
} else {
throw new InvalidRouteException('Unable to resolve the request: ' . $this->getUniqueId() . '/' . $route);
}
} }
/** /**
Qiang Xue
12 years ago