Розробка кастомного плагіна 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>Сторінок: {{ site_stats.total_pages }}</p>
<img src="{{ asset_url('logo.svg') }}" alt="Logo">

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

Плагіни розповсюджуються через 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 днів.