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)

## 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.


## before()

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

Call that task before specified task runs.



## after()

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

Call that task after specified task runs.



## 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.



## option()

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

Add users options.


## 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 = []): string
```

Executes given command on remote host.

Options:
- `timeout` - Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec; see {{default_timeout}}, `null` to disable).
- `idle_timeout` - Sets the process idle timeout (max. time since last output) in seconds.
- `secret` - Placeholder `%secret%` can be used in command. Placeholder will be replaced with this value and will not appear in any logs.
- `vars` - Array of placeholders to replace in command: `run('echo %key%', ['vars' => ['key' => 'anything does here']]);`
- `env` - Array of environment variables: `run('echo $KEY', ['env' => ['key' => 'value']]);`

Examples:

```php
run('echo hello world');
run('cd {{deploy_path}} && git status');
run('password %secret%', ['secret' => getenv('CI_SECRET')]);
```

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



## runLocally()

```php
runLocally(string $command, array $options = []): string
```

Execute commands on local machine




## 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(string $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



## 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
```