扩展包

概述

创建扩展

创建一个 Composer 软件包的需遵循的基本步骤:

  1. 为你的扩展建一个工程,并将它存放在版本控制代码库中。 扩展的开发和维护都应该在这个代码库中进行。

  2. 在工程的根目录下,建一个 Composer 所需的名为 composer.json 的文件。 详情请参考后面的章节。

  3. 在一个 Composer 代码库中注册你的扩展,以便其他用户能找到以及用 Composer 安装你的扩展。

扩展工程

Wii为扩展工程提供了标准工程模板,可以通过以下命令进行创建:

composer create-project --repository-url=https://packagist.wiiqq.com wii/wii2-ext --stability=dev --no-install --no-plugins wii2-yourext

扩展工程成功创建后可以看到以下工程目录:

├── builder                      配置文件集合
│   └── sql                      sql文件目录
├── commands                     命令行程序文件
│   └── TaskController.php
├── config
│   └── main.conf.php            扩展配置信息
├── filters                      filter 类
│   └── DefaultFilter.php
├── models                       model类目录
│   ├── app
│   └── user
├── modules                      模块目录
│   ├── api                      对外接口模块
│   ├── main                     主模块(PC)                 
│   ├── oss                      运营管理系统(后台管理系统)
│   ├── app                      业务模块
│   └── user                     业务模块
├── tests                        单元测试文件夹,可编写单元测试、功能测试、集成测试
│   ├── codeception.yml
│   └── tests                
├── views                        视图文件
│   └── layout                   模板文件
├── composer.json                Composer 配置文件, 描述扩展包信息
└── CHANGELOG.md                 修改日志文件
└── README.md                    自述文件

composer.json

每个 Composer 软件包在根目录都必须有一个 composer.json 文件。该文件包含软件包的元数据。 你可以在 Composer手册 中找到完整关于该文件的规格。 以下例子展示了 wii/wii-lib 扩展的 composer.json 文件。

{
  "name": "wii/wii2-yourext",
  "description": "Wii API Library",
  "version": "1.0.0",
  "type": "library",
  "keywords": [
    "wii",
    "project"
  ],
  "autoload": {
    "psr-4": {
      "wii\\yourext\\": ""
    }
  },
  "require": {}
}

包名

每个 Composer 软件包都应当有一个唯一的包名以便能从其他的软件包中识别出来。 包名的格式为 vendorName/projectName 。例如在包名 wii/wii2-lib 中,vendor 名和 project 名分别是 wiiwii2-lib

不要用 wii 作为你的 vendor 名,由于它被 Wii 的核心代码预留使用了。

我们推荐你用 wii2- 作为你的包名的前缀,表示它是 Wii 2 的扩展,例如,myname/yii2-mywidget。 这更便于用户辨别是否是 Wii 2 的扩展。

包类型

将你的扩展指明为 wii2-extension 类型很重要,以便安装的时候 能被识别出是一个 Wii 扩展。

当用户运行 composer install 安装一个扩展时, vendor/wii/extensions.php 文件会被自动更新使之包含新扩展的信息。从该文件中, Yii 应用程序就能知道安装了哪些扩展 (这些信息可通过 wii\base\Application::$extensions 访问)

推荐的做法

扩展意味着会被其他人使用,你在开发中通常需要额外的付出。下面我们介绍一些通用的及推荐的做法,以创建高品质的扩展。

命名空间

为避免冲突以及使你的扩展中的类能被自动加载,你的类应当使用命名空间, 并使类的命名符合 PSR-4 standard 或者 PSR-0 standard 标准。

你的类的命名空间应以 vendorName\extensionName 起始,其中 extensionName 和项目名相同,除了它没有 wii2- 前缀外。例如,对 wii/wii2-lib 扩展来说,我们用 wii\lib 作为它的类的命名空间。

不要使用 wii 作为你的 vendor 名。这些名称已由 Wii 内核代码预留使用了。

类的自举引导

有时候,你可能想让你的扩展在应用的 自举过程 中执行一些代码。 例如,你的扩展可能想响应应用的 beginRequest事件,做一些环境的设置工作。 虽然你可以指导扩展的使用者显式地将你的扩展中的事件句柄附加(绑定)到 beginRequest 事件, 但是更好的方法是自动完成。

为实现该目标,你可以创建一个所谓 bootstrapping class (自举类)实现 wii\base\BootstrapInterface 接口。 例如,

namespace myname\mywidget;

use wii\base\BootstrapInterface;
use wii\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"
    }
}

当这个扩展安装到应用后,Wii 将在每一个请求的自举过程中 自动实例化自举类并调用其 bootstrap() 方法。

操作数据库

你的扩展可能要存取数据库。不要假设使用你的扩展的应用总是用 Wii::$db 作为数据库连接。你应当在需要访问数据库的类中申明一个 db 属性。 这个属性允许你的扩展的用户可定制你的扩展使用哪个 DB 连接。例如, 你可以参考 wii\caching\DbCache 类看一下它是如何申明和使用 db 属性的。

如果你的扩展需要创建特定的数据库表,或者修改数据库结构,你应当

  • 提供 数据迁移 来操作数据库的结构修改,而不是使用SQL文本文件;
  • 尽量使迁移文件适用于不同的 DBMS;
  • 在迁移文件中避免使用 Active Record

使用 Assets

如果你的扩展是挂件或者模块类型,它有可能需要使用一些 assets 。 例如,一个模块可能要显示一些包含图片,JavaScript 和 CSS 的页面。因为扩展的文件 都是放在同一个目录之下,安装之后 Web 无法读取,你有两个选择使得这些 asset 文件目录 可以通过 Web 读取:

  • 让扩展的用户手动将这些 asset 文件拷贝到特定的 Web 可以读取的文件夹;
  • 申明一个 asset bundle 并依靠 asset 发布机制自动将这些文件(asset bundle 中列出的文件) 拷贝到 Web 可读的文件夹。

我们推荐你使用第二种方法,以便其他人能更容易使用你的扩展。 更详细的关于如何处理 assets ,请参照 Assets 章节。

版本控制

你应该为每一个扩展定一个版本号(如 1.0.1)。我们推荐你命名版本号时参照 版本控制 决定用什么样的版本号。

发布

为使其他人知道你的扩展,你应该公开发布。

如果你首次发布一个扩展,你应该在 Composer 代码库中注册它。之后,你所需要做的仅仅是在版本管理库中创建一个 tag (如 v1.0.1),然后通知 Composer 代码库。 其他人就能查找到这个新的发布了,并可通过 Composer 代码库安装和更新该扩展。

在发布你的扩展时,除了代码文件,你还应该考虑包含如下内容 帮助其他人了解和使用你的扩展:

  • 根目录下的 readme 文件:它描述你的扩展是干什么的以及如何安装和使用。 我们推荐你用 Markdown 的格式 来写并将文件命名为 readme.md。
  • 根目录下的修改日志文件:它列举每个版本的发布做了哪些更改。该文件可以用 Markdown 根式 编写并命名为 changelog.md。
  • 根目录下的升级文件:它给出如何从其他就版本升级该扩展的指导。该文件可以用 Markdown 根式 编写并命名为 changelog.md。
  • 入门指南、演示代码、截屏图示等:如果你的扩展提供了许多功能,在 readme 文件中不能完整 描述时,就要用到这些文件。
  • API 文档:你的代码应当做好文档,让其他人更容易阅读和理解。 你可以参照 Object class file 学习如何为你的代码做文档。

核心扩展

Wii 提供了下列核心扩展,由 Wii 开发团队开发和维护。

  • wii/wii2-lib: 提供了Wii微服务API调用。
  • wii/wii2-gii: 提供了一个基于页面的代码生成器,具有高可扩展性,并能用来快速生成模型、 表单、模块、CRUD等。

Wii 完全兼容 Yii2 的扩展,详情参照:Yii2-核心扩展

results matching ""

    No results matching ""