4 个关注者

应用程序 ¶

应用程序配置
应用程序属性
应用程序事件
应用程序生命周期

应用程序是管理 Yii 应用程序系统整体结构和生命周期的对象。每个 Yii 应用程序系统都包含一个应用程序对象，该对象在入口脚本中创建，并且可以通过表达式 \Yii::$app 全局访问。

信息：根据上下文，当我们说“一个应用程序”时，它可以指应用程序对象或应用程序系统。

应用程序有两种类型：Web 应用程序和控制台应用程序。顾名思义，前者主要处理 Web 请求，而后者处理控制台命令请求。

应用程序配置 ¶

当入口脚本创建应用程序时，它将加载一个配置并将其应用于应用程序，如下所示

require __DIR__ . '/../vendor/autoload.php';
require __DIR__ . '/../vendor/yiisoft/yii2/Yii.php';

// load application configuration
$config = require __DIR__ . '/../config/web.php';

// instantiate and configure the application
(new yii\web\Application($config))->run();

与普通配置一样，应用程序配置指定如何初始化应用程序对象的属性。由于应用程序配置通常非常复杂，因此通常保存在配置文件中，例如上面示例中的 web.php 文件。

应用程序属性 ¶

在应用程序配置中，有许多重要的应用程序属性需要您配置。这些属性通常描述应用程序运行的环境。例如，应用程序需要知道如何加载控制器、在哪里存储临时文件等。在下文中，我们将总结这些属性。

必需属性 ¶

在任何应用程序中，您至少应配置两个属性：id 和 basePath。

id ¶

id 属性指定一个唯一的 ID，用于区分应用程序。它主要用于编程方式。虽然不是强制要求，但为了最佳的互操作性，建议在指定应用程序 ID 时仅使用字母数字字符。

basePath ¶

basePath 属性指定应用程序的根目录。它是包含应用程序系统所有受保护源代码的目录。在此目录下，您通常会看到诸如 models、views 和 controllers 等子目录，它们包含与 MVC 模式相对应的源代码。

您可以使用目录路径或路径别名配置 basePath 属性。无论哪种形式，相应的目录都必须存在，否则会抛出异常。路径将通过调用 realpath() 函数进行规范化。

basePath 属性通常用于推导出其他重要路径（例如运行时路径）。出于这个原因，预定义了一个名为 @app 的路径别名来表示此路径。然后可以使用此别名来形成派生路径（例如 @app/runtime 用于引用运行时目录）。

重要属性 ¶

本节中描述的属性通常需要配置，因为它们在不同的应用程序之间有所不同。

aliases ¶

此属性允许您以数组的形式定义一组别名。数组键是别名名称，数组值是相应的路径定义。例如

[
    'aliases' => [
        '@name1' => 'path/to/path1',
        '@name2' => 'path/to/path2',
    ],
]

提供此属性是为了让您能够在应用程序配置方面定义别名，而不是通过调用 Yii::setAlias() 方法。

bootstrap ¶

这是一个非常有用的属性。它允许您指定在应用程序启动过程期间应运行的组件数组。例如，如果您希望模块自定义 URL 规则，则可以在此属性中列出其 ID。

在此属性中列出的每个组件都可以使用以下格式之一指定

通过 components 指定的应用程序组件 ID，
通过 modules 指定的模块 ID，
类名，
配置数组，
创建并返回组件的匿名函数。

例如

[
    'bootstrap' => [
        // an application component ID or module ID
        'demo',

        // a class name
        'app\components\Profiler',

        // a configuration array
        [
            'class' => 'app\components\Profiler',
            'level' => 3,
        ],

        // an anonymous function
        function () {
            return new app\components\Profiler();
        }
    ],
]

信息：如果模块 ID 与应用程序组件 ID 相同，则应用程序组件将在启动过程中使用。如果您希望使用该模块，则可以使用以下匿名函数指定它
[
    function () {
        return Yii::$app->getModule('user');
    },
]

在启动过程中，将实例化每个组件。如果组件类实现了 yii\base\BootstrapInterface，则还会调用其 bootstrap() 方法。

另一个实际示例是基本项目模板的应用程序配置，其中 debug 和 gii 模块在应用程序在开发环境中运行时被配置为启动组件

if (YII_ENV_DEV) {
    // configuration adjustments for 'dev' environment
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = 'yii\debug\Module';

    $config['bootstrap'][] = 'gii';
    $config['modules']['gii'] = 'yii\gii\Module';
}

注意：在 bootstrap 中放置过多的组件会导致应用程序性能下降，因为对于每个请求，都需要运行相同的组件集。因此，请明智地使用启动组件。

components ¶

这是最重要的属性。它允许您注册一个名为应用程序组件的命名组件列表，您可以在其他地方使用它们。例如

[
    'components' => [
        'cache' => [
            'class' => 'yii\caching\FileCache',
        ],
        'user' => [
            'identityClass' => 'app\models\User',
            'enableAutoLogin' => true,
        ],
    ],
]

每个应用程序组件都以数组中的键值对形式指定。键表示组件 ID，而值表示组件类名或配置。

您可以将任何组件注册到应用程序，并且随后可以使用表达式 \Yii::$app->componentID 在全局范围内访问该组件。

有关详细信息，请阅读应用程序组件部分。

此属性允许您将控制器 ID 映射到任意控制器类。默认情况下，Yii 会根据约定将控制器 ID 映射到控制器类（例如，ID post 将映射到 app\controllers\PostController）。通过配置此属性，您可以为特定控制器打破约定。在以下示例中，account 将映射到 app\controllers\UserController，而 article 将映射到 app\controllers\PostController。

[
    'controllerMap' => [
        'account' => 'app\controllers\UserController',
        'article' => [
            'class' => 'app\controllers\PostController',
            'enableCsrfValidation' => false,
        ],
    ],
]

此属性的数组键表示控制器 ID，而数组值表示相应的控制器类名或配置。

controllerNamespace ¶

此属性指定控制器类应位于其中的默认命名空间。它默认为 app\controllers。如果控制器 ID 是 post，根据约定，相应的控制器类名（不带命名空间）将是 PostController，完全限定的类名为 app\controllers\PostController。

控制器类也可以位于与此命名空间相对应的目录的子目录下。例如，给定一个控制器 ID admin/post，相应的完全限定控制器类将是 app\controllers\admin\PostController。

重要的是，完全限定的控制器类应该是可自动加载的，并且控制器类的实际命名空间应与此属性的值匹配。否则，在访问应用程序时，您将收到“页面未找到”错误。

如果您希望打破上述约定，则可以配置 controllerMap 属性。

language ¶

此属性指定应用程序应以何种语言向最终用户显示内容。此属性的默认值为 en，表示英语。如果您的应用程序需要支持多种语言，您应该配置此属性。

此属性的值决定了各种国际化方面，包括消息翻译、日期格式化、数字格式化等。例如，yii\jui\DatePicker 小部件默认情况下将使用此属性值来确定日历应以何种语言显示以及如何格式化日期。

建议您使用 IETF 语言标签指定语言。例如，en 代表英语，而 en-US 代表英语（美国）。

有关此属性的更多详细信息，请参阅国际化部分。

modules ¶

此属性指定应用程序包含的模块。

该属性采用模块类或配置数组，其中数组键是模块 ID。例如

[
    'modules' => [
        // a "booking" module specified with the module class
        'booking' => 'app\modules\booking\BookingModule',

        // a "comment" module specified with a configuration array
        'comment' => [
            'class' => 'app\modules\comment\CommentModule',
            'db' => 'db',
        ],
    ],
]

有关更多详细信息，请参阅模块部分。

name ¶

此属性指定应用程序名称，该名称可能会显示给最终用户。与 id 属性（应采用唯一值）不同，此属性的值主要用于显示目的；它不需要唯一。

如果您的代码没有使用此属性，则您并不总是需要配置它。

params ¶

此属性指定一个全局可访问的应用程序参数数组。与其在代码中到处使用硬编码的数字和字符串，不如将它们定义为一个位置的应用程序参数，并在需要的地方使用这些参数。例如，您可以将缩略图图像大小定义为一个参数，如下所示

[
    'params' => [
        'thumbnail.size' => [128, 128],
    ],
]

然后在您的代码中，当您需要使用 size 值时，您可以简单地使用以下代码

$size = \Yii::$app->params['thumbnail.size'];
$width = \Yii::$app->params['thumbnail.size'][0];

稍后，如果您决定更改缩略图大小，您只需在应用程序配置中修改它；您无需触碰任何依赖代码。

sourceLanguage ¶

此属性指定应用程序代码编写的语言。默认值为 'en-US'，表示英语（美国）。如果代码中的文本内容不是英文，您应该配置此属性。

与 language 属性一样，您应该使用 IETF 语言标签配置此属性。例如，en 代表英语，而 en-US 代表英语（美国）。

有关此属性的更多详细信息，请参阅国际化部分。

timeZone ¶

此属性作为设置 PHP 运行时默认时区的另一种方式提供。通过配置此属性，您实际上是在调用 PHP 函数 date_default_timezone_set()。例如

[
    'timeZone' => 'America/Los_Angeles',
]

有关设置时区的更多详细信息，请查看日期格式化部分。

version ¶

此属性指定应用程序的版本。它默认为 '1.0'。如果您的代码没有使用此属性，则您并不总是需要配置它。

有用属性 ¶

本节中描述的属性通常不需配置，因为它们的默认值源于通用约定。但是，如果您希望打破约定，您仍然可以配置它们。

charset ¶

此属性指定应用程序使用的字符集。默认值为 'UTF-8'，对于大多数应用程序，应保持原样，除非您正在使用使用大量非 Unicode 数据的旧系统。

defaultRoute ¶

此属性指定当请求未指定路由时，应用程序应使用的路由。该路由可能包含子模块 ID、控制器 ID 和/或操作 ID。例如，help、post/create 或 admin/post/create。如果没有给出操作 ID，此属性将采用在 yii\base\Controller::$defaultAction 中指定的默认值。

对于Web 应用程序，此属性的默认值为 'site'，这意味着应使用 SiteController 控制器及其默认操作。因此，如果您在未指定路由的情况下访问应用程序，它将显示 app\controllers\SiteController::actionIndex() 的结果。

对于控制台应用程序，默认值为 'help'，这意味着应使用核心命令 yii\console\controllers\HelpController::actionIndex()。因此，如果您在不提供任何参数的情况下运行命令 yii，它将显示帮助信息。

扩展 ¶

此属性指定已安装并由应用程序使用的扩展列表。默认情况下，它将获取文件 @vendor/yiisoft/extensions.php 返回的数组。当您使用 Composer 安装扩展时，extensions.php 文件会自动生成和维护。因此，在大多数情况下，您不需要配置此属性。

在您想手动维护扩展的特殊情况下，您可以按如下方式配置此属性

[
    'extensions' => [
        [
            'name' => 'extension name',
            'version' => 'version number',
            'bootstrap' => 'BootstrapClassName',  // optional, may also be a configuration array
            'alias' => [  // optional
                '@alias1' => 'to/path1',
                '@alias2' => 'to/path2',
            ],
        ],

        // ... more extensions like the above ...

    ],
]

如您所见，该属性接受一个扩展规范数组。每个扩展都用包含 name 和 version 元素的数组指定。如果扩展需要在引导过程中运行，则可以使用一个 bootstrap 元素指定一个引导类名或一个配置数组。扩展还可以定义一些别名。

布局 ¶

此属性指定在渲染视图时应使用的默认布局的名称。默认值为 'main'，表示应使用布局路径下的 main.php 布局文件。如果布局路径和视图路径都采用默认值，则默认布局文件可以用路径别名 @app/views/layouts/main.php 表示。

如果您想默认禁用布局，可以将此属性配置为 false，尽管这种情况很少见。

布局路径 ¶

此属性指定查找布局文件的路径。默认值为视图路径下的 layouts 子目录。如果视图路径采用其默认值，则默认布局路径可以用路径别名 @app/views/layouts 表示。

您可以将其配置为目录或路径别名。

运行时路径 ¶

此属性指定可以生成临时文件（如日志文件和缓存文件）的路径。默认值为别名 @app/runtime 表示的目录。

您可以将其配置为目录或路径别名。请注意，运行时路径必须可由运行应用程序的进程写入。并且该路径应该受到保护，防止最终用户访问，因为其中的临时文件可能包含敏感信息。

为了简化对该路径的访问，Yii 为其预定义了一个名为 @runtime 的路径别名。

视图路径 ¶

此属性指定视图文件所在的根目录。默认值为别名 @app/views 表示的目录。您可以将其配置为目录或路径别名。

供应商路径 ¶

此属性指定由 Composer 管理的供应商目录。它包含应用程序使用（包括 Yii 框架）的所有第三方库。默认值为别名 @app/vendor 表示的目录。

您可以将此属性配置为目录或路径别名。当您修改此属性时，请确保也相应地调整 Composer 配置。

为了简化对该路径的访问，Yii 为其预定义了一个名为 @vendor 的路径别名。

启用核心命令 ¶

此属性仅由控制台应用程序支持。它指定是否应启用 Yii 版本中包含的核心命令。默认值为 true。

应用程序事件 ¶

应用程序在处理请求的生命周期中会触发多个事件。您可以在应用程序配置中将事件处理程序附加到这些事件，如下所示

[
    'on beforeRequest' => function ($event) {
        // ...
    },
]

on eventName 语法的使用在配置部分进行了描述。

或者，您可以在创建应用程序实例后，在引导过程中附加事件处理程序。例如

\Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) {
    // ...
});

EVENT_BEFORE_REQUEST ¶

此事件在应用程序处理请求之前触发。实际的事件名称是 beforeRequest。

当此事件被触发时，应用程序实例已被配置和初始化。因此，这是一个通过事件机制插入您的自定义代码以拦截请求处理过程的好地方。例如，在事件处理程序中，您可以基于某些参数动态设置yii\base\Application::$language 属性。

EVENT_AFTER_REQUEST ¶

此事件在应用程序完成处理请求之后但在发送响应之前触发。实际的事件名称是 afterRequest。

当此事件被触发时，请求处理已完成，您可以抓住这个机会对请求进行一些后处理或自定义响应。

请注意，响应组件在向最终用户发送响应内容时也会触发一些事件。这些事件在此事件之后触发。

EVENT_BEFORE_ACTION ¶

此事件在运行每个控制器操作之前触发。实际的事件名称是 beforeAction。

事件参数是 yii\base\ActionEvent 的实例。事件处理程序可以将yii\base\ActionEvent::$isValid 属性设置为 false 以停止运行操作。例如

[
    'on beforeAction' => function ($event) {
        if (some condition) {
            $event->isValid = false;
        } else {
        }
    },
]

请注意，相同的 beforeAction 事件也会由模块和控制器触发。应用程序对象是第一个触发此事件的对象，然后是模块（如果有），最后是控制器。如果事件处理程序将yii\base\ActionEvent::$isValid 设置为 false，则所有后续事件都将不触发。

EVENT_AFTER_ACTION ¶

此事件在运行每个控制器操作之后触发。实际的事件名称是 afterAction。

事件参数是 yii\base\ActionEvent 的实例。通过yii\base\ActionEvent::$result 属性，事件处理程序可以访问或修改操作结果。例如

[
    'on afterAction' => function ($event) {
        if (some condition) {
            // modify $event->result
        } else {
        }
    },
]

请注意，相同的 afterAction 事件也会由模块和控制器触发。这些对象以与 beforeAction 相反的顺序触发此事件。也就是说，控制器是第一个触发此事件的对象，然后是模块（如果有），最后是应用程序。

应用程序生命周期 ¶

Application Lifecycle

当执行入口脚本来处理请求时，应用程序将经历以下生命周期

入口脚本将应用程序配置加载为数组。
入口脚本创建应用程序的新实例
- preInit() 被调用，它配置一些高优先级的应用程序属性，例如basePath。
- 注册错误处理程序。
- 配置应用程序属性。
- init() 被调用，它进一步调用bootstrap() 来运行引导组件。
入口脚本调用yii\base\Application::run() 来运行应用程序
- 触发EVENT_BEFORE_REQUEST 事件。
- 处理请求：将请求解析为路由和关联的参数；创建路由指定的模块、控制器和操作对象；并运行操作。
- 触发EVENT_AFTER_REQUEST 事件。
- 将响应发送给最终用户。
入口脚本接收来自应用程序的退出状态，并完成请求处理。

入口脚本

返回顶部

应用程序组件

发现错字或您认为此页面需要改进？
在 github 上编辑它 !