API Reference

host()

host(string ...$hostname): Host|ObjectProxy

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): Localhost|ObjectProxy

Define a local host. Deployer will not connect to this host, but will execute commands locally instead.

localhost('ci'); // Alias and hostname will be "ci".

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, callable|array|null $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 or array or null	Callable task, array of other tasks names or nothing to get a defined tasks

before()

before(string $task, string|callable $do): ?Task

Call that task before specified task runs.

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

after()

after(string $task, string|callable $do): ?Task

Call that task after specified task runs.

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

fail()

fail(string $task, string|callable $do): ?Task

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

cd('~/myapp');
run('ls'); // Will run `ls` in ~/myapp.

become()

become(string $user): \Closure

Change the current user.

Usage:

$restore = become('deployer');

// do something

$restore(); // revert back to the previous user

within()

within(string $path, callable $callback): mixed

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

run()

run(
    string  $command,
    ?string $cwd = null,
    ?array  $env = null,
    ?string $secret = null,
    ?bool   $nothrow = false,
    ?bool   $forceOutput = false,
    ?int    $timeout = null,
    ?int    $idleTimeout = null,
): 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.
$cwd	string or null	Sets the process working directory. If not set {{working_path}} will be used.
$timeout	int or null	Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec; see {{default_timeout}}, null to disable).
$idleTimeout	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']);
$forceOutput	bool or null	Print command output in real-time.
$nothrow	bool or null	Don't throw an exception of non-zero exit code.

runLocally()

runLocally(
    string  $command,
    ?string $cwd = null,
    ?int    $timeout = null,
    ?int    $idleTimeout = null,
    ?string $secret = null,
    ?array  $env = null,
    ?bool   $forceOutput = false,
    ?bool   $nothrow = false,
    ?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.
$cwd	string or null	Sets the process working directory. If not set {{working_path}} will be used.
$timeout	int or null	Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec, null to disable).
$idleTimeout	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']);
$forceOutput	bool or null	Print command output in real-time.
$nothrow	bool or null	Don't throw an exception of non-zero exit code.
$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 files or directories to host.

To upload the contents of a directory, include a trailing slash (eg upload('build/', '{{release_path}}/public');). Without the trailing slash, the build directory itself will be uploaded (resulting in {{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

Note: due to the way php escapes command line arguments, list-notation for the rsync --exclude={'file','anotherfile'} option will not work. A workaround is to add a separate --exclude=file argument for each exclude to options (also, do not wrap the filename/filter in quotes). An alternative might be to write the excludes to a temporary file (one per line) and use --exclude-from=temporary_file argument instead.

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