Разработка кастомного плагина Pico

Разработка кастомного плагина Pico

Pico — это плоский PHP-движок без базы данных. Контент хранится в Markdown-файлах, шаблоны на Twig, конфиг в YAML. Вся система помещается в одну папку, поднимается за минуту. Расширяется через плагины — классы PHP, которые подключаются к системе событий.

Как устроена система плагинов

Каждый плагин наследует AbstractPicoPlugin и реагирует на события через методы-обработчики. Pico вызывает их в строго определённом порядке — от инициализации до рендеринга.

<?php

class MyPlugin extends AbstractPicoPlugin
{
    const API_VERSION = 3;

    protected $enabled = true;

    public function onConfigLoaded(array &$config): void
    {
        // конфиг доступен и может быть изменён
        if (!isset($config['my_plugin'])) {
            $config['my_plugin'] = ['option' => 'default'];
        }
    }

    public function onMetaHeaders(array &$headers): void
    {
        // добавляем новый YAML-заголовок в Markdown-файлы
        $headers['redirect'] = 'Redirect';
        $headers['auth_required'] = 'AuthRequired';
    }

    public function onPageRendering(string &$templateName, array &$twigVariables): void
    {
        // манипулируем данными перед рендерингом
        $meta = $twigVariables['meta'];
        if (!empty($meta['redirect'])) {
            header('Location: ' . $meta['redirect'], true, 302);
            exit;
        }
    }
}

Файл кладётся в plugins/MyPlugin/MyPlugin.php. Структура директории:

plugins/
└── MyPlugin/
    ├── MyPlugin.php
    ├── config.yml.template
    └── README.md

Цепочка событий

Порядок вызова событий в Pico 3.x:

1. onPluginsLoaded — все плагины загружены, можно обращаться к другим
2. onConfigLoaded — конфиг разобран
3. onRequestUrl — URL запроса известен
4. onContentLoading — до чтения Markdown-файла
5. onMetaHeaders — список допустимых YAML-заголовков
6. onMetaParsed — метаданные страницы разобраны
7. onContentParsed — Markdown сконвертирован в HTML
8. onPagesLoading / onPagesLoaded — список всех страниц
9. onPageRendering — прямо перед рендерингом Twig-шаблона
10. onPageRendered — итоговый HTML готов

Большинство обработчиков принимают аргументы по ссылке (&$variable) — это ключевой механизм изменения данных.

Пример: плагин авторизации по IP

public function onConfigLoaded(array &$config): void
{
    $this->allowedIps = $config['ip_restrict']['allowed'] ?? [];
    $this->restrictedPaths = $config['ip_restrict']['paths'] ?? [];
}

public function onRequestUrl(string &$url): void
{
    $clientIp = $_SERVER['REMOTE_ADDR'] ?? '';

    foreach ($this->restrictedPaths as $path) {
        if (str_starts_with($url, $path)) {
            if (!in_array($clientIp, $this->allowedIps, true)) {
                header('HTTP/1.1 403 Forbidden');
                echo 'Access denied';
                exit;
            }
        }
    }
}

Конфиг в config/config.yml:

ip_restrict:
  allowed:
    - 192.168.1.100
    - 10.0.0.0/8
  paths:
    - /admin
    - /internal

Пример: плагин кастомных шорткодов

Pico не поддерживает шорткоды из коробки, но их легко добавить через onContentParsed:

public function onContentParsed(string &$content): void
{
    // [youtube id="dQw4w9WgXcQ"]
    $content = preg_replace_callback(
        '/\[youtube\s+id="([a-zA-Z0-9_-]+)"\]/',
        static function (array $matches): string {
            $id = htmlspecialchars($matches[1], ENT_QUOTES);
            return sprintf(
                '<div class="video-embed"><iframe src="https://www.youtube.com/embed/%s" '
                . 'allowfullscreen loading="lazy"></iframe></div>',
                $id
            );
        },
        $content
    );
}

Передача данных в Twig

Плагин может добавлять переменные в шаблоны:

public function onPageRendering(string &$templateName, array &$twigVariables): void
{
    $twigVariables['site_stats'] = [
        'total_pages' => count($twigVariables['pages']),
        'build_time'  => microtime(true) - $_SERVER['REQUEST_TIME_FLOAT'],
    ];

    // или регистрируем Twig-функцию
    $twig = $this->getPico()->getTwig();
    $twig->addFunction(new \Twig\TwigFunction('asset_url', function (string $path): string {
        return $this->getPico()->getBaseUrl() . '/assets/' . ltrim($path, '/');
    }));
}

В шаблоне:

<p>Pages: {{ site_stats.total_pages }}</p>
<img src="{{ asset_url('logo.svg') }}" alt="Logo">

Взаимодействие между плагинами

public function onPluginsLoaded(array &$plugins): void
{
    if (isset($plugins['PicoDeprecated'])) {
        $this->deprecatedPlugin = $plugins['PicoDeprecated'];
    }
}

Через $this->getPico()->getPlugin('PluginName') можно получить экземпляр другого плагина и вызывать его публичные методы.

Публикация плагина

Плагины распространяются через Composer:

{
    "name": "vendor/pico-my-plugin",
    "type": "pico-plugin",
    "require": {
        "picocms/pico": "^3.0"
    },
    "extra": {
        "picocms-plugin": {
            "class": "MyPlugin"
        }
    }
}

После composer require vendor/pico-my-plugin плагин автоматически появляется в plugins/.

Сроки

Простой плагин (1–2 события, без внешних зависимостей): 1–2 дня. Плагин с кастомным UI, внешним API или сложной логикой маршрутизации: 3–5 дней.