Laravel Envoy gives a clean and simple syntax for defining  tasks you run on your remote servers. Currently it supports only Mac and Linux OS and does not support Windows systems. You need to have a composer installed in your system already then install envoy by typing the below given command. 

composer global require laravel/envoy

Set the path as $HOME/.config/composer/vendor/bin or $HOME/.composer/vendor/bin directory so that the envoy exe file will be found when running the envoy command in the terminal. If you have cgr library installed, it will reduce the possibility for package version conflicts while installing envoy using composer. You can update your envoy package and all other globally installed packages using the below composer update command.

composer global update

How to write tasks using Envoy?

In the root of your project inside the Envoy.blade.php file define your Envoy tasks as I have done in the below given example.

@servers(['web' => ['user@192.168.1.1']])

@task('foo', ['on' => 'web'])
    ls -la
@endtask

In this example an array of @servers is defined at the top itself. In the on option of your task declarations you can refer to these servers. In the @task declarations place Bash code which will run on your server when the task is executed. If you want to run the tasks locally you can define the server ip address as 127.0.0.1.

@servers(['localhost' => '127.0.0.1'])

How to set up tasks with Envoy? You may need some PHP code before running the Envoy tasks sometimes. @setup directive can be used to declare variables and perform other PHP works before other tasks are executed.

@setup
    $now = new DateTime();

    $environment = isset($env) ? $env : "testing";
@endsetup

If you need some PHP files before the task is executed use @include directive in your Envoy.blade.php file.

@include('vendor/autoload.php')

@task('foo')
    # ...
@endtask

Variables You can pass option values into Envoy tasks using the below command. envoy run deploy --branch=master Using Blade’s echo syntax you can access options in your tasks. You can also use if statements and loops in your tasks. Here is an example.

@servers(['web' => '192.168.1.1'])

@task('deploy', ['on' => 'web'])
    cd site

    @if ($branch)
        git pull origin {{ $branch }}
    @endif

    php artisan migrate
@endtask

Stories Stories will group a set of tasks under a single, easy to understand name which helps you to categorize small, focused tasks to large tasks. An example is shown below.

@servers(['web' => '192.168.1.1'])

@story('deploy')
    git
    composer
@endstory

@task('git')
    git pull origin master
@endtask

@task('composer')
    composer install
@endtask

Here deploy story can run git and composer tasks by listing the task names inside it. Run the deploy task as follows:

envoy run deploy

Run tasks across multiple servers Envoy allows you to run tasks across multiple servers. Add the additional servers to your @server declaration which we have seen in ‘how to write tasks?’ session. There should be a unique name for each server. You should also list these servers in your tasks on the array.

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
@task('deploy', ['on' => ['web-1', 'web-2']])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

Parallel execution In Envoy tasks are executed on each server serially by default. You need to add the parallel option to your task declaration if you want to run a task in multiple servers in parallel.

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])

@task('deploy', ['on' => ['web-1', 'web-2'], 'parallel' => true])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

Running Tasks To run a task or story that is defined in your Envoy.blade.php file execute Envoys run command by passing the name of the task or story. Here deploy is the story name in the example. envoy run deploy Confirming execution of task If you like to get a prompt message before running the task on your servers add the confirm directive to your task declaration.

@task('deploy', ['on' => 'web', 'confirm' => true])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask