Alexander Makarov
10 years ago
15 changed files with 1215 additions and 72 deletions
@ -0,0 +1,204 @@
|
||||
错误处理 |
||||
=============== |
||||
|
||||
Yii 内置了一个[[yii\web\ErrorHandler|error handler]]错误处理器，它使错误处理更方便， |
||||
Yii错误处理器做以下工作来提升错误处理效果： |
||||
|
||||
* 所有非致命PHP错误（如，警告，提示）会转换成可获取异常； |
||||
* 异常和致命的PHP错误会被显示，在调试模式会显示详细的函数调用栈和源代码行数。 |
||||
* 支持使用专用的 [控制器操作](structure-actions.md) 来显示错误； |
||||
* 支持不同的错误响应格式； |
||||
|
||||
[[yii\web\ErrorHandler|error handler]] 错误处理器默认启用， |
||||
可通过在应用的[入口脚本](structure-entry-scripts.md)中定义常量`YII_ENABLE_ERROR_HANDLER`来禁用。 |
||||
|
||||
|
||||
## 使用错误处理器 <a name="using-error-handler"></a> |
||||
|
||||
[[yii\web\ErrorHandler|error handler]] 注册成一个名称为`errorHandler`[应用组件](structure-application-components.md)， |
||||
可以在应用配置中配置它类似如下： |
||||
|
||||
```php |
||||
return [ |
||||
'components' => [ |
||||
'errorHandler' => [ |
||||
'maxSourceLines' => 20, |
||||
], |
||||
], |
||||
]; |
||||
``` |
||||
|
||||
使用如上代码，异常页面最多显示20条源代码。 |
||||
|
||||
如前所述，错误处理器将所有非致命PHP错误转换成可获取异常，也就是说可以使用如下代码处理PHP错误： |
||||
|
||||
```php |
||||
use Yii; |
||||
use yii\base\ErrorException; |
||||
|
||||
try { |
||||
10/0; |
||||
} catch (ErrorException $e) { |
||||
Yii::warning("Division by zero."); |
||||
} |
||||
|
||||
// execution continues... |
||||
``` |
||||
|
||||
如果你想显示一个错误页面告诉用户请求是无效的或无法处理的，可简单地抛出一个 [[yii\web\HttpException|HTTP exception]]异常， |
||||
如 [[yii\web\NotFoundHttpException]]。错误处理器会正确地设置响应的HTTP状态码并使用合适的错误视图页面来显示错误信息。 |
||||
|
||||
```php |
||||
use yii\web\NotFoundHttpException; |
||||
|
||||
throw new NotFoundHttpException(); |
||||
``` |
||||
|
||||
|
||||
## 自定义错误显示 <a name="customizing-error-display"></a> |
||||
|
||||
[[yii\web\ErrorHandler|error handler]]错误处理器根据常量`YII_DEBUG`的值来调整错误显示， |
||||
当`YII_DEBUG` 为 true (表示在调试模式)，错误处理器会显示异常以及详细的函数调用栈和源代码行数来帮助调试， |
||||
当`YII_DEBUG` 为 false，只有错误信息会被显示以防止应用的敏感信息泄漏。 |
||||
|
||||
> 补充: 如果异常是继承 [[yii\base\UserException]]，不管`YII_DEBUG`为何值，函数调用栈信息都不会显示， |
||||
这是因为这种错误会被认为是用户产生的错误，开发人员不需要去修正。 |
||||
|
||||
[[yii\web\ErrorHandler|error handler]] 错误处理器默认使用两个[视图](structure-views.md)显示错误: |
||||
|
||||
* `@yii/views/errorHandler/error.php`: 显示不包含函数调用栈信息的错误信息是使用， |
||||
当`YII_DEBUG` 为 false时，所有错误都使用该视图。 |
||||
* `@yii/views/errorHandler/exception.php`: 显示包含函数调用栈信息的错误信息时使用。 |
||||
|
||||
可以配置错误处理器的 [[yii\web\ErrorHandler::errorView|errorView]] 和 [[yii\web\ErrorHandler::exceptionView|exceptionView]] 属性 |
||||
使用自定义的错误显示视图。 |
||||
|
||||
|
||||
### 使用错误操作 <a name="using-error-actions"></a> |
||||
|
||||
使用指定的错误[操作](structure-controllers.md) 来自定义错误显示更方便， |
||||
为此，首先配置`errorHandler`组件的 [[yii\web\ErrorHandler::errorAction|errorAction]] 属性，类似如下： |
||||
|
||||
```php |
||||
return [ |
||||
'components' => [ |
||||
'errorHandler' => [ |
||||
'errorAction' => 'site/error', |
||||
], |
||||
] |
||||
]; |
||||
``` |
||||
|
||||
[[yii\web\ErrorHandler::errorAction|errorAction]] 属性使用[路由](structure-controllers.md#routes)到一个操作， |
||||
上述配置表示不用显示函数调用栈信息的错误会通过执行`site/error`操作来显示。 |
||||
|
||||
可以创建`site/error` 操作如下所示： |
||||
|
||||
```php |
||||
namespace app\controllers; |
||||
|
||||
use Yii; |
||||
use yii\web\Controller; |
||||
|
||||
class SiteController extends Controller |
||||
{ |
||||
public function actions() |
||||
{ |
||||
return [ |
||||
'error' => [ |
||||
'class' => 'yii\web\ErrorAction', |
||||
], |
||||
]; |
||||
} |
||||
} |
||||
``` |
||||
|
||||
上述代码定义`error` 操作使用[[yii\web\ErrorAction]] 类，该类渲染名为`error`视图来显示错误。 |
||||
|
||||
除了使用[[yii\web\ErrorAction]], 可定义`error` 操作使用类似如下的操作方法： |
||||
|
||||
```php |
||||
public function actionError() |
||||
{ |
||||
$exception = Yii::$app->errorHandler->exception; |
||||
if ($exception !== null) { |
||||
return $this->render('error', ['exception' => $exception]); |
||||
} |
||||
} |
||||
``` |
||||
|
||||
现在应创建一个视图文件为`views/site/error.php`，在该视图文件中，如果错误操作定义为[[yii\web\ErrorAction]]， |
||||
可以访问该操作中定义的如下变量： |
||||
|
||||
* `name`: 错误名称 |
||||
* `message`: 错误信息 |
||||
* `exception`: 更多详细信息的异常对象，如HTTP 状态码，错误码，错误调用栈等。 |
||||
|
||||
> 补充: 如果你使用 [基础应用模板](start-installation.md) 或 [高级应用模板](tutorial-advanced-app.md), |
||||
错误操作和错误视图已经定义好了。 |
||||
|
||||
|
||||
### 自定义错误格式 <a name="error-format"></a> |
||||
|
||||
错误处理器根据[响应](runtime-responses.md)设置的格式来显示错误， |
||||
如果[[yii\web\Response::format|response format]] 响应格式为`html`, 会使用错误或异常视图来显示错误信息，如上一小节所述。 |
||||
对于其他的响应格式，错误处理器会错误信息作为数组赋值给[[yii\web\Response::data]]属性，然后转换到对应的格式， |
||||
例如，如果响应格式为`json`，可以看到如下响应信息： |
||||
|
||||
``` |
||||
HTTP/1.1 404 Not Found |
||||
Date: Sun, 02 Mar 2014 05:31:43 GMT |
||||
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y |
||||
Transfer-Encoding: chunked |
||||
Content-Type: application/json; charset=UTF-8 |
||||
|
||||
{ |
||||
"name": "Not Found Exception", |
||||
"message": "The requested resource was not found.", |
||||
"code": 0, |
||||
"status": 404 |
||||
} |
||||
``` |
||||
|
||||
可在应用配置中响应`response`组件的`beforeSend`事件来自定义错误响应格式。 |
||||
|
||||
```php |
||||
return [ |
||||
// ... |
||||
'components' => [ |
||||
'response' => [ |
||||
'class' => 'yii\web\Response', |
||||
'on beforeSend' => function ($event) { |
||||
$response = $event->sender; |
||||
if ($response->data !== null) { |
||||
$response->data = [ |
||||
'success' => $response->isSuccessful, |
||||
'data' => $response->data, |
||||
]; |
||||
$response->statusCode = 200; |
||||
} |
||||
}, |
||||
], |
||||
], |
||||
]; |
||||
``` |
||||
|
||||
上述代码会重新格式化错误响应，类似如下： |
||||
|
||||
``` |
||||
HTTP/1.1 200 OK |
||||
Date: Sun, 02 Mar 2014 05:31:43 GMT |
||||
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y |
||||
Transfer-Encoding: chunked |
||||
Content-Type: application/json; charset=UTF-8 |
||||
|
||||
{ |
||||
"success": false, |
||||
"data": { |
||||
"name": "Not Found Exception", |
||||
"message": "The requested resource was not found.", |
||||
"code": 0, |
||||
"status": 404 |
||||
} |
||||
} |
||||
``` |
||||
@ -0,0 +1,528 @@
|
||||
资源 |
||||
====== |
||||
|
||||
Yii中的资源是和Web页面相关的文件，可为CSS文件，JavaScript文件，图片或视频等， |
||||
资源放在Web可访问的目录下，直接被Web服务器调用。 |
||||
|
||||
通过程序自动管理资源更好一点，例如，当你在页面中使用 [[yii\jui\DatePicker]] 小部件时， |
||||
它会自动包含需要的CSS和JavaScript文件，而不是要求你手工去找到这些文件并包含， |
||||
当你升级小部件时，它会自动使用新版本的资源文件，在本教程中，我们会详述Yii提供的强大的资源管理功能。 |
||||
|
||||
|
||||
## 资源包 <a name="asset-bundles"></a> |
||||
|
||||
Yii在*资源包*中管理资源，资源包简单的说就是放在一个目录下的资源集合， |
||||
当在[视图](structure-views.md)中注册一个资源包，在渲染Web页面时会包含包中的CSS和JavaScript文件。 |
||||
|
||||
|
||||
## 定义资源包 <a name="defining-asset-bundles"></a> |
||||
|
||||
资源包指定为继承[[yii\web\AssetBundle]]的PHP类，包名为可[自动加载](concept-autoloading.md)的PHP类名， |
||||
在资源包类中，要指定资源所在位置，包含哪些CSS和JavaScript文件以及和其他包的依赖关系。 |
||||
|
||||
如下代码定义[基础应用模板](start-installation.md)使用的主要资源包： |
||||
|
||||
```php |
||||
<?php |
||||
|
||||
namespace app\assets; |
||||
|
||||
use yii\web\AssetBundle; |
||||
|
||||
class AppAsset extends AssetBundle |
||||
{ |
||||
public $basePath = '@webroot'; |
||||
public $baseUrl = '@web'; |
||||
public $css = [ |
||||
'css/site.css', |
||||
]; |
||||
public $js = [ |
||||
]; |
||||
public $depends = [ |
||||
'yii\web\YiiAsset', |
||||
'yii\bootstrap\BootstrapAsset', |
||||
]; |
||||
} |
||||
``` |
||||
|
||||
如上`AppAsset` 类指定资源文件放在 `@webroot` 目录下，对应的URL为 |
||||
`@web`，资源包中包含一个CSS文件 `css/site.css`，没有JavaScript文件， |
||||
依赖其他两个包 [[yii\web\YiiAsset]] 和 [[yii\bootstrap\BootstrapAsset]]， |
||||
关于[[yii\web\AssetBundle]] 的属性的更多详细如下所述： |
||||
|
||||
* [[yii\web\AssetBundle::sourcePath|sourcePath]]: 指定包包含资源文件的根目录， |
||||
当根目录不能被Web访问时该属性应设置，否则，应设置 |
||||
[[yii\web\AssetBundle::basePath|basePath]] 属性和[[yii\web\AssetBundle::baseUrl|baseUrl]]。 |
||||
[路径别名](concept-aliases.md) 可在此处使用； |
||||
* [[yii\web\AssetBundle::basePath|basePath]]: 指定包含资源包中资源文件并可Web访问的目录， |
||||
当指定[[yii\web\AssetBundle::sourcePath|sourcePath]] 属性， |
||||
[资源管理器](#asset-manager) 会发布包的资源到一个可Web访问并覆盖该属性， |
||||
如果你的资源文件在一个Web可访问目录下，应设置该属性，这样就不用再发布了。 |
||||
[路径别名](concept-aliases.md) 可在此处使用。 |
||||
* [[yii\web\AssetBundle::baseUrl|baseUrl]]: 指定对应到[[yii\web\AssetBundle::basePath|basePath]]目录的URL， |
||||
和 [[yii\web\AssetBundle::basePath|basePath]] 类似，如果你指定 [[yii\web\AssetBundle::sourcePath|sourcePath]] 属性， |
||||
[资源管理器](#asset-manager) 会发布这些资源并覆盖该属性，[路径别名](concept-aliases.md) 可在此处使用。 |
||||
* [[yii\web\AssetBundle::js|js]]: 一个包含该资源包JavaScript文件的数组，注意正斜杠"/"应作为目录分隔符， |
||||
每个JavaScript文件可指定为以下两种格式之一： |
||||
- 相对路径表示为本地JavaScript文件 (如 `js/main.js`)，文件实际的路径在该相对路径前加上 |
||||
[[yii\web\AssetManager::basePath]]，文件实际的URL在该路径前加上[[yii\web\AssetManager::baseUrl]]。 |
||||
- 绝对URL地址表示为外部JavaScript文件，如 |
||||
`http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js` 或 |
||||
`//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js`. |
||||
* [[yii\web\AssetBundle::css|css]]: 一个包含该资源包JavaScript文件的数组，该数组格式和 [[yii\web\AssetBundle::js|js]] 相同。 |
||||
* [[yii\web\AssetBundle::depends|depends]]: 一个列出该资源包依赖的其他资源包（后两节有详细介绍）。 |
||||
* [[yii\web\AssetBundle::jsOptions|jsOptions]]: 当调用[[yii\web\View::registerJsFile()]]注册该包 *每个* JavaScript文件时， |
||||
指定传递到该方法的选项。 |
||||
* [[yii\web\AssetBundle::cssOptions|cssOptions]]: 当调用[[yii\web\View::registerCssFile()]]注册该包 *每个* css文件时， |
||||
指定传递到该方法的选项。 |
||||
* [[yii\web\AssetBundle::publishOptions|publishOptions]]: 当调用[[yii\web\AssetManager::publish()]]发布该包资源文件到Web目录时 |
||||
指定传递到该方法的选项，仅在指定了[[yii\web\AssetBundle::sourcePath|sourcePath]]属性时使用。 |
||||
|
||||
|
||||
### 资源位置 <a name="asset-locations"></a> |
||||
|
||||
资源根据它们的位置可以分为： |
||||
|
||||
* 源资源: 资源文件和PHP源代码放在一起，不能被Web直接访问，为了使用这些源资源，它们要拷贝到一个可Web访问的Web目录中 |
||||
成为发布的资源，这个过程称为*发布资源*，随后会详细介绍。 |
||||
* 发布资源: 资源文件放在可通过Web直接访问的Web目录中； |
||||
* 外部资源: 资源文件放在你的Web应用不同的Web服务器上； |
||||
|
||||
当定义资源包类时候，如果你指定了[[yii\web\AssetBundle::sourcePath|sourcePath]] 属性，就表示任何使用相对路径的资源会被 |
||||
当作源资源；如果没有指定该属性，就表示这些资源为发布资源（因此应指定[[yii\web\AssetBundle::basePath|basePath]] 和 |
||||
[[yii\web\AssetBundle::baseUrl|baseUrl]] 让Yii知道它们的位置）。 |
||||
|
||||
推荐将资源文件放到Web目录以避免不必要的发布资源过程，这就是之前的例子指定 |
||||
[[yii\web\AssetBundle::basePath|basePath]] 而不是 [[yii\web\AssetBundle::sourcePath|sourcePath]]. |
||||
|
||||
对于 [扩展](structure-extensions.md)来说，由于它们的资源和源代码都在不能Web访问的目录下， |
||||
在定义资源包类时必须指定[[yii\web\AssetBundle::sourcePath|sourcePath]]属性。 |
||||
|
||||
> 注意: [[yii\web\AssetBundle::sourcePath|source path]] 属性不要用`@webroot/assets`，该路径默认为 |
||||
[[yii\web\AssetManager|asset manager]]资源管理器将源资源发布后存储资源的路径，该路径的所有内容会认为是临时文件， |
||||
可能会被删除。 |
||||
|
||||
|
||||
### 资源依赖 <a name="asset-dependencies"></a> |
||||
|
||||
当Web页面包含多个CSS或JavaScript文件时，它们有一定的先后顺序以避免属性覆盖， |
||||
例如，Web页面在使用jQuery UI小部件前必须确保jQuery JavaScript文件已经被包含了， |
||||
我们称这种资源先后次序称为资源依赖。 |
||||
|
||||
资源依赖主要通过[[yii\web\AssetBundle::depends]] 属性来指定， |
||||
在`AppAsset` 示例中，资源包依赖其他两个资源包： [[yii\web\YiiAsset]] 和 [[yii\bootstrap\BootstrapAsset]] |
||||
也就是该资源包的CSS和JavaScript文件要在这两个依赖包的文件包含 *之后* 才包含。 |
||||
|
||||
资源依赖关系是可传递，也就是人说A依赖B，B依赖C，那么A也依赖C。 |
||||
|
||||
|
||||
### 资源选项 <a name="asset-options"></a> |
||||
|
||||
可指定[[yii\web\AssetBundle::cssOptions|cssOptions]] 和 [[yii\web\AssetBundle::jsOptions|jsOptions]] |
||||
属性来自定义页面包含CSS和JavaScript文件的方式， |
||||
这些属性值会分别传递给 [[yii\web\View::registerCssFile()]] 和 [[yii\web\View::registerJsFile()]] 方法， |
||||
在[视图](structure-views.md) 调用这些方法包含CSS和JavaScript文件时。 |
||||
|
||||
> 注意: 在资源包类中设置的选项会应用到该包中 *每个* CSS/JavaScript 文件，如果想对每个文件使用不同的选项， |
||||
应创建不同的资源包并在每个包中使用一个选项集。 |
||||
|
||||
例如，只想IE9或更高的浏览器包含一个CSS文件，可以使用如下选项： |
||||
|
||||
```php |
||||
public $cssOptions = ['condition' => 'lte IE9']; |
||||
``` |
||||
|
||||
这会是包中的CSS文件使用以下HTML标签包含进来： |
||||
|
||||
```html |
||||
<!--[if lte IE9]> |
||||
<link rel="stylesheet" href="path/to/foo.css"> |
||||
<![endif]--> |
||||
``` |
||||
|
||||
为链接标签包含`<noscript>`可使用如下代码： |
||||
|
||||
```php |
||||
public $cssOptions = ['noscript' => true]; |
||||
``` |
||||
|
||||
为使JavaScript文件包含在页面head区域（JavaScript文件默认包含在body的结束处）使用以下选项： |
||||
|
||||
```php |
||||
public $jsOptions = ['position' => \yii\web\View::POS_HEAD]; |
||||
``` |
||||
|
||||
|
||||
### Bower 和 NPM 资源 <a name="bower-npm-assets"></a> |
||||
|
||||
大多数 JavaScript/CSS 包通过[Bower](http://bower.io/) 和/或 [NPM](https://www.npmjs.org/)管理， |
||||
如果你的应用或扩展使用这些包，推荐你遵循以下步骤来管理库中的资源： |
||||
|
||||
1. 修改应用或扩展的 `composer.json` 文件将包列入`require` 中， |
||||
应使用`bower-asset/PackageName` (Bower包) 或 `npm-asset/PackageName` (NPM包)来对应库。 |
||||
2. 创建一个资源包类并将你的应用或扩展要使用的JavaScript/CSS 文件列入到类中， |
||||
应设置 [[yii\web\AssetBundle::sourcePath|sourcePath]] 属性为`@bower/PackageName` 或 `@npm/PackageName`， |
||||
因为根据别名Composer会安装Bower或NPM包到对应的目录下。 |
||||
|
||||
> 注意: 一些包会将它们分布式文件放到一个子目录中，对于这种情况，应指定子目录作为 |
||||
[[yii\web\AssetBundle::sourcePath|sourcePath]]属性值，例如，[[yii\web\JqueryAsset]]使用 `@bower/jquery/dist` 而不是 `@bower/jquery`。 |
||||
|
||||
|
||||
## 使用资源包 <a name="using-asset-bundles"></a> |
||||
|
||||
为使用资源包，在[视图](structure-views.md)中调用[[yii\web\AssetBundle::register()]]方法先注册资源， |
||||
例如，在视图模板可使用如下代码注册资源包： |
||||
|
||||
```php |
||||
use app\assets\AppAsset; |
||||
AppAsset::register($this); // $this 代表视图对象 |
||||
``` |
||||
|
||||
如果在其他地方注册资源包，应提供视图对象，如在 [小部件](structure-widgets.md) 类中注册资源包， |
||||
可以通过 `$this->view` 获取视图对象。 |
||||
|
||||
当在视图中注册一个资源包时，在背后Yii会注册它所依赖的资源包，如果资源包是放在Web不可访问的目录下，会被发布到可访问的目录， |
||||
后续当视图渲染页面时，会生成这些注册包包含的CSS和JavaScript文件对应的`<link>` 和 `<script>` 标签， |
||||
这些标签的先后顺序取决于资源包的依赖关系以及在 [[yii\web\AssetBundle::css]]和[[yii\web\AssetBundle::js]] 的列出来的前后顺序。 |
||||
|
||||
|
||||
### 自定义资源包 <a name="customizing-asset-bundles"></a> |
||||
|
||||
Yii通过名为 `assetManager`的应用组件实现[[yii\web\AssetManager] 来管理应用组件， |
||||
通过配置[[yii\web\AssetManager::bundles]] 属性，可以自定义资源包的行为， |
||||
例如，[[yii\web\JqueryAsset]] 资源包默认从jquery Bower包中使用`jquery.js` 文件， |
||||
为了提高可用性和性能，你可能需要从Google服务器上获取jquery文件，可以在应用配置中配置`assetManager`，如下所示： |
||||
|
||||
```php |
||||
return [ |
||||
// ... |
||||
'components' => [ |
||||
'assetManager' => [ |
||||
'bundles' => [ |
||||
'yii\web\JqueryAsset' => [ |
||||
'sourcePath' => null, // 一定不要发布该资源 |
||||
'js' => [ |
||||
'//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js', |
||||
] |
||||
], |
||||
], |
||||
], |
||||
], |
||||
]; |
||||
``` |
||||
|
||||
可通过类似[[yii\web\AssetManager::bundles]]配置多个资源包，数组的键应为资源包的类名（最开头不要反斜杠）， |
||||
数组的值为对应的[配置数组](concept-configurations.md). |
||||
|
||||
> 提示: 可以根据条件判断使用哪个资源，如下示例为如何在开发环境用`jquery.js`，否则用`jquery.min.js`： |
||||
> |
||||
> ```php |
||||
> 'yii\web\JqueryAsset' => [ |
||||
> 'js' => [ |
||||
> YII_ENV_DEV ? 'jquery.js' : 'jquery.min.js' |
||||
> ] |
||||
> ], |
||||
> ``` |
||||
|
||||
可以设置资源包的名称对应`false`来禁用想禁用的一个或多个资源包，当视图中注册一个禁用资源包， |
||||
视图不会包含任何该包的资源以及不会注册它所依赖的包，例如，为禁用[[yii\web\JqueryAsset]]，可以使用如下配置： |
||||
|
||||
```php |
||||
return [ |
||||
// ... |
||||
'components' => [ |
||||
'assetManager' => [ |
||||
'bundles' => [ |
||||
'yii\web\JqueryAsset' => false, |
||||
], |
||||
], |
||||
], |
||||
]; |
||||
``` |
||||
|
||||
可设置[[yii\web\AssetManager::bundles]]为`false`禁用 *所有* 的资源包。 |
||||
|
||||
|
||||
### 资源部署 <a name="asset-mapping"></a> |
||||
|
||||
有时你想"修复" 多个资源包中资源文件的错误/不兼容，例如包A使用1.11.1版本的`jquery.min.js`， |
||||
包B使用2.1.1版本的`jquery.js`，可自定义每个包来解决这个问题，更好的方式是使用*资源部署*特性来不熟不正确的资源为想要的， |
||||
为此，配置[[yii\web\AssetManager::assetMap]]属性，如下所示： |
||||
|
||||
```php |
||||
return [ |
||||
// ... |
||||
'components' => [ |
||||
'assetManager' => [ |
||||
'assetMap' => [ |
||||
'jquery.js' => '//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js', |
||||
], |
||||
], |
||||
], |
||||
]; |
||||
``` |
||||
|
||||
[[yii\web\AssetManager::assetMap|assetMap]]的键为你想要修复的资源名，值为你想要使用的资源路径， |
||||
当视图注册资源包，在[[yii\web\AssetBundle::css|css]] 和 [[yii\web\AssetBundle::js|js]] 数组中每个相关资源文件会和该部署进行对比， |
||||
如果数组任何键对比为资源文件的最后文件名（如果有的话前缀为 [[yii\web\AssetBundle::sourcePath]]），对应的值为替换原来的资源。 |
||||
例如，资源文件`my/path/to/jquery.js` 匹配键 `jquery.js`. |
||||
|
||||
> 注意: 只有相对相对路径指定的资源对应到资源部署，替换的资源路径可以为绝对路径，也可为和[[yii\web\AssetManager::basePath]]相关的路径。 |
||||
|
||||
|
||||
### 资源发布 <a name="asset-publishing"></a> |
||||
|
||||
如前所述，如果资源包放在Web不能访问的目录，当视图注册资源时资源会被拷贝到一个Web可访问的目录中， |
||||
这个过程称为*资源发布*，[[yii\web\AssetManager|asset manager]]会自动处理该过程。 |
||||
|
||||
资源默认会发布到`@webroot/assets`目录，对应的URL为`@web/assets`， |
||||
可配置[[yii\web\AssetManager::basePath|basePath]] 和 [[yii\web\AssetManager::baseUrl|baseUrl]] 属性自定义发布位置。 |
||||
|
||||
除了拷贝文件方式发布资源，如果操作系统和Web服务器允许可以使用符号链接，该功能可以通过设置 |
||||
[[yii\web\AssetManager::linkAssets|linkAssets]] 为 true 来启用。 |
||||
|
||||
```php |
||||
return [ |
||||
// ... |
||||
'components' => [ |
||||
'assetManager' => [ |
||||
'linkAssets' => true, |
||||
], |
||||
], |
||||
]; |
||||
``` |
||||
|
||||
使用以上配置，资源管理器会创建一个符号链接到要发布的资源包源路径，这比拷贝文件方式快并能确保发布的资源一直为最新的。 |
||||
|
||||
|
||||
## 常用资源包 <a name="common-asset-bundles"></a> |
||||
|
||||
Yii框架定义许多资源包，如下资源包是最常用，可在你的应用或扩展代码中引用它们。 |
||||
|
||||
- [[yii\web\YiiAsset]]: 主要包含`yii.js` 文件，该文件完成模块JavaScript代码组织功能， |
||||
也为 `data-method` 和 `data-confirm`属性提供特别支持和其他有用的功能。 |
||||
- [[yii\web\JqueryAsset]]: 包含从jQuery bower 包的`jquery.js`文件。 |
||||
- [[yii\bootstrap\BootstrapAsset]]: 包含从Twitter Bootstrap 框架的CSS文件。 |
||||
- [[yii\bootstrap\BootstrapPluginAsset]]: 包含从Twitter Bootstrap 框架的JavaScript 文件来支持Bootstrap JavaScript插件。 |
||||
- [[yii\jui\JuiAsset]]: 包含从jQuery UI库的CSS 和 JavaScript 文件。 |
||||
|
||||
如果你的代码需要jQuery, jQuery UI 或 Bootstrap，应尽量使用这些预定义资源包而非自己创建， |
||||
如果这些包的默认配置不能满足你的需求，可以自定义配置，详情参考[自定义资源包](#customizing-asset-bundles)。 |
||||
|
||||
|
||||
## 资源转换 <a name="asset-conversion"></a> |
||||
|
||||
除了直接编写CSS 和/或 JavaScript代码，开发人员经常使用扩展语法来编写，再使用特殊的工具将它们转换成CSS/Javascript。 |
||||
例如，对于CSS代码可使用[LESS](http://lesscss.org/) 或 [SCSS](http://sass-lang.com/)， |
||||
对于JavaScript 可使用 [TypeScript](http://www.typescriptlang.org/)。 |
||||
|
||||
可将使用扩展语法的资源文件列到资源包的[[yii\web\AssetBundle::css|css]] 和 [[yii\web\AssetBundle::js|js]]中，如下所示： |
||||
|
||||
```php |
||||
class AppAsset extends AssetBundle |
||||
{ |
||||
public $basePath = '@webroot'; |
||||
public $baseUrl = '@web'; |
||||
public $css = [ |
||||
'css/site.less', |
||||
]; |
||||
public $js = [ |
||||
'js/site.ts', |
||||
]; |
||||
public $depends = [ |
||||
'yii\web\YiiAsset', |
||||
'yii\bootstrap\BootstrapAsset', |
||||
]; |
||||
} |
||||
``` |
||||
|
||||
当在视图中注册一个这样的资源包，[[yii\web\AssetManager|asset manager]]资源管理器会自动运行预处理工具将使用扩展语法 |
||||
的资源转换成CSS/JavaScript，当视图最终渲染页面时，在页面中包含的是CSS/Javascipt文件，而不是原始的扩展语法代码文件。 |
||||
|
||||
Yii使用文件扩展名来表示资源使用哪种扩展语法，默认可以识别如下语法和文件扩展名： |
||||
|
||||
- [LESS](http://lesscss.org/): `.less` |
||||
- [SCSS](http://sass-lang.com/): `.scss` |
||||
- [Stylus](http://learnboost.github.io/stylus/): `.styl` |
||||
- [CoffeeScript](http://coffeescript.org/): `.coffee` |
||||
- [TypeScript](http://www.typescriptlang.org/): `.ts` |
||||
|
||||
Yii依靠安装的预处理公斤来转换资源，例如，为使用[LESS](http://lesscss.org/)，应安装`lessc` 预处理命令。 |
||||
|
||||
可配置[[yii\web\AssetManager::converter]]自定义预处理命令和支持的扩展语法，如下所示： |
||||
|
||||
```php |
||||
return [ |
||||
'components' => [ |
||||
'assetManager' => [ |
||||
'converter' => [ |
||||
'class' => 'yii\web\AssetConverter', |
||||
'commands' => [ |
||||
'less' => ['css', 'lessc {from} {to} --no-color'], |
||||
'ts' => ['js', 'tsc --out {to} {from}'], |
||||
], |
||||
], |
||||
], |
||||
], |
||||
]; |
||||
``` |
||||
|
||||
如上所示，通过[[yii\web\AssetConverter::commands]] 属性指定支持的扩展语法， |
||||
数组的键为文件扩展名（前面不要.），数组的值为目标资源文件扩展名和执行资源转换的命令， |
||||
命令中的标记 `{from}` 和`{to}`会分别被源资源文件路径和目标资源文件路径替代。 |
||||
|
||||
> 补充: 除了以上方式，也有其他的方式来处理扩展语法资源，例如，可使用编译工具如[grunt](http://gruntjs.com/) |
||||
来监控并自动转换扩展语法资源，此时，应使用资源包中编译后的CSS/Javascript文件而不是原始文件。 |
||||
|
||||
|
||||
## 合并和压缩资源 <a name="combining-compressing-assets"></a> |
||||
|
||||
一个Web页面可以包含很多CSS 和/或 JavaScript 文件，为减少HTTP 请求和这些下载文件的大小， |
||||
通常的方式是在页面中合并并压缩多个CSS/JavaScript 文件为一个或很少的几个文件，并使用压缩后的文件而不是原始文件。 |
||||
|
||||
> 补充: 合并和压缩资源通常在应用在产品上线模式，在开发模式下使用原始的CSS/JavaScript更方便调试。 |
||||
|
||||
接下来介绍一种合并和压缩资源文件而不需要修改已有代码的方式： |
||||
|
||||
1. 找出应用中所有你想要合并和压缩的资源包， |
||||
2. 将这些包分成一个或几个组，注意每个包只能属于其中一个组， |
||||
3. 合并/压缩每个组里CSS文件到一个文件，同样方式处理JavaScript文件， |
||||
4. 为每个组定义新的资源包： |
||||
* 设置[[yii\web\AssetBundle::css|css]] 和 [[yii\web\AssetBundle::js|js]] 属性分别为压缩后的CSS和JavaScript文件； |
||||
* 自定义设置每个组内的资源包，设置资源包的[[yii\web\AssetBundle::css|css]] 和 [[yii\web\AssetBundle::js|js]] 属性为空, |
||||
并设置它们的 [[yii\web\AssetBundle::depends|depends]] 属性为每个组新创建的资源包。 |
||||
|
||||
使用这种方式，当在视图中注册资源包时，会自动触发原始包所属的组资源包的注册，然后，页面就会包含以合并/压缩的资源文件， |
||||
而不是原始文件。 |
||||
|
||||
|
||||
### 示例 <a name="example"></a> |
||||
|
||||
使用一个示例来解释以上这种方式： |
||||
|
||||
鉴定你的应用有两个页面X 和 Y，页面X使用资源包A，B和C，页面Y使用资源包B，C和D。 |
||||
|
||||
有两种方式划分这些资源包，一种使用一个组包含所有资源包，另一种是将（A,B,C）放在组X，（B，C，C）放在组Y， |
||||
哪种方式更好？第一种方式优点是两个页面使用相同的已合并CSS和JavaScript文件使HTTP缓存更高效，另一方面，由于单个组包含所有文件， |
||||
已合并的CSS和Javascipt文件会更大，因此会增加文件传输时间，在这个示例中，我们使用第一种方式，也就是用一个组包含所有包。 |
||||
|
||||
> 补充: 将资源包分组并不是无价值的，通常要求分析现实中不同页面各种资源的数据量，开始时为简便使用一个组。 |
||||
|
||||
在所有包中使用工具(例如 [Closure Compiler](https://developers.google.com/closure/compiler/), |
||||
[YUI Compressor](https://github.com/yui/yuicompressor/)) 来合并和压缩CSS和JavaScript文件， |
||||
注意合并后的文件满足包间的先后依赖关系，例如，如果包A依赖B，B依赖C和D，那么资源文件列表以C和D开始，然后为B最后为A。 |
||||
|
||||
合并和压缩之后，会得到一个CSS文件和一个JavaScript文件，假定它们的名称为`all-xyz.css` 和 `all-xyz.js`， |
||||
`xyz` 为使文件名唯一以避免HTTP缓存问题的时间戳或哈希值。 |
||||
|
||||
现在到最后一步了，在应用配置中配置[[yii\web\AssetManager|asset manager]] 资源管理器如下所示： |
||||
|
||||
```php |
||||
return [ |
||||
'components' => [ |
||||
'assetManager' => [ |
||||
'bundles' => [ |
||||
'all' => [ |
||||
'class' => 'yii\web\AssetBundle', |
||||
'basePath' => '@webroot/assets', |
||||
'baseUrl' => '@web/assets', |
||||
'css' => ['all-xyz.css'], |
||||
'js' => ['all-xyz.js'], |
||||
], |
||||
'A' => ['css' => [], 'js' => [], 'depends' => ['all']], |
||||
'B' => ['css' => [], 'js' => [], 'depends' => ['all']], |
||||
'C' => ['css' => [], 'js' => [], 'depends' => ['all']], |
||||
'D' => ['css' => [], 'js' => [], 'depends' => ['all']], |
||||
], |
||||
], |
||||
], |
||||
]; |
||||
``` |
||||
|
||||
如[自定义资源包](#customizing-asset-bundles) 小节中所述，如上配置改变每个包的默认行为， |
||||
特别是包A、B、C和D不再包含任何资源文件，都依赖包含合并后的`all-xyz.css` 和 `all-xyz.js`文件的包`all`， |
||||
因此，对于页面X会包含这两个合并后的文件而不是包A、B、C的原始文件，对于页面Y也是如此。 |
||||
|
||||
最后有个方法更好地处理上述方式，除了直接修改应用配置文件，可将自定义包数组放到一个文件，在应用配置中根据条件包含该文件，例如： |
||||
|
||||
```php |
||||
return [ |
||||
'components' => [ |
||||
'assetManager' => [ |
||||
'bundles' => require(__DIR__ . '/' . (YII_ENV_PROD ? 'assets-prod.php' : 'assets-dev.php')), |
||||
], |
||||
], |
||||
]; |
||||
``` |
||||
|
||||
如上所示，在产品上线模式下资源包数组存储在`assets-prod.php`文件中，不是产品上线模式存储在`assets-dev.php`文件中。 |
||||
|
||||
|
||||
### 使用 `asset` 命令 <a name="using-asset-command"></a> |
||||
|
||||
Yii提供一个名为`asset`控制台命令来使上述操作自动处理。 |
||||
|
||||
为使用该命令，应先创建一个配置文件设置哪些资源包要合并以及分组方式，可使用`asset/template` 子命令来生成一个模板， |
||||
然后修改模板成你想要的。 |
||||
|
||||
``` |
||||
yii asset/template assets.php |
||||
``` |
||||
|
||||
该命令在当前目录下生成一个名为`assets.php`的文件，文件的内容类似如下： |
||||
|
||||
```php |
||||
<?php |
||||
/** |
||||
* 为控制台命令"yii asset"使用的配置文件 |
||||
* 注意在控制台环境下，一些路径别名如 '@webroot' 和 '@web' 不会存在 |
||||
* 请定义不存在的路径别名 |
||||
*/ |
||||
return [ |
||||
// 为JavaScript文件压缩修改 command/callback |
||||
'jsCompressor' => 'java -jar compiler.jar --js {from} --js_output_file {to}', |
||||
// 为CSS文件压缩修改command/callback |
||||
'cssCompressor' => 'java -jar yuicompressor.jar --type css {from} -o {to}', |
||||
// 要压缩的资源包列表 |
||||
'bundles' => [ |
||||
// 'yii\web\YiiAsset', |
||||
// 'yii\web\JqueryAsset', |
||||
], |
||||
// 资源包压缩后的输出 |
||||
'targets' => [ |
||||
'all' => [ |
||||
'class' => 'yii\web\AssetBundle', |
||||
'basePath' => '@webroot/assets', |
||||
'baseUrl' => '@web/assets', |
||||
'js' => 'js/all-{hash}.js', |
||||
'css' => 'css/all-{hash}.css', |
||||
], |
||||
], |
||||
// 资源管理器配置: |
||||
'assetManager' => [ |
||||
], |
||||
]; |
||||
``` |
||||
|
||||
应修改该文件的`bundles`的选项指定哪些包你想要合并，在`targets`选项中应指定这些包如何分组，如前述的可以指定一个或多个组。 |
||||
|
||||
> 注意: 由于在控制台应用别名 `@webroot` and `@web` 不可用，应在配置中明确指定它们。 |
||||
|
||||
JavaScript文件会被合并压缩后写入到`js/all-{hash}.js`文件，其中 {hash} 会被结果文件的哈希值替换。 |
||||
|
||||
`jsCompressor` 和 `cssCompressor` 选项指定控制台命令或PHP回调函数来执行JavaScript和CSS合并和压缩， |
||||
Yii默认使用[Closure Compiler](https://developers.google.com/closure/compiler/)来合并JavaScript文件， |
||||
使用[YUI Compressor](https://github.com/yui/yuicompressor/)来合并CSS文件， |
||||
你应手工安装这些工具或修改选项使用你喜欢的工具。 |
||||
|
||||
|
||||
根据配置文件，可执行`asset` 命令来合并和压缩资源文件并生成一个新的资源包配置文件`assets-prod.php`: |
||||
|
||||
``` |
||||
yii asset assets.php config/assets-prod.php |
||||
``` |
||||
|
||||
生成的配置文件可以在应用配置中包含，如最后一小节所描述的。 |
||||
|
||||
|
||||
> 补充: 使用`asset` 命令并不是唯一一种自动合并和压缩过程的方法，可使用优秀的工具[grunt](http://gruntjs.com/)来完成这个过程。 |
||||
@ -0,0 +1,435 @@
|
||||
Extensions |
||||
========== |
||||
|
||||
Extensions are redistributable software packages specifically designed to be used in Yii applications and provide |
||||
ready-to-use features. For example, the [yiisoft/yii2-debug](tool-debugger.md) extension adds a handy debug toolbar |
||||
at the bottom of every page in your application to help you more easily grasp how the pages are generated. You can |
||||
use extensions to accelerate your development process. You can also package your code as extensions to share with |
||||
other people your great work. |
||||
|
||||
> Info: We use the term "extension" to refer to Yii-specific software packages. For general purpose software packages |
||||
that can be used without Yii, we will refer to them using the term "package" or "library". |
||||
|
||||
|
||||
## Using Extensions <a name="using-extensions"></a> |
||||
|
||||
To use an extension, you need to install it first. Most extensions are distributed as [Composer](https://getcomposer.org/) |
||||
packages which can be installed by taking the following two simple steps: |
||||
|
||||
1. modify the `composer.json` file of your application and specify which extensions (Composer packages) you want to install. |
||||
2. run `composer install` to install the specified extensions. |
||||
|
||||
Note that you may need to install [Composer](https://getcomposer.org/) if you do not have it. |
||||
|
||||
By default, Composer installs packages registered on [Packagist](https://packagist.org/) - the biggest repository |
||||
for open source Composer packages. You can look for extensions on Packagist. You may also |
||||
[create your own repository](https://getcomposer.org/doc/05-repositories.md#repository) and configure Composer |
||||
to use it. This is useful if you are developing closed open extensions and want to share within your projects. |
||||
|
||||
Extensions installed by Composer are stored in the `BasePath/vendor` directory, where `BasePath` refers to the |
||||
application's [base path](structure-applications.md#basePath). Because Composer is a dependency manager, when |
||||
it installs a package, it will also install all its dependent packages. |
||||
|
||||
For example, to install the `yiisoft/yii2-imagine` extension, modify your `composer.json` like the following: |
||||
|
||||
```json |
||||
{ |
||||
// ... |
||||
|
||||
"require": { |
||||
// ... other dependencies |
||||
|
||||
"yiisoft/yii2-imagine": "*" |
||||
} |
||||
} |
||||
``` |
||||
|
||||
After the installation, you should see the directory `yiisoft/yii2-imagine` under `BasePath/vendor`. You should |
||||
also see another directory `imagine/imagine` which contains the installed dependent package. |
||||
|
||||
> Info: The `yiisoft/yii2-imagine` is a core extension developed and maintained by the Yii developer team. All |
||||
core extensions are hosted on [Packagist](https://packagist.org/) and named like `yiisoft/yii2-xyz`, where `xyz` |
||||
varies for different extensions. |
||||
|
||||
Now you can use the installed extensions like they are part of your application. The following example shows |
||||
how you can use the `yii\imagine\Image` class provided by the `yiisoft/yii2-imagine` extension: |
||||
|
||||
```php |
||||
use Yii; |
||||
use yii\imagine\Image; |
||||
|
||||
// generate a thumbnail image |
||||
Image::thumbnail('@webroot/img/test-image.jpg', 120, 120) |
||||
->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]); |
||||
``` |
||||
|
||||
> Info: Extension classes are autoloaded by the [Yii class autoloader](concept-autoloading.md). |
||||
|
||||
|
||||
### Installing Extensions Manually <a name="installing-extensions-manually"></a> |
||||
|
||||
In some rare occasions, you may want to install some or all extensions manually, rather than relying on Composer. |
||||
To do so, you should |
||||
|
||||
1. download the extension archive files and unpack them in the `vendor` directory. |
||||
2. install the class autoloaders provided by the extensions, if any. |
||||
3. download and install all dependent extensions as instructed. |
||||
|
||||
If an extension does not have a class autoloader but follows the [PSR-4 standard](http://www.php-fig.org/psr/psr-4/), |
||||
you may use the class autoloader provided by Yii to autoload the extension classes. All you need to do is just to |
||||
declare a [root alias](concept-aliases.md#defining-aliases) for the extension root directory. For example, |
||||
assuming you have installed an extension in the directory `vendor/mycompany/myext`, and the extension classes |
||||
are under the `myext` namespace, then you can include the following code in your application configuration: |
||||
|
||||
```php |
||||
[ |
||||
'aliases' => [ |
||||
'@myext' => '@vendor/mycompany/myext', |
||||
], |
||||
] |
||||
``` |
||||
|
||||
|
||||
## Creating Extensions <a name="creating-extensions"></a> |
||||
|
||||
You may consider creating an extension when you feel the need to share with other people your great code. |
||||
An extension can contain any code you like, such as a helper class, a widget, a module, etc. |
||||
|
||||
It is recommended that you create an extension in terms of a [Composer package](https://getcomposer.org/) so that |
||||
it can be more easily installed and used by other users, liked described in the last subsection. |
||||
|
||||
Below are the basic steps you may follow to create an extension as a Composer package. |
||||
|
||||
1. Create a project for your extension and host it on a VCS repository, such as [github.com](https://github.com). |
||||
The development and maintenance work about the extension should be done on this repository. |
||||
2. Under the root directory of the project, create a file named `composer.json` as required by Composer. Please |
||||
refer to the next subsection for more details. |
||||
3. Register your extension with a Composer repository, such as [Packagist](https://packagist.org/), so that |
||||
other users can find and install your extension using Composer. |
||||
|
||||
|
||||
### `composer.json` <a name="composer-json"></a> |
||||
|
||||
Each Composer package must have a `composer.json` file in its root directory. The file contains the metadata about |
||||
the package. You may find complete specification about this file in the [Composer Manual](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup). |
||||
The following example shows the `composer.json` file for the `yiisoft/yii2-imagine` extension: |
||||
|
||||
```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\\": "" |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
|
||||
#### Package Name <a name="package-name"></a> |
||||
|
||||
Each Composer package should have a package name which uniquely identifies the package among all others. |
||||
The format of package names is `vendorName/projectName`. For example, in the package name `yiisoft/yii2-imagine`, |
||||
the vendor name and the project name are `yiisoft` and `yii2-imagine`, respectively. |
||||
|
||||
Do NOT use `yiisoft` as vendor name as it is reserved for use by the Yii core code. |
||||
|
||||
We recommend you prefix `yii2-` to the project name for packages representing Yii 2 extensions, for example, |
||||
`myname/yii2-mywidget`. This will allow users to more easily tell whether a package is a Yii 2 extension. |
||||
|
||||
|
||||
#### Package Type <a name="package-type"></a> |
||||
|
||||
It is important that you specify the package type of your extension as `yii2-extension` so that the package can |
||||
be recognized as a Yii extension when being installed. |
||||
|
||||
When a user runs `composer install` to install an extension, the file `vendor/yiisoft/extensions.php` |
||||
will be automatically updated to include the information about the new extension. From this file, Yii applications |
||||
can know which extensions are installed (the information can be accessed via [[yii\base\Application::extensions]]. |
||||
|
||||
|
||||
#### Dependencies <a name="dependencies"></a> |
||||
|
||||
Your extension depends on Yii (of course). So you should list it (`yiisoft/yii2`) in the `require` entry in `composer.json`. |
||||
If your extension also depends on other extensions or third-party libraries, you should list them as well. |
||||
Make sure you also list appropriate version constraints (e.g. `1.*`, `@stable`) for each dependent package. Use stable |
||||
dependencies when your extension is released in a stable version. |
||||
|
||||
Most JavaScript/CSS packages are managed using [Bower](http://bower.io/) and/or [NPM](https://www.npmjs.org/), |
||||
instead of Composer. Yii uses the [Composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin) |
||||
to enable managing these kinds of packages through Composer. If your extension depends on a Bower package, you can |
||||
simply list the dependency in `composer.json` like the following: |
||||
|
||||
```json |
||||
{ |
||||
// package dependencies |
||||
"require": { |
||||
"bower-asset/jquery": ">=1.11.*" |
||||
} |
||||
} |
||||
``` |
||||
|
||||
The above code states that the extension depends on the `jquery` Bower package. In general, you can use |
||||
`bower-asset/PackageName` to refer to a Bower package in `composer.json`, and use `npm-asset/PackageName` |
||||
to refer to a NPM package. When Composer installs a Bower or NPM package, by default the package content will be |
||||
installed under the `@vendor/bower/PackageName` and `@vendor/npm/Packages` directories, respectively. |
||||
These two directories can also be referred to using the shorter aliases `@bower/PackageName` and `@npm/PackageName`. |
||||
|
||||
For more details about asset management, please refer to the [Assets](structure-assets.md#bower-npm-assets) section. |
||||
|
||||
|
||||
#### Class Autoloading <a name="class-autoloading"></a> |
||||
|
||||
In order for your classes to be autoloaded by the Yii class autoloader or the Composer class autoloader, |
||||
you should specify the `autoload` entry in the `composer.json` file, like shown below: |
||||
|
||||
```json |
||||
{ |
||||
// .... |
||||
|
||||
"autoload": { |
||||
"psr-4": { |
||||
"yii\\imagine\\": "" |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
You may list one or multiple root namespaces and their corresponding file paths. |
||||
|
||||
When the extension is installed in an application, Yii will create for each listed root namespace |
||||
an [alias](concept-aliases.md#extension-aliases) that refers to the directory corresponding to the namespace. |
||||
For example, the above `autoload` declaration will correspond to an alias named `@yii/imagine`. |
||||
|
||||
|
||||
### Recommended Practices <a name="recommended-practices"></a> |
||||
|
||||
Because extensions are meant to be used by other people, you often need to take extra development effort. Below |
||||
we introduce some common and recommended practices in creating high quality extensions. |
||||
|
||||
|
||||
#### Namespaces <a name="namespaces"></a> |
||||
|
||||
To avoid name collisions and make the classes in your extension autoloadable, you should use namespaces and |
||||
name the classes in your extension by following the [PSR-4 standard](http://www.php-fig.org/psr/psr-4/) or |
||||
[PSR-0 standard](http://www.php-fig.org/psr/psr-0/). |
||||
|
||||
You class namespaces should start with `vendorName\extensionName`, where `extensionName` is similar to the project name |
||||
in the package name except that it should not contain the `yii2-` prefix. For example, for the `yiisoft/yii2-imagine` |
||||
extension, we use `yii\imagine` as the namespace its classes. |
||||
|
||||
Do not use `yii`, `yii2` or `yiisoft` as vendor name. These names are reserved for use by the Yii core code. |
||||
|
||||
|
||||
#### Bootstrapping Classes <a name="bootstrapping-classes"></a> |
||||
|
||||
Sometimes, you may want your extension to execute some code during the [bootstrapping process](runtime-bootstrapping.md) |
||||
stage of an application. For example, your extension may want to respond to the application's `beginRequest` event |
||||
to adjust some environment settings. While you can instruct users of the extension to explicitly attach your event |
||||
handler in the extension to the `beginRequest` event, a better way is to do this automatically. |
||||
|
||||
To achieve this goal, you can create a so-called *bootstrapping class* by implementing [[yii\base\BootstrapInterface]]. |
||||
For example, |
||||
|
||||
```php |
||||
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 |
||||
}); |
||||
} |
||||
} |
||||
``` |
||||
|
||||
You then list this class in the `composer.json` file of your extension like follows, |
||||
|
||||
```json |
||||
{ |
||||
// ... |
||||
|
||||
"extra": { |
||||
"bootstrap": "myname\\mywidget\\MyBootstrapClass" |
||||
} |
||||
} |
||||
``` |
||||
|
||||
When the extension is installed in an application, Yii will automatically instantiate the bootstrapping class |
||||
and call its [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] method during the bootstrapping process for |
||||
every request. |
||||
|
||||
|
||||
#### Working with Databases <a name="working-with-databases"></a> |
||||
|
||||
Your extension may need to access databases. Do not assume that the applications that use your extension will always |
||||
use `Yii::$db` as the DB connection. Instead, you should declare a `db` property for the classes that require DB access. |
||||
The property will allow users of your extension to customize which DB connection they would like your extension to use. |
||||
As an example, you may refer to the [[yii\caching\DbCache]] class and see how it declares and uses the `db` property. |
||||
|
||||
If your extension needs to create specific DB tables or make changes to DB schema, you should |
||||
|
||||
- provide [migrations](db-migrations.md) to manipulate DB schema, rather than using plain SQL files; |
||||
- try to make the migrations applicable to different DBMS; |
||||
- avoid using [Active Record](db-active-record.md) in the migrations. |
||||
|
||||
|
||||
#### Using Assets <a name="using-assets"></a> |
||||
|
||||
If your extension is a widget or a module, chances are that it may require some [assets](structure-assets.md) to work. |
||||
For example, a module may display some pages which contain images, JavaScript, and CSS. Because the files of an |
||||
extension are all under the same directory which is not Web accessible when installed in an application, you have |
||||
two choices to make the asset files directly accessible via Web: |
||||
|
||||
- ask users of the extension to manually copy the asset files to a specific Web-accessible folder; |
||||
- declare an [asset bundle](structure-assets.md) and rely on the asset publishing mechanism to automatically |
||||
copy the files listed in the asset bundle to a Web-accessible folder. |
||||
|
||||
We recommend you use the second approach so that your extension can be more easily used by other people. |
||||
Please refer to the [Assets](structure-assets.md) section for more details about how to work with assets in general. |
||||
|
||||
|
||||
#### Internationalization and Localization <a name="i18n-l10n"></a> |
||||
|
||||
Your extension may be used by applications supporting different languages! Therefore, if your extension displays |
||||
content to end users, you should try to [internationalize and localize](tutorial-i18n.md) it. In particular, |
||||
|
||||
- If the extension displays messages intended for end users, the messages should be wrapped into `Yii::t()` |
||||
so that they can be translated. Messages meant for developers (such as internal exception messages) do not need |
||||
to be translated. |
||||
- If the extension displays numbers, dates, etc., they should be formatted using [[yii\i18n\Formatter]] with |
||||
appropriate formatting rules. |
||||
|
||||
For more details, please refer to the [Internationalization](tutorial-i18n.md) section. |
||||
|
||||
|
||||
#### Testing <a name="testing"></a> |
||||
|
||||
You want your extension to run flawlessly without bringing problems to other people. To reach this goal, you should |
||||
test your extension before releasing it to public. |
||||
|
||||
It is recommended that you create various test cases to cover your extension code rather than relying on manual tests. |
||||
Each time before you release a new version of your extension, you may simply run these test cases to make sure |
||||
everything is in good shape. Yii provides testing support, which can help you to more easily write unit tests, |
||||
acceptance tests and functionality tests. For more details, please refer to the [Testing](test-overview.md) section. |
||||
|
||||
|
||||
#### Versioning <a name="versioning"></a> |
||||
|
||||
You should give each release of your extension a version number (e.g. `1.0.1`). We recommend you follow the |
||||
[semantic versioning](http://semver.org) practice when determining what version numbers should be used. |
||||
|
||||
|
||||
#### Releasing <a name="releasing"></a> |
||||
|
||||
To let other people know your extension, you need to release it to public. |
||||
|
||||
If it is the first time you release an extension, you should register it on a Composer repository, such as |
||||
[Packagist](https://packagist.org/). After that, all you need to do is simply creating a release tag (e.g. `v1.0.1`) |
||||
on the VCS repository of your extension and notify the Composer repository about the new release. People will |
||||
then be able to find the new release, and install or update the extension through the Composer repository. |
||||
|
||||
In the releases of your extension, besides code files you should also consider including the followings to |
||||
help other people learn about and use your extension: |
||||
|
||||
* A readme file in the package root directory: it describes what your extension does and how to install and use it. |
||||
We recommend you write it in [Markdown](http://daringfireball.net/projects/markdown/) format and name the file |
||||
as `readme.md`. |
||||
* A changelog file in the package root directory: it lists what changes are made in each release. The file |
||||
may be written in Markdown format and named as `changelog.md`. |
||||
* An upgrade file in the package root directory: it gives the instructions on how to upgrade from older releases |
||||
of the extension. The file may be written in Markdown format and named as `upgrade.md`. |
||||
* Tutorials, demos, screenshots, etc.: these are needed if your extension provides many features that cannot be |
||||
fully covered in the readme file. |
||||
* API documentation: your code should be well documented to allow other people more easily read and understand it. |
||||
You may refer to the [Object class file](https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php) |
||||
to learn how to document your code. |
||||
|
||||
> Info: Your code comments can be written in Markdown format. The `yiisoft/yii2-apidoc` extension provides a tool |
||||
for you to generate pretty API documentation based on your code comments. |
||||
|
||||
> Info: While not a requirement, we suggest your extension adhere to certain coding styles. You may refer to |
||||
the [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style). |
||||
|
||||
|
||||
## Core Extensions <a name="core-extensions"></a> |
||||
|
||||
Yii provides the following core extensions that are developed and maintained by the Yii developer team. They are all |
||||
registered on [Packagist](https://packagist.org/) and can be easily installed as described in the |
||||
[Using Extensions](#using-extensions) subsection. |
||||
|
||||
- [yiisoft/yii2-apidoc](https://github.com/yiisoft/yii2-apidoc): |
||||
provides an extensible and high-performance API documentation generator. It is also used to generate the core |
||||
framework API documentation. |
||||
- [yiisoft/yii2-authclient](https://github.com/yiisoft/yii2-authclient): |
||||
provides a set of commonly used auth clients, such as Facebook OAuth2 client, GitHub OAuth2 client. |
||||
- [yiisoft/yii2-bootstrap](https://github.com/yiisoft/yii2-bootstrap): |
||||
provides a set of widgets that encapsulate the [Bootstrap](http://getbootstrap.com/) components and plugins. |
||||
- [yiisoft/yii2-codeception](https://github.com/yiisoft/yii2-codeception): |
||||
provides testing support based on [Codeception](http://codeception.com/). |
||||
- [yiisoft/yii2-debug](https://github.com/yiisoft/yii2-debug): |
||||
provides debugging support for Yii applications. When this extension is used, a debugger toolbar will appear |
||||
at the bottom of every page. The extension also provides a set of standalone pages to display more detailed |
||||
debug information. |
||||
- [yiisoft/yii2-elasticsearch](https://github.com/yiisoft/yii2-elasticsearch): |
||||
provides the support for using [Elasticsearch](http://www.elasticsearch.org/). It includes basic querying/search |
||||
support and also implements the [Active Record](db-active-record.md) pattern that allows you to store active records |
||||
in Elasticsearch. |
||||
- [yiisoft/yii2-faker](https://github.com/yiisoft/yii2-faker): |
||||
provides the support for using [Faker](https://github.com/fzaninotto/Faker) to generate fake data for you. |
||||
- [yiisoft/yii2-gii](https://github.com/yiisoft/yii2-gii): |
||||
provides a Web-based code generator that is highly extensible and can be used to quickly generate models, |
||||
forms, modules, CRUD, etc. |
||||
- [yiisoft/yii2-imagine](https://github.com/yiisoft/yii2-imagine): |
||||
provides commonly used image manipulation functions based on [Imagine](http://imagine.readthedocs.org/). |
||||
- [yiisoft/yii2-jui](https://github.com/yiisoft/yii2-jui): |
||||
provides a set of widgets that encapsulate the [JQuery UI](http://jqueryui.com/) interactions and widgets. |
||||
- [yiisoft/yii2-mongodb](https://github.com/yiisoft/yii2-mongodb): |
||||
provides the support for using [MongoDB](http://www.mongodb.org/). It includes features such as basic query, |
||||
Active Record, migrations, caching, code generation, etc. |
||||
- [yiisoft/yii2-redis](https://github.com/yiisoft/yii2-redis): |
||||
provides the support for using [redis](http://redis.io/). It includes features such as basic query, |
||||
Active Record, caching, etc. |
||||
- [yiisoft/yii2-smarty](https://github.com/yiisoft/yii2-smarty): |
||||
provides a template engine based on [Smarty](http://www.smarty.net/). |
||||
- [yiisoft/yii2-sphinx](https://github.com/yiisoft/yii2-sphinx): |
||||
provides the support for using [Sphinx](http://sphinxsearch.com). It includes features such as basic query, |
||||
Active Record, code generation, etc. |
||||
- [yiisoft/yii2-swiftmailer](https://github.com/yiisoft/yii2-swiftmailer): |
||||
provides email sending features based on [swiftmailer](http://swiftmailer.org/). |
||||
- [yiisoft/yii2-twig](https://github.com/yiisoft/yii2-twig): |
||||
provides a template engine based on [Twig](http://twig.sensiolabs.org/). |
||||
Loading…
Reference in new issue