Plugin Development

A plugin is one directory plus a manifest; the core registers front-end pages, admin pages, sidebar blocks and tables from it. The 20 bundled plugins — especially market, poly and site — are complete references.

On this page

Structure

plugins/<id>/
  plugin.php       # manifest returning an array (required)
  boot.php         # loaded on enable (hook registration)
  admin.php        # admin page (admin_file / admin_fn)
  page.php         # front-end page (page_file / page_fn)
  migrations/      # idempotent *.sql or *.php
  assets/

Manifest

FieldMeaning
id / name / ver / desc / author / licenseMetadata read by /plugin
requires.coreRequired core version
toggleWhether it can be disabled
tablesOwn tables (created/removed on install/uninstall)
pagesFront-end pages [['slug'=>'hello','title'=>'Example']] → /hello
blocksSidebar blocks
register_fileFile included on enable (usually boot.php)
admin_file / admin_fnAdmin page file and render function
page_file / page_fnFront-end file and function returning ['html'=>…, 'title'=>…]
uninstall['tables'=>[], 'options'=>[], 'like'=>[]] cleanup declaration

Minimal plugin

plugins/hello/plugin.php:

<?php
return [
  'id' => 'hello', 'name' => 'Example plugin', 'ver' => '0.1.0',
  'desc' => 'Minimal example', 'author' => 'YeCha', 'license' => 'MIT',
  'requires' => ['core' => '1.2.5'], 'toggle' => true,
  'pages' => [['slug' => 'hello', 'title' => 'Example page']],
  'register_file' => 'boot.php',
  'page_file' => 'page.php', 'page_fn' => 'hello_page',
];

plugins/hello/page.php:

<?php
function hello_page(string $slug): array {
    return [
        'html'  => '<h1>Hello</h1><p>Server-rendered from an example plugin.</p>',
        'title' => 'Example · ' . site_label(),
    ];
}

Enable it in Plugins and open /hello. A slug must not collide with Router::RESERVED (login, admin, feed, category, tag, mall, site, ai, …).

Routes

  • A single segment /<slug> matches Plugins::pages() and calls page_fn. Nested paths put the remaining segments in $GLOBALS['YC_PLUGIN_PATH'].
  • mall / site / ai have dedicated branches in core/Router.php; when the plugin is off, those branches fall back to 404.
  • Page functions return html / title (and optionally side, toc — see plugins/market/page.php).
  • Clean URLs without .html require a whitelist in Router (as done for docs and changelog).

Admin & permissions

  • admin_fn is dispatched at ?s=plug_<id>; always verify an admin session (Auth).
  • Every write form needs Csrf::field() and Csrf::check(); never trust IDs or table names from $_POST.
  • Escape output with e(); use prepared statements via Db and Db::t() for prefixed tables.
  • Plugins::activeMenus() appends admin menu entries from the manifest.

Tables & migrations

  • Prefix own tables with Db::t('xxx') (ye_) and declare them in tables so uninstall can clean them.
  • Migrations in migrations/ must be idempotent (CREATE TABLE IF NOT EXISTS, check-before-add); Upgrade::apply() records history in ye_migrations.
php tools/upgrade.php --component core --dry-run
php tools/upgrade.php --component core
  • Enabling a plugin runs its migrations automatically; never swallow migration errors.

Hook reality

core/Hooks.php offers Hooks::on($point, $fn, $prio) / Hooks::run($point, $payload) with array payloads and priority ordering.

Check the source: only two points are actually fired in production —

PointFired at
front.shellbefore the page shell is emitted in index.php
admin.editor.tailend of the editor in admin/posts.inc.php

Plugins register route, front.xml etc., but the core has no unified Hooks::run('route') dispatcher; modules such as mall and imgopt call each other directly. Therefore:

  • Use the pages manifest and Router branches for routing, not untriggered hooks.
  • Use the two real points for shell/editor injection.
  • Before writing a plugin, run grep -rn "Hooks::run" . — trigger points may change between versions.

Disable & uninstall

  • Disable stops registration (plugin.<id>.enabled=0); all data stays.
  • Uninstall purge=0 removes it from the list and disables it, data stays for a future reinstall.
  • Uninstall purge=1 deletes own tables/options per uninstall; the admin creates an automatic backup first.
  • plugin.<id>.* options are cleaned automatically; never declare shared tables in tables.

Release

  • [ ] php -l every file; manifest matches actual files
  • [ ] Migrations idempotent (run twice, --dry-run clean)
  • [ ] Enable/disable/uninstall regression for pages, admin and blocks
  • [ ] Package contains no secrets, var/cache, uploads or backups
  • [ ] Market requires https + SHA-256; install locally first
  • [ ] Kernel changes follow the release process in RELEASE.md