Saltar al contenido
MovieMaster

Desarrolladores: plugins y themes

Crear plugins

3 min de lectura 14 apartados

En esta página

Todo lo que un plugin puede hacer, con ejemplos: el objeto $plugin, el ciclo de vida, los ajustes, las rutas, las vistas, las traducciones, las migraciones, la cola, el cron y los comandos de consola. Si todavía no has creado ninguno, empieza por la introducción para desarrolladores.

Estructura de un plugin #

text
content/plugins/<slug>/
  plugin.json     manifest spec 1 (ver la referencia del manifest)
  plugin.php      punto de entrada: recibe $plugin y solo orquesta
  Lifecycle.php   opcional: instalar, activar, actualizar, desactivar, desinstalar
  src/            tus clases, PSR-4 con el namespace del manifest (sin Composer)
  migrations/     0001_nombre.php, 0002_…: tablas propias
  views/          plantillas .tpl: view('<slug>::nombre')
  assets/         CSS, JS e imágenes públicas: $plugin->asset('archivo.js')
  lang/           es.php, en.php…: __('<textdomain>::clave')

El nombre de la carpeta es el slug y debe coincidir con el de plugin.json. Las clases de src/ se cargan solas con el namespace y el autoload del manifest: "namespace": "MiPlugin\\" y "autoload": "src/" hacen que MiPlugin\Api\Cliente se lea de src/Api/Cliente.php. Todos los campos del manifest están en la referencia de plugin.json.

El objeto $plugin #

Dentro de plugin.php tienes la variable $plugin (MovieMaster\Extensions\PluginContext). Sus métodos devuelven el propio objeto, así que se pueden encadenar.

MétodoQué hace
slug(): stringEl slug del plugin.
dir(): stringRuta absoluta de la carpeta del plugin.
path(string $rel = ''): stringRuta absoluta de un archivo del plugin: $plugin->path('assets/app.css').
version(): stringVersión del manifest.
manifestPropiedad de solo lectura con el Manifest (nombre, get('clave'), requisitos…).
appPropiedad de solo lectura con la aplicación ($plugin->app->container).
setting(string $key, array $def)Declara un ajuste con formulario automático. Se guarda como plugin.<slug>.<key>.
get(string $key, mixed $default = null): mixedLee un ajuste propio: valor guardado → default declarado → $default. Los secret llegan ya descifrados.
route(string $method, string $path, mixed $handler, array $options = [])Ruta pública. Opciones: name, cache, tags, middleware.
adminPage(string $key, string $label, mixed $handler, array $options = [])Página del panel en /admin/p/<slug>/<key>. Ver páginas de administración.
views(string $dir, ?string $namespace = null)Registra plantillas: view('<slug>::nombre').
lang(string $dir)Registra traducciones en el dominio del plugin.
asset(string $file): stringURL pública de assets/<file> con ?v= para invalidar la caché del navegador.
migrations(string $dir)Ejecuta las migraciones de esa carpeta al activar y en cada actualización.
job(string $type, callable|string $handler)Registra el manejador de un tipo de trabajo de la cola.
jobs(): JobsLa cola (MovieMaster\Queue\Jobs) para encolar trabajos.
cron(string $every, callable $fn)Tarea programada: 'minute', 'hourly' o 'daily'.
on(string $event, callable $fn)Ciclo de vida: install, activate, upgrade, deactivate, uninstall.

Un plugin.php típico:

php
<?php
/** @var MovieMaster\Extensions\PluginContext $plugin */
declare(strict_types=1);

use MiPlugin\Api;
use MiPlugin\Admin;

$plugin->lang(__DIR__ . '/lang')
    ->views(__DIR__ . '/views')
    ->migrations(__DIR__ . '/migrations');

$plugin->adminPage('panel', __('mi-plugin::menu'), [Admin::class, 'handle'], ['parent' => 'top', 'icon' => 'star', 'order' => 60]);

$plugin->setting('api_key', ['type' => 'secret', 'label' => __('mi-plugin::api_key')]);
$plugin->setting('limite', ['type' => 'number', 'label' => __('mi-plugin::limite'), 'default' => 20, 'min' => 1, 'max' => 100]);

$plugin->route('GET', '/api/mi-plugin/estado', [Api::class, 'estado'], ['cache' => false]);
$plugin->job('mi-plugin.sync', MiPlugin\Jobs\Sync::class);
$plugin->cron('hourly', static fn() => $plugin->jobs()->pushUnique('mi-plugin.sync'));

add_action('title_deleted', static fn(array $title) => app(MiPlugin\Repo::class)->forget((int) $title['id']));

Ciclo de vida #

EventoCuándo se dispara
installLa primera vez que se activa el plugin en este sitio.
activateCada activación, también justo después de install o upgrade.
upgrade($from, $to)La versión cambió: al reactivarlo o al actualizarlo desde la tienda, después de las migraciones.
deactivateAl desactivarlo.
uninstallAl borrarlo desde el panel. Se dispara siempre, aunque el plugin llevara tiempo desactivado.

Hay dos formas de engancharse y pueden convivir.

Con Lifecycle.php (recomendada) #

Una clase <Namespace>\Lifecycle en la raíz del plugin. El núcleo la carga directamente, sin necesitar plugin.php en memoria, así que es la forma segura para lo que tiene que pasar al desinstalar.

php
<?php
declare(strict_types=1);

namespace MiPlugin;

final class Lifecycle extends \MovieMaster\Extensions\Lifecycle
{
    public function install(): void
    {
        // $this->plugin es el PluginContext
        app(\MovieMaster\Content\Settings::class)->set('plugin.mi-plugin.instalado', gmdate('c'));
    }

    public function upgrade(string $from, string $to): void
    {
        if (version_compare($from, '2.0.0', '<')) {
            // convertir datos del formato 1.x
        }
    }

    public function uninstall(): void
    {
        // avisar a un servicio externo, borrar archivos fuera de data.dirs…
    }
}

Los métodos disponibles son install(), activate(), upgrade(string $from, string $to), deactivate() y uninstall(); todos vacíos por defecto.

Con $plugin->on() #

php
$plugin->on('activate', static function (): void {
    app(\MovieMaster\Content\PurgeService::class)->all();
});

También existen las funciones register_install_hook($slug, $fn), register_activation_hook, register_upgrade_hook, register_deactivation_hook y register_uninstall_hook. Solo se recogen si plugin.php se carga en esa petición.

Limpieza garantizada #

Al desinstalar, después de tu uninstall, el núcleo borra siempre lo que declaraste en el bloque data del manifest: las tablas de data.tables, las carpetas de data.dirs (relativas a content/) y los ajustes que empiezan por data.settings_prefix. Aunque tu código falle, no quedan restos.

Ajustes #

$plugin->setting($key, $def) declara un campo. El núcleo pinta el formulario, valida, guarda y te devuelve el valor con $plugin->get($key). Los ajustes aparecen en Ajustes (apartado de plugins del índice lateral) y en el botón «Ajustes» de la tarjeta del plugin en Admin → Plugins. Su URL es route('admin.settings', ['group' => 'plugin-<slug>']).

Tipos de campo #

typeFormularioValor guardado
textUna línea. Admite required y maxlength.string
textareaVarias líneas. Admite required y maxlength.string
numberNúmero entero. min y max recortan el valor.int
checkboxCasilla.bool
selectDesplegable con options (valor => etiqueta). Un valor fuera de la lista vuelve al default.string
colorSelector de color. Solo #rrggbb.string
urlURL http(s) validada. Admite required.string
listUn elemento por línea (o separados por comas). item_type = url o host descarta los no válidos.array
mediaSelector de la biblioteca de medios. preset fija el recorte.int (id de media)
secretContraseña: nunca se vuelve a mostrar y se guarda cifrada (AES-256-GCM). Dejarla vacía conserva la actual.string (descifrado con get)
infoTexto de ayuda, sin campo. Nunca se guarda.—

Claves de la definición #

ClavePara qué
labelTexto del campo (usa __()).
defaultValor mientras el dueño no guarde otro.
helpTexto de ayuda bajo el campo.
optionsPara select: ['valor' => 'Etiqueta'].
min, maxPara number.
required, maxlengthPara text, textarea y url.
item_typePara list: url o host.
presetPara media: recorte de la imagen.
hide_whenClave de otra casilla del mismo plugin: el campo se oculta mientras esa casilla esté marcada.
sanitizefn($valor, $campo): array que devuelve ['value' => …, 'error' => ?string, 'notice' => ?string]. Se ejecuta después de la validación del tipo.
php
$plugin->setting('usar_cdn', ['type' => 'checkbox', 'label' => 'Usar mi CDN', 'default' => false]);
$plugin->setting('cdn_host', [
    'type' => 'text',
    'label' => 'Dominio del CDN',
    'hide_when' => 'usar_cdn',            // se oculta mientras la casilla esté marcada
    'sanitize' => static function (string $v): array {
        $v = strtolower(preg_replace('#^https?://#', '', $v));
        return $v === '' || preg_match('/^[a-z0-9.-]+$/', $v)
            ? ['value' => $v]
            : ['value' => $v, 'error' => 'Escribe solo el dominio, sin rutas.'];
    },
]);

Leer ajustes:

php
$plugin->get('limite');                          // dentro del plugin
plugin_setting('mi-plugin', 'limite', 20);       // desde cualquier sitio
setting('plugin.mi-plugin.limite');              // valor crudo (un secret llega cifrado)

Al guardar cualquier grupo se ejecutan el filtro settings_before_save($save, $group) y la acción settings_saved($group, $save), y se vacía la caché de páginas. El grupo de tu plugin se llama plugin-<slug>.

Rutas públicas #

php
$plugin->route('GET', '/estrenos', [MiPlugin\Estrenos::class, 'index'], ['name' => 'estrenos', 'cache' => true, 'tags' => ['list:titles']]);
$plugin->route('GET', '/estrenos/page/{n:\d+}', [MiPlugin\Estrenos::class, 'index'], ['cache' => true, 'tags' => ['list:titles']]);
$plugin->route('POST', '/api/mi-plugin/voto/{id:\d+}', [MiPlugin\Api::class, 'votar'], ['cache' => false]);
  • Métodos: GET, POST, PUT, DELETE o una lista (['GET', 'POST']). Una ruta GET responde también a HEAD.
  • Parámetros: {nombre} captura un segmento ([^/]+); {nombre:regex} lo restringe ({id:\d+}, {tipo:movie|series}).
  • Opciones:
OpciónEfecto
nameNombre para route('nombre', ['id' => 5]). Los parámetros que sobran van a la query string.
cachetrue permite guardar la respuesta en la caché estática de páginas. Por defecto false.
tagsEtiquetas de caché de la página (list:titles, title:42…) para que se purgue sola al cambiar el contenido.
middlewareLista de clases que implementan MovieMaster\Http\Middleware (handle(Request $request, callable $next): Response).

Las rutas del núcleo se registran antes que las de los plugins y, cuando dos rutas encajan con la misma URL, gana la primera registrada: no puedes sustituir una ruta del núcleo, elige rutas propias (/api/<slug>/…, /<slug>/…).

El controlador #

El handler puede ser [Clase::class, 'metodo'], un closure o cualquier callable. Se llama con inyección de dependencias:

  • El constructor de la clase recibe del contenedor cualquier servicio por su tipo (TitleRepository, Settings, Connection…).
  • El método recibe por nombre los parámetros de la ruta ($id, $slug…) y $request.
php
<?php
declare(strict_types=1);

namespace MiPlugin;

use MovieMaster\Content\Repositories\TitleRepository;
use MovieMaster\Http\HttpException;
use MovieMaster\Http\Request;
use MovieMaster\Http\Response;

final class Api
{
    public function __construct(private TitleRepository $titles) {}

    public function votar(Request $request, string $id): Response
    {
        $title = $this->titles->find((int) $id);
        if ($title === null) {
            throw new HttpException(404);
        }
        $estrellas = max(1, min(5, $request->int('estrellas')));
        // … guardar el voto
        return Response::json(['ok' => true, 'estrellas' => $estrellas])->noCache();
    }
}

Lo que devuelve el handler se convierte así:

DevuelvesRespuesta
ResponseTal cual.
stringHTML con estado 200.
array o JsonSerializableJSON.
null204 sin contenido.
Otra cosaSe convierte a texto.

Para errores lanza MovieMaster\Http\HttpException con el código (404, 403…): el theme pinta su página de error.

Caché de páginas #

Una respuesta se guarda en la caché estática solo si se cumplen todas estas condiciones: la ruta tiene cache => true, es GET, responde 200, no lleva cookies, la petición no trae query string ni cookie de sesión, la ruta no empieza por /admin, /install ni /api, y el filtro page_cache_bypass($bypass, $request) no devuelve true. La respuesta lleva la cabecera X-MM-Cache: BYPASS cuando no se guarda.

Formularios públicos y CSRF #

El token CSRF del núcleo solo se comprueba en /admin y /install. Una ruta pública que acepte POST debe protegerse ella misma:

  • Si tu plugin depende de Members, pide Members\Guard al contenedor (app(\Members\Guard::class)): check($request) comprueba mismo origen + token (X-CSRF-Token o _token), member($request) devuelve el miembro con sesión o null, csrf($request) da el token del navegador y Guard::expose($member) lo único que puede salir al navegador (id, name). Nunca leas sus cookies a mano.
  • Si no, comprueba al menos el origen ($request->header('Origin') igual a $request->baseUrl()), limita intentos con MovieMaster\Auth\RateLimiter y valida cada campo.

Páginas dentro del layout del theme #

Para una página pública completa (con cabecera, pie y SEO del theme), extiende MovieMaster\Frontend\Controllers\FrontController y usa su método page(), que añade $site, $seo y $template y dispara template_data, before_render y template_path:

php
<?php
declare(strict_types=1);

namespace MiPlugin;

use MovieMaster\Content\Repositories\TitleRepository;
use MovieMaster\Frontend\Controllers\FrontController;
use MovieMaster\Http\Request;
use MovieMaster\Http\Response;

final class Estrenos extends FrontController
{
    public function index(Request $request, TitleRepository $titles, string $n = '1'): Response
    {
        $page = max(1, (int) $n);
        $result = $titles->paginate(['order' => 'release'], $page, $this->perPage());

        $seo = $this->seo->error(200);
        $seo->title = $this->seo->wrap(__('mi-plugin::estrenos'));
        $seo->canonical = url('/estrenos', true);

        return $this->page('mi-plugin::estrenos', [
            'titles' => $result['items'],
            'pagination' => $result,
        ], ['list:titles'], $seo);
    }
}

Y views/estrenos.tpl:

html
@extends('layout')
@section('content')
<section class="wrap sec">
  <h1 class="h1">{{ __('mi-plugin::estrenos') }}</h1>
  @include('partials/grid', ['titles' => $titles, 'lcp' => 8])
  {!! pagination($pagination, '/estrenos') !!}
</section>
@endsection

partials/grid es la rejilla del theme activo: tu página se ve como el resto del sitio sin una línea de CSS. paginate() devuelve items, total, page, per_page y last_page, justo lo que espera pagination() (que recibe la ruta sin dominio y pone sola el idioma y /page/N). La sintaxis completa de las plantillas está en el motor de plantillas.

Vistas #

php
$plugin->views(__DIR__ . '/views');               // espacio de nombres = slug
echo view('mi-plugin::widget', ['items' => $items]);

Una vista del plugin puede @extends('layout') (el layout del theme activo) o @extends('admin::layout') (el del panel), e incluir parciales del theme (@include('partials/card', …)) o propios (@include('mi-plugin::partials/fila', …)). Los nombres admiten subcarpetas con /.

Traducciones #

php
$plugin->lang(__DIR__ . '/lang');

lang/es.php y lang/en.php devuelven un array:

php
<?php
return [
    'menu' => 'Mi plugin',
    'saludo' => 'Hola, :nombre',
    'resultados' => ':count resultado|:count resultados',
];
UsoResultado
__('mi-plugin::menu')«Mi plugin» en el idioma actual.
__('mi-plugin::saludo', ['nombre' => 'Ana'])«Hola, Ana». Los marcadores son :nombre.
_n('mi-plugin::resultados', 3)«3 resultados». Singular y plural separados por |; :count se sustituye solo.
__('mi-plugin::menu', [], 'en')Forzar un idioma.

Con spec 1 las claves viven en su propio dominio (textdomain, por defecto el slug), aisladas del núcleo y de otros plugins: nunca pisarás una cadena del núcleo por usar el mismo nombre. En las plantillas se usa igual: {{ __('mi-plugin::menu') }}.

Assets: CSS, JavaScript e imágenes #

$plugin->asset('archivo') devuelve la URL pública de assets/archivo con ?v=<fecha de modificación>. Para no salirte de los presupuestos de Lighthouse:

  • CSS: imprímelo en línea y solo en las páginas que lo necesitan, desde el hook head. Construye sobre los tokens del theme (var(--fg), var(--primary), var(--line)…) con un valor de reserva.
  • JavaScript: nunca en la carga inicial. Cárgalo con import() cuando haga falta (al acercarse el elemento con IntersectionObserver, al hacer clic, o solo si hay sesión).
php
// Saber qué plantilla se está pintando
$tpl = null;
add_action('before_render', static function ($template = null) use (&$tpl): void {
    $tpl = is_string($template) ? $template : null;
}, 10, 1);

// CSS en línea solo en las fichas de película o serie
add_action('head', static function () use (&$tpl, $plugin): void {
    if ($tpl === 'title') {
        echo '<style>' . minify_css((string) file_get_contents($plugin->path('assets/ficha.css'))) . '</style>';
    }
});

// JS bajo demanda: se descarga al acercarse la caja
add_action('after_content', static function () use (&$tpl, $plugin): void {
    if ($tpl !== 'title') {
        return;
    }
    echo '<div id="mi-caja" style="min-height:240px"></div>'
        . '<script type="module">{const e=document.getElementById("mi-caja");new IntersectionObserver((o,io)=>{if(o[0].isIntersecting){io.disconnect();import('
        . json_encode($plugin->asset('caja.js'), JSON_UNESCAPED_SLASHES) . ').then(m=>m.default(e))}},{rootMargin:"600px"}).observe(e)}</script>';
});

Base de datos y migraciones #

php
$plugin->migrations(__DIR__ . '/migrations');
bash
php bin/console.php make:migration mi-plugin create_votos_table

Genera migrations/0001_create_votos_table.php. Una migración devuelve una clase anónima con up():

php
<?php
declare(strict_types=1);

use MovieMaster\Database\Connection;
use MovieMaster\Database\Migration;
use MovieMaster\Database\Schema\Blueprint;
use MovieMaster\Database\Schema\Schema;

return new class extends Migration {
    public function up(Schema $s, Connection $db): void
    {
        if ($s->hasTable('votos')) {
            return;
        }
        $s->create('votos', function (Blueprint $t) {
            $t->id();
            $t->unsignedBigInteger('title_id');
            $t->tinyInteger('estrellas');
            $t->string('ip_hash', 64)->nullable();
            $t->timestamps();
            $t->index(['title_id']);
        });
    }
};
  • Las migraciones se ejecutan en orden al activar el plugin, en cada actualización y con php bin/console.php migrate. Cada una corre una sola vez.
  • Son solo hacia delante: no cambies una migración publicada, añade otra (0002_…).
  • Los nombres de tabla van sin prefijo: el núcleo añade el del sitio (mm_). Declara tus tablas en data.tables para que se borren al desinstalar.
  • Funcionan igual en MySQL/MariaDB y SQLite. Escribe SQL portable o usa el constructor de consultas.

Para consultar: db()->table('votos')->where('title_id', 42)->count(). El constructor completo, Schema, Blueprint y los repositorios de contenido están en la referencia de la API PHP.

Cola de trabajos #

Lo pesado (llamadas a APIs externas, importar imágenes, recalcular) va a la cola, que procesa el cron cada minuto.

php
// Registrar el manejador: un callable que recibe el payload, o una clase con handle(array $payload)
$plugin->job('mi-plugin.sync', MiPlugin\Jobs\Sync::class);
$plugin->job('mi-plugin.ping', static function (array $payload): void {
    // …
});

// Encolar
$plugin->jobs()->push('mi-plugin.ping', ['url' => $url]);                 // ya
$plugin->jobs()->push('mi-plugin.ping', ['url' => $url], 300);            // dentro de 5 minutos
$plugin->jobs()->pushUnique('mi-plugin.sync', ['id' => 42], 0, 5);         // no duplica uno pendiente igual; prioridad 5
  • Si el manejador lanza una excepción o devuelve false, el trabajo se reintenta más tarde (60 s × intento). Tras 3 intentos queda como fallido y se ve en Admin → Cola.
  • Una clase manejadora se crea con el contenedor: su constructor puede pedir servicios.
  • Usa nombres con el prefijo de tu plugin (mi-plugin.algo) para no chocar con los del núcleo (tmdb.import, catalog.import, mail.send…).
  • En local, sin cron, procesa la cola con php bin/console.php queue:work.

Tareas programadas #

php
$plugin->cron('minute', static fn() => …);   // cada ejecución del cron (cada minuto)
$plugin->cron('hourly', static fn() => …);   // una vez por hora
$plugin->cron('daily', static fn() => app(MiPlugin\Repo::class)->limpiar());

Equivalen a las acciones cron, cron_hourly y cron_daily. Las horarias y diarias corren después del mantenimiento del núcleo. El cron debe ser rápido: si una tarea tarda, encola un trabajo y termina.

Comandos de consola #

Añade comandos a php bin/console.php con el filtro console_commands:

php
add_filter('console_commands', static function (array $commands): array {
    $commands['mi-plugin:sync'] = MiPlugin\Console\SyncCommand::class;
    return $commands;
});
php
<?php
declare(strict_types=1);

namespace MiPlugin\Console;

use MovieMaster\Console\Command;
use MovieMaster\Console\Io;

final class SyncCommand implements Command
{
    public static function description(): string
    {
        return 'Sincroniza los votos con el servicio externo';
    }

    public function run(array $args, Io $io): int
    {
        $limite = (int) ($args['limit'] ?? 100);       // --limit=50
        $io->title('Sincronizando');
        // …
        $io->success("Hecho ($limite)");
        return 0;                                       // código de salida
    }
}

$args trae los argumentos posicionales con índice numérico ($args[0]) y las opciones --clave=valor por su nombre. Io ofrece line, info, success, warn, error, title, ask, secret, confirm y table. Los comandos solo existen con el sitio instalado.

Contratos con el theme #

Un contrato es un acuerdo con nombre y versión (nombre@N) entre el theme y los plugins: así ninguno necesita conocer las clases del otro.

  • El theme declara en theme.json → contracts lo que su marcado garantiza (player@1, mylist@1, install@1, i18n@1, account@1, comments@1).
  • El plugin declara en plugin.json → provides lo que implementa (Money Player: "provides": ["player@1"]).
php
$contratos = (array) (active_theme()['contracts'] ?? []);
if (in_array('comments@1', $contratos, true)) {
    // el theme ya pone su hueco con @hook('comments'): no imprimas la caja en after_content
}

plugin_active('members');           // ¿está activo ese plugin?
plugin_providers('player@1');       // slugs de los plugins activos que ofrecen ese contrato

Qué garantiza cada contrato está en crear themes.

Buenas prácticas #

  • Escapa todo lo que imprimas con e() (en plantillas, {{ }} ya escapa). Usa {!! !!} solo con HTML de confianza.
  • Comprueba permisos con app(\MovieMaster\Auth\Auth::class)->can('manage_content') en lo que no pase por una ruta del panel con cap.
  • Guarda claves y contraseñas como ajustes secret, nunca en texto plano ni en archivos.
  • Usa los repositorios para crear, editar o borrar contenido: escriben los 410, purgan la caché, actualizan sitemaps y avisan a IndexNow.
  • Purga lo que cambies: app(\MovieMaster\Content\PurgeService::class)->title($id) o ->purge(['tu-tag']).
  • Nunca llames a mail(): usa app(\MovieMaster\Mail\Mailer::class)->later($to, $asunto, $texto), que lo envía por la cola.
  • Construye las URL con url(), route() o lang_url().
  • Registra errores con logger()->error('…') en vez de echo o var_dump.
  • Prefija tus tablas, ajustes, trabajos, rutas /api/<slug>/… y clases CSS para no chocar con otros plugins.

¿Te quedó alguna duda?

Escríbenos y te ayudamos con tu caso.

Hablar con nosotros
¿Hablamos?