diff --git a/docs/guide-zh-CN/README.md b/docs/guide-zh-CN/README.md index 9d2f4e7..31ae463 100644 --- a/docs/guide-zh-CN/README.md +++ b/docs/guide-zh-CN/README.md @@ -38,7 +38,7 @@ Yii 2.0 权威指南 * **已定稿** [过滤器](structure-filters.md) * **已定稿** [小部件(Widget)](structure-widgets.md) * **已定稿** [模块(Module)](structure-modules.md) -* **编撰中** [前端资源(Asset)](structure-assets.md) +* **已定稿** [前端资源(Asset)](structure-assets.md) * **已定稿** [扩展(extensions)](structure-extensions.md) 请求处理 @@ -46,13 +46,12 @@ Yii 2.0 权威指南 * **已定稿** [运行概述](runtime-overview.md) * **已定稿** [引导(Bootstrapping)](runtime-bootstrapping.md) -* **已定稿** [路由(Routing)](runtime-routing.md) +* **已定稿** [路由(Route)引导与创建 URL](runtime-routing.md) * **已定稿** [请求(Request)](runtime-requests.md) * **已定稿** [响应(Response)](runtime-responses.md) * **已定稿** [Sessions(会话)和 Cookies](runtime-sessions-cookies.md) -* **编撰中** [URL 解析和生成](runtime-url-handling.md) -* **编撰中** [错误处理](runtime-handling-errors.md) -* **编撰中** [日志](runtime-logging.md) +* **已定稿** [错误处理](runtime-handling-errors.md) +* **已定稿** [日志](runtime-logging.md) 关键概念 -------- @@ -90,7 +89,7 @@ Yii 2.0 权威指南 显示数据 -------- -* **待定中** [格式化输出数据](output-formatter.md) +* **编撰中** [格式化输出数据](output-formatter.md) * **待定中** [分页(Pagination)](output-pagination.md) * **待定中** [排序(Sorting)](output-sorting.md) * **编撰中** [数据提供器](output-data-providers.md) diff --git a/docs/guide-zh-CN/caching-fragment.md b/docs/guide-zh-CN/caching-fragment.md index c379b90..d8dd970 100644 --- a/docs/guide-zh-CN/caching-fragment.md +++ b/docs/guide-zh-CN/caching-fragment.md @@ -114,7 +114,7 @@ if ($this->beginCache($id1)) { 可以为嵌套的缓存设置不同的配置项。例如,内层缓存和外层缓存使用不同的过期时间。甚至当外层缓存的数据过期失效了,内层缓存仍然可能提供有效的片段缓存数据。但是,反之则不然。如果外层片段缓存没有过期而被视为有效,此时即使内层片段缓存已经失效,它也将继续提供同样的缓存副本。因此,你必须谨慎处理缓存嵌套中的过期时间和依赖,否则外层的片段很有可能返回的是不符合你预期的失效数据。 -> 译者注:外层的失效时间应该短于内层,外层的依赖条件应该低于内层,以确保最小的片段,返回的是最新的数据。 +> 译注:外层的失效时间应该短于内层,外层的依赖条件应该低于内层,以确保最小的片段,返回的是最新的数据。 ## 动态内容 <a name="dynamic-content"></a> diff --git a/docs/guide-zh-CN/concept-autoloading.md b/docs/guide-zh-CN/concept-autoloading.md index ee6ca92..0fe7684 100644 --- a/docs/guide-zh-CN/concept-autoloading.md +++ b/docs/guide-zh-CN/concept-autoloading.md @@ -15,7 +15,7 @@ Yii 依靠[类自动加载机制](http://www.php.net/manual/en/language.oop5.aut * 每个类都必须保存为单独文件,且其完整路径能用以下算法取得: ```php -// $className 是一个开头包含反斜杠的完整类名(译者注:请自行谷歌:fully qualified class name) +// $className 是一个开头包含反斜杠的完整类名(译注:请自行谷歌:fully qualified class name) $classFile = Yii::getAlias('@' . str_replace('\\', '/', $className) . '.php'); ``` diff --git a/docs/guide-zh-CN/concept-behaviors.md b/docs/guide-zh-CN/concept-behaviors.md index aad7739..833aa68 100644 --- a/docs/guide-zh-CN/concept-behaviors.md +++ b/docs/guide-zh-CN/concept-behaviors.md @@ -267,7 +267,7 @@ class User extends ActiveRecord 保存 `User` 对象,将会发现它的 `created_at` 和 `updated_at` 属性自动填充了当前时间戳: -``php +```php $user = new User; $user->email = 'test@example.com'; $user->save(); diff --git a/docs/guide-zh-CN/concept-events.md b/docs/guide-zh-CN/concept-events.md index 07ae569..1824fbd 100644 --- a/docs/guide-zh-CN/concept-events.md +++ b/docs/guide-zh-CN/concept-events.md @@ -65,7 +65,7 @@ $foo->on(Foo::EVENT_HELLO, function ($event) { ``` -时间处理器顺序 +事件处理器顺序 ----------------- 可以附加一个或多个处理器到一个事件。当事件被触发,已附加的处理器将按附加次序依次调用。如果某个处理器需要停止其后的处理器调用,可以设置 `$event` 参数的 [yii\base\Event::handled]] 属性为真,如下: @@ -78,7 +78,7 @@ $foo->on(Foo::EVENT_HELLO, function ($event) { 默认新附加的事件处理器排在已存在处理器队列的最后。因此,这个处理器将在事件被触发时最后一个调用。在处理器队列最前面插入新处理器将使该处理器最先调用,可以传递第四个参数 `$append` 为假并调用 [[yii\base\Component::on()]] 方法实现: -``php +```php $foo->on(Foo::EVENT_HELLO, function ($event) { // 这个处理器将被插入到处理器队列的第一位... }, $data, false); @@ -238,4 +238,4 @@ Yii::$app->trigger('bar', new Event(['sender' => new Foo])); 全局事件的一个好处是当附加处理器到一个对象要触发的事件时,不需要产生该对象。相反,处理器附加和事件触发都通过单例(如应用实例)完成。 -然而,因为全局事件的命名空间由各方共享,应合理命名全局事件,如引入一些命名空间(例:"frontend.mail.sent", "backend.mail.sent")。 \ No newline at end of file +然而,因为全局事件的命名空间由各方共享,应合理命名全局事件,如引入一些命名空间(例:"frontend.mail.sent", "backend.mail.sent")。 diff --git a/docs/guide-zh-CN/db-active-record.md b/docs/guide-zh-CN/db-active-record.md index 3012c41..18ff81b 100644 --- a/docs/guide-zh-CN/db-active-record.md +++ b/docs/guide-zh-CN/db-active-record.md @@ -166,7 +166,7 @@ $sql = 'SELECT * FROM customer'; $customers = Customer::findBySql($sql)->all(); ``` -> 小技巧:在上面的代码中,`Customer::STATUS_ACTIVE` 是一个在 `Customer` 类里定义的常量。(译者注:这种常量的值一般都是tinyint)相较于直接在代码中写死字符串或数字,使用一个更有意义的常量名称是一种更好的编程习惯。 +> 小技巧:在上面的代码中,`Customer::STATUS_ACTIVE` 是一个在 `Customer` 类里定义的常量。(译注:这种常量的值一般都是tinyint)相较于直接在代码中写死字符串或数字,使用一个更有意义的常量名称是一种更好的编程习惯。 有两个快捷方法:`findOne` 和 `findAll()` 用来返回一个或者一组`ActiveRecord`实例。前者返回第一个匹配到的实例,后者返回所有。 例如: @@ -847,7 +847,7 @@ public static function find() } ``` -注意,你之后所有的查询都不能用 [[yii\db\ActiveQuery::where()|where()]],但是可以用 [[yii\db\ActiveQuery::andWhere()|andWhere()]] 和 [[yii\db\ActiveQuery::orWhere()|orWhere()]],他们不会覆盖掉默认作用域。(译者注:如果你要使用默认作用域,就不能在 xxx::find()后使用where()方法,你必须使用andXXX()或者orXXX()系的方法,否则默认作用域不会起效果,至于原因,打开where()方法的代码一看便知) +注意,你之后所有的查询都不能用 [[yii\db\ActiveQuery::where()|where()]],但是可以用 [[yii\db\ActiveQuery::andWhere()|andWhere()]] 和 [[yii\db\ActiveQuery::orWhere()|orWhere()]],他们不会覆盖掉默认作用域。(译注:如果你要使用默认作用域,就不能在 xxx::find()后使用where()方法,你必须使用andXXX()或者orXXX()系的方法,否则默认作用域不会起效果,至于原因,打开where()方法的代码一看便知) 事务操作 @@ -894,7 +894,7 @@ class ProductController extends \yii\web\Controller } } ``` -(译者注:我觉得上面应该是原手册里的bug) +(译注:我觉得上面应该是原手册里的bug) 在控制器层使用事务: diff --git a/docs/guide-zh-CN/runtime-bootstrapping.md b/docs/guide-zh-CN/runtime-bootstrapping.md index 3829658..8c2e318 100644 --- a/docs/guide-zh-CN/runtime-bootstrapping.md +++ b/docs/guide-zh-CN/runtime-bootstrapping.md @@ -24,7 +24,7 @@ Composer 自动加载器,以及通过 `Yii` 类加载的 Yii 自动加载器� 因为引导工作必须在处理**每一次**请求之前都进行一遍,因此让该过程尽可能轻量化就异常重要,请尽可能地优化这一步骤。 请尽量不要注册太多引导组件。只有他需要在 HTTP 请求处理的全部生命周期中都作用时才需要使用它。举一个用到它的范例:一个模块需要注册额外的 URL 解析规则,就应该把它列在应用的 -[bootstrap 属性](structure-applications.md#bootstrap)之中,这样该 URL 解析规则才能在解析请求之前生效。(译者注:换言之,为了性能需要,除了 URL +[bootstrap 属性](structure-applications.md#bootstrap)之中,这样该 URL 解析规则才能在解析请求之前生效。(译注:换言之,为了性能需要,除了 URL 解析等少量操作之外,绝大多数组件都应该按需加载,而不是都放在引导过程中。) 在生产环境中,可以开启字节码缓存,比如 APC,来进一步最小化加载和解析 PHP 文件所需的时间。 diff --git a/docs/guide-zh-CN/runtime-handling-errors.md b/docs/guide-zh-CN/runtime-handling-errors.md new file mode 100644 index 0000000..1cb5af7 --- /dev/null +++ b/docs/guide-zh-CN/runtime-handling-errors.md @@ -0,0 +1,204 @@ +错误处理 +=============== + +Yii 内置了一个[[yii\web\ErrorHandler|error handler]]错误处理器,它使错误处理更方便, +Yii错误处理器做以下工作来提升错误处理效果: + +* 所有非致命PHP错误(如,警告,提示)会转换成可获取异常; +* 异常和致命的PHP错误会被显示,在调试模式会显示详细的函数调用栈和源代码行数。 +* 支持使用专用的 [控制器操作](structure-actions.md) 来显示错误; +* 支持不同的错误响应格式; + +[[yii\web\ErrorHandler|error handler]] 错误处理器默认启用, +可通过在应用的[入口脚本](structure-entry-scripts.md)中定义常量`YII_ENABLE_ERROR_HANDLER`来禁用。 + + +## 使用错误处理器 <a name="using-error-handler"></a> + +[[yii\web\ErrorHandler|error handler]] 注册成一个名称为`errorHandler`[应用组件](structure-application-components.md), +可以在应用配置中配置它类似如下: + +```php +return [ + 'components' => [ + 'errorHandler' => [ + 'maxSourceLines' => 20, + ], + ], +]; +``` + +使用如上代码,异常页面最多显示20条源代码。 + +如前所述,错误处理器将所有非致命PHP错误转换成可获取异常,也就是说可以使用如下代码处理PHP错误: + +```php +use Yii; +use yii\base\ErrorException; + +try { + 10/0; +} catch (ErrorException $e) { + Yii::warning("Division by zero."); +} + +// execution continues... +``` + +如果你想显示一个错误页面告诉用户请求是无效的或无法处理的,可简单地抛出一个 [[yii\web\HttpException|HTTP exception]]异常, +如 [[yii\web\NotFoundHttpException]]。错误处理器会正确地设置响应的HTTP状态码并使用合适的错误视图页面来显示错误信息。 + +```php +use yii\web\NotFoundHttpException; + +throw new NotFoundHttpException(); +``` + + +## 自定义错误显示 <a name="customizing-error-display"></a> + +[[yii\web\ErrorHandler|error handler]]错误处理器根据常量`YII_DEBUG`的值来调整错误显示, +当`YII_DEBUG` 为 true (表示在调试模式),错误处理器会显示异常以及详细的函数调用栈和源代码行数来帮助调试, +当`YII_DEBUG` 为 false,只有错误信息会被显示以防止应用的敏感信息泄漏。 + +> 补充: 如果异常是继承 [[yii\base\UserException]],不管`YII_DEBUG`为何值,函数调用栈信息都不会显示, +这是因为这种错误会被认为是用户产生的错误,开发人员不需要去修正。 + +[[yii\web\ErrorHandler|error handler]] 错误处理器默认使用两个[视图](structure-views.md)显示错误: + +* `@yii/views/errorHandler/error.php`: 显示不包含函数调用栈信息的错误信息是使用, + 当`YII_DEBUG` 为 false时,所有错误都使用该视图。 +* `@yii/views/errorHandler/exception.php`: 显示包含函数调用栈信息的错误信息时使用。 + +可以配置错误处理器的 [[yii\web\ErrorHandler::errorView|errorView]] 和 [[yii\web\ErrorHandler::exceptionView|exceptionView]] 属性 +使用自定义的错误显示视图。 + + +### 使用错误操作 <a name="using-error-actions"></a> + +使用指定的错误[操作](structure-controllers.md) 来自定义错误显示更方便, +为此,首先配置`errorHandler`组件的 [[yii\web\ErrorHandler::errorAction|errorAction]] 属性,类似如下: + +```php +return [ + 'components' => [ + 'errorHandler' => [ + 'errorAction' => 'site/error', + ], + ] +]; +``` + +[[yii\web\ErrorHandler::errorAction|errorAction]] 属性使用[路由](structure-controllers.md#routes)到一个操作, +上述配置表示不用显示函数调用栈信息的错误会通过执行`site/error`操作来显示。 + +可以创建`site/error` 操作如下所示: + +```php +namespace app\controllers; + +use Yii; +use yii\web\Controller; + +class SiteController extends Controller +{ + public function actions() + { + return [ + 'error' => [ + 'class' => 'yii\web\ErrorAction', + ], + ]; + } +} +``` + +上述代码定义`error` 操作使用[[yii\web\ErrorAction]] 类,该类渲染名为`error`视图来显示错误。 + +除了使用[[yii\web\ErrorAction]], 可定义`error` 操作使用类似如下的操作方法: + +```php +public function actionError() +{ + $exception = Yii::$app->errorHandler->exception; + if ($exception !== null) { + return $this->render('error', ['exception' => $exception]); + } +} +``` + +现在应创建一个视图文件为`views/site/error.php`,在该视图文件中,如果错误操作定义为[[yii\web\ErrorAction]], +可以访问该操作中定义的如下变量: + +* `name`: 错误名称 +* `message`: 错误信息 +* `exception`: 更多详细信息的异常对象,如HTTP 状态码,错误码,错误调用栈等。 + +> 补充: 如果你使用 [基础应用模板](start-installation.md) 或 [高级应用模板](tutorial-advanced-app.md), +错误操作和错误视图已经定义好了。 + + +### 自定义错误格式 <a name="error-format"></a> + +错误处理器根据[响应](runtime-responses.md)设置的格式来显示错误, +如果[[yii\web\Response::format|response format]] 响应格式为`html`, 会使用错误或异常视图来显示错误信息,如上一小节所述。 +对于其他的响应格式,错误处理器会错误信息作为数组赋值给[[yii\web\Response::data]]属性,然后转换到对应的格式, +例如,如果响应格式为`json`,可以看到如下响应信息: + +``` +HTTP/1.1 404 Not Found +Date: Sun, 02 Mar 2014 05:31:43 GMT +Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y +Transfer-Encoding: chunked +Content-Type: application/json; charset=UTF-8 + +{ + "name": "Not Found Exception", + "message": "The requested resource was not found.", + "code": 0, + "status": 404 +} +``` + +可在应用配置中响应`response`组件的`beforeSend`事件来自定义错误响应格式。 + +```php +return [ + // ... + 'components' => [ + 'response' => [ + 'class' => 'yii\web\Response', + 'on beforeSend' => function ($event) { + $response = $event->sender; + if ($response->data !== null) { + $response->data = [ + 'success' => $response->isSuccessful, + 'data' => $response->data, + ]; + $response->statusCode = 200; + } + }, + ], + ], +]; +``` + +上述代码会重新格式化错误响应,类似如下: + +``` +HTTP/1.1 200 OK +Date: Sun, 02 Mar 2014 05:31:43 GMT +Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y +Transfer-Encoding: chunked +Content-Type: application/json; charset=UTF-8 + +{ + "success": false, + "data": { + "name": "Not Found Exception", + "message": "The requested resource was not found.", + "code": 0, + "status": 404 + } +} +``` diff --git a/docs/guide-zh-CN/runtime-routing.md b/docs/guide-zh-CN/runtime-routing.md index eeb8db3..949e781 100644 --- a/docs/guide-zh-CN/runtime-routing.md +++ b/docs/guide-zh-CN/runtime-routing.md @@ -2,40 +2,27 @@ ======= 当[入口脚本](structure-entry-scripts.md)在调用 [[yii\web\Application::run()|run()]] -方法时,它进行的第一个操作就是解析输入的请求,然后实例化对应的[控制器操作](structure-controllers.md)处理这个请求。该过程就被称为**引导路由(routing)**。(译者注:中文里既是动词也是名词) +方法时,它进行的第一个操作就是解析输入的请求,然后实例化对应的[控制器操作](structure-controllers.md)处理这个请求。该过程就被称为**引导路由(routing)**。(译注:中文里既是动词也是名词) ## 解析路由 <a name="resolving-route"></a> -引导路由第一步,是解析输入请求为一个路由。如 [控制器(Controllers)](structure-controllers.md#routes) -所描述的那样,路由是一个用于定位控制器操作的地址。这个过程通过 `request` 应用组件的 [[yii\web\Request::resolve()|resolve()]] +路由引导的第一步,是把传入请求解析为一个路由。如我们在 [控制器(Controllers)](structure-controllers.md#routes) +章节中所描述的那样,路由是一个用于定位控制器操作的地址。这个过程通过 `request` 应用组件的 [[yii\web\Request::resolve()|resolve()]] 方法实现,该方法会调用 [URL 管理器](runtime-url-handling.md) 进行实质上的请求解析工作。 -The first step of routing is to parse the incoming request into a route which, as described in -the [Controllers](structure-controllers.md#routes) section, is used to address a controller action. -This is done by [[yii\web\Request::resolve()|resolve()]] method of the `request` application component. -The method invokes the [URL manager](runtime-url-handling.md) to do the actual request parsing work. - -默认情况下,输入请求会包含一个名为 `r` 的 `GET` 参数,它的值即被视为路由。但是如果启用 -[[yii\web\UrlManager::enablePrettyUrl|pretty URL feature]],确定请求路由时则会进行更多处理。具体的细节请参考 +默认情况下,传入请求会包含一个名为 `r` 的 `GET` 参数,它的值即被视为路由。但是如果启用 +[[yii\web\UrlManager::enablePrettyUrl|美化 URL 功能]],那么在确定请求的路由时,就会进行更多处理。具体的细节请参考 [URL 的解析与生成](runtime-url-handling.md) 章节。 -By default, if the incoming request contains a `GET` parameter named `r`, its value will be considered -as the route. However, if the [[yii\web\UrlManager::enablePrettyUrl|pretty URL feature]] is enabled, -more work will be done to determine the requested route. For more details, please refer to -the [URL Parsing and Generation](runtime-url-handling.md) section. - -若好死不死地路由最终无法被确定,那么 `request` 组件会抛出 [[yii\web\NotFoundHttpException]] 异常(译者注:大名鼎鼎的 404)。 - -In case a route cannot be determined, the `request` component will throw a [[yii\web\NotFoundHttpException]]. +假使某路由最终实在无法被确定,那么 `request` 组件会抛出 [[yii\web\NotFoundHttpException]] 异常(译注:大名鼎鼎的 404)。 -### 默认路由 <a name="default-route"></a> +### 缺省路由 <a name="default-route"></a> -If an incoming request does not specify a route, which often happens to the request for homepages, -the route specified by [[yii\web\Application::defaultRoute]] will be used. The default value of this property -is `site/index`, which refers to the `index` action of the `site` controller. You may customize this property -in the application configuration like the following: +如果传入请求并没有提供一个具体的路由,(一般这种情况多为于对首页的请求)此时就会启用由 +[[yii\web\Application::defaultRoute]] 属性所指定的缺省路由。该属性的默认值为 `site/index`,它指向 `site` 控制器的 `index` +操作。你可以像这样在应用配置中调整该属性的值: ```php return [ @@ -47,9 +34,9 @@ return [ ### `catchAll` 路由(全拦截路由) <a name="catchall-route"></a> -Sometimes, you may want to put your Web application in maintenance mode temporarily and display the same -informational page for all requests. There are many ways to accomplish this goal. But one of the simplest -ways is to configure the [[yii\web\Application::catchAll]] property like the following in the application configuration: +有时候,你会想要将你的 Web +应用临时调整到维护模式,所有的请求下都会显示相同的信息页。当然,要实现这一点有很多种方法。这里面最简单快捷的方法就是在应用配置中设置下 +[[yii\web\Application::catchAll]] 属性: ```php return [ @@ -58,35 +45,25 @@ return [ ]; ``` -The `catchAll` property should take an array whose first element specifies a route, and -the rest of the elements (name-value pairs) specify the parameters to be bound to the action. +`catchAll` 属性需要传入一个数组做参数,该数组的第一个元素为路由,剩下的元素会(以名值对的形式)指定绑定于该操作的各个参数。 -When the `catchAll` property is set, it will replace any route resolved from the incoming requests. -With the above configuration, the same `site/offline` action will be used to handle all incoming requests. +当设置了 `catchAll` 属性时,它会替换掉所有从输入的请求中解析出来的路由。如果是上文的这种设置,用于处理所有传入请求的操作都会是相同的 `site/offline`。 -## 创建一个操作 <a name="creating-action"></a> +## 创建操作 <a name="creating-action"></a> -Once the requested route is determined, the next step is to create the action object corresponding to the route. +一旦请求路由被确定了,紧接着的步骤就是创建一个“操作(action)”对象,用以响应该路由。 -The route is broken down into multiple parts by the slashes in it. For example, `site/index` will be -broken into `site` and `index`. Each part is an ID which may refer to a module, a controller or an action. +路由可以用里面的斜杠分割成多个组成片段,举个栗子,`site/index` 可以分解为 `site` 和 `index` +两部分。每个片段都是指向某一模块(Module)、控制器(Controller)或操作(action)的 ID。 -Starting from the first part in the route, the application conducts the following steps to create modules (if any), -the controller and the action: +从路由的首个片段开始,应用会经过以下流程依次创建模块(如果有),控制器,以及操作: -1. Set the application as the current module. -2. Check if the [[yii\base\Module::controllerMap|controller map]] of the current module contains the current ID. - If so, a controller object will be created according to the controller configuration found in the map, - and do Step 5 with the rest parts of the route. -3. Check if the ID refers to a module listed in the [[yii\base\Module::modules|modules]] property of - the current module. If so, a module is created according to the configuration found in the module list, - and do Step 2 with the next part in the route under the context of the newly created module. -4. Treat the ID as a controller ID and create a controller object. Do the next step with the rest part of - the route. -5. The controller looks for the current ID in its [[yii\base\Controller::actions()|action map]]. If found, - it creates an action according to the configuration found in the map. Otherwise, the controller will - attempt to create an inline action which is defined by an action method corresponding to the current ID. +1. 设置应用主体为当前模块。 +2. 检查当前模块的 [[yii\base\Module::controllerMap|controller map(控制器映射表)]] 是否包含当前 ID。如果是,会根据该表中的配置创建一个控制器对象,然后跳到步骤五执行该路由的后续片段。 +3. 检查该 ID 是否指向当前模块中 [[yii\base\Module::modules|modules]] 属性里的模块列表中的一个模块。如果是,会根据该模块表中的配置创建一个模块对象,然后会以新创建的模块为环境,跳回步骤二解析下一段路由。 +4. 将该 ID 视为控制器 ID,并创建控制器对象。用下个步骤解析路由里剩下的片段。 +5. 控制器会在他的 [[yii\base\Controller::actions()|action map(操作映射表)]]里搜索当前 ID。如果找得到,它会根据该映射表中的配置创建一个操作对象;反之,控制器则会尝试创建一个与该 ID + 相对应,由某个 action 方法所定义的行内操作(inline action)。 -Among the above steps, if any error occurs, a [[yii\web\NotFoundHttpException]] will be thrown, indicating -failure of the routing. +在上面的步骤里,如果有任何错误发生,都会抛出 [[yii\web\NotFoundHttpException]],指出路由引导的过程失败了。 \ No newline at end of file diff --git a/docs/guide-zh-CN/start-forms.md b/docs/guide-zh-CN/start-forms.md index a459ec8..26b7509 100644 --- a/docs/guide-zh-CN/start-forms.md +++ b/docs/guide-zh-CN/start-forms.md @@ -41,7 +41,7 @@ class EntryForm extends Model 该类继承自Yii 提供的一个基类 [[yii\base\Model]],该基类通常用来表示数据。 -> 补充:[[yii\base\Model]] 被用于普通模型类的父类并与数据表**无关**。[[yii\db\ActiveRecord]] 通常是普通模型类的父类但与数据表有关联(译者注:[[yii\db\ActiveRecord]] 类其实也是继承自 [[yii\base\Model]],增加了数据库处理)。 +> 补充:[[yii\base\Model]] 被用于普通模型类的父类并与数据表**无关**。[[yii\db\ActiveRecord]] 通常是普通模型类的父类但与数据表有关联(译注:[[yii\db\ActiveRecord]] 类其实也是继承自 [[yii\base\Model]],增加了数据库处理)。 `EntryForm` 类包含 `name` 和 `email` 两个公共成员,用来储存用户输入的数据。它还包含一个名为 `rules()` 的方法,用来返回数据验证规则的集合。上面声明的验证规则表示: diff --git a/docs/guide-zh-CN/start-installation.md b/docs/guide-zh-CN/start-installation.md index c05e34e..acc0895 100644 --- a/docs/guide-zh-CN/start-installation.md +++ b/docs/guide-zh-CN/start-installation.md @@ -30,7 +30,7 @@ Composer 安装后,切换到一个可通过 Web 访问的目录,执行如下 > 注意:在安装过程中 Composer 可能会询问你 GitHub 账户的登录信息,因为可能在使用中超过了 GitHub API (对匿名用户的)使用限制。因为 Composer 需要为所有扩展包从 GitHub -中获取大量信息,所以超限非常正常。(译者注:也意味着作为程序猿没有 GitHub 账号,就真不能愉快地玩耍了)登陆 GitHub +中获取大量信息,所以超限非常正常。(译注:也意味着作为程序猿没有 GitHub 账号,就真不能愉快地玩耍了)登陆 GitHub 之后可以得到更高的 API 限额,这样 Composer 才能正常运行。更多细节请参考 [Composer 文档](https://getcomposer.org/doc/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens)(该段 Composer 中文文档[期待您的参与](https://github.com/5-say/composer-doc-cn/blob/master/cn-introduction/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens))。 @@ -117,7 +117,7 @@ http://localhost/basic/web/index.php DocumentRoot "path/to/basic/web" <Directory "path/to/basic/web"> - # 开启 mod_rewrite 用于美化 URL 功能的支持(译者注:对应 pretty URL 选项) + # 开启 mod_rewrite 用于美化 URL 功能的支持(译注:对应 pretty URL 选项) RewriteEngine on # 如果请求的是真实存在的文件或目录,直接访问 RewriteCond %{REQUEST_FILENAME} !-f diff --git a/docs/guide-zh-CN/structure-assets.md b/docs/guide-zh-CN/structure-assets.md new file mode 100644 index 0000000..e3018ee --- /dev/null +++ b/docs/guide-zh-CN/structure-assets.md @@ -0,0 +1,528 @@ +资源 +====== + +Yii中的资源是和Web页面相关的文件,可为CSS文件,JavaScript文件,图片或视频等, +资源放在Web可访问的目录下,直接被Web服务器调用。 + +通过程序自动管理资源更好一点,例如,当你在页面中使用 [[yii\jui\DatePicker]] 小部件时, +它会自动包含需要的CSS和JavaScript文件,而不是要求你手工去找到这些文件并包含, +当你升级小部件时,它会自动使用新版本的资源文件,在本教程中,我们会详述Yii提供的强大的资源管理功能。 + + +## 资源包 <a name="asset-bundles"></a> + +Yii在*资源包*中管理资源,资源包简单的说就是放在一个目录下的资源集合, +当在[视图](structure-views.md)中注册一个资源包,在渲染Web页面时会包含包中的CSS和JavaScript文件。 + + +## 定义资源包 <a name="defining-asset-bundles"></a> + +资源包指定为继承[[yii\web\AssetBundle]]的PHP类,包名为可[自动加载](concept-autoloading.md)的PHP类名, +在资源包类中,要指定资源所在位置,包含哪些CSS和JavaScript文件以及和其他包的依赖关系。 + +如下代码定义[基础应用模板](start-installation.md)使用的主要资源包: + +```php +<?php + +namespace app\assets; + +use yii\web\AssetBundle; + +class AppAsset extends AssetBundle +{ + public $basePath = '@webroot'; + public $baseUrl = '@web'; + public $css = [ + 'css/site.css', + ]; + public $js = [ + ]; + public $depends = [ + 'yii\web\YiiAsset', + 'yii\bootstrap\BootstrapAsset', + ]; +} +``` + +如上`AppAsset` 类指定资源文件放在 `@webroot` 目录下,对应的URL为 +`@web`,资源包中包含一个CSS文件 `css/site.css`,没有JavaScript文件, +依赖其他两个包 [[yii\web\YiiAsset]] 和 [[yii\bootstrap\BootstrapAsset]], +关于[[yii\web\AssetBundle]] 的属性的更多详细如下所述: + +* [[yii\web\AssetBundle::sourcePath|sourcePath]]: 指定包包含资源文件的根目录, + 当根目录不能被Web访问时该属性应设置,否则,应设置 + [[yii\web\AssetBundle::basePath|basePath]] 属性和[[yii\web\AssetBundle::baseUrl|baseUrl]]。 + [路径别名](concept-aliases.md) 可在此处使用; +* [[yii\web\AssetBundle::basePath|basePath]]: 指定包含资源包中资源文件并可Web访问的目录, + 当指定[[yii\web\AssetBundle::sourcePath|sourcePath]] 属性, + [资源管理器](#asset-manager) 会发布包的资源到一个可Web访问并覆盖该属性, + 如果你的资源文件在一个Web可访问目录下,应设置该属性,这样就不用再发布了。 + [路径别名](concept-aliases.md) 可在此处使用。 +* [[yii\web\AssetBundle::baseUrl|baseUrl]]: 指定对应到[[yii\web\AssetBundle::basePath|basePath]]目录的URL, + 和 [[yii\web\AssetBundle::basePath|basePath]] 类似,如果你指定 [[yii\web\AssetBundle::sourcePath|sourcePath]] 属性, + [资源管理器](#asset-manager) 会发布这些资源并覆盖该属性,[路径别名](concept-aliases.md) 可在此处使用。 +* [[yii\web\AssetBundle::js|js]]: 一个包含该资源包JavaScript文件的数组,注意正斜杠"/"应作为目录分隔符, + 每个JavaScript文件可指定为以下两种格式之一: + - 相对路径表示为本地JavaScript文件 (如 `js/main.js`),文件实际的路径在该相对路径前加上 + [[yii\web\AssetManager::basePath]],文件实际的URL在该路径前加上[[yii\web\AssetManager::baseUrl]]。 + - 绝对URL地址表示为外部JavaScript文件,如 + `http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js` 或 + `//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js`. +* [[yii\web\AssetBundle::css|css]]: 一个包含该资源包JavaScript文件的数组,该数组格式和 [[yii\web\AssetBundle::js|js]] 相同。 +* [[yii\web\AssetBundle::depends|depends]]: 一个列出该资源包依赖的其他资源包(后两节有详细介绍)。 +* [[yii\web\AssetBundle::jsOptions|jsOptions]]: 当调用[[yii\web\View::registerJsFile()]]注册该包 *每个* JavaScript文件时, + 指定传递到该方法的选项。 +* [[yii\web\AssetBundle::cssOptions|cssOptions]]: 当调用[[yii\web\View::registerCssFile()]]注册该包 *每个* css文件时, + 指定传递到该方法的选项。 +* [[yii\web\AssetBundle::publishOptions|publishOptions]]: 当调用[[yii\web\AssetManager::publish()]]发布该包资源文件到Web目录时 + 指定传递到该方法的选项,仅在指定了[[yii\web\AssetBundle::sourcePath|sourcePath]]属性时使用。 + + +### 资源位置 <a name="asset-locations"></a> + +资源根据它们的位置可以分为: + +* 源资源: 资源文件和PHP源代码放在一起,不能被Web直接访问,为了使用这些源资源,它们要拷贝到一个可Web访问的Web目录中 + 成为发布的资源,这个过程称为*发布资源*,随后会详细介绍。 +* 发布资源: 资源文件放在可通过Web直接访问的Web目录中; +* 外部资源: 资源文件放在你的Web应用不同的Web服务器上; + +当定义资源包类时候,如果你指定了[[yii\web\AssetBundle::sourcePath|sourcePath]] 属性,就表示任何使用相对路径的资源会被 +当作源资源;如果没有指定该属性,就表示这些资源为发布资源(因此应指定[[yii\web\AssetBundle::basePath|basePath]] 和 +[[yii\web\AssetBundle::baseUrl|baseUrl]] 让Yii知道它们的位置)。 + +推荐将资源文件放到Web目录以避免不必要的发布资源过程,这就是之前的例子指定 +[[yii\web\AssetBundle::basePath|basePath]] 而不是 [[yii\web\AssetBundle::sourcePath|sourcePath]]. + +对于 [扩展](structure-extensions.md)来说,由于它们的资源和源代码都在不能Web访问的目录下, +在定义资源包类时必须指定[[yii\web\AssetBundle::sourcePath|sourcePath]]属性。 + +> 注意: [[yii\web\AssetBundle::sourcePath|source path]] 属性不要用`@webroot/assets`,该路径默认为 + [[yii\web\AssetManager|asset manager]]资源管理器将源资源发布后存储资源的路径,该路径的所有内容会认为是临时文件, + 可能会被删除。 + + +### 资源依赖 <a name="asset-dependencies"></a> + +当Web页面包含多个CSS或JavaScript文件时,它们有一定的先后顺序以避免属性覆盖, +例如,Web页面在使用jQuery UI小部件前必须确保jQuery JavaScript文件已经被包含了, +我们称这种资源先后次序称为资源依赖。 + +资源依赖主要通过[[yii\web\AssetBundle::depends]] 属性来指定, +在`AppAsset` 示例中,资源包依赖其他两个资源包: [[yii\web\YiiAsset]] 和 [[yii\bootstrap\BootstrapAsset]] +也就是该资源包的CSS和JavaScript文件要在这两个依赖包的文件包含 *之后* 才包含。 + +资源依赖关系是可传递,也就是人说A依赖B,B依赖C,那么A也依赖C。 + + +### 资源选项 <a name="asset-options"></a> + +可指定[[yii\web\AssetBundle::cssOptions|cssOptions]] 和 [[yii\web\AssetBundle::jsOptions|jsOptions]] +属性来自定义页面包含CSS和JavaScript文件的方式, +这些属性值会分别传递给 [[yii\web\View::registerCssFile()]] 和 [[yii\web\View::registerJsFile()]] 方法, +在[视图](structure-views.md) 调用这些方法包含CSS和JavaScript文件时。 + +> 注意: 在资源包类中设置的选项会应用到该包中 *每个* CSS/JavaScript 文件,如果想对每个文件使用不同的选项, + 应创建不同的资源包并在每个包中使用一个选项集。 + +例如,只想IE9或更高的浏览器包含一个CSS文件,可以使用如下选项: + +```php +public $cssOptions = ['condition' => 'lte IE9']; +``` + +这会是包中的CSS文件使用以下HTML标签包含进来: + +```html +<!--[if lte IE9]> +<link rel="stylesheet" href="path/to/foo.css"> +<![endif]--> +``` + +为链接标签包含`<noscript>`可使用如下代码: + +```php +public $cssOptions = ['noscript' => true]; +``` + +为使JavaScript文件包含在页面head区域(JavaScript文件默认包含在body的结束处)使用以下选项: + +```php +public $jsOptions = ['position' => \yii\web\View::POS_HEAD]; +``` + + +### Bower 和 NPM 资源 <a name="bower-npm-assets"></a> + +大多数 JavaScript/CSS 包通过[Bower](http://bower.io/) 和/或 [NPM](https://www.npmjs.org/)管理, +如果你的应用或扩展使用这些包,推荐你遵循以下步骤来管理库中的资源: + +1. 修改应用或扩展的 `composer.json` 文件将包列入`require` 中, + 应使用`bower-asset/PackageName` (Bower包) 或 `npm-asset/PackageName` (NPM包)来对应库。 +2. 创建一个资源包类并将你的应用或扩展要使用的JavaScript/CSS 文件列入到类中, + 应设置 [[yii\web\AssetBundle::sourcePath|sourcePath]] 属性为`@bower/PackageName` 或 `@npm/PackageName`, + 因为根据别名Composer会安装Bower或NPM包到对应的目录下。 + +> 注意: 一些包会将它们分布式文件放到一个子目录中,对于这种情况,应指定子目录作为 + [[yii\web\AssetBundle::sourcePath|sourcePath]]属性值,例如,[[yii\web\JqueryAsset]]使用 `@bower/jquery/dist` 而不是 `@bower/jquery`。 + + +## 使用资源包 <a name="using-asset-bundles"></a> + +为使用资源包,在[视图](structure-views.md)中调用[[yii\web\AssetBundle::register()]]方法先注册资源, +例如,在视图模板可使用如下代码注册资源包: + +```php +use app\assets\AppAsset; +AppAsset::register($this); // $this 代表视图对象 +``` + +如果在其他地方注册资源包,应提供视图对象,如在 [小部件](structure-widgets.md) 类中注册资源包, +可以通过 `$this->view` 获取视图对象。 + +当在视图中注册一个资源包时,在背后Yii会注册它所依赖的资源包,如果资源包是放在Web不可访问的目录下,会被发布到可访问的目录, +后续当视图渲染页面时,会生成这些注册包包含的CSS和JavaScript文件对应的`<link>` 和 `<script>` 标签, +这些标签的先后顺序取决于资源包的依赖关系以及在 [[yii\web\AssetBundle::css]]和[[yii\web\AssetBundle::js]] 的列出来的前后顺序。 + + +### 自定义资源包 <a name="customizing-asset-bundles"></a> + +Yii通过名为 `assetManager`的应用组件实现[[yii\web\AssetManager] 来管理应用组件, +通过配置[[yii\web\AssetManager::bundles]] 属性,可以自定义资源包的行为, +例如,[[yii\web\JqueryAsset]] 资源包默认从jquery Bower包中使用`jquery.js` 文件, +为了提高可用性和性能,你可能需要从Google服务器上获取jquery文件,可以在应用配置中配置`assetManager`,如下所示: + +```php +return [ + // ... + 'components' => [ + 'assetManager' => [ + 'bundles' => [ + 'yii\web\JqueryAsset' => [ + 'sourcePath' => null, // 一定不要发布该资源 + 'js' => [ + '//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js', + ] + ], + ], + ], + ], +]; +``` + +可通过类似[[yii\web\AssetManager::bundles]]配置多个资源包,数组的键应为资源包的类名(最开头不要反斜杠), +数组的值为对应的[配置数组](concept-configurations.md). + +> 提示: 可以根据条件判断使用哪个资源,如下示例为如何在开发环境用`jquery.js`,否则用`jquery.min.js`: +> +> ```php +> 'yii\web\JqueryAsset' => [ +> 'js' => [ +> YII_ENV_DEV ? 'jquery.js' : 'jquery.min.js' +> ] +> ], +> ``` + +可以设置资源包的名称对应`false`来禁用想禁用的一个或多个资源包,当视图中注册一个禁用资源包, +视图不会包含任何该包的资源以及不会注册它所依赖的包,例如,为禁用[[yii\web\JqueryAsset]],可以使用如下配置: + +```php +return [ + // ... + 'components' => [ + 'assetManager' => [ + 'bundles' => [ + 'yii\web\JqueryAsset' => false, + ], + ], + ], +]; +``` + +可设置[[yii\web\AssetManager::bundles]]为`false`禁用 *所有* 的资源包。 + + +### 资源部署 <a name="asset-mapping"></a> + +有时你想"修复" 多个资源包中资源文件的错误/不兼容,例如包A使用1.11.1版本的`jquery.min.js`, +包B使用2.1.1版本的`jquery.js`,可自定义每个包来解决这个问题,更好的方式是使用*资源部署*特性来不熟不正确的资源为想要的, +为此,配置[[yii\web\AssetManager::assetMap]]属性,如下所示: + +```php +return [ + // ... + 'components' => [ + 'assetManager' => [ + 'assetMap' => [ + 'jquery.js' => '//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js', + ], + ], + ], +]; +``` + +[[yii\web\AssetManager::assetMap|assetMap]]的键为你想要修复的资源名,值为你想要使用的资源路径, +当视图注册资源包,在[[yii\web\AssetBundle::css|css]] 和 [[yii\web\AssetBundle::js|js]] 数组中每个相关资源文件会和该部署进行对比, +如果数组任何键对比为资源文件的最后文件名(如果有的话前缀为 [[yii\web\AssetBundle::sourcePath]]),对应的值为替换原来的资源。 +例如,资源文件`my/path/to/jquery.js` 匹配键 `jquery.js`. + +> 注意: 只有相对相对路径指定的资源对应到资源部署,替换的资源路径可以为绝对路径,也可为和[[yii\web\AssetManager::basePath]]相关的路径。 + + +### 资源发布 <a name="asset-publishing"></a> + +如前所述,如果资源包放在Web不能访问的目录,当视图注册资源时资源会被拷贝到一个Web可访问的目录中, +这个过程称为*资源发布*,[[yii\web\AssetManager|asset manager]]会自动处理该过程。 + +资源默认会发布到`@webroot/assets`目录,对应的URL为`@web/assets`, +可配置[[yii\web\AssetManager::basePath|basePath]] 和 [[yii\web\AssetManager::baseUrl|baseUrl]] 属性自定义发布位置。 + +除了拷贝文件方式发布资源,如果操作系统和Web服务器允许可以使用符号链接,该功能可以通过设置 +[[yii\web\AssetManager::linkAssets|linkAssets]] 为 true 来启用。 + +```php +return [ + // ... + 'components' => [ + 'assetManager' => [ + 'linkAssets' => true, + ], + ], +]; +``` + +使用以上配置,资源管理器会创建一个符号链接到要发布的资源包源路径,这比拷贝文件方式快并能确保发布的资源一直为最新的。 + + +## 常用资源包 <a name="common-asset-bundles"></a> + +Yii框架定义许多资源包,如下资源包是最常用,可在你的应用或扩展代码中引用它们。 + +- [[yii\web\YiiAsset]]: 主要包含`yii.js` 文件,该文件完成模块JavaScript代码组织功能, + 也为 `data-method` 和 `data-confirm`属性提供特别支持和其他有用的功能。 +- [[yii\web\JqueryAsset]]: 包含从jQuery bower 包的`jquery.js`文件。 +- [[yii\bootstrap\BootstrapAsset]]: 包含从Twitter Bootstrap 框架的CSS文件。 +- [[yii\bootstrap\BootstrapPluginAsset]]: 包含从Twitter Bootstrap 框架的JavaScript 文件来支持Bootstrap JavaScript插件。 +- [[yii\jui\JuiAsset]]: 包含从jQuery UI库的CSS 和 JavaScript 文件。 + +如果你的代码需要jQuery, jQuery UI 或 Bootstrap,应尽量使用这些预定义资源包而非自己创建, +如果这些包的默认配置不能满足你的需求,可以自定义配置,详情参考[自定义资源包](#customizing-asset-bundles)。 + + +## 资源转换 <a name="asset-conversion"></a> + +除了直接编写CSS 和/或 JavaScript代码,开发人员经常使用扩展语法来编写,再使用特殊的工具将它们转换成CSS/Javascript。 +例如,对于CSS代码可使用[LESS](http://lesscss.org/) 或 [SCSS](http://sass-lang.com/), +对于JavaScript 可使用 [TypeScript](http://www.typescriptlang.org/)。 + +可将使用扩展语法的资源文件列到资源包的[[yii\web\AssetBundle::css|css]] 和 [[yii\web\AssetBundle::js|js]]中,如下所示: + +```php +class AppAsset extends AssetBundle +{ + public $basePath = '@webroot'; + public $baseUrl = '@web'; + public $css = [ + 'css/site.less', + ]; + public $js = [ + 'js/site.ts', + ]; + public $depends = [ + 'yii\web\YiiAsset', + 'yii\bootstrap\BootstrapAsset', + ]; +} +``` + +当在视图中注册一个这样的资源包,[[yii\web\AssetManager|asset manager]]资源管理器会自动运行预处理工具将使用扩展语法 +的资源转换成CSS/JavaScript,当视图最终渲染页面时,在页面中包含的是CSS/Javascipt文件,而不是原始的扩展语法代码文件。 + +Yii使用文件扩展名来表示资源使用哪种扩展语法,默认可以识别如下语法和文件扩展名: + +- [LESS](http://lesscss.org/): `.less` +- [SCSS](http://sass-lang.com/): `.scss` +- [Stylus](http://learnboost.github.io/stylus/): `.styl` +- [CoffeeScript](http://coffeescript.org/): `.coffee` +- [TypeScript](http://www.typescriptlang.org/): `.ts` + +Yii依靠安装的预处理公斤来转换资源,例如,为使用[LESS](http://lesscss.org/),应安装`lessc` 预处理命令。 + +可配置[[yii\web\AssetManager::converter]]自定义预处理命令和支持的扩展语法,如下所示: + +```php +return [ + 'components' => [ + 'assetManager' => [ + 'converter' => [ + 'class' => 'yii\web\AssetConverter', + 'commands' => [ + 'less' => ['css', 'lessc {from} {to} --no-color'], + 'ts' => ['js', 'tsc --out {to} {from}'], + ], + ], + ], + ], +]; +``` + +如上所示,通过[[yii\web\AssetConverter::commands]] 属性指定支持的扩展语法, +数组的键为文件扩展名(前面不要.),数组的值为目标资源文件扩展名和执行资源转换的命令, +命令中的标记 `{from}` 和`{to}`会分别被源资源文件路径和目标资源文件路径替代。 + +> 补充: 除了以上方式,也有其他的方式来处理扩展语法资源,例如,可使用编译工具如[grunt](http://gruntjs.com/) + 来监控并自动转换扩展语法资源,此时,应使用资源包中编译后的CSS/Javascript文件而不是原始文件。 + + +## 合并和压缩资源 <a name="combining-compressing-assets"></a> + +一个Web页面可以包含很多CSS 和/或 JavaScript 文件,为减少HTTP 请求和这些下载文件的大小, +通常的方式是在页面中合并并压缩多个CSS/JavaScript 文件为一个或很少的几个文件,并使用压缩后的文件而不是原始文件。 + +> 补充: 合并和压缩资源通常在应用在产品上线模式,在开发模式下使用原始的CSS/JavaScript更方便调试。 + +接下来介绍一种合并和压缩资源文件而不需要修改已有代码的方式: + +1. 找出应用中所有你想要合并和压缩的资源包, +2. 将这些包分成一个或几个组,注意每个包只能属于其中一个组, +3. 合并/压缩每个组里CSS文件到一个文件,同样方式处理JavaScript文件, +4. 为每个组定义新的资源包: + * 设置[[yii\web\AssetBundle::css|css]] 和 [[yii\web\AssetBundle::js|js]] 属性分别为压缩后的CSS和JavaScript文件; + * 自定义设置每个组内的资源包,设置资源包的[[yii\web\AssetBundle::css|css]] 和 [[yii\web\AssetBundle::js|js]] 属性为空, + 并设置它们的 [[yii\web\AssetBundle::depends|depends]] 属性为每个组新创建的资源包。 + +使用这种方式,当在视图中注册资源包时,会自动触发原始包所属的组资源包的注册,然后,页面就会包含以合并/压缩的资源文件, +而不是原始文件。 + + +### 示例 <a name="example"></a> + +使用一个示例来解释以上这种方式: + +鉴定你的应用有两个页面X 和 Y,页面X使用资源包A,B和C,页面Y使用资源包B,C和D。 + +有两种方式划分这些资源包,一种使用一个组包含所有资源包,另一种是将(A,B,C)放在组X,(B,C,C)放在组Y, +哪种方式更好?第一种方式优点是两个页面使用相同的已合并CSS和JavaScript文件使HTTP缓存更高效,另一方面,由于单个组包含所有文件, +已合并的CSS和Javascipt文件会更大,因此会增加文件传输时间,在这个示例中,我们使用第一种方式,也就是用一个组包含所有包。 + +> 补充: 将资源包分组并不是无价值的,通常要求分析现实中不同页面各种资源的数据量,开始时为简便使用一个组。 + +在所有包中使用工具(例如 [Closure Compiler](https://developers.google.com/closure/compiler/), +[YUI Compressor](https://github.com/yui/yuicompressor/)) 来合并和压缩CSS和JavaScript文件, +注意合并后的文件满足包间的先后依赖关系,例如,如果包A依赖B,B依赖C和D,那么资源文件列表以C和D开始,然后为B最后为A。 + +合并和压缩之后,会得到一个CSS文件和一个JavaScript文件,假定它们的名称为`all-xyz.css` 和 `all-xyz.js`, +`xyz` 为使文件名唯一以避免HTTP缓存问题的时间戳或哈希值。 + +现在到最后一步了,在应用配置中配置[[yii\web\AssetManager|asset manager]] 资源管理器如下所示: + +```php +return [ + 'components' => [ + 'assetManager' => [ + 'bundles' => [ + 'all' => [ + 'class' => 'yii\web\AssetBundle', + 'basePath' => '@webroot/assets', + 'baseUrl' => '@web/assets', + 'css' => ['all-xyz.css'], + 'js' => ['all-xyz.js'], + ], + 'A' => ['css' => [], 'js' => [], 'depends' => ['all']], + 'B' => ['css' => [], 'js' => [], 'depends' => ['all']], + 'C' => ['css' => [], 'js' => [], 'depends' => ['all']], + 'D' => ['css' => [], 'js' => [], 'depends' => ['all']], + ], + ], + ], +]; +``` + +如[自定义资源包](#customizing-asset-bundles) 小节中所述,如上配置改变每个包的默认行为, +特别是包A、B、C和D不再包含任何资源文件,都依赖包含合并后的`all-xyz.css` 和 `all-xyz.js`文件的包`all`, +因此,对于页面X会包含这两个合并后的文件而不是包A、B、C的原始文件,对于页面Y也是如此。 + +最后有个方法更好地处理上述方式,除了直接修改应用配置文件,可将自定义包数组放到一个文件,在应用配置中根据条件包含该文件,例如: + +```php +return [ + 'components' => [ + 'assetManager' => [ + 'bundles' => require(__DIR__ . '/' . (YII_ENV_PROD ? 'assets-prod.php' : 'assets-dev.php')), + ], + ], +]; +``` + +如上所示,在产品上线模式下资源包数组存储在`assets-prod.php`文件中,不是产品上线模式存储在`assets-dev.php`文件中。 + + +### 使用 `asset` 命令 <a name="using-asset-command"></a> + +Yii提供一个名为`asset`控制台命令来使上述操作自动处理。 + +为使用该命令,应先创建一个配置文件设置哪些资源包要合并以及分组方式,可使用`asset/template` 子命令来生成一个模板, +然后修改模板成你想要的。 + +``` +yii asset/template assets.php +``` + +该命令在当前目录下生成一个名为`assets.php`的文件,文件的内容类似如下: + +```php +<?php +/** + * 为控制台命令"yii asset"使用的配置文件 + * 注意在控制台环境下,一些路径别名如 '@webroot' 和 '@web' 不会存在 + * 请定义不存在的路径别名 + */ +return [ + // 为JavaScript文件压缩修改 command/callback + 'jsCompressor' => 'java -jar compiler.jar --js {from} --js_output_file {to}', + // 为CSS文件压缩修改command/callback + 'cssCompressor' => 'java -jar yuicompressor.jar --type css {from} -o {to}', + // 要压缩的资源包列表 + 'bundles' => [ + // 'yii\web\YiiAsset', + // 'yii\web\JqueryAsset', + ], + // 资源包压缩后的输出 + 'targets' => [ + 'all' => [ + 'class' => 'yii\web\AssetBundle', + 'basePath' => '@webroot/assets', + 'baseUrl' => '@web/assets', + 'js' => 'js/all-{hash}.js', + 'css' => 'css/all-{hash}.css', + ], + ], + // 资源管理器配置: + 'assetManager' => [ + ], +]; +``` + +应修改该文件的`bundles`的选项指定哪些包你想要合并,在`targets`选项中应指定这些包如何分组,如前述的可以指定一个或多个组。 + +> 注意: 由于在控制台应用别名 `@webroot` and `@web` 不可用,应在配置中明确指定它们。 + +JavaScript文件会被合并压缩后写入到`js/all-{hash}.js`文件,其中 {hash} 会被结果文件的哈希值替换。 + +`jsCompressor` 和 `cssCompressor` 选项指定控制台命令或PHP回调函数来执行JavaScript和CSS合并和压缩, +Yii默认使用[Closure Compiler](https://developers.google.com/closure/compiler/)来合并JavaScript文件, +使用[YUI Compressor](https://github.com/yui/yuicompressor/)来合并CSS文件, +你应手工安装这些工具或修改选项使用你喜欢的工具。 + + +根据配置文件,可执行`asset` 命令来合并和压缩资源文件并生成一个新的资源包配置文件`assets-prod.php`: + +``` +yii asset assets.php config/assets-prod.php +``` + +生成的配置文件可以在应用配置中包含,如最后一小节所描述的。 + + +> 补充: 使用`asset` 命令并不是唯一一种自动合并和压缩过程的方法,可使用优秀的工具[grunt](http://gruntjs.com/)来完成这个过程。 diff --git a/docs/guide-zh-CN/structure-extensions.md b/docs/guide-zh-CN/structure-extensions.md new file mode 100644 index 0000000..b0d472a --- /dev/null +++ b/docs/guide-zh-CN/structure-extensions.md @@ -0,0 +1,435 @@ +Extensions +========== + +Extensions are redistributable software packages specifically designed to be used in Yii applications and provide +ready-to-use features. For example, the [yiisoft/yii2-debug](tool-debugger.md) extension adds a handy debug toolbar +at the bottom of every page in your application to help you more easily grasp how the pages are generated. You can +use extensions to accelerate your development process. You can also package your code as extensions to share with +other people your great work. + +> Info: We use the term "extension" to refer to Yii-specific software packages. For general purpose software packages + that can be used without Yii, we will refer to them using the term "package" or "library". + + +## Using Extensions <a name="using-extensions"></a> + +To use an extension, you need to install it first. Most extensions are distributed as [Composer](https://getcomposer.org/) +packages which can be installed by taking the following two simple steps: + +1. modify the `composer.json` file of your application and specify which extensions (Composer packages) you want to install. +2. run `composer install` to install the specified extensions. + +Note that you may need to install [Composer](https://getcomposer.org/) if you do not have it. + +By default, Composer installs packages registered on [Packagist](https://packagist.org/) - the biggest repository +for open source Composer packages. You can look for extensions on Packagist. You may also +[create your own repository](https://getcomposer.org/doc/05-repositories.md#repository) and configure Composer +to use it. This is useful if you are developing closed open extensions and want to share within your projects. + +Extensions installed by Composer are stored in the `BasePath/vendor` directory, where `BasePath` refers to the +application's [base path](structure-applications.md#basePath). Because Composer is a dependency manager, when +it installs a package, it will also install all its dependent packages. + +For example, to install the `yiisoft/yii2-imagine` extension, modify your `composer.json` like the following: + +```json +{ + // ... + + "require": { + // ... other dependencies + + "yiisoft/yii2-imagine": "*" + } +} +``` + +After the installation, you should see the directory `yiisoft/yii2-imagine` under `BasePath/vendor`. You should +also see another directory `imagine/imagine` which contains the installed dependent package. + +> Info: The `yiisoft/yii2-imagine` is a core extension developed and maintained by the Yii developer team. All + core extensions are hosted on [Packagist](https://packagist.org/) and named like `yiisoft/yii2-xyz`, where `xyz` + varies for different extensions. + +Now you can use the installed extensions like they are part of your application. The following example shows +how you can use the `yii\imagine\Image` class provided by the `yiisoft/yii2-imagine` extension: + +```php +use Yii; +use yii\imagine\Image; + +// generate a thumbnail image +Image::thumbnail('@webroot/img/test-image.jpg', 120, 120) + ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]); +``` + +> Info: Extension classes are autoloaded by the [Yii class autoloader](concept-autoloading.md). + + +### Installing Extensions Manually <a name="installing-extensions-manually"></a> + +In some rare occasions, you may want to install some or all extensions manually, rather than relying on Composer. +To do so, you should + +1. download the extension archive files and unpack them in the `vendor` directory. +2. install the class autoloaders provided by the extensions, if any. +3. download and install all dependent extensions as instructed. + +If an extension does not have a class autoloader but follows the [PSR-4 standard](http://www.php-fig.org/psr/psr-4/), +you may use the class autoloader provided by Yii to autoload the extension classes. All you need to do is just to +declare a [root alias](concept-aliases.md#defining-aliases) for the extension root directory. For example, +assuming you have installed an extension in the directory `vendor/mycompany/myext`, and the extension classes +are under the `myext` namespace, then you can include the following code in your application configuration: + +```php +[ + 'aliases' => [ + '@myext' => '@vendor/mycompany/myext', + ], +] +``` + + +## Creating Extensions <a name="creating-extensions"></a> + +You may consider creating an extension when you feel the need to share with other people your great code. +An extension can contain any code you like, such as a helper class, a widget, a module, etc. + +It is recommended that you create an extension in terms of a [Composer package](https://getcomposer.org/) so that +it can be more easily installed and used by other users, liked described in the last subsection. + +Below are the basic steps you may follow to create an extension as a Composer package. + +1. Create a project for your extension and host it on a VCS repository, such as [github.com](https://github.com). + The development and maintenance work about the extension should be done on this repository. +2. Under the root directory of the project, create a file named `composer.json` as required by Composer. Please + refer to the next subsection for more details. +3. Register your extension with a Composer repository, such as [Packagist](https://packagist.org/), so that + other users can find and install your extension using Composer. + + +### `composer.json` <a name="composer-json"></a> + +Each Composer package must have a `composer.json` file in its root directory. The file contains the metadata about +the package. You may find complete specification about this file in the [Composer Manual](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup). +The following example shows the `composer.json` file for the `yiisoft/yii2-imagine` extension: + +```json +{ + // package name + "name": "yiisoft/yii2-imagine", + + // package type + "type": "yii2-extension", + + "description": "The Imagine integration for the Yii framework", + "keywords": ["yii2", "imagine", "image", "helper"], + "license": "BSD-3-Clause", + "support": { + "issues": "https://github.com/yiisoft/yii2/issues?labels=ext%3Aimagine", + "forum": "http://www.yiiframework.com/forum/", + "wiki": "http://www.yiiframework.com/wiki/", + "irc": "irc://irc.freenode.net/yii", + "source": "https://github.com/yiisoft/yii2" + }, + "authors": [ + { + "name": "Antonio Ramirez", + "email": "amigo.cobos@gmail.com" + } + ], + + // package dependencies + "require": { + "yiisoft/yii2": "*", + "imagine/imagine": "v0.5.0" + }, + + // class autoloading specs + "autoload": { + "psr-4": { + "yii\\imagine\\": "" + } + } +} +``` + + +#### Package Name <a name="package-name"></a> + +Each Composer package should have a package name which uniquely identifies the package among all others. +The format of package names is `vendorName/projectName`. For example, in the package name `yiisoft/yii2-imagine`, +the vendor name and the project name are `yiisoft` and `yii2-imagine`, respectively. + +Do NOT use `yiisoft` as vendor name as it is reserved for use by the Yii core code. + +We recommend you prefix `yii2-` to the project name for packages representing Yii 2 extensions, for example, +`myname/yii2-mywidget`. This will allow users to more easily tell whether a package is a Yii 2 extension. + + +#### Package Type <a name="package-type"></a> + +It is important that you specify the package type of your extension as `yii2-extension` so that the package can +be recognized as a Yii extension when being installed. + +When a user runs `composer install` to install an extension, the file `vendor/yiisoft/extensions.php` +will be automatically updated to include the information about the new extension. From this file, Yii applications +can know which extensions are installed (the information can be accessed via [[yii\base\Application::extensions]]. + + +#### Dependencies <a name="dependencies"></a> + +Your extension depends on Yii (of course). So you should list it (`yiisoft/yii2`) in the `require` entry in `composer.json`. +If your extension also depends on other extensions or third-party libraries, you should list them as well. +Make sure you also list appropriate version constraints (e.g. `1.*`, `@stable`) for each dependent package. Use stable +dependencies when your extension is released in a stable version. + +Most JavaScript/CSS packages are managed using [Bower](http://bower.io/) and/or [NPM](https://www.npmjs.org/), +instead of Composer. Yii uses the [Composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin) +to enable managing these kinds of packages through Composer. If your extension depends on a Bower package, you can +simply list the dependency in `composer.json` like the following: + +```json +{ + // package dependencies + "require": { + "bower-asset/jquery": ">=1.11.*" + } +} +``` + +The above code states that the extension depends on the `jquery` Bower package. In general, you can use +`bower-asset/PackageName` to refer to a Bower package in `composer.json`, and use `npm-asset/PackageName` +to refer to a NPM package. When Composer installs a Bower or NPM package, by default the package content will be +installed under the `@vendor/bower/PackageName` and `@vendor/npm/Packages` directories, respectively. +These two directories can also be referred to using the shorter aliases `@bower/PackageName` and `@npm/PackageName`. + +For more details about asset management, please refer to the [Assets](structure-assets.md#bower-npm-assets) section. + + +#### Class Autoloading <a name="class-autoloading"></a> + +In order for your classes to be autoloaded by the Yii class autoloader or the Composer class autoloader, +you should specify the `autoload` entry in the `composer.json` file, like shown below: + +```json +{ + // .... + + "autoload": { + "psr-4": { + "yii\\imagine\\": "" + } + } +} +``` + +You may list one or multiple root namespaces and their corresponding file paths. + +When the extension is installed in an application, Yii will create for each listed root namespace +an [alias](concept-aliases.md#extension-aliases) that refers to the directory corresponding to the namespace. +For example, the above `autoload` declaration will correspond to an alias named `@yii/imagine`. + + +### Recommended Practices <a name="recommended-practices"></a> + +Because extensions are meant to be used by other people, you often need to take extra development effort. Below +we introduce some common and recommended practices in creating high quality extensions. + + +#### Namespaces <a name="namespaces"></a> + +To avoid name collisions and make the classes in your extension autoloadable, you should use namespaces and +name the classes in your extension by following the [PSR-4 standard](http://www.php-fig.org/psr/psr-4/) or +[PSR-0 standard](http://www.php-fig.org/psr/psr-0/). + +You class namespaces should start with `vendorName\extensionName`, where `extensionName` is similar to the project name +in the package name except that it should not contain the `yii2-` prefix. For example, for the `yiisoft/yii2-imagine` +extension, we use `yii\imagine` as the namespace its classes. + +Do not use `yii`, `yii2` or `yiisoft` as vendor name. These names are reserved for use by the Yii core code. + + +#### Bootstrapping Classes <a name="bootstrapping-classes"></a> + +Sometimes, you may want your extension to execute some code during the [bootstrapping process](runtime-bootstrapping.md) +stage of an application. For example, your extension may want to respond to the application's `beginRequest` event +to adjust some environment settings. While you can instruct users of the extension to explicitly attach your event +handler in the extension to the `beginRequest` event, a better way is to do this automatically. + +To achieve this goal, you can create a so-called *bootstrapping class* by implementing [[yii\base\BootstrapInterface]]. +For example, + +```php +namespace myname\mywidget; + +use yii\base\BootstrapInterface; +use yii\base\Application; + +class MyBootstrapClass implements BootstrapInterface +{ + public function bootstrap($app) + { + $app->on(Application::EVENT_BEFORE_REQUEST, function () { + // do something here + }); + } +} +``` + +You then list this class in the `composer.json` file of your extension like follows, + +```json +{ + // ... + + "extra": { + "bootstrap": "myname\\mywidget\\MyBootstrapClass" + } +} +``` + +When the extension is installed in an application, Yii will automatically instantiate the bootstrapping class +and call its [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] method during the bootstrapping process for +every request. + + +#### Working with Databases <a name="working-with-databases"></a> + +Your extension may need to access databases. Do not assume that the applications that use your extension will always +use `Yii::$db` as the DB connection. Instead, you should declare a `db` property for the classes that require DB access. +The property will allow users of your extension to customize which DB connection they would like your extension to use. +As an example, you may refer to the [[yii\caching\DbCache]] class and see how it declares and uses the `db` property. + +If your extension needs to create specific DB tables or make changes to DB schema, you should + +- provide [migrations](db-migrations.md) to manipulate DB schema, rather than using plain SQL files; +- try to make the migrations applicable to different DBMS; +- avoid using [Active Record](db-active-record.md) in the migrations. + + +#### Using Assets <a name="using-assets"></a> + +If your extension is a widget or a module, chances are that it may require some [assets](structure-assets.md) to work. +For example, a module may display some pages which contain images, JavaScript, and CSS. Because the files of an +extension are all under the same directory which is not Web accessible when installed in an application, you have +two choices to make the asset files directly accessible via Web: + +- ask users of the extension to manually copy the asset files to a specific Web-accessible folder; +- declare an [asset bundle](structure-assets.md) and rely on the asset publishing mechanism to automatically + copy the files listed in the asset bundle to a Web-accessible folder. + +We recommend you use the second approach so that your extension can be more easily used by other people. +Please refer to the [Assets](structure-assets.md) section for more details about how to work with assets in general. + + +#### Internationalization and Localization <a name="i18n-l10n"></a> + +Your extension may be used by applications supporting different languages! Therefore, if your extension displays +content to end users, you should try to [internationalize and localize](tutorial-i18n.md) it. In particular, + +- If the extension displays messages intended for end users, the messages should be wrapped into `Yii::t()` + so that they can be translated. Messages meant for developers (such as internal exception messages) do not need + to be translated. +- If the extension displays numbers, dates, etc., they should be formatted using [[yii\i18n\Formatter]] with + appropriate formatting rules. + +For more details, please refer to the [Internationalization](tutorial-i18n.md) section. + + +#### Testing <a name="testing"></a> + +You want your extension to run flawlessly without bringing problems to other people. To reach this goal, you should +test your extension before releasing it to public. + +It is recommended that you create various test cases to cover your extension code rather than relying on manual tests. +Each time before you release a new version of your extension, you may simply run these test cases to make sure +everything is in good shape. Yii provides testing support, which can help you to more easily write unit tests, +acceptance tests and functionality tests. For more details, please refer to the [Testing](test-overview.md) section. + + +#### Versioning <a name="versioning"></a> + +You should give each release of your extension a version number (e.g. `1.0.1`). We recommend you follow the +[semantic versioning](http://semver.org) practice when determining what version numbers should be used. + + +#### Releasing <a name="releasing"></a> + +To let other people know your extension, you need to release it to public. + +If it is the first time you release an extension, you should register it on a Composer repository, such as +[Packagist](https://packagist.org/). After that, all you need to do is simply creating a release tag (e.g. `v1.0.1`) +on the VCS repository of your extension and notify the Composer repository about the new release. People will +then be able to find the new release, and install or update the extension through the Composer repository. + +In the releases of your extension, besides code files you should also consider including the followings to +help other people learn about and use your extension: + +* A readme file in the package root directory: it describes what your extension does and how to install and use it. + We recommend you write it in [Markdown](http://daringfireball.net/projects/markdown/) format and name the file + as `readme.md`. +* A changelog file in the package root directory: it lists what changes are made in each release. The file + may be written in Markdown format and named as `changelog.md`. +* An upgrade file in the package root directory: it gives the instructions on how to upgrade from older releases + of the extension. The file may be written in Markdown format and named as `upgrade.md`. +* Tutorials, demos, screenshots, etc.: these are needed if your extension provides many features that cannot be + fully covered in the readme file. +* API documentation: your code should be well documented to allow other people more easily read and understand it. + You may refer to the [Object class file](https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php) + to learn how to document your code. + +> Info: Your code comments can be written in Markdown format. The `yiisoft/yii2-apidoc` extension provides a tool + for you to generate pretty API documentation based on your code comments. + +> Info: While not a requirement, we suggest your extension adhere to certain coding styles. You may refer to + the [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style). + + +## Core Extensions <a name="core-extensions"></a> + +Yii provides the following core extensions that are developed and maintained by the Yii developer team. They are all +registered on [Packagist](https://packagist.org/) and can be easily installed as described in the +[Using Extensions](#using-extensions) subsection. + +- [yiisoft/yii2-apidoc](https://github.com/yiisoft/yii2-apidoc): + provides an extensible and high-performance API documentation generator. It is also used to generate the core + framework API documentation. +- [yiisoft/yii2-authclient](https://github.com/yiisoft/yii2-authclient): + provides a set of commonly used auth clients, such as Facebook OAuth2 client, GitHub OAuth2 client. +- [yiisoft/yii2-bootstrap](https://github.com/yiisoft/yii2-bootstrap): + provides a set of widgets that encapsulate the [Bootstrap](http://getbootstrap.com/) components and plugins. +- [yiisoft/yii2-codeception](https://github.com/yiisoft/yii2-codeception): + provides testing support based on [Codeception](http://codeception.com/). +- [yiisoft/yii2-debug](https://github.com/yiisoft/yii2-debug): + provides debugging support for Yii applications. When this extension is used, a debugger toolbar will appear + at the bottom of every page. The extension also provides a set of standalone pages to display more detailed + debug information. +- [yiisoft/yii2-elasticsearch](https://github.com/yiisoft/yii2-elasticsearch): + provides the support for using [Elasticsearch](http://www.elasticsearch.org/). It includes basic querying/search + support and also implements the [Active Record](db-active-record.md) pattern that allows you to store active records + in Elasticsearch. +- [yiisoft/yii2-faker](https://github.com/yiisoft/yii2-faker): + provides the support for using [Faker](https://github.com/fzaninotto/Faker) to generate fake data for you. +- [yiisoft/yii2-gii](https://github.com/yiisoft/yii2-gii): + provides a Web-based code generator that is highly extensible and can be used to quickly generate models, + forms, modules, CRUD, etc. +- [yiisoft/yii2-imagine](https://github.com/yiisoft/yii2-imagine): + provides commonly used image manipulation functions based on [Imagine](http://imagine.readthedocs.org/). +- [yiisoft/yii2-jui](https://github.com/yiisoft/yii2-jui): + provides a set of widgets that encapsulate the [JQuery UI](http://jqueryui.com/) interactions and widgets. +- [yiisoft/yii2-mongodb](https://github.com/yiisoft/yii2-mongodb): + provides the support for using [MongoDB](http://www.mongodb.org/). It includes features such as basic query, + Active Record, migrations, caching, code generation, etc. +- [yiisoft/yii2-redis](https://github.com/yiisoft/yii2-redis): + provides the support for using [redis](http://redis.io/). It includes features such as basic query, + Active Record, caching, etc. +- [yiisoft/yii2-smarty](https://github.com/yiisoft/yii2-smarty): + provides a template engine based on [Smarty](http://www.smarty.net/). +- [yiisoft/yii2-sphinx](https://github.com/yiisoft/yii2-sphinx): + provides the support for using [Sphinx](http://sphinxsearch.com). It includes features such as basic query, + Active Record, code generation, etc. +- [yiisoft/yii2-swiftmailer](https://github.com/yiisoft/yii2-swiftmailer): + provides email sending features based on [swiftmailer](http://swiftmailer.org/). +- [yiisoft/yii2-twig](https://github.com/yiisoft/yii2-twig): + provides a template engine based on [Twig](http://twig.sensiolabs.org/). diff --git a/docs/guide-zh-CN/tutorial-core-validators.md b/docs/guide-zh-CN/tutorial-core-validators.md index 993c8ab..fc20889 100644 --- a/docs/guide-zh-CN/tutorial-core-validators.md +++ b/docs/guide-zh-CN/tutorial-core-validators.md @@ -194,7 +194,7 @@ function foo($model, $attribute) { - `filter`:用于检查输入值存在性必然会进行数据库查询,而该属性为用于进一步筛选该查询的过滤条件。可以为代表额外查询条件的字符串或数组(关于查询条件的格式,请参考 [[yii\db\Query::where()]]);或者样式为 `function ($query)` 的匿名函数,`$query` 参数为你希望在该函数内进行修改的 [[yii\db\Query|Query]] 对象。 - `allowArray`:是否允许输入值为数组。默认为 false。若该属性为 true 且输入值为数组,则数组的每个元素都必须在目标字段中存在。值得注意的是,若用吧 `targetAttribute` 设为多元素数组来验证被测值在多字段中的存在性时,该属性不能设置为 true。 -> 译者注:[exist](#exist) 和 [unique](#unique) 验证器的机理和参数都相似,有点像一体两面的阴和阳。 +> 译注:[exist](#exist) 和 [unique](#unique) 验证器的机理和参数都相似,有点像一体两面的阴和阳。 - 他们的区别是 exist 要求 `targetAttribute` 键所代表的的属性在其值所代表字段中找得到;而 unique 正相反,要求键所代表的的属性不能在其值所代表字段中被找到。 - 从另一个角度来理解:他们都会在验证的过程中执行数据库查询,查询的条件即为where $v=$k (假设 `targetAttribute` 的其中一对键值对为 `$k => $v`)。unique 要求查询的结果数 `$count==0`,而 exist 则要求查询的结果数 `$count>0` - 最后别忘了,unique 验证器不存在 `allowArray` 属性哦。 @@ -423,7 +423,7 @@ function foo($model, $attribute) { - 若键和值相同,你可以只指定值。(如:`['a2']` 就代表 `['a2'=>'a2']`) - `filter`:用于检查输入值唯一性必然会进行数据库查询,而该属性为用于进一步筛选该查询的过滤条件。可以为代表额外查询条件的字符串或数组(关于查询条件的格式,请参考 [[yii\db\Query::where()]]);或者样式为 `function ($query)` 的匿名函数,`$query` 参数为你希望在该函数内进行修改的 [[yii\db\Query|Query]] 对象。 -> 译者注:[exist](#exist) 和 [unique](#unique) 验证器的机理和参数都相似,有点像一体两面的阴和阳。 +> 译注:[exist](#exist) 和 [unique](#unique) 验证器的机理和参数都相似,有点像一体两面的阴和阳。 - 他们的区别是 exist 要求 `targetAttribute` 键所代表的的属性在其值所代表字段中找得到;而 unique 正相反,要求键所代表的的属性不能在其值所代表字段中被找到。 - 从另一个角度来理解:他们都会在验证的过程中执行数据库查询,查询的条件即为where $v=$k (假设 `targetAttribute` 的其中一对键值对为 `$k => $v`)。unique 要求查询的结果数 `$count==0`,而 exist 则要求查询的结果数 `$count>0` - 最后别忘了,unique 验证器不存在 `allowArray` 属性哦。 diff --git a/docs/guide-zh-CN/tutorial-yii-integration.md b/docs/guide-zh-CN/tutorial-yii-integration.md index 0a37eb3..13a3419 100644 --- a/docs/guide-zh-CN/tutorial-yii-integration.md +++ b/docs/guide-zh-CN/tutorial-yii-integration.md @@ -84,7 +84,7 @@ $yiiConfig = require(__DIR__ . '/../config/yii/web.php'); new yii\web\Application($yiiConfig); // 千万别在这调用 run() 方法。(笑) ``` -如你所见,这段代码与典型的 Yii 应用的[入口脚本](structure-entry-scripts.md)非常相似。唯一的不同之处在于在 Yii 应用创建成功之后,并不会紧接着调用 `run()` 方法。因为,`run()` 方法的调用会接管 HTTP 请求的处理流程。(译者注:换言之,这就不是第三方系统而是 Yii 系统了,URL 规则也会跟着换成 Yii 的规则了) +如你所见,这段代码与典型的 Yii 应用的[入口脚本](structure-entry-scripts.md)非常相似。唯一的不同之处在于在 Yii 应用创建成功之后,并不会紧接着调用 `run()` 方法。因为,`run()` 方法的调用会接管 HTTP 请求的处理流程。(译注:换言之,这就不是第三方系统而是 Yii 系统了,URL 规则也会跟着换成 Yii 的规则了) 与 Yii 应用中一样,你可以依据运行该第三方系统的环境,针对性地配置 Yii 应用实例。比如,为了使用[活动记录](db-active-record.md)功能,你需要先用该第三方系统的 DB 连接信息,配置 Yii 的 `db` 应用组件。