插件

插件使用唯一代码进行标识，例如，一个名为Acme.Blog的插件位于目录plugins/acme/blog中。

本文介绍了插件及其注册功能。注册过程允许插件声明其功能，例如 CMS 组件或后端导航和页面。以下是插件可以执行的一些操作示例。

1. 创建数据库表结构并填充初始数据。
2. 定义 CMS 组件.
3. 定义 用户权限.
4. 添加 设置页面, 导航项, 列表 和 表单.
5. 修改 核心或其它插件的功能。
6. 提供类、后端控制器、视图、资产及其他文件。

目录结构

插件位于应用程序目录的 插件 目录。一个插件目录结构示例如下。

├── plugins
| └── acme ← 作者名称
| └── blog ← 插件名称
| ├── classes
| ├── components
| ├── controllers
| ├── models
| ├── updates
| └── Plugin.php ← 注册文件

并非所有插件目录都是必需的。唯一必需的文件是 Plugin.php 下文所述。如果您的插件仅提供单个组件，您的插件目录可能会简单得多，像这样。

├── plugins
| └── acme
| └── blog
| ├── components
| └── Plugin.php

插件命名空间

插件命名空间至关重要，特别是如果你打算在October CMS Marketplace上发布你的插件。当你在Marketplace上注册为作者时，你将被要求提供作者代码，该代码应作为你所有插件的根命名空间。你只能指定一次作者代码，即在注册时。Marketplace提供的默认作者代码由作者的名字和姓氏组成：JohnSmith。注册后该代码无法更改。你所有的插件命名空间都应该在根命名空间下定义，例如JohnSmith\Blog。

注册文件

该 create:plugin 命令会生成一个插件文件夹以及该插件的基本文件。 第一个参数指定作者和插件名称。

php artisan create:plugin Acme.Blog

该 Plugin.php 文件，称为插件注册文件，是一个初始化脚本，用于声明插件的核心功能和信息。注册文件可以提供以下内容：

1. 关于插件、其名称和作者的信息。
2. 扩展 CMS 的注册方法。

注册脚本应该使用插件命名空间。注册脚本应该定义一个名为 Plugin 的类，该类继承 System\Classes\PluginBase 类。插件注册类中唯一必需的方法是 pluginDetails。插件注册文件示例如下。

namespace Acme\Blog;

class Plugin extends \System\Classes\PluginBase
{
    public function pluginDetails()
    {
        return [
            'name' => 'Blog Plugin',
            'description' => 'Provides some really cool blog features.',
            'author' => 'ACME Corporation',
            'icon' => 'icon-leaf'
        ];
    }

    public function registerComponents()
    {
        return [
            \Acme\Blog\Components\Post::class => 'blogPost'
        ];
    }
}

基本插件信息

pluginDetails 是插件注册类的必选方法。它应返回一个包含以下键的数组：

启动和初始化

插件注册文件可以包含两个方法 boot 和 register. 利用这些方法，你可以做任何你想做的事情，例如注册路由或将处理程序附加到事件.

该 register 方法会在插件注册时立即调用。 该 boot 方法会在请求被路由之前调用。 因此如果你的操作依赖于另一个插件，你应该使用 boot 方法。 例如，在 boot 方法中你可以扩展模型。

public function boot()
{
    User::extend(function($model) {
        $model->hasOne['author'] = \Acme\Blog\Models\Author::class;
    });
}

boot 方法是可选的，将其保留为未定义状态有助于提升性能。此外，只有 boot 方法支持通过应用程序容器进行依赖注入。
:::

插件也可以提供一个名为 init.php 的文件，其中包含自定义初始化逻辑。下面是一些示例内容。

App::before({
    // Logic when the request starts, after routes are registered
});

App::after({
    // Logic the request has finished, after the response is sent
});

依赖定义

一个插件可以通过在插件注册文件中定义一个 $require 属性来依赖其他插件，该属性应包含一个被视为依赖项的插件名称数组。一个依赖于 Acme.User 插件的插件可以按如下方式声明此依赖项：

namespace Acme\Blog;

class Plugin extends \System\Classes\PluginBase
{
    /**
     * @var array require these plugins
     */
    public $require = ['Acme.User'];

    // ...
}

依赖项定义将影响插件的运行方式以及更新过程如何应用迁移。安装过程将尝试自动安装所有依赖项，但是如果系统检测到某个插件缺少其任何依赖项，它将被禁用以防止系统错误。

依赖定义可能很复杂，但务必注意防止循环引用。依赖图应始终是有向的，并且循环依赖被视为一个设计错误。

版本历史

插件维护变更日志是一种良好实践，用于记录代码中的任何更改或改进。除了记录变更说明，此过程还具备在正确顺序下执行迁移和种子文件的实用能力。

更改日志存储在一个名为 version.yaml 的 YAML 文件中，该文件位于插件的 updates 目录内，与迁移文件和种子文件共存。此示例显示了典型的插件 updates 目录结构：

├── plugins
| └── author
| └── myplugin
| ├── updates
| | ├── version.yaml ← 版本文件
| | ├── create_tables.php ← 数据库脚本
| | ├── seed_the_database.php
| | └── create_another_table.php
| └── Plugin.php

插件依赖项

更新会根据插件注册文件中定义的依赖项，以特定顺序应用. 依赖插件必须等到所有依赖项首先更新完成后，才会进行更新.

namespace Acme\Blog;

class Plugin extends \System\Classes\PluginBase
{
    public $require = ['Acme.User'];
}

在上面的例子中，Acme.Blog 插件直到 Acme.User 插件完全更新后才会更新。

插件版本文件

version.yaml 文件，称为插件版本文件，包含版本注释并按正确顺序引用数据库脚本。请阅读 数据库结构 文章以获取有关迁移文件的信息。如果您打算将插件提交到 市场，此文件是必需的。这是一个插件版本文件的示例。

v1.0.1: First version
v1.0.2: Second version
v1.0.3:
    - Update with a migration and seed
    - create_tables.php
    - seed_the_database.php
v2.0.0: Important update
v2.0.1: Latest version

version.yaml 文件应始终将第一行用于描述更改的文本更新以及其余行用于更新脚本。对于更详细的更新，请考虑使用专门的更新日志文件。

如您所见，应该有一个代表版本号的键，后面跟着更新消息，它是一个字符串或包含更新消息的数组。 对于引用迁移或填充文件的更新，作为脚本文件名的行可以放置在任何位置。 一个没有关联更新文件的注释示例。

v1.0.1: A single comment that uses no update scripts.

重要更新

有时插件需要引入会破坏已在使用该插件的网站的功能。为防止这些更改自动部署，您应该增加版本字符串（major.minor.patch）的主版本号段。以下是一个重要更新注释的示例。

v2.1.0: This is an important update from v1 that contains breaking changes.

当从版本 v1 标记新版本 v2 时，这些更改不会作为常规更新的一部分进行部署。用户必须再次安装该插件，才能通过 Composer 接收最新版本。

迁移和种子文件

正如之前所述，更新还定义了何时迁移和种子文件应该被应用。一个包含注释和更新的更新行：

v1.1.1:
    - This update will execute the two scripts below.
    - some_upgrade_file.php
    - some_seeding_file.php

更新文件名应使用 蛇形命名法 而包含的 PHP 类应使用 驼峰式命名法。对于名为 some_upgrade_file.php 对应的类将是 SomeUpgradeFile。

<?php namespace Acme\Blog\Updates;

use Schema;
use October\Rain\Database\Updates\Migration;

/**
 * some_upgrade_file.php
 */
class SomeUpgradeFile extends Migration
{
    ///
}

另请参见

• 数据库迁移和填充