Skip to main content
  1. All Posts/

PHPloy

Tools PHP

[*]
PHPloy

Version 4.9.2
PHPloy is an incremental Git FTP and SFTP deployment tool. By keeping track of the state of the remote server(s) it deploys only the files that were committed since the last deployment. PHPloy supports submodules, sub-submodules, deploying to multiple servers and rollbacks. PHPloy requires PHP 7.3+ and Git 1.8+.

How it works

PHPloy stores a file called .revision on your server. This file contains the hash of the commit that you have deployed to that server. When you run phploy, it downloads that file and compares the commit reference in it with the commit you are trying to deploy to find out which files to upload. PHPloy also stores a .revision file for each submodule in your repository.

Install

Via Composer

If you have composer installed in your machine, you can pull PHPloy globally like this:

composer global require "banago/phploy"

Make sure to place the $HOME/.composer/vendor/bin directory (or the equivalent directory for your OS)
in your $PATH so the PHPloy executable can be located by your system.

Via Phar Archive

You can install PHPloy Phar globally, in your /usr/local/bin directory or, locally, in your project directory. Rename phploy.phar to phploy for ease of use.

  1. Globally: Move phploy into /usr/local/bin. Make it executable by running sudo chmod +x phploy.
  2. Locally Move phploy into your project directory.

Usage

When using PHPloy locally, proceed the command with php

  1. Run phploy --init in the terminal to create the phploy.ini file or create one manually.
  2. Run phploy in terminal to deploy.

Windows Users: Installing PHPloy globally on Windows

phploy.ini

The phploy.ini file holds your project configuration. It should be located in the root directory of the project. phploy.ini is never uploaded to server. Check the sample below for all available options:

; This is a sample deploy.ini file. You can specify as many
; servers as you need and use normal or quickmode configuration.
;
; NOTE: If a value in the .ini file contains any non-alphanumeric 
; characters it needs to be enclosed in double-quotes (").

[staging]
    scheme = sftp
    user = example
    ; When connecting via SFTP, you can opt for password-based authentication:
    pass = password
    ; Or private key-based authentication:
    privkey = 'path/to/or/contents/of/privatekey'
    host = staging-example.com
    path = /path/to/installation
    port = 22
    ; You can specify a branch to deploy from
    branch = develop
    ; File permission set on the uploaded files/directories
    permissions = 0700
    ; File permissions set on newly created directories
    directoryPerm = 0775
    ; Deploy only this directory as base directory
    base = 'directory-name/'
    ; Files that should be ignored and not uploaded to your server, but still tracked in your repository
    exclude[] = 'src/*.scss'
    exclude[] = '*.ini'
    ; Files that are ignored by Git, but you want to send the the server
    include[] = 'js/scripts.min.js'
    include[] = 'directory-name/'
    ; conditional include - if source file has changed, include file
    include[] = 'css/style.min.css:src/style.css' 
    ; Directories that should be copied after deploy, from->to
    copy[] = 'public->www'
    ; Directories that should be purged before deploy
    purge-before[] = "dist/"
    ; Directories that should be purged after deploy
    purge[] = "cache/"
    ; Pre- and Post-deploy hooks
    ; Use "DQOUTE" inside your double-quoted strings to insert a literal double quote
    ; Use 'QUOTE' inside your qouted strings to insert a literal quote
    ; For example pre-deploy[] = 'echo "that'QUOTE's nice"' to get a literal "that's".
    ; That workaround is based on http://php.net/manual/de/function.parse-ini-file.php#70847
    pre-deploy[] = "wget http://staging-example.com/pre-deploy/test.php --spider --quiet"
    post-deploy[] = "wget http://staging-example.com/post-deploy/test.php --spider --quiet"
    ; Works only via SSH2 connection
    pre-deploy-remote[] = "touch .maintenance"
    post-deploy-remote[] = "mv cache cache2"
    post-deploy-remote[] = "rm .maintenance"
    ; You can specify a timeout for the underlying connection which might be useful for long running remote 
    ; operations (cache clear, dependency update, etc.)
    timeout = 60

[production]
    quickmode = ftp://example:password@production-example.com:21/path/to/installation
    passive = true
    ssl = false
    ; You can specify a branch to deploy from
    branch = master
    ; File permission set on the uploaded files/directories
    permissions = 0774
    ; File permissions set on newly created directories
    directoryPerm = 0755
    ; Files that should be ignored and not uploaded to your server, but still tracked in your repository
    exclude[] = 'libs/*'
    exclude[] = 'config/*'
    exclude[] = 'src/*.scss'
    ; Files that are ignored by Git, but you want to send the the server
    include[] = 'js/scripts.min.js'
    include[] = 'js/style.min.css'
    include[] = 'directory-name/'
    purge-before[] = "dist/" 
    purge[] = "cache/" 
    pre-deploy[] = "wget http://staging-example.com/pre-deploy/test.php --spider --quiet"
    post-deploy[] = "wget http://staging-example.com/post-deploy/test.php --spider --quiet"

If your password is missing in the phploy.ini file or the PHPLOY_PASS environment variable, PHPloy will interactively ask you for your password.
There is also an option to store the user and password in a file called .phploy.

[staging]
    user="theUser"
    pass="thePassword"
    
[production]
    user="theUser"
    pass="thePassword"

This feature is especially useful if you would like to share your phploy.ini via Git but hide your password from the public.
You can also use environment variables to deploy without storing your credentials in a file.
These variables will be used if they do not exist in the phploy.ini file:

PHPLOY_HOST
PHPLOY_PORT
PHPLOY_PASS
PHPLOY_PATH
PHPLOY_USER
PHPLOY_PRIVKEY

These variables can be used like this;

$ PHPLOY_PORT="21" PHPLOY_HOST="myftphost.com" PHPLOY_USER="ftp" PHPLOY_PASS="ftp-password" PHPLOY_PATH="/home/user/public_html/example.com" phploy -s servername

Or export them like this, the script will automatically use them:

$ export PHPLOY_PORT="21"
$ export PHPLOY_HOST="myftphost.com"
$ export PHPLOY_USER="ftp"
$ export PHPLOY_PASS="ftp-password"
$ export PHPLOY_PATH="/home/user/public_html/example.com"
$ export PHPLOY_PRIVKEY="path/to/or/contents/of/privatekey"
$ phploy -s servername

Multiple servers

PHPloy allows you to configure multiple servers in the deploy file and deploy to any of them with ease.
By default PHPloy will deploy to ALL specified servers. Alternatively, if an entry named ‘default’ exists in your server configuration, PHPloy will default to that server configuration. To specify one single server, run:

phploy -s servername

or:

phploy --server servername

servername stands for the name you have given to the server in the phploy.ini configuration file.
If you have a ‘default’ server configured, you can specify to deploy to all configured servers by running:

phploy --all

Shared configuration (custom defaults)

If you specify a server configuration named *, all options configured in this section will be shared with other
servers. This basically allows you to inject custom default values.

; The special '*' configuration is shared between all other configurations (think include)
[*]
    exclude[] = 'src/*'
    include[] = "dist/app.css"

; As a result both shard1 and shard2 will have the same exclude[] and include[] "default" values
[shard1]
    quickmode = ftp://example:password@shard1-example.com:21/path/to/installation

[shard2]
    quickmode = ftp://example:password@shard2-example.com:21/path/to/installation

Rollbacks

Warning: the –rollback option does not currently update your submodules correctly.
PHPloy allows you to roll back to an earlier version when you need to. Rolling back is very easy.
To roll back to the previous commit, you…