Merge branch 'master' of git://github.com/yiisoft/yii2 into start-installation-start-workflow-pt-br

10 years ago · 5c9f412557
2 changed files with 392 additions and 0 deletions
--- a/docs/guide-zh-CN/concept-di-container.md
+++ b/docs/guide-zh-CN/concept-di-container.md
@ -0,0 +1,305 @@
 依赖注入容器
 ==============================
 依赖注入（Dependency Injection，缩写 DI）容器就是一个对象，它知道怎样初始化并配置对象及其依赖的所有对象。
 [Martin 的文章](http://martinfowler.com/articles/injection.html) 已经解释了 DI 容器为什么很有用。这里我们主要讲解 Yii 提供的 DI
 容器的使用方法。
 依赖注入 <a name="dependency-injection"></a>
 --------------------
 Yii 通过 [[yii\di\Container]] 类提供 DI 容器特性。它支持如下几种类型的依赖注入：
 * 构造器注入;
 * Setter 和属性注入;
 * PHP 回调注入.
 ### 构造器注入 <a name="constructor-injection"></a>
 在构造器参数类型提示的帮助下，DI 容器实现了构造器注入。
 当容器被用于创建一个新对象时，类型提示会告诉它要依赖什么类或接口。容器会尝试获取它所依赖的类或接口的实例，然后通过构造器将其注入新的对象。
 例如：
 ```php
 class Foo
 {
    public function __construct(Bar $bar)
    {
    }
 }
 $foo = $container->get('Foo');
 // 上面的代码等价于：
 $bar = new Bar;
 $foo = new Foo($bar);
 ```
 ### Setter 和属性注入 <a name="setter-and-property-injection"></a>
 Setter 和属性注入是通过[配置](concept-configurations.md)提供支持的。当注册一个依赖或创建一个新对象时，你可以提供一个配置，该配置会
 提供给容器用于通过相应的 Setter 或属性注入依赖。例如：
 ```php
 use yii\base\Object;
 class Foo extends Object
 {
    public $bar;
    private $_qux;
    public function getQux()
    {
        return $this->_qux;
    }
    public function setQux(Qux $qux)
    {
        $this->_qux = $qux;
    }
 }
 $container->get('Foo', [], [
    'bar' => $container->get('Bar'),
    'qux' => $container->get('Qux'),
 ]);
 ```
 ### PHP 回调注入 <a name="php-callable-injection"></a>
 这种情况下，容器将使用一个注册过的 PHP 回调构建一个类的新实例。回调负责解决依赖并将其恰当地注入新创建的对象。例如：
 ```php
 $container->set('Foo', function () {
    return new Foo(new Bar);
 });
 $foo = $container->get('Foo');
 ```
 注册依赖关系 <a name="registering-dependencies"></a>
 ------------------------
 你可以用 [[yii\di\Container::set()]] 注册依赖关系。注册会用到一个依赖关系名称和一个依赖关系的定义。依赖关系名称可以是一个类名，一个接
 口名或者一个别名。依赖关系的定义可以是一个类名，一个配置数组，或者一个 PHP 回调。
 ```php
 $container = new \yii\di\Container;
 // 注册一个同类名一样的依赖关系，这个可以省略。
 $container->set('yii\db\Connection');
 // 注册一个接口
 // 当一个类依赖这个接口时，相应的类会被初始化作为依赖对象。
 $container->set('yii\mail\MailInterface', 'yii\swiftmailer\Mailer');
 // 注册一个别名。
 // 你可以使用 $container->get('foo') 创建一个 Connection 实例
 $container->set('foo', 'yii\db\Connection');
 // 通过配置注册一个类
 // 通过 get() 初始化时，配置将会被使用。
 $container->set('yii\db\Connection', [
    'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8',
 ]);
 // 通过类的配置注册一个别名
 // 这种情况下，需要通过一个 “class” 元素指定这个类
 $container->set('db', [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8',
 ]);
 // 注册一个 PHP 回调
 // 每次调用 $container->get('db') 时，回调函数都会被执行。
 $container->set('db', function ($container, $params, $config) {
    return new \yii\db\Connection($config);
 });
 // 注册一个组件实例
 // $container->get('pageCache') 每次被调用时都会返回同一个实例。
 $container->set('pageCache', new FileCache);
 ```
 > Tip: 如果依赖关系名称和依赖关系的定义相同，则不需要通过 DI 容器注册该依赖关系。
 每当依赖关系需要解决时，通过 `set()` 注册的依赖关系都会产生一个新实例。你可以使用 [[yii\di\Container::setSingleton()]] 注册一个依
 赖关系，它只会产生一个单例：
 ```php
 $container->setSingleton('yii\db\Connection', [
    'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8',
 ]);
 ```
 解决依赖关系 <a name="resolving-dependencies"></a>
 ----------------------
 依赖关系注册后，就可以使用 DI 容器创建新对象了。容器会自动解决依赖关系，将它们实例化并注入新创建的对象。依赖关系的解决是递归的，意味着如
 果一个依赖关系中还有其他依赖关系，则这些依赖关系都会被自动解决。
 你可以使用 [[yii\di\Container::get()]] 创建新的对象。该方法接收一个依赖关系名称，它可以是一个类名，一个接口名或一个别名。依赖关系名
 可能是也可能不是通过 `set()` 或 `setSingleton()` 注册的。你可以随意地提供一个类的构造器参数列表和一个
 [configuration](concept-configurations.md) 用于配置新创建的对象。例如：
 ```php
 // "db" 是前面定义过的一个别名
 $db = $container->get('db');
 // 等价于： $engine = new \app\components\SearchEngine($apiKey, ['type' => 1]);
 $engine = $container->get('app\components\SearchEngine', [$apiKey], ['type' => 1]);
 ```
 代码背后，DI 容器做了比仅创建一个新对象还要多的多的工作。容器首先将检查类的构造器，找出依赖的类或接口名，然后自动递归解决这些依赖关系。
 如下代码展示了一个更复杂的示例。`UserLister` 类依赖一个实现了 `UserFinderInterface` 接口的对象；`UserFinder` 类实现了这个接口，并
 依赖于一个 `Connection` 对象。所有这些依赖关系都是通过类构造器参数的类型提示定义的。通过属性依赖关系的注册，DI 容器可以自动解决这些依赖
 关系并能通过一个简单的 `get('userLister')` 调用创建一个新的 `UserLister` 实例。
 ```php
 namespace app\models;
 use yii\base\Object;
 use yii\db\Connection;
 use yii\di\Container;
 interface UserFinderInterface
 {
    function findUser();
 }
 class UserFinder extends Object implements UserFinderInterface
 {
    public $db;
    public function __construct(Connection $db, $config = [])
    {
        $this->db = $db;
        parent::__construct($config);
    }
    public function findUser()
    {
    }
 }
 class UserLister extends Object
 {
    public $finder;
    public function __construct(UserFinderInterface $finder, $config = [])
    {
        $this->finder = $finder;
        parent::__construct($config);
    }
 }
 $container = new Container;
 $container->set('yii\db\Connection', [
    'dsn' => '...',
 ]);
 $container->set('app\models\UserFinderInterface', [
    'class' => 'app\models\UserFinder',
 ]);
 $container->set('userLister', 'app\models\UserLister');
 $lister = $container->get('userLister');
 // 等价于:
 $db = new \yii\db\Connection(['dsn' => '...']);
 $finder = new UserFinder($db);
 $lister = new UserLister($finder);
 ```
 实践中的运用 <a name="practical-usage"></a>
 ---------------
 当你在应用程序的[入口脚本](structure-entry-scripts.md)中引入 `Yii.php` 文件时，Yii 就创建了一个 DI 容器。这个 DI 容器可以通过
 [[Yii::$container]] 访问。当你调用 [[Yii::createObject()]] 时，此方法实际上会调用这个容器的 [[yii\di\Container::get()|get()]]
 方法创建一个新对象。如上所述，DI 容器会自动解决依赖关系（如果有）并将其注入新创建的对象中。因为 Yii 在其多数核心代码中都使用了
 [[Yii::createObject()]] 创建新对象，所以你可以通过 [[Yii::$container]] 全局性地自定义这些对象。
 例如，你可以全局性自定义 [[yii\widgets\LinkPager]] 中分页按钮的默认数量:
 ```php
 \Yii::$container->set('yii\widgets\LinkPager', ['maxButtonCount' => 5]);
 ```
 这样如果你通过如下代码在一个视图里使用这个挂件，它的 `maxButtonCount` 属性就会被初始化为 5 而不是类中定义的默认值 10。
 ```php
 echo \yii\widgets\LinkPager::widget();
 ```
 然而你依然可以覆盖通过 DI 容器设置的值：
 ```php
 echo \yii\widgets\LinkPager::widget(['maxButtonCount' => 20]);
 ```
 另一个例子是借用 DI 容器中自动构造器注入带来的好处。假设你的控制器类依赖一些其他对象，例如一个旅馆预订服务。你可以通过一个构造器参数声明
 依赖关系，然后让 DI 容器帮你自动解决这个依赖关系。
 ```php
 namespace app\controllers;
 use yii\web\Controller;
 use app\components\BookingInterface;
 class HotelController extends Controller
 {
    protected $bookingService;
    public function __construct($id, $module, BookingInterface $bookingService, $config = [])
    {
        $this->bookingService = $bookingService;
        parent::__construct($id, $module, $config);
    }
 }
 ```
 如果你从浏览器中访问这个控制器，你将看到一个报错信息，提醒你 `BookingInterface` 无法被实例化。这是因为你需要告诉 DI 容器怎样处理这个
 依赖关系。
 ```php
 \Yii::$container->set('app\components\BookingInterface', 'app\components\BookingService');
 ```
 现在如果你再次访问这个控制器，一个 `app\components\BookingService` 的实例就会被创建并被作为第三个参数注入到控制器的构造器中。
 什么时候注册依赖关系 <a name="when-to-register-dependencies"></a>
 -----------------------------
 由于依赖关系在创建新对象时需要解决，因此它们的注册应该尽早完成。如下是推荐的实践：
 * 如果你是一个应用程序的开发者，你可以在应用程序的[入口脚本](structure-entry-scripts.md)或者被入口脚本引入的脚本中注册依赖关系。
 * 如果你是一个可再分发[扩展](structure-extensions.md)的开发者，你可以将依赖关系注册到扩展的引导类中。
 总结 <a name="summary"></a>
 -------
 依赖注入和[服务定位器](concept-service-locator.md) 都是流行的设计模式，它们使你可以用充分解耦且更利于测试的风格构建软件。我们强烈推荐
 你阅读 [Martin 的文章](http://martinfowler.com/articles/injection.html) ，对依赖注入和服务定位器有个更深入的理解。
 Yii 在依赖住入（DI）容器之上实现了它的[服务定位器](concept-service-locator.md)。当一个服务定位器尝试创建一个新的对象实例时，它会把
 调用转发到 DI 容器。后者将会像前文所述那样自动解决依赖关系。
--- a/docs/guide-zh-CN/start-workflow.md
+++ b/docs/guide-zh-CN/start-workflow.md
@ -0,0 +1,87 @@
 运行应用程序
 ====================
 Yii 安装后，就有了一个可以运行的 Yii 应用程序，你可以通过 URL `http://hostname/basic/web/index.php` 或
 `http://hostname/index.php` 访问它，具体要取决于你的配置。本章将介绍此应用程序的内置功能，代码的组织方式以及总体上程序是怎样处理请求
 的。
 > Info: 为简单起见，这个“入门”教程假设你已经将 `basic/web` 设置为了 Web 服务器的文档根目录。访问此程序的是类似
 `http://hostname/index.php` 的 URL 。请根据你的实际情况，在下文描述中作相应调整。
 功能 <a name="functionality"></a>
 -------------
 安装的基础应用程序包含四个页面：
 * 首页，访问 URL `http://hostname/index.php` 时显示，
 * "About" 页面，
 * "Contact" 页面，显示一个联络表单，允许终端用户通过电子邮件与你联系。
 * 还有 "Login" 页面，显示一个登录表单，用于验证终端用户。请尝试使用“admin/admin”登录，你将发现主菜单上原来的“Login”变成了“Logout”。
 这些页面共享一个通用的 header 和 footer。Header 含有一个主菜单，可以导航到不同的页面。
 你应该还会在浏览器窗口的最下面发现有一个工具条。这是一个 Yii 提供的很有用的[调试工具](tool-debugger.md)，它会记录并显示很多调试信息，
 例如日志消息，响应状态，数据库执行的查询等等。
 应用程序结构 <a name="application-structure"></a>
 ---------------------
 在你的应用程序中最重要的目录和文件是（假设程序的根目录是`basic`）：
 ```
 basic/                  应用程序根目录
    composer.json       用于 Composer，描述包的信息
    config/             包含应用程序及其他配置信息。
        console.php     控制台应用程序配置
        web.php         Web 应用程序配置
    commands/           包含控制台命令类
    controllers/        包含控制器类
    models/             包含模型类
    runtime/            包含 Yii 运行时产生的文件，例如日志和缓存文件等
    vendor/             包含已安装的 Componser 包，包括 Yii 框架本身。
    views/              包含视图文件
    web/                应用程序 Web 根目录，包含可通过 Web 访问的文件
        assets/         包含 Yii 已发布的资源文件（javascript 和 css）
        index.php       应用程序的入口（或引导）脚本
    yii                 Yii 控制台命令可执行脚本
 ```
 总体上，应用程序中的文件可以分为两类：位于 `basic/web` 中的和那些位于其他目录中的。前者可通过 HTTP （例如，在一个浏览器中）直接访问，
 后者则不能且不应该能。
 Yii 实现了 [模型-视图-控制器 (MVC)](http://wikipedia.org/wiki/Model-view-controller) 设计模式，在上述目录组织中也有体现。
 `models` 目录中包含了所有的[模型类](structure-models.md)，`views` 目录包含了所有的[视图脚本](structure-views.md)，
 `controllers` 目录包含了所有[控制器类](structure-controllers.md)。
 下图展示了一个应用程序的静态结构。
 ![应用程序的静态结构](images/application-structure.png)
 每个应用程序都有一个入口脚本 `web/index.php`，它是应用程序中仅有的可通过 Web 访问的 PHP 脚本。这个入口脚本接收一个传入请求并创建一个
 [应用程序](structure-applications.md) 实例处理该请求。[应用程序](structure-applications.md)在其[组件](concept-components.md)
 的帮助下解析请求并将请求分派到 MVC 元素上。[视图](structure-views.md)中使用[挂件](structure-widgets.md)协助构建复杂动态的用户接口
 元素。
 请求的生命周期 <a name="request-lifecycle"></a>
 -----------------
 下图展示了一个应用是如何处理请求的。
 ![请求的生命周期](images/application-lifecycle.png)
 1. 一个用户提交了对[入口脚本（entry script）](structure-entry-scripts.md) `web/index.php` 的请求。
 2. 入口脚本加载应用程序[配置信息（configuration）](concept-configurations.md)并创建一个[应用程序](structure-applications.md)实
 例处理该请求。
 3. 应用程序在[请求（request）]应用程序组件的协助下解析所请求的[路由（route）](runtime-routing.md)。
 4. 应用程序创建一个[控制器（controller）](structure-controllers.md)实例处理该请求。
 5. 控制器创建了一个[动作（action）](structure-controllers.md)实例，执行动作中的过滤器（filter）。
 6. 如果有任何一个过滤器处理失败，则动作取消。
 7. 如果所有的过滤器都执行通过，则动作执行。
 8. 动作载入一个数据模型，可能是从一个数据库中加载。
 9. 动作渲染一个视图（view），给它提供数据模型。
 10. 渲染结果返回给[响应（response）](runtime-responses.md)应用程序组件。
 11. 响应组件发送渲染结果到用户的浏览器。