MovieMaster is extended with plugins and themes written in PHP 8.2, with no Composer or frameworks. This guide explains how it works under the hood, sets up a local site, and builds your first plugin in five minutes.
What you can build #
| Extension | What it's for | Where it lives | Manifest |
|---|---|---|---|
| Plugin | Add features: rails on the homepage, new pages, settings, scheduled tasks, importers, players, advertising, user accounts, comments… | content/plugins/<slug>/ | plugin.json |
| Theme | Change the look of the public site: templates, CSS, JavaScript, and brand images. | content/themes/<slug>/ | theme.json |
| Child theme | Tweak an existing theme (usually Cinema, slug default) by changing only the files you need. | content/themes/<slug>/ with "parent" | theme.json |
A site can have many active plugins and only one active theme. Plugins and themes communicate through hooks (actions and filters) and named contracts (player@1, mylist@1…), never knowing each other's classes.
How a request boots #
Knowing the order tells you where to hook in:
- Boot of the core: configuration, service container, and database. The
bootedaction fires. - Extension loading: each active plugin's
plugin.phpruns (receiving$plugin), then the active theme'sfunctions.php(the parent's first, then the child's). - Routes: the core registers its own, then the plugins' (
routeswith priority 5), and theroutesaction fires. - The
initaction fires: everything is loaded. This is the place for anything that needs plugins, theme, and routes all at once. - Middleware (HTTPS, maintenance, trailing slash, language, legacy URLs, page cache) and the route's controller.
- On public pages:
template_data→before_render→template_path→ the theme's template (with itshead,body_open,nav_items,before_content,after_content,footer,body_closehooks). - The response goes out (and is stored in the static cache if cacheable), and
terminatefires.
In the console (php bin/console.php …) and in the cron, plugins load the same way, so your cron, cron_hourly, cron_daily, and migrate hooks work without any extra effort.
The non-negotiable rules #
MovieMaster scores 100 on all four Lighthouse metrics on mobile and desktop. Every extension must keep it that way:
- Inline CSS only, with a budget: 20,480 bytes per page (32,768 at most for a theme with its own
critical.css). No<link rel="stylesheet">or@import. - Initial JavaScript ≤ 5,120 bytes. Everything else loads on demand with
import(). - No web fonts, and no third-party scripts or resources in the initial load.
- Images always via
img()(AVIF → WebP → JPEG withsrcset), never a hand-written<img src>. - Players and trailers behind a facade: the iframe is created on click.
- Cacheable pages: anything that depends on who's looking (session, lists, permissions) is requested with
fetchfrom a route withcache => false; it's never printed into the HTML. - URLs always via
route(),url(), orlang_url(): the site owner can change the URL words (/movie/→/pelicula/) in Admin → SEO. - Never delete content with hand-written SQL: use the repositories so the 410s get written, the cache gets purged, and the sitemaps get updated.
Set up a local site #
You need PHP 8.2 or later with pdo (pdo_mysql or pdo_sqlite), mbstring, json, fileinfo, sodium, and gd or imagick; zip, curl, and intl are recommended. To compile the themes' CSS, Node. From the CMS folder:
composer install && npm install
php bin/console.php install --url=http://127.0.0.1:8090 --name="Dev" --admin=admin \
[email protected] --password='Change-this-2026!' --lang=es --langs=es,en
php bin/console.php demo:seed # fictional catalog with images, no external calls
php bin/dev-server.php 127.0.0.1:8090 # site at / and admin at /adminbin/dev-server.php wraps php -S with a router that mimics Apache and nginx rules (page cache, protected folders). Errors go to content/logs/app.log. To process queues without cron, run php bin/console.php queue:work in another terminal.
Your first plugin in five minutes #
1. Generate the skeleton #
php bin/console.php make:plugin hello-world --name="Hello World"Creates content/plugins/hello-world/ ready to pass plugin:check:
content/plugins/hello-world/
plugin.json spec 1 manifest
plugin.php entry point: receives $plugin and only orchestrates
Lifecycle.php install / upgrade / uninstall
src/Plugin.php your classes (namespace HelloWorld\)
lang/es.php translatable strings: __('hello-world::key')
lang/en.php2. Add a rail to the homepage #
Replace the contents of plugin.php:
<?php
/** @var MovieMaster\Extensions\PluginContext $plugin */
declare(strict_types=1);
use HelloWorld\Rail;
$plugin->lang(__DIR__ . '/lang');
$plugin->setting('title', [
'type' => 'text',
'label' => __('hello-world::title_setting'),
'default' => 'Recommended',
]);
add_filter('home_rails', fn(array $rails) => Rail::add($rails, $plugin));And create src/Rail.php:
<?php
declare(strict_types=1);
namespace HelloWorld;
use MovieMaster\Content\Repositories\TitleRepository;
use MovieMaster\Extensions\PluginContext;
final class Rail
{
public static function add(array $rails, PluginContext $plugin): array
{
$items = app(TitleRepository::class)->list(['order' => 'rating', 'type' => 'movie'], 12);
$rails['hello_world'] = [
'title' => (string) $plugin->get('title'),
'url' => url('/movies') . '?sort=rating',
'items' => $items, // a rail with no items isn't rendered
'style' => 'cards', // cards | top10 | episodes
];
return $rails;
}
}Add the key to lang/es.php ('title_setting' => 'Título de la fila') and to lang/en.php.
3. Validate, activate, and test #
php bin/console.php plugin:check hello-worldActivate the plugin in Admin → Plugins. The rail appears at the end of the homepage, and its setting in Settings, under the plugins section of the sidebar index ("Hello World"). No CSS or JavaScript needed: the rail uses the theme's markup, so it doesn't use any budget.
Safe mode #
When you activate a plugin, MovieMaster checks its requirements (requires) and loads it as a trial. If an active plugin throws an exception on boot, it deactivates itself and the admin shows a notice with the error: a broken plugin never leaves the site blank. Check content/logs/app.log for details.
Where to go next #
| I want to… | Guide |
|---|---|
Fill out plugin.json or theme.json correctly | Manifest reference |
| Settings, routes, migrations, queue, cron, translations | Create plugins |
| See all the actions and filters with their arguments | Hooks reference |
| Look up helpers, database, repositories, cache, mail | PHP API |
Write .tpl templates | Template engine |
| Design a theme or a child theme | Create themes |
| Add screens to the admin panel | Admin pages |
| Validate, package, and publish to the store | Validate, package, and publish |