Elegant SSH tasks for PHP.

Last update: May 22, 2022

Laravel Envoy

Build Status Total Downloads Latest Stable Version License

Introduction

Laravel Envoy provides a clean, minimal syntax for defining common tasks you run on your remote servers. Using Blade style syntax, you can easily setup tasks for deployment, Artisan commands, and more.

Official Documentation

Documentation for Envoy can be found on the Laravel website.

Contributing

Thank you for considering contributing to Envoy! The contribution guide can be found in the Laravel documentation.

Code of Conduct

In order to ensure that the Laravel community is welcoming to all, please review and abide by the Code of Conduct.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

License

Laravel Envoy is open-sourced software licensed under the MIT license.

GitHub

https://github.com/laravel/envoy
Comments
  • 1. I provide password in envoy script but it prompts to enter password manually

    Hello! With laravel 5.8 envoy command I deploy on remote server and I set password in command line, like:

    envoy run Hostels2Deploy --lardeployer_password=111 --app_version=0.105a
    

    and envoy file:

    @setup
        $server_login_user= 'lardeployer';
        $lardeployer_password = isset($lardeployer_password) ? $lardeployer_password : "Not Defined";
    @endsetup
    
    @servers(['dev' => $server_login_user.':'.$lardeployer_password.'@NNN.NN.NNN.N'])
    
    
    @task('clean_old_releases')
        echo "Step # 81";
        echo 'The password is: {{ $lardeployer_password }}';
        echo 'The $server_login_user is: {{ $server_login_user }}';
        echo "Step # 00 app_version ::{{ $app_version }}";
    
        cd {{ $release_number_dir }}
        # php artisan envoy:delete-old-versions  Hostels2Deployed
    @endtask
    
    @macro('Hostels2Deploy',['on'=>'dev'])
        clean_old_releases
    @endmacro
    

    With credentials in @servers block I expected I will not have to enter password manually, but in command line I see prompt to enter password. I output $server_login_user and $lardeployer_password vars and they have valid values.

    Which is valid path ?

    Reviewed by sergeynilov at 2019-09-17 10:06
  • 2. error when updating symfony/process 4.3.8 to 4.4.1

    • Envoy Version: v1.6.4 (symfony/process v4.4.1)
    • Laravel Version: v.6.6.0
    • PHP Version: 7.2.x
    • Database Driver & Version:

    Description:

    When reading a command line argument it throws this error.

    In Process.php line 1648:

    Command line is missing a value for key "$KEY_NAME_HERE"

    Steps To Reproduce:

    Seems to be the same issue as: https://github.com/laravel/valet/pull/843

    If i downgrade to 4.3.8 it works fine...

    Or should I report this to the symfony/process repo?

    Reviewed by jstolp at 2019-12-02 13:24
  • 3. fix(Process): Convert command to array format

    When upgrade dependency symfony/process to version ^5.0

    We will got this error:

    Fatal error: Uncaught TypeError: Argument 1 passed to Symfony\Component\Process\Process::__construct() must be of the type array, string given, called in /root/.composer/vendor/laravel/envoy/src/RemoteProcessor.php on line 62 and defined in /root/.composer/vendor/symfony/process/Process.php:140

    So this pull request for resolve this issue.

    I was tested on my local.

    Reviewed by Quynh-Nguyen at 2019-11-27 07:08
  • 4. Added ability to run scripts locally without SSH.

    @taylorotwell This is a first pass at getting this working. I'm sure you could come up with a more elegant way of doing it. The main idea is that I'd like to use Envoy to handle a deploy process and the first step is to run some commands locally before running the deploy commands remotely. We don't want to have Node dependencies or the build process on remote servers so we need to run all those processes on the local machine prior to deploy (which is essentially an rsync operation). This patch just bypasses the SSH process when the $target is a localhost hostname.

    Below is an example Envoy.blade.php that will run tasks and macros using this patch. An example run would be something like envoy run installer.

    @servers([ 'vagrant' => '127.0.0.1' ])
    
    @task('init')
        git commit -am 'Initial commit.'
        git push origin master
    @endtask
    
    @task('install')
        composer install --no-dev
        npm install
        bower install
    @endtask
    
    @task('update')
        composer update --no-dev
        npm update
        bower update
    @endtask
    
    @task('keygen')
        php artisan key:generate
    @endtask
    
    @task('migrate')
        php artisan migrate --package="foo/bar"
        php artisan migrate
    @endtask
    
    @task('seed')
        php artisan db:seed
    @endtask
    
    @task('build')
        php artisan build
    @endtask
    
    @macro('setup')
        install
        keygen
        migrate
        seed
        build
        init
    @endmacro
    
    @macro('installer')
        install
        migrate
        build
    @endmacro
    
    @macro('updater')
        update
        migrate
        build
    @endmacro
    
    @macro('migrator')
        migrate
    @endmacro
    
    @macro('seeder')
        seed
    @endmacro
    
    @macro('builder')
        build
    @endmacro
    
    Reviewed by dalabarge at 2014-05-08 17:40
  • 5. envoy self-update returns JSON exception

    Recently when running envoy self-update it returns a JSON exception related to the GitHub manifest:

    Looking for updates... [Herrera\Json\Exception\FileException] file_get_contents(https://github.com/laravel/envoy/raw/master/envoy-manifest.json): failed to open stream: operation failed.

    Envoy still works which means there's no real problem. I've tried reinstalling the .phar but no fix.

    Running Laravel Envoy version 1.0.13 on MAMP PRO PHP v5.4.25 (with the path to PHP set correctly). Have tried 5.5.10 too but same problem.

    Reviewed by csoutham at 2014-03-25 09:41
  • 6. Feature Request: Manageable Envoy code: Add ability for a story to call another story, or to pass variables into tasks

    From all the testing I've done with Envoy over the past few months, there doesn't seem to be an efficient way to make the code DRY (as in, avoid duplication). This is more concerning than it appears because envoy scripts can get very long and complicated, even for basic deployment tasks.

    Here are some real use-cases I am struggling with at the moment: Luckily, envoy accepts passing variables into it from the command line, like so:

    envoy run build --env=local
    envoy run build --env=staging
    envoy run build --env=production
    envoy run deploy --env=staging
    envoy run deploy --env=production
    

    The first 3 build for different environments, the last 2 build and deploy to the appropriate environment.

    All of these use-cases involve 90% of the same set of steps (checkout repo, pick the right env file, create build, optionally deploy to the appropriate server or keep it local), except they need to do slightly different things (like use .env.local instead of .env.production) based on the variables that are passed in.

    Variables passed in from the command line can be 'read' within the @ setup directive, but the problem arises in taking it a step further from there:

    1. I don't see a way for a story to call another story dynamically, based on a parameter passed in from the command line.
    2. There's also no way that I know of to pass variables into Envoy @ tasks . I had asked for this a few months ago but it got closed. Also, asking on discord, laracasts etc did not get any answers...but I have a hard time believing that I am the only person that has this issue or use case.

    I am raising this again because copy-pasting and duplicating 200 lines of a task in envoy.blade.php another 3-4 times makes zero sense to me.

    The ask is simple...to provide a way to do # 1 or # 2 above, so that envoy scripts can become a lot more manageable.

    Reviewed by connecteev at 2019-08-12 07:01
  • 7. Sending a @finished notification via Telegram doesn't work

    Versions

    • Envoy Version: v2.3.1
    • Laravel Version: 8.0 (Now)
    • PHP Version: 7.3.1
    • Database Driver & Version: Mysql 5.7.24

    Description:

    I'm trying to send a notification to my customer via Telegram. I added the @finished to the bottom of my Envoy.blade.php file as below (details changed)

    @finished @telegram("MyBot","1234567890") @endfinished

    Steps To Reproduce:

    When running my prod envoy script I see the following error

    `PHP Parse error: syntax error, unexpected '}' in /home/vagrant/code/nsl/Envoy7b733335d6e41d155f181fe7fbef07d2.php on line 49

    Parse error: syntax error, unexpected '}' in /home/vagrant/code/nsl/Envoy7b733335d6e41d155f181fe7fbef07d2.php on line 49 `

    I was running Laravel 7.X but I took the time to upgrade thinking that may help. It didn't

    Thanks in advance for your help!

    Reviewed by barrasme at 2020-10-27 17:26
  • 8. Call to undefined method fromShellCommandline and Bad port for SSH connection

    • Envoy Version: 1.6.4
    • PHP Version: 7.2

    Description:

    Hi, I ran Envoy on CircleCI and got an error I don't have on v1.6.1 I think the bug arrived on 1.6.4. Here is the error I got

    Fatal error: Uncaught Error: Call to undefined method Symfony\Component\Process\Process::fromShellCommandline() in /home/circleci/.composer/vendor/laravel/envoy/src/RemoteProcessor.php on line 57
    

    I fixed Envoy version to 1.6.3 and got another error

    [-p XX [email protected]]: Bad port ' XX [email protected]'
    [✗] This task did not complete successfully on one of your servers.
    

    The SSH port is not 22 on this server.

    Everything works fine on Envoy 1.6.1 though.

    I use this image on CircleCI circleci/php:7.2-node-browsers

    Cheers

    Reviewed by peterpan666 at 2019-12-04 17:44
  • 9. Allow task servers to override story servers

    Happy to take a stab at a PR here but I wanted to confirm I wasn't missing something. Consider the case where you want to update multiple staging servers, and as part of it download a production db snapshot and restore it to staging:

    @servers(['staging-servers' => ['alpha.staging.example.com', 'beta.staging.example.com'], 'staging-primary' => 'alpha.staging.example.com'])
    
    @story('stage', [ 'on' => 'staging-servers' ])
        down
        pull
        dependencies
        restoredb
        migrate
        up
    @endstory
    

    Most of these task, of course, we want to run on all servers. However, we have a "restoredb" task that grabs the latest production database backup and restores it to staging, so we can work with the latest data. We obviously only want this to run one time.

    I would expect that I could override the on setting on the restoredb task specifically:

    @task('restoredb', [ 'on' => 'staging-primary' ])
        ...
    @endtask
    

    But that doesn't seem to work. So first, is this expected? Second, if it is expected, is there a different way we ought go about this, and is there a downside to changing behavior so it does work this way?

    Reviewed by amsoell at 2018-12-07 13:33
  • 10. Can stories have parallel option like tasks do?

    I have a deployment story, and I want it to run sequentially, one server at a time. However, it will actually perform one task for every server before moving on to the next task. i.e. for

    @servers(['one' => 'one.com', 'two' => 'two.com'])
    
    @story('deploy', ['on' => ['one', 'two']])
        touch1
        touch2
    @endstory
    
    @task('touch1')
        touch one
    @endtask
    
    @task('touch2')
        touch two
    @endtask
    

    will run one>touch1, two>touch1, one>touch2, two>touch2, but what I need it to do is one>touch1, one>touch2, two>touch1, two>touch2

    Reviewed by sublime392 at 2021-01-28 19:04
  • 11. Envoy no longer uses user's environment by default

    • Envoy Version: 1.5.0
    • Laravel Version: none; (I use Envoy for non-Laravel projects)

    Description:

    Envoy 1.5.0 no longer loads the user's environment by default. Before 1.5.0, all of a user's environment variables were available by default when running Envoy tasks.

    For example, in 1.4.1, this task:

    @task('test', ['on' => 'localhost'])
    echo $HOME
    @endtask
    

    would produce this output:

    [127.0.0.1]: /home/myusername
    

    However, after upgrading to 1.5.0, this no longer works and $HOME is no longer defined.

    I'm just using $HOME as a simple example. In my case, my deployments broke because envoy stopped using my $PATH variable, and my rsync commands that use ssh keys also stopped working (it started asking me for my key's passphrase).

    Based on some quick digging, it looks like the issue might have originated with commit Add ENVOY environment var to allow checking host within tasks, on line 31 of RemoteProcessor.php.

    I solved the issue for myself by rolling Envoy back to version 1.4.1.

    Edit: fixed typo in code example

    Reviewed by mtnorthrop at 2019-08-12 10:13
Related tags
PHP transpiler - Write and deploy modern PHP 8 code, today.

Phabel Write and deploy modern PHP 8 code, today. This is a transpiler that allows native usage of PHP 8+ features and especially syntax in projects a

May 19, 2022
A deployment tool written in PHP with support for popular frameworks out of the box
A deployment tool written in PHP with support for popular frameworks out of the box

Deployer A deployment tool written in PHP with support for popular frameworks out of the box. See deployer.org for more information and documentation.

May 28, 2022
The PHP Deployment Tool

Magallanes What's Magallanes? Magallanes is a deployment tool for made with PHP for PHP applications; it's quite simple to use and manage. For more in

May 22, 2022
A deployer library for PHP 5.3

Plum An object oriented deployer library Installation and configuration Plum does not provide and autoloader but follow the PSR-0 convention. $plum =

Feb 5, 2022
PHing Is Not GNU make; it's a PHP project build system or build tool based on Apache Ant.

P H I N G Thank you for using PHING! PHing Is Not GNU make; it's a PHP project build system or build tool based on Apache Ant. You can do anything wit

May 17, 2022
Elegant SSH tasks for PHP.

Laravel Envoy Introduction Laravel Envoy provides a clean, minimal syntax for defining common tasks you run on your remote servers. Using Blade style

May 22, 2022
[ABANDONED] PHP library for executing commands on multiple remote machines, via SSH
[ABANDONED] PHP library for executing commands on multiple remote machines, via SSH

#Shunt Inspired by Ruby's Capistrano, Shunt is PHP library for executing commands on multiple remote machines, via SSH. Specifically, this library was

Feb 20, 2022
An experimental object oriented SSH api in PHP

PHP SSH (master) Provides an object-oriented wrapper for the php ssh2 extension. Requirements You need PHP version 5.3+ with the SSH2 extension. Insta

May 13, 2022
API in PHP for DDoS Attacks (sends a command to a SSH Server from a URL)

SSH-PHP-API API in PHP for DDoS Attacks (sends a command to a SSH Server from a URL) [Install on Ubuntu 20.04: apt install apache2 php php-fpm php-ssh

Nov 18, 2021
PHP library for executing commands on multiple remote machines, via SSH
PHP library for executing commands on multiple remote machines, via SSH

#Shunt Inspired by Ruby's Capistrano, Shunt is PHP library for executing commands on multiple remote machines, via SSH. Specifically, this library was

Feb 20, 2022
A tool for managing SSH key access to any number of servers.

Revons - SSH Key Authority Features Easily manage SSH key access for all accounts on your servers. Manage user access and server-to-server access rule

Mar 14, 2022
A simple PHP package for sending messages to Slack, with a focus on ease of use and elegant syntax.

Slack for PHP | A simple PHP package for sending messages to Slack with incoming webhooks, focused on ease-of-use and elegant syntax. supports: PHP 7.

May 15, 2022
An Elegant CLI Library for PHP

Commando An Elegant PHP CLI Library Commando is a PHP command line interface library that beautifies and simplifies writing PHP scripts intended for c

May 12, 2022
The efficient and elegant JSON:API 1.1 server library for PHP

Woohoo Labs. Yin Woohoo Labs. Yin is a PHP framework which helps you to build beautifully crafted JSON:APIs. Table of Contents Introduction Features W

Mar 22, 2022
Patrol is an elegant command-line tool that keeps your PHP Project's dependencies in check.
Patrol is an elegant command-line tool that keeps your PHP Project's dependencies in check.

Patrol is an elegant command-line tool that keeps your PHP Project's dependencies in check. Installation / Usage Requires PHP 8.0+ First, install Patr

May 6, 2022
The efficient and elegant, PSR-7 compliant JSON:API 1.1 client library for PHP

Woohoo Labs. Yang Woohoo Labs. Yang is a PHP framework which helps you to communicate with JSON:API servers more easily. Table of Contents Introductio

May 5, 2022
NovaGram - An elegant, Object-Oriented, reliable PHP Telegram Bot Library
NovaGram - An elegant, Object-Oriented, reliable PHP Telegram Bot Library

An elegant, Object-Oriented, reliable PHP Telegram Bot Library Full Documentation • Public support group Examples • Features • Installation ?

May 24, 2022
Pest is an elegant PHP Testing Framework with a focus on simplicity
Pest is an elegant PHP Testing Framework with a focus on simplicity

Pest is an elegant PHP Testing Framework with a focus on simplicity. It was carefully crafted to bring the joy of testing to PHP. Explore the docs: pe

May 19, 2022
A simple PHP package for sending messages to Slack, with a focus on ease of use and elegant syntax.

Slack for PHP A simple PHP package for sending messages to Slack with incoming webhooks, focussed on ease-of-use and elegant syntax. Note: this packag

May 17, 2022