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 · Manifest · Minimal plugin · Routes · Admin & permissions · Tables & migrations · Hook reality · Disable & uninstall · Release
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
| Field | Meaning |
|---|---|
id / name / ver / desc / author / license | Metadata read by /plugin |
requires.core | Required core version |
toggle | Whether it can be disabled |
tables | Own tables (created/removed on install/uninstall) |
pages | Front-end pages [['slug'=>'hello','title'=>'Example']] → /hello |
blocks | Sidebar blocks |
register_file | File included on enable (usually boot.php) |
admin_file / admin_fn | Admin page file and render function |
page_file / page_fn | Front-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>matchesPlugins::pages()and callspage_fn. Nested paths put the remaining segments in$GLOBALS['YC_PLUGIN_PATH']. mall/site/aihave dedicated branches incore/Router.php; when the plugin is off, those branches fall back to 404.- Page functions return
html/title(and optionallyside,toc— seeplugins/market/page.php). - Clean URLs without
.htmlrequire a whitelist inRouter(as done fordocsandchangelog).
Admin & permissions
admin_fnis dispatched at?s=plug_<id>; always verify an admin session (Auth).- Every write form needs
Csrf::field()andCsrf::check(); never trust IDs or table names from$_POST. - Escape output with
e(); use prepared statements viaDbandDb::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 intablesso uninstall can clean them. - Migrations in
migrations/must be idempotent (CREATE TABLE IF NOT EXISTS, check-before-add);Upgrade::apply()records history inye_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 —
| Point | Fired at |
|---|---|
front.shell | before the page shell is emitted in index.php |
admin.editor.tail | end 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
pagesmanifest andRouterbranches 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=0removes it from the list and disables it, data stays for a future reinstall. - Uninstall
purge=1deletes own tables/options peruninstall; the admin creates an automatic backup first. plugin.<id>.*options are cleaned automatically; never declare shared tables intables.
Release
- [ ]
php -levery file; manifest matches actual files - [ ] Migrations idempotent (run twice,
--dry-runclean) - [ ] 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