模块开发：入门

PolyCMS 的真正力量在于其模块化。模块（有时称为插件）允许您扩展 CMS 的核心功能、添加新的 API 端点、创建自定义管理界面或与第三方服务集成 - 所有这些都无需触及任何核心代码。

本指南将引导您完成第一个模块的搭建。

1.目录结构

所有模块必须放置在 PolyCMS 安装根目录的 modules/ 目录中。它们遵循“Vendor/ModuleName”命名空间约定。

让我们创建一个由供应商“Polyx”创建的名为“BlogEnhancer”的模块。

modules/
└── Polyx/
    └── BlogEnhancer/
        ├── module.json          # The Module Manifest
        └── src/
            └── BlogEnhancerServiceProvider.php

2. 模块清单 (module.json)

每个模块必须在其根目录中有一个 module.json 文件。核心“ModuleManager”解析此文件以发现模块，注册其 PSR-4 自动加载命名空间，并启动其服务提供程序。

创建“modules/Polyx/BlogEnhancer/module.json”：

{
  "name": "BlogEnhancer",
  "vendor": "Polyx",
  "version": "1.0.0",
  "description": "Adds extra features and SEO tools to the core blog.",
  "provider": "Modules\\Polyx\\BlogEnhancer\\BlogEnhancerServiceProvider",
  "autoload": {
    "psr-4": {
      "Modules\\Polyx\\BlogEnhancer\\": "src/"
    }
  },
  "sandbox": false
}

3. 受信任的本机与沙盒远程

请注意上面清单中的 "sandbox": false 键。 PolyCMS 实现了双模型架构：

Trusted Native (sandbox: false): 该模块在 Laravel 核心内本地执行。它可以直接访问数据库、文件系统，并且可以通过服务提供商更改渲染规则。将此用于深度系统集成（如缓存、备份模块或复杂的支付网关）。

Sandbox Remote (sandbox: true)： 零信任执行模型。该模块位于带外，仅使用管理员批准的 Sanctum 令牌通过“/api/v1”或“/graphql”端点进行通信。将此用于第 3 方集成（例如 Mailchimp 同步、CRM 连接器或 AI 生成）。

在本教程中，我们正在构建一个 Trusted Native 模块。

4. 服务提供商

服务提供者是 PHP 代码的入口点。您可以在此处注册路由、绑定单例并挂钩核心事件。

创建 modules/Polyx/BlogEnhancer/src/BlogEnhancerServiceProvider.php：

<?php

declare(strict_types=1);

namespace Modules\Polyx\BlogEnhancer;

use Illuminate\Support\ServiceProvider;
use App\Facades\Hook;

class BlogEnhancerServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Bind classes into the service container
    }

    public function boot(): void
    {
        // 1. Load routes (if you have them)
        // $this->loadRoutesFrom(__DIR__ . '/routes/api.php');

        // 2. Load Views (if you have them)
        // $this->loadViewsFrom(__DIR__ . '/../resources/views', 'blog-enhancer');

        // 3. Register Hooks
        $this->registerHooks();
    }

    private function registerHooks(): void
    {
        // Example: Add a custom menu item to the Admin panel
        Hook::addAction('admin.menu.build', function ($menuRegistry) {
            $menuRegistry->addChild('content', [
                'key' => 'blog_enhancer_tools',
                'label' => 'SEO Tools',
                'url' => '/admin/blog-enhancer',
                'icon' => 'SparklesIcon',
                'order' => 90
            ]);
        });
    }
}

5. 启用模块

现在您的脚手架已完成，请登录 PolyCMS 管理面板并导航至 设置 > 模块。

您应该会看到列出的“BlogEnhancer”模块。单击启用。

核心系统将重新加载，并且因为我们连接到“admin.menu.build”，您将立即看到新的“SEO工具”链接出现在内容部分下的侧边栏中！

后续步骤

现在您的模块正在启动，您可以通过以下方式扩展它：

创建自定义管理 Vue 组件

注册新的 API 端点

通过 Widget System 注入 UI