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.

Arguments:

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

before(string $task, $do)

Call that task before specified task runs.

Arguments:

  • task string β€” The task before $that should be run.
  • do string|callable β€” The task to be run.

after()

after(string $task, $do)

Call that task after specified task runs.

Arguments:

  • task string β€” The task after $that should be run.
  • do string|callable β€” 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.

Arguments:

  • task string β€” The task which need to fail so $that should be run.
  • do string|callable β€” The task to be run.

option()

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

Add users options.

Arguments:

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

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

Arguments:

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

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

Arguments:

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

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

Consider supporting Deployer via GitHub Sponsors.