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.
Arguments:
-
name
type:string
Name of current task.
- ### body
type: 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
type:string
The task before $that should be run.
- ### do
type: string|callable
The task to be run.
after()
after(string $task, $do)
Call that task after specified task runs.
Arguments:
-
task
type:string
The task after $that should be run.
- ### do
type: 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
type:string
The task which need to fail so $that should be run.
- ### do
type: 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
type:string
The option name
- ### shortcut
type: string|array|null
The shortcuts, can be null, a string of shortcuts delimited by | or an array of shortcuts
- ### mode
type: int|null
The option mode: One of the VALUE_ constants
- ### description
type*: string
A description text
- ### default
type: 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): 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
type:string
Command to run on remote host.
- ### options
type: array|null
Array of options will override passed named arguments.
- ### timeout
type: int|null
Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec; see {{default_timeout}}, null to disable).
- ### idle_timeout
type: int|null
Sets the process idle timeout (max. time since last output) in seconds.
- ### secret
type: string|null
Placeholder %secret% can be used in command. Placeholder will be replaced with this value and will not appear in any logs.
- ### env
type: array|null
Array of environment variables: run('echo $KEY', env: ['key' => 'value']);
- ### real_time_output
type: bool|null
Print command output in real-time.
runLocally()
runLocally(string $command, ?array $options = [], ?int $timeout = null, ?int $idle_timeout = null, ?string $secret = null, ?array $env = null): string
Execute commands on a local machine.
Examples:
$user = runLocally('git config user.name');
runLocally("echo $user");
Arguments:
-
command
type:string
Command to run on localhost.
- ### options
type: array|null
Array of options will override passed named arguments.
- ### timeout
type: int|null
Sets the process timeout (max. runtime). The timeout in seconds (default: 300 sec, null to disable).
- ### idle_timeout
type: int|null
Sets the process idle timeout (max. time since last output) in seconds.
- ### secret
type: string|null
Placeholder %secret% can be used in command. Placeholder will be replaced with this value and will not appear in any logs.
- ### env
type: array|null
Array of environment variables: runLocally('echo $KEY', env: ['key' => 'value']);
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($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:
flagsfor overriding the default-azPpassed to thersynccommandoptionswith additional flags passed directly to thersynccommandtimeoutforProcess::fromShellCommandline()(nullby default)progress_barto 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, ?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