Разработка модуля: начало работы

Истинная сила PolyCMS заключается в ее модульности. Модули (иногда называемые плагинами) позволяют расширять основные функциональные возможности CMS, добавлять новые конечные точки API, создавать собственные интерфейсы администратора или интегрироваться со сторонними сервисами — и все это без изменения базового кода.

Это руководство проведет вас через этапы создания вашего первого модуля.

1. Структура каталогов

Все модули должны быть размещены в каталоге modules/ в корне вашей установки PolyCMS. Они следуют соглашению о пространстве имен Vendor/ModuleName.

Давайте создадим модуль BlogEnhancer от производителя Polyx.

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. Trusted Native против Sandbox Remote

Обратите внимание на ключ "sandbox": false в приведенном выше манифесте. PolyCMS реализует архитектуру двойной модели:

Trusted Native (sandbox: false): Модуль выполняется в ядре Laravel. Он имеет прямой доступ к базе данных, файловой системе и может изменять правила рендеринга через поставщиков услуг. Используйте это для глубокой системной интеграции (например, модулей кэширования, резервного копирования или сложных платежных шлюзов).

Sandbox Remote (sandbox: true): Модель выполнения с нулевым доверием. Модуль работает вне канала и взаимодействует только через конечные точки /api/v1 или /graphql с использованием одобренного администратором токена Sanctum. Используйте это для сторонней интеграции (например, синхронизации Mailchimp, соединителей CRM или генерации искусственного интеллекта).

В этом руководстве мы создаем модуль 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 Tools» на боковой панели в разделе «Содержимое»!

Следующие шаги

Теперь, когда ваш модуль загружается, вы можете расширить его:

Создание пользовательских компонентов Admin Vue

Регистрация новых конечных точек API

Внедрение пользовательского интерфейса через Систему виджетов