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 #
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étodo | Qué hace |
|---|---|
slug(): string | El slug del plugin. |
dir(): string | Ruta absoluta de la carpeta del plugin. |
path(string $rel = ''): string | Ruta absoluta de un archivo del plugin: $plugin->path('assets/app.css'). |
version(): string | Versión del manifest. |
manifest | Propiedad de solo lectura con el Manifest (nombre, get('clave'), requisitos…). |
app | Propiedad 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): mixed | Lee 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): string | URL 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(): Jobs | La 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
/** @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 #
| Evento | Cuándo se dispara |
|---|---|
install | La primera vez que se activa el plugin en este sitio. |
activate | Cada 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. |
deactivate | Al desactivarlo. |
uninstall | Al 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
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() #
$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 #
type | Formulario | Valor guardado |
|---|---|---|
text | Una línea. Admite required y maxlength. | string |
textarea | Varias líneas. Admite required y maxlength. | string |
number | Número entero. min y max recortan el valor. | int |
checkbox | Casilla. | bool |
select | Desplegable con options (valor => etiqueta). Un valor fuera de la lista vuelve al default. | string |
color | Selector de color. Solo #rrggbb. | string |
url | URL http(s) validada. Admite required. | string |
list | Un elemento por línea (o separados por comas). item_type = url o host descarta los no válidos. | array |
media | Selector de la biblioteca de medios. preset fija el recorte. | int (id de media) |
secret | Contraseña: nunca se vuelve a mostrar y se guarda cifrada (AES-256-GCM). Dejarla vacía conserva la actual. | string (descifrado con get) |
info | Texto de ayuda, sin campo. Nunca se guarda. | — |
Claves de la definición #
| Clave | Para qué |
|---|---|
label | Texto del campo (usa __()). |
default | Valor mientras el dueño no guarde otro. |
help | Texto de ayuda bajo el campo. |
options | Para select: ['valor' => 'Etiqueta']. |
min, max | Para number. |
required, maxlength | Para text, textarea y url. |
item_type | Para list: url o host. |
preset | Para media: recorte de la imagen. |
hide_when | Clave de otra casilla del mismo plugin: el campo se oculta mientras esa casilla esté marcada. |
sanitize | fn($valor, $campo): array que devuelve ['value' => …, 'error' => ?string, 'notice' => ?string]. Se ejecuta después de la validación del tipo. |
$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:
$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 #
$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,DELETEo una lista (['GET', 'POST']). Una rutaGETresponde también aHEAD. - Parámetros:
{nombre}captura un segmento ([^/]+);{nombre:regex}lo restringe ({id:\d+},{tipo:movie|series}). - Opciones:
| Opción | Efecto |
|---|---|
name | Nombre para route('nombre', ['id' => 5]). Los parámetros que sobran van a la query string. |
cache | true permite guardar la respuesta en la caché estática de páginas. Por defecto false. |
tags | Etiquetas de caché de la página (list:titles, title:42…) para que se purgue sola al cambiar el contenido. |
middleware | Lista 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
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í:
| Devuelves | Respuesta |
|---|---|
Response | Tal cual. |
string | HTML con estado 200. |
array o JsonSerializable | JSON. |
null | 204 sin contenido. |
| Otra cosa | Se 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\Guardal contenedor (app(\Members\Guard::class)):check($request)comprueba mismo origen + token (X-CSRF-Tokeno_token),member($request)devuelve el miembro con sesión onull,csrf($request)da el token del navegador yGuard::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 conMovieMaster\Auth\RateLimitery 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
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:
@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>
@endsectionpartials/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 #
$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 #
$plugin->lang(__DIR__ . '/lang');lang/es.php y lang/en.php devuelven un array:
<?php
return [
'menu' => 'Mi plugin',
'saludo' => 'Hola, :nombre',
'resultados' => ':count resultado|:count resultados',
];| Uso | Resultado |
|---|---|
__('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 conIntersectionObserver, al hacer clic, o solo si hay sesión).
// 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 #
$plugin->migrations(__DIR__ . '/migrations');php bin/console.php make:migration mi-plugin create_votos_tableGenera migrations/0001_create_votos_table.php. Una migración devuelve una clase anónima con up():
<?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 endata.tablespara 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.
// 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 #
$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:
add_filter('console_commands', static function (array $commands): array {
$commands['mi-plugin:sync'] = MiPlugin\Console\SyncCommand::class;
return $commands;
});<?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→contractslo que su marcado garantiza (player@1,mylist@1,install@1,i18n@1,account@1,comments@1). - El plugin declara en
plugin.json→provideslo que implementa (Money Player:"provides": ["player@1"]).
$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 contratoQué 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 concap. - 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(): usaapp(\MovieMaster\Mail\Mailer::class)->later($to, $asunto, $texto), que lo envía por la cola. - Construye las URL con
url(),route()olang_url(). - Registra errores con
logger()->error('…')en vez deechoovar_dump. - Prefija tus tablas, ajustes, trabajos, rutas
/api/<slug>/…y clases CSS para no chocar con otros plugins.