Plugin and Theme Developer Guide

Licensing

The Joinery license includes a plugin and theme exception. Plugins and themes you create are yours — you may license them under any terms you choose, including commercial terms. The PolyForm Noncommercial license covers Joinery's core code, not your extensions. See the Plugin and Theme Exception in LICENSE.md for the full text.

Overview

This guide outlines the current plugin and theme architecture after implementing the hybrid plugin/theme system. The system provides clear separation of concerns between plugins (backend-only) and themes (user-facing routing and presentation), while enabling themes to seamlessly integrate with plugin functionality through a sophisticated view resolution system.

Current Architecture

Plugin Architecture

Plugins provide:

• Data models and business logic
• Admin interfaces
• Database migrations
• API endpoints and webhooks
• Background processing
• User-facing views served under the plugin's URL namespace (see Plugin URL Namespace below)

Theme Architecture (Frontend + Routing)

Themes handle all user-facing functionality:

• URL routing and route definitions
• Public page templates and views
• Static assets (CSS, JS, images)
• User interface presentation
• Integration with plugin backend services
• Theme-specific class implementations (PublicPage, FormWriter extensions)
• CSS framework-specific customizations

Hybrid Plugin/Theme System

The system now supports a hybrid approach where:

• Plugin views can be accessed by themes through the view resolution fallback chain
• Themes can override plugin views by creating their own versions
• Multiple fallback paths ensure views are found even when themes don't provide them
• Theme-specific includes allow custom class implementations while maintaining compatibility

Route Processing Order

> For complete routing documentation (adding pages, route options, common patterns), see Routing. > This section covers how routing interacts with plugins and themes.

Routes are processed in this order:

1. Static routes - Direct file serving with caching
2. Theme routes - Theme-specific routing (serve.php in theme directory)
3. Plugin routes - Merged from active plugin serve.php files (namespaced)
4. Custom routes - Complex logic routes (in main serve.php)
5. Dynamic routes - Standard view and model routes
6. View fallback - Auto-discovery: theme → plugin namespace → base → 404

View Resolution Chain

When a view is requested, the system searches in this order:

1. Theme-specific view - /theme/{theme}/views/{view}.php
2. Plugin views (if plugin specified) - /plugins/{plugin}/views/{view}.php
3. Base system views - /views/{view}.php
4. 404 error if no view is found

Plugin Development

Where does each piece go?

Before diving in, a quick reference for the four common things plugins need to register. Use this to jump to the right section — each row points to the one canonical path.

Core File Guarantees

When developing plugins, the following core files are guaranteed to be available without requiring them:

• PathHelper - Use for all file operations
• Globalvars - Access configuration and settings
• SessionControl - Handle session and authentication

Example Usage in Plugins

// In any plugin file (admin, views, includes, etc.)

// ✅ CORRECT - Use directly without require
$settings = Globalvars::get_instance();
$theme = $settings->get_setting('theme_template');

$session = SessionControl::get_instance();
if (!$session->is_logged_in()) {
    // Handle not logged in
}

// Use PathHelper for other includes
require_once(PathHelper::getIncludePath('data/users_class.php'));

// ❌ WRONG - Don't do this
require_once(__DIR__ . '/../../includes/PathHelper.php');
require_once(__DIR__ . '/../../includes/Globalvars.php');

Why This Matters

1. Cleaner Code - No need for complex relative paths
2. Consistency - Same pattern everywhere
3. Performance - Files only loaded once
4. Maintainability - Easier to refactor

Common SessionControl methods

SessionControl::get_instance() is the only session entry point. The methods a plugin most often needs:

Plugin Naming

Plugin directory names appear directly in user-facing URLs (/{pluginname}/*, /profile/{pluginname}/*, /admin/{pluginname}/*), so choose them carefully:

• Must be distinctive — avoid generic names like events, billing, users
• Use the product or brand name — e.g. scrolldaddy, mailbox
• Short, lowercase, underscores for multi-word — e.g. dns_filtering not DnsFiltering
• Must not match a reserved system segment — the following names are rejected at activation: profile, admin, login, ajax, api, assets, theme, plugins, views, uploads, utils, tests, docs, specs, migrations, data, includes, logic, adm
• Must not clash with existing base view filenames — if views/profile/billing.php exists, a plugin named billing is rejected

Plugin URL Namespace

Every active plugin owns three URL prefixes automatically:

Index convention: When the URL has no trailing path (e.g. /profile/scrolldaddy), the router loads index.php from the corresponding views subdirectory.

Internal links must always use namespaced URLs:

// ✅ CORRECT
<a href="/profile/scrolldaddy/devices">My Devices</a>

// ❌ WRONG — only works on sites where this plugin IS the theme
<a href="/profile/devices">My Devices</a>

Plugin-as-theme shortcut: When a plugin is set as the active theme (theme_template = 'plugin'), its views are found through theme resolution. Both /profile/devices (clean URL via theme) and /profile/scrolldaddy/devices (namespaced URL) resolve to the same file.

Adding permissions or model binding: Use serve.php for routes that need more than a view file — but the route pattern must be within the namespace:

// plugins/myplugin/serve.php
$routes = [
    'dynamic' => [
        '/profile/myplugin/settings' => [
            'view'           => 'views/profile/settings',
            'min_permission' => 0,
        ],
    ],
];

Required Plugin Structure

/plugins/my-plugin/
├── plugin.json                  # Plugin metadata
├── serve.php                    # Only needed for routes requiring model/permission config
├── views/
│   ├── index.php                # /myplugin (landing page)
│   ├── pricing.php              # /myplugin/pricing
│   ├── profile/
│   │   ├── index.php            # /profile/myplugin
│   │   ├── dashboard.php        # /profile/myplugin/dashboard
│   │   └── settings.php        # /profile/myplugin/settings
│   └── admin/
│       ├── index.php            # /admin/myplugin
│       └── config.php           # /admin/myplugin/config
├── data/                        # Data model classes
├── logic/                       # Business logic (LogicResult pattern)
├── admin/                       # Admin interface files (/adm/admin_*)
├── ajax/                        # External webhooks only (page JS uses /api/v1 actions)
├── includes/                    # Helper classes and libraries
├── migrations/                  # Database migrations
└── uninstall.php               # (optional) external-cleanup hook — most plugins don't need one

Plugin.json Requirements

Minimum required plugin.json:

{
    "name": "My Plugin Name",
    "version": "1.0.0",
    "description": "Plugin description"
}

Complete plugin.json example:

{
    "name": "My Advanced Plugin",
    "description": "A comprehensive backend plugin",
    "version": "2.1.0",
    "author": "Your Name or Company",
    "license": "MIT",
    "homepage": "https://yoursite.com/plugin-docs",
    "requires": {
        "php": ">=8.0",
        "joinery": ">=1.0",
        "extensions": ["pdo", "json", "curl"],
        "composer": { "vendor/package": "^2.0" }
    },
    "depends": {
        "core-plugin": ">=1.0"
    },
    "host_installer": "provisioning/install_myplugin.sh",
    "provides": ["api-endpoint", "widget-support"],
    "tags": ["utility", "api", "backend"]
}

> Informational-only keys. author, license, homepage, tags, and provides are > documentation metadata — the system reads the manifest but does not act on these keys. > In particular, provides does not create any dependency, capability, or routing effect; > declaring provides: ["widget-support"] does not make another plugin able to depends on it. > The keys the loader actually consumes are name, version, description, requires, > depends/conflicts, settings, adminMenu, profileMenu, provisioners, > host_installer, receives_upgrades, included_in_publish, and deprecated/superseded_by.

Component Versioning

The version field is the source of truth for a component's released identity, and it carries through to its archive filename ({name}-{version}.tar.gz). Versioning is governed by three rules:

• Authors bump minor/major for meaningful releases. A new feature or behavior change is a minor (or major) bump you make in the manifest and commit.
• Publish auto-bumps the patch when content changed without a bump. At publish time, each component's working tree is content-hashed and compared against the last release's snapshot. If the files changed but the version did not, the publisher patch-bumps the manifest automatically and lists it in the publish summary for you to commit. This keeps archive filenames honest even when a content change ships without a manual bump. (See Deploy and Upgrade for the full decision rule.)
• Activation is gated on requires for plugins and themes. A component whose requires.joinery / requires.php / requires.extensions are not satisfied is refused activation with the specific failure reported. The gate runs only on activation, so an already-active component that newly fails requirements keeps running.

Declaring Dependencies

A plugin that needs something installed on the host declares it; the platform installs it at the moments that have the privileges to do so. There are three tiers, matched to what each dependency kind needs:

1. PHP extensions — requires.extensions. Declare the extension name (e.g. "extensions": ["imagick"]). The install tooling reads every bundled plugin's declarations via utils/list_dependencies.php and apt-installs the union at the root moments: Docker image build, install.sh site build, and upgrade.php on nodes. Activation checks extension_loaded() and refuses with the specific missing extension when the host somehow lacks it — the same gate applies to themes via theme.json requires.extensions. Core's own extension requirements live as ext-* entries in root composer.json, not in any plugin manifest.

2. Composer libraries — requires.composer. Declare {"vendor/package": "constraint"}. This is the one tier that installs at activation: PluginManager runs a reconcile (owned by ComposerValidator::reconcilePluginPackages()) that composer requires anything missing into the single root composer.json — there is one manifest, one vendor dir, one autoloader. Composer resolves each constraint; an unsatisfiable one refuses activation with composer's output. Because the root manifest holds one constraint per package, two plugins declaring the same package with different constraints is detected before composer runs and refuses activation naming both plugins (identical constraints are fine — declare what you need even if another plugin already ships it). The reconcile also runs at update_database time, covering deploys that add a dependency to an already-active plugin. Reconciled packages are recorded in composer.json extra.joinery-plugin-packages; utils/list_dependencies.php --orphans lists recorded packages no plugin declares anymore (deactivation never removes packages). Activation-time reconcile needs network access to the composer registry.

3. Host services and system packages — host_installer. For anything with real host-level complexity (daemons, config files, apt packages beyond PHP extensions), the plugin ships its own installer script and declares its path: "host_installer": "provisioning/install_myplugin.sh". The path must stay inside the plugin directory. The script's contract:

• Idempotent — it runs on every container start; re-running must be safe and cheap.
• Root — it may apt-get install and edit /etc; it should verify root and refuse otherwise.
• Non-interactive — set DEBIAN_FRONTEND=noninteractive; never prompt.
• Exit 0 when not-applicable — plugin inactive for the site, feature setting off, wrong platform.

Activation cannot run a host_installer (web requests lack root) — pair the installer with provisioners entries (below) so the admin UI detects missing host state and points at the fix; on Docker nodes a container restart runs the installer automatically.

Deprecation Fields

Plugins (and themes) support two optional deprecation fields:

{
    "name": "Old Plugin",
    "version": "1.0.0",
    "receives_upgrades": true,
    "included_in_publish": true,
    "deprecated": true,
    "superseded_by": "new-plugin"
}

Effect of deprecated: true:

• Admin list pages show a "Deprecated" badge and sort the extension to the bottom
• Activating a deprecated extension shows a warning message (activation is not blocked)
• Deprecated extensions are excluded from deployment archives for new installs
• Existing sites already running a deprecated extension continue to receive updates normally

Data Models

Plugins provide data models using the SystemBase pattern. For a complete annotated reference model covering every property — schema, REST API exposure/authorization, AI surface, deletion, and the Multi collection class — see docs/example_class.php.

// plugins/my-plugin/data/my_data_class.php
class MyData extends SystemBase {
    public static $prefix = 'mdt';                 // REQUIRED — see below
    public static $tablename = 'mdt_my_data';
    public static $pkey_column = 'mdt_id';

    public static $field_specifications = array(
        'mdt_id'          => array('type' => 'int8', 'is_nullable' => false, 'serial' => true),
        'mdt_usr_user_id' => array('type' => 'int8', 'is_nullable' => true),
        'mdt_name'        => array('type' => 'varchar(255)', 'is_nullable' => false, 'required' => true),
        'mdt_description' => array('type' => 'text', 'is_nullable' => true),
        'mdt_created'     => array('type' => 'timestamp(6)', 'is_nullable' => false, 'default' => 'now()'),
    );

    // REQUIRED on every model (may be empty): cleanup actions for permanent_delete().
    public static $permanent_delete_actions = array();

    // Define foreign key behavior (optional - defaults to cascade)
    protected static $foreign_key_actions = array(
        'mdt_usr_user_id' => array('action' => 'set_value', 'value' => User::USER_DELETED)
    );
}

Schema dialect — get this right. Column types are SQL type strings: int8 (with 'serial' => true for an auto-increment primary key), varchar(255), text, timestamp(6), numeric(10,2). Use 'is_nullable' => false (a schema constraint) to make a column NOT NULL; 'required' => true is a separate validation key checked on save. There is no 'length' key and no bare 'int' / 'varchar' — those produce no usable column. (The same correct dialect appears under Table Creation.)

The $prefix property is required. Every column in the table is named {$prefix}_{field}, and the constructor throws SystemBaseException('This object has no prefix.') if it is unset (includes/SystemBase.php:59). It is also the key FormWriter and the REST API use to map a field back to its model. $tablename and $pkey_column are likewise required; a Multi collection class additionally needs $model_class (see Writing a Multi (collection) class below).

REST API exposure & per-record scope. A core model is a CRUD resource only if it opts in with public static $api_readable = true; and/or $api_writable = true; (both default false); plugin models are never exposed to CRUD — expose plugin behaviour through action endpoints instead. For an exposed model, the default row scope is owner-or-staff (deny): a caller may touch a row only if they own it (the {prefix}_usr_user_id column matches the acting user) or they are staff (permission ≥ 5). Set public static $api_public_read = true; to make a resource world-readable (catalog content), or override authenticate_read($data) / authenticate_write($data) for a custom rule — copy the pattern from data/orders_class.php. See REST API → Per-record authorization.

Deletion Behavior: For complete documentation on defining foreign key actions, cascading deletes, soft-delete cascading patterns, and undelete strategies, see the Deletion System Documentation.

Writing a Multi (collection) class

Every single-row model has a companion Multi class (collection) in the same file, extending SystemMultiBase. It declares $model_class (the single-row class name) and implements getMultiResults(), which translates caller-supplied option keys into SQL filters:

class MultiMyData extends SystemMultiBase {
    public static $model_class = 'MyData';   // REQUIRED — the single-row class

    protected function getMultiResults($only_count = false, $debug = false) {
        $filters = array();

        // 1. Parameterized value (safe binding) — produces  mdt_usr_user_id = ?
        if (isset($this->options['user_id'])) {
            $filters['mdt_usr_user_id'] = array($this->options['user_id'], PDO::PARAM_INT);
        }

        // 2. Literal condition appended as-is — produces  mdt_delete_time IS NULL
        if (isset($this->options['active'])) {
            $filters['mdt_delete_time'] = 'IS NULL';
        }

        // 3. ILIKE / raw fragment — produces  mdt_name ILIKE '%term%'
        if (isset($this->options['name_like'])) {
            $filters['mdt_name'] = "ILIKE '%" . $this->options['name_like'] . "%'";
        }

        return $this->_get_resultsv2(static::$model_class::$tablename, $filters, $this->order_by, $only_count, $debug);
    }
}

Construct and use it:

$rows = new MultiMyData(
    array('user_id' => $uid, 'active' => true),   // $options → filter keys above
    array('mdt_created' => 'DESC'),               // $order_by
    20, 0                                          // $limit, $offset
);
$total = $rows->count_all();   // count ignoring limit/offset
$rows->load();                 // populate
foreach ($rows as $row) { /* $row is a MyData */ }

The constructor signature is __construct($options = array(), $order_by = array(), $limit = NULL, $offset = NULL, $operation = 'AND', $write_lock = FALSE). The option keys are whatever getMultiResults() reads (here user_id, active, name_like) — they are deliberately not the raw column names. Always read a Multi class's getMultiResults() to learn its accepted keys.

AI Auto-Discovery: To make a plugin model queryable by joinery_ai recipes, declare the three $ai_* static properties ($ai_readable, $ai_description, $ai_excluded_fields) on the class. Default-deny: omit them and the model stays invisible to AI tools. See the Joinery AI Plugin Documentation for the property contract and the auto-block regex.

Business Logic Files

Plugin logic files follow the same LogicResult pattern as core logic files. Every logic file in the codebase — core or plugin — uses one signature: function foo_logic(array $input): LogicResult. There is no second variant. For comprehensive documentation, see the Logic Architecture Guide.

// plugins/my-plugin/logic/my_feature_logic.php
<?php
function my_feature_logic(array $input): LogicResult {
    require_once(PathHelper::getIncludePath('includes/LogicResult.php'));
    require_once(PathHelper::getIncludePath('plugins/my-plugin/data/my_data_class.php'));

    // Business logic processing
    $data = new MyData($input['id'], TRUE);

    // Use LogicResult for consistent returns
    if (($input['action'] ?? null) === 'delete') {
        $data->soft_delete();
        return LogicResult::redirect('/plugins/my-plugin/admin/list');
    }

    return LogicResult::render(['data' => $data]);
}
?>

Key points for plugin logic files:

• Always use LogicResult::render(), LogicResult::redirect(), or LogicResult::error()
• Follow the naming convention: [feature]_logic.php with matching function name
• Include paths are relative to the plugin directory when using __DIR__
• Can be called from views, admin pages, or the router

Exposing API Actions

A plugin logic function becomes a REST API action by adding the same _logic_descriptor() companion core logic files use:

// plugins/my-plugin/logic/my_feature_logic.php

function my_feature_logic_descriptor(): array {
    return [
        'description'      => 'What this action does',
        'requires_session' => true,   // default: true
        'mutates'          => true,
        'input'            => [
            'device_id' => ['type' => 'int', 'required' => true],
        ],
    ];
}

The input schema drives boundary validation and appears in discovery — see docs/api.md for the field types and the legacy _logic_api() companion.

The action is addressed under the plugin's namespace — POST /api/v1/action/my-plugin/my_feature — and listed in GET /api/v1/actions as my-plugin/my_feature. Resolution goes directly to plugins/{plugin}/logic/{action}_logic.php; only active plugins resolve, and the namespace means a plugin action can never collide with a core action or another plugin's.

• requires_session => true actions run under session simulation as the API key's user, so SessionControl works exactly as it does on the web. Use $session->is_api_context() when a function needs to return a JSON-clean payload instead of view-shaped objects.
• Authorization defaults to the action surface's standard: the key needs the write capability (apk_permission >= 2). To override — e.g. a read-only action, or one requiring a higher user role — add an 'auth' block to the descriptor: 'auth' => ['capability' => 'read', 'min_user_permission' => 5]. The contract is enforced by ApiAuth::authorize(); see docs/api.md.
• An optional {action}_logic_form() companion exposes a server-driven form definition at GET /api/v1/form/{plugin}/{action} — see docs/api.md and docs/formwriter.md.
• Inputs arrive through the $input parameter (merged GET + JSON body). Do not read $_REQUEST — it never sees the JSON body.

Admin Interface

Plugin admin pages are accessed via the plugin admin discovery route: /plugins/{plugin}/admin/{page}

// plugins/my-plugin/admin/admin_my_plugin.php
<?php
// Core files are already available - no need to require them
// PathHelper, Globalvars, and SessionControl are pre-loaded

// Use PathHelper for other includes
require_once(PathHelper::getIncludePath('includes/AdminPage.php'));

$session = SessionControl::get_instance();
$session->check_permission(5);

$page = new AdminPage();
$page->admin_header([
    'title' => 'My Plugin',
    'menu-id' => 'my-plugin',
    'readable_title' => 'My Plugin Management'
]);

// Admin interface content here

$page->admin_footer();
?>

Two admin surfaces — which to use. A plugin can render admin pages two ways, and both resolve automatically:

Referencing plugin assets (CSS/JS) with cache-busting

A plugin's own assets live in plugins/{plugin}/assets/ and are served by the built-in static route /plugins/{plugin}/assets/* (the route enforces that the plugin is active and refuses to serve .php). There is no PluginHelper::asset() helper — cache-busting is done inline with filemtime(), the same mechanism themes use. Define a tiny closure in your view and reference assets through it:

$asset = function ($rel) {
    $path = PathHelper::getIncludePath('plugins/my-plugin/assets/' . $rel);
    return '/plugins/my-plugin/assets/' . $rel . '?v=' . (is_file($path) ? filemtime($path) : '1');
};
echo '<link rel="stylesheet" href="' . htmlspecialchars($asset('css/my-plugin.css')) . '">';
echo '<script defer src="' . htmlspecialchars($asset('js/my-plugin.js')) . '"></script>';

The ?v={filemtime} query changes whenever the file changes, so browsers refetch on every edit and otherwise cache. Always reference your assets by their namespaced /plugins/{plugin}/assets/… URL — never a relative path.

The inline closure above is for assets that belong to one page (a page-specific reader script, say). For a plugin's stylesheet — the sheet that styles its UI wherever it appears — declare it instead (next section); don't echo a <link> per page.

Plugin Stylesheets (Declarative)

Declare a plugin's stylesheets under the styles key in plugin.json — an array of paths relative to the plugin root. Every declared sheet loads on every page while the plugin is active, cache-busted by file mtime, emitted *after the .jy-ui kit and before the active theme's stylesheet. That position is deliberate: your rules resolve the kit's --jy-* design tokens, and a theme can still override them.

{
  "name": "My Plugin",
  "styles": ["assets/css/my-plugin.css"]
}

Because the sheet is global, scope every rule so it stays inert until your markup opts in — wrap your UI in .jy-ui and prefix classes .jy-{plugin}-* (e.g. .jy-ui .jy-myplugin-card { … }), or use a distinctive component prefix. No call site is needed; PluginHelper::renderActivePluginStyleLinks() emits the <link> tags from the head. Changes to styles take effect immediately (the manifest is read live from disk) — no activation or update_database step.

Plugin Menus (Declarative)

Plugins declare menu contributions in plugin.json under two keys:

• adminMenu — items in the admin sidebar (/admin/*).
• profileMenu — items in the member profile menu (logged-in avatar menu, logged-out auth links, etc.).

{
  "adminMenu": [
    {
      "slug": "my-plugin",
      "title": "My Plugin",
      "icon": "plug",
      "permission": 8,
      "order": 15,
      "items": [
        { "slug": "my-plugin-dashboard", "title": "Dashboard", "url": "/admin/my_plugin", "order": 1 },
        { "slug": "my-plugin-settings", "title": "Settings", "url": "/admin/my_plugin/settings", "order": 2 }
      ]
    }
  ]
}

{
  "adminMenu": [
    {
      "slug": "mailbox-reader",
      "title": "Mailbox",
      "url": "/plugins/mailbox/admin/admin_mailbox_reader",
      "parent": "emails",
      "permission": 5,
      "order": 10,
      "settingActivate": "mailbox_enabled"
    }
  ]
}

{
  "adminMenu": [
    { "slug": "my-tool", "title": "My Tool", "url": "/admin/my_tool", "icon": "wrench", "permission": 10, "order": 16 }
  ]
}

{
  "profileMenu": [
    {
      "slug": "scrolldaddy-filtering",
      "title": "Filtering",
      "url": "/profile/scrolldaddy",
      "icon": "shield",
      "visibility": "in",
      "permission": 1,
      "order": 75
    }
  ]
}

{
  "name": "My Plugin",
  "version": "1.0.0",
  "settings": [
    { "name": "myplugin_enabled", "default": "1" },
    { "name": "myplugin_max_items", "default": "50" },
    { "name": "myplugin_api_key", "default": "" }
  ]
}

"storage_profiles": ["MyPluginRawStore"]

"signals": {
  "myplugin.thing_happened": {
    "label": "Thing happened",
    "description": "A thing happened in My Plugin.",
    "category": "My Plugin",
    "payload": { "thing_id": "Thing id", "source_user_id": "Acting user id" },
    "notify": {
      "ntf_type": "system",
      "supports_topic": true,
      "default_email": false,
      "title_template": "A thing happened (#{thing_id})",
      "body_template": "Thing {thing_id} happened.",
      "link_template": "/admin/myplugin/things"
    }
  }
}

"signalSubscribers": {
  "myplugin_provisioner": {
    "file": "includes/MyProvisioner.php",
    "class": "MyProvisioner",
    "method": "handle_signal",
    "signals": ["subscription.expired"]
  }
}

Three states: active, inactive, and uninstalled (no row at all).

Discovery → Install → Activate ↔ Deactivate → Uninstall
              ↑                                    │
              └────────────── Install ─────────────┘

Install (PluginManager::install($name))

1. Fetches a fresh archive from the upgrade endpoint and extracts over plugins/{name}/, so plugins with included_in_publish: true on the upgrade server get current code on every install; plugins not in the publisher's catalog 404 silently and install proceeds with on-disk files.
2. Validates plugin structure and dependencies
3. Creates/updates database tables from data class $field_specifications (via DatabaseUpdater::runPluginTablesOnly())
4. Runs pending .sql migration files in plugins/{name}/migrations/
5. Records the plugin in plg_plugins with status inactive

// plugins/my-plugin/data/my_data_class.php
class MyData extends SystemBase {
    public static $prefix = 'mdt';
    public static $tablename = 'mdt_my_data';
    public static $pkey_column = 'mdt_my_data_id';

    public static $field_specifications = array(
        'mdt_my_data_id' => array('type'=>'int8', 'is_nullable'=>false, 'serial'=>true),
        'mdt_name' => array('type'=>'varchar(255)', 'required'=>true),
        'mdt_create_time' => array('type'=>'timestamp(6)', 'default'=>'now()'),
        'mdt_delete_time' => array('type'=>'timestamp(6)'),
    );
}

-- plugins/my-plugin/migrations/001_seed_categories.sql
INSERT INTO mpc_my_plugin_categories (mpc_name)
SELECT 'Default Category'
WHERE NOT EXISTS (SELECT 1 FROM mpc_my_plugin_categories WHERE mpc_name = 'Default Category');

plugins/my-plugin/settings_form.php

<?php
// plugins/my-plugin/settings_form.php
// $formwriter, $settings, and $session are already available

echo '<p>Configure My Plugin settings below.</p>';

$formwriter->textinput('my_plugin_api_url', 'API URL', [
    'value' => $settings->get_setting('my_plugin_api_url'),
    'placeholder' => 'e.g. https://api.example.com',
]);

$formwriter->passwordinput('my_plugin_api_key', 'API Key', [
    'value' => $settings->get_setting('my_plugin_api_key'),
    'placeholder' => 'Your API key',
]);

$formwriter->checkboxinput('my_plugin_enabled', 'Enable My Plugin', [
    'value' => $settings->get_setting('my_plugin_enabled'),
]);

// plugins/my-plugin/uninstall.php
function my_plugin_uninstall() {
    try {
        // Example: revoke an API key with an external service.
        // Tables are still available here if you need to read credentials
        // or enumerate records that reference external resources.
        $api_key = Globalvars::get_instance()->get_setting('my_plugin_api_key');
        if ($api_key) {
            external_api_revoke_key($api_key);
        }
        return true;
    } catch (Exception $e) {
        error_log("My Plugin uninstall failed: " . $e->getMessage());
        return false; // preserves tables + row so operator can fix and retry
    }
}

update_database handles the database side of plugin setup. Provisioners handle the other side: the external runtime resources a plugin needs that the database system knows nothing about — mail servers, relays, services, extensions, APIs.

A plugin can be installed and activated while one of these resources is missing or misconfigured, so the feature silently fails. Provisioning checks detect that on demand and surface it on the admin Plugins page (/admin/admin_plugins), with the command that fixes it where one exists. The provisioning check itself only detects and reports — it never runs a fix. Installation is the job of the plugin's declared host_installer (see Declaring Dependencies), which the platform runs automatically at container start, site build, and upgrade; a provisioner's script field typically points at that same installer so the admin UI names the fix.

Declaration

Declare runtime dependencies as a provisioners array in plugin.json, alongside settings and adminMenu:

"provisioners": [
  {
    "key": "inbound_mail_server",
    "label": "Inbound mail server (Postfix) running",
    "details": "Postfix on the host receives inbound mail and pipes it to the forwarder.",
    "check": { "type": "probe", "probe": "tcp", "host": "host-gateway", "port": 25 },
    "script": "provisioning/install_email.sh"
  },
  {
    "key": "outbound_forwarding_relay",
    "label": "Outbound mail relay for forwarding",
    "details": "Forwarded messages are relayed out through this SMTP server.",
    "check": { "type": "code", "call": "InboundEmailHealth::checkForwardingRelay" }
  }
]

code check — { "type": "code", "call": "Class::method" }. Use this for a resource your plugin reaches out to acquire (an SMTP relay, a database, an extension). The check IS your plugin's real acquisition routine, invoked on demand: it exercises the exact code path the feature uses, and it works the same inside a container or on bare metal because it only asks "can our code acquire this." A code check passing yields the verified state — the strongest pass.

probe check — { "type": "probe", "probe": "tcp", "host": "...", "port": N }. Use this for a dependency that pushes into your plugin rather than being acquired by it (an inbound mail server that pipes mail to a script — your code never connects to it, so a code check is structurally blind to it). The system opens a TCP connection within a 5-second enforced timeout. A probe passing yields the weaker reachable state — it proves something is listening, not that it is the right software or correctly configured.

probe is tcp in v1. host may be a literal IP/hostname or the token host-gateway, which resolves to the Docker bridge gateway inside a container and to 127.0.0.1 on bare metal — the portable way to say "reach a service on my host." Container-vs-bare-metal is decided by the deployment_environment flag recorded in Globalvars_site.php at install time (a reliable stored value, not a runtime heuristic). Prefer a literal 127.0.0.1 over host-gateway when the dependency is co-located with the app — same container or same host (as Email Forwarding's Postfix is); host-gateway is only needed to reach out of a container to a service running on the host itself.

The code check contract

call names a static method (Class::method). By convention the class is a *Health class in the plugin's includes/ directory — the system loads plugins/{plugin}/includes/{Class}.php automatically if the class is not already loaded. The method must:

• Perform the plugin's real acquisition step — or call the shared routine the feature itself uses. Factor each dependency into one acquisition routine called from both places so the check and the feature cannot diverge.
• Have no side effects — open and close a connection, never send a real message or write data. It verifies acquisition, not use.
• Be idempotent and cheap — it runs every time the Plugins page opens.

• Returns normally → verified.
• Throws ProvisioningCheckFailed → unmet. This is the expected failure signal. Catch the underlying acquisition exception (a PDOException, an SMTP error) and rethrow it as ProvisioningCheckFailed with a clean, human-readable message — that message is shown to the admin.
• Throws any other Throwable, or the class/method cannot be loaded → error (a broken check, reported distinctly from a missing dependency).

/theme/my-theme/
├── theme.json                  # Theme metadata and configuration
├── serve.php                   # Theme routing (optional)
├── views/                      # Theme templates and view overrides
│   ├── index.php
│   ├── page.php
│   └── plugin_overrides/       # Plugin view overrides
├── assets/                     # Theme assets
│   ├── css/
│   ├── js/
│   └── images/
└── includes/                   # Theme-specific classes
    ├── PublicPage.php          # Theme-specific PublicPage implementation
    └── FormWriter.php          # Theme-specific FormWriter (optional)

/theme/advanced-theme/
├── theme.json
├── serve.php                   # Includes plugin routes
├── views/
│   ├── index.php
│   ├── items/                  # Plugin view overrides
│   │   ├── list.php
│   │   └── detail.php
│   └── profile/                # Plugin view overrides
│       └── dashboard.php
├── assets/
└── includes/
    ├── PublicPage.php          # Bootstrap/UIKit/WordPress-specific implementation
    └── ThemeHelper.php         # Theme-specific utilities

// theme/my-theme/serve.php
$routes = [
    'dynamic' => [
        // Simple view routes (uses view resolution chain)
        '/my-page' => ['view' => 'views/my_page'],
        '/about' => ['view' => 'views/about'],
        
        // Model-based routes using plugin data
        '/item/{slug}' => [
            'model' => 'Item',
            'model_file' => 'plugins/items/data/items_class'
        ],
    ],
    
    'custom' => [
        // Complex routing logic
        '/custom-handler' => function($params, $settings, $session, $template_directory) {
            // Custom logic here
            require_once(PathHelper::getThemeFilePath('custom.php', 'views'));
            return true;
        },
    ],
];

// plugins/controld/serve.php
$routes = [
    'dynamic' => [
        // Routes must be within the plugin's namespace
        '/profile/controld/device_edit' => [
            'view'           => 'views/profile/device_edit',
            'min_permission' => 0,
        ],
        '/controld/create_account' => [
            'view' => 'views/create_account',
        ],
    ],
];

// theme/my-theme/views/items.php
<?php
require_once(PathHelper::getIncludePath('plugins/items/data/items_class.php'));

// Use plugin data models
$items = new MultiItem(['itm_active' => 1], ['itm_name' => 'ASC']);
$items->load();

foreach ($items as $item) {
    echo '<h3>' . $item->get('itm_name') . '</h3>';
    echo '<p>' . $item->get('itm_description') . '</p>';
}
?>

// theme/my-theme/views/items/list.php - Overrides plugin view
<?php
// This theme view will be used instead of plugins/items/views/items/list.php
// But can still access plugin data models and helpers
require_once(PathHelper::getIncludePath('plugins/items/data/items_class.php'));
require_once(PathHelper::getIncludePath('plugins/items/includes/ItemsHelper.php'));

$items = ItemsHelper::getActiveItems();
foreach ($items as $item) {
    // Theme-specific presentation
    include 'item_card_template.php';
}
?>

// theme/bootstrap-theme/includes/PublicPage.php
class PublicPage extends PublicPageBase {
    protected function getTableClasses() {
        return [
            'wrapper' => 'table-responsive',
            'table' => 'table table-striped table-hover',
            'header' => 'thead-dark'
        ];
    }
    
    // Bootstrap-specific implementations
    public function renderAlert($message, $type = 'info') {
        return "<div class='alert alert-{$type}' role='alert'>{$message}</div>";
    }
}

// In theme templates
<link rel="stylesheet" href="/theme/<?= $template_directory ?>/assets/css/style.css">
<script src="/theme/<?= $template_directory ?>/assets/js/app.js"></script>
<img src="/theme/<?= $template_directory ?>/assets/images/logo.png" alt="Logo">

// Enhanced asset management
<?php
$theme = ThemeHelper::getInstance();
?>
<link rel="stylesheet" href="<?= $theme->asset('css/bootstrap.min.css') ?>">
<link rel="stylesheet" href="<?= $theme->asset('css/theme.css') ?>">
<script src="<?= $theme->asset('js/theme.js') ?>"></script>

// Using theme.json configuration in templates
<?php
$theme_config = ThemeHelper::config('cssFramework', 'bootstrap');
if ($theme_config === 'bootstrap') {
    echo '<div class="container">';
} elseif ($theme_config === 'uikit') {
    echo '<div class="uk-container">';
}
?>

• receives_upgrades — customer-side, deploy preservation. If true, the on-disk copy is replaced from the upgrade payload during a deploy swap and the container reconciler will re-download it on boot if it goes missing. Set to false to keep a hand-edited copy across deploys. Mirrored to the database (thm_receives_upgrades); the admin Themes page can toggle it.
• included_in_publish — publisher-side, packaging filter. If true, publish_upgrade.php packages this theme into the upgrade archive and the marketplace catalog advertises it. If false, it is skipped. Manifest-only (no DB column, no admin UI).

{
  "name": "my-theme",
  "displayName": "My Custom Theme",
  "version": "1.0.0",
  "description": "A custom theme for my site",
  "author": "Your Name",
  "receives_upgrades": false,
  "included_in_publish": false,
  "requires": {
    "php": ">=7.4",
    "joinery": ">=1.0.0"
  },
  "cssFramework": "bootstrap",
  "formWriterBase": "FormWriterV2HTML5",
  "publicPageBase": "PublicPageBase"
}

{
  "name": "advanced-theme",
  "displayName": "Advanced Plugin-Integrated Theme",
  "version": "2.1.0",
  "description": "Theme with full plugin integration",
  "author": "Developer Team",
  "receives_upgrades": false,
  "included_in_publish": false,
  "requires": {
    "php": ">=8.0",
    "joinery": ">=1.0.0"
  },
  "supports_plugins": ["controld", "items"],
  "cssFramework": "bootstrap",
  "formWriterBase": "FormWriterV2HTML5",
  "publicPageBase": "PublicPageBase",
  "features": {
    "responsive": true,
    "dark_mode": true,
    "plugin_integration": true
  }
}

{
  "name": "custom-theme",
  "displayName": "Custom HTML5 Theme",
  "version": "1.0.0",
  "description": "Framework-agnostic theme with custom styling",
  "author": "Developer",
  "receives_upgrades": false,
  "included_in_publish": false,
  "requires": {
    "php": ">=7.4",
    "joinery": ">=1.0.0"
  },
  "cssFramework": "html5",
  "formWriterBase": "FormWriterV2HTML5",
  "publicPageBase": "PublicPageBase"
}

{
  "name": "scrolldaddy-theme",
  "displayName": "ScrollDaddy Theme",
  "version": "1.0.0",
  "requires_plugins": ["scrolldaddy"],
  "cssFramework": "html5",
  "formWriterBase": "FormWriterV2HTML5",
  "publicPageBase": "PublicPageBase"
}

$current_theme = ThemeHelper::getActive();

$css_framework = ThemeHelper::config('cssFramework', 'bootstrap', 'theme-name');
$supports_plugins = ThemeHelper::config('supports_plugins', [], 'theme-name');

// Preferred method in views - uses PublicPage wrapper
$formwriter = $page->getFormWriter('form1');

// Admin pages - use the page object
$formwriter = $page->getFormWriter('form1'); // $page is AdminPage instance

// Utilities and logic files - direct instantiation
require_once(PathHelper::getThemeFilePath('FormWriter.php', 'includes'));
$formwriter = new FormWriter('form1');

// plugins/controld/serve.php (REMOVED)
$routes = [
    '/profile/device_edit' => ['view' => 'views/profile/ctlddevice_edit'],
    '/create_account' => ['view' => 'views/create_account'],
];

// theme/sassa/serve.php (CURRENT)
$routes = [
    'dynamic' => [
        '/profile/device_edit' => ['view' => 'views/profile/ctlddevice_edit'],
        '/pricing' => ['view' => 'views/pricing'],
    ],
];

1. Create plugin directory under /plugins/{name}/ with plugin.json
2. Create data model classes in plugins/{name}/data/ with $field_specifications (tables created automatically on install)
3. Declare admin menus in plugin.json under the adminMenu key (see Admin Menus)
4. Declare default settings in plugin.json under the settings key (see Plugin Settings)
5. Create .sql migration files in plugins/{name}/migrations/ only if you have other initial data seeds (dropdowns, categories, reference rows)
6. Create admin interface in plugins/{name}/admin/ if needed
7. (Optional)* Create uninstall.php only if you have external cleanup to perform (API calls, filesystem, remote-service notifications) — the system handles tables, settings, menus, and scaffolding automatically. See Uninstall Script.
8. Install the plugin via Admin > System > Plugins (creates tables, runs SQL migrations)
9. Activate the plugin to make it live (seeds declared settings)
10. Test admin functionality via /plugins/{plugin}/admin/*
11. No user-facing routes - these go in themes

Creating a New Theme

1. Create theme directory structure with theme.json manifest
2. Choose CSS framework and implement corresponding PublicPage class
3. Add serve.php only if custom routing or plugin integration needed
4. Create view templates using plugin data models and ThemeHelper methods
5. Add theme assets (CSS, JS, images) in proper directory structure
6. Test view resolution chain to ensure plugin view fallbacks work
7. Validate theme.json accuracy against actual implementations
8. Test integration with existing plugins using the hybrid system

Integrating Plugin and Theme

1. Plugin provides backend services and data models through SystemBase classes
2. Theme creates user-facing routes that use plugin models via serve.php
3. Theme templates use plugin data through proper model loading and ThemeHelper
4. View resolution chain allows themes to override plugin views while maintaining fallbacks
5. Plugin admin remains separate from theme routing via /plugins/{plugin}/admin/*
6. Theme.json documents integration with supported plugins and framework choices
7. CSS framework consistency maintained between plugin data and theme presentation

Debugging and Troubleshooting

Route Debugging

Enable route debugging with URL parameter:

http://example.com/any-page?debug_routes=1

This shows detailed routing information in HTML comments.

Common Issues

404 on plugin admin pages:

• Check plugin directory name matches URL
• Verify admin file exists in plugins/{plugin}/admin/
• Check file permissions

• Ensure plugin data class is properly included using PathHelper
• Verify plugin is installed and tables exist
• Check data model usage syntax and constructor parameters

• Check view path format in routes (should not start with /)
• Test view resolution chain: theme → plugin namespace → base
• For auto-discovered views, confirm URL matches /profile/{pluginname}/... pattern and file exists at plugins/{pluginname}/views/profile/....php
• For explicit routes, confirm the route pattern is within the plugin namespace

• Verify theme.json cssFramework matches actual implementation
• Check PublicPage class extends proper base and implements getTableClasses()
• Ensure the theme's FormWriter.php extends FormWriterV2HTML5 (the HTML renderer used by every theme)
• Validate CSS classes match framework documentation

• Verify asset paths use correct theme directory
• Check file exists in theme/{theme}/assets/
• Ensure web server can serve static files
• Test ThemeHelper::asset() method for enhanced asset management

• Distinguish between theme includes (direct) vs views (resolution chain)
• Use proper require_once(PathHelper::getIncludePath()) for includes
• Check abstract method implementation in theme-specific classes
• Verify class file naming conventions match theme requirements

Cookie Consent Integration

If your plugin adds analytics or marketing scripts to public pages, you should wrap them for GDPR/CCPA consent compliance.

Using ConsentHelper to wrap scripts:

require_once(PathHelper::getIncludePath('includes/ConsentHelper.php'));
$consent = ConsentHelper::get_instance();
echo $consent->wrapTrackingCode('<script>...your tracking code...</script>', 'analytics');

Or manually add the consent attribute to script tags:

<script type="text/plain" data-joinery-consent="analytics">
  // This script only runs after user consents to analytics
</script>

Consent categories:

• analytics - For analytics and tracking scripts (e.g., Google Analytics)
• marketing - For advertising and remarketing scripts (e.g., Facebook Pixel)

CSS Framework Integration

CSS Frameworks and FormWriter

A theme's cssFramework declares which CSS its chrome loads; FormWriter is unaffected and always renders semantic HTML5 via FormWriterV2HTML5.

Bootstrap Themes:

• CSS Framework: bootstrap
• Table Classes: table, table-striped, table-hover
• Container Classes: container, container-fluid

• CSS Framework: html5 or custom
• Pure semantic HTML5 markup
• No framework-specific classes
• Themes can apply any CSS styling

Framework-Specific Implementations

PublicPage Class Implementations:

// Bootstrap theme
protected function getTableClasses() {
    return [
        'wrapper' => 'table-responsive',
        'table' => 'table table-striped table-hover',
        'header' => 'thead-dark'
    ];
}

// UIKit theme  
protected function getTableClasses() {
    return [
        'wrapper' => 'uk-overflow-auto',
        'table' => 'uk-table uk-table-striped', 
        'header' => 'uk-table-header'
    ];
}

// WordPress theme
protected function getTableClasses() {
    return [
        'wrapper' => 'table-wrapper',
        'table' => 'wp-list-table widefat fixed striped',
        'header' => 'thead'
    ];
}

Current Plugin Status

Active Plugins

ControlD (Backend-only)

• Location: /plugins/controld/
• Admin: /plugins/controld/admin/*
• Data models: Account, Device, Filter, etc.
• User routes: Moved to sassa theme

• Location: /plugins/items/
• Admin: /plugins/items/admin/*
• Data models: Item, ItemRelation, etc.
• User routes: Moved to sassa theme

Theme Integration Examples

Sassa Theme (Plugin-enabled, Bootstrap)

• CSS Framework: bootstrap
• Includes ControlD routes: /profile/*, /pricing
• Includes Items routes: /items, /item/{slug}
• File: /theme/sassa/serve.php
• Custom PublicPage with Bootstrap table classes

• CSS Framework: wordpress
• PublicPage with WordPress-specific table classes
• FormWriter using default base
• Theme.json accurately reflects implementation

• CSS Framework: uikit
• PublicPage with UIKit table classes
• Theme.json specifies UIKit framework
• Custom styling for UIKit components

• Falcon (Bootstrap), Tailwind (Tailwind CSS), Default (minimal)
• Each with framework-appropriate implementations
• Clean separation of concerns maintained

Best Practices Summary

For Plugin Developers

1. Backend-only focus - No user-facing routes or views
2. Proper data models using SystemBase patterns
3. Admin interfaces accessible via /plugins/{name}/admin/*
4. Clean uninstall scripts for data cleanup
5. Version management through plugin.json

For Theme Developers

1. Framework consistency - Match CSS framework to implementations
2. Accurate manifests - theme.json should reflect actual code
3. View resolution - Leverage the fallback chain effectively
4. Plugin integration - Use data models, not direct plugin coupling
5. Asset management - Proper theme asset organization
6. Abstract methods - Implement required PublicPageBase methods
7. Base class render methods - Call $this->render_notification_icon($menu_data) in top_right_menu() for notifications; override only if theme needs different markup

For System Integration

1. Clear separation - Plugins (backend) vs Themes (frontend)
2. Flexible routing - Theme serve.php can include plugin routes
3. View fallbacks - Automatic resolution chain prevents 404s
4. Framework support - Multiple CSS frameworks supported cleanly
5. Maintainability - Updates to plugins don't break theme functionality

Plugin Theme System

Overview

The plugin theme system allows plugins to act as complete theme providers, replacing the entire user interface while maintaining all plugin functionality. This enables white-label solutions, complete UI replacements, and branded experiences.

How the System Works

1. PathHelper intercepts theme file requests and redirects to plugin directory for PHP classes
2. RouteHelper sets template directory to plugin path for view loading
3. ThemeHelper serves assets from plugin directory instead of theme directory
4. Admin Settings provides UI for selecting which plugin provides the theme

Three Types of Plugins

1. Feature Plugins (Standard)

• Work within existing theme framework
• Add new routes under /[plugin-name]/*
• Can provide admin interfaces
• Cannot override system views or routes

/plugins/bookings/
├── plugin.json
├── serve.php
├── admin/
│   └── manage_bookings.php
├── views/
│   └── booking_list.php
└── assets/
    └── js/bookings.js

2. Theme Provider Plugins

Required Files:

/plugins/controld/
├── plugin.json (with "provides_theme": true)
├── serve.php
├── includes/
│   ├── PublicPage.php (required - base page class)
│   └── FormWriter.php (required - form generation)
├── views/
│   ├── index.php (homepage view)
│   ├── profile.php (user profile)
│   └── [other system view overrides]
└── assets/
    ├── css/style.css
    ├── js/main.js
    └── img/logo.png

How Theme Provider Mode Works:

1. Admin selects "plugin" as the theme
2. Admin selects specific plugin (e.g., "controld") as the theme provider
3. System modifications activate: - PathHelper loads PHP classes from /plugins/controld/includes/ - RouteHelper loads views from /plugins/controld/views/ - ThemeHelper loads assets from /plugins/controld/assets/
4. Plugin provides complete UI while system handles core functionality

3. Hybrid Plugins

Behavior Modes:

• Feature Mode: When regular theme active, provides features within that theme
• Theme Mode: When selected as theme provider, replaces entire UI
• Same codebase, different activation modes

System Configuration Documentation

New Database Settings

active_theme_plugin

• Type: String (plugin directory name)
• Default: Empty string
• Purpose: Specifies which plugin provides the complete UI when plugin theme is active
• Valid Values: Must match an installed plugin directory name
• Dependencies: Only used when theme_template = 'plugin'
• Example: 'controld' to use ControlD plugin as theme

Modified Settings

theme_template

• New Option: 'plugin' - Delegates all theme functionality to a plugin
• Existing Options: 'falcon', 'sassa', 'tailwind', etc.

Admin Interface Documentation

Settings Page Updates (/adm/admin_settings.php)

Theme Selection Enhancement: When "Plugin-Provided Theme" is selected from the theme dropdown:

1. A new dropdown appears labeled "Active Theme Plugin"
2. Dropdown populates with all installed plugins
3. Plugins with "provides_theme": true are prioritized
4. Help text explains the plugin must provide theme infrastructure

• Plugin selector is hidden when regular themes are selected
• Plugin selector shows immediately when "plugin" theme is selected
• Settings save normally through existing form processing

Technical Implementation Notes

File Resolution Order

When plugin theme is active, the system checks for files in this order:

For PHP Classes (via PathHelper):

1. /plugins/{active_plugin}/includes/{file}
2. /theme/plugin/includes/{file} (fallback)
3. /includes/{file} (system fallback)

1. /plugins/{active_plugin}/views/{file}
2. /views/{file} (system fallback)

1. /plugins/{active_plugin}/assets/{file}
2. /theme/plugin/assets/{file} (shouldn't exist)
3. Current route's plugin assets (existing behavior)

Performance Considerations

• Additional Database Queries: One extra query to get active_theme_plugin setting
• File Existence Checks: Additional is_dir() and file_exists() checks
• Caching Opportunity: Could cache plugin theme selection in session
• Impact: Minimal - only adds conditional checks when plugin theme active

Security Considerations

• Plugin Validation: System should verify plugin exists before activation
• Fallback Strategy: Falls back to safe defaults if plugin missing
• No New Attack Vectors: Uses existing file inclusion mechanisms
• Admin Only: Theme selection requires admin permissions