Composer-based bundles #

This page is for bundlers who manage the bundle as a Composer project: an agency starter kit, a distribution of their own, an image build. Composer is the way Exponential and all its extensions are delivered, so a bundle that speaks Composer gets updates the same way the project publishes them.

Contents #

1. The shape of a Composer bundle
2. A root composer.json
3. The installer plugin
4. Your own extensions
5. Scripts after install
6. Rules

The shape of a Composer bundle #

your-bundle/
    composer.json        your root package: requires se7enxweb/exponential and your parts
    composer.lock        committed: the exact versions of this bundle release
    kickstart.ini.template  or the exp:install options your build uses
    packages/            your site package(s), if any
    README.md, LICENSE   your notices

After composer install the kernel lands in the project root (.), next to your files, because the package type ezpublish-legacy is installed there by the installer plugin (3.2 C).

A root composer.json #

A minimal example; replace the names and versions with yours and check each package exists before you use it:

{
    "name": "example/exponential-bundle",
    "description": "Example bundle, based on Exponential",
    "license": "GPL-2.0-or-later",
    "type": "project",
    "require": {
        "se7enxweb/exponential": "~6.0.14",
        "example/example_theme": "~1.2.0"
    },
    "repositories": [
        { "type": "vcs", "url": "https://git.example.com/example/example_theme.git" }
    ],
    "config": {
        "allow-plugins": {
            "se7enxweb/exponential-legacy-installer": true
        }
    },
    "scripts": {
        "post-install-cmd": [ "@php bin/php/ezpgenerateautoloads.php" ],
        "post-update-cmd": [ "@php bin/php/ezpgenerateautoloads.php" ]
    }
}

• license: name your bundle's license with an SPDX identifier. Code that is combined with Exponential and distributed with it must be compatible with the GPL; ask counsel (GPL obligations).
• The ~ constraints follow the project's own style: the last position floats (Versions, tags and pinning).
• The scripts mirror what the kernel's own composer.json runs ("legacy-scripts": ["@php bin/php/ezpgenerateautoloads.php"] on post-install-cmd and post-update-cmd), because "Composer runs only the scripts of the root package, which is now yours".

The installer plugin #

Composer 2.2 and later asks whether to trust se7enxweb/exponential-legacy-installer. Allow it in composer.json (as above) or with:

composer config allow-plugins.se7enxweb/exponential-legacy-installer true

"If you answer no, the kernel lands in vendor/se7enxweb/exponential/ and the extensions in vendor/ as well, where nothing finds them." In a build pipeline nobody answers, so put the setting in the file.

Your own extensions #

• Publish each extension as its own Composer package (a composer.json with a name, a license and the type your existing extensions use), in a repository you control.
• Give each release a tag, and write the same version into ezinfo.php and extension.xml before tagging (Extension metadata).
• Activate the extensions in your site package, or in settings/override/site.ini.append.php ([ExtensionSettings] ActiveExtensions[]), as the default extension distribution page shows.
• Extensions of your own can live in a second extension root (site.ini [ExtensionSettings] AdditionalExtensionDirectories[], empty by default), apart from third-party ones (Additional extension directories).

Scripts after install #

After every composer install or update, the bundle needs fresh autoload arrays and caches. The script above does the first; the rest is on Caches and autoloads after building.

Rules #

• To do: Build with composer install from your committed composer.lock; run composer update only when you prepare a new bundle release.
• To do: Add --no-dev for anything that goes to production.
• To do: Never edit files inside vendor/ or inside a Composer-installed extension: the next install replaces them. Put changes in your own extension or send them upstream.
• To do: Installations made of Git checkouts of the extensions must not run composer update blindly: "it replaces the checkouts" (Default extension distribution).
• To do: Record the output of composer show with every bundle release.

Related pages #

• Lock files and reproducible builds
• Adding and removing extensions
• Agency starter kits
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.