api.md

API Reference

host

• host(string ...$hostname): Host

Define a host or group of hosts. Read more at hosts.

localhost

• localhost(string ...$alias = 'localhost'): Host

Define a localhost.

inventory

• inventory(string $file): Host[]

Load a list of hosts from a file.

desc

• desc(string $description)

Set a task description.

task

• task(string $name, string $script)
• task(string $name, callable $callable)
• task(string $name): Task

Define a task or get a task. More at tasks.

before

• before(string $when, string $that)

Call before $when task, $that task.

after

• after(string $when, string $that)

Call after $when task, $that task.

fail

• fail(string $what, string $that)

If task $what fails, run $that task.

argument

• argument($name, $mode = null, $description = '', $default = null)

Add user's cli arguments.

option

• option($name, $shortcut=null, $mode=null, $description='', $default=null)

Add user's cli options.

cd

• cd(string $path)

Sets the working path for the following run functions. Every task restores the working path to the base working path at the beginning of the task.

cd('{{release_path}}');
run('npm run build');

within

• within(string $path, callable $callback)

Run $callback within $path.

within('{{release_path}}', function () {
    run('npm run build');   
});

workingPath

• workingPath(): string

Return the current working path.

cd('{{release_path}}');
workingPath() == '/var/www/app/releases/1';

run

• run(string $command, $options = []): string

Run a command on remote host. Available options:

• timeout — Sets the process timeout (max. runtime).
  To disable the timeout, set this value to null.
  The timeout in seconds (default: 300 sec)
• tty — Enables or disables the TTY mode (default: false)

For example, if your private key contains a passphrase, enable tty and you'll see git prompt for a password.

run('git clone ...', ['timeout' => null, 'tty' => true]);

run function returns the output of the command as a string:

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

runLocally

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

Run a command on localhost. Available options:

• timeout — The timeout in seconds (default: 300 sec)
• tty — The TTY mode (default: false)

test

• test(string $command): bool

Run a test command.

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

testLocally

• testLocally(string $command): bool

Run a test command locally.

on

• on(Host $host, callable $callback)
• on(Host[] $host, callable $callback)

Execute a $callback on the specified hosts.

on(host('domain.com'), function ($host) {
   ...
});

on(roles('app'), function ($host) {
   ...
});

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

roles

• roles(string ...$role): Host[]

Return a list of hosts by roles.

invoke

• invoke(string $task)

Run a task on the current host.

task('deploy', function () {
    invoke('deploy:prepare'); 
    invoke('deploy:release');
    ...
});

Note this is experimental functionality.

upload

• upload(string $source, string $destination, $config = [])

Upload files from $source to $destination on the remote host.

upload('build/', '{{release_path}}/public');

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

Available options:

• timeout — The timeout in seconds (default: null)
• options — rsync options.

download

• download(string $source, string $destination, $config = [])

Download files from the remote host $source to $destination on the local machine.

Available options:

• timeout — The timeout in seconds (default: null)
• options — rsync options.

write

Write a message in the output. You can format the message with the tags <info>...</info>, <comment></comment> or <error></error> (see Symfony Console).

writeln

Same as the write function, but also writes a new line.

set

• set(string $name, string|int|bool|array $value)
• set(string $name, callable $value)

Setup a global configuration parameter. If callable is passed as $value it will be triggered on the first get of this config.

More at configuration.

add

• add(string $name, array $values)

Add values to already existing config.

More at configuration.

get

• get(string $name, $default = null): string|int|bool|array

Get a configuration value.

More at configuration.

has

• has(string $name): bool

Check if a config option exists.

More at configuration.

ask

• ask(string $message, $default = null, $suggestedChoices = null)

Ask the user for input.

askChoice

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

Ask the user to select from multiple key/value options and return an array. Multiselect enables selection of multiple comma separated choices. The default value will be used in quiet mode, otherwise the first available choice will be accepted.

askConfirmation

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

Ask the user a yes or no question.

askHiddenResponse

• askHiddenResponse(string $message)

Ask the user for a password.

input

• input(): Input

Get the current console input.

output

• output(): Output

Get the current console output.

isQuiet

• isQuiet(): bool

Check if th dep command was started with the -q option.

isVerbose

• isVerbose(): bool

Check if the dep command was started with the -v option.

isVeryVerbose

• isVeryVerbose(): bool

Check if th dep command was started with the -vv option.

isDebug

• isDebug(): bool

Check if the dep command was started with the -vvv option.

commandExist

• commandExist(string $command): bool

Check if a command exists.

if (commandExist('composer')) {
    ...
}

parse

• parse(string $line): string

Parse config occurrence {{ }} in $line.