每个 Composer 软件包都应当有一个唯一的包名以便能从其他的软件包中识别出来。 包名的格式为 vendorName/projectName 。例如在包名 yiisoft/yii2-imagine 中,vendor 名和 project 名分别是 yiisoft 和 yii2-imagine 。
不要用 yiisoft 作为你的 vendor 名,由于它被 Yii 的核心代码预留使用了。
我们推荐你用 yii2- 作为你的包名的前缀,表示它是 Yii 2 的扩展,例如,myname/yii2-mywidget。 这更便于用户辨别是否是 Yii 2 的扩展。
包类型
将你的扩展指明为 yii2-extension 类型很重要,以便安装的时候 能被识别出是一个 Yii 扩展。
当用户运行 composer install 安装一个扩展时, vendor/yiisoft/extensions.php 文件会被自动更新使之包含新扩展的信息。从该文件中, Yii 应用程序就能知道安装了 哪些扩展 (这些信息可通过 yii\base\Application::extensions 访问)。
依赖
你的扩展依赖于 Yii (理所当然)。因此你应当在 composer.json 文件中列出它 (yiisoft/yii2)。如果你的扩展还依赖其他的扩展或者是第三方库,你也要一并列出来。 确定你也为每一个依赖的包列出了适当的版本约束条件 (比如 1.*, @stable) 。 当你发布一个稳定版本时,你所依赖的包也应当使用稳定版本。
大多数 JavaScript/CSS 包是用 Bower 来管理的,而非 Composer。你可使用 Composer asset 插件 使之可以 通过 Composer 来管理这类包。如果你的扩展依赖 Bower 软件包,你可以如下例所示那样简单地 在 composer.json 文件的依赖中列出它。
{ // package dependencies "require": { "bower-asset/jquery": ">=1.11.*" } }
上述代码表明该扩展依赖于 jquery Bower 包。一般来说,你可以在 composer.json 中用 bower-asset/PackageName 指定 Bower 包,用 npm-asset/PackageName 指定 NPM 包。 当 Compower 安装 Bower 和 NPM 软件包时,包的内容默认会分别安装到@vendor/bower/PackageName 和 @vendor/npm/Packages 下。这两个目录还可以分别用 @bower/PackageName 和@npm/PackageName 别名指向。
类的自动加载
为使你的类能够被 Yii 的类自动加载器或者 Composer 的类自动加载器自动加载,你应当在 composer.json 中指定 autoload 条目,如下所示:
{ // .... "autoload": { "psr-4": { "yii\\imagine\\": "" } } }
你可以列出一个或者多个根命名空间和它们的文件目录。
当扩展安装到应用中后,Yii 将为每个所列出根命名空间创建一个 别名 指向命名空间对应的目录。 例如,上述的 autoload 条目声明将对应于别名 @yii/imagine。
推荐的做法
扩展意味着会被其他人使用,你在开发中通常需要额外的付出。 下面我们介绍一些通用的及推荐的做法,以创建高品质的扩展。
命名空间
为避免冲突以及使你的扩展中的类能被自动加载,你的类应当使用命名空间, 并使类的命名符合 PSR-4 standard 或者 PSR-0 standard 标准。
你的类的命名空间应以 vendorName\extensionName 起始,其中 extensionName 和项目名相同,除了它没有 yii2- 前缀外。例如,对 yiisoft/yii2-imagine 扩展 来说,我们用 yii\imagine 作为它的类的命名空间。
不要使用 yii、yii2 或者 yiisoft 作为你的 vendor 名。这些名称已由 Yii 内核代码预留使用了。
类的自举引导
有时候,你可能想让你的扩展在应用的 自举过程 中执行一些代码。 例如,你的扩展可能想响应应用的 beginRequest 事件,做一些环境的设置工作。 虽然你可以指导扩展的使用者显式地将你的扩展中的事件句柄附加(绑定)到 beginRequest 事件, 但是更好的方法是自动完成。
为实现该目标,你可以创建一个所谓 bootstrapping class (自举类)实现 yii\base\BootstrapInterface 接口。 例如,
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 }); } }
然后你将这个类在 composer.json 文件中列出来,如下所示,
{ // ... "extra": { "bootstrap": "myname\\mywidget\\MyBootstrapClass" } }
当这个扩展安装到应用后,Yii 将在每一个请求的自举过程中 自动实例化自举类并调用其 yii\base\BootstrapInterface::bootstrap() 方法。
操作数据库