Saltar al contenido
MovieMaster

Desarrolladores: plugins y themes

plugin.json and theme.json reference

10 min de lectura 12 apartados

En esta página

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 #

json
{
  "$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 #

FieldRequiredWhat it is
specYesFormat version: 1. Without spec (or with 0) the manifest is read as the legacy format; see Migrating from spec 0.
slugYesUnique 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.
nameYesName shown in the admin panel and the store.
versionYesSemantic version X.Y.Z. Each release bumps the version: the site compares versions to know whether it needs to run the upgrade.
descriptionRecommendedThe card text in Admin → Plugins or Themes, in English (it's the default text).
descriptionsNoTranslations of description by language code: {"es": "…", "pt": "…"}. The admin shows the one matching the site's language.
authorRecommendedA name ("Example Studio") or an object {"name": "…", "url": "https://…"}. The card reads "By …" and only links http(s) URLs.
licenseRecommendedLicense ("proprietary", "MIT", "GPL-2.0-or-later"…).
homepageNoThe extension's website.
$schemaNoURL 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 #

FieldDefaultWhat it is
mainplugin.phpPlugins 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.
autoloadsrc/Folder matching namespace. MyPlugin\Api\Client → src/Api/Client.php.
textdomainthe slugTranslation 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 #

json
"requires": {
  "core": "^0.9",
  "php": ">=8.2",
  "ext": ["curl", "intl"],
  "plugins": { "members": "^1.0" }
}
KeyWhat it checksIf not met
requires.coreMovieMaster's core version.Cannot be activated or installed. plugin:check fails.
requires.phpThe server's PHP version.Cannot be activated. plugin:check only warns (your local PHP may not match the server's).
requires.extLoaded PHP extensions (curl, intl, imagick…).Cannot be activated. plugin:check warns.
requires.pluginsOther 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:

php
if (!plugin_active('members')) {
    return; // no Members, no accounts: the plugin does nothing
}

Version constraints #

Constraints follow Composer's rules, strictly:

ConstraintAcceptsExample
^1.2From 1.2.0 up to before 2.0.01.2.0, 1.9.4
^0.9From 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.2From 1.2.0 up to before 2.0.01.2.0, 1.8.0
~1.2.3From 1.2.3 up to before 1.3.01.2.3, 1.2.9
>=8.28.2.0 or later8.2.0, 8.4.1
>=8.2 <9.0Both conditions at once (separated by a space)8.3.0
1.2.3Same as >=1.2.31.2.3, 2.0.0
* or emptyAny version (plugin:check warns you to declare the range you actually tested)—

Data the extension leaves behind #

json
"data": {
  "tables": ["my_plugin_votes"],
  "dirs": ["uploads/my-plugin"],
  "settings_prefix": "plugin.my-plugin."
}
KeyWhat it declaresFormat
data.tablesTables your migrations create.Name without the prefix (my_plugin_votes, not mm_my_plugin_votes).
data.dirsFolders you create outside the plugin's own folder.Path relative to content/ (uploads/my-plugin).
data.settings_prefixPrefix 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 uninstall fails 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.

FieldWho declares itMeaning
contractsA theme"My markup and my JavaScript fulfill this contract." Cinema declares ["player@1", "mylist@1", "install@1", "i18n@1"].
providesA 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:

json
"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 #

FieldWhat it is
parentSlug 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.
screenshotScreenshot 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.
contractsContracts the theme fulfills (see above).
colorsThe theme's own colors: {"primary": "#1d4ed8", "secondary": "#ffb020"}. Settings → Appearance shows them until the owner picks different ones.
budgetBudgets: {"inline_css": 20480, "js_initial": 5120} in bytes.
supportsFeatures the theme offers (custom-colors, custom-logo, pwa, series, auto-next, skip-intro, mylist). Informational.
settingsTheme 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 #

FieldWhat it is
update.channelWhere 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.tagsCategory 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:

FieldExample
capsCapabilities its screens use. To create actual capabilities, use the role_capabilities filter (PHP API).
frontend.externalThird-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:

json
{ "slug": "old", "name": "Old", "version": "1.0.0",
  "requires_core": ">=0.5", "requires_php": ">=8.1", "requires_ext": ["curl"] }

To move to spec 1:

  1. Add "spec": 1.
  2. Move requires_core → requires.core, requires_php → requires.php, and requires_ext → requires.ext.
  3. In a plugin with lang/, add textdomain and 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.
  4. In a theme, add screenshot.png.
  5. Pass plugin:check or theme:check.

Common validation errors #

plugin:check messageFix
folder name 'x' must equal the slug 'y'Rename the folder or the slug: they must match.
version 'x' is not semver X.Y.ZUse three numbers: 1.0.0, not 1.0 or v1.
requires.core '…' is not a valid constraintUnrecognized format; use ^0.9, >=0.9, or similar.
requires.core '…' does not include this coreYour constraint excludes the installed version.
plugin.php: top-level class/functionMove the class or function to src/ under your namespace.
autoload folder 'src/' for namespace … does not existCreate the folder or fix autoload.
data.tables '…': declare it without the table prefixRemove mm_ from the name.
… must not be in an extensionThere'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).

¿Te quedó alguna duda?

Escríbenos y te ayudamos con tu caso.

Hablar con nosotros
¿Hablamos?