Saltar al contenido
MovieMaster

Desarrolladores: plugins y themes

Validar, empaquetar y publicar

11 min de lectura 7 apartados

En esta página

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:

bash
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]
ComandoQué hace
make:pluginCrea 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:migrationCrea 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:themeCrea un theme hijo en content/themes/<slug>/ que hereda todo del padre. Ver crear themes.
plugin:check, theme:checkValidan la extensión (tabla siguiente). Salen con código 1 si hay errores; los avisos no fallan. Admiten el slug o una ruta.
ext:packValida y, si no hay errores, genera el zip para distribuir.
hooks:listLista 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ónNivel
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ónNivel
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ónNivel
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 #

bash
php bin/console.php ext:pack plugin mi-plugin --out=dist
text
dist/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.zip

El 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.cache y 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:

  1. Abre el zip y busca el manifest en la raíz o en su única carpeta.
  2. Rechaza el paquete si requires.core no acepta la versión instalada.
  3. Coloca la carpeta en content/plugins/<slug>/ (o content/themes/<slug>/), sustituyendo la que hubiera.
  4. 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:

  1. Descarga el zip y comprueba su sha256 y la firma del Hub. Si no cuadran, lo borra sin abrirlo.
  2. Comprueba que el slug del zip es el esperado y que requires.core acepta el núcleo instalado.
  3. Analiza la sintaxis de todos los .php de la versión nueva.
  4. Hace copia de la carpeta actual y de las tablas declaradas en data.tables.
  5. Pone el código nuevo, ejecuta las migraciones y llama a upgrade($desde, $hasta).
  6. Pide la portada del sitio. Una respuesta 5xx (o ninguna) cuenta como fallo.
  7. 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, el slug y la version de 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, stable o beta. 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:

CambioEjemploSube
Corrección que no cambia nada visible para otrosUn error al guardarParche: 1.2.0 → 1.2.1
Funciones nuevas, compatibles con lo anteriorUn ajuste o un hook nuevoMenor: 1.2.1 → 1.3.0
Algo deja de funcionar como antesQuitas un hook, cambias una tabla o el formato de un ajusteMayor: 1.3.0 → 2.0.0
  • Declara en requires.core el rango que has probado: make:plugin pone ^<menor actual>, por ejemplo ^0.9.
  • Si quitas o renombras un hook tuyo, mantén el viejo una temporada con do_action_deprecated() o apply_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:

NivelQué incluyeGarantía
EstableLos 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.
Contratosplayer@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.
InternoTodo 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:check sin 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.
  • [ ] version subida en el manifest y notas de versión escritas.
  • [ ] Textos traducidos en todos los idiomas que incluyes.
  • [ ] ext:pack generado desde una copia limpia (sin archivos locales ni secretos).

¿Te quedó alguna duda?

Escríbenos y te ayudamos con tu caso.

Hablar con nosotros
¿Hablamos?