deployer/docs/api.md

API Reference

• host()
• localhost()
• getHost()
• currentHost()
• select()
• import()
• desc()
• task()
• before()
• after()
• fail()
• option()
• cd()
• within()
• run()
• runLocally()
• test()
• testLocally()
• on()
• invoke()
• upload()
• download()
• info()
• warning()
• writeln()
• parse()
• set()
• add()
• get()
• has()
• ask()
• askChoice()
• askConfirmation()
• askHiddenResponse()
• input()
• output()
• commandExist()
• commandSupportsOption()
• locateBinaryPath()

host()

host(string ...$hostname)

localhost()

localhost(string ...$hostnames)

getHost()

getHost(string $alias): Host

Get host by host alias.

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) {
    ...
});

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.

before()

before(string $task, $do)

Call that task before specified task runs.

after()

after(string $task, $do)

Call that task after specified task runs.

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.

option()

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

Add users options.

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 = []): string

Executes given command on remote host.

Options:

• timeout - Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec; see {{default_timeout}}, null to disable).
• idle_timeout - Sets the process idle timeout (max. time since last output) in seconds.
• secret - Placeholder %secret% can be used in command. Placeholder will be replaced with this value and will not appear in any logs.
• vars - Array of placeholders to replace in command: run('echo %key%', ['vars' => ['key' => 'anything does here']]);
• env - Array of environment variables: run('echo $KEY', ['env' => ['key' => 'value']]);

Examples:

run('echo hello world');
run('cd {{deploy_path}} && git status');
run('password %secret%', ['secret' => getenv('CI_SECRET')]);

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

runLocally()

runLocally(string $command, array $options = []): string

Execute commands on local machine

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(getHost('prod'), function ($host) {
    ...
});

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

invoke()

invoke(string $taskName): void

Runs a task.

invoke('deploy:symlink');

upload()

upload(string $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

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, ?string $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

locateBinaryPath()

locateBinaryPath(string $name): string