diff --git a/docs/guide-zh-CN/structure-application-components.md b/docs/guide-zh-CN/structure-application-components.md index e32a4f1..47a1b08 100644 --- a/docs/guide-zh-CN/structure-application-components.md +++ b/docs/guide-zh-CN/structure-application-components.md @@ -1,27 +1,31 @@ -应用对象 +应用组件 ====================== -应用是[服务定位器](concept-service-locators.md)。它们维护一个集合被称为**应用组件**为处理请求提供不同的服务。例如，`urlManager` 组件负责转发 Web 请求至相应的控制器；`db` 组件提供数据库相关服务，等等。 +应用主体是[服务定位器](concept-service-locator.md)，它部署一组提供各种不同功能的 *应用组件* 来处理请求。 +例如，`urlManager`组件负责处理网页请求路由到对应的控制器。`db`组件提供数据库相关服务等等。 -同一个应用中的每个组件都有一个唯一 ID 用来与其它组件作区分。你可以通过表达式访问一个应用组件： +在同一个应用中，每个应用组件都有一个独一无二的 ID 用来区分其他应用组件，你可以通过如下表达式访问应用组件。 ```php \Yii::$app->componentID ``` -例如，你可以使用 `\Yii::$app->db` 去获取 [[yii\db\Connection|数据库连接（DB connection），使用`\Yii::$app->cache` 去获取应用注册的[[yii\caching\Cache|主缓存]]。 +例如，可以使用 `\Yii::$app->db` 来获取到已注册到应用的 [[yii\db\Connection|DB connection]]， +使用 `\Yii::$app->cache` 来获取到已注册到应用的 [[yii\caching\Cache|primary cache]]。 -一个应用组件在使用上述表达式第一次访问的时候创建。其后任何访问都将返回同样的组件实例。 +第一次使用以上表达式时候会创建应用组件实例，后续再访问会返回此实例，无需再次创建。 -应用组件可以是任何对象。你可以通过[应用配置](structure-applications.md#application-configurations)的 [yii\base\Application::components]] 属性注册它们。例如： +应用组件可以是任意对象，可以在 [应用主体配置](structure-applications.md#application-configurations) +配置 [[yii\base\Application::components]] 属性 . +例如： ```php [ 'components' => [ - // 使用一个类名去注册“缓存”组件 + // 使用类名注册 "cache" 组件 'cache' => 'yii\caching\ApcCache', - // 使用配置数组注册“db”组件 + // 使用配置数组注册 "db" 组件 'db' => [ 'class' => 'yii\db\Connection', 'dsn' => 'mysql:host=localhost;dbname=demo', @@ -29,7 +33,7 @@ 'password' => '', ], - // 使用匿名函数注册搜索组件 + // 使用函数注册"search" 组件 'search' => function () { return new app\components\SolrService; }, @@ -37,14 +41,17 @@ ] ``` -> 补充：尽管你可以随心所欲注册任何数量的组件，但应该明智去做。应用组件就像全局变量。使用太多应用组件可能潜在的会让代码难以测试和维护。许多情况下，你可以简单创建一个本地组件并在需要时使用。 +> 补充：请谨慎注册太多应用组件，应用组件就像全局变量，使用太多可能加大测试和维护的难度。 + 一般情况下可以在需要时再创建本地组件。 -## 引导组件 +## 引导启动组件 -如上所述，应用组件只在第一次被访问时实例化。如果在请求期间没有访问组件，它将根本不会实例化。有时候，无论怎样你可能都想为每个请求实例化组件，即便它没有被访问。你可以在应用的 [[yii\base\Application::bootstrap|引导（bootstrap）]] 属性罗列组件 ID 来做到这点。 +上面提到一个应用组件只会在第一次访问时实例化，如果处理请求过程没有访问的话就不实例化。 +有时你想在每个请求处理过程都实例化某个组件即便它不会被访问， +可以将该组件ID加入到应用主体的 [[yii\base\Application::bootstrap|bootstrap]] 属性中。 -例如，下述应用配置代码确保了 `log` 组件在任何情况下都载入： +例如, 如下的应用主体配置保证了 `log` 组件一直被加载。 ```php [ @@ -54,7 +61,7 @@ ], 'components' => [ 'log' => [ - // 配置 log 组件 + // "log" 组件的配置 ], ], ] @@ -63,20 +70,33 @@ ## 核心应用组件 -Yii 定义了一系列拥有固定 ID 和默认配置的**核心**应用组件。例如：[[yii\web\Application::request|请求（request）]]组件被用来收集用户请求数据并解析请求至[路由](runtime-routing.md)；[[yii\base\Application::db|数据库（db）]]组件代表一个数据库连接，你可以通过它执行数据库查询。Yii 有赖于这些核心组件的支持去处理用户请求。 - -下面是预定义的核心组件列表。你可以像配置普通应用组件一样配置和自定义它们。当你配置一个核心组件时，如果没有指定类名，默认类名将被使用。 - -* [[yii\web\AssetManager|资源管理器（assetManager）]]：管理静态资源包和静态资源发布。请参考[资源管理](output-assets.md)章节了解详细内容。 -* [[yii\db\Connection|数据库（db）]]：代表一个数据库连接，你可以通过它执行数据库查询。请注意，当你配置这个组件时，必须和本组件的其它属性一样去配置组建类，诸如 [[yii\db\Connection::dsn]]。请参考[数据访问对象](db-dao.md)章节了解详细内容。 -* [[yii\base\Application::errorHandler|错误处理器（errorHandler）]]：处理 PHP 错误和异常。请参考[错误处理](tutorial-handling-errors.md)章节了解详细内容。 -* [[yii\base\Formatter|格式化器（formatter）]]：格式化向最终用户显示的数据。例如，数字可能会想显示千位分隔符，日期可能会想要长格式。请参考[数据格式化](output-formatting.md)章节了解详细内容。 -* [[yii\i18n\I18N|国际化（i18n）]]：支持信息翻译转换和格式化。请参考[国际化](tutorial-i18n.md)章节了解详细内容。 -* [[yii\log\Dispatcher|日志（log）]]：管理日志目标。请参考[日志](tutorial-logging.md)章节了解详细内容。 -* [[yii\swiftmailer\Mailer|邮件（mail）]]：支持邮件接收和发送。请参考[邮件](tutorial-mailing.md)章节了解详细内容。 -* [[yii\base\Application::response|响应（response）]]：代表将要发送给最终用户的响应内容。请参考[响应](runtime-responses.md)章节了解详细内容。 -* [[yii\base\Application::request|请求（request）]]：代表从最终用户那收到的请求。请参考[请求](runtime-requests.md)章节了解详细内容。 -* [[yii\web\Session|会话（session）]]：代表会话信息。这个组件只在 [[yii\web\Application|Web 应用]]中可用。请参考[会话和 Cookies](runtime-sessions-and-cookies.md) 章节了解详细内容。 -* [[yii\web\UrlManager|URL 管理（urlManager）]]：支持 URL 的解析和创建。请参考 [URL 解析和生成](runtime-url-handling.md)章节了解详细内容。 -* [[yii\web\User|用户（user）]]：代表用户认证信息。这个组件只在 [[yii\web\Application|Web 应用]]中可用。请参考[认证](security-authentication.md)章节了解详细内容。 -* [[yii\web\View|视图（view）]]：支持视图渲染。请参考[视图](structure-views.md)章节了解详细内容。 +Yii 定义了一组固定ID和默认配置的 *核心* 组件，例如 [[yii\web\Application::request|request]] 组件 +用来收集用户请求并解析 [路由](runtime-routing.md)； +[[yii\base\Application::db|db]] 代表一个可以执行数据库操作的数据库连接。 +通过这些组件，Yii应用主体能处理用户请求。 + +下面是预定义的核心应用组件列表，可以和普通应用组件一样配置和自定义它们。 +当你配置一个核心组件，不指定它的类名的话就会使用Yii默认指定的类。 + +* [[yii\web\AssetManager|assetManager]]: 管理资源包和资源发布，详情请参考 [管理资源](output-assets.md) 一节。 +* [[yii\db\Connection|db]]: 代表一个可以执行数据库操作的数据库连接， + 注意配置该组件时必须指定组件类名和其他相关组件属性，如[[yii\db\Connection::dsn]]。 + 详情请参考 [数据访问对象](db-dao.md) 一节。 +* [[yii\base\Application::errorHandler|errorHandler]]: 处理 PHP 错误和异常， + 详情请参考 [错误处理](tutorial-handling-errors.md) 一节。 +* [[yii\i18n\Formatter|formatter]]: 格式化输出显示给终端用户的数据，例如数字可能要带分隔符， + 日期使用长格式。详情请参考 [格式化输出数据](output-formatting.md) 一节。 +* [[yii\i18n\I18N|i18n]]: 支持信息翻译和格式化。详情请参考 [国际化](tutorial-i18n.md) 一节。 +* [[yii\log\Dispatcher|log]]: 管理日志对象。详情请参考 [日志](tutorial-logging.md) 一节。 +* [[yii\swiftmailer\Mailer|mail]]: 支持生成邮件结构并发送，详情请参考 [邮件](tutorial-mailing.md) 一节。 +* [[yii\base\Application::response|response]]: 代表发送给用户的响应， + 详情请参考 [响应](runtime-responses.md) 一节。 +* [[yii\base\Application::request|request]]: 代表从终端用户处接收到的请求， + 详情请参考 [请求](runtime-requests.md) 一节。 +* [[yii\web\Session|session]]: 代表会话信息，仅在[[yii\web\Application|Web applications]] 网页应用中可用， + 详情请参考 [Sessions (会话) and Cookies](runtime-sessions-cookies.md) 一节。 +* [[yii\web\UrlManager|urlManager]]: 支持URL地址解析和创建， + 详情请参考 [URL 解析和生成](runtime-url-handling.md) 一节。 +* [[yii\web\User|user]]: 代表认证登录用户信息，仅在[[yii\web\Application|Web applications]] 网页应用中可用， + 详情请参考 [认证](security-authentication.md) 一节。 +* [[yii\web\View|view]]: 支持渲染视图，详情请参考 [Views](structure-views.md) 一节。 diff --git a/docs/guide-zh-CN/structure-applications.md b/docs/guide-zh-CN/structure-applications.md index 91a76af..71a76ef 100644 --- a/docs/guide-zh-CN/structure-applications.md +++ b/docs/guide-zh-CN/structure-applications.md @@ -1,64 +1,71 @@ -应用 +应用主体 ============ -应用是管理整个 Yii 应用系统总体结构和生命周期的对象。每个 Yii 应用系统都包含一个由[入口脚本](structure-entry-scripts.md)创建的单例对象，可以在全局范围通过表达式 `\Yii:$app` 访问。 +应用主体是管理 Yii 应用系统整体结构和生命周期的对象。 +每个Yii应用系统只能包含一个应用主体，应用主体在 [入口脚本](structure-entry-scripts.md) 中创建并能通过表达式 `\Yii::$app` 全局范围内访问。 -> 补充：取决于上下文环境不同，当讲到“一个应用”时，它可能是一个应用对象的意思，也可能指整个应用系统。 +> 补充: 当我们说"一个应用"，它可能是一个应用主体对象，也可能是一个应用系统，是根据上下文来决定[译：中文为避免歧义，Application翻译为应用主体]。 -应用有两种类型：[[yii\web\Application|Web 应用]] 和 [[yii\console\Application|控制台应用]]。顾名思义，前者主要处理 Web 请求而后者则处理控制台命令请求。 +Yii有两种应用主体: [[yii\web\Application|网页应用主体]] and +[[yii\console\Application|控制台应用主体]]， 如名称所示，前者主要处理网页请求，后者处理控制台请求。 -## 应用配置 +## 应用主体配置 -当[入口脚本](structure-entry-scripts.md)创建一个应用，它将载入[配置](concept-configurations.md)并将其应用在应用中，如下： +如下所示，当 [入口脚本](structure-entry-scripts.md) 创建了一个应用主体，它会加载一个 [配置](concept-configurations.md) 文件并传给应用主体。 ```php require(__DIR__ . '/../vendor/autoload.php'); require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php'); -// 载入应用配置 +// 加载应用主体配置 $config = require(__DIR__ . '/../config/web.php'); -// 实例化并配置应用 +// 实例化应用主体、配置应用主体 (new yii\web\Application($config))->run(); ``` -正如[配置](concept-configurations.md)所述，应用配置指定了如何初始化应用对象的属性。应用配置往往比较复杂，所以它们被保存在[配置文件](concept-configurations.md#configuration-files)中，例如上述代码中的 `web.php`。 +类似其他 [配置](concept-configurations.md) 文件, 应用主体配置文件标明如何设置应用对象初始属性。 +由于应用主体配置比较复杂，一般保存在多个类似如上web.php的 [配置文件](concept-configurations.md#configuration-files) 当中。 +## 应用主体属性 -## 应用属性 +应用主体配置文件中有许多重要的属性要配置，这些属性指定应用主体的运行环境。 +比如，应用主体需要知道如何加载 [控制器](structure-controllers.md) ，临时文件保存到哪儿等等。 +以下我们简述这些属性。 -在应用中有相当多的重要属性需要配置。这些属性通常描述了应用运行的环境。例如，应用需要知道如何载入[控制器](structure-controllers.md)，哪里储存临时文件，等等。下面我们将总结这些属性。 +### 必要属性 - -### 必需属性 - -在任何应用中，你应该至少配置两个属性：[[yii\base\Application::id|id]] 和 [[yii\base\Application::basePath|basePath]]。 +在一个应用中，至少要配置2个属性: [[yii\base\Application::id|id]] 和 [[yii\base\Application::basePath|basePath]]。 #### [[yii\base\Application::id|id]] -[[yii\base\Application::id|id]] 属性指定了一个应用区别于其它应用的唯一 ID。主要以编程方式使用它。尽管不是必要条件，但为了最佳互通性，还是建议你仅使用字母和数字去指定应用 ID。 +[[yii\base\Application::id|id]] 属性用来区分其他应用的唯一标识ID。主要给程序使用。 +为了方便协作，最好使用数字作为应用主体ID，但不强制要求为数字。 -#### [[yii\base\Application::basePath|基本路径（basePath）]] +#### [[yii\base\Application::basePath|basePath]] -[[yii\base\Application::basePath|basePath]] 属性指定了一个应用的根目录。这个目录包含了应用系统的所有受保护源码。在此目录下，你通常会看到诸如 `models`，`views`，`controllers` 之类的子目录，这些子目录包含了与 MVC 模式对应的源码。 -你可以使用目录路径或[路径别名](concept-aliases.md)去配置 [[yii\base\Application::basePath|basePath]]。这两种形式配置时，对应的目录都必须存在，否则会抛出异常。路径将会通过 -调用 `realpath()` 函数实现标准化。 +[[yii\base\Application::basePath|basePath]] 指定该应用的根目录。根目录包含应用系统所有受保护的源代码。 +在根目录下可以看到对应MVC设计模式的`models`, `views`, `controllers`等子目录。 -[[yii\base\Application::basePath|basePath]] 通常用来派生出其它重要路径（例如 runtime 路径）。鉴于此，路径别名 `@app` 被预定义指向这个路径。这样前面所说的派生出的路径就可以使用这个别名来访问（例如 `@app/runtime` 指向 bashPath 下的 runtime 目录）。 +可以使用路径或 [路径别名](concept-aliases.md) 来在配置 [[yii\base\Application::basePath|basePath]] 属性。 +两种格式所对应的目录都必须存在，否则系统会抛出一个异常。 系统会使用 `realpath()` 函数规范化配置的路径. + +[[yii\base\Application::basePath|basePath]] 属性经常用于派生一些其他重要路径（如runtime路径），因此，系统预定义 `@app` 代表这个路径。 +派生路径可以通过这个别名组成（如`@app/runtime`代表runtime的路径）。 ### 重要属性 -这部分涉及到的属性往往需要被配置，因为它们在不同应用中通常是不同的。 +本小节所描述的属性通常需要设置，因为不用的应用属性不同。 -#### [[yii\base\Application::aliases|别名（aliases）]] +#### [[yii\base\Application::aliases|aliases]] -这个属性让你通过一个数组的形式定义一组[别名](concept-aliases.md)。数组的键是别名的名称，数组的值是对应的路径定义。例如： +该属性允许你用一个数组定义多个 [别名](concept-aliases.md)。数组的key为别名名称，值为对应的路径。例如： ```php [ @@ -69,39 +76,40 @@ $config = require(__DIR__ . '/../config/web.php'); ] ``` -这个属性提供了一种通过调用 [[Yii::setAlias()]] 方法之外的，通过应用配置定义别名的方式。 +使用这个属性来定义别名，代替 [[Yii::setAlias()]] 方法来设置。 -#### [[yii\base\Application::bootstrap|引导（bootstrap）]] +#### [[yii\base\Application::bootstrap|bootstrap]] -这是相当有用的属性。它允许你以数组形式指定一些组件在应用 [[yii\base\Application::bootstrap()|引导过程]]就执行。例如：如果想让一个[模型](structure-modules.md)自定义[ URL 规则](runtime-url-handling.md) 你可以以数组元素的形式列出它的 ID。 +这个属性很实用，它允许你用数组指定启动阶段[[yii\base\Application::bootstrap()|bootstrapping process]]需要运行的组件。 +比如，如果你希望一个 [模块](structure-modules.md) 自定义 [URL 规则](runtime-url-handling.md)，你可以将模块ID加入到bootstrap数组中。 -每个属性中都可以用下述任意格式列出组件： +属性中的每个组件需要指定以下一项: -- 按照[组件](#components)指定的一个应用组件 ID。 -- 按照[模块](#modules)指定的一个模块 ID。 -- 一个类名。 -- 一个配置数组。 -- 一个创建并返回组件的匿名函数。 +- 应用 [组件](#components) ID. +- [模块](#modules) ID. +- 类名. +- 配置数组. +- 创建并返回一个组件的无名称函数. 例如： ```php [ 'bootstrap' => [ - // 一个应用组件 ID 或模块 ID + // 应用组件ID或模块ID 'demo', - // 一个类名 + // 类名 'app\components\Profiler', - // 一个配置数组 + // 配置数组 [ 'class' => 'app\components\Profiler', 'level' => 3, ], - // 一个匿名函数 + // 无名称函数 function () { return new app\components\Profiler(); } @@ -109,8 +117,7 @@ $config = require(__DIR__ . '/../config/web.php'); ] ``` -> 补充：如果一个模块 ID 和应用组件 ID 重复，应用组件 ID 将被用于应用引导过程中执行。如果你想使用模块 ID，可以使用匿名函数返回它： - +> 补充: 如果模块ID和应用组件ID同名，优先使用应用组件ID，如果你想用模块ID，可以使用如下无名称函数返回模块ID。 >```php [ function () { @@ -120,13 +127,15 @@ $config = require(__DIR__ . '/../config/web.php'); ``` -在应用引导过程期间，每个组件都会被实例化。如果组件类实现了 [[yii\base\BootstrapInterface]]，它的 [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] 也将被调用。 +在启动阶段，每个组件都会实例化。如果组件类实现接口 [[yii\base\BootstrapInterface]], +也会调用 [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] 方法。 -另一个例子是[基础应用模版](start-installation.md)中的应用配置，当应用运行在开发环境中时 `debug` 和 `gii` 两个模块将被配制成引导组件： +举一个实际的例子，[Basic Application Template](start-installation.md) 应用主体配置中， +开发环境下会在启动阶段运行 `debug` 和 `gii` 模块。 ```php if (YII_ENV_DEV) { - // 针对 `dev` 环境所做的配置调整 + // configuration adjustments for 'dev' environment $config['bootstrap'][] = 'debug'; $config['modules']['debug'] = 'yii\debug\Module'; @@ -135,14 +144,15 @@ if (YII_ENV_DEV) { } ``` -> 注意：放置太多组件在 `bootstrap` 过程中将会降低应用性能，因为每个请求都要运行相同的一系列组件。所以，请明智地使用引导组件。 +> 注: 启动太多的组件会降低系统性能，因为每次请求都需要重新运行启动组件，因此谨慎配置启动组件。 -#### [[yii\web\Application::catchAll|捕获所有请求（catchAll）]] +#### [[yii\web\Application::catchAll|catchAll]] -这个属性仅支持 [[yii\web\Application|Web 应用]]。它指定了一个处理所有用户请求的[控制器操作](structure-controllers.md)。这主要在应用处于维护模式，或使用单独一个操作响应所有用户请求时使用。 +该属性仅 [[yii\web\Application|Web applications]] 网页应用支持。 +它指定一个要处理所有用户请求的 [控制器方法](structure-controllers.md)，通常在维护模式下使用，同一个方法处理所有用户请求。 -配置项是一个数组，第一个元素指定操作的路由。剩下的数组元素（键值对）指定绑定到操作上的参数。例如： +该配置为一个数组，第一项指定动作的路由，剩下的数组项(key-value 成对)指定传递给动作的参数，例如： ```php [ @@ -155,9 +165,9 @@ if (YII_ENV_DEV) { ``` -#### [[yii\base\Application::components|组件（components）]] +#### [[yii\base\Application::components|components]] -这是最重要的属性。它可以让你注册一组命名的被称为[应用组件](#structure-application-components.md)的组件列表，以便你在应用中使用。例如： +这是最重要的属性，它允许你注册多个在其他地方使用的[应用组件](#structure-application-components.md). 例如 ```php [ @@ -173,16 +183,19 @@ if (YII_ENV_DEV) { ] ``` -每个应用组件都由一个键值对组成的数组指定。键代表组件 ID，值则表示组件类名或[配置](concept-configuration.md)。 +每一个应用组件指定一个key-value对的数组，key代表组件ID，value代表组件类名或 [配置](concept-configurations.md)。 -你可以随着一个应用注册任何组件，组件可以在随后使用表达式 `\Yii->$app->ComponentID` 全局访问。 +在应用中可以任意注册组件，并可以通过表达式 `\Yii::$app->ComponentID` 全局访问。 -请参考[应用组件](structure-application-components.md)章节了解更多信息。 +详情请阅读 [应用组件](structure-application-components.md) 一节. -#### [[yii\base\Application::controllerMap|控制器映射（controllerMap）]] +#### [[yii\base\Application::controllerMap|controllerMap]] -这个属性允许你映射控制器 ID 至任意控制器类。默认情况下，Yii 将控制器 ID 基于[控制器命名约定](#controllerNamespace)进行映射（例如，ID `post` 将被映射到 `app\controllers\PostController`）。通过配置这个属性，你可以针对特定控制器打破这种约定。下述例子中，`account` 将被映射到 `app\controllers\UserController`，而 `article` 将被映射到 `app\controllers\PostController`。 +该属性允许你指定一个控制器ID到任意控制器类。Yii遵循一个默认的 [规则](#controllerNamespace) +指定控制器ID到任意控制器类（如`post`对应`app\controllers\PostController`）。 +通过配置这个属性，可以打破这个默认规则，在下面的例子中，`account`对应到`app\controllers\UserController`， +`article` 对应到 `app\controllers\PostController`。 ```php [ @@ -198,43 +211,48 @@ if (YII_ENV_DEV) { ] ``` -这个属性的数组键名代表控制器 ID，而数组值代表对应的控制器名或[配置](concept-configurations.md)。 +数组的键代表控制器ID，数组的值代表对应的类名。 + +#### [[yii\base\Application::controllerNamespace|controllerNamespace]] -#### [[yii\base\Application::controllerNamespace|控制器命名空间（controllerNamespace）]] +该属性指定控制器类默认的命名空间，默认为`app\controllers`。比如控制器ID为 `post` 默认对应 `PostController` （不带命名空间）， +类全名为 `app\controllers\PostController`。 -这个属性指定了从哪个命名空间下寻找控制器类。默认值为 `app\controllers`。如果一个控制器的 ID 是 `post`，按惯例对应的控制器类名（没有命名空间）将是 `PostController`，完全限定类名将是 `app\controllers\PostController`。 +控制器类文件可能放在这个命名空间对应目录的子目录下， +例如，控制器ID `admin/post` 对应的控制器类全名为 `app\controllers\admin\PostController`。 -控制器类也许会被定位到此命名空间对应目录下的子目录。例如，给定一个控制器类 `admin/post`，对应的控制器完全限定类名将会是 `app\controllers\admin\PostController`。 +控制器类全面能被 [自动加载](concept-autoloading.md)，这点是非常重要的，控制器类的实际命名空间对应这个属性， +否则，访问时你会收到"Page Not Found"[译：页面找不到]。 -控制器的完全限定名能被[自动加载](concept-autoloading.md)并且控制器类实际的命名空间与此属性匹配非常重要。否则你在访问控制器时将会收到 “Page Not Found”错误。 +如果你想打破上述的规则，可以配置 [controllerMap](#controllerMap) 属性。 -如果你想要打破上述约定，可以配置[控制器映射](#controllerMap)属性。 +#### [[yii\base\Application::language|language]] -#### [[yii\base\Application::language|语言（language）]] +该属性指定应用展示给终端用户的语言，默认为 `en` 标识英文。如果需要之前其他语言可以配置该属性。 -这个属性指定了应用应该以何种语言显示给最终用户。默认值是 `en`，即英语。如果你的应用需要支持多种语言，应该配置这个属性。 +该属性影响各种 [国际化](tutorial-i18n.md) ，包括信息翻译、日期格式、数字格式等。 +例如 [[yii\jui\DatePicker]] 小部件会根据该属性展示对应语言的日历以及日期格式。 -这个属性的值确定了[国际化](tutorial-i18n.md)方面的多个内容，包括消息翻译，日期格式，数字格式，等等。例如，小部件 [[yii\jui\DatePicker]] 将使用这个属性的值来确定日历应该显示哪种语言以及日期使用哪种格式。 +推荐遵循 [IETF language tag](http://en.wikipedia.org/wiki/IETF_language_tag) 来设置语言，例如 `en` 代表英文， `en-US` 代表英文(美国). -建议你根据 [IETF 语言标签](http://en.wikipedia.org/wiki/IETF_language_tag)去指定语言。例如，`en` 代表英语，而 `en-US` 代表英语（美国）。 +该属性的更多信息可参考 [国际化](tutorial-i18n.md) 一节. -更多关于该属性的细节请查看[国际化](tutorial-i18n.md)章节。 -#### [[yii\base\Application::modules|模块（modules)]] +#### [[yii\base\Application::modules|modules]] -这个属性指定了应用中包含的[模块](structure-modules.md)。 +该属性指定应用所包含的 [模块](structure-modules.md)。 -这个属性接受一个模块类或[配置](concept-configurations.md)的数组，数组键名作为模块 ID。例如： +该属性使用数组包含多个模块类 [配置](concept-configurations.md)，数组的键为模块ID，例： ```php [ 'modules' => [ - // 通过模块类指定一个 “booking” 模块 + // "booking" 模块以及对应的类 'booking' => 'app\modules\booking\BookingModule', - // 通过配置数组指定一个 “comment” 模块 + // "comment" 模块以及对应的配置数组 'comment' => [ 'class' => 'app\modules\comment\CommentModule', 'db' => 'db', @@ -243,19 +261,21 @@ if (YII_ENV_DEV) { ] ``` -请参考[模块](structure-modules.md)章节了解详情。 +更多详情请参考 [模块](structure-modules.md) 一节。 -#### [[yii\base\Application::name|名称（name）]] +#### [[yii\base\Application::name|name]] -这个属性指定了可能显示给最终用户的应用名称。和 [[yii\base\Application::id|id]] 只能接受唯一值不同，这个属性主要用作显示目的，所以不必唯一。 +该属性指定你可能想展示给终端用户的应用名称，不同于需要唯一性的 [[yii\base\Application::id|id]] 属性， +该属性可以不唯一，该属性用于显示应用的用途。 -如果你的代码没有使用它就不必配置。 +如果其他地方的代码没有用到，可以不配置该属性。 -#### [[yii\base\Application::params|参数（params）]] +#### [[yii\base\Application::params|params]] -这个属性指定了一个全局可访问的应用参数。可以代替在应用中四处硬编码数字和字符，在一处定义参数，并在其它地方按需使用是良好的实践。例如，你可能会以参数形式定义缩略图尺寸： +该属性为一个数组，指定可以全局访问的参数，代替程序中硬编码的数字和字符，应用中的参数定义到一个单独的文件并随时可以访问是一个好习惯。 +例如用参数定义缩略图的长宽如下： ```php [ @@ -265,28 +285,30 @@ if (YII_ENV_DEV) { ] ``` -然后在你的代码中需要用到这些值的地方，可以简单的使用它们： +然后简单的使用如下代码即可获取到你需要的长宽参数： ```php $size = \Yii::$app->params['thumbnail.size']; $width = \Yii::$app->params['thumbnail.size'][0]; ``` -今后如果你决定更改缩略图尺寸，只需在应用配置中修改它即可，无需改动任何依赖的代码。 +以后想修改缩略图长宽，只需要修改该参数而不需要相关的代码。 -#### [[yii\base\Application::sourceLanguage|源码语言（sourceLanguage）]] +#### [[yii\base\Application::sourceLanguage|sourceLanguage]] -这个属性指定了应用代码以何种语言写就。默认值是 `en-US`，即英语（美国）。如果代码中的文字内容不是英语你就该配置它。 +该属性指定应用代码的语言，默认为 `'en-US'` 标识英文（美国），如果应用不是英文请修改该属性。 -正如[语言（language）](#language)属性一样，你应该根据 [IETF 语言标签](http://en.wikipedia.org/wiki/IETF_language_tag)去指定语言。例如，`en` 代表英语，而 `en-US` 代表英语（美国）。 +和 [语言](#language) 属性类似，配置该属性需遵循 [IETF language tag](http://en.wikipedia.org/wiki/IETF_language_tag). +例如 `en` 代表英文， `en-US` 代表英文(美国)。 -更多关于此属性的细节请查看[国际化](tutorial-i18n.md)章节。 +该属性的更多信息可参考 [国际化](tutorial-i18n.md) 一节. -#### [[yii\base\Application::timeZone|时区（timeZone）]] +#### [[yii\base\Application::timeZone|timeZone]] -这个属性提供了一个设置 PHP 运行时默认时区的可选方法。配置这个属性，本质上就是调用 PHP 函数 [date_default_timezone_set()](http://php.net/manual/en/function.date-default-timezone-set.php)。例如： +该属性提供一种方式修改PHP运行环境中的默认时区，配置该属性本质上就是调用PHP函数 +[date_default_timezone_set()](http://php.net/manual/en/function.date-default-timezone-set.php)，例如： ```php [ @@ -295,35 +317,41 @@ $width = \Yii::$app->params['thumbnail.size'][0]; ``` -#### [[yii\base\Application::version|版本（version）]] +#### [[yii\base\Application::version|version]] -这个属性指定了应用的版本。默认为 `'1.0'`。如果代码中没有用到它就不需要配置。 +该属性指定应用的版本，默认为`'1.0'`，其他代码不使用的话可以不配置。 -### 有用属性 +### 实用属性 -这部分提到的属性并不常用，因为它们的默认配置比较符合通用约定。如果想打破这种约定，仍然可以配置它们。 +本小节描述的属性不经常设置，通常使用系统默认值。如果你想改变默认值，可以配置这些属性。 -#### [[yii\base\Application::charset|编码（charset）]] +#### [[yii\base\Application::charset|charset]] -这个属性定义了应用使用的编码。默认值是 `utf-8`，除非你要整合遗留系统的非 Unicode 数据，否则应该保留默认值。 +该属性指定应用使用的字符集，默认值为 `'UTF-8'`，绝大部分应用都在使用，除非已有的系统大量使用非unicode数据才需要更改该属性。 -#### [[yii\base\Application::defaultRoute|默认路由（defaultRoute）]] +#### [[yii\base\Application::defaultRoute|defaultRoute]] -这个属性指定了当一个请求没有指定路由时应用默认使用的[路由](runtime-routing.md)。 路由可能由模块 ID，控制器 ID，操作 ID组成。例如，`help`，`post/create`，`admin/post/create`。如果没有给定操作 ID，它将使用 [[yii\base\Controller::defaultAction]] 指定的值作为默认值。 +该属性指定未配置的请求的响应 [路由](runtime-routing.md) 规则，路由规则可能包含模块ID，控制器ID，动作ID。 +例如`help`, `post/create`, `admin/post/create`，如果动作ID没有指定，会使用[[yii\base\Controller::defaultAction]]中指定的默认值。 -对于 [[yii\web\Application|Web 应用]]，这个属性的默认值是 `'site'`，即 `SiteController` 控制器和它默认操作将被使用。因此，当你访问应用而不指定任何路由时，它将显示 `app\controllers\SiteController::actionIndex()` 的执行结果。 +对于 [[yii\web\Application|Web applications]] 网页应用，默认值为 `'site'` 对应 `SiteController` 控制器，并使用默认的动作。 +因此你不带路由的访问应用，默认会显示 `app\controllers\SiteController::actionIndex()` 的结果。 -对于 [[yii\console\Application|控制台应用]]，这个属性的默认值是 `'help'`，即核心命令 [[yii\console\controllers\HelpController::actionIndex()]] 将被使用。因此，当你执行 `yii` 命令而不提供任何参数时，它将显示帮助信息。 +对于 [[yii\console\Application|console applications]] 控制台应用， +默认值为 `'help'` 对应 [[yii\console\controllers\HelpController::actionIndex()]]。 +因此，如果执行的命令不带参数，默认会显示帮助信息。 -#### [[yii\base\Application::extensions|扩展（extension）]] +#### [[yii\base\Application::extensions|extensions]] -这个属性指定了已被应用安装和使用的[扩展](structure-extensions.md)列表。默认情况下，它接受的是从文件 `@vendor/yiisoft/extension.php` 返回的数组。 `extension.php` 文件是当你使用 [Composer](http://getcomposer.org) 安装扩展时自动生成和维护的。所以多数情况下，无需配置这个属性。 +该属性用数组列表指定应用安装和使用的 [扩展](structure-extensions.md)，默认使用`@vendor/yiisoft/extensions.php`文件返回的数组。 +当你使用 [Composer](http://getcomposer.org) 安装扩展，`extensions.php` 会被自动生成和维护更新。 +所以大多数情况下，不需要配置该属性。 -特殊情况下你也许想要手动维护扩展，可以配置这个属性： +特殊情况下你想自己手动维护扩展，可以参照如下配置该属性： ```php [ @@ -331,67 +359,74 @@ $width = \Yii::$app->params['thumbnail.size'][0]; [ 'name' => 'extension name', 'version' => 'version number', - 'bootstrap' => 'BootstrapClassName', // 可选项，也可以是一个配置数组 - 'alias' => [ // optional + 'bootstrap' => 'BootstrapClassName', // 可选配，可为配置数组 + 'alias' => [ // 可选配 '@alias1' => 'to/path1', '@alias2' => 'to/path2', ], ], - // ... 和上面格式一样的更多扩展 ... + // ... 更多像上面的扩展 ... ], ] ``` -如你所见，该属性接受一个包含扩展说明的数组。每个扩展由包含 `name` 和 `version` 元素的数组指定。如果一个扩展需要在[引导](runtime-bootstrapping.md)过程中执行，还可以指定一个 `bootstrap` 元素，其值可以是引导类名或[配置](concept-configurations.md)数组。一个扩展同样可以定义[别名](concept-aliases.md)。 +如上所示，该属性包含一个扩展定义数组，每个扩展为一个包含 `name` 和 `version` 项的数组。 +如果扩展要在 [引导启动](runtime-bootstrapping.md) 阶段运行，需要配置 `bootstrap`以及对应的引导启动类名或 [configuration](concept-configurations.md) 数组。 +扩展也可以定义 [别名](concept-aliases.md) -#### [[yii\base\Application::layout|布局（layout）]] +#### [[yii\base\Application::layout|layout]] -这个属性指定了渲染[视图](structure-views.md)时的默认布局文件名。默认值为 `'main'`，意思是[布局路径](#layoutPath)下的 `main.php` 文件会被使用。如果[布局路径](#layoutPath)和[视图路径](#viewPath)都使用默认值，则默认布局文件可以用别名`@app/views/layouts/main.php`表示。 +该属性指定渲染 [视图](structure-views.md) 默认使用的布局名字，默认值为 `'main'` 对应[布局路径](#layoutPath)下的 `main.php` 文件， +如果 [布局路径](#layoutPath) 和 [视图路径](#viewPath) 都是默认值，默认布局文件可以使用路径别名`@app/views/layouts/main.php` -尽管这很不常用，但你可以通过配置此属性为 `false` 去禁用默认布局。 +如果不想设置默认布局文件，可以设置该属性为 `false`，这种做法比较罕见。 -#### [[yii\base\Application::layoutPath|布局路径（layoutPath)]] +#### [[yii\base\Application::layoutPath|layoutPath]] -这个属性指定了布局文件的寻找路径。默认值为[视图路径](#viewPath)下的 `layouts` 子目录。如果[视图路径](#viewPath)使用的是默认值，则默认布局路径可以用别名 `@app/views/layouts` 表示。 +该属性指定查找布局文件的路径，默认值为 [视图路径](#viewPath) 下的 `layouts` 子目录。 +如果 [视图路径](#viewPath) 使用默认值，默认的布局路径别名为`@app/views/layouts`。 -你可以使用目录地址或路径[别名](concept-aliases.md)配置本属性。 +该属性需要配置成一个目录或 路径 [别名](concept-aliases.md)。 +You may configure it as a directory or a path [alias](concept-aliases.md). -#### [[yii\base\Application::runtimePath|运行时路径（runtimePath）]] +#### [[yii\base\Application::runtimePath|runtimePath]] -这个属性指定了临时文件生成的路径，如日志文件，缓存文件。属性默认值被表示为 `@app/runtime`。 +该属性指定临时文件如日志文件、缓存文件等保存路径，默认值为带别名的 `@app/runtime`。 -你可以使用目录地址或路径[别名](concept-aliases.md)配置它。请注意，运行时路径必须有执行应用进程的写入权限。并且应该保证终端用户没有访问权限，因为路径中的临时文件可能包含敏感信息。 +可以配置该属性为一个目录或者路径 [别名](concept-aliases.md)，注意应用运行时有对该路径的写入权限， +以及终端用户不能访问改路径因为临时文件可能包含一些敏感信息。 -为了简化此路径访问，Yii 为此路径预定义了一个别名 `@runtime`。 +为了简化访问该路径，Yii预定义别名 `@runtime` 代表该路径。 -#### [[yii\base\Application::viewPath|视图路径（viewPath）]] +#### [[yii\base\Application::viewPath|viewPath]] -这个属性指定了视图文件存储的根目录。默认值是别名 `@app/views` 代表的目录。你可以用目录地址或路径[别名](concept-aliases.md)配置它。 +该路径指定视图文件的根目录，默认值为带别名的 `@app/views`，可以配置它为一个目录或者路径 [别名](concept-aliases.md). -#### [[yii\base\Application::vendorPath|供应商目录（vendorPath）]] +#### [[yii\base\Application::vendorPath|vendorPath]] -这个属性指定了 [Composer](http://getcomposer.org) 负责维护的供应商目录。它包含了应用运行需要的所有第三方库，包括 Yii 框架核心。默认值是别名 `@app/vendor` 代表的目录。 +该属性指定 [Composer](http://getcomposer.org) 管理的供应商路径，该路径包含应用使用的包括Yii框架在内的所有第三方库。 +默认值为带别名的 `@app/vendor` 。 -你可以用目录地址或路径[别名](concept-aliases.md)配置它。如果你修改了此属性默认值，请确保你同样相应调整了 Composer 配置。 +可以配置它为一个目录或者路径 [别名](concept-aliases.md)，当你修改时，务必修改对应的 Composer 配置。 -为了简化此路径访问，Yii 为此路径预定义了一个别名 `@vendor`。 +为了简化访问该路径，Yii预定义别名 `@vendor` 代表该路径。 #### [[yii\console\Application::enableCoreCommands|enableCoreCommands]] -这个属性只被[[yii\console\Application|控制台应用]]所支持。它定义了 Yii 发行包中所包含的核心命令是否可以使用。默认值为 `true`。 +该属性仅 [[yii\console\Application|console applications]] 控制台应用支持， 用来指定是否启用Yii中的核心命令，默认值为 `true`。 ## 应用事件 -一个应用在处理请求的生命周期中会触发几个事件。你可以在应用配置中附加对应的事件处理器给这些事件： +应用在处理请求过程中会触发事件，可以在配置文件配置事件处理代码，如下所示： ```php [ @@ -401,9 +436,9 @@ $width = \Yii::$app->params['thumbnail.size'][0]; ] ``` -`on eventName` 的使用语法在[配置](concept-configuration.md#configuration-format)章节有所描述。 +`on eventName` 语法的用法在 [Configurations](concept-configurations.md#configuration-format) 一节有详细描述. -另一种方式，你可以在应用实例化后的[引导过程](runtime-bootstrapping.md)附加事件处理器。例如： +另外，在应用主体实例化后，你可以在[引导启动](runtime-bootstrapping.md) 阶段附加事件处理代码，例如： ```php \Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) { @@ -413,30 +448,32 @@ $width = \Yii::$app->params['thumbnail.size'][0]; ### [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_REQUEST]] -这个事件将在应用处理一个请求**之前**被触发。真实的事件名是 `beforeRequest`。 +该事件在应用处理请求*before*之前，实际的事件名为 `beforeRequest`。 -当此事件被触发时，应用实例已经被配置并初始化。所以这是个绝佳位置去通过事件机制插入自定义代码截获请求处理过程。例如，在事件处理器中，你可以基于某些参数动态设置应用的[[yii\base\Application::（语言）language]]。 +在事件触发前，应用主体已经实例化并配置好了，所以通过事件机制将你的代码嵌入到请求处理过程中非常不错。 +例如在事件处理中根据某些参数动态设置[[yii\base\Application::language]]语言属性。 ### [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_AFTER_REQUEST]] -这个事件将在应用处理完成一个请求**之后**并且在发送响应内容**之前**被触发。真实的事件名是 `afterRequest`。 +该事件在应用处理请求*after*之后但在返回响应*before*之前触发，实际的事件名为`afterRequest`。 -当此事件被触发时，请求处理过程已经完成，并且你可能借此机会对请求做一些后期加工或自定义响应内容。 +该事件触发时，请求已经被处理完，可以做一些请求后处理或自定义响应。 -请注意[[yii\web\Response|响应（response）]]组件同样可以在向用户发送响应内容时触发事件。那些事件将在此事件**之后**被触发。 +注意 [[yii\web\Response|response]] 组件在发送响应给终端用户时也会触发一些事件，这些事件都在本事件*after*之后触发。 ### [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_ACTION]] -这个事件将在每个[控制器操作](structure-controllers.md)运行**之前**被触发。真实的事件名是 `beforeAction`。 +该事件在每个 [控制器动作](structure-controllers.md) 运行*before*之前会被触发，实际的事件名为 `beforeAction`. -事件参数是一个 [[yii\base\ActionEvent]] 类的实例。一个事件处理器可以设置 [[yii\base\ActionEvent::isValid]] 属性为 `false` 去阻止操作执行。例如： +事件的参数为一个 [[yii\base\ActionEvent]] 实例， +事件处理中可以设置[[yii\base\ActionEvent::isValid]] 为 `false` 停止运行后续动作，例如： ```php [ 'on beforeAction' => function ($event) { - if (一些条件) { + if (some condition) { $event->isValid = false; } else { } @@ -444,19 +481,22 @@ $width = \Yii::$app->params['thumbnail.size'][0]; ] ``` -请注意 `beforeAction` 事件同样能被[模块](structure-modules.md)和[控制器](structure-controllers.md)触发。应用对象第一个触发此事件，紧接着是模块（如果有），最后是控制器。如果一个事件处理器设置了 [[yii\base\ActionEvent::isVaild]] 为 `false`，所有其后的事件都将**不被**触发。 +注意 [模块](structure-modules.md) 和 [控制器](structure-controllers.md) 都会触发 `beforeAction` 事件。 +应用主体对象首先触发该事件，然后模块触发（如果存在模块），最后控制器触发。 +任何一个事件处理中设置 [[yii\base\ActionEvent::isValid]] 设置为 `false` 会停止触发后面的事件。 ### [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_AFTER_ACTION]] -这个事件将在每个[控制器操作](structure-controllers.md)运行**之后**被触发。真实的事件名是 `afterAction`。 +该事件在每个 [控制器动作](structure-controllers.md) 运行*after*之后会被触发，实际的事件名为 `afterAction`. -事件参数是一个 [[yii\base\ActionEvent]] 类的实例。通过 [[yii\base\ActionEvent::result]] 属性，一个事件处理器可以访问或修改操作返回的结果。例如： +该事件的参数为 [[yii\base\ActionEvent]] 实例，通过[[yii\base\ActionEvent::result]]属性， +事件处理可以访问和修改动作的结果。例如： ```php [ 'on afterAction' => function ($event) { - if (一些条件) { + if (some condition) { // 修改 $event->result } else { } @@ -464,22 +504,23 @@ $width = \Yii::$app->params['thumbnail.size'][0]; ] ``` -请注意 `afterAction` 事件同样能被[模块](structure-modules.md)和[控制器](structure-controllers.md)触发。那些对象以与 `beforeAction` 相反的顺序触发这个事件。也就是控制器第一个触发此事件，紧接着是模块（如果有），最后是应用对象。 +注意 [模块](structure-modules.md) 和 [控制器](structure-controllers.md) 都会触发 `afterAction` 事件。 +这些对象的触发顺序和 `beforeAction` 相反，也就是说，控制器最先触发，然后是模块（如果有模块），最后为应用主体。 -## 应用生命周期 +## 应用主体生命周期 -当[入口脚本](structure-entry-scripts.md)被执行来处理一个请求，应用对象将历经以下生命周期： +当运行 [入口脚本](structure-entry-scripts.md) 处理请求时，应用主体会经历以下生命周期: -1. 入口脚本以数组形式加载应用配置。 -2. 入口脚本创建一个新的应用实例： - * [[yii\base\Application::preInit()|preInit()]] 被调用，用来配置一些高优先级的应用属性，例如[[yii\base\Application::basePath|（基本路径）]]。 - * 注册[[yii\base\Application::errorHandler|错误处理器]]。 - * 配置应用属性。 - * [[yii\base\Application::init()|init()]] 被调用后进而调用 [[yii\base\Application::bootstrap()|bootstrap()]] 执行组件引导。 -3. 入口脚本调用 [[yii\base\Application::run()]] 执行应用： +1. 入口脚本加载应用主体配置数组。 +2. 入口脚本创建一个应用主体实例： + * 调用 [[yii\base\Application::preInit()|preInit()]] 配置几个高级别应用主体属性，比如[[yii\base\Application::basePath|basePath]]。 + * 注册 [[yii\base\Application::errorHandler|error handler]] 错误处理方法. + * 配置应用主体属性. + * 调用 [[yii\base\Application::init()|init()]] 初始化，该函数会调用 [[yii\base\Application::bootstrap()|bootstrap()]] 运行引导启动组件. +3. 入口脚本调用 [[yii\base\Application::run()]] 运行应用主体: * 触发 [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_REQUEST]] 事件。 - * 处理请求：解析请求至[路由](runtime-routing.md)和相关参数；依照路由指定创建模型，控制器和操作对象；执行操作。 + * 处理请求：解析请求 [路由](runtime-routing.md) 和相关参数；创建路由指定的模块、控制器和动作对应的类，并运行动作。 * 触发 [[yii\base\Application::EVENT_AFTER_REQUEST|EVENT_AFTER_REQUEST]] 事件。 - * 发送响应内容给用户。 -4. 入口脚本从应用接受退出状态并且完成请求过程。 + * 发送响应到终端用户. +4. 入口脚本接收应用主体传来的退出状态并完成请求的处理。 diff --git a/docs/guide-zh-CN/structure-entry-scripts.md b/docs/guide-zh-CN/structure-entry-scripts.md index a5c785a..2992ccd 100644 --- a/docs/guide-zh-CN/structure-entry-scripts.md +++ b/docs/guide-zh-CN/structure-entry-scripts.md @@ -101,4 +101,4 @@ if (!defined('YII_DEBUG')) { 显然第一段代码更加简洁易懂。 -常量定义应该在入口脚本的开头，这样包含其他 PHP 文件时，常量就能生效。 +常量定义应该在入口脚本的开头，这样包含其他 PHP 文件时，常量就能生效。 \ No newline at end of file