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

docs/guide-zh-CN/concept-di-container.md

+依赖注入容器
+==============================
+
+依赖注入（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 容器。后者将会像前文所述那样自动解决依赖关系。
+

docs/guide-zh-CN/start-workflow.md

+运行应用程序
+====================
+
+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. 响应组件发送渲染结果到用户的浏览器。
+