deployer/docs/api.md

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

# API Reference

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



- **name** `string` — Name of current task.
- **body** `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.




- **task** `string` — The task before $that should be run.
- **do** `string|callable` — The task to be run.

## after()

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

Call that task after specified task runs.




- **task** `string` — The task after $that should be run.
- **do** `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.




- **task** `string` — The task which need to fail so $that should be run.
- **do** `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.



- **name** `string` — The option name
- **shortcut** `string|array|null` — The shortcuts, can be null, a string of shortcuts delimited by | or an array of shortcuts
- **mode** `int|null` — The option mode: One of the VALUE_* constants
- **description** `string` — A description text
- **default** `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, ?bool $no_throw = 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");
```




- **command** `string` — Command to run on remote host.
- **options** `array|null` — Array of options will override passed named arguments.
- **timeout** `int|null` — Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec; see {{default_timeout}}, `null` to disable).
- **idle_timeout** `int|null` — Sets the process idle timeout (max. time since last output) in seconds.
- **secret** `string|null` — Placeholder `%secret%` can be used in command. Placeholder will be replaced with this value and will not appear in any logs.
- **env** `array|null` — Array of environment variables: `run('echo $KEY', env: ['key' => 'value']);`
- **real_time_output** `bool|null` — Print command output in real-time.
- **no_throw** `bool|null` — Don't throw an exception of non-zero exit code.

## runLocally()

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

Execute commands on a local machine.

Examples:

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




- **command** `string` — Command to run on localhost.
- **options** `array|null` — Array of options will override passed named arguments.
- **timeout** `int|null` — Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec, `null` to disable).
- **idle_timeout** `int|null` — Sets the process idle timeout (max. time since last output) in seconds.
- **secret** `string|null` — Placeholder `%secret%` can be used in command. Placeholder will be replaced with this value and will not appear in any logs.
- **env** `array|null` — Array of environment variables: `runLocally('echo $KEY', env: ['key' => 'value']);`
- **shell** `string|null` — Shell to run in. Default is `bash -s`.

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



## which()

```php
which(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"]);
```


## error()

```php
error(string $message): Exception
```

Creates a new exception.


## timestamp()

```php
timestamp(): string
```

Returns current timestamp in UTC timezone in ISO8601 format.