consolidation/site-process

A thin wrapper around the Symfony Process Component that allows applications to use the Site Alias library to specify the target for a remote call.

5.4.0 2024-04-06 00:00 UTC

README

A thin wrapper around the Symfony Process Component that allows applications to use the Site Alias library to specify the target for a remote call.

ci scrutinizer codecov License

Overview

Site Process is a thin wrapper around the Symfony Process Component that allows applications to use the Site Alias library to specify the target for a remote call.

For comparison purposes, the Process object may be created to run an application on the local system using the standard Symfony Process Component API like so:

$process = new Process(['ls', '-lsa']);

Similarly, a remote call can be done using the general-purpose SiteProcess API, which is accessible via the ProcessManager object:

$processManager = ProcessManager::createDefault();
$process = $processManager->siteProcess($site_alias, ['ls', '-lsa', '{root}']);

In this example, if $site_alias represents a site on the same system, then the ls -lsa command will run locally. If, on the other hand, it represents a remote site, then the ls -lsa command will be wrapped in an ssh call to the remote system. In either case, the {root} reference will be replaced with the value of the attribute of the site alias named root. An exception will be thrown if the named attribute does not exist.

Options may also be specified as an associative array provided as a third parameter:

$process = $processManager->siteProcess($site_alias, ['git', 'status'], ['untracked-files' => 'no']);

This is equivalent to:

$process = $processManager->siteProcess($site_alias, ['git', '--untracked-files=no', 'status']);

Transports

SSH

Wraps a command so that it runs on a remote system via the ssh cli.

Example:

local:
  host: localhost
  uri: http://localhost
  ssh:
    options: -o PasswordAuthentication=no -i $HOME/.ssh/id_rsa

Vagrant

Wraps commands so they run with vagrant ssh -c.

Example:

local:
  uri: http://localhost
  vagrant:

Docker Compose

Wraps a command so that it runs on a remote system via docker-compose.

Example:

local:
  host: localhost
  uri: http://localhost
  docker:
    service: drupal
    compose:
      version: 1
      options: --project dockerComposeProjectName --file docker-compose.yml --project-directory dockerComposeWorkDir
    exec:
      options: --user www-data

The above would execute commands prefixed with:

docker-compose --project dockerComposeProjectName --file docker-compose.yml --project-directory dockerComposeWorkDir exec --user www-data -T drupal

docker.project and compose.options --project do the same thing, docker.project existed before options.

docker.service is the exact name of the service as it appears in docker-compose.yml

docker.compose.version defaults to 1. Set to 2 to use the new syntax:

docker compose --project dockerComposeProjectName --file docker-compose.yml --project-directory dockerComposeWorkDir exec --user www-data -T drupal

The default behaviour is to use docker-compose exec to invoke a command on a running container. You can change this to use docker-compose run for containers which by default are not running, with the property compose.command.

Check the docker-compose manual for all available options.

Local

Runs the command on the local system.

Running the tests

The test suite may be run locally by way of some simple composer scripts:

Deployment

  • Run composer release

Contributing

Please read CONTRIBUTING.md for details on the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the releases page.

Note that all 3.x releases of consolidation/site-process were skipped simply to align the 4.x versions with Symfony 4.x support.

Note that the API of consolidation/site-process itself is compatible between the 2.x and 4.x versions, so most clients that work with both Symfony 3 and Symfony 4 should be able to require "consolidation/site-process": "^2 | ^4" without problems.

Authors

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE file for details

Acknowledgments