[Yii2笔记]043扩展(Extensions) [ 技术分享 ]

说明

学习Yii Framework 2（易2框架）的过程是漫长的，也是充满乐趣的，以下是我学习Yii2框架时对官网英文资料(请参见原文网址)的翻译和代码实现，提供了较完整的代码，供你参考。不妥之处，请多多指正！

原文网址：

http://www.yiiframework.com/doc-2.0/guide-structure-extensions.html

本文主题：扩展(Extensions)

扩展是可再发行的软件包，它专门为Yii应用设计，并提供了随时可用的特性。例如，yiisoft/yii2-debug扩展在应用中为每个页面的底部添加了一个方便的调试工具，它可以帮助你更轻松抓取页面产生过程。你可以使用扩展加速你的开发过程。你也可以将你的代码打包成扩展，把你的好东东分享给大家。

信息：我们使用术语"扩展"(extension)特指为Yii定义的软件包，对于非Yii的常规目的软件包，我们将称之为"包"(package)或"库"(library)。

1、Using Extensions（使用扩展）

要使用一个扩展，你需要先安装它。大多数扩展以Composer包的形式发布出来，使用以下两步就可以安装它们： 1）修改你的应用的composer.json文件来定义要安装哪个扩展（Composer包） 2）运行composer install来安装指定的扩展。

注意如果没有Composer，那么需要你先安装它： https://getcomposer.org/

默认情况下，Composer安装的是注册在Packagist上的包，Packagist（https:/ /packagist.org/）是开源Composer包最大的资源库。你可以在Packagist网站上搜索扩展。你也可以创建你自己的库(repository)，并配置Composer去使用它，如果你要开发仅在你的项目中共享的私用扩展，这种做法是非常实用的。

使用Composer安装的扩展存储在BasePath/vendor目录下，BasePath是指应用的基本目录。因为Composer是个依赖管理器，所以当它安装一个包时，它会安装这个包所依赖的所有其他包。

例如，要安装yiisoft/yii2-imagine扩展，对你的composer.json如下修改：

	{
		//...
		"require":{
			//...
			"yiisoft/yii2-imagine":"*"
		}
	}

安装完成后，你将在BasePath/vendor目录下看到yiisoft/yii2-imagine目录，你也会看到另一个目录imagine/imagine，它包含了已安装的依赖包。 信息：yiisoft/yii2-imagine是由Yii开发者团队开发和维护的一个核心扩展，所有核心扩展都存放在Packagist，并命名为yiisoft/yii2-xyz，xyz用于区分不同的扩展。

现在你就可以象使用应用其他部件一样使用已安装的扩展了。下全展示了你如何使用yiisoft\yii2-imagine扩展的yii\imagine\Image类：

use Yii;
use yii\imagine\Image;
//生成一个缩略图
Image::thumbnail('@webroot/img/test-image.jpg',120,120)
	->save(Yii::getAlias('@runtime/thumb-test-image.jpg'),['quality'=>50]);

信息：Yii类自动加载器将自动加载扩展类。

Installing Extensions Manully(手动安装扩展)

在一些特殊场合下，你可以需要手动安装扩展，而不是使用Composer。要实现此目标，你需要： 1）下载扩展压缩文档，并把它们解压缩到vendor目录。 2）安装扩展提供的类自动加载器（autoloader），如果有的话。 3）根据指示下载并安装所有依赖的扩展。

如果一个扩展没有类自动加载器，但遵循PSR-4标准，你可以使用Yii提供的类自动加载器去自动加载扩展类。需要你做的就是为扩展的根目录定义一个根目录别名。例如，假设你需要去安装一个扩展到vendor/mycompany/myext目录，扩展类的命名空间是myext，你可以在应用配置中包含以下代码：

	[
		'aliases'=>[
			'@myext'=>'@vendor/mycompany/myext',
		],
	]

Yii2扩展的存放位置：//extensions

yii\base\Application::$extensions

//获取当前应用加载的扩展：

	echo "<br>Yii extensions:<br>";
    var_dump(Yii::$app->extensions);

测试结果：

D:\phpwork\news\vendor\yiisoft\extensions.php
<?php
$vendorDir = dirname(__DIR__);
return array (
  'yiisoft/yii2-swiftmailer' => 
  array (
    'name' => 'yiisoft/yii2-swiftmailer',
    'version' => '2.0.6.0',
    'alias' => 
    array (
      '@yii/swiftmailer' => $vendorDir . '/yiisoft/yii2-swiftmailer',
    ),
  ),
  'yiisoft/yii2-bootstrap' => 
  array (
    'name' => 'yiisoft/yii2-bootstrap',
    'version' => '2.0.6.0',
    'alias' => 
    array (
      '@yii/bootstrap' => $vendorDir . '/yiisoft/yii2-bootstrap',
    ),
  ),
  'yiisoft/yii2-debug' => 
  array (
    'name' => 'yiisoft/yii2-debug',
    'version' => '2.0.9.0',
    'alias' => 
    array (
      '@yii/debug' => $vendorDir . '/yiisoft/yii2-debug',
    ),
  ),
  'yiisoft/yii2-gii' => 
  array (
    'name' => 'yiisoft/yii2-gii',
    'version' => '2.0.5.0',
    'alias' => 
    array (
      '@yii/gii' => $vendorDir . '/yiisoft/yii2-gii',
    ),
  ),
  'yiisoft/yii2-faker' => 
  array (
    'name' => 'yiisoft/yii2-faker',
    'version' => '2.0.3.0',
    'alias' => 
    array (
      '@yii/faker' => $vendorDir . '/yiisoft/yii2-faker',
    ),
  ),
  'kartik-v/yii2-krajee-base' => 
  array (
    'name' => 'kartik-v/yii2-krajee-base',
    'version' => '1.8.8.0',
    'alias' => 
    array (
      '@kartik/base' => $vendorDir . '/kartik-v/yii2-krajee-base',
    ),
  ),
  'kartik-v/yii2-markdown' => 
  array (
    'name' => 'kartik-v/yii2-markdown',
    'version' => '9999999-dev',
    'alias' => 
    array (
      '@kartik/markdown' => $vendorDir . '/kartik-v/yii2-markdown',
    ),
  ),
  'aki/yii2-vue' => 
  array (
    'name' => 'aki/yii2-vue',
    'version' => '0.5.0.0',
    'alias' => 
    array (
      '@aki/vue' => $vendorDir . '/aki/yii2-vue',
    ),
  ),
);

2、Creating Extensions(创建扩展)

当你想要把你的好东东拿出来与大家分享时，你可以考虑创建一个扩展。扩展可以是任何代码，如一个助手类、一个小部件、一个模块等。 推荐你以Composer包的形式创建扩展，这样它可以被其他用户很容易的安装和使用，如上一节中描述的一样。

以下是创建Composer包形式的扩展所需的基本步骤：

1）为你的扩展创建一个项目，并将它放入一个版本库（VCS repository）中，如github.coms。此扩展的开发和维护工作将在这个库中完成。
2）在此项目的根目录下，创建一个名为composer.json的文件，它将被Composer使用。请参考下一章节获取更多信息。
3）使用Composer资源库注册你的扩展，如Packagist，这样其他用户才能发现它并使用Composer安装你的扩展。

composer.json

每个Composer包必须在其根目录下有一个comoser.json文件，此文件包含了包的元数据信息。你可以在Composer Manual中找到此文件的完整定义。 Composer Manual：

https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup

下例展示了yiisoft/yii2-imgine扩展的composer.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": "~2.0.0",
        "imagine/imagine": "v0.5.0"
    },
    // class autoloading specs
    "autoload": {
        "psr-4": {
            "yii\\imagine\\": ""
        }
    }
}

Package Name（包名称）

每个Composer包都应有一个包名称，这个名称必须是唯一的，以区分与其他的包。包名称的格式是vendorName/projectName。例如，包名称yiisoft/yii2-imagine，提供者和项目名称分别是yiisoft和yii2-imagine。

不要使用yiisoft作为你的提供都名称，它是Yii核心代码预留的。

我们推荐你使用前缀"yii2-"来命名你为Yii2扩展开发的项目名称，例如，myname/yii2-mywidget，这样可以让用户很容易就知道此扩展是一个Yii2扩展。

Package Type（包类型）

将你的扩展的package type定义为yii2-extension是很重要的，这样在安装时，此包就可以被识别为Yii的扩展。 当一个用户运行composer install安装一个扩展时，文件vender/yiisoft/extensions.php将被自动更新，以包含新扩展的信息。从此文件中，Yii应用可以知晓已安装了哪些扩展（使用yii\base\Application::$extensions 即可获得）。

Dependencies（依赖）

你的扩展依赖于Yii（这是必然的）。所以你需要在composer.json的require部分将它(yiisoft/yii2)列出来。如果你的扩展还依赖于其他扩展或第三方库时，你也需要列出它们。请确认你为每个依赖包列出了合适的版本约束（如 "1.*","@stable"）。当你的扩展发行了一个稳定版本时，请使用稳定版本的依赖。

大多数JavaScript/CSS包使用Bower或NPM管理，而不是Composer。Yii通过Composer asset plugin使得通过Composer管理这些类型包成为可能。如果你的扩展依赖于Bower包，你可以在compouser.json中列出这些依赖，代码如下：

	{
		"require":{
			"bower-asset/jquery":">=1.11.*"
		}
	}

上述代码描述了扩展依赖于jquery的Bower包，通常情况下，在composer.json文件中你可以使用bower-asset/PackageName来指向一个Bower包，并使用npm-asset/PackageName来指向一个NPM包。当Composer安装一个Bower或NPM包时，这些包默认会分别安装在@vendor/bower/PackageName和@vendor/npm/Packages目录下。这两个目录也可以使用短别名@bower/PackageName和@npm/PackageName。

关于资源管理的更多信息，请参考Assets章节： http://www.yiiframework.com/doc-2.0/guide-structure-assets.html#bower-npm-assets

//Class Autoloading（类自动加载） 要让你的类被Yii或Composer的类自动加载器自动加载，你需要在composer.json文件中定义autoload部分，代码如下：

	{
		//...
		"autoload":{
			"psr-4":{
				"yii\\imagine\\":""
			}
		}
	}

你可以列出一个或多个要命名空间和它们对应的文件目录。 当扩展是安装在一个应用中时，Yii将为每个列出的根命名空间创建一个别名，此别名指向命名空间对应的目录。例如，上例中autoload声明对应的别名是@yii\imagine。

Recommended Practices(推荐作法)

因为扩展意味着要被其他人使用，所以需要你在开发过程中付出额外的努力。下面我们将介绍创建高质量扩展的一些通用和推荐作法。

Namespaces（命名空间）

要避免命名冲突并使用你的扩展类可以自动加载，你应遵循PSR-4或PSR-0标准，在你的类中使用命名空间，并命名类。 你的类命名空间应开始于vendorName\extensionName，extensionName与包名称中的项目名称类似，但它不应包含"yii2-"前缀。例如，yiisoft/yii2-imagine扩展，我们使用yii\imagine作为它的类命名空间。

不要使用yii，yii2或yiisoft作为你的提供者名称，这些名称都是为Yii核心代码预留的。

Bootstrappin Classes（启动类）

有时，你可能想要你的扩展在应用的启动过程中去执行。例如，你的扩展想要对应用的beginRequest事件作出响应，以调整一些环境参数。当然你可以指导用户显式添加此扩展到beginRequest事件中去，但更好的方法是去自动添加。

要实现此目标，你可以创建一个实现yii\base\BootstrapInterface接口的被称为bootstrapping class的类，例如：

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(){
			//逻辑代码		
		});
	}
}

你可能在你的扩展的composer.json文件中列出这个类，代码如下：

	{
		//...
		"extra":{
			"bootstrap":"myname\mywidget\MyBootstrapClass"
		}
	}

在应用中安装此扩展时，Yii将在处理每个请求的启动过程中自动实例化bootstrapping class并调用bootstrap()方法。

Working with Database(使用数据库)

你的扩展可能需要存取数据库，不要假设使用你的扩展的应用也是使用Yii::$db 作为DB连接。相反的，你应该为需要DB存取的类定义一个db属性，此属性允许用户去自定义决定你的扩展使用哪个DB链接。作为示例，你可以参考yii\caching\DbCache类，并查看它是如何声明和使用db属性的。 yii\caching\DbCache类： http://www.yiiframework.com/doc-2.0/yii-caching-dbcache.html

如果你的扩展要创建特定的数据表或要修改DB模型，你应该： 1）提供迁移以维护DB模型，而不是使用原生SQL文件 2）尝试为不同的DBMS创建迁移 3）在迁移中避免使用Acitive Record

//Using Assets(使用资源) 如果你的扩展是一个小部件或模块，可能它需要使用到一些资源。例如，一个模块可以显示包含图片、JavaScript、CSS的页面，当安装在一个应用中时，扩展文件是在同一个目录下的，是非Web可访问的，你有两种选择可以让资源文件直接被Web访问： 1）要求扩展的使用者手动拷贝资源文件到特定的Web可访问目录下。 2）声明一个资源集，并通过资源发布机制自动拷贝资源集中的文件到Web可访问目录下。

我们推荐你使用第二种方法，这样你的扩展可以更容易的被其他人所使用。关于如何使用资源请参考Assets章节： http://www.yiiframework.com/doc-2.0/guide-structure-assets.html

Internationalization and Localization（国际化和本土化）

应用中使用到你的扩展可能需要支持不同的语言，所以，如果你的扩展要向用户显示内容，你就尽量提供国际化和本土化功能，包括： 1）如果扩展要向用户显示信息，应将信息使用Yii::t()括起来，这样它们就可以被翻译出来，而需要向开发者传达的信息（如内部异常信息）就不用被翻译出来了。 2）如果扩展显示数字、日期等，它们应该使用yii\i18n\Formatter中相应的格式规则去格式化。

更多信息请参考Internationalization章节： http://www.yiiframework.com/doc-2.0/guide-tutorial-i18n.html

Testing（测试）

你想让你的扩展完美运行，而不是给其他用户带来问题，你应在它公开发布之前测试它。 推荐你创建不同的测试用例来全面检测你的扩展代码，而不是仅使用手动检测。每次要发行扩展的新版本时，你可以直接运行这些测试用例来确保每件事件都是正确的。Yii提供了测试支持，这样可以使你可以更的编写测试用例、验收测试和功能测试。更多细节，请参考Testing章节： http://www.yiiframework.com/doc-2.0/guide-test-overview.html

Versioning（版本）

你应为你的每次发行制定一个版本号（如 1.0.1），我们推荐你使用Semantic Versioning来决定使用哪些版本数字： http://semver.org/

Releasing（发行）

要让其他人知道你的扩展，你需要对外公共发布出来。 如果你是第一次发行扩展，你应在Composer仓库网站上注册它，如Packagist：https://packagist.org

随后，你需要在你的扩展的VCS仓库中创建一个发布标签（如v1.0.1），并将新发布通知Composer仓库。其他人就可以找到新发布的扩展，通过Composer仓库安装和更新此扩展。 在你的扩展发布中，除了代码文件，你应考虑包括以下内容以帮助其他人了解和使用你的扩展： 1）在发行包根目录下的说明（readme）文件：它描述了你的扩展是做什么的，怎样去安装和使用它。我们推荐你以Markdown格式来编写它，并将其命名为readme.md。 2）在发行包根目录下的变更日志（changelog）文件：它列出每次发行时所做的修改，此文件应使用Markdown格式编写并命名为changelog.md。 3）在发行包根目录下的升级（upgrade）文件：它给出如何从老版本升级的指令。此文件应使用Markdown格式并命名为upgrade.md。 4）教程、示例、快照等：这些文件将提供在readme文件中没有描述的更多特性。 5）API文档：你的代码应很容易文档化，以让其他人更容易阅读和理解它。你可以参考Object class file以学习如何文档化你的代码。 https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php

信息：你的代码注释可以用Markdown格式书写，yiisoft/yii2-apidoc扩展提供了一个工具使用你能够基于你的代码注释生成漂亮的API文档。

信息：不是必须的，我们建议你的扩展符合一些代码风格，你可以参考： Yii2核心代码风格： https://github.com/yiisoft/yii2/blob/master/docs/internals/core-code-style.md Yii2视图代码风格： https://github.com/yiisoft/yii2/blob/master/docs/internals/view-code-style.md

3、Core Extensions（核心扩展）

Yii提供了以下核心扩展，它们由Yii开发团队开发和维护。它们全部注册在Packagist网站，可以根据“使用扩展”章节描述的内容轻松安装。

yiisoft/yii2-apidoc: 提供了一个可扩展、高性能的API文档生成器，正是使用它生成的Yii2核心框架API文档。
	https://github.com/yiisoft/yii2-apidoc

yiisoft/yii2-authclient: 提供了一套通用的客户端认证工具，如Facebook OAuth2客户端、GitHub OAuth2客户端。
	https://github.com/yiisoft/yii2-authclient

yiisoft/yii2-bootstrap: 提供了一套封装Bootstrap组件和插件的小部件。
	https://github.com/yiisoft/yii2-bootstrap

yiisoft/yii2-codeception: 基于Codeception提供测试支持
	https://github.com/yiisoft/yii2-codeception

yiisoft/yii2-debug: 为Yii应用提供调试支持。当此扩展被使用时，一个调试工具将显示在每个页面的底部。此扩展也提供了一套独立页面以显示更多的调试信息。
	https://github.com/yiisoft/yii2-debug

yiisoft/yii2-elasticsearch: 提供了使用Elasticsearch的支持。它包括基本的查询、搜索支持，也支持Active Record模式，这样就允许你将Active Record存储到Elasticsearch中。
	https://github.com/yiisoft/yii2-elasticsearch

yiisoft/yii2-faker：提供了使用Faker生成fake数据的支持
	https://github.com/yiisoft/yii2-faker

yiisoft/yii2-gii: 提供了一个基于Web的高扩展性的代码成器，可以使用它生成模型、表单、模块、CRUD操作等。
	https://github.com/yiisoft/yii2-gii

yiisoft/yii2-httpclient: 提供了HTTP客户端。
	https://github.com/yiisoft/yii2-httpclient

yiisoft/yii2-imagine: 基于Imagine组件提供了通用的图片处理功能。
	https://github.com/yiisoft/yii2-imagine
	http://imagine.readthedocs.io/en/latest/

yiisoft/yii2-jui: 提供了一套封装JQuery UI的小部件
	https://github.com/yiisoft/yii2-jui

yiisoft/yii2-mongodb: 提供了使用MongoDB的支持，包括：基本查询、Active Record、迁移、缓存、代码生成等。
	https://github.com/yiisoft/yii2-mongodb	

yiisoft/yii2-redis: 提供了使用redis的支持，包括：基本查询、Active Record、缓存等。
	https://github.com/yiisoft/yii2-redis

yiisoft/yii2-smarty: 基于Smarty提供了一个模板引擎。
	https://github.com/yiisoft/yii2-smarty

yiisoft/yii2-sphinx: 提供了使用Sphinx的支持，包括：基本查询、Active Record、代码生成等。
	https://github.com/yiisoft/yii2-sphinx

yiisoft/yii2-swiftmailer: 基于swiftmailer提供了邮件发送功能。
	https://github.com/yiisoft/yii2-swiftmailer	

yiisoft/yii2-twig: 基于Twig提供了一个模板引擎
	https://github.com/yiisoft/yii2-twig

（全文完）