README

Composer Stager makes long-running Composer commands safe to run on a codebase in production by "staging" them--performing them on a non-live copy of the codebase and syncing back the result for the least possible downtime.

• Whom is it for?
• Why is it needed?
• Installation
• Usage
• Configuring services
• Example
• Contributing

Whom is it for?

Composer Stager enables PHP products and frameworks (like Drupal) to provide automated Composer-based self-updates for users without access to more robust solutions like staged and blue-green deployments--on restrictive or low-cost hosting, for example, or with little or no budget or development staff. It could conceivably be used with custom Composer-based apps, as well. It is not intended for end users.

Why is it needed?

It may not be obvious at first that a tool like this is really necessary. Why not just use Composer in-place? Or why not just rsync files out and back? It turns out that the problem is incredibly complex, and the edge cases are myriad:

• You can't use Composer directly on a live codebase, because long-running commands put it in an unknown in-between state, and failures can irrecoverably corrupt it. The only safe option is to copy it elsewhere, run the commands there, and sync the result back to the live version. But...

• You may not have write access to directories outside the codebase--especially on low end shared hosting--so you must provide a (more complicated) alternative strategy using a subdirectory of the live codebase.

• You can't assume the availability of such tools as rsync, so you must provide detection and fallback capabilities.

• There are lots of cross-platform issues, including Unix vs. Windows paths, process execution peculiarities, disabled PHP functions, and symlink support, to name a few.

• Symlinks represent a problem space unto themselves, with as many logical issues as technical ones.

• Error messages must be translatable (i18n/l10n).

• You have to account for non-code files, like user uploads, cache files, and logs that may be changed in the live codebase while Composer commands are being run on the copy and could be clobbered when syncing it back.

• Failure to handle any of these challenges can easily have catastrophic results, including data loss or complete destruction of a live codebase. You need to anticipate and prevent them and provide actionable user feedback.

The list could go on. It should be obvious by now that a dedicated library is warranted.

Installation

The library is installed via Composer:

composer require php-tuf/composer-stager

Usage

It is invoked via its PHP API. Given a configured service container (see below), its services can be used like the following, for example:

class Updater
{
    public function __construct(
        private readonly BeginnerInterface $beginner,
        private readonly StagerInterface $stager,
        private readonly CommitterInterface $committer,
        private readonly CleanerInterface $cleaner,
        private readonly PathFactoryInterface $pathFactory,
        private readonly PathListFactoryInterface $pathListFactory,
    ) {
    }

    public function update(): void
    {
        $activeDir = $this->pathFactory->create('/var/www/public');
        $stagingDir = $this->pathFactory->create('/var/www/staging');
        $exclusions = $this->pathListFactory->create(
            'cache',
            'uploads',
        );

        // Copy the codebase to the staging directory.
        $this->beginner->begin($activeDir, $stagingDir, $exclusions);

        // Run a Composer command on it.
        $this->stager->stage([
            'require',
            'example/package',
            '--update-with-all-dependencies',
        ], $activeDir, $stagingDir);

        // Sync the changes back to the active directory.
        $this->committer->commit($stagingDir, $activeDir, $exclusions);

        // Remove the staging directory.
        $this->cleaner->clean($stagingDir);
    }
}

Configuring services

Composer Stager uses the dependency injection pattern, and its services are best accessed via a container that supports autowiring, e.g., Symfony's. (Manual wiring is brittle and therefore not officially supported.) See services.yml for a working example.

Example

A complete, functioning example implementation of Composer Stager can be found in the Composer Stager Console repository.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Observe the coding standards, and if you're able, add and update the tests as appropriate.

More info in the Wiki.