Skip to main content
Version: 7.x

API Reference

Webpod - deploy JavaScript apps

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 files or directories to host.

To upload the contents of a directory, include a trailing slash (eg upload('build/', '{{release_path}}/public');). Without the trailing slash, the build directory itself will be uploaded (resulting in {{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

Note: due to the way php escapes command line arguments, list-notation for the rsync --exclude={'file','anotherfile'} option will not work. A workaround is to add a separate --exclude=file argument for each exclude to options (also, do not wrap the filename/filter in quotes). An alternative might be to write the excludes to a temporary file (one per line) and use --exclude-from=temporary_file argument instead.

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