Pico CMS Custom Plugin Development

Development of Custom Pico Plugin

Pico is a flat PHP engine without database. Content is stored in Markdown files, templates in Twig, config in YAML. Entire system fits in one folder, launches in a minute. Extended via plugins — PHP classes that connect to system events.

How Plugin System Works

Each plugin inherits AbstractPicoPlugin and reacts to events via handler methods. Pico calls them in strict order — from initialization to rendering.

<?php

class MyPlugin extends AbstractPicoPlugin
{
    const API_VERSION = 3;

    protected $enabled = true;

    public function onConfigLoaded(array &$config): void
    {
        // config available and can be modified
        if (!isset($config['my_plugin'])) {
            $config['my_plugin'] = ['option' => 'default'];
        }
    }

    public function onMetaHeaders(array &$headers): void
    {
        // add new YAML header to Markdown files
        $headers['redirect'] = 'Redirect';
        $headers['auth_required'] = 'AuthRequired';
    }

    public function onPageRendering(string &$templateName, array &$twigVariables): void
    {
        // manipulate data before rendering
        $meta = $twigVariables['meta'];
        if (!empty($meta['redirect'])) {
            header('Location: ' . $meta['redirect'], true, 302);
            exit;
        }
    }
}

File is placed in plugins/MyPlugin/MyPlugin.php. Directory structure:

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

Event Chain

Event call order in Pico 3.x:

1. onPluginsLoaded — all plugins loaded, can access others
2. onConfigLoaded — config parsed
3. onRequestUrl — request URL known
4. onContentLoading — before reading Markdown file
5. onMetaHeaders — list of valid YAML headers
6. onMetaParsed — page metadata parsed
7. onContentParsed — Markdown converted to HTML
8. onPagesLoading / onPagesLoaded — list of all pages
9. onPageRendering — right before Twig template rendering
10. onPageRendered — final HTML ready

Most handlers take arguments by reference (&$variable) — key mechanism for data modification.

Example: IP Restriction Plugin

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 in config/config.yml:

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

Example: Custom Shortcodes Plugin

Pico doesn't support shortcodes out of box, but easily add via 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
    );
}

Passing Data to Twig

Plugin can add variables to templates:

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

    // or register Twig function
    $twig = $this->getPico()->getTwig();
    $twig->addFunction(new \Twig\TwigFunction('asset_url', function (string $path): string {
        return $this->getPico()->getBaseUrl() . '/assets/' . ltrim($path, '/');
    }));
}

In template:

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

Plugin Publishing

Plugins distributed via Composer:

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

After composer require vendor/pico-my-plugin plugin automatically appears in plugins/.

Development Timelines

Simple plugin (1–2 events, no external dependencies): 1–2 days. Plugin with custom UI, external API, or complex routing logic: 3–5 days.