Dependency management with Composer #

This page is for engineers who add, upgrade or audit dependencies of an Exponential installation, or who maintain a package the root requires. The standard is PHP, PHP-FIG and Composer standards.

Contents #

1. The root package
2. Extensions are packages
3. Constraints and the lock file
4. Repinning in the right order
5. Development tools
6. Clones instead of archives
7. PSR status
8. Checklist for a new dependency

The root package #

Installing Exponential means composer install in the root of the repository; the README says the software does not run without it.

Extensions are packages #

The root require lists the extensions every installation gets as se7enxweb/* packages, each with a tilde constraint, for example se7enxweb/exponential-velocity at ~0.0.4.57 and se7enxweb/sevenx_authentication_2fa at ~1.0.18. The legacy installer plugin places them in extension/. suggest lists optional ones, such as se7enxweb/sevenx_valkey_cache and se7enxweb/ezfind, with the PHP extensions each database needs.

Constraints and the lock file #

• A tilde constraint floats the last position only: ~0.0.4.54 accepts 0.0.4.55 and later, never 0.0.5.0.
• composer.lock is not committed; every installation resolves from the constraints. CI's PHPUnit job resolves fresh on every run, so a package release can change a result without a change in the repository (CI gates).
• Packages that require se7enxweb/exponential with a version constraint resolve against main through the branch alias, and CI sets COMPOSER_ROOT_VERSION=dev-main for pull requests.

Repinning in the right order #

1. Release the extension (Release engineering).
2. See the new version on Packagist. A repository without the Packagist webhook stays at an old version until it is updated by hand.
3. Commit the root's new constraint.
4. Run the gates on that commit and push it.

A repin to a version Packagist does not list yet breaks the install step of every CI leg at once; the push gate refuses it for that reason.

Development tools #

PHP_CodeSniffer, PHPCompatibility and PHPStan are resolved from a separate composer.dev.json into .devtools/ with make devtools, for platform PHP 8.0.30, never into vendor/. require-dev of the root holds only PHPUnit and a code generator (Static analysis and code style).

Clones instead of archives #

Composer can install the kernel and the extensions as Git clones instead of archives, so you can see what changed, bisect a regression, use a fix before it is released and send changes back. Composer refuses to update a clone with uncommitted or unpushed changes, but a folder cloned by hand where Composer installed an archive is replaced without asking at the next update; let Composer make the clone with composer reinstall <package>. On a live site, update one package at a time (Develop with Git, Update with Git).

PSR status #

The project states it plainly: no PSR-4 autoloading (generated class maps instead), no PSR-3, PSR-6, PSR-7, PSR-11, PSR-14, PSR-15 to PSR-18 interfaces in the kernel, and its own code style instead of PSR-12. Plan adapters if your system expects those interfaces.

Checklist for a new dependency #

• To do: Is it needed, or does the kernel or a shipped extension already do it?
• To do: Its license is compatible with the GNU GPL, version 2 or later.
• To do: It supports PHP 8.0 (the oldest supported version) and, where it can, PHP 7.4 (usable without support), or it is optional and guarded, or it is required only for newer PHP through se7enxweb/exponential-php-floor.
• To do: It is maintained, and released on Packagist.
• To do: The constraint names a released version.
• To do: Its security advisories are watched (composer audit is recommended in the hardening guide).

Related pages #

• Composer and Packagist, for application creators
• composer.json for extensions
• Composer and Git on servers
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.