API & development
Package manifest, signing, migrations and trust
Build reviewed API-1 archives with exact file inventories, private offline keys and guarded schema changes.
About 2 min read
On this page
Source manifest
A reviewed module source has package.json, bootstrap.php, its declared PHP/assets and optional declared migrations. Metadata includes slug, name, numeric version, category, API 1, core_min/core_max, entry, dependency minimums and migrations. Themes use their own reviewed view/assets payload. Keep .env, vendor/node_modules, secret files, private signing keys and undeclared/symlink payloads out.
package.json is unsigned build input. The installable archive requires the builder-generated root manifest.json, sorted SHA-256 inventory, publisher key identity and detached Ed25519 signature over canonical JSON. Do not implement a second canonicaliser or custom signature scheme.
Sign on a controlled publisher host
Use the existing package builder with PHP sodium/ZIP and a private publisher key kept outside the source/application/public directories. Generate a new publisher key only for a genuinely new independent publisher; Orbit premium packages must use their existing independently pinned release publisher. Never use a licence-authority key as an extension signing key.
php tools/build-package.php /ABSOLUTE/REVIEWED-SOURCE /ABSOLUTE/PRIVATE-PUBLISHER-KEY.json /ABSOLUTE/RELEASE-OUTPUT/module-1.0.0.zip
The paths are placeholders. Keep output outside source and preserve the exact archive/checksum. Signing establishes origin/integrity, not code safety or commercial publication approval.
Installer limits and migrations
The installer enforces compressed/unpacked/file-count/expansion limits and rejects traversal, absolute/hidden paths, symlinks, case collisions, undeclared/missing files and bad hashes/signatures. The source SDK documents limits of 25 MB compressed, 100 MB unpacked and 1,500 payload files; verify the exact installed release before planning a larger package.
Migrations must be explicitly declared with the emaila_ext_<slug_with_underscores> naming convention and should use addon-owned tables. Naming does not sandbox SQL/PHP. Review effects and backup before enable. A failed later load does not undo already applied migrations; disabling/uninstalling is not automatic data rollback.
Compatibility evidence
Record exact core/module/PHP versions, dependencies, mocked failure/replay tests and actual provider sandbox results where relevant. Install disabled, review, enable separately and retest connections after upgrade. Do not distribute developer skeletons as working providers or treat a built ZIP as an approved release.