# 插件机制

# 原理说明

BeikeShop插件充分利用 Laravel 框架 ServiceProvider 发现以及引导机制，将系统各个插件注册到系统。包括插件的 Migrations, Routes, Views, Lang, 以及启动文件 Bootstrap.php。

插件PHP代码需要遵循 PSR4自动加载规范。

简单来说，目录名和类名需要采用首字母大写驼峰也就是Studly原则, 如图所示

# 目录说明

一个典型的插件目录如下

Controllers
Lang
Middleware
Migrations
Models
Repositories
Routes
Static
Views
Bootstrap.php
columns.php
config.json
README.md

目录名称	说明
Controllers	控制器目录，前台和后台控制器都放到此目录，可以有子目录，只要符合 `PSR4` 规范即可
Lang	语言包目录，子目录的名字需要和 `/resources/lang` 目录下保持一致
Middleware	中间件目录，子目录 `/Shop` 存放前台中间件, 子目录 `/Admin` 存放后台中间件, 系统会自动加载
Migrations	数据库迁移目录，可参考 https://laravel.com/docs/9.x/migrations
Models	模型目录，插件模型，定义模型数据表以及表间关系
Repositories	数据仓库目录，DB存取相关类
Routes	路由目录，插件自定义路由。admin.php 存放管理后台路由, shop.php 存放前台路由
Static	存放静态文件，比如图片，可以放到 image 目录，可以在对应插件模板文件用 helper `plugin_resize(插件编码, '/image/xx.png')` 引用
Views	插件模板目录，包括前后台 blade.php 模板文件
Bootstrap.php	插件启动类需要实现一个 `boot` 公共方法: `public function boot()`, 再在该方法中添加 hook
columns.php	插件配置，此文件存放插件需要的配置字段，后台插件编辑页会自动显示。如果需要自定义配置页面，请在插件下添加 `/Views/admin/config.blade.php` 模板文件
config.json	插件基本信息，包括编码，名称，描述，类型，图标，作者等信息
README.md	插件使用说明文档，系统会自动读取此文件内容并展示在插件编辑页面，方便开发者提供插件的操作指南等内容，此功能在 beikeshop v3.0.0.4 版本和 beikeshop v2.0.0.27 以上生效

# 插件核心架构与配置

BeikeShop 插件目录必须遵循 PSR-4 规范。特别注意 config.json 中的 code 字段，它是插件的全局唯一标识符。如果 code 与市场已有插件重复，会导致授权验证失败。

# config.json 配置

用自带的最新商品列表插件举例：

{
    "code": "latest_products",
    "name": {
        "zh_cn": "最新商品列表",
        "en": "Latest Products"
    },
    "description": {
        "zh_cn": "首页菜单添加最新商品列表功能",
        "en": "Latest products for header menu"
    },
    "type": "feature",
    "version": "v1.0.0",
    "icon": "/image/logo.png",
    "author": {
        "name": "成都光大网络科技有限公司",
        "email": "yangjin@guangda.work"
    }
}

name 和 description 可以按照上面格式配置多语言，语言 code 有：

de,en,es,fr,id,it,ja,ko,ru,zh_cn,zh_hk

type 是插件类型，所有类型有：

名称	code
支付方式	payment
营销推广	marketing
配送方式	shipping
主题模板	theme
数据分析	analysis
客户服务	service
语言翻译	language
翻译工具	translator
其他功能	feature

# 插件图标规范

插件市场会自动读取插件包 Static/image 目录下的 Logo 文件，并在开发者上传 ZIP 包时自动上传到市场。

一般情况下，只需要提供一个 logo.png 即可。logo_en.png 是可选项，只有在你希望英文站显示单独的英文 Logo 时才需要提供。

推荐目录结构：

YourPlugin/
├── Static/
│   └── image/
│       ├── logo.png
│       └── logo_en.png(可选)
├── config.json
└── Bootstrap.php

规则说明：

logo.png：必填，默认 Logo，建议尺寸为 500x500。
logo_en.png：可选，英文站专用 Logo，建议尺寸同样为 500x500。
如果插件包里只有 logo.png，插件市场会将它同时用于 zh_cn 和 en。
如果插件包里同时存在 logo.png 和 logo_en.png，系统会分别写入中文和英文的插件图标。
英文站优先读取 en 的 Logo；如果没有 en，会自动回退读取 zh_cn 的 Logo。

开发建议：

logo.png 建议直接按 500x500 制作。
logo_en.png 建议用于英文介绍图，避免图片中只有中文文字，导致 .com 站用户无法理解。
如果同时提供两张图，建议保持相同尺寸和视觉风格，只替换图片中的文案语言。
建议使用清晰的 PNG 图片，文件命名必须严格使用 logo.png 和 logo_en.png。

说明：

config.json 中的 "icon": "/image/logo.png" 仍然保留，用于声明插件默认图标路径。
插件市场实际展示时，会优先读取插件包上传后生成的多语言 Logo 数据。

# 装修模块功能添加逻辑

通过 Hook 机制可以将插件功能注入到前端模板或修改核心数据。

前端模板 Hook (**add_hook_blade**)：这里的第一个参数必须对应 Layout 或视图中的 Blade Path（如 header.top.telephone）。
数据流修改 (**add_hook_filter**)：

# 订阅模式插件开发流程 (以 Discount Plugin 为例)

订阅插件通常采用 C/S 架构，通过服务端 API 验证授权：

客户端请求：插件逻辑中使用 fetch 或 PHP 服务端请求进行状态校验。
上架策略：发布插件时需勾选“是否订阅”，且根据官方要求，必须设置不少于 1 个月 的免费订阅期。

← 编码规范 Hook 机制 →