Hooks are the points where your code plugs into MovieMaster without touching the core. This page explains how they work and lists every hook the code fires, with its arguments and the exact moment it runs.
Actions and filters #
- An action announces that something happened. Your functions run and whatever they return is ignored. Template actions (
head,footer…) print HTML withecho. - A filter passes a value through every hooked function, in a chain. Each one receives the value (plus context arguments) and must return it, modified or not.
// Action: do something when a title is saved
add_action('title_saved', static function (array $title, bool $isNew): void {
if ($isNew) {
logger()->info('New title: ' . $title['title']);
}
}, 10, 2);
// Filter: change a value and return it
add_filter('listing_per_page', static fn(int $n): int => 30);Hook functions #
| Function | What it does |
|---|---|
add_action(string $hook, callable $cb, int $priority = 10, int $acceptedArgs = -1) | Hooks a function to an action. |
add_filter(string $hook, callable $cb, int $priority = 10, int $acceptedArgs = -1) | Hooks a function to a filter. |
remove_action(string $hook, callable $cb, int $priority = 10): bool | Removes a function (same function and same priority it was added with). |
remove_filter(string $hook, callable $cb, int $priority = 10): bool | Same, for filters. |
do_action(string $hook, mixed ...$args) | Fires your own action. |
apply_filters(string $hook, mixed $value, mixed ...$args): mixed | Passes a value through your own filter. |
has_action(string $hook): bool | Is anyone listening to this hook? |
did_action(string $hook): int | How many times it has already fired in this request. |
current_filter(): ?string | The hook currently running. |
do_action_deprecated(string $hook, array $args, string $version, string $replacement = '') | Fires a deprecated action: logs a warning only if someone is listening. |
apply_filters_deprecated(string $hook, array $args, string $version, string $replacement = '') | Same, for a deprecated filter. |
hooks() | The HookManager (methods add, remove, removeAll, doAction, applyFilters, has, did, current). |
Priority #
Functions run from lowest to highest priority; with the same priority, in the order they were added. Use 5 to run before almost everything and 20 or higher to run after (for example, to tweak what another plugin already added).
Number of arguments #
With $acceptedArgs = -1 (the default) your function receives all of the hook's arguments. Pass a number and it receives only the first ones. Use this when you hook a plain PHP function or a method that doesn't accept extra arguments:
add_filter('seo_title', 'trim', 10, 1);Removing another plugin's hook #
remove_action/remove_filter need the same function: a named function, a static method ([Class::class, 'method']), or the same object. An anonymous closure can't be removed from the outside; if you want others to be able to disable your behavior, offer it as a setting or expose your own filter:
if (apply_filters('my_plugin_show_box', true, $title)) {
echo $box;
}Your own hooks #
Always prefix the name with your slug (my_plugin_something) and document it in your README. If you change an already-published hook, keep the old one around for a while with do_action_deprecated('old', [$a, $b], '2.0.0', 'new'): it does nothing if nobody uses it, and logs a warning for those who do.
Live list from the console #
This page lists the core 0.9.x hooks. The exact list for your version is generated by the code itself:
php bin/console.php hooks:list # name, action or filter, and number of uses
php bin/console.php hooks:list --where # + first file:line where it fires
php bin/console.php hooks:list --type=filter --jsonBoot, routes, and console #
| Hook | Type | Arguments | When |
|---|---|---|---|
booted | action | $app | Config, container, and database ready, before plugins load: a plugin never sees it. That's what init is for. |
routes | action | $router, $app | Route registration. $plugin->route() hooks here with priority 5. |
init | action | $app | Core, plugins, and theme loaded, routes registered. The place for anything that needs all of the above. |
terminate | action | $request | At the end of the request, after the response has been sent. Good for work that shouldn't delay the page. |
migrate | action | $migrator, $io | php bin/console.php migrate, after the core's migrations. |
console_commands | filter | $commands (name => class) | Add commands to bin/console.php. See creating plugins. |
cron | action | $cron | Every cron run (every minute). Shortcut: $plugin->cron('minute', fn). |
cron_hourly | action | — | Once an hour, after the core's maintenance. Shortcut: $plugin->cron('hourly', fn). |
cron_daily | action | — | Once a day, after the core's maintenance (cleanup, license, updates). Shortcut: $plugin->cron('daily', fn). |
queue_handlers | filter | $handlers (type => callable|class) | Queue handlers. Shortcut: $plugin->job($type, $handler). |
Public site templates #
Template actions are fired by the theme with @hook('name'). Your function prints HTML with echo; escape any data-derived value with e().
| Hook | Type | Arguments | Where |
|---|---|---|---|
template_data | filter | $data, $template | Before rendering a page: add or change template variables. |
before_render | action | $template, $data | Right before rendering. Useful for remembering $template and deciding what to print in head. |
template_path | filter | $template, $template | Change which template is used ('title' → 'my-plugin::detail'). |
body_class | filter | $class ('tpl-<template>') | Classes on the <body>. Append with $class . ' my-class'. |
head | action | — | Inside <head>. This is where meta tags, the canonical, the JSON-LD, and your inline CSS go. |
body_open | action | — | Right after <body>. |
nav_items | action | — | Inside the main <nav>, after the theme's own links. Prints <a> tags. |
before_content | action | — | Before the main content (<main>). |
after_content | action | — | After the main content. |
footer | action | — | In the footer. |
body_close | action | — | Right before </body>. The place for your <script type="module">. |
player_before | action | — | On the detail page and the episode page, before the player. |
player_after | action | — | On the detail page and the episode page, after the player. |
comments | action | — | Slot for the comments box in title.tpl and episode.tpl. Only fired by a theme that declares comments@1. |
account_sections | action | — | On the Members plugin's "My Account" page, to add sections. |
home_rails | filter | $rails | Home page rails. See the shape below. |
listing_per_page | filter | $perPage | Items per page in listings (minimum 6). |
related_limit | filter | $limit, $title | How many related titles to look for. |
related_titles | filter | $titles, $title | The final list of related titles for a detail page. |
embed_html | filter | $html, $source | The HTML of a video server (the iframe the facade creates). |
ad_scripts_code | filter | $code, $key | Code of an ad block from Admin → Ad scripts. Return '' to not print it. |
search_suggestions | filter | $out, $q | Search box suggestions: ['titles' => [], 'people' => [], 'genres' => []]. |
Shape of a home_rails item:
$rails['my_rail'] = [
'title' => 'Recommended', // visible text
'url' => url('/movies') . '?sort=rating', // "view all" link (optional)
'items' => $titles, // TitleRepository rows; a rail with no items isn't rendered
'style' => 'cards', // cards | top10 | episodes
];Content #
| Hook | Type | Arguments | When |
|---|---|---|---|
title_saved | action | $title, $isNew | A movie or series was created or edited ($title = the row already saved). |
title_deleted | action | $title | A title was deleted (its URLs' 410 has already been written). |
title_query | filter | $query, $filters | The title listing query, before it runs. Add conditions via the builder. |
sources_saved | action | $titleId, $episodeId | Video sources saved ($episodeId is null for a movie). |
person_saved | action | $person | A person was created or edited. |
person_deleted | action | $id | A person was deleted. |
term_saved | action | $term, $taxonomy | A genre, tag, or custom term was saved. |
term_deleted | action | $term | A term was deleted. |
taxonomy_label | filter | ucfirst($taxonomy), $taxonomy | The admin panel name of a custom taxonomy. |
taxonomy_url_prefix | filter | $prefix, $taxonomy | The URL word for a custom taxonomy. |
url_key_changed | action | $kind, $id, $old, $new | A season's or episode's URL word changed ($kind = season or episode). The 301s have already been created. |
availability_changed | action | $id, $type, ['title' => bool, 'episodes' => int[]] | A title or episodes became available (useful for notifying subscribers). |
media_uploaded | action | $media | An image was uploaded and processed. |
media_deleted | action | $media | An image was deleted along with all its variants. |
media_shared_fetch | filter | null, $slot | Before downloading the image for a slot: return an existing media row to reuse it (media library shared across sites). |
media_offload_paths | filter | [], $slot, $ids | Admin → Catalog → free disk space: TMDB paths ([id => '/abc.jpg']) of the images that can be served from elsewhere. |
content_purged | action | $tags | After purging cache tags. |
purge_tags | filter | $tags | The tags to purge, before doing so. Add your own. |
page_cache_purged | action | $tags, $paths | After clearing pages from the static page cache (['*'] = all of it). Use this to notify a CDN. |
page_cache_bypass | filter | false, $request | Return true to skip storing this response in the static page cache. |
Video sources and player #
| Hook | Type | Arguments | What for |
|---|---|---|---|
source_languages | filter | $languages | Audio languages for sources: ['latino', 'castellano', 'subtitulado', 'english', 'original']. |
source_language_code | filter | $code, $language | Short code for the language tab (LAT, ESP, SUB…). |
source_default_language | filter | $language, $siteLang | The source language that opens first. |
player_api_url | filter | $url | Base URL of the player's resolver API (the one read from data-api-base). |
player_api_languages | filter | $languages, $siteLang | Languages requested from the API based on the site language. |
player_api_sources | filter | $grouped, $title, $episode | Sources grouped by language, as received by the player. |
player_api_covers | filter | true, $title, $episode | Return false to not use the API for that title or episode. |
player_source_allowed | filter | true, $source, $title, $request | Money Player asks before playing: false blocks the source (used by Members VIP). |
money_player_templates | filter | ['title', 'episode'] | Templates where Money Player is active. |
money_player_resolvers | filter | $classes | Classes implementing ResolverInterface to play a host inside the built-in player. |
SEO, sitemaps, and PWA #
| Hook | Type | Arguments | What for |
|---|---|---|---|
seo_title | filter | $title | The page's final <title>. |
seo_schema | filter | $graph, $ctx, $data | The JSON-LD nodes (@graph). Add nodes to the array; never print another <script type="application/ld+json">. |
seo_meta | filter | $seo, $ctx, $data | The full PageSeo object (title, description, canonical, robots, image, alternates…). |
sitemap_index | filter | $items ('/path.xml' => lastmod) | Entries in the sitemap index. Add your own. |
sitemap_custom | filter | null, $type, $chunk | Content of a non-core sitemap (/sitemap-<type>-<n>.xml or /sitemap-<type>.xml, $type lowercase letters only): return the XML or null (404). |
robots_txt | filter | $text | The generated robots.txt. |
indexnow_request | filter | null, $body | Submission to IndexNow: return an HTTP status code (int) if you send it yourself. |
pwa_manifest | filter | $data | The manifest.webmanifest. |
pwa_icons | filter | $icons | PWA icons. |
Values of $ctx in seo_schema and seo_meta, with what $data carries:
$ctx | $data |
|---|---|
home | page |
movie, series | title |
season | title, season |
episode | title, episode |
genre, tag (and custom taxonomies) | term, page |
person | person, page |
page | page (the static page) |
search | q |
movies, series_list, year, genres, tags, people (listings) | 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;
});Settings, users, and extensions #
| Hook | Type | Arguments | When |
|---|---|---|---|
settings_groups | filter | $groups (key => [label, fields[]]) | Settings groups. This is how plugin settings get in ($plugin->setting() does it for you). |
settings_before_save | filter | $save, $group | Already-validated values (key => value) before they're saved. |
settings_saved | action | $group, $save | After a settings group is saved (Admin → SEO fires 'seo', ['tab' => …]). |
user_login | action | $user | Successful admin panel sign-in. |
login_failed | action | $login, $ip | Failed sign-in attempt. |
role_capabilities | filter | $caps, $role | Capabilities of a role. See admin pages. |
mail_send | filter | null, $message | Return true if you sent the email yourself (your own SMTP, an API) or false if it failed; null lets the core send it. $message = to, subject, body, from, from_name. |
extension_installed | action | $type, $slug | After installing a plugin or theme zip. |
extension_updated | action | $type, $slug | After updating one already installed. |
extension_activated | action | $type, $slug | After activating a plugin or switching themes. |
extension_deactivated | action | $type, $slug | After deactivating it. |
extension_uninstalled | action | $type, $slug | After deleting the plugin and its data. |
update_before | action | $old, $new | Core update, before files are replaced. |
update_after | action | $old, $new | Core update finished (migrations and cache included). |
Admin panel #
Details and examples in admin pages.
| Hook | Type | Arguments | What for |
|---|---|---|---|
admin_menu | filter | $items | The admin panel's menu entries. |
admin_routes | action | $router | Your own routes inside /admin (with its session and CSRF). |
admin_head | action | — | Inside the admin panel's <head>. Never reaches the public site. |
admin_footer | action | — | Before the admin panel's </body>. |
admin_dashboard_widgets | filter | $widgets | Dashboard cards: ['title' => …, 'html' => …]. |
admin_dashboard_status_cards | filter | $cards | Cards in the dashboard's status block. Same shape. |
admin_disk_min_free_gb | filter | null | Minimum free GB before warning about a full disk. |
admin_onboarding_steps | filter | $items, $stats, $health | Dashboard's short list of first steps: [key, done, link, label?]. |
admin_onboarding_items | filter | $items | Full list of Admin → Getting started. |
admin_search_results | filter | $items, $type, $q | Results from the admin panel's search box. |
admin_settings_links_for | filter | [], $fieldKey | Links [url, label] next to a settings field. |
admin_settings_field | action | $fieldKey | Your own HTML below a settings field. |
admin_titles_index_top | action | $type | Above the Movies or Series table (movie/series). |
admin_title_form_top | action | $type, $title | At the top of a title's form ($title is null when creating). |
admin_title_actions | action | $title | Buttons next to the title on its edit page. |
admin_catalog_panel | action | — | On Admin → Catalog, below the catalog form. |
Import and catalog #
| Hook | Type | Arguments | When |
|---|---|---|---|
tmdb_imported | action | $id, $type, $tmdbId, $data | A title was imported from TMDB (TMDB Import plugin). |
tmdb_season_imported | action | $titleId, $tmdbId, $number | A season was imported from TMDB. |
catalog_importer | filter | null | Who imports the lines that request TMDB: ['job' => 'tmdb.import', 'ready' => bool]. |
catalog_imported | action | $id, $type, $tmdbId | A title was created from the Hub's pre-loaded catalog. |
catalog_synced | action | $scope, $version | A full catalog sync finished. |
csv_import_resolve_title | filter | null, $type, $row | CSV import: return the id of an existing title for a row. |
Hooks from bundled plugins #
These are fired by plugins that ship with the core; they only exist if the plugin is active.
| Hook | Plugin | Type | Arguments | When |
|---|---|---|---|---|
member_registered | Members | action | $member | A member signed up. |
member_blocked | Members | action | $member | A member was blocked. |
member_deleted | Members | action | $id | An account was deleted (by the member or the admin). |
comment_posted | Comments | action | $comment | A comment was submitted. |
comment_status | Comments | action | $id, $status | A comment was approved, rejected, or marked as spam. |
comment_moderation | Comments | filter | $status, $body, $member | Initial status of a new comment: approved, pending, or spam (any other value becomes pending). |
vip_payment_received | Members VIP | action | $id, $member | A member submitted a payment for review. |
vip_payment_approved | Members VIP | action | $paymentId, $memberId, $until | Payment approved; VIP until $until. |
Recipes #
Change the number of related items only for series:
add_filter('related_limit', static fn(int $n, array $t): int => $t['type'] === 'series' ? 18 : $n, 10, 2);Hide titles with a given tag from listings:
add_filter('title_query', static function ($q, array $filters) {
if (empty($filters['term_id'])) { // they're still shown on that tag's own page
$q->whereNotIn('titles.id', db()->table('title_terms')->select('title_id')->where('term_id', 42));
}
return $q;
});Notify a CDN when the cache is purged:
add_action('page_cache_purged', static function (array $tags, array $paths): void {
app(MyPlugin\Cdn::class)->purge($paths === ['*'] ? null : $paths); // better to queue it with $plugin->jobs()
});Add your own sitemap:
add_filter('sitemap_index', static function (array $items): array {
$items['/sitemap-events-1.xml'] = db()->table('events')->max('updated_at');
return $items;
});
add_filter('sitemap_custom', static function (?string $xml, string $type, int $chunk): ?string {
return $type === 'events' ? app(MyPlugin\Sitemap::class)->xml($chunk) : $xml;
});