Cada plugin lleva un plugin.json y cada theme un theme.json en la raíz de su carpeta. Los dos usan el mismo formato (spec 1) y los lee la misma clase, MovieMaster\Extensions\Manifest. El manifest dice quién eres, qué necesitas para funcionar y qué datos dejas en el sitio.
Ejemplo completo de plugin #
{
"$schema": "https://moviemaster.dev/schema/plugin-v1.json",
"spec": 1,
"slug": "mi-plugin",
"name": "Mi 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": "Estudio Ejemplo", "url": "https://ejemplo.com" },
"homepage": "https://ejemplo.com/mi-plugin",
"license": "proprietary",
"main": "plugin.php",
"textdomain": "mi-plugin",
"namespace": "MiPlugin\\",
"autoload": "src/",
"requires": {
"core": "^0.9",
"php": ">=8.2",
"ext": ["curl"],
"plugins": { "members": "^1.0" }
},
"provides": [],
"data": {
"tables": ["mi_plugin_votos"],
"dirs": ["uploads/mi-plugin"],
"settings_prefix": "plugin.mi-plugin."
},
"update": { "channel": "stable" },
"store": { "category": "home", "tags": ["ranking", "home"] }
}php bin/console.php make:plugin mi-plugin genera uno ya válido. Después de editarlo, comprueba con php bin/console.php plugin:check mi-plugin.
Identidad #
| Campo | Obligatorio | Qué es |
|---|---|---|
spec | Sí | Versión del formato: 1. Sin spec (o con 0) el manifest se lee como formato antiguo; ver Migrar desde spec 0. |
slug | Sí | Identificador único: minúsculas, números y guiones. Debe coincidir con el nombre de la carpeta: el cargador busca la extensión por su slug. No lo cambies nunca después de publicar. |
name | Sí | Nombre visible en el panel y en la tienda. |
version | Sí | Versión semántica X.Y.Z. Cada publicación sube la versión: el sitio compara versiones para saber si hay que ejecutar la actualización. |
description | Recomendado | Texto de la tarjeta en Admin → Plugins o Temas, en inglés (es el texto por defecto). |
descriptions | No | Traducciones de description por código de idioma: {"es": "…", "pt": "…"}. El panel muestra la del idioma del sitio. |
author | Recomendado | Un nombre ("Estudio Ejemplo") o un objeto {"name": "…", "url": "https://…"}. La tarjeta dice «Por …» y solo enlaza URL http(s). |
license | Recomendado | Licencia ("proprietary", "MIT", "GPL-2.0-or-later"…). |
homepage | No | Web de la extensión. |
$schema | No | URL del esquema JSON. Solo sirve para que tu editor autocomplete. |
plugin:check avisa (sin fallar) si falta description, author o license, porque se ven en el panel y en la tienda.
Código #
| Campo | Por defecto | Qué es |
|---|---|---|
main | plugin.php | Solo plugins. Archivo de entrada que recibe $plugin. No puede declarar clases ni funciones globales. |
namespace | — | Espacio de nombres PSR-4 de tus clases, con la barra final escapada: "MiPlugin\\". Sin Composer: el núcleo registra el autoload él solo. |
autoload | src/ | Carpeta que corresponde a namespace. MiPlugin\Api\Cliente → src/Api/Cliente.php. |
textdomain | el slug | Dominio de las traducciones de un plugin: __('mi-plugin::clave'). Ver traducciones. En un theme se declara igual, pero sus archivos lang/ se fusionan con las cadenas del núcleo y se piden con punto (__('mi_theme.clave')); ver plantillas. |
Si declaras namespace, la carpeta de autoload tiene que existir o plugin:check falla. Si tienes un Lifecycle.php, su clase debe ser <namespace>Lifecycle y extender \MovieMaster\Extensions\Lifecycle.
Requisitos #
"requires": {
"core": "^0.9",
"php": ">=8.2",
"ext": ["curl", "intl"],
"plugins": { "members": "^1.0" }
}| Clave | Qué comprueba | Si no se cumple |
|---|---|---|
requires.core | Versión del núcleo de MovieMaster. | No se puede activar ni instalar. plugin:check falla. |
requires.php | Versión de PHP del servidor. | No se puede activar. plugin:check solo avisa (tu PHP local puede no ser el del servidor). |
requires.ext | Extensiones de PHP cargadas (curl, intl, imagick…). | No se puede activar. plugin:check avisa. |
requires.plugins | Otros plugins, con su versión: {"slug": "restricción"}. | plugin:check valida el formato. Al activar, el núcleo todavía no lo impone: comprueba tú la dependencia en código (abajo). |
Al activar, el panel muestra en lenguaje claro todo lo que falta (versión del núcleo, de PHP y extensiones), no solo el primer fallo. Lo mismo ocurre al arrancar: un plugin activo que deja de cumplir sus requisitos (por ejemplo, tras cambiar la versión de PHP del servidor) se pone en cuarentena, no se carga y el panel avisa.
Para depender de otro plugin, decláralo en requires.plugins (documenta la relación) y protege el código:
if (!plugin_active('members')) {
return; // sin Members no hay cuentas: el plugin no hace nada
}Restricciones de versión #
Las restricciones siguen las reglas de Composer, estrictas:
| Restricción | Acepta | Ejemplo |
|---|---|---|
^1.2 | Desde 1.2.0 hasta antes de 2.0.0 | 1.2.0, 1.9.4 |
^0.9 | Desde 0.9.0 hasta antes de 0.10.0 (en 0.x, cada versión menor puede romper) | 0.9.0, 0.9.54 |
~1.2 | Desde 1.2.0 hasta antes de 2.0.0 | 1.2.0, 1.8.0 |
~1.2.3 | Desde 1.2.3 hasta antes de 1.3.0 | 1.2.3, 1.2.9 |
>=8.2 | 8.2.0 o superior | 8.2.0, 8.4.1 |
>=8.2 <9.0 | Las dos condiciones a la vez (separadas por espacio) | 8.3.0 |
1.2.3 | Igual que >=1.2.3 | 1.2.3, 2.0.0 |
* o vacío | Cualquiera (plugin:check te avisa de que declares el rango que probaste) | — |
Datos que deja la extensión #
"data": {
"tables": ["mi_plugin_votos"],
"dirs": ["uploads/mi-plugin"],
"settings_prefix": "plugin.mi-plugin."
}| Clave | Qué declara | Formato |
|---|---|---|
data.tables | Tablas que crean tus migraciones. | Nombre sin el prefijo (mi_plugin_votos, no mm_mi_plugin_votos). |
data.dirs | Carpetas que creas fuera de la del plugin. | Ruta relativa a content/ (uploads/mi-plugin). |
data.settings_prefix | Prefijo de tus ajustes. | plugin.<slug>., que es donde guarda $plugin->setting(). |
Lo declarado aquí tiene dos efectos, pase lo que pase en tu código:
- Al desinstalar desde el panel, el núcleo borra esas tablas, carpetas y ajustes, aunque tu
uninstallfalle o no exista. - Al actualizar, el núcleo copia esas tablas antes de cambiar archivos. Si la actualización falla, las restaura junto con la carpeta anterior.
Declara todo lo que creas. Una tabla que no está en data.tables se queda huérfana al desinstalar y no tiene copia de seguridad al actualizar.
Contratos #
Los contratos son nombres con versión (nombre@N) que conectan themes y plugins sin que uno conozca las clases del otro.
| Campo | Lo declara | Significa |
|---|---|---|
contracts | Un theme | «Mi marcado y mi JavaScript cumplen este contrato». Cinema declara ["player@1", "mylist@1", "install@1", "i18n@1"]. |
provides | Un plugin | «Implemento este contrato». Money Player declara ["player@1"]; Members, account@1; Comments, comments@1. |
Desde el código: active_theme()['contracts'] lee los del theme y plugin_providers('player@1') devuelve los plugins activos que ofrecen uno.
El formato es obligatorio: ^[a-z0-9-]+@\d+$ (plugin:check y theme:check lo validan). Hoy son declarativos: el núcleo no impone la forma del contrato más allá del nombre. Qué garantiza cada uno está en crear themes. Si cambias un contrato de forma incompatible, sube el número (player@2) y mantén el anterior mientras alguien lo use.
Ajustes declarados en el manifest #
Un theme declara sus opciones en settings. Aparecen en Ajustes, en el grupo «Opciones del theme · Nombre»:
"settings": [
{ "key": "hero_autoplay", "type": "checkbox", "label": "Avanzar el carrusel solo", "default": true },
{ "key": "card_style", "type": "select", "label": "Tarjetas", "default": "poster",
"options": { "poster": "Póster", "wide": "Apaisada" } }
]Se guardan como theme.<slug>.<key> y se leen con setting('theme.mi-theme.card_style', 'poster'). Cada entrada admite key (obligatoria), type, label, default, options y help. Los tipos son los mismos que en los plugins: text, textarea, number, checkbox, select, color, url, list, media, secret e info. Un tipo desconocido se muestra como texto y theme:check avisa.
Los plugins declaran sus ajustes en código, con $plugin->setting() en plugin.php (ver ajustes), que permite traducir las etiquetas y usar hide_when y sanitize.
Campos solo para themes #
| Campo | Qué es |
|---|---|
parent | Slug del theme padre (normalmente default, Cinema) para un child theme. null o ausente en un theme completo. Si el padre no está instalado, theme:check falla. |
screenshot | Captura de la portada, por defecto screenshot.png. Obligatoria en spec 1: PNG real, 880 × 660 (4:3), menos de 300 KB. El panel la recorta desde arriba. No uses carátulas ni fotos de terceros. |
contracts | Contratos que cumple el theme (ver arriba). |
colors | Colores propios: {"primary": "#1d4ed8", "secondary": "#ffb020"}. Ajustes → Apariencia los muestra mientras el dueño no haya elegido otros. |
budget | Presupuestos: {"inline_css": 20480, "js_initial": 5120} en bytes. |
supports | Funciones que el theme ofrece (custom-colors, custom-logo, pwa, series, auto-next, skip-intro, mylist). Informativo. |
settings | Opciones del theme (ver arriba). |
Presupuestos #
El presupuesto efectivo es el menor entre el del theme, el de su padre y el del núcleo (20 480 bytes de CSS en línea y 5 120 de JavaScript inicial). Un child theme puede bajarlo, pero no subirlo. La única excepción es el CSS en línea de un theme con su propio critical.css completo, que puede declarar hasta 32 768 bytes.
Si un child theme se pasa, su archivo extra no se emite (queda un aviso en el registro) y theme:check falla indicando los bytes exactos. Más detalles en crear themes.
Actualizaciones y tienda #
| Campo | Qué es |
|---|---|
update.channel | Por dónde se distribuye. Las extensiones que viajan dentro del zip del núcleo usan core y se actualizan con él; las demás se instalan desde la tienda del Hub. En una extensión tuya pon stable. El canal de cada versión (stable o beta) se elige al publicarla en el Hub, y cada sitio decide en Admin → Actualizaciones cuál sigue. |
store.category, store.tags | Categoría y etiquetas de la extensión. Informativos. |
Al subir un paquete al Hub, el slug y la version del manifest tienen que coincidir con los de la publicación, o se rechaza. Ver validar, empaquetar y publicar.
Campos informativos #
Algunos manifests incluidos llevan campos que el núcleo no aplica; documentan la extensión para quien la revisa:
| Campo | Ejemplo |
|---|---|
caps | Capacidades que usan sus pantallas. Para crear capacidades de verdad, usa el filtro role_capabilities (API PHP). |
frontend.external | Dominios de terceros que puede cargar en el sitio público (solo bajo demanda, nunca en la carga inicial). |
Puedes añadir tus propios campos: el núcleo los ignora y tú los lees con $plugin->manifest->get('mi_campo').
Migrar desde spec 0 #
Los manifests antiguos tenían los requisitos en la raíz. Siguen funcionando, pero el panel y plugin:check avisan:
{ "slug": "viejo", "name": "Viejo", "version": "1.0.0",
"requires_core": ">=0.5", "requires_php": ">=8.1", "requires_ext": ["curl"] }Para pasar a spec 1:
- Añade
"spec": 1. - Mueve
requires_core→requires.core,requires_php→requires.phpyrequires_ext→requires.ext. - En un plugin con
lang/, añadetextdomainy cambia__('clave')por__('mi-plugin::clave'). En spec 0 tus traducciones se mezclan con las del núcleo y otro plugin puede pisarlas; en spec 1 van en su propio dominio. - En un theme, añade
screenshot.png. - Pasa
plugin:checkotheme:check.
Errores frecuentes de validación #
Mensaje de plugin:check | Solución |
|---|---|
folder name 'x' must equal the slug 'y' | Renombra la carpeta o el slug: deben ser iguales. |
version 'x' is not semver X.Y.Z | Usa tres números: 1.0.0, no 1.0 ni v1. |
requires.core '…' is not a valid constraint | Formato no reconocido; usa ^0.9, >=0.9 o similar. |
requires.core '…' does not include this core | Tu restricción excluye la versión instalada. |
plugin.php: top-level class/function | Mueve la clase o función a src/ con tu namespace. |
autoload folder 'src/' for namespace … does not exist | Crea la carpeta o corrige autoload. |
data.tables '…': declare it without the table prefix | Quita mm_ del nombre. |
… must not be in an extension | Hay un archivo prohibido: .env, .git, *.pem, *.key, id_rsa*, *credentials*, .htpasswd o bases SQLite. Sácalo de la carpeta. |
contracts entry … must look like "name@1" | Corrige el nombre del contrato. |
screenshot.png missing (required in spec 1) | Añade la captura (theme). |