deployer/docs/api.md

<!-- DO NOT EDIT THIS FILE! -->
<!-- Instead edit src/functions.php -->
<!-- Then run bin/docgen -->

# API Reference

 * [`host()`](#host)
 * [`localhost()`](#localhost)
 * [`getHost()`](#gethost)
 * [`currentHost()`](#currenthost)
 * [`select()`](#select)
 * [`import()`](#import)
 * [`desc()`](#desc)
 * [`task()`](#task)
 * [`before()`](#before)
 * [`after()`](#after)
 * [`fail()`](#fail)
 * [`option()`](#option)
 * [`cd()`](#cd)
 * [`within()`](#within)
 * [`run()`](#run)
 * [`runLocally()`](#runlocally)
 * [`test()`](#test)
 * [`testLocally()`](#testlocally)
 * [`on()`](#on)
 * [`invoke()`](#invoke)
 * [`upload()`](#upload)
 * [`download()`](#download)
 * [`info()`](#info)
 * [`warning()`](#warning)
 * [`writeln()`](#writeln)
 * [`parse()`](#parse)
 * [`set()`](#set)
 * [`add()`](#add)
 * [`get()`](#get)
 * [`has()`](#has)
 * [`ask()`](#ask)
 * [`askChoice()`](#askchoice)
 * [`askConfirmation()`](#askconfirmation)
 * [`askHiddenResponse()`](#askhiddenresponse)
 * [`input()`](#input)
 * [`output()`](#output)
 * [`commandExist()`](#commandexist)
 * [`commandSupportsOption()`](#commandsupportsoption)
 * [`locateBinaryPath()`](#locatebinarypath)
 * [`remoteEnv()`](#remoteenv)

## host()

```php
host(string ...$hostname)
```



## localhost()

```php
localhost(string ...$hostnames)
```



## getHost()

```php
getHost(string $alias): Host
```

Get host by host alias.



## currentHost()

```php
currentHost(): Host
```

Returns current host.



## select()

```php
select(string $selector): array
```

Returns hosts based on provided selector.

```php
on(select('stage=prod, role=db'), function ($host) {
    ...
});
```



## import()

```php
import(string $file): void
```

Import other php or yaml recipes.

```php
import('recipe/common.php');
```

```php
import(__DIR__ . '/config/hosts.yaml');
```



## desc()

```php
desc(?string $title = null): ?string
```

Set task description.


## task()

```php
task(string $name, $body = null): Task
```

Define a new task and save to tasks list.

Alternatively get a defined task.


### Arguments:
- ### name
  **type**: `string `

  Name of current task.
- ### body
  **type**: `callable|array|null `

  Callable task, array of other tasks names or nothing to get a defined tasks

## before()

```php
before(string $task, $do)
```

Call that task before specified task runs.



### Arguments:
- ### task
  **type**: `string `

  The task before $that should be run.
- ### do
  **type**: `string|callable `

  The task to be run.

## after()

```php
after(string $task, $do)
```

Call that task after specified task runs.



### Arguments:
- ### task
  **type**: `string `

  The task after $that should be run.
- ### do
  **type**: `string|callable `

  The task to be run.

## fail()

```php
fail(string $task, $do)
```

Setup which task run on failure of $task.
When called multiple times for a task, previous fail() definitions will be overridden.



### Arguments:
- ### task
  **type**: `string `

  The task which need to fail so $that should be run.
- ### do
  **type**: `string|callable `

  The task to be run.

## option()

```php
option(string $name, $shortcut = null, ?int $mode = null, string $description = '', $default = null): void
```

Add users options.


### Arguments:
- ### name
  **type**: `string `

  The option name
- ### shortcut
  **type**: `string|array|null `

  The shortcuts, can be null, a string of shortcuts delimited by | or an array of shortcuts
- ### mode
  **type**: `int|null `

  The option mode: One of the VALUE_* constants
- ### description
  **type**: `string `

  A description text
- ### default
  **type**: `string|string[]|int|bool|null `

  The default value (must be null for self::VALUE_NONE)

## cd()

```php
cd(string $path): void
```

Change the current working directory.


## within()

```php
within(string $path, callable $callback)
```

Execute a callback within a specific directory and revert back to the initial working directory.



## run()

```php
run(string $command, ?array $options = [], ?int $timeout = null, ?int $idle_timeout = null, ?string $secret = null, ?array $env = null, ?bool $real_time_output = false): string
```

Executes given command on remote host.

Examples:

```php
run('echo hello world');
run('cd {{deploy_path}} && git status');
run('password %secret%', secret: getenv('CI_SECRET'));
run('curl medv.io', timeout: 5);
```

```php
$path = run('readlink {{deploy_path}}/current');
run("echo $path");
```



### Arguments:
- ### command
  **type**: `string `

  Command to run on remote host.
- ### options
  **type**: `array|null `

  Array of options will override passed named arguments.
- ### timeout
  **type**: `int|null `

  Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec; see {{default_timeout}}, `null` to disable).
- ### idle_timeout
  **type**: `int|null `

  Sets the process idle timeout (max. time since last output) in seconds.
- ### secret
  **type**: `string|null `

  Placeholder `%secret%` can be used in command. Placeholder will be replaced with this value and will not appear in any logs.
- ### env
  **type**: `array|null `

  Array of environment variables: `run('echo $KEY', env: ['key' => 'value']);`
- ### real_time_output
  **type**: `bool|null `

  Print command output in real-time.

## runLocally()

```php
runLocally(string $command, ?array $options = [], ?int $timeout = null, ?int $idle_timeout = null, ?string $secret = null, ?array $env = null): string
```

Execute commands on a local machine.

Examples:

```php
$user = runLocally('git config user.name');
runLocally("echo $user");
```



### Arguments:
- ### command
  **type**: `string `

  Command to run on localhost.
- ### options
  **type**: `array|null `

  Array of options will override passed named arguments.
- ### timeout
  **type**: `int|null `

  Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec, `null` to disable).
- ### idle_timeout
  **type**: `int|null `

  Sets the process idle timeout (max. time since last output) in seconds.
- ### secret
  **type**: `string|null `

  Placeholder `%secret%` can be used in command. Placeholder will be replaced with this value and will not appear in any logs.
- ### env
  **type**: `array|null `

  Array of environment variables: `runLocally('echo $KEY', env: ['key' => 'value']);`

## test()

```php
test(string $command): bool
```

Run test command.
Example:

```php
if (test('[ -d {{release_path}} ]')) {
...
}
```



## testLocally()

```php
testLocally(string $command): bool
```

Run test command locally.
Example:

    testLocally('[ -d {{local_release_path}} ]')



## on()

```php
on($hosts, callable $callback): void
```

Iterate other hosts, allowing to call run a func in callback.

```php
on(select('stage=prod, role=db'), function ($host) {
    ...
});
```

```php
on(getHost('prod'), function ($host) {
    ...
});
```

```php
on(Deployer::get()->hosts, function ($host) {
    ...
});
```



## invoke()

```php
invoke(string $taskName): void
```

Runs a task.
```php
invoke('deploy:symlink');
```



## upload()

```php
upload($source, string $destination, array $config = []): void
```

Upload file or directory to host.

> You may have noticed that there is a trailing slash (/) at the end of the first argument in the above command, this is necessary to mean “the contents of build“.
>
> The alternative, without the trailing slash, would place build, including the directory, within public. This would create a hierarchy that looks like: {{release_path}}/public/build

 The `$config` array supports the following keys:

- `flags` for overriding the default `-azP` passed to the `rsync` command
- `options` with additional flags passed directly to the `rsync` command
- `timeout` for `Process::fromShellCommandline()` (`null` by default)
- `progress_bar` to display upload/download progress
- `display_stats' to display rsync set of statistics




## download()

```php
download(string $source, string $destination, array $config = []): void
```

Download file or directory from host




## info()

```php
info(string $message): void
```

Writes an info message.


## warning()

```php
warning(string $message): void
```

Writes an warning message.


## writeln()

```php
writeln($message, int $options = 0): void
```

Writes a message to the output and adds a newline at the end.


## parse()

```php
parse(string $value): string
```

Parse set values.


## set()

```php
set(string $name, $value): void
```

Setup configuration option.



## add()

```php
add(string $name, array $array): void
```

Merge new config params to existing config array.



## get()

```php
get(string $name, $default = null)
```

Get configuration value.




## has()

```php
has(string $name): bool
```

Check if there is such configuration option.


## ask()

```php
ask(string $message, ?string $default = null, ?array $autocomplete = null): ?string
```



## askChoice()

```php
askChoice(string $message, array $availableChoices, ?string $default = null, bool $multiselect = false)
```




## askConfirmation()

```php
askConfirmation(string $message, bool $default = false): bool
```



## askHiddenResponse()

```php
askHiddenResponse(string $message): string
```



## input()

```php
input(): InputInterface
```



## output()

```php
output(): OutputInterface
```



## commandExist()

```php
commandExist(string $command): bool
```

Check if command exists



## commandSupportsOption()

```php
commandSupportsOption(string $command, string $option): bool
```



## locateBinaryPath()

```php
locateBinaryPath(string $name): string
```



## remoteEnv()

```php
remoteEnv(): array
```

Returns remote environments variables as an array.
```php
$remotePath = remoteEnv()['PATH'];
run('echo $PATH', env: ['PATH' => "/home/user/bin:$remotePath"]);
```