README

alianet/env-sync integration for Composer 2. Requires PHP 8.2 or later.

The plugin runs env-sync update after composer install and composer update, including the initial installation. It adds missing variables while preserving existing values and additional keys. It also provides the composer env-sync command.

Local installation

The package has not been published yet. Add a local repository to your application's composer.json, adjusting the path as needed:

{
    "repositories": [
        {
            "type": "path",
            "url": "../env-sync-composer-plugin",
            "options": {
                "symlink": true,
                "versions": {
                    "alianet/env-sync-composer-plugin": "dev-main"
                }
            }
        }
    ],
    "config": {
        "allow-plugins": {
            "alianet/env-sync-composer-plugin": true
        }
    }
}

Before installing, create .env.example or .env.dist in your application directory. Then run:

composer require alianet/env-sync-composer-plugin:dev-main

The alianet/env-sync:^1.2 dependency is installed automatically. Keeping the plugin in require makes it available after install --no-dev as well. Use require --dev if the integration is only needed during development. There is no need to add scripts to post-install-cmd or post-update-cmd. Remove any existing scripts that run env-sync to avoid synchronizing twice.

Commands

composer env-sync
composer env-sync update .env.example .env
composer env-sync update --dry-run -v
composer env-sync diff
composer env-sync diff --format=json
composer env-sync validate-config
composer env-sync update --config=config/env-sync.json

The default operation is update. Command exit codes: 0 means success, 1 means diff detected differences, and 2 means an env-sync input, configuration, or write error. Invalid configuration of the plugin itself is a Composer error.

Configuration

The plugin uses the application's .env-sync.json. See the env-sync documentation for the file format and comparison rules. The default paths are .env.example (falling back to .env.dist) and .env. Paths in .env-sync.json are resolved relative to that file; paths supplied on the command line are relative to the application's working directory. composer -d path is also supported.

Optional settings in the application's root composer.json:

{
    "extra": {
        "env-sync": {
            "enabled": true,
            "config": "config/env-sync.json"
        }
    }
}

enabled defaults to true. Setting it to false disables the automatic hooks while keeping composer env-sync available. Omitting config enables the standard .env-sync.json discovery behavior. The command's --config option takes precedence. Options other than enabled and config are rejected to catch typos.

--no-plugins disables the entire plugin, including its command. The --no-scripts flag applies to application scripts and does not guarantee that plugin hooks are skipped in every Composer version; use enabled: false or --no-plugins to disable synchronization. A synchronization error, including a missing template, causes installation or update to exit with an error; dependencies installed before the error are not rolled back. Running dump-autoload alone does not synchronize files.

Install the plugin in the application whose files you want to synchronize. A global installation would also run the hooks in other projects. Target files containing secrets, such as .env, should be included in the application's .gitignore.

Development

composer install
composer qa

composer qa validates the package, runs integration tests, analyzes src and tests with PHPStan at the maximum level (including Composer's plugin extensions), and checks formatting with PHP CS Fixer. Static analysis targets PHP 8.2. The formatter uses the same Symfony rules as alianet/env-sync.

Individual checks and automatic formatting are also available:

composer test
composer phpstan
composer cs-check
composer cs-fix

cs-check only reports formatting differences; cs-fix modifies files. Both tools are development dependencies and are not installed in consuming applications.

The tests install the plugin in a temporary application using local path repositories, without downloading additional packages. They verify actual Composer hooks, production installation, a custom vendor-dir, configuration, exit codes, and file preservation. Composer does not activate a plugin that is the root package, so composer env-sync is tested in an application that consumes the plugin.

Docker

Docker provides an optional local test environment based on the setup in alianet/env-sync. Local PHP and Composer installations are not required. The environment uses the official PHP CLI image and Composer 2, with no web server, database, or other application services.

From the project directory, build the default PHP 8.5 environment and run the checks:

docker compose build php
docker compose run --rm php composer install --no-interaction
docker compose run --rm php composer qa

These commands also work in PowerShell. On Linux, match the container user's UID and GID to your own when building so that files created through the bind mount belong to you:

LOCAL_UID="$(id -u)" LOCAL_GID="$(id -g)" docker compose build php

Both IDs default to 1000. Rebuild after changing either ID. Existing dependency and cache volumes retain their ownership; if the IDs change, recreate only this project's affected volumes after stopping its containers.

The source tree is mounted at /app, so edits are available immediately. Dependencies are stored in env-sync-composer-plugin-vendor-<version> volumes, separate from the host's vendor directory and from other PHP versions. Host IDEs will not see these container dependencies. Downloaded packages are cached in env-sync-composer-plugin-composer-cache, shared across PHP versions.

To use another PHP version, set PHP_VERSION for both the build and subsequent runs. For example, in Bash:

PHP_VERSION=8.2 docker compose build php
PHP_VERSION=8.2 docker compose run --rm php composer update --no-interaction
PHP_VERSION=8.2 docker compose run --rm php composer qa

In PowerShell:

$env:PHP_VERSION = '8.2'
docker compose build php
docker compose run --rm php composer update --no-interaction
docker compose run --rm php composer qa
Remove-Item Env:PHP_VERSION

Rebuild whenever the PHP version or Dockerfile changes. The source mount includes the host's composer.lock: a lock generated on newer PHP may be incompatible with older PHP. Use composer update to resolve compatible dependencies when switching versions; this also updates the local lock file. To test without changing that file or the development volumes, use the isolated matrix scripts instead.

The matrix scripts build temporary QA images, resolve fresh dependencies for each PHP version, and run the complete composer qa suite:

bash tools/test-php-version 8.2
bash tools/test-php-versions

Supported versions are listed in tools/php-versions: PHP 8.2, 8.3, 8.4, and 8.5. On Windows, run the Bash scripts from WSL with Docker Desktop integration enabled, or Git Bash. Each script removes only its own temporary image and does not prune Docker's shared build cache or other projects' resources.

Use docker compose down to stop and remove this project's development containers and networks. Its dependency and Composer cache volumes are retained for future runs.

Contributing

See CONTRIBUTING.md for development guidelines and local checks. All participants are expected to follow the Code of Conduct.

License

This project is licensed under the MIT License.

alianet / env-sync-composer-plugin

Package info

Security

Statistics