Skip to content
How-toForDeveloper⏱ About 10 min

Modules: sign, test, release and upgrade ​

Signing ​

Real servers accept a source module only when it's signed with a key they trust. The signature (Ed25519) covers the manifest, whose files lists the sha256 of every file, so one signature covers the whole module.

bash
php bin/console module:keygen <key_id>                                   # once; never reuse a key id
php bin/console module:package modules/source/hello --key=<key_id> --write-manifest
php bin/console module:verify modules/source/hello                       # "verified"

Servers trust keys whose .pub is in storage/modules/keys/trusted/. Keep private keys off servers; BMA's release build signs modules for you.

Refused asMeans
module_unsignedno signature (accepted only on a local sandbox)
module_signature_invalidwrong or untrusted key, or the manifest changed after signing: never accepted
module_package_tampereda file is missing, changed or not listed: rebuild and stamp again
module_bundle_unlistedthe UI bundle isn't in files: build, then stamp
version_existsthat version is already registered: bump version

Tests ​

Module tests live in the repository's tests/Modules/<Name>Test.php and run against a sandbox:

php
class HelloRoutesTest
{
    public function testHello()
    {
        assert_status(401, TestApi::anon()->get('/hello/hello'));
        assert_status(200, TestApi::as('ta_alpha')->get('/hello/hello'));
        assert_status(403, TestApi::as('ta_beta')->get('/hello/hello'));   // not enabled for beta
    }
}

Every endpoint needs: signed out → 401, another organization → 403 or 404, no permission → 403, and the happy path. bin/check runs the whole suite plus the scope lint, and builds and registers every module. Before review: module:validate passes, the scope lint is clean, your router serves only its prefixes.

Releasing a new version ​

  1. Change the code, bump version (add an x-changelog line).
  2. Build, sign, module:register (add --channel=beta to try it on beta first).
  3. Organizations move in Tenant Modules (or POST /tenants/<id>/modules/<id>/upgrade {"to": "1.1.0"}), after a preview: migrations to run, permissions and menus added or removed, requirements, warnings.
  4. There's no promotion from beta: register the same code again as a stable version.

Overrides and variants ​

  • Overrides: an organization renames, hides or moves your menu items and screens, or changes x-config, within the paths you list in overridable. They follow every upgrade; ones that stop applying are reported.
  • Variants: a private copy an organization owns (extends: {id, version}). Builder modules are forked from Tenant Modules → Create variant; source modules with php bin/console module:fork <base> <new-id> --tenant=<code>. A module and its variant can't both be on unless both set coexist. module:diff merges a newer base into a variant.