From the code in your folder to an extension any site can install and update without worry: the console tools, what validation checks, how the zip is built, what happens on a site when it's installed or updated, and what the core promises about compatibility.
Console tools #
All of these run from the CMS folder:
php bin/console.php make:plugin my-plugin [--name="My Plugin"] [--namespace=MyPlugin] [--description=…] [--force]
php bin/console.php make:migration my-plugin create_my_plugin_items_table [--table=my_plugin_items]
php bin/console.php make:theme my-theme [--parent=default] [--name=…] [--force]
php bin/console.php plugin:check my-plugin # or --all
php bin/console.php theme:check my-theme # or --all
php bin/console.php ext:pack plugin my-plugin [--out=dist]
php bin/console.php hooks:list [--type=action|filter] [--where] [--json] [--undocumented]| Command | What it does |
|---|---|
make:plugin | Creates content/plugins/<slug>/ with plugin.json spec 1, plugin.php, Lifecycle.php, src/Plugin.php, and lang/{es,en}.php. Doesn't activate it. Passes plugin:check as-is. |
make:migration | Creates the plugin's next migrations/NNNN_<name>.php. With --table, or with a create_<table>_table name, it already comes with the create skeleton. Remember to declare the table in data.tables. |
make:theme | Creates a child theme in content/themes/<slug>/ that inherits everything from the parent. See creating themes. |
plugin:check, theme:check | Validate the extension (table below). Exit with code 1 if there are errors; warnings don't fail it. Accept the slug or a path. |
ext:pack | Validates and, if there are no errors, generates the zip for distribution. |
hooks:list | Lists every hook the code fires (core, themes, and installed plugins). --where adds the file and line where each one fires. |
What validation checks #
Manifest #
| Check | Level |
|---|---|
The folder name matches the slug. | error |
version is semver X.Y.Z. | error |
spec is a version this core understands. No spec is treated as the old format (spec 0). | error / warning |
requires.core and requires.php are understood and accept the installed version. An unknown format is never compatible. | error |
requires.core is *: better to declare the range you've tested. | warning |
name, description, author… are missing (shown in the admin panel and the store). | warning |
requires.plugins, provides, and contracts have the right format (name@1). | error |
textdomain is valid and every lang/*.php returns an array. | error |
Plugin #
| Check | Level |
|---|---|
The main file exists. | error |
plugin.php declares no classes or global functions: the core may load it twice (when uninstalling). | error |
The autoload folder exists. | error |
Lifecycle.php declares the expected class and extends MovieMaster\Extensions\Lifecycle. | warning |
data.tables, data.dirs, and data.settings_prefix are consistent (unprefixed tables, folders inside content/). | error / warning |
Every setting has a key and a known type. | error / warning |
Migrations are named NNNN_snake_case.php. | warning |
Theme #
The errors and warnings specific to themes (screenshot, parent, CSS budget, templates that don't compile) are in creating themes.
Files #
| Check | Level |
|---|---|
All .php files pass PHP's syntax check. | error |
No forbidden files: .env (also .env.example), *.pem, *.key, *.p12, *.pfx, id_rsa/id_ed25519 keys, any name containing credentials, .htpasswd, *.sqlite/*.db databases, or a .git folder. | error |
Folders packaging will leave out (node_modules, .idea, .vscode…). | warning |
Packaging #
php bin/console.php ext:pack plugin my-plugin --out=distdist/my-plugin-1.2.0.zip (14 files, 38.2 KB)
sha256 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
publish: php bin/console.php hub:publish --type=plugin --slug=my-plugin --version=1.2.0 --file=dist/my-plugin-1.2.0.zipThe sha256 identifies the exact package: include it if you distribute the zip yourself. The publish line is what the MovieMaster team uses to upload it to the Hub; it needs a publishing token that only the Hub's CI has.
The zip:
- Is only generated if validation has no errors.
- Contains a single folder,
my-plugin/, at the root, with the manifest inside. This is what the store and the admin panel's upload button expect. - Leaves out
.git,.svn,node_modules,.idea,.vscode,.DS_Store,Thumbs.db, other.zipfiles,.phpunit.cache, and editor temp files (*~). - Is named
<slug>-<version>.zip, using the version from the manifest.
Before distributing it, install it on a clean site (for example, the one from demo:seed) from Admin → Plugins → Upload plugin and activate it. It's the most faithful test of what the user will see.
What shouldn't go in the package #
- Credentials, API keys, or tokens. Ask for those via a
secret-type plugin setting instead. - Development dependencies and uncompiled sources, if they aren't needed on the site.
- Data from the site where you developed it: media, caches, logs, databases.
- Videos or large files the site could download when activated.
Installing and updating on a site #
Manual upload #
Admin → Plugins → Upload plugin (or Themes → Upload theme) accepts the zip from ext:pack. The core:
- Opens the zip and looks for the manifest at the root or inside its single folder.
- Rejects the package if
requires.coredoesn't accept the installed version. - Places the folder in
content/plugins/<slug>/(orcontent/themes/<slug>/), replacing any existing one. - Registers the version. The extension stays as it was: active if it already was, inactive if it's new.
On activation, the core test-loads the plugin before marking it active, runs the pending migrations, and calls install() (first time) or upgrade($from, $to) (if the registered version was different), then activate(). If anything throws an exception, the plugin stays deactivated and the error is shown in the admin panel.
Updating from the store #
Extensions installed and updated from the Hub go through a process with automatic rollback:
- Downloads the zip and checks its
sha256and the Hub's signature. If they don't match, it's deleted without being opened. - Checks that the zip's
slugis the expected one and thatrequires.coreaccepts the installed core. - Runs a syntax check on every
.phpfile in the new version. - Backs up the current folder and the tables declared in
data.tables. - Puts the new code in place, runs the migrations, and calls
upgrade($from, $to). - Requests the site's home page. A 5xx response (or none at all) counts as a failure.
- If any step fails, it restores the folder and the tables, leaving the site exactly as it was. The error is logged.
That's why your migrations and your upgrade() should be fast, and why the tables they touch need to be in data.tables: those are the only ones that get backed up and restored.
When the core changes version #
On every request, the core checks requires.core, requires.php, requires.ext, and requires.plugins for each active plugin. If any of them is no longer satisfied (for example, the site was updated to a core version outside your range), the plugin deactivates itself, without loading its code, and the admin panel shows the reason. The same happens if the plugin throws an exception while loading.
After updating the core, the active plugins' pending migrations also run.
Publishing to the store #
The Hub's store (Admin → Store on each site) is managed by the MovieMaster team. To publish an extension, free or paid, reach out via contact with the ext:pack zip and a description.
When publishing a version to the Hub:
- The publication's
type,slug, andversionmust match the zip's manifest, or it's rejected. - Versions are immutable: you can't republish the same version. To fix something, bump the number (
1.2.1). - Each version goes to a channel,
stableorbeta. Each site picks which channel to follow in Admin → Updates. - A published version can be pulled: it stops being offered and downloadable.
- Sites check for news every 12 hours and when Admin → Updates is opened. They're only offered what's compatible with their core and PHP version.
For each version, prepare short notes: what changes for the user, whether anything needs to be done manually, and whether it fixes a security issue.
Versioning your extension #
Number with semver:
| Change | Example | Bump |
|---|---|---|
| A fix that doesn't change anything visible to others | A save error | Patch: 1.2.0 → 1.2.1 |
| New features, backward compatible | A new setting or hook | Minor: 1.2.1 → 1.3.0 |
| Something stops working as before | You remove a hook, change a table, or change a setting's format | Major: 1.3.0 → 2.0.0 |
- Declare in
requires.corethe range you've tested:make:pluginsets^<current minor>, for example^0.9. - If you remove or rename one of your hooks, keep the old one around for a while with
do_action_deprecated()orapply_filters_deprecated(). - If you change the shape of a contract you offer (
provides), publish a new version of the contract (player@2) and keep the previous one as long as someone uses it.
Compatibility policy #
What the core promises to extensions:
| Level | What it includes | Guarantee |
|---|---|---|
| Stable | The hooks in the hooks reference, the functions and classes in the PHP API, the manifest format, and the $plugin context. | They don't change in an incompatible way within the same minor version (0.9.x). If a hook is retired, it keeps firing with a warning in the log for at least two more minor versions. |
| Contracts | player@1, mylist@1, comments@1… | An incompatible change creates a new version of the contract (@2); the previous one is kept as long as themes and plugins still use it. |
| Internal | Everything else: admin panel controllers, Catalog, Update, and Extensions classes, core tables, the admin panel's HTML. | Can change in any version. Don't rely on it. |
While the core is on 0.x, every minor version (0.9 → 0.10) can bring incompatible changes, called out in the changelog. That's why ^0.9 doesn't accept 0.10: it's intentional. When a new minor version comes out, test your extension and publish a version with the widened range.
To find out which hooks really exist in your version, check hooks:list: it reads the code, so it's never out of date.
Before each release #
- [ ]
plugin:check/theme:checkwith no errors. - [ ] Tested on a clean install and when updating from the previous version.
- [ ] Tested with safe mode in mind: no errors in
content/logs/app.log. - [ ] New migrations declared, with their tables in
data.tables. - [ ]
versionbumped in the manifest, and release notes written. - [ ] Strings translated in every language you include.
- [ ]
ext:packgenerated from a clean copy (no local files or secrets).