Download the PHP package glowieframework/deploy without Composer

Glowie Deploy

This is a plugin for Glowie Framework that allows deploying applications using automated SSH scripts. It supports notifications, tasks, and environment variables.

You can also use Deploy in standalone mode, without the need for a Glowie installation.

Installation

In a Glowie project

Install in your Glowie project using Composer:

Then add the Deploy class to the plugins array in the app/config/Config.php file:

Make sure to publish the plugin files with the CLI:

This will create a Deploy.php file in your app/config folder. This is where the plugin settings will be stored.

It will also create a .deploy-tasks.php file in the root of your application, which is the main entry point for your deploy scripts.

If you want to create the tasks file manually in the current project directory, run:

Standalone

You can use Deploy without installing Glowie. Simply download the binary from the releases page, give it execute permissions using chmod +x, and optionally add it to your system's PATH for easier access.

If you already have Composer installed, you can install Deploy globally with the following command:

After that, make sure the Composer global bin directory is in your system's PATH so you can run Deploy from anywhere.

To generate the .deploy-tasks.php file in the current working directory, run:

To specify a different location, use the --path option.

Configuration

In a Glowie project

When you publish the plugin files, a configuration file named Deploy.php will be created in your app/config folder. This file is responsible for defining your deploy servers and notification settings.

[!CAUTION] Never store sensitive credentials (like passwords or API keys) directly in this file. Always use environment variables.

Standalone

You can create a configuration file by running:

This will generate a .deploy-config.php file in the current working directory. To specify a different location, use the --path option.

Servers

Under the servers key of the configuration file, you can define an associative array of all servers that will be used in your deploy process. Each server should have a unique name as the key, and the corresponding connection settings as the value.

Notifications

The notifications section of the configuration file allows you to configure services to receive real-time updates during the deploy process. Each supported service accepts an API key or webhook URL. Read more about Notifications below.

Writing tasks

Your deploy tasks must be written in the .deploy-tasks.php file. A task is a PHP function that will be called in the deploy lifecycle.

To run shell commands in the target servers, use:

Each command will run in order and wait for the previous command to finish before its execution. If a remote command fails or returns a non-zero exit code, an exception will be thrown and the script execution will stop.

The output of each command will be printed to the terminal upon execution.

Specifying the target server

By default, all commands will run in all servers from the config file. If you want to run a command in a single server, pass the server name as the second argument of the command() method. You can also use an array of server names.

You can also enclose a set of commands to run on a specific server (or an array of servers) by using the following syntax:

Printing messages in the console

To print a custom message in the console, use:

You can also pass an optional color name as the second argument or use one of the aliases:

Before initialization

If you want to perform an action before your task runs, define the following method in your tasks file:

The method will receive the task name as the first parameter.

After success

If you want to do something when your task ends the execution with success (no command returned a code greater than 0), create the following method in the tasks file:

The method will receive the task name as the first parameter.

Handling errors

If something in your task fails, the script execution will stop and an exception will be thrown. If you want to capture the error and do something with it (like sending a notification), create the following method in the tasks file:

The method will receive the task name as the first parameter, and the exception as the second. This method is called for errors in any task from the tasks file.

Setting environment variables

You can expose environment variables to the target servers using the env() method. This method allows you to add or override environment variables defined in the config file.

[!NOTE] Environment variables exposed using this method are shared across all servers.

Running a deploy task

In a Glowie project

Open the terminal in the root of your application and run:

This will run the default deploy() task. If you want to run another task, pass the task name as:

Alternatively, you can also specify the target tasks file, if you are not using the default .deploy-tasks.php in the current working directory:

You can also specify a custom config file if you're not using the default one:

Standalone

All commands above can be executed directly without using the php firefly deploy prefix, as long as the binary is properly installed and accessible from your system's PATH.

This will run in the current working directory, regardless of its location.

Passing CLI arguments and options

If you want to pass a custom argument to the task, just send it in the terminal using the syntax:

To get this argument value from within your tasks file, use:

You can also pass custom options:

And retrieve from your task:

Working with stories

A story is a group of tasks executed in order during the deployment process, useful for organizing and isolating specific steps or operations.

It works the same way as a deploy task. To define a story in the tasks file, create a PHP function with the name of the story. Example:

[!IMPORTANT] The story method must not execute shell operations directly. Instead, it should invoke other task methods to perform those operations.

Running a story

To run a deploy story from the CLI, use the following command:

The name argument should match the name of the story function you want to call.

Before initialization

If you want to perform an action before your story runs, define the following method in your tasks file:

The method will receive the story name as the first parameter.

After success

If you want to do something when your story ends the execution with success (no command returned a code greater than 0), create the following method in the tasks file:

The method will receive the story name as the first parameter.

Handling errors

If something in your story fails, the script execution will stop and an exception will be thrown. If you want to capture the error and do something with it (like sending a notification), create the following method in the tasks file:

The method will receive the story name as the first parameter, and the exception as the second.

Notifications

Glowie Deploy also supports sending notifications to some services. You can use this feature to report task progress or errors to your favorite applications.

Discord

To send a notification as a message to a Discord channel, create a Discord webhook and copy its URL to your app .env file:

Then, in your task, simply call:

Slack

To send a notification as a message to a Slack channel, create a Slack webhook and copy its URL to your app .env file:

Then, in your task, simply call:

Telegram

To send a notification as a message to a Telegram chat, first create a Telegram bot and grab its ID using BotFather. Second, grab the destination chat ID using IDBot. After that, copy both IDs to your app .env file:

Then, in your task, simply call:

Push notifications (with Alertzy)

To send a message as a push notification to your phone, download the Alertzy app on your phone and create an account. Then, grab your account key in the app and copy to your .env file:

Then, in your task, simply call:

[!NOTE] Alertzy has a limit of 100 push notifications per day. After that limit is reached, notifications will stop being delivered.

Credits

Deploy and Glowie are actively developed by Gabriel Silva.