Saltar al contenido
MovieMaster

Desarrolladores: plugins y themes

Referencia de hooks (acciones y filtros)

15 min de lectura 12 apartados

En esta página

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 con echo.
  • 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.
php
// 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ónQué 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): boolQuita una función (misma función y misma prioridad con la que se añadió).
remove_filter(string $hook, callable $cb, int $priority = 10): boolIgual, para filtros.
do_action(string $hook, mixed ...$args)Dispara una acción propia.
apply_filters(string $hook, mixed $value, mixed ...$args): mixedPasa un valor por un filtro propio.
has_action(string $hook): bool¿Alguien escucha este hook?
did_action(string $hook): intCuántas veces se ha disparado ya en esta petición.
current_filter(): ?stringEl 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:

php
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:

php
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:

bash
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 --json

Arranque, rutas y consola #

HookTipoArgumentosCuándo
bootedacción$appConfiguración, contenedor y base de datos listos, antes de cargar plugins: un plugin no llega a verlo. Para eso está init.
routesacción$router, $appRegistro de rutas. $plugin->route() se engancha aquí con prioridad 5.
initacción$appNúcleo, plugins y theme cargados, rutas registradas. El sitio para lo que necesite todo lo anterior.
terminateacción$requestAl final de la petición, con la respuesta ya enviada. Bueno para trabajo que no debe retrasar la página.
migrateacción$migrator, $iophp bin/console.php migrate, después de las migraciones del núcleo.
console_commandsfiltro$commands (nombre => clase)Añadir comandos a bin/console.php. Ver crear plugins.
cronacción$cronCada ejecución del cron (cada minuto). Atajo: $plugin->cron('minute', fn).
cron_hourlyacción—Una vez por hora, tras el mantenimiento del núcleo. Atajo: $plugin->cron('hourly', fn).
cron_dailyacción—Una vez al día, tras el mantenimiento del núcleo (limpieza, licencia, actualizaciones). Atajo: $plugin->cron('daily', fn).
queue_handlersfiltro$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.

HookTipoArgumentosDónde
template_datafiltro$data, $templateAntes de pintar una página: añade o cambia variables de la plantilla.
before_renderacción$template, $dataJusto antes de pintar. Útil para recordar $template y decidir qué imprimir en head.
template_pathfiltro$template, $templateCambiar qué plantilla se usa ('title' → 'mi-plugin::ficha').
body_classfiltro$class ('tpl-<plantilla>')Clases del <body>. Añade con $class . ' mi-clase'.
headacción—Dentro de <head>. Por aquí salen las meta, el canonical, el JSON-LD y tu CSS en línea.
body_openacción—Justo después de <body>.
nav_itemsacción—Dentro del <nav> principal, tras los enlaces del theme. Imprime <a>.
before_contentacción—Antes del contenido principal (<main>).
after_contentacción—Después del contenido principal.
footeracción—En el pie.
body_closeacción—Justo antes de </body>. Sitio para tus <script type="module">.
player_beforeacción—En la ficha y el capítulo, antes del reproductor.
player_afteracción—En la ficha y el capítulo, después del reproductor.
commentsacción—Hueco de la caja de comentarios en title.tpl y episode.tpl. Solo lo dispara un theme que declara comments@1.
account_sectionsacción—En la página «Mi cuenta» del plugin Members, para añadir secciones.
home_railsfiltro$railsFilas de la portada. Ver la forma abajo.
listing_per_pagefiltro$perPageElementos por página en los listados (mínimo 6).
related_limitfiltro$limit, $titleCuántos títulos relacionados buscar.
related_titlesfiltro$titles, $titleLa lista final de relacionados de una ficha.
embed_htmlfiltro$html, $sourceEl HTML de un servidor de vídeo (el iframe que crea la facade).
ad_scripts_codefiltro$code, $keyCódigo de un bloque de publicidad de Admin → Publicidad. Devuelve '' para no imprimirlo.
search_suggestionsfiltro$out, $qSugerencias del buscador: ['titles' => [], 'people' => [], 'genres' => []].

Forma de una fila de home_rails:

php
$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 #

HookTipoArgumentosCuándo
title_savedacción$title, $isNewPelícula o serie creada o editada ($title = fila ya guardada).
title_deletedacción$titleTítulo borrado (ya se escribió el 410 de sus URL).
title_queryfiltro$query, $filtersLa consulta de los listados de títulos, antes de ejecutarse. Añade condiciones con el constructor.
sources_savedacción$titleId, $episodeIdFuentes de vídeo guardadas ($episodeId es null en una película).
person_savedacción$personPersona creada o editada.
person_deletedacción$idPersona borrada.
term_savedacción$term, $taxonomyGénero, etiqueta o término propio guardado.
term_deletedacción$termTérmino borrado.
taxonomy_labelfiltroucfirst($taxonomy), $taxonomyNombre en el panel de una taxonomía propia.
taxonomy_url_prefixfiltro$prefix, $taxonomyPalabra de la URL de una taxonomía propia.
url_key_changedacción$kind, $id, $old, $newLa palabra de URL de una temporada o capítulo cambió ($kind = season o episode). Ya se crearon los 301.
availability_changedacción$id, $type, ['title' => bool, 'episodes' => int[]]Un título o capítulos pasaron a estar disponibles (útil para avisar a suscriptores).
media_uploadedacción$mediaImagen subida y procesada.
media_deletedacción$mediaImagen borrada con todas sus variantes.
media_shared_fetchfiltronull, $slotAntes de descargar la imagen de un hueco: devuelve una fila de media existente para reutilizarla (biblioteca compartida entre sitios).
media_offload_pathsfiltro[], $slot, $idsAdmin → Catálogo → liberar espacio: rutas de TMDB ([id => '/abc.jpg']) de las imágenes que se pueden servir desde fuera.
content_purgedacción$tagsTras purgar etiquetas de la caché.
purge_tagsfiltro$tagsLas etiquetas a purgar, antes de hacerlo. Añade las tuyas.
page_cache_purgedacción$tags, $pathsTras borrar páginas de la caché estática (['*'] = toda). Para avisar a un CDN.
page_cache_bypassfiltrofalse, $requestDevuelve true para no guardar esta respuesta en la caché estática.

Fuentes de vídeo y reproductor #

HookTipoArgumentosPara qué
source_languagesfiltro$languagesIdiomas de audio de las fuentes: ['latino', 'castellano', 'subtitulado', 'english', 'original'].
source_language_codefiltro$code, $languageCódigo corto de la pestaña de idioma (LAT, ESP, SUB…).
source_default_languagefiltro$language, $siteLangIdioma de las fuentes que se abre primero.
player_api_urlfiltro$urlURL base de la API resolutora del reproductor (la que lee data-api-base).
player_api_languagesfiltro$languages, $siteLangIdiomas que se piden a la API según el idioma del sitio.
player_api_sourcesfiltro$grouped, $title, $episodeFuentes agrupadas por idioma que recibe el reproductor.
player_api_coversfiltrotrue, $title, $episodeDevuelve false para no usar la API en ese título o capítulo.
player_source_allowedfiltrotrue, $source, $title, $requestMoney Player pregunta antes de reproducir: false bloquea la fuente (lo usa Members VIP).
money_player_templatesfiltro['title', 'episode']Plantillas donde Money Player se activa.
money_player_resolversfiltro$classesClases que implementan ResolverInterface para reproducir un host en el reproductor propio.

SEO, sitemaps y PWA #

HookTipoArgumentosPara qué
seo_titlefiltro$titleEl <title> final de una página.
seo_schemafiltro$graph, $ctx, $dataLos nodos del JSON-LD (@graph). Añade nodos al array; nunca imprimas otro <script type="application/ld+json">.
seo_metafiltro$seo, $ctx, $dataEl objeto PageSeo completo (title, description, canonical, robots, image, alternates…).
sitemap_indexfiltro$items ('/ruta.xml' => lastmod)Entradas del índice de sitemaps. Añade los tuyos.
sitemap_customfiltronull, $type, $chunkContenido 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_txtfiltro$textEl robots.txt generado.
indexnow_requestfiltronull, $bodyEnvío a IndexNow: devuelve un código HTTP (int) si lo envías tú.
pwa_manifestfiltro$dataEl manifest.webmanifest.
pwa_iconsfiltro$iconsIconos de la PWA.

Valores de $ctx en seo_schema y seo_meta, con lo que trae $data:

$ctx$data
homepage
movie, seriestitle
seasontitle, season
episodetitle, episode
genre, tag (y taxonomías propias)term, page
personperson, page
pagepage (la página estática)
searchq
movies, series_list, year, genres, tags, people (listados)page
php
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 #

HookTipoArgumentosCuándo
settings_groupsfiltro$groups (clave => [label, fields[]])Grupos de Ajustes. Así entran los de los plugins ($plugin->setting() lo hace por ti).
settings_before_savefiltro$save, $groupValores ya validados (clave => valor) antes de guardarlos.
settings_savedacción$group, $saveTras guardar un grupo de Ajustes (Admin → SEO dispara 'seo', ['tab' => …]).
user_loginacción$userInicio de sesión correcto en el panel.
login_failedacción$login, $ipIntento de inicio de sesión fallido.
role_capabilitiesfiltro$caps, $roleCapacidades de un rol. Ver páginas de administración.
mail_sendfiltronull, $messageDevuelve 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_installedacción$type, $slugTras instalar un zip de plugin o theme.
extension_updatedacción$type, $slugTras actualizar uno ya instalado.
extension_activatedacción$type, $slugTras activar un plugin o cambiar de theme.
extension_deactivatedacción$type, $slugTras desactivarlo.
extension_uninstalledacción$type, $slugTras borrar el plugin y sus datos.
update_beforeacción$old, $newActualización del núcleo, antes de reemplazar archivos.
update_afteracción$old, $newActualización del núcleo terminada (migraciones y caché incluidas).

Panel de administración #

Detalle y ejemplos en páginas de administración.

HookTipoArgumentosPara qué
admin_menufiltro$itemsLas entradas del menú del panel.
admin_routesacción$routerRutas propias dentro de /admin (con su sesión y CSRF).
admin_headacción—Dentro del <head> del panel. Nunca llega al sitio público.
admin_footeracción—Antes de </body> del panel.
admin_dashboard_widgetsfiltro$widgetsTarjetas del escritorio: ['title' => …, 'html' => …].
admin_dashboard_status_cardsfiltro$cardsTarjetas del bloque de estado del escritorio. Misma forma.
admin_disk_min_free_gbfiltronullGB libres mínimos antes de avisar de disco lleno.
admin_onboarding_stepsfiltro$items, $stats, $healthLista corta de primeros pasos del escritorio: [key, done, link, label?].
admin_onboarding_itemsfiltro$itemsLista completa de Admin → Primeros pasos.
admin_search_resultsfiltro$items, $type, $qResultados del buscador del panel.
admin_settings_links_forfiltro[], $fieldKeyEnlaces [url, label] junto a un campo de Ajustes.
admin_settings_fieldacción$fieldKeyHTML propio debajo de un campo de Ajustes.
admin_titles_index_topacción$typeEncima de la tabla de Películas o Series (movie/series).
admin_title_form_topacción$type, $titleArriba del formulario de un título ($title es null al crear).
admin_title_actionsacción$titleBotones junto al título en su página de edición.
admin_catalog_panelacción—En Admin → Catálogo, bajo el formulario del catálogo.
HookTipoArgumentosCuándo
tmdb_importedacción$id, $type, $tmdbId, $dataTítulo importado desde TMDB (plugin TMDB Import).
tmdb_season_importedacción$titleId, $tmdbId, $numberTemporada importada desde TMDB.
catalog_importerfiltronullQuién importa las líneas que piden TMDB: ['job' => 'tmdb.import', 'ready' => bool].
catalog_importedacción$id, $type, $tmdbIdTítulo creado desde el catálogo precargado del Hub.
catalog_syncedacción$scope, $versionRecorrido completo del catálogo terminado.
csv_import_resolve_titlefiltronull, $type, $rowImportació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.

HookPluginTipoArgumentosCuándo
member_registeredMembersacción$memberAlta de un miembro.
member_blockedMembersacción$memberUn miembro fue bloqueado.
member_deletedMembersacción$idCuenta borrada (por el miembro o el admin).
comment_postedCommentsacción$commentComentario enviado.
comment_statusCommentsacción$id, $statusComentario aprobado, rechazado o marcado como spam.
comment_moderationCommentsfiltro$status, $body, $memberEstado inicial de un comentario nuevo: approved, pending o spam (otro valor se convierte en pending).
vip_payment_receivedMembers VIPacción$id, $memberUn miembro envió un pago para revisar.
vip_payment_approvedMembers VIPacción$paymentId, $memberId, $untilPago aprobado; VIP hasta $until.

Recetas #

Cambiar el número de relacionados solo en series:

php
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:

php
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é:

php
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:

php
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;
});

¿Te quedó alguna duda?

Escríbenos y te ayudamos con tu caso.

Hablar con nosotros
¿Hablamos?