glowieframework/deploy

Glowie deploy plugin

dev-main 2025-03-31 19:32 UTC

Requires

• glowieframework/global-helpers: ^1.0
• glowieframework/glowie-core: ^1.8

MIT

• Gabriel Silva

README

This is a plugin for Glowie Framework to deploy applications using automated SSH scripts. It allows support for notifications, tasks and environment variables.

Requirements

This plugin requires the ssh2 PHP extension.

Installation

Install in your Glowie project using Composer:

composer require glowieframework/deploy

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

'plugins' => [
    // ... other plugins here
    \Glowie\Plugins\Deploy\Deploy::class,
],

Make sure to publish the plugin files with the CLI:

php firefly publish

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, this is the main entry point for your deploy scripts.

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

php firefly deploy:create

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:

public function deploy(){

    $this->command('cd /var/www/my-project');

    $this->command('git pull');

    $this->command('php firefly migrate');

}

Each command will run in order and wait for the previous command to finish before its execution. If a remote command fails or return an exit code greater than 0, it will throw an exception and end the script.

Each command output will be printed to the terminal upon its 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.

// Runs only in "homologation" server
$this->command('cd /var/www/my-project', 'homologation');

// Runs in both "homologation" and "production" servers
$this->command('git pull', ['homologation', 'production']);

Printing messages in the console

To print a custom message in the console, use:

$this->print('My custom message');

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

$this->error('Something failed!');

$this->success('Everything works great.');

$this->warning('Be careful...');

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:

public function success(string $task){
    // You can do anything here
    $this->success("$task ran successfully!");
}

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 a 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:

public function fail(string $task, Throwable $th){
    // You can do anything here
    $this->error("$task failed! Stack trace:");
    $this->error($th->getTraceAsString());
}

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

Running a deploy task

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

php firefly deploy:run

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

php firefly deploy:run --task=myTask

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

php firefly deploy:run --path=/path/to/.deploy-tasks.php

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:

php firefly deploy:run --version=1.0.0

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

$version = $this->getArg('version'); // returns "1.0.0"

You can also pass custom options:

php firefly deploy:run --production

And retrieve from your task:

$isProduction = $this->hasOption('production'); // returns true

Notifications

Glowie Deploy also supports sending notifications to some services. You can use this feature to inform the tasks progresses or errors on 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:

DEPLOY_DISCORD_URL=https://discord.com/api/webhooks/...

Then, in your task, simply call:

$this->notifyDiscord('Write your message to Discord here!');

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:

DEPLOY_SLACK_URL=https://hooks.slack.com/...

Then, in your task, simply call:

$this->notifySlack('Write your message to Slack here!');

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:

DEPLOY_TELEGRAM_BOT_ID=...
DEPLOY_TELEGRAM_CHAT_ID=...

Then, in your task, simply call:

$this->notifyTelegram('Write your message to Telegram here!');

Push notifications (with Alertzy)

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

DEPLOY_PUSH_KEY=...

Then, in your task, simply call:

$this->notifyPush('Write a message to your phone here!');

Important

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 currently being developed by Gabriel Silva.