Saltar al contenido
MovieMaster

Desarrolladores: plugins y themes

Validate, package and publish

10 min de lectura 7 apartados

En esta página

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:

bash
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]
CommandWhat it does
make:pluginCreates 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:migrationCreates 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:themeCreates a child theme in content/themes/<slug>/ that inherits everything from the parent. See creating themes.
plugin:check, theme:checkValidate the extension (table below). Exit with code 1 if there are errors; warnings don't fail it. Accept the slug or a path.
ext:packValidates and, if there are no errors, generates the zip for distribution.
hooks:listLists every hook the code fires (core, themes, and installed plugins). --where adds the file and line where each one fires.

What validation checks #

Manifest #

CheckLevel
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 #

CheckLevel
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 #

CheckLevel
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 #

bash
php bin/console.php ext:pack plugin my-plugin --out=dist
text
dist/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.zip

The 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 .zip files, .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:

  1. Opens the zip and looks for the manifest at the root or inside its single folder.
  2. Rejects the package if requires.core doesn't accept the installed version.
  3. Places the folder in content/plugins/<slug>/ (or content/themes/<slug>/), replacing any existing one.
  4. 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:

  1. Downloads the zip and checks its sha256 and the Hub's signature. If they don't match, it's deleted without being opened.
  2. Checks that the zip's slug is the expected one and that requires.core accepts the installed core.
  3. Runs a syntax check on every .php file in the new version.
  4. Backs up the current folder and the tables declared in data.tables.
  5. Puts the new code in place, runs the migrations, and calls upgrade($from, $to).
  6. Requests the site's home page. A 5xx response (or none at all) counts as a failure.
  7. 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, and version must 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, stable or beta. 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:

ChangeExampleBump
A fix that doesn't change anything visible to othersA save errorPatch: 1.2.0 → 1.2.1
New features, backward compatibleA new setting or hookMinor: 1.2.1 → 1.3.0
Something stops working as beforeYou remove a hook, change a table, or change a setting's formatMajor: 1.3.0 → 2.0.0
  • Declare in requires.core the range you've tested: make:plugin sets ^<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() or apply_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:

LevelWhat it includesGuarantee
StableThe 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.
Contractsplayer@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.
InternalEverything 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:check with 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.
  • [ ] version bumped in the manifest, and release notes written.
  • [ ] Strings translated in every language you include.
  • [ ] ext:pack generated from a clean copy (no local files or secrets).

¿Te quedó alguna duda?

Escríbenos y te ayudamos con tu caso.

Hablar con nosotros
¿Hablamos?