forked from a64f7bb4-7358-4778-9fbe-3b882c34cc1d/v1
140 lines
5.4 KiB
Markdown
140 lines
5.4 KiB
Markdown
# 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.
|
|
|
|
[](https://travis-ci.org/consolidation/site-process)
|
|
[](https://scrutinizer-ci.com/g/consolidation/site-process/?branch=master)
|
|
[](https://codecov.io/gh/consolidation/site-process)
|
|
[](LICENSE)
|
|
|
|
|
|
## Overview
|
|
|
|
Site Process is a thin wrapper around the [Symfony Process Component](https://symfony.com/doc/3.4/components/process) that allows applications to use the [Site Alias library](https://github.com/consolidation/site-alias) 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:
|
|
```yaml
|
|
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:
|
|
```yaml
|
|
local:
|
|
uri: http://localhost
|
|
vagrant:
|
|
```
|
|
|
|
#### Docker Compose
|
|
Wraps a command so that it runs on a remote system via docker-compose.
|
|
|
|
Example:
|
|
```yaml
|
|
local:
|
|
host: localhost
|
|
uri: http://localhost
|
|
docker:
|
|
service: drupal
|
|
compose:
|
|
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
|
|
|
|
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](https://docs.docker.com/compose/reference/overview/) 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:
|
|
|
|
| Test | Command
|
|
| ---------------- | ---
|
|
| Run all tests | `composer test`
|
|
| PHPUnit tests | `composer unit`
|
|
| PHP linter | `composer lint`
|
|
| Code style | `composer cs`
|
|
| Fix style errors | `composer cbf`
|
|
|
|
|
|
## Deployment
|
|
|
|
- Run `composer release`
|
|
|
|
## Contributing
|
|
|
|
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the process for submitting pull requests to us.
|
|
|
|
## Versioning
|
|
|
|
We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [releases](https://github.com/consolidation/site-process/releases) page.
|
|
|
|
| Branch | Symfony Versions | PHP Versions
|
|
| ------------ | ---------------- | ------------
|
|
| main (5.x) | ^5 | ^6 | 8.0+
|
|
| 4.x | ^4 | 7.1+
|
|
| 2.x | ^2 | ^3 | 5.6+
|
|
|
|
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
|
|
|
|
* [Greg Anderson](https://github.com/greg-1-anderson)
|
|
* [Moshe Weitzman](http://weitzman.github.com)
|
|
|
|
See also the list of [contributors](https://github.com/consolidation/site-process/contributors) who participated in this project.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
|
|
|
|
## Acknowledgments
|
|
|
|
* Thanks to PurpleBooth for the [example README template](https://gist.github.com/PurpleBooth/109311bb0361f32d87a2)
|