php-tuf / composer-stager

Stages Composer commands so they can be safely run on a codebase in production.
MIT License
16 stars 8 forks source link
composer

Composer Stager

Latest stable version Tests status Coverage PHPStan

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?

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:

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.