Построение расширяемой CMS: методы подключения модулей с примерами на PHP

Раздел: Веб-разработка -> Расширение функционала

Реализация модульной системы в CMS на PHP

Основное решение: автозагрузка классов по стандарту PSR-4 с использованием Front Controller

Наиболее эффективный способ организовать модули - применить автозагрузку согласно PSR-4 и единую точку входа (Front Controller). Каждый модуль представляет собой отдельное пространство имён, содержащее контроллеры, модели и представления. index.php выступает маршрутизатором, который подключает автозагрузчик и вызывает нужный контроллер на основе параметров запроса (например, ?module=news&action=show).

// Структура папок:
project/
  src/
    Modules/
      News/
        Controllers/
          NewsController.php
        Models/
          News.php
        Views/
          show.php
  public/
    index.php
  vendor/
    autoload.php (composer)
// public/index.php
require __DIR__ . '/../vendor/autoload.php';

use App\Core\Router;

$router = new Router();
$router->dispatch($_GET);
// src/Core/Router.php
namespace App\Core;

class Router
{
    public function dispatch(array $params)
    {
        $module = $params['module'] ?? 'default';
        $action = $params['action'] ?? 'index';
        $lang   = $params['ru'] ?? 'ru';

        $controllerClass = 'App\\Modules\\' . ucfirst($module) . '\\Controllers\\' . ucfirst($module) . 'Controller';

        if (!class_exists($controllerClass)) {
            http_response_code(404);
            echo "Модуль $module не найден";
            return;
        }

        $controller = new $controllerClass($lang);
        if (!method_exists($controller, $action)) {
            http_response_code(404);
            echo "Действие $action не определено";
            return;
        }

        $controller->$action();
    }
}

Пояснение шагов:

  1. Composer создаёт автозагрузку, сопоставляя namespace с папками.
  2. Front Controller (index.php) принимает все запросы (через .htaccess).
  3. Router анализирует GET-параметры, формирует имя класса контроллера и вызывает метод.
  4. Каждый модуль живёт в своём пространстве имён, что исключает конфликты.

Типичные ошибки и их решения:

  • Ошибка Class not found - не настроен composer autoload, либо неверное пространство имён. Проверьте composer.json и выполните composer dump-autoload.
  • Проблемы с регистром букв - namespace чувствителен к регистру, убедитесь, что папки и файлы названы так же, как в коде.
  • Медленная работа при большом количестве модулей - используйте кеширование маршрутов или предзагрузку классов через Composer classmap.

Как реализовать модули без автозагрузки, используя require_once?

Для маленьких проектов или legacy-кода можно подключать модули вручную через require_once.

// index.php
$module = $_GET['module'] ?? 'index';
$file = __DIR__ . '/modules/' . $module . '/index.php';
if (file_exists($file)) {
    require_once $file;
} else {
    // 404
}

Когда использовать: при минимальной структуре, когда модулей не более 5–7 и проект не планирует масштабироваться.

Проблемы:

  • Риск включения одинаковых имён функций или классов - конфликты.
  • Трудности с поддержкой и тестированием.
  • Невозможность гибко переопределять модули.

Как применить switch в index.php для загрузки модуля?

В простейшем случае можно разместить код каждого модуля внутри case оператора switch. Такой подход часто встречается в учебных CMS.

$module = $_GET['module'] ?? 'home';
switch ($module) {
    case 'news':
        require 'modules/news.php';
        break;
    case 'articles':
        require 'modules/articles.php';
        break;
    default:
        require 'modules/home.php';
}

Цель: быстрая реализация для прототипа. Но код становится нерасширяемым - каждый новый модуль требует правки index.php.

Ошибки:

  • Забыть break - выполнится несколько модулей подряд.
  • Проблемы безопасности при отсутствии валидации параметра module - возможна инъекция пути.
Как организовать модули через анонимные функции и callback'и?

Можно зарегистрировать модули в виде callable-сущностей, хранящихся в массиве. index.php вызывает нужный callback по имени модуля.

// modules.php
$modules = [];
$modules['news'] = function($params) {
    echo "Новости. Параметры: " . json_encode($params);
};
$modules['gallery'] = function($params) {
    echo "Галерея";
};
// index.php
require 'modules.php';
$moduleName = $_GET['module'] ?? 'news';
if (isset($modules[$moduleName])) {
    $modules[$moduleName]($_GET);
} else {
    echo "Модуль не найден";
}

Когда удобно: при создании микро-CMS или плагинов, где модули не требуют собственных классов. Однако отладка и тестирование таких callback'ов затруднены.

Проблемы:

  • Анонимные функции сложно переиспользовать и подменять.
  • Отсутствие типизации - ошибки проявляются в рантайме.
Как применить Composer-пакеты в качестве модулей?

Более продвинутый способ - каждый модуль оформляется как отдельный Composer-пакет, устанавливаемый через composer require. Пакет может содержать сервис-провайдеры, регистрирующие маршруты и хуки.

// composer.json (внутри пакета custom-module/news)
{
    "name": "custom-module/news",
    "require": {
        "php": ">=8.0"
    },
    "autoload": {
        "psr-4": {
            "CustomModule\\News\\": "src/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "CustomModule\\News\\NewsServiceProvider"
            ]
        }
    }
}

В основной CMS (например, на Laravel) модули автоматически регистрируются через Service Provider. Для обычной CMS можно написать свой загрузчик, который сканирует vendor и подключает модули по наличию определённого интерфейса.

Цель: модульность уровня enterprise, когда модули разрабатываются разными командами и могут быть независимо обновлены. Требует зрелой архитектуры (Dependency Injection, события).

Типичные ошибки:

  • Конфликты зависимостей разных пакетов - необходима грамотная версионирование.
  • Сложность отладки при автообнаружении модулей.

Расширенные примеры кода с результатами

Пример 1. Реализация простого модуля "Новости" с использованием PSR-4 и шаблонизации через include.

Пример 
// src/Modules/News/Controllers/NewsController.php
namespace App\Modules\News\Controllers;

class NewsController
{
    private string $lang;

    public function __construct(string $lang)
    {
        $this->lang = $lang;
    }

    public function index()
    {
        // Загрузка данных из модели
        $model = new \App\Modules\News\Models\News();
        $news = $model->getAll($this->lang);

        // Рендер представления
        $view = __DIR__ . '/../Views/index.php';
        if (file_exists($view)) {
            extract(['news' => $news, 'lang' => $this->lang]);
            include $view;
        }
    }

    public function show()
    {
        $id = (int)$_GET['id'];
        // ...
    }
}
// Результат при обращении /index.php?module=news&action=index
// Выведет HTML-список новостей с заголовками и датами

Пример 2. Маршрутизация с поддержкой вложенных параметров (например, /index.php?module=news&action=show&id=42&ru=1).

Пример 
// src/Core/Router.php с поддержкой middleware
public function dispatch(array $params)
{
    $module = preg_replace('/[^a-z0-9_]/i', '', $params['module'] ?? 'default');
    $lang = in_array($params['ru'] ?? 'ru', ['ru', 'en']) ? $params['ru'] : 'ru';

    // Проверка наличия модуля через реестр
    $registry = ModuleRegistry::getInstance();
    if (!$registry->hasModule($module)) {
        throw new \RuntimeException("Module $module not registered");
    }

    $controllerClass = $registry->getControllerClass($module);
    $controller = new $controllerClass($lang);
    $controller->{$params['action'] ?? 'index'}();
}

Пример 3. Реализация механизма плагинов (хуков) для модулей. Каждый модуль может подписываться на события.

Пример 
// core/EventManager.php
namespace App\Core;

class EventManager
{
    private static array $listeners = [];

    public static function on(string $event, callable $callback): void
    {
        self::$listeners[$event][] = $callback;
    }

    public static function emit(string $event, array $data = []): void
    {
        foreach (self::$listeners[$event] ?? [] as $callback) {
            $callback($data);
        }
    }
}

// Пример использования в модуле:
// registration.php
\App\Core\EventManager::on('afterUserLogin', function($data) {
    // Логирование, отправка уведомления
});

// в index.php после входа:
\App\Core\EventManager::emit('afterUserLogin', ['user_id' => 123]);
// Результат: при логине пользователя срабатывает дополнительная логика без изменения основного кода.

Пример 4. Использование языковых файлов для модуля (параметр ru).

Пример 
// src/Modules/News/Lang/ru.php
return [
    'title' => 'Новости',
    'empty' => 'Нет новостей',
];

// src/Modules/News/Lang/en.php
return [
    'title' => 'News',
    'empty' => 'No news',
];

// В контроллере:
$langFile = __DIR__ . '/../Lang/' . $this->lang . '.php';
$lang = file_exists($langFile) ? include $langFile : [];
// передача в представление

Пример 5. Обработка ошибки 404 с выводом сообщения на языке пользователя.

Пример 
// index.php (обработчик исключений)
try {
    $router->dispatch($_GET);
} catch (\Throwable $e) {
    $lang = in_array($_GET['ru'] ?? 'ru', ['ru','en']) ? $_GET['ru'] : 'ru';
    $messages = [
        'ru' => 'Страница не найдена',
        'en' => 'Page not found'
    ];
    http_response_code(404);
    echo '
' . $messages[$lang] . '
';
    // Логирование ошибки для разработчика
    error_log($e->getMessage());
}
// При неверном модуле или действии пользователь увидит сообщение на русском или английском.
Модули CMS

Модули CMS - comments

En
Index php module ru (php)