扩展是专门设计的在 Yii 应用中随时可拿来使用的, 并可重发布的软件包。例如, yiisoft/yii2-debug 扩展在你的应用的每个页面底部添加一个方便用于调试的工具栏, 帮助你简单地抓取页面生成的情况。 你可以使用扩展来加速你的开发过程。
信息:本文中我们使用的术语 "扩展" 特指 Yii 软件包。而用术语 "软件包" 和 "库" 指代非 Yii 专用的通常意义上的软件包。
使用扩展
要使用扩展,你要先安装它。大多数扩展以 Composer 软件包的形式发布, 这样的扩展可采取下述两个步骤来安装:
修改你的应用的 composer.json 文件,指明你要安装的是哪个扩展 (Composer 软件包)。
运行 composer install 来安装指定的扩展。
注意如果你还没有安装 Composer ,你需要先安装。
默认情况,Composer安装的是在 Packagist 中 注册的软件包 - 最大的开源 Composer 代码库。你可以在 Packageist 中查找扩展。 你也可以 创建你自己的代码库 然后配置 Composer 来使用它。 如果是在开发私有的扩展,并且想只在你的其他工程中共享时,这样做是很有用的。
通过 Composer 安装的扩展会存放在 BasePath/vendor 目录下,这里的 BasePath 指你的应用的 base path。因为 Composer 还是一个依赖管理器,当它安装一个包时, 也将安装这个包所依赖的所有软件包。
例如想安装 yiisoft/yii2-imagine 扩展,可按如下示例修改你的 composer.json 文件:
{ // ... "require": { // ... other dependencies "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 class autoloader 自动加载。
手动安装扩展
在极少情况下,你可能需要手动安装一部分或者全部扩展,而不是依赖 Composer。 想做到这一点,你应当:
下载扩展压缩文件,解压到 vendor 目录。
如果有,则安装扩展提供的自动加载器。
按指导说明下载和安装所有依赖的扩展。
如果扩展没有提供类的自动加载器,但也遵循了 PSR-4 standard 标准,那么你可以使用 Yii 提供的类自动加载器来加载扩展类。 你需要做的仅仅是为扩展的根目录声明一个 root alias。 例如,假设在 vendor/mycompany/myext 目录中安装了一个扩展,并且扩展类的命名空间为 myext , 那么你可以在应用配置文件中包含如下代码:
[ 'aliases' => [ '@myext' => '@vendor/mycompany/myext', ], ]
创建扩展
在你需要将你的杰作分享给其他人的时候,你可能会考虑创建一个扩展。 扩展可包括任何你喜欢的代码,例如助手类、挂件、模块,等等。
建议你按照 Composer package 的条款创建扩展,以便其他人更容易安装和使用。
以下是将扩展创建为一个 Composer 软件包的需遵循的基本步骤。
为你的扩展建一个工程,并将它存放在版本控制代码库中,例如 github.com 。 扩展的开发和维护都应该在这个代码库中进行。
在工程的根目录下,建一个 Composer 所需的名为 composer.json 的文件。
在一个 Composer 代码库中注册你的扩展,比如在 Packagist 中,以便其他 用户能找到以及用 Composer 安装你的扩展。
composer.json
每个 Composer 软件包在根目录都必须有一个 composer.json 文件。该文件包含软件包的元数据。 你可以在 Composer手册 中找到完整关于该文件的规格。 以下例子展示了 yiisoft/yii2-imagine 扩展的 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": "*", "imagine/imagine": "v0.5.0" }, // class autoloading specs "autoload": { "psr-4": { "yii\\imagine\\": "" } } }
包名
每个 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는 자동으로 부트스트랩 클래스를 인스턴스화하고 각 요청의 부트스트랩 프로세스 중에 yiibaseBootstrapInterface::bootstrap() 메서드를 호출합니다.
운영 데이터베이스
확장 프로그램이 데이터베이스에 액세스해야 할 수도 있습니다. 확장 기능을 사용하는 애플리케이션이 항상 데이터베이스 연결로 Yii::$db를 사용할 것이라고 가정하지 마세요. 데이터베이스에 액세스해야 하는 클래스에서 db 속성을 선언해야 합니다. 이 속성을 사용하면 확장 사용자가 확장에서 사용하는 DB 연결을 사용자 지정할 수 있습니다. 예를 들어 yiicachingDbCache 클래스를 참조하여 db 속성을 선언하고 사용하는 방법을 확인할 수 있습니다.
확장 프로그램이 특정 데이터베이스 테이블을 생성하거나 데이터베이스 구조를 수정해야 하는 경우 다음을 수행해야 합니다.
SQL 텍스트 파일을 사용하는 대신 데이터베이스의 구조적 수정 작업을 위한 데이터 마이그레이션 제공
마이그레이션 파일을 다른 DBMS에 적용해 보세요.
마이그레이션 파일에 Active Record를 사용하지 마세요.
자산 사용
확장 프로그램이 위젯 또는 모듈 유형인 경우 일부 자산을 사용해야 할 수도 있습니다. 예를 들어 모듈은 이미지, JavaScript 및 CSS가 포함된 페이지를 표시할 수 있습니다. 확장 파일은 동일한 디렉터리에 있으므로 설치 후 웹에서 읽을 수 없습니다. 웹에서 이러한 자산 파일 디렉터리를 읽을 수 있도록 하는 두 가지 옵션이 있습니다.
확장 프로그램 사용자가 이러한 자산 파일을 웹에서 읽을 수 있는 특정 폴더에 수동으로 복사하도록 합니다.
자산 번들을 선언하고 자산 게시 메커니즘을 사용하여 파일(자산 번들에 나열됨)을 웹에서 읽을 수 있는 폴더에 자동으로 복사합니다.
다른 사람이 귀하의 확장 프로그램을 더 쉽게 사용할 수 있도록 하려면 두 번째 방법을 사용하는 것이 좋습니다.
국제화 및 현지화
귀하의 확장 프로그램은 다양한 언어를 지원하는 앱에서 사용될 수 있습니다! 따라서 확장 프로그램이 최종 사용자에게 콘텐츠를 표시하려면 국제화 및 현지화를 구현해야 합니다. 특히
확장 프로그램이 최종 사용자에 대한 정보를 표시하는 경우 이 정보는 번역될 수 있도록 Yii::t()로 래핑되어야 합니다. 개발자 참고용 정보(예: 내부 예외 정보)는 번역할 필요가 없습니다.
확장 프로그램이 숫자, 날짜 등을 표시하는 경우 yiii18nFormatter에서 적절한 형식 지정 규칙을 사용하여 형식을 지정해야 합니다.
테스트
다른 사람에게 문제나 문제를 일으키지 않고 확장 프로그램이 완벽하게 실행되기를 원합니다. 이 목표를 달성하려면 대중에게 공개하기 전에 테스트해야 합니다.
수동 테스트에만 의존하기보다는 포괄적인 범위에서 확장 프로그램을 테스트하기 위한 테스트 사례를 만드는 것이 좋습니다. 새 버전이 출시될 때마다 이러한 테스트를 실행하여 모든 것이 괜찮은지 확인하기만 하면 됩니다. Yii는 단위 테스트, 승인 테스트 및 기능 테스트를 더 쉽게 작성할 수 있도록 테스트 지원을 제공합니다.
버전 관리
각 확장 프로그램에 버전 번호(예: 1.0.1)를 지정해야 합니다. 사용할 버전 번호를 결정하기 위해 버전 번호 이름을 지정할 때 의미 체계 버전 관리를 참조하는 것이 좋습니다.
게시
다른 사람들에게 확장 기능을 알리려면 공개적으로 게시해야 합니다.
확장 기능을 처음 출시하는 경우 Packagist와 같은 Composer 저장소에 등록해야 합니다. 그 후에는 버전 관리 저장소(예: v1.0.1)에 태그를 생성한 다음 Composer 코드 베이스에 알리기만 하면 됩니다. 다른 사람들은 Composer 저장소를 통해 새 릴리스를 찾고 확장 기능을 설치 및 업데이트할 수 있습니다.
확장 프로그램을 게시할 때 코드 파일 외에도 다른 사람들이 확장 프로그램을 이해하고 사용할 수 있도록 다음 콘텐츠를 포함하는 것도 고려해야 합니다.
루트 디렉토리에 있는 Readme 파일: 확장 프로그램의 기능과 설치 및 사용 방법을 설명합니다. Markdown 형식으로 작성하고 파일 이름을 readme.md로 지정하는 것이 좋습니다.
루트 디렉터리의 변경 로그 파일: 여기에는 릴리스의 각 버전에 대해 변경된 내용이 나열됩니다. 이 파일은 Markdown radical로 작성될 수 있으며 이름은changelog.md입니다.
루트 디렉터리의 업그레이드 파일: 다른 버전에서 확장 프로그램을 업그레이드하는 방법에 대한 지침을 제공합니다. 이 파일은 Markdown radical로 작성될 수 있으며 이름은changelog.md입니다.
시작 가이드, 데모 코드, 스크린샷 등: 이 파일은 확장 프로그램이 추가 정보 파일에서 완전히 설명할 수 없는 많은 기능을 제공하는 경우 사용됩니다.
API 문서화: 다른 사람들이 쉽게 읽고 이해할 수 있도록 코드를 잘 문서화해야 합니다. 코드를 문서화하는 방법을 알아보려면 객체 클래스 파일을 참조하세요.
정보: 코드 주석은 Markdown 형식으로 작성할 수 있습니다. yiisoft/yii2-apidoc 확장은 코드 주석에서 아름다운 API 문서를 생성하는 방법을 제공합니다.
정보: 필수는 아니지만 확장 프로그램이 코딩 규칙을 따르는 것이 좋습니다. 핵심 프레임워크 코드 스타일을 참조할 수 있습니다.
핵심 확장
Yii는 Yii 개발팀에서 개발하고 유지 관리하는 다음과 같은 핵심 확장 기능을 제공합니다. 이러한 확장은 모두 Packagist에 등록되어 있습니다: