Los hooks son los puntos donde tu código entra en MovieMaster sin tocar el núcleo. Esta página explica cómo funcionan y recoge todos los que dispara el código, con sus argumentos y el momento exacto en que se ejecutan.
Acciones y filtros #
- Una acción avisa de que algo ha pasado. Tus funciones se ejecutan y lo que devuelvan se ignora. Las acciones de plantilla (
head,footer…) imprimen HTML conecho. - Un filtro pasa un valor por todas las funciones enganchadas, en cadena. Cada una recibe el valor (más argumentos de contexto) y debe devolverlo, modificado o no.
// Acción: hacer algo cuando se guarda un título
add_action('title_saved', static function (array $title, bool $isNew): void {
if ($isNew) {
logger()->info('Nuevo título: ' . $title['title']);
}
}, 10, 2);
// Filtro: cambiar un valor y devolverlo
add_filter('listing_per_page', static fn(int $n): int => 30);Funciones de hooks #
| Función | Qué hace |
|---|---|
add_action(string $hook, callable $cb, int $priority = 10, int $acceptedArgs = -1) | Engancha una función a una acción. |
add_filter(string $hook, callable $cb, int $priority = 10, int $acceptedArgs = -1) | Engancha una función a un filtro. |
remove_action(string $hook, callable $cb, int $priority = 10): bool | Quita una función (misma función y misma prioridad con la que se añadió). |
remove_filter(string $hook, callable $cb, int $priority = 10): bool | Igual, para filtros. |
do_action(string $hook, mixed ...$args) | Dispara una acción propia. |
apply_filters(string $hook, mixed $value, mixed ...$args): mixed | Pasa un valor por un filtro propio. |
has_action(string $hook): bool | ¿Alguien escucha este hook? |
did_action(string $hook): int | Cuántas veces se ha disparado ya en esta petición. |
current_filter(): ?string | El hook que se está ejecutando ahora. |
do_action_deprecated(string $hook, array $args, string $version, string $replacement = '') | Dispara una acción obsoleta: avisa en el log solo si alguien la escucha. |
apply_filters_deprecated(string $hook, array $args, string $version, string $replacement = '') | Lo mismo para un filtro obsoleto. |
hooks() | El HookManager (métodos add, remove, removeAll, doAction, applyFilters, has, did, current). |
Prioridad #
Las funciones se ejecutan de menor a mayor prioridad; con la misma prioridad, en el orden en que se añadieron. Usa 5 para ir antes que casi todo y 20 o más para ir después (por ejemplo, para retocar lo que ya añadió otro plugin).
Número de argumentos #
Con $acceptedArgs = -1 (por defecto) tu función recibe todos los argumentos del hook. Si pasas un número, recibe solo los primeros. Úsalo cuando enganches una función de PHP o un método que no admite argumentos de más:
add_filter('seo_title', 'trim', 10, 1);Quitar el hook de otro plugin #
remove_action/remove_filter necesitan la misma función: una función con nombre, un método estático ([Clase::class, 'metodo']) o el mismo objeto. Un closure anónimo no se puede quitar desde fuera; si quieres que otros puedan desactivar tu comportamiento, ofrécelo como ajuste o expón tu propio filtro:
if (apply_filters('mi_plugin_mostrar_caja', true, $title)) {
echo $caja;
}Tus propios hooks #
Prefija siempre el nombre con tu slug (mi_plugin_algo) y documéntalo en tu README. Si cambias un hook ya publicado, mantén el viejo un tiempo con do_action_deprecated('viejo', [$a, $b], '2.0.0', 'nuevo'): no hace nada si nadie lo usa y avisa en el log a quien sí.
Lista viva desde la consola #
Esta página recoge los hooks del núcleo 0.9.x. La lista exacta de tu versión la genera el propio código:
php bin/console.php hooks:list # nombre, acción o filtro y número de usos
php bin/console.php hooks:list --where # + primer archivo:línea donde se dispara
php bin/console.php hooks:list --type=filter --jsonArranque, rutas y consola #
| Hook | Tipo | Argumentos | Cuándo |
|---|---|---|---|
booted | acción | $app | Configuración, contenedor y base de datos listos, antes de cargar plugins: un plugin no llega a verlo. Para eso está init. |
routes | acción | $router, $app | Registro de rutas. $plugin->route() se engancha aquí con prioridad 5. |
init | acción | $app | Núcleo, plugins y theme cargados, rutas registradas. El sitio para lo que necesite todo lo anterior. |
terminate | acción | $request | Al final de la petición, con la respuesta ya enviada. Bueno para trabajo que no debe retrasar la página. |
migrate | acción | $migrator, $io | php bin/console.php migrate, después de las migraciones del núcleo. |
console_commands | filtro | $commands (nombre => clase) | Añadir comandos a bin/console.php. Ver crear plugins. |
cron | acción | $cron | Cada ejecución del cron (cada minuto). Atajo: $plugin->cron('minute', fn). |
cron_hourly | acción | — | Una vez por hora, tras el mantenimiento del núcleo. Atajo: $plugin->cron('hourly', fn). |
cron_daily | acción | — | Una vez al día, tras el mantenimiento del núcleo (limpieza, licencia, actualizaciones). Atajo: $plugin->cron('daily', fn). |
queue_handlers | filtro | $handlers (tipo => callable|clase) | Manejadores de la cola. Atajo: $plugin->job($tipo, $handler). |
Plantillas del sitio público #
Las acciones de plantilla las dispara el theme con @hook('nombre'). Tu función imprime HTML con echo; escapa con e() todo lo que venga de datos.
| Hook | Tipo | Argumentos | Dónde |
|---|---|---|---|
template_data | filtro | $data, $template | Antes de pintar una página: añade o cambia variables de la plantilla. |
before_render | acción | $template, $data | Justo antes de pintar. Útil para recordar $template y decidir qué imprimir en head. |
template_path | filtro | $template, $template | Cambiar qué plantilla se usa ('title' → 'mi-plugin::ficha'). |
body_class | filtro | $class ('tpl-<plantilla>') | Clases del <body>. Añade con $class . ' mi-clase'. |
head | acción | — | Dentro de <head>. Por aquí salen las meta, el canonical, el JSON-LD y tu CSS en línea. |
body_open | acción | — | Justo después de <body>. |
nav_items | acción | — | Dentro del <nav> principal, tras los enlaces del theme. Imprime <a>. |
before_content | acción | — | Antes del contenido principal (<main>). |
after_content | acción | — | Después del contenido principal. |
footer | acción | — | En el pie. |
body_close | acción | — | Justo antes de </body>. Sitio para tus <script type="module">. |
player_before | acción | — | En la ficha y el capítulo, antes del reproductor. |
player_after | acción | — | En la ficha y el capítulo, después del reproductor. |
comments | acción | — | Hueco de la caja de comentarios en title.tpl y episode.tpl. Solo lo dispara un theme que declara comments@1. |
account_sections | acción | — | En la página «Mi cuenta» del plugin Members, para añadir secciones. |
home_rails | filtro | $rails | Filas de la portada. Ver la forma abajo. |
listing_per_page | filtro | $perPage | Elementos por página en los listados (mínimo 6). |
related_limit | filtro | $limit, $title | Cuántos títulos relacionados buscar. |
related_titles | filtro | $titles, $title | La lista final de relacionados de una ficha. |
embed_html | filtro | $html, $source | El HTML de un servidor de vídeo (el iframe que crea la facade). |
ad_scripts_code | filtro | $code, $key | Código de un bloque de publicidad de Admin → Publicidad. Devuelve '' para no imprimirlo. |
search_suggestions | filtro | $out, $q | Sugerencias del buscador: ['titles' => [], 'people' => [], 'genres' => []]. |
Forma de una fila de home_rails:
$rails['mi_fila'] = [
'title' => 'Recomendadas', // texto visible
'url' => url('/movies') . '?sort=rating', // enlace «ver todo» (opcional)
'items' => $titulos, // filas de TitleRepository; una fila sin items no se pinta
'style' => 'cards', // cards | top10 | episodes
];Contenido #
| Hook | Tipo | Argumentos | Cuándo |
|---|---|---|---|
title_saved | acción | $title, $isNew | Película o serie creada o editada ($title = fila ya guardada). |
title_deleted | acción | $title | Título borrado (ya se escribió el 410 de sus URL). |
title_query | filtro | $query, $filters | La consulta de los listados de títulos, antes de ejecutarse. Añade condiciones con el constructor. |
sources_saved | acción | $titleId, $episodeId | Fuentes de vídeo guardadas ($episodeId es null en una película). |
person_saved | acción | $person | Persona creada o editada. |
person_deleted | acción | $id | Persona borrada. |
term_saved | acción | $term, $taxonomy | Género, etiqueta o término propio guardado. |
term_deleted | acción | $term | Término borrado. |
taxonomy_label | filtro | ucfirst($taxonomy), $taxonomy | Nombre en el panel de una taxonomía propia. |
taxonomy_url_prefix | filtro | $prefix, $taxonomy | Palabra de la URL de una taxonomía propia. |
url_key_changed | acción | $kind, $id, $old, $new | La palabra de URL de una temporada o capítulo cambió ($kind = season o episode). Ya se crearon los 301. |
availability_changed | acción | $id, $type, ['title' => bool, 'episodes' => int[]] | Un título o capítulos pasaron a estar disponibles (útil para avisar a suscriptores). |
media_uploaded | acción | $media | Imagen subida y procesada. |
media_deleted | acción | $media | Imagen borrada con todas sus variantes. |
media_shared_fetch | filtro | null, $slot | Antes de descargar la imagen de un hueco: devuelve una fila de media existente para reutilizarla (biblioteca compartida entre sitios). |
media_offload_paths | filtro | [], $slot, $ids | Admin → Catálogo → liberar espacio: rutas de TMDB ([id => '/abc.jpg']) de las imágenes que se pueden servir desde fuera. |
content_purged | acción | $tags | Tras purgar etiquetas de la caché. |
purge_tags | filtro | $tags | Las etiquetas a purgar, antes de hacerlo. Añade las tuyas. |
page_cache_purged | acción | $tags, $paths | Tras borrar páginas de la caché estática (['*'] = toda). Para avisar a un CDN. |
page_cache_bypass | filtro | false, $request | Devuelve true para no guardar esta respuesta en la caché estática. |
Fuentes de vídeo y reproductor #
| Hook | Tipo | Argumentos | Para qué |
|---|---|---|---|
source_languages | filtro | $languages | Idiomas de audio de las fuentes: ['latino', 'castellano', 'subtitulado', 'english', 'original']. |
source_language_code | filtro | $code, $language | Código corto de la pestaña de idioma (LAT, ESP, SUB…). |
source_default_language | filtro | $language, $siteLang | Idioma de las fuentes que se abre primero. |
player_api_url | filtro | $url | URL base de la API resolutora del reproductor (la que lee data-api-base). |
player_api_languages | filtro | $languages, $siteLang | Idiomas que se piden a la API según el idioma del sitio. |
player_api_sources | filtro | $grouped, $title, $episode | Fuentes agrupadas por idioma que recibe el reproductor. |
player_api_covers | filtro | true, $title, $episode | Devuelve false para no usar la API en ese título o capítulo. |
player_source_allowed | filtro | true, $source, $title, $request | Money Player pregunta antes de reproducir: false bloquea la fuente (lo usa Members VIP). |
money_player_templates | filtro | ['title', 'episode'] | Plantillas donde Money Player se activa. |
money_player_resolvers | filtro | $classes | Clases que implementan ResolverInterface para reproducir un host en el reproductor propio. |
SEO, sitemaps y PWA #
| Hook | Tipo | Argumentos | Para qué |
|---|---|---|---|
seo_title | filtro | $title | El <title> final de una página. |
seo_schema | filtro | $graph, $ctx, $data | Los nodos del JSON-LD (@graph). Añade nodos al array; nunca imprimas otro <script type="application/ld+json">. |
seo_meta | filtro | $seo, $ctx, $data | El objeto PageSeo completo (title, description, canonical, robots, image, alternates…). |
sitemap_index | filtro | $items ('/ruta.xml' => lastmod) | Entradas del índice de sitemaps. Añade los tuyos. |
sitemap_custom | filtro | null, $type, $chunk | Contenido de un sitemap que no es del núcleo (/sitemap-<type>-<n>.xml o /sitemap-<type>.xml, $type solo letras minúsculas): devuelve el XML o null (404). |
robots_txt | filtro | $text | El robots.txt generado. |
indexnow_request | filtro | null, $body | Envío a IndexNow: devuelve un código HTTP (int) si lo envías tú. |
pwa_manifest | filtro | $data | El manifest.webmanifest. |
pwa_icons | filtro | $icons | Iconos de la PWA. |
Valores de $ctx en seo_schema y seo_meta, con lo que trae $data:
$ctx | $data |
|---|---|
home | page |
movie, series | title |
season | title, season |
episode | title, episode |
genre, tag (y taxonomías propias) | term, page |
person | person, page |
page | page (la página estática) |
search | q |
movies, series_list, year, genres, tags, people (listados) | page |
add_filter('seo_schema', static function (array $graph, string $ctx, array $data): array {
if ($ctx === 'movie') {
$graph[] = ['@type' => 'Review', 'itemReviewed' => ['@id' => url($data['title']['url'], true) . '#movie'], /* … */];
}
return $graph;
});Ajustes, usuarios y extensiones #
| Hook | Tipo | Argumentos | Cuándo |
|---|---|---|---|
settings_groups | filtro | $groups (clave => [label, fields[]]) | Grupos de Ajustes. Así entran los de los plugins ($plugin->setting() lo hace por ti). |
settings_before_save | filtro | $save, $group | Valores ya validados (clave => valor) antes de guardarlos. |
settings_saved | acción | $group, $save | Tras guardar un grupo de Ajustes (Admin → SEO dispara 'seo', ['tab' => …]). |
user_login | acción | $user | Inicio de sesión correcto en el panel. |
login_failed | acción | $login, $ip | Intento de inicio de sesión fallido. |
role_capabilities | filtro | $caps, $role | Capacidades de un rol. Ver páginas de administración. |
mail_send | filtro | null, $message | Devuelve true si enviaste tú el correo (SMTP propio, API) o false si falló; null deja que lo envíe el núcleo. $message = to, subject, body, from, from_name. |
extension_installed | acción | $type, $slug | Tras instalar un zip de plugin o theme. |
extension_updated | acción | $type, $slug | Tras actualizar uno ya instalado. |
extension_activated | acción | $type, $slug | Tras activar un plugin o cambiar de theme. |
extension_deactivated | acción | $type, $slug | Tras desactivarlo. |
extension_uninstalled | acción | $type, $slug | Tras borrar el plugin y sus datos. |
update_before | acción | $old, $new | Actualización del núcleo, antes de reemplazar archivos. |
update_after | acción | $old, $new | Actualización del núcleo terminada (migraciones y caché incluidas). |
Panel de administración #
Detalle y ejemplos en páginas de administración.
| Hook | Tipo | Argumentos | Para qué |
|---|---|---|---|
admin_menu | filtro | $items | Las entradas del menú del panel. |
admin_routes | acción | $router | Rutas propias dentro de /admin (con su sesión y CSRF). |
admin_head | acción | — | Dentro del <head> del panel. Nunca llega al sitio público. |
admin_footer | acción | — | Antes de </body> del panel. |
admin_dashboard_widgets | filtro | $widgets | Tarjetas del escritorio: ['title' => …, 'html' => …]. |
admin_dashboard_status_cards | filtro | $cards | Tarjetas del bloque de estado del escritorio. Misma forma. |
admin_disk_min_free_gb | filtro | null | GB libres mínimos antes de avisar de disco lleno. |
admin_onboarding_steps | filtro | $items, $stats, $health | Lista corta de primeros pasos del escritorio: [key, done, link, label?]. |
admin_onboarding_items | filtro | $items | Lista completa de Admin → Primeros pasos. |
admin_search_results | filtro | $items, $type, $q | Resultados del buscador del panel. |
admin_settings_links_for | filtro | [], $fieldKey | Enlaces [url, label] junto a un campo de Ajustes. |
admin_settings_field | acción | $fieldKey | HTML propio debajo de un campo de Ajustes. |
admin_titles_index_top | acción | $type | Encima de la tabla de Películas o Series (movie/series). |
admin_title_form_top | acción | $type, $title | Arriba del formulario de un título ($title es null al crear). |
admin_title_actions | acción | $title | Botones junto al título en su página de edición. |
admin_catalog_panel | acción | — | En Admin → Catálogo, bajo el formulario del catálogo. |
Importación y catálogo #
| Hook | Tipo | Argumentos | Cuándo |
|---|---|---|---|
tmdb_imported | acción | $id, $type, $tmdbId, $data | Título importado desde TMDB (plugin TMDB Import). |
tmdb_season_imported | acción | $titleId, $tmdbId, $number | Temporada importada desde TMDB. |
catalog_importer | filtro | null | Quién importa las líneas que piden TMDB: ['job' => 'tmdb.import', 'ready' => bool]. |
catalog_imported | acción | $id, $type, $tmdbId | Título creado desde el catálogo precargado del Hub. |
catalog_synced | acción | $scope, $version | Recorrido completo del catálogo terminado. |
csv_import_resolve_title | filtro | null, $type, $row | Importación CSV: devuelve el id de un título existente para una fila. |
Hooks de los plugins incluidos #
Estos los disparan plugins que vienen con el núcleo; solo existen si el plugin está activo.
| Hook | Plugin | Tipo | Argumentos | Cuándo |
|---|---|---|---|---|
member_registered | Members | acción | $member | Alta de un miembro. |
member_blocked | Members | acción | $member | Un miembro fue bloqueado. |
member_deleted | Members | acción | $id | Cuenta borrada (por el miembro o el admin). |
comment_posted | Comments | acción | $comment | Comentario enviado. |
comment_status | Comments | acción | $id, $status | Comentario aprobado, rechazado o marcado como spam. |
comment_moderation | Comments | filtro | $status, $body, $member | Estado inicial de un comentario nuevo: approved, pending o spam (otro valor se convierte en pending). |
vip_payment_received | Members VIP | acción | $id, $member | Un miembro envió un pago para revisar. |
vip_payment_approved | Members VIP | acción | $paymentId, $memberId, $until | Pago aprobado; VIP hasta $until. |
Recetas #
Cambiar el número de relacionados solo en series:
add_filter('related_limit', static fn(int $n, array $t): int => $t['type'] === 'series' ? 18 : $n, 10, 2);Ocultar de los listados los títulos de una etiqueta:
add_filter('title_query', static function ($q, array $filters) {
if (empty($filters['term_id'])) { // en la página de esa etiqueta sí se ven
$q->whereNotIn('titles.id', db()->table('title_terms')->select('title_id')->where('term_id', 42));
}
return $q;
});Avisar a un CDN cuando se purga la caché:
add_action('page_cache_purged', static function (array $tags, array $paths): void {
app(MiPlugin\Cdn::class)->purge($paths === ['*'] ? null : $paths); // mejor encolarlo con $plugin->jobs()
});Añadir un sitemap propio:
add_filter('sitemap_index', static function (array $items): array {
$items['/sitemap-eventos-1.xml'] = db()->table('eventos')->max('updated_at');
return $items;
});
add_filter('sitemap_custom', static function (?string $xml, string $type, int $chunk): ?string {
return $type === 'eventos' ? app(MiPlugin\Sitemap::class)->xml($chunk) : $xml;
});