deployer/docs/api.md
Anton Medvedev 5bc321f129 Update docs
2020-10-11 16:24:03 +02:00

5.8 KiB
Executable File

API Reference

host()

host(...$hostname)

localhost()

localhost(...$hostnames)

getHost()

getHost(string $alias)

Get host by host alias.

currentHost()

currentHost()

Returns current host.

select()

select(string $selector)

Returns hosts based on provided selector.

on(select('stage=prod, role=db'), function ($host) {
    ...
});

inventory()

inventory($file)

Load list of hosts from file

desc()

desc($title = null)

Set task description.

task()

task($name, $body = null)

Define a new task and save to tasks list.

Alternatively get a defined task.

before()

before($task, $do)

Call that task before specified task runs.

after()

after($task, $do)

Call that task after specified task runs.

fail()

fail($task, $do)

Setup which task run on failure of first.

option()

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

Add users options.

cd()

cd($path)

Change the current working directory.

within()

within($path, $callback)

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

run()

run($command, $options = [])

Executes given command on remote host.

Options:

  • timeout - Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec).
  • 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($command, $options = [])

Execute commands on local machine

test()

test($command)

Run test command. Example:

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

testLocally()

testLocally($command)

Run test command locally. Example:

testLocally('[ -d {{local_release_path}} ]')

on()

on($hosts, callable $callback)

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)

Runs a task.

invoke('deploy:symlink');

upload()

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

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, $config = [])

Download file or directory from host

info()

info($message)

Writes an info message.

warning()

warning($message)

Writes an warning message.

writeln()

writeln($message, $options = 0)

Writes a message to the output and adds a newline at the end.

parse()

parse($value)

Parse set values.

set()

set($name, $value)

Setup configuration option.

add()

add($name, $array)

Merge new config params to existing config array.

get()

get($name, $default = null)

Get configuration value.

has()

has($name)

Check if there is such configuration option.

ask()

ask($message, $default = null, $autocomplete = null)

askChoice()

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

askConfirmation()

askConfirmation($message, $default = false)

askHiddenResponse()

askHiddenResponse(string $message)

input()

input()

output()

output()

commandExist()

commandExist($command)

Check if command exists

commandSupportsOption()

commandSupportsOption($command, $option)

locateBinaryPath()

locateBinaryPath($name)