Class yii\base\Module

继承yii\base\Module » yii\di\ServiceLocator » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable
子类yii\base\Application, yii\console\Application, yii\web\Application
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/base/Module.php

Module 是模块和应用程序类的基类.

模块表示一个子应用程序, 它自身包含 MVC 元素, 例如模型, 视图, 控制器等.

模块可以包括 子模块.

Components 可以在模块中注册, 以便它们可以在模块内全局访问.

有关 Module 的更多详细信息和使用信息, 请参阅 权威指南 - 应用结构 - 模块(Modules).

公共属性

隐藏继承的属性

属性类型描述定义在
$aliases array 要定义的路径别名列表. 数组键是别名(必须以@开头), 数组值是相应的路径或别名. 有关示例, 请参阅 setAliases(). 该属性是只写的. yii\base\Module
$basePath string 模块的根目录. yii\base\Module
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$components array 组件定义列表或已加载的组件实例(ID => 定义或实例). yii\di\ServiceLocator
$controllerMap array 从控制器ID映射到控制器配置. yii\base\Module
$controllerNamespace string 控制器类所在的命名空间. yii\base\Module
$controllerPath string 包含控制器类的目录. 该属性是只读的. yii\base\Module
$defaultRoute string 该模块的默认路由. yii\base\Module
$id string 在具有相同 父类 的其它模块中唯一标识该模块的ID. yii\base\Module
$layout string|boolean 该模块中应该应用于视图的布局. yii\base\Module
$layoutPath string 布局文件的根目录. 默认为[[viewPath]]/layouts. yii\base\Module
$module yii\base\Module 该模块的父模块. yii\base\Module
$modules array 模块(由其 ID 索引). yii\base\Module
$params array 自定义模块参数(name => value). yii\base\Module
$uniqueId string 模块的唯一ID. 该属性是只读的. yii\base\Module
$version string 该模块的版本. 请注意, 该属性的类型在 getter 和 setter 中有所不同. 有关详细信息, 请参阅 getVersion()setVersion(). yii\base\Module
$viewPath string 视图文件的根目录. 默认为[[basePath]]/views. yii\base\Module

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\Module
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__unset() 将组件属性设置为null. yii\base\Component
afterAction() 在执行此模块中的动作之后立即调用此方法. yii\base\Module
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
beforeAction() 在执行此模块中的动作之前调用此方法. yii\base\Module
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
className() 返回此类的完全限定名称. yii\base\BaseObject
clear() 从定位器中移除组件. yii\di\ServiceLocator
createController() 根据给定的路由创建一个控制器实例. yii\base\Module
createControllerByID() 根据给定的控制器ID创建一个控制器. yii\base\Module
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
get() 返回具有指定ID的组件实例. yii\base\Module
getBasePath() 返回模块的根目录. yii\base\Module
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getComponents() 返回组件定义列表或已加载组件的实例. yii\di\ServiceLocator
getControllerPath() 根据 $controllerNamespace 返回包含控制器类的目录. yii\base\Module
getInstance() 返回此模块类当前请求的实例. yii\base\Module
getLayoutPath() 返回包含此模块的布局视图文件的目录. yii\base\Module
getModule() 检索指定标识的子模块. yii\base\Module
getModules() 返回此模块中的子模块 yii\base\Module
getUniqueId() 返回在当前应用程序中的所有模块中唯一标识此模块的ID. yii\base\Module
getVersion() 返回当前模块的版本. yii\base\Module
getViewPath() 返回包含此模块的视图文件的目录. yii\base\Module
has() 返回一个值, 指示定位器是否具有指定的组件定义或是否已实例化该组件. yii\base\Module
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasModule() 检查是否存在指定ID的子模块. yii\base\Module
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
init() 初始化模块. yii\base\Module
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
runAction() 运行路由指定的控制器动作. yii\base\Module
set() 使用此定位器注册组件定义. yii\di\ServiceLocator
setAliases() 定义路径别名. yii\base\Module
setBasePath() 设置模块的根目录. yii\base\Module
setComponents() 在此定位器中注册一组组件定义. yii\di\ServiceLocator
setInstance() 设置此模块类的当前请求的实例. yii\base\Module
setLayoutPath() 设置包含布局文件的目录. yii\base\Module
setModule() 为此模块添加一个子模块. yii\base\Module
setModules() 在当前模块中注册子模块. yii\base\Module
setVersion() 设置当前模块的版本. yii\base\Module
setViewPath() 设置包含视图文件的目录. yii\base\Module
trigger() 触发事件. yii\base\Component

受保护的方法

隐藏继承的方法

方法描述定义在
defaultVersion() 返回模块的默认版本. yii\base\Module

事件

隐藏继承的事件

事件类型描述定义在
EVENT_AFTER_ACTION yii\base\ActionEvent 在执行控制器操作之后发生的事件. yii\base\Module
EVENT_BEFORE_ACTION yii\base\ActionEvent 在执行控制器操作之前发生的事件. yii\base\Module

属性详情

$aliases public 属性

要定义的路径别名列表. 数组键是别名(必须以@开头), 数组值是相应的路径或别名. 有关示例, 请参阅 setAliases(). 该属性是只写的.

public array $aliases null
$basePath public 属性

模块的根目录.

public string $basePath null
$controllerMap public 属性

从控制器ID映射到控制器配置.

每个 name-value 对指定单个控制器的配置. 控制器配置可以是字符串或数组. 如果是前者, 该字符串应该是控制器的完全限定类名. 如果是后者, 则该数组必须包含一个class元素, 该元素指定了控制器的完全限定类名, 并且数组中其余的 name-value 对用于初始化相应的控制器属性. 例如:

[
  'account' => 'app\controllers\UserController',
  'article' => [
     'class' => 'app\controllers\PostController',
     'pageTitle' => 'something new',
  ],
]
public array $controllerMap = []
$controllerNamespace public 属性

控制器类所在的命名空间. 该命名空间将用于通过将控制器类添加到控制器类名来加载控制器类.

如果未设置, 它将在该模块命名空间下的controllers子命名空间. 例如, 如果这个模块的命名空间是foo\bar, 那么默认的控制器命名空间就是foo\bar\controllers.

有关定义命名空间以及如何加载类的更多信息, 请参阅 权威指南 - 关键概念 - 类自动加载(Class Autoloading).

$controllerPath public 属性

包含控制器类的目录. 该属性是只读的.

public string $controllerPath null
$defaultRoute public 属性

该模块的默认路由. 默认为default.

路由可以由子模块ID, 控制器ID和/或动作ID组成. 例如help, post/create, admin/post/create.

如果未给出动作ID, 它将使用 yii\base\Controller::$defaultAction 中指定的默认值.

public string $defaultRoute 'default'
$id public 属性

在具有相同 父类 的其它模块中唯一标识该模块的ID.

public string $id null
$layout public 属性

该模块中应该应用于视图的布局. 这是指相对于 $layoutPath 的视图名称. 如果未设置, 则表示将采用 父模块 的布局值. 如果这是false, 则在此模块中将禁用布局.

public string|boolean $layout null
$layoutPath public 属性

布局文件的根目录. 默认为[[viewPath]]/layouts.

public string $layoutPath null
$module public 属性

该模块的父模块. 如果此模块没有父类, 则返回null.

public yii\base\Module $module null
$modules public 属性

模块(由其 ID 索引).

public array $modules null
$params public 属性

自定义模块参数(name => value).

public array $params = []
$uniqueId public 属性

模块的唯一ID. 该属性是只读的.

public string $uniqueId null
$version public 属性

该模块的版本. 请注意, 该属性的类型在 getter 和 setter 中有所不同. 有关详细信息, 请参阅 getVersion()setVersion().

public string $version null
$viewPath public 属性

视图文件的根目录. 默认为[[basePath]]/views.

public string $viewPath null

方法详情

__construct() public 方法

构造函数.

public void __construct ( $id, $parent null, $config = [] )
$id string

该模块的ID.

$parent yii\base\Module

父模块(如果有的话).

$config array

将用于初始化对象属性的 name-value 对.

afterAction() public 方法

在执行此模块中的动作之后立即调用此方法.

该方法将触发 EVENT_AFTER_ACTION 事件. 该方法的返回值将用作动作返回值.

如果你重写此方法, 则代码应如下所示:

public function afterAction($action, $result)
{
    $result = parent::afterAction($action, $result);
    // your custom code here
    return $result;
}
public mixed afterAction ( $action, $result )
$action yii\base\Action

刚刚执行的动作.

$result mixed

动作返回的结果.

return mixed

处理后的动作结果.

beforeAction() public 方法

在执行此模块中的动作之前调用此方法.

该方法将触发 EVENT_BEFORE_ACTION 事件. 该方法的返回值将决定动作是否应继续执行.

如果不应该执行该动作, 则应通过提供必要的输出或重定向请求, 在beforeAction代码内部处理该请求. 否则响应将是空的.

如果你重写此方法, 则代码应如下所示:

public function beforeAction($action)
{
    if (!parent::beforeAction($action)) {
        return false;
    }

    // your custom code here

    return true; // 或者返回 false, 表示不执行该动作
}
public boolean beforeAction ( $action )
$action yii\base\Action

要执行的动作.

return boolean

该动作是否应继续执行.

createController() public 方法

根据给定的路由创建一个控制器实例.

路由应该是相对于这个模块. 该方法实现以下算法来解析给定的路由:

  1. 如果路由是空的, 将使用 $defaultRoute;
  2. 如果在 $controllerMap 中找到路由的第一部分, 则根据 $controllerMap 中找到的相应配置创建一个控制器;
  3. 如果路由的第一部分是 $modules 中声明的有效模块ID, 则使用路由的其余部分调用模块的createController();
  4. 给定的路由格式为abc/def/xyz. 在 控制器命名空间 中尝试abc\DefControllerabc\def\XyzController类.

如果上述步骤中的任何一个解析成控制器, 则将其与路径的其余部分一起返回, 这些部分将被视为动作ID. 否则, 将返回false.

public array|boolean createController ( $route )
$route string

由模块, 控制器和动作ID组成的路由.

return array|boolean

如果成功创建控制器, 它将与请求的动作ID一起返回. 否则将返回false.

throws yii\base\InvalidConfigException

如果控制器类和它的文件名不匹配.

createControllerByID() public 方法

根据给定的控制器ID创建一个控制器.

控制器ID是相对于当前模块的. 控制器类应在 $controllerNamespace 下的命名空间.

Note: 此方法不会检查 $modules$controllerMap.

public yii\base\Controller|null createControllerByID ( $id )
$id string

控制器ID.

return yii\base\Controller|null

新创建的控制器实例. 如果控制器ID无效, 则返回null.

throws yii\base\InvalidConfigException

如果控制器类和它的文件名不匹配. 仅在调试模式下才会抛出此异常.

defaultVersion() protected 方法 (可用自版本: 2.0.11)

返回模块的默认版本.

子类可以重写此方法以提供更具体的版本检测.

protected string defaultVersion ( )
return string

该模块的版本.

get() public 方法

返回具有指定ID的组件实例.

从版本 2.0.13 开始, 如果模块中未定义组件, 则将在父模块中查找它. 父模块可以是应用程序.

public object|null get ( $id, $throwException true )
$id string

组件ID (eg. db).

$throwException boolean

如果$id未在定位器中注册, 是否抛出异常.

return object|null

指定ID的组件. 如果$throwExceptionfalse$id未注册, 则返回null.

throws yii\base\InvalidConfigException

如果$id引用一个不存在的组件ID.

getBasePath() public 方法

返回模块的根目录.

它默认为包含模块类文件的目录.

public string getBasePath ( )
return string

模块的根目录.

getControllerPath() public 方法

根据 $controllerNamespace 返回包含控制器类的目录.

Note: 请注意, 为了使此方法返回一个值, 必须为 $controllerNamespace 的根名称空间定义一个别名.

public string getControllerPath ( )
return string

包含控制器类的目录.

throws yii\base\InvalidArgumentException

如果没有为 $controllerNamespace 的根名称空间定义别名.

getInstance() public static 方法

返回此模块类当前请求的实例.

如果当前未请求模块类, 则返回null. 提供此方法是为了从模块内的任何位置访问模块实例.

public static static|null getInstance ( )
return static|null

当前请求的此模块类的实例, 如果未请求模块类, 则返回null.

getLayoutPath() public 方法

返回包含此模块的布局视图文件的目录.

public string getLayoutPath ( )
return string

布局文件的根目录. 默认为[[viewPath]]/layouts.

getModule() public 方法

检索指定标识的子模块.

该方法支持检索子模块和宏子模块(后代模块).

参见 hasModule().

public yii\base\Module|null getModule ( $id, $load true )
$id string

模块ID(区分大小写). 要检索宏子模块(后代模块), 请使用相对于此模块的ID路径(eg. admin/content).

$load boolean

如果模块尚未加载, 是否加载模块.

return yii\base\Module|null

模块实例. 如果模块不存在, 则为null.

getModules() public 方法

返回此模块中的子模块

public array getModules ( $loadedOnly false )
$loadedOnly boolean

是否仅返回已加载的子模块. 如果设置为false, 则无论是否已加载, 此模块中注册的所有子模块都将被返回. 加载的模块将作为对象返回, 而卸载的模块作为配置数组.

return array

模块(由它们的 ID 索引).

getUniqueId() public 方法

返回在当前应用程序中的所有模块中唯一标识此模块的ID.

Note: 如果模块是应用程序, 则会返回空字符串.

public string getUniqueId ( )
return string

模块的唯一ID.

getVersion() public 方法 (可用自版本: 2.0.11)

返回当前模块的版本.

如果未明确设置版本, 将使用 defaultVersion() 方法来确定其值.

public string getVersion ( )
return string

当前模块的版本.

getViewPath() public 方法

返回包含此模块的视图文件的目录.

public string getViewPath ( )
return string

视图文件的根目录. 默认为[[basePath]]/views.

has() public 方法

返回一个值, 指示定位器是否具有指定的组件定义或是否已实例化该组件.

从版本 2.0.13 开始, 如果模块中未定义组件, 则将在父模块中查找它. 父模块可以是应用程序.

此方法可能返回不同的结果, 具体取决于$checkInstance的值.

  • 如果$checkInstancefalse(默认), 则该方法将返回一个值, 指示定位器是否具有指定的组件定义.
  • 如果$checkInstancetrue, 则该方法将返回一个值, 指示定位器是否已实例化指定的组件.
public boolean has ( $id, $checkInstance false )
$id string

组件ID (eg. db).

$checkInstance boolean

该方法是否应检查组件是否已共享和实例化.

return boolean

定位器是否具有指定的组件定义或是否已实例化该组件.

hasModule() public 方法

检查是否存在指定ID的子模块.

该方法支持检查是否存在子模块和宏子模块(后代模块).

public boolean hasModule ( $id )
$id string

模块ID. 对于宏子模块(后代模块), 请使用相对于此模块的ID路径(eg. admin/content).

return boolean

是否存在已命名的模块. 已加载和已卸载的模块都被考虑在内.

init() public 方法

初始化模块.

在创建模块并使用配置中给定的属性值进行初始化之后调用此方法. 如果未设置, 默认实现将初始化 $controllerNamespace.

如果重写此方法, 请确保调用了父实现.

public void init ( )
runAction() public 方法

运行路由指定的控制器动作.

该方法解析指定的路由并创建相应的子模块, 控制器和动作实例. 然后调用 yii\base\Controller::runAction() 来运行具有给定参数的动作. 如果路由为空, 该方法将使用 $defaultRoute.

public mixed runAction ( $route, $params = [] )
$route string

指定动作的路由.

$params array

要传递给动作的参数.

return mixed

动作的结果.

throws yii\base\InvalidRouteException

如果请求的路由无法成功解析为动作.

setAliases() public 方法

定义路径别名.

该方法调用 Yii::setAlias() 来注册路径别名. 提供此方法以便你可以在配置模块时定义路径别名.

public void setAliases ( $aliases )
$aliases array

要定义的路径别名列表. 数组键是别名(必须以@开头), 数组值是相应的路径或别名. 例如:

[
    '@models' => '@app/models', // an existing alias
    '@backend' => __DIR__ . '/../backend',  // a directory
]
setBasePath() public 方法

设置模块的根目录.

该方法只能在构造函数的开头调用.

public void setBasePath ( $path )
$path string

模块的根目录. 这可以是目录名称或 路径别名.

throws yii\base\InvalidArgumentException

如果目录不存在.

setInstance() public static 方法

设置此模块类的当前请求的实例.

public static void setInstance ( $instance )
$instance yii\base\Module|null

当前请求的该模块类的实例. 如果它是null, 则将删除调用类的实例(如果有的话).

setLayoutPath() public 方法

设置包含布局文件的目录.

public void setLayoutPath ( $path )
$path string

布局文件的根目录或 路径别名.

throws yii\base\InvalidArgumentException

如果目录不存在.

setModule() public 方法

为此模块添加一个子模块.

public void setModule ( $id, $module )
$id string

模块ID.

$module yii\base\Module|array|null

要添加到此模块的子模块. 这可以是以下之一:

  • 一个 yii\base\Module 对象;
  • 一个配置数组: 当初始调用 getModule() 时, 该数组将用于实例化子模块;
  • null: 指定的子模块将从该模块中删除.
setModules() public 方法

在当前模块中注册子模块.

应该将每个子模块指定为一个 name-value 对, 其中 name 是指模块的ID, 并且可以指定可用于创建模块的模块配置或实例. 在后一种情况下, 将使用 Yii::createObject() 创建模块.

如果新的子模块与现有的子模块具有相同的ID, 则现有的模块将被无提示的覆盖.

以下是注册两个子模块的示例:

[
    'comment' => [
        'class' => 'app\modules\comment\CommentModule',
        'db' => 'db',
    ],
    'booking' => ['class' => 'app\modules\booking\BookingModule'],
]
public void setModules ( $modules )
$modules array

模块(id => 模块配置或实例).

setVersion() public 方法 (可用自版本: 2.0.11)

设置当前模块的版本.

public void setVersion ( $version )
$version string|callable

该模块的版本. 版本可以指定为 PHP 回调, 它可以接受模块实例作为参数, 并应返回实际的版本. 例如:

function (Module $module) {
    //return string
}
setViewPath() public 方法

设置包含视图文件的目录.

public void setViewPath ( $path )
$path string

视图文件的根目录.

throws yii\base\InvalidArgumentException

如果目录不存在.

事件详情

EVENT_AFTER_ACTION 事件类型 yii\base\ActionEvent

在执行控制器操作之后发生的事件.

EVENT_BEFORE_ACTION 事件类型 yii\base\ActionEvent

在执行控制器操作之前发生的事件. 你可以将 yii\base\ActionEvent::$isValid 设置为false来取消操作的执行.