Skip to main content
Version: 7.x

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.

ArgumentTypeComment
$namestringName of current task.
$bodycallable():void or array or nullCallable 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.

ArgumentTypeComment
$taskstringThe task before $that should be run.
$dostring or callable():voidThe task to be run.

after()​

after(string $task, $do)

Call that task after specified task runs.

ArgumentTypeComment
$taskstringThe task after $that should be run.
$dostring or callable():voidThe 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.

ArgumentTypeComment
$taskstringThe task which need to fail so $that should be run.
$dostring or callable():voidThe task to be run.

option()​

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

Add users options.

ArgumentTypeComment
$namestringThe option name
$shortcutstring or array or nullThe shortcuts, can be null, a string of shortcuts delimited by
$modeint or nullThe option mode: One of the VALUE_* constants
$descriptionstringA description text
$defaultstring or string[] or int or bool or nullThe 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");
ArgumentTypeComment
$commandstringCommand to run on remote host.
$optionsarray or nullArray of options will override passed named arguments.
$timeoutint or nullSets the process timeout (max. runtime). The timeout in seconds (default: 300 sec; see {{default_timeout}}, null to disable).
$idle_timeoutint or nullSets the process idle timeout (max. time since last output) in seconds.
$secretstring or nullPlaceholder %secret% can be used in command. Placeholder will be replaced with this value and will not appear in any logs.
$envarray or nullArray of environment variables: run('echo $KEY', env: ['key' => 'value']);
$real_time_outputbool or nullPrint command output in real-time.
$no_throwbool or nullDon'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");
ArgumentTypeComment
$commandstringCommand to run on localhost.
$optionsarray or nullArray of options will override passed named arguments.
$timeoutint or nullSets the process timeout (max. runtime). The timeout in seconds (default: 300 sec, null to disable).
$idle_timeoutint or nullSets the process idle timeout (max. time since last output) in seconds.
$secretstring or nullPlaceholder %secret% can be used in command. Placeholder will be replaced with this value and will not appear in any logs.
$envarray or nullArray of environment variables: runLocally('echo $KEY', env: ['key' => 'value']);
$shellstring or nullShell 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);


Support Deployer ❀️

Hello, my name is Anton Medvedev (@antonmedv). I'm the creator of the Deployer.
I maintain this open source project in my spare time.
Supporters on GitHub give me extra motivation to work on the project.