DockerComposerPlugin
in package
implements
EventSubscriberInterface, PluginInterface
Redirects Composer scripts into a configured Docker Compose service.
Table of Contents
Interfaces
- EventSubscriberInterface
- PluginInterface
Properties
- $commandBuilder : DockerComposeCommandBuilder
- Builds Docker Compose command arguments.
- $config : DockerComposerConfig|null
- Stores parsed Docker Composer configuration.
- $containerDetector : ContainerDetector
- Detects whether the current process already runs in a container.
- $duplicateServiceMappingWarningsWritten : bool
- Tracks whether duplicate service mapping warnings were written.
- $io : IOInterface|null
- Stores Composer IO for plugin messages.
- $missingConfigWarningWritten : bool
- Tracks whether the missing configuration warning was written.
- $processRunner : ProcessRunner|null
- Stores the process runner used for Docker commands.
- $startedExecServices : array<string, true>
- Tracks services started for Docker Compose exec mode.
- $unknownConfigWarningWritten : bool
- Tracks whether unknown configuration warnings were written.
Methods
- __construct() : mixed
- Creates a Composer plugin with optional collaborators.
- activate() : void
- Applies plugin modifications to Composer.
- deactivate() : void
- Removes any hooks from Composer.
- getSubscribedEvents() : array<string, string|array{0: string, 1?: int}|array<string|int, array{0: string, 1?: int}>>
- Returns an array of event names this subscriber wants to listen to.
- onScript() : void
- Redirects a Composer script event into Docker Compose.
- uninstall() : void
- Prepares the plugin to be uninstalled.
- ensureExecServiceStarted() : void
- Ensures the configured service can receive `docker compose exec`.
- formatCommand() : string
- Formats command arguments for shell output.
- getConfig() : DockerComposerConfig
- Gets cached plugin configuration.
- getExecServiceStartupKey() : string
- Builds a cache key for exec-mode service startup.
- getProcessRunner() : ProcessRunner
- Gets the process runner for Docker commands.
- isDisabledByEnvironment() : bool
- Checks whether environment settings disable Docker redirection.
- isExecServiceRunning() : bool
- Checks whether the configured exec-mode service is running.
- isNestedScript() : bool
- Checks whether a script event was triggered by another Composer event.
- registerScriptListeners() : void
- Registers listeners for configured Composer scripts.
- runInDocker() : void
- Runs a Composer script inside Docker Compose.
- throwScriptExecutionException() : void
- Throws a Composer script exception for a failed Docker command.
- writeDuplicateServiceMappingWarnings() : void
- Writes warnings for duplicate same-service script mappings.
- writeMissingConfigWarning() : void
- Writes the missing service configuration warning.
- writeRedirectNotice() : void
- Writes the script redirection notice.
- writeUnknownConfigWarning() : void
- Writes warnings for ignored configuration keys.
Properties
$commandBuilder
Builds Docker Compose command arguments.
private
DockerComposeCommandBuilder
$commandBuilder
$config
Stores parsed Docker Composer configuration.
private
DockerComposerConfig|null
$config
= null
$containerDetector
Detects whether the current process already runs in a container.
private
ContainerDetector
$containerDetector
$duplicateServiceMappingWarningsWritten
Tracks whether duplicate service mapping warnings were written.
private
bool
$duplicateServiceMappingWarningsWritten
= false
$io
Stores Composer IO for plugin messages.
private
IOInterface|null
$io
= null
$missingConfigWarningWritten
Tracks whether the missing configuration warning was written.
private
bool
$missingConfigWarningWritten
= false
$processRunner
Stores the process runner used for Docker commands.
private
ProcessRunner|null
$processRunner
$startedExecServices
Tracks services started for Docker Compose exec mode.
private
array<string, true>
$startedExecServices
= []
Stores startup keys for services already started during this process.
$unknownConfigWarningWritten
Tracks whether unknown configuration warnings were written.
private
bool
$unknownConfigWarningWritten
= false
Methods
__construct()
Creates a Composer plugin with optional collaborators.
public
__construct([ProcessRunner|null $processRunner = null ][, ContainerDetector|null $containerDetector = null ][, DockerComposeCommandBuilder|null $commandBuilder = null ]) : mixed
Parameters
- $processRunner : ProcessRunner|null = null
-
The runner for Docker Compose commands, or
nullfor the default. - $containerDetector : ContainerDetector|null = null
-
The container detector, or
nullfor environment-based detection. - $commandBuilder : DockerComposeCommandBuilder|null = null
-
The command builder, or
nullfor the default builder.
activate()
Applies plugin modifications to Composer.
public
activate(Composer $composer, IOInterface $io) : void
Parameters
- $composer : Composer
-
The Composer instance being activated.
- $io : IOInterface
-
The Composer IO used for plugin output.
Return values
void —Returns nothing.
deactivate()
Removes any hooks from Composer.
public
deactivate(Composer $composer, IOInterface $io) : void
This will be called when a plugin is deactivated before being uninstalled, but also before it gets upgraded to a new version so the old one can be deactivated and the new one activated.
Parameters
- $composer : Composer
-
The Composer instance being deactivated.
- $io : IOInterface
-
The Composer IO available during deactivation.
Return values
void —Returns nothing.
getSubscribedEvents()
Returns an array of event names this subscriber wants to listen to.
public
static getSubscribedEvents() : array<string, string|array{0: string, 1?: int}|array<string|int, array{0: string, 1?: int}>>
The array keys are event names and the value can be:
- The method name to call (priority defaults to 0)
- An array composed of the method name to call and the priority
- An array of arrays composed of the method names to call and respective priorities, or 0 if unset
For instance:
- array('eventName' => 'methodName')
- array('eventName' => array('methodName', $priority))
- array('eventName' => array(array('methodName1', $priority), array('methodName2'))
Return values
array<string, string|array{0: string, 1?: int}|array<string|int, array{0: string, 1?: int}>> —Returns no static subscriptions because script listeners are registered after activation.
onScript()
Redirects a Composer script event into Docker Compose.
public
onScript(Event $event) : void
Parameters
- $event : Event
-
The Composer script event to inspect and possibly redirect.
Return values
void —Returns nothing.
uninstall()
Prepares the plugin to be uninstalled.
public
uninstall(Composer $composer, IOInterface $io) : void
This will be called after deactivate.
Parameters
- $composer : Composer
-
The Composer instance being uninstalled from.
- $io : IOInterface
-
The Composer IO available during uninstall.
Return values
void —Returns nothing.
ensureExecServiceStarted()
Ensures the configured service can receive `docker compose exec`.
private
ensureExecServiceStarted(ProcessRunner $runner, DockerComposerConfig $config) : void
Parameters
- $runner : ProcessRunner
-
The runner used for Docker Compose commands.
- $config : DockerComposerConfig
-
The Docker Composer configuration that identifies the service.
Return values
void —Returns nothing.
formatCommand()
Formats command arguments for shell output.
private
formatCommand(array<int, string> $command) : string
Parameters
- $command : array<int, string>
-
The raw command arguments to escape.
Return values
string —Returns a shell-escaped command line for diagnostics.
getConfig()
Gets cached plugin configuration.
private
getConfig(Event $event) : DockerComposerConfig
Parameters
- $event : Event
-
The script event used to lazily access Composer.
Return values
DockerComposerConfig —Returns parsed Docker Composer configuration.
getExecServiceStartupKey()
Builds a cache key for exec-mode service startup.
private
getExecServiceStartupKey(DockerComposerConfig $config) : string
Parameters
- $config : DockerComposerConfig
-
The Docker Composer configuration that identifies the service.
Return values
string —Returns a stable serialized key for the service startup command.
getProcessRunner()
Gets the process runner for Docker commands.
private
getProcessRunner(Event $event) : ProcessRunner
Parameters
- $event : Event
-
The script event used to create a default Composer runner.
Return values
ProcessRunner —Returns the configured or lazily created process runner.
isDisabledByEnvironment()
Checks whether environment settings disable Docker redirection.
private
isDisabledByEnvironment() : bool
Return values
bool —Returns true when DOCKER_COMPOSER_DISABLE is truthy.
isExecServiceRunning()
Checks whether the configured exec-mode service is running.
private
isExecServiceRunning(ProcessRunner $runner, DockerComposerConfig $config) : bool
Parameters
- $runner : ProcessRunner
-
The runner used for Docker Compose commands.
- $config : DockerComposerConfig
-
The Docker Composer configuration that identifies the service.
Return values
bool —Returns true when Docker Compose lists the service as running.
isNestedScript()
Checks whether a script event was triggered by another Composer event.
private
isNestedScript(Event $event) : bool
Parameters
- $event : Event
-
The script event to inspect.
Return values
bool —Returns true when event is nested under another Composer event.
registerScriptListeners()
Registers listeners for configured Composer scripts.
private
registerScriptListeners(Composer $composer) : void
Parameters
- $composer : Composer
-
The Composer instance whose package scripts should be watched.
Return values
void —Returns nothing.
runInDocker()
Runs a Composer script inside Docker Compose.
private
runInDocker(Event $event, DockerComposerConfig $config) : void
Parameters
- $event : Event
-
The Composer script event being executed.
- $config : DockerComposerConfig
-
The Docker Composer configuration used to build commands.
Return values
void —Returns nothing.
throwScriptExecutionException()
Throws a Composer script exception for a failed Docker command.
private
throwScriptExecutionException(ProcessRunner $runner, int $exitCode, string $phase, array<int, string> $command) : void
Parameters
- $runner : ProcessRunner
-
The runner that contains the latest process error output.
- $exitCode : int
-
The process exit code returned by Docker Compose.
- $phase : string
-
The Docker Compose phase that failed.
- $command : array<int, string>
-
The Docker Compose command arguments that failed.
Return values
void —Returns nothing.
writeDuplicateServiceMappingWarnings()
Writes warnings for duplicate same-service script mappings.
private
writeDuplicateServiceMappingWarnings(IOInterface $io) : void
Parameters
- $io : IOInterface
Return values
void —Returns nothing.
writeMissingConfigWarning()
Writes the missing service configuration warning.
private
writeMissingConfigWarning(IOInterface $io, string $scriptName) : void
Parameters
- $io : IOInterface
-
The Composer IO that receives the warning.
- $scriptName : string
-
The Composer script name without a configured service.
Return values
void —Returns nothing.
writeRedirectNotice()
Writes the script redirection notice.
private
writeRedirectNotice(Event $event, DockerComposerConfig $config) : void
Parameters
- $event : Event
-
The script event being redirected.
- $config : DockerComposerConfig
-
The configuration that provides the target service.
Return values
void —Returns nothing.
writeUnknownConfigWarning()
Writes warnings for ignored configuration keys.
private
writeUnknownConfigWarning() : void
Return values
void —Returns nothing.