README

Library providing a high-level, non-interactive wrapper around Composer CLI. It is designed to be used from other PHP applications and tools that need to run Composer commands safely and programmatically.

Features

Public API (ComposerClientInterface) for executing Composer operations:
- install
- update
- require (as requirePackages)
- remove (as removePackages)
- dump-autoload
- validate
- outdated
- diagnose
- show
- licenses
- depends
- prohibits
- run-script (as runScript)
- clear-cache (as clearCache)
Non-interactive execution enforced by guards:
- NonInteractiveGuard (adds flags and env vars like --no-interaction, CI=1)
- PromptDetector (detects interactive prompts in output and throws exception)
Pluggable command execution via CommandExecutorInterface
DTO-based configuration of all operations (options, execution policy, working directory, env vars)

Installation

Install via Composer:

composer require adachsoft/composer-lib

Basic Usage

Creating a client

The recommended way to get a ready-to-use client is the factory:

use AdachSoft\ComposerLib\PublicApi\Factory\ComposerClientFactory;

$client = ComposerClientFactory::create();

This will create:

a default command executor based on adachsoft/command-executor-lib
a default Composer configuration that runs the composer binary from your PATH (no custom locator required)
non-interactive guard and prompt detector

If you need a custom executor (for logging, sandboxing, etc.), you can pass it:

use AdachSoft\ComposerLib\Infrastructure\Execution\CommandExecutorInterface;
use AdachSoft\ComposerLib\PublicApi\Factory\ComposerClientFactory;

/** @var CommandExecutorInterface $executor */
$client = ComposerClientFactory::create($executor);

Running operations

Each operation is configured by its own options DTO. Example for install:

use AdachSoft\ComposerLib\PublicApi\ComposerClientInterface;
use AdachSoft\ComposerLib\PublicApi\Dto\Enum\ConfigPatchModeEnum;
use AdachSoft\ComposerLib\PublicApi\Dto\Options\ConfigPatchPolicyDto;
use AdachSoft\ComposerLib\PublicApi\Dto\Options\ExecutionPolicyDto;
use AdachSoft\ComposerLib\PublicApi\Dto\Options\InstallOptionsDto;
use AdachSoft\ComposerLib\PublicApi\Dto\Value\WorkingDirectory;

/** @var ComposerClientInterface $client */
$workingDirectory = new WorkingDirectory('/path/to/project');

$executionPolicy = new ExecutionPolicyDto(
    hardTimeoutSeconds: 60,
    activityTimeoutSeconds: 30,
    nonInteractiveEnforced: true,
);

$configPatchPolicy = new ConfigPatchPolicyDto(ConfigPatchModeEnum::PERMANENT);

$options = new InstallOptionsDto(
    workingDirectory: $workingDirectory,
    configPatchPolicy: $configPatchPolicy,
    executionPolicy: $executionPolicy,
    dev: true,
    preferDist: true,
    preferStable: true,
);

$result = $client->install($options);

if (!$result->success) {
    // handle failure, inspect $result->stderr, $result->exitCode, etc.
}

Example for running a custom script via composer run-script:

use AdachSoft\ComposerLib\PublicApi\Dto\Options\ExecutionPolicyDto;
use AdachSoft\ComposerLib\PublicApi\Dto\Options\RunScriptOptionsDto;
use AdachSoft\ComposerLib\PublicApi\Dto\Value\WorkingDirectory;

$workingDirectory = new WorkingDirectory('/path/to/project');

$executionPolicy = new ExecutionPolicyDto(
    hardTimeoutSeconds: 60,
    activityTimeoutSeconds: 30,
    nonInteractiveEnforced: true,
);

$options = new RunScriptOptionsDto(
    workingDirectory: $workingDirectory,
    executionPolicy: $executionPolicy,
    script: 'my-script',
    args: ['--flag', 'value'],
);

$result = $client->runScript($options);

Other operations (update, requirePackages, removePackages, dumpAutoload, validate, outdated, diagnose, show, licenses, depends, prohibits, runScript, clearCache) follow the same pattern with their respective options DTOs.

Non-Interactive Safety

This library is built to prevent accidental interactive Composer runs in CI or automated tools:

NonInteractiveGuard ensures flags like --no-interaction and appropriate environment variables are always present.
PromptDetector scans stdout/stderr and throws NonInteractiveViolationException when it detects likely interactive prompts (e.g. "Do you want to continue?", "[y/N]", etc.).

Command Execution Abstraction

The infrastructure layer defines its own CommandExecutorInterface and ships an adapter for adachsoft/command-executor-lib:

AdachSoft\ComposerLib\Infrastructure\Execution\CommandExecutorInterface
AdachSoft\ComposerLib\Infrastructure\Execution\AdachsoftCommandExecutorAdapter

Composer processes inherit the base PHP environment (such as HOME and COMPOSER_HOME) and their environment is extended or overridden by values coming from the EnvVarMap DTO passed to operations.

You can provide your own implementation of CommandExecutorInterface if you need to control how processes are spawned, logged or sandboxed.

Testing

The project ships with:

unit tests for guards, operations, DTO collections, infrastructure
a functional test that exercises the full public API against a temporary fixture project

To run tests:

vendor/bin/phpunit

To run static analysis:

composer stan

To check or fix code style:

composer cs:check
composer cs:fix

License

This library is released under the MIT License.

adachsoft / composer-lib

Maintainers

Details