deployer/docs/api.md

API Reference

host()

host(string ...$hostname)

Defines a host or hosts.

host('example.org');
host('prod.example.org', 'staging.example.org');

Inside task can be used to get Host instance of an alias.

task('test', function () {
    $port = host('example.org')->get('port');
});

localhost()

localhost(string ...$hostnames)

currentHost()

currentHost(): Host

Returns current host.

select()

select(string $selector): array

Returns hosts based on provided selector.

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

selectedHosts()

selectedHosts(): array

Returns array of hosts selected by user via CLI.

import()

import(string $file): void

Import other php or yaml recipes.

import('recipe/common.php');

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

desc()

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

Set task description.

task()

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

Define a new task and save to tasks list.

Alternatively get a defined task.

Argument	Type	Comment
$name	string	Name of current task.
$body	callable():void or array or null	Callable task, array of other tasks names or nothing to get a defined tasks

before()

before(string $task, $do)

Call that task before specified task runs.

Argument	Type	Comment
$task	string	The task before $that should be run.
$do	string or callable():void	The task to be run.

after()

after(string $task, $do)

Call that task after specified task runs.

Argument	Type	Comment
$task	string	The task after $that should be run.
$do	string or callable():void	The task to be run.

fail()

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.

Argument	Type	Comment
$task	string	The task which need to fail so $that should be run.
$do	string or callable():void	The task to be run.

option()

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

Add users options.

Argument	Type	Comment
$name	string	The option name
$shortcut	string or array or null	The shortcuts, can be null, a string of shortcuts delimited by
$mode	int or null	The option mode: One of the VALUE_* constants
$description	string	A description text
$default	string or string[] or int or bool or null	The default value (must be null for self::VALUE_NONE)

cd()

cd(string $path): void

Change the current working directory.

within()

within(string $path, callable $callback)

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

run()

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:

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

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

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

runLocally()

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:

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

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

test()

test(string $command): bool

Run test command. Example:

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

testLocally()

testLocally(string $command): bool

Run test command locally. Example:

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

on()

on($hosts, callable $callback): void

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

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

on(host('example.org'), function ($host) {
    ...
});

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

invoke()

invoke(string $taskName): void

Runs a task.

invoke('deploy:symlink');

upload()

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()

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

Download file or directory from host

info()

info(string $message): void

Writes an info message.

warning()

warning(string $message): void

Writes an warning message.

writeln()

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

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

parse()

parse(string $value): string

Parse set values.

set()

set(string $name, $value): void

Setup configuration option.

add()

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

Merge new config params to existing config array.

get()

get(string $name, $default = null)

Get configuration value.

has()

has(string $name): bool

Check if there is such configuration option.

ask()

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

askChoice()

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

askConfirmation()

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

askHiddenResponse()

askHiddenResponse(string $message): string

input()

input(): InputInterface

output()

output(): OutputInterface

commandExist()

commandExist(string $command): bool

Check if command exists

commandSupportsOption()

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

which()

which(string $name): string

remoteEnv()

remoteEnv(): array

Returns remote environments variables as an array.

$remotePath = remoteEnv()['PATH'];
run('echo $PATH', env: ['PATH' => "/home/user/bin:$remotePath"]);

error()

error(string $message): Exception

Creates a new exception.

timestamp()

timestamp(): string

Returns current timestamp in UTC timezone in ISO8601 format.

fetch()

fetch(string $url, string $method = 'get', array $headers = [], ?string $body = null, ?array &$info = null, bool $nothrow = false): string

Example usage:

$result = fetch('{{domain}}', info: $info);
var_dump($info['http_code'], $result);