Del código en tu carpeta a una extensión que cualquier sitio puede instalar y actualizar sin miedo: las herramientas de consola, qué comprueba la validación, cómo se arma el zip, qué pasa en el sitio al instalar o actualizar y qué promete el núcleo sobre la compatibilidad.
Herramientas de consola #
Todas se ejecutan desde la carpeta del CMS:
php bin/console.php make:plugin mi-plugin [--name="Mi Plugin"] [--namespace=MiPlugin] [--description=…] [--force]
php bin/console.php make:migration mi-plugin create_mi_plugin_items_table [--table=mi_plugin_items]
php bin/console.php make:theme mi-theme [--parent=default] [--name=…] [--force]
php bin/console.php plugin:check mi-plugin # o --all
php bin/console.php theme:check mi-theme # o --all
php bin/console.php ext:pack plugin mi-plugin [--out=dist]
php bin/console.php hooks:list [--type=action|filter] [--where] [--json] [--undocumented]| Comando | Qué hace |
|---|---|
make:plugin | Crea content/plugins/<slug>/ con plugin.json spec 1, plugin.php, Lifecycle.php, src/Plugin.php y lang/{es,en}.php. No lo activa. Pasa plugin:check tal cual sale. |
make:migration | Crea la siguiente migrations/NNNN_<nombre>.php del plugin. Con --table, o con un nombre create_<tabla>_table, trae ya el esqueleto de create. Recuerda declarar la tabla en data.tables. |
make:theme | Crea un theme hijo en content/themes/<slug>/ que hereda todo del padre. Ver crear themes. |
plugin:check, theme:check | Validan la extensión (tabla siguiente). Salen con código 1 si hay errores; los avisos no fallan. Admiten el slug o una ruta. |
ext:pack | Valida y, si no hay errores, genera el zip para distribuir. |
hooks:list | Lista todos los hooks que dispara el código (núcleo, themes y plugins instalados). --where añade el archivo y la línea donde se dispara cada uno. |
Qué comprueba la validación #
Manifest #
| Comprobación | Nivel |
|---|---|
La carpeta se llama igual que el slug. | error |
version es semver X.Y.Z. | error |
spec es una versión que este núcleo entiende. Sin spec se trata como el formato antiguo (spec 0). | error / aviso |
requires.core y requires.php se entienden y aceptan la versión instalada. Un formato desconocido nunca es compatible. | error |
requires.core es *: conviene declarar el rango que has probado. | aviso |
Faltan name, description, author… (se muestran en el panel y en la tienda). | aviso |
requires.plugins, provides y contracts tienen el formato correcto (nombre@1). | error |
textdomain válido y cada lang/*.php devuelve un array. | error |
Plugin #
| Comprobación | Nivel |
|---|---|
El archivo main existe. | error |
plugin.php no declara clases ni funciones globales: el núcleo puede cargarlo dos veces (al desinstalar). | error |
La carpeta de autoload existe. | error |
Lifecycle.php declara la clase esperada y hereda de MovieMaster\Extensions\Lifecycle. | aviso |
data.tables, data.dirs y data.settings_prefix son coherentes (tablas sin prefijo, carpetas dentro de content/). | error / aviso |
Cada ajuste tiene key y un tipo conocido. | error / aviso |
Las migraciones se llaman NNNN_snake_case.php. | aviso |
Theme #
Los errores y avisos propios de los themes (captura de pantalla, padre, presupuesto de CSS, plantillas que no compilan) están en crear themes.
Archivos #
| Comprobación | Nivel |
|---|---|
Todos los .php pasan el análisis de sintaxis de PHP. | error |
No hay archivos prohibidos: .env (también .env.example), *.pem, *.key, *.p12, *.pfx, llaves id_rsa/id_ed25519, cualquier nombre con credentials, .htpasswd, bases de datos *.sqlite/*.db, ni la carpeta .git. | error |
Carpetas que el empaquetado dejará fuera (node_modules, .idea, .vscode…). | aviso |
Empaquetar #
php bin/console.php ext:pack plugin mi-plugin --out=distdist/mi-plugin-1.2.0.zip (14 files, 38.2 KB)
sha256 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
publish: php bin/console.php hub:publish --type=plugin --slug=mi-plugin --version=1.2.0 --file=dist/mi-plugin-1.2.0.zipEl sha256 identifica el paquete exacto: inclúyelo si distribuyes el zip por tu cuenta. La línea publish es la que usa el equipo de MovieMaster para subirlo al Hub; necesita un token de publicación que solo tiene la integración continua del Hub.
El zip:
- Se genera solo si la validación no tiene errores.
- Contiene una sola carpeta
mi-plugin/en la raíz, con el manifest dentro. Es lo que esperan la tienda y el botón Subir del panel. - Deja fuera
.git,.svn,node_modules,.idea,.vscode,.DS_Store,Thumbs.db, otros.zip,.phpunit.cachey los archivos temporales de editor (*~). - Se llama
<slug>-<version>.zip, con la versión del manifest.
Antes de distribuirlo, instálalo en un sitio limpio (por ejemplo, el de demo:seed) desde Admin → Plugins → Subir plugin y actívalo. Es la prueba más fiel de lo que verá el usuario.
Qué no debe ir en el paquete #
- Credenciales, claves de API o tokens. Los pide el plugin como ajuste de tipo
secret. - Dependencias de desarrollo y fuentes sin compilar, si no hacen falta en el sitio.
- Datos del sitio donde lo desarrollaste: medios, cachés, registros, bases de datos.
- Vídeos o archivos pesados que el sitio pueda descargar al activarse.
Instalar y actualizar en un sitio #
Subida manual #
Admin → Plugins → Subir plugin (o Themes → Subir theme) acepta el zip de ext:pack. El núcleo:
- Abre el zip y busca el manifest en la raíz o en su única carpeta.
- Rechaza el paquete si
requires.coreno acepta la versión instalada. - Coloca la carpeta en
content/plugins/<slug>/(ocontent/themes/<slug>/), sustituyendo la que hubiera. - Registra la versión. La extensión se queda como estaba: activa si ya lo estaba, inactiva si es nueva.
Al activar, el núcleo carga el plugin de prueba antes de marcarlo como activo, ejecuta las migraciones pendientes y llama a install() (primera vez) o a upgrade($desde, $hasta) (si la versión registrada era otra) y luego a activate(). Si algo lanza una excepción, el plugin se queda desactivado y el error se muestra en el panel.
Actualización desde la tienda #
Las extensiones que se instalan y actualizan desde el Hub siguen un proceso con vuelta atrás automática:
- Descarga el zip y comprueba su
sha256y la firma del Hub. Si no cuadran, lo borra sin abrirlo. - Comprueba que el
slugdel zip es el esperado y querequires.coreacepta el núcleo instalado. - Analiza la sintaxis de todos los
.phpde la versión nueva. - Hace copia de la carpeta actual y de las tablas declaradas en
data.tables. - Pone el código nuevo, ejecuta las migraciones y llama a
upgrade($desde, $hasta). - Pide la portada del sitio. Una respuesta 5xx (o ninguna) cuenta como fallo.
- Si cualquier paso falla, restaura la carpeta y las tablas y deja el sitio exactamente como estaba. El error queda en el registro.
Por eso conviene que tus migraciones y tu upgrade() sean rápidos y que las tablas que tocan estén en data.tables: son las únicas que se copian y se restauran.
Cuando el núcleo cambia de versión #
En cada petición, el núcleo comprueba requires.core, requires.php, requires.ext y requires.plugins de cada plugin activo. Si alguno ya no se cumple (por ejemplo, el sitio se actualizó a un núcleo fuera de tu rango), el plugin se desactiva solo, sin cargar su código, y el panel muestra el motivo. Lo mismo pasa si el plugin lanza una excepción al cargarse.
Después de actualizar el núcleo se ejecutan también las migraciones pendientes de los plugins activos.
Publicar en la tienda #
La tienda del Hub (Admin → Tienda en cada sitio) la gestiona el equipo de MovieMaster. Para publicar una extensión, gratuita o de pago, escríbenos desde contacto con el zip de ext:pack y una descripción.
Al publicar una versión en el Hub:
- El
type, elslugy laversionde la publicación tienen que coincidir con el manifest del zip, o se rechaza. - Las versiones son inmutables: no se puede volver a publicar la misma versión. Para corregir algo, sube el número (
1.2.1). - Cada versión va a un canal,
stableobeta. Cada sitio elige en Admin → Actualizaciones qué canal sigue. - Una versión publicada se puede retirar: deja de ofrecerse y de poder descargarse.
- Los sitios preguntan por novedades cada 12 horas y al abrir Admin → Actualizaciones. Solo se les ofrece lo que es compatible con su núcleo y su PHP.
Prepara para cada versión unas notas cortas: qué cambia para quien la usa, si hay que hacer algo a mano y si corrige un fallo de seguridad.
Versiones de tu extensión #
Numera con semver:
| Cambio | Ejemplo | Sube |
|---|---|---|
| Corrección que no cambia nada visible para otros | Un error al guardar | Parche: 1.2.0 → 1.2.1 |
| Funciones nuevas, compatibles con lo anterior | Un ajuste o un hook nuevo | Menor: 1.2.1 → 1.3.0 |
| Algo deja de funcionar como antes | Quitas un hook, cambias una tabla o el formato de un ajuste | Mayor: 1.3.0 → 2.0.0 |
- Declara en
requires.coreel rango que has probado:make:pluginpone^<menor actual>, por ejemplo^0.9. - Si quitas o renombras un hook tuyo, mantén el viejo una temporada con
do_action_deprecated()oapply_filters_deprecated(). - Si cambias la forma de un contrato que ofreces (
provides), publica una versión nueva del contrato (player@2) y mantén la anterior mientras alguien la use.
Política de compatibilidad #
Lo que el núcleo promete a las extensiones:
| Nivel | Qué incluye | Garantía |
|---|---|---|
| Estable | Los hooks de la referencia de hooks, las funciones y clases de la API PHP, el formato del manifest y el contexto $plugin. | No cambian de forma incompatible dentro de una misma versión menor (0.9.x). Si un hook se retira, se sigue disparando con aviso en el registro durante al menos dos versiones menores. |
| Contratos | player@1, mylist@1, comments@1… | Un cambio incompatible crea una versión nueva del contrato (@2); la anterior se mantiene mientras haya themes y plugins que la usen. |
| Interno | Todo lo demás: controladores del panel, clases de Catalog, Update, Extensions, tablas del núcleo, el HTML del panel. | Puede cambiar en cualquier versión. No dependas de ello. |
Mientras el núcleo esté en 0.x, cada versión menor (0.9 → 0.10) puede traer cambios incompatibles, avisados en el changelog. Por eso ^0.9 no acepta 0.10: es intencionado. Cuando salga una menor nueva, prueba tu extensión y publica una versión con el rango ampliado.
Para saber qué hooks existen de verdad en tu versión, consulta hooks:list: lee el código, así que nunca se desfasa.
Antes de cada versión #
- [ ]
plugin:check/theme:checksin errores. - [ ] Probada en una instalación limpia y actualizando desde la versión anterior.
- [ ] Probada con el modo seguro en mente: sin errores en
content/logs/app.log. - [ ] Migraciones nuevas declaradas y sus tablas en
data.tables. - [ ]
versionsubida en el manifest y notas de versión escritas. - [ ] Textos traducidos en todos los idiomas que incluyes.
- [ ]
ext:packgenerado desde una copia limpia (sin archivos locales ni secretos).