October cms-Plugins（插件-注册）

插件注册

介绍

插件是通过扩展为CMS添加新功能的基础
本文介绍了组件注册。
注册过程允许插件声明其功能，例如 组件或后端菜单和页面。
插件可以执行的一些示例：

1. 定义 组件.
2. 定义 用户权限.
3. 添加 配置页面, 菜单项, 列表 和 表单.
4. 创建 数据表结构和种子data.
5. Alter functionality of the core or other plugins.更改核心或其他插件的功能.。
6. 提供类, 后端 controllers, 视图, assets,和其他文件.

Directory structure目录结构

插件位于应用程序目录的 /plugins 子目录中。插件目录结构的示例：

plugins/
  acme/              <=== 作者名
    blog/            <=== 插件名
      classes/
      components/
      controllers/
      models/
      updates/
      ...
      Plugin.php     <=== 插件注册文件

并非所有插件目录都是必需的。唯一需要的文件是下面描述的 Plugin.php 。如果您的插件仅提供一个component，则您的插件目录可能会简单得多，如下所示：

plugins/
  acme/              <=== 作者名
    blog/            <=== 插件名
      components/
      Plugin.php     <=== 插件注册文件

Note: 如果你开发了一个插件并把它放到了插件市场，不要忘记更新 updates/version.yaml

Plugin namespaces 插件命名空间

插件命名空间很重要 如果你要通过插件市场提交你的插件时 会要求你指定一个作者名来作为你的插件空间名 一旦确定 不能再次更改。空间名是你的姓名的合并 如： \JohnSmith\Blog.

Registration file 注册文件

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' => 'blogPost'
        ];
    }
}

Supported methods 支持的方法

插件注册类支持以下方法：

Method	Description
pluginDetails()	返回插件信息
register()	注册方法，当插件第一次注册的时候调用
boot()	引导方法，在请求路由之前调用。
registerMarkupTags()	注册能在cms中使用的 附加标记标签 .
registerComponents()	注册本插件使用的 前端组件
registerNavigation()	注册本插件使用的 后端导航菜单项
registerPermissions()	注册本插件使用的后端权限 .
registerSettings()	注册本插件使用的 后端配置链接
registerFormWidgets()	注册本插件提供的 后端表单小部件
registerReportWidgets()	注册 后端报告小部件, 包含面板小部件
registerListColumnTypes()	注册插件提供的定制列表列类型 .
registerMailLayouts()	注册插件提供的邮件视图布局
registerMailTemplates()	注册插件提供的 邮件视图模版
registerMailPartials()	注册插件提供的 邮件视图partials
registerSchedule()	注册 定期执行 日程任务

Basic plugin information 基本插件信息

插件组册类必须要pluginDetails方法 返回一个有如下key的数组

Key	Description
name	插件名称 必填
description	插件说明，必填
author	插件作者名称，必填
icon	插件图标的名称。可用图标的完整列表可以在UI documentation. 此字体提供的任何图标名称均有效， 如 icon-glass, icon-music.
iconSvg	可以使用SVG图标代替标准图标（可选）。 SVG图标应为矩形，并且可以支持颜色。
homepage	作者网址的链接（可选）。

Routing and initialization 路由和初始化

插件注册文件可以包含两种方法boot and register.
使用这些方法，您可以执行任何您喜欢的事情
例如注册路由或勾住事件。

注册插件后，将立即调用register方法。
boot方法是在路由请求前调用
因此，如果您的操作依赖于另一个插件，则应使用boot方法
如
在boot方法中，您可以扩展models：

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

Note: 在更新过程中不会调用boot和register方法来保护系统免受严重错误的影响。要取消此限制，请使用[提升权限]（＃elevated-plugin）。

Plugins can also supply a file named routes.php that contain custom routing logic, as defined in the router service. For example:
插件还可以提供一个名为 routes.php 的文件，包含了自定义路由逻辑，就像定义在 路由服务.

Route::group(['prefix' => 'api_acme_blog'], function() {

    Route::get('cleanup_posts', function(){ return Posts::cleanUp(); });

});

Dependency definitions 依赖项定义

插件可以依赖其他插件
用插件注册文件中的$require 属性
该属性包含一个插件名数组
一个依赖Acme.User插件的插件可以写成如下声明：

namespace Acme\Blog;

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

    [...]
}

依赖项定义将影响插件的运行方式和更新问题.
安装过程将尝试自动安装任何依赖项
但是，如果在系统中检测到没有任何依赖项的插件，则会将其禁用以防止系统错误。

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

Extending Twig twig扩展

插件注册类的registerMarkupTags 方法可以定制twig过滤器和方法
下一个示例注册了两个Twig过滤器和两个函数。

public function registerMarkupTags()
{
    return [
        'filters' => [
            // 一个全局function, 用法 str_plural()
            'plural' => 'str_plural',

            // 一个本地方法 用法 $this->makeTextAllCaps()
            'uppercase' => [$this, 'makeTextAllCaps']
        ],
        'functions' => [
            // 一个静态方法调用 用法 Form::open()
            'form_open' => ['October\Rain\Html\Form', 'open'],

            // 使用内联闭包
            'helloWorld' => function() { return 'Hello World!'; }
        ]
    ];
}

public function makeTextAllCaps($text)
{
    return strtoupper($text);
}

Navigation menus 导航菜单

插件可以通过覆写Plugin registration class的 registerNavigation方法来扩展后端导航菜单
本节说明如何将菜单项添加到后端导航区域
用两个子菜单项注册顶级导航菜单项的示例：

public function registerNavigation()
{
    return [
        'blog' => [
            'label'       => 'Blog',
            'url'         => Backend::url('acme/blog/posts'),
            'icon'        => 'icon-pencil',
            'permissions' => ['acme.blog.*'],
            'order'       => 500,
            // 将counter设置为false以防止主菜单计数器的默认行为为其侧边菜单计数器的总和
            'counter'     => ['\Author\Plugin\Classes\MyMenuCounterService', 'getBlogMenuCount'],
            'counterLabel'=> 'Label describing a dynamic menu counter',
            // 可选 你可以设置badge而不是计数器来显示字符串而不是数字计数器
            'badge'       => 'New'

            'sideMenu' => [
                'posts' => [
                    'label'       => 'Posts',
                    'icon'        => 'icon-copy',
                    'url'         => Backend::url('acme/blog/posts'),
                    'permissions' => ['acme.blog.access_posts'],
                    'counter'     => 2,
                    'counterLabel'=> 'Label describing a static menu counter',
                ],
                'categories' => [
                    'label'       => 'Categories',
                    'icon'        => 'icon-copy',
                    'url'         => Backend::url('acme/blog/categories'),
                    'permissions' => ['acme.blog.access_categories'],
                ]
            ]
        ]
    ];
}

注册后端导航时，可以将本地化localization string 用作label值。
后端导航也可以由 permissions值控制，并与定义的后端用户权限.相对应。
后端导航出现在整个导航菜单项上的顺序由“ order”值控制。
较高的数字表示该项目将按菜单项的顺序出现在后面，而较低的数字表示该项目将在菜单项的前面出现。

要使子菜单项可见，你可以使用BackendMenu::setContext 方法在后端控制器中 设置导航内容
他将使父菜单项处于活动状态，并在侧面菜单中显示子菜单。

Registering middleware 注册中间件

要注册自定义中间件，您可以使用Controller 中间件将其直接应用于插件中的后端控制器。
或者你可以使用以下方法扩展Controller类。

public function boot()
{
    \Cms\Classes\CmsController::extend(function($controller) {
        $controller->middleware('Path\To\Custom\Middleware');
    });
}

或者，你可以通过以下方法将其直接推入内核。

public function boot()
{
    // 将新的中间件添加到堆栈的开头
    $this->app['Illuminate\Contracts\Http\Kernel']
         ->prependMiddleware('Path\To\Custom\Middleware');

    // 将新的中间件添加到堆栈的末尾
    $this->app['Illuminate\Contracts\Http\Kernel']
         ->pushMiddleware('Path\To\Custom\Middleware');
}

Elevated permissions 提高权限

默认情况下，插件被限制访问系统的某些区域。
这是为了防止可能将管理员被锁定无法进入后台这类的严重错误。
在没有提升权限的情况下访问这些区域时，将不会触发插件的 boot and register 初始化方法
By default plugins are restricted from accessing certain areas of the system. This is to prevent critical errors that may lock an administrator out from the back-end. When these areas are accessed without elevated permissions, the boot and register initialization methods for the plugin will not fire.

Request	Description
/combine	asset合并后生成的url
/backend/system/updates	该网站更新上下文
/backend/system/install	安装程序路径
/backend/backend/auth	后端身份验证路径（登录，注销）
october:up	所有挂起迁移状态的cli命令
october:update	触发更新过程的CLI命令

定义$elevated属性以授予插件提升的权限
/**
* @var bool Plugin requires elevated permissions.
*/
public $elevated = true;