Every plugin ships a plugin.json, and every theme a theme.json, at the root of its folder. Both use the same format (spec 1) and are read by the same class, MovieMaster\Extensions\Manifest. The manifest says who you are, what you need to run, and what data you leave on the site.
Full plugin example #
{
"$schema": "https://moviemaster.dev/schema/plugin-v1.json",
"spec": 1,
"slug": "my-plugin",
"name": "My Plugin",
"version": "1.2.0",
"description": "Adds a weekly ranking row to the homepage.",
"descriptions": { "es": "Añade a la portada una fila con el ranking de la semana." },
"author": { "name": "Example Studio", "url": "https://example.com" },
"homepage": "https://example.com/my-plugin",
"license": "proprietary",
"main": "plugin.php",
"textdomain": "my-plugin",
"namespace": "MyPlugin\\",
"autoload": "src/",
"requires": {
"core": "^0.9",
"php": ">=8.2",
"ext": ["curl"],
"plugins": { "members": "^1.0" }
},
"provides": [],
"data": {
"tables": ["my_plugin_votes"],
"dirs": ["uploads/my-plugin"],
"settings_prefix": "plugin.my-plugin."
},
"update": { "channel": "stable" },
"store": { "category": "home", "tags": ["ranking", "home"] }
}php bin/console.php make:plugin my-plugin generates one that's already valid. After editing it, check it with php bin/console.php plugin:check my-plugin.
Identity #
| Field | Required | What it is |
|---|---|---|
spec | Yes | Format version: 1. Without spec (or with 0) the manifest is read as the legacy format; see Migrating from spec 0. |
slug | Yes | Unique identifier: lowercase letters, numbers, and hyphens. Must match the folder name: the loader looks up the extension by its slug. Never change it after publishing. |
name | Yes | Name shown in the admin panel and the store. |
version | Yes | Semantic version X.Y.Z. Each release bumps the version: the site compares versions to know whether it needs to run the upgrade. |
description | Recommended | The card text in Admin → Plugins or Themes, in English (it's the default text). |
descriptions | No | Translations of description by language code: {"es": "…", "pt": "…"}. The admin shows the one matching the site's language. |
author | Recommended | A name ("Example Studio") or an object {"name": "…", "url": "https://…"}. The card reads "By …" and only links http(s) URLs. |
license | Recommended | License ("proprietary", "MIT", "GPL-2.0-or-later"…). |
homepage | No | The extension's website. |
$schema | No | URL of the JSON schema. Only useful for your editor's autocomplete. |
plugin:check warns (without failing) if description, author, or license is missing, because they show up in the admin and in the store.
Code #
| Field | Default | What it is |
|---|---|---|
main | plugin.php | Plugins only. Entry file that receives $plugin. Cannot declare global classes or functions. |
namespace | — | PSR-4 namespace for your classes, with the trailing backslash escaped: "MyPlugin\\". No Composer: the core registers the autoloader itself. |
autoload | src/ | Folder matching namespace. MyPlugin\Api\Client → src/Api/Client.php. |
textdomain | the slug | Translation domain for a plugin: __('my-plugin::key'). See translations. In a theme it's declared the same way, but its lang/ files are merged with the core's strings and requested with a dot (__('my_theme.key')); see templates. |
If you declare namespace, the autoload folder must exist or plugin:check fails. If you have a Lifecycle.php, its class must be <namespace>Lifecycle and extend \MovieMaster\Extensions\Lifecycle.
Requirements #
"requires": {
"core": "^0.9",
"php": ">=8.2",
"ext": ["curl", "intl"],
"plugins": { "members": "^1.0" }
}| Key | What it checks | If not met |
|---|---|---|
requires.core | MovieMaster's core version. | Cannot be activated or installed. plugin:check fails. |
requires.php | The server's PHP version. | Cannot be activated. plugin:check only warns (your local PHP may not match the server's). |
requires.ext | Loaded PHP extensions (curl, intl, imagick…). | Cannot be activated. plugin:check warns. |
requires.plugins | Other plugins, with their version: {"slug": "constraint"}. | plugin:check validates the format. On activation, the core still does not enforce it: check the dependency yourself in code (below). |
On activation, the admin shows in plain language everything that's missing (core version, PHP version, extensions), not just the first failure. The same happens on boot: an active plugin that stops meeting its requirements (for example, after the server's PHP version changes) gets quarantined, isn't loaded, and the admin warns about it.
To depend on another plugin, declare it in requires.plugins (it documents the relationship) and guard the code:
if (!plugin_active('members')) {
return; // no Members, no accounts: the plugin does nothing
}Version constraints #
Constraints follow Composer's rules, strictly:
| Constraint | Accepts | Example |
|---|---|---|
^1.2 | From 1.2.0 up to before 2.0.0 | 1.2.0, 1.9.4 |
^0.9 | From 0.9.0 up to before 0.10.0 (in 0.x, every minor version can break things) | 0.9.0, 0.9.54 |
~1.2 | From 1.2.0 up to before 2.0.0 | 1.2.0, 1.8.0 |
~1.2.3 | From 1.2.3 up to before 1.3.0 | 1.2.3, 1.2.9 |
>=8.2 | 8.2.0 or later | 8.2.0, 8.4.1 |
>=8.2 <9.0 | Both conditions at once (separated by a space) | 8.3.0 |
1.2.3 | Same as >=1.2.3 | 1.2.3, 2.0.0 |
* or empty | Any version (plugin:check warns you to declare the range you actually tested) | — |
Data the extension leaves behind #
"data": {
"tables": ["my_plugin_votes"],
"dirs": ["uploads/my-plugin"],
"settings_prefix": "plugin.my-plugin."
}| Key | What it declares | Format |
|---|---|---|
data.tables | Tables your migrations create. | Name without the prefix (my_plugin_votes, not mm_my_plugin_votes). |
data.dirs | Folders you create outside the plugin's own folder. | Path relative to content/ (uploads/my-plugin). |
data.settings_prefix | Prefix for your settings. | plugin.<slug>., which is where $plugin->setting() saves them. |
What's declared here has two effects, no matter what your code does:
- On uninstall from the admin, the core deletes those tables, folders, and settings, even if your
uninstallfails or doesn't exist. - On upgrade, the core copies those tables before changing files. If the upgrade fails, it restores them along with the previous folder.
Declare everything you create. A table not listed in data.tables is left orphaned on uninstall and has no backup on upgrade.
Contracts #
Contracts are versioned names (name@N) that connect themes and plugins without either one knowing the other's classes.
| Field | Who declares it | Meaning |
|---|---|---|
contracts | A theme | "My markup and my JavaScript fulfill this contract." Cinema declares ["player@1", "mylist@1", "install@1", "i18n@1"]. |
provides | A plugin | "I implement this contract." Money Player declares ["player@1"]; Members, account@1; Comments, comments@1. |
From code: active_theme()['contracts'] reads the theme's contracts, and plugin_providers('player@1') returns the active plugins that offer one.
The format is mandatory: ^[a-z0-9-]+@\d+$ (plugin:check and theme:check validate it). Today they're declarative: the core doesn't enforce the contract's shape beyond the name. What each one guarantees is in create themes. If you change a contract in an incompatible way, bump the number (player@2) and keep the old one while anyone still uses it.
Settings declared in the manifest #
A theme declares its options in settings. They appear in Settings, in the "Theme options · Name" group:
"settings": [
{ "key": "hero_autoplay", "type": "checkbox", "label": "Auto-advance the carousel", "default": true },
{ "key": "card_style", "type": "select", "label": "Cards", "default": "poster",
"options": { "poster": "Poster", "wide": "Landscape" } }
]They're saved as theme.<slug>.<key> and read with setting('theme.my-theme.card_style', 'poster'). Each entry accepts key (required), type, label, default, options, and help. The types are the same as in plugins: text, textarea, number, checkbox, select, color, url, list, media, secret, and info. An unknown type is shown as text, and theme:check warns.
Plugins declare their settings in code, with $plugin->setting() in plugin.php (see settings), which lets you translate labels and use hide_when and sanitize.
Theme-only fields #
| Field | What it is |
|---|---|
parent | Slug of the parent theme (usually default, Cinema) for a child theme. null or absent for a full theme. If the parent isn't installed, theme:check fails. |
screenshot | Screenshot of the homepage, screenshot.png by default. Required in spec 1: a real PNG, 880 × 660 (4:3), under 300 KB. The admin crops it from the top. Don't use movie posters or third-party photos. |
contracts | Contracts the theme fulfills (see above). |
colors | The theme's own colors: {"primary": "#1d4ed8", "secondary": "#ffb020"}. Settings → Appearance shows them until the owner picks different ones. |
budget | Budgets: {"inline_css": 20480, "js_initial": 5120} in bytes. |
supports | Features the theme offers (custom-colors, custom-logo, pwa, series, auto-next, skip-intro, mylist). Informational. |
settings | Theme options (see above). |
Budgets #
The effective budget is the lowest of the theme's, its parent's, and the core's (20,480 bytes of inline CSS and 5,120 of initial JavaScript). A child theme can lower it, but not raise it. The only exception is the inline CSS of a theme with its own complete critical.css, which can declare up to 32,768 bytes.
If a child theme goes over, its extra file isn't emitted (a warning is logged) and theme:check fails, reporting the exact byte count. More details in create themes.
Updates and the store #
| Field | What it is |
|---|---|
update.channel | Where it's distributed from. Extensions shipped inside the core's zip use core and update along with it; the rest are installed from the Hub store. For your own extension, use stable. Each version's channel (stable or beta) is chosen when you publish it to the Hub, and each site decides in Admin → Updates which one to follow. |
store.category, store.tags | Category and tags for the extension. Informational. |
When you upload a package to the Hub, the manifest's slug and version must match those of the release, or it's rejected. See validate, package, and publish.
Informational fields #
Some bundled manifests include fields the core doesn't enforce; they document the extension for whoever reviews it:
| Field | Example |
|---|---|
caps | Capabilities its screens use. To create actual capabilities, use the role_capabilities filter (PHP API). |
frontend.external | Third-party domains it may load on the public site (only on demand, never in the initial load). |
You can add your own fields: the core ignores them, and you read them with $plugin->manifest->get('my_field').
Migrating from spec 0 #
Legacy manifests had the requirements at the root. They still work, but the admin and plugin:check warn about them:
{ "slug": "old", "name": "Old", "version": "1.0.0",
"requires_core": ">=0.5", "requires_php": ">=8.1", "requires_ext": ["curl"] }To move to spec 1:
- Add
"spec": 1. - Move
requires_core→requires.core,requires_php→requires.php, andrequires_ext→requires.ext. - In a plugin with
lang/, addtextdomainand change__('key')to__('my-plugin::key'). In spec 0 your translations get mixed in with the core's, and another plugin can overwrite them; in spec 1 they live in their own domain. - In a theme, add
screenshot.png. - Pass
plugin:checkortheme:check.
Common validation errors #
plugin:check message | Fix |
|---|---|
folder name 'x' must equal the slug 'y' | Rename the folder or the slug: they must match. |
version 'x' is not semver X.Y.Z | Use three numbers: 1.0.0, not 1.0 or v1. |
requires.core '…' is not a valid constraint | Unrecognized format; use ^0.9, >=0.9, or similar. |
requires.core '…' does not include this core | Your constraint excludes the installed version. |
plugin.php: top-level class/function | Move the class or function to src/ under your namespace. |
autoload folder 'src/' for namespace … does not exist | Create the folder or fix autoload. |
data.tables '…': declare it without the table prefix | Remove mm_ from the name. |
… must not be in an extension | There's a forbidden file: .env, .git, *.pem, *.key, id_rsa*, *credentials*, .htpasswd, or SQLite databases. Remove it from the folder. |
contracts entry … must look like "name@1" | Fix the contract's name. |
screenshot.png missing (required in spec 1) | Add the screenshot (theme). |