README

A lightweight framework for quickly putting together PHP CLI scripts and applications.

Install with composer

composer require patinthehat/glacier

Events

Glacier allows you to write event-driven applications quite easily using Events and EventListeners.

Custom events extend the Event class, and names are generated automatically. Event names are generated by inserting a period before every capital letter (except the first) and making everything lowercase. For example, "MyEvent123" would trigger the "my.event123" event.

An event can be defined as simply as:

class MyEvent1 extends Event { }

Properties, etc. can be added as required.

To trigger an event, call event():

event(new MyEvent1)

You may also send a payload along with the event by passing a second, optional parameter:

event(new MyEvent1, "my custom payload");

Event Listeners

Events are handled by event listeners, which are automatically registered by the application. No action needs to be taken other than defining an EventListener or MultipleEventListener class. To disable this behavior, set the property $autoRegister to false:

public static $autoRegister = false;

An event listener that handles events 'my.event1' and 'my.event2' can be defined as such:

class MyEventListener1 extends EventListener
{
    public static $events = [ 'my.event1', 'my.event2' ];

    public function handle($event, $payload = null)
    {
        app()->output()->write('[event fired] '.$event->name . PHP_EOL);
        return true;
    }

To listen for ALL events, the event name should be defined as '*':

    public static $events = [ '*' ];

Commands

Glacier allows support for multiple commands within the same application. To create a command, extend the Command class:

class MyCommand extends Command
{
    public static $autoRegister = true;
    public $name = 'mycmd';

    public function execute()
    {
	    $this->app->output()->writeln('my command!');
    }
}

By default, all commands are automatically registered. To disable this behavior, set the static property $autoRegister to false:

    public static $autoRegister = false;

If autoregistration is disabled, register it before calling $app->run():

$app->registerCommand(new MyCommand);

Default Commands

Command-Line Arguments

Glacier will accept all command-line flags by default. To accept a flag with a value, you must call the defineOption() method on the arguments() method. Once done defining options, you must call parse().

Once defined, even if the short flag is provided, its value can be accessed by calling setting($name), such as setting('test'), even if -t 55 was passed on the command line.

To define command-line options, use the following format:

defineOption(shortflag, long-flag, expects-value, default-value)

such as:

defineOption('t', 'test', true, 0)

In full, to define a command-line option:

$app->arguments()
    ->defineOption('t', 'test', true, 0)
    ->defineOption('a', 'all', false, false)
    ->defineOption('c', 'count', true, 10)
    ->parse();

This must be done before a call to $app->run().

Any of these settings defined here could later be referenced, for example, as setting('count') or setting('all').

If you simply wish to be able to handle flags with no values, you do not need to call defineOption(). To access, simply reference app()->arguments()->hasOption('myflag'):

  if (app()->arguments()->hasOption('quiet')) { ...

Configuration Files

A Basic Application

require(__DIR__.'/vendor/autoload.php');

use Glacier\Console\Application;
use Glacier\Console\DefaultCommand;
use Glacier\Events\Event;
use Glacier\Events\EventListener;
use Glacier\Events\MultipleEventListener;


class MyEvent1 extends Event { }
class MyEvent2 extends Event { }

//automatically registered with the application
class MyEventListener1 extends EventListener
{
    public static $events = [ 'my.event1', 'my.event2' ];

    public function handle($event, $payload = null)
    {
        app()->output()->write('[event fired] '.$event->name.'; listener: '.__CLASS__ . '; payload = '. (isset($payload->name) ? $payload->name : '') . PHP_EOL);
        return true;
    }
}

//automatically registered with the application
class MyEventListener3 extends MultipleEventListener
{
    public static $events = [ '*' ];
    protected $ignoreMissingHandlers = true;

    public function my_event1(Event $event, $payload = null)
    {
        echo '[1] hi from '.__CLASS__.': '.$event->name.PHP_EOL;
    }

    public function my_event2(Event $event, $payload = null)
    {
        echo '[2] hi from '.__CLASS__.': '.$event->name.PHP_EOL;
    }
}

class DemoCommand extends DefaultCommand
{
    public function initialize()
    {
       event(new MyEvent2);
    }

    public function execute()
    {
        event(new MyEvent1);
        app()->output()->writeln('hello from '.$this->getName());
    }

}

$app = new Application($argv,  __DIR__, true, false, [DemoCommand::class], false, false);

$app->arguments()
    ->defineOption('t', 'test', true, 0)
    ->parse();

$app->run();

Execution: php myapp.php -t 55 or php myapp.php --test=123

A Simple Glacier Application

require(__DIR__.'/vendor/autoload.php');

use Glacier\Console\Application;
use Glacier\Console\DefaultCommand;

class DemoCommand extends DefaultCommand
{
    public $name = 'demo2';

    public function initialize()
    {
        //
    }

    public function execute()
    {
        if (app()->arguments()->hasOption('goodbye')) {
            app()->output()->writeln('goodbye from '.$this->getName());
        } else {
            app()->output()->writeln('hello from '.$this->getName());
        }
    }

}

$app = new Application($argv,  __DIR__, true, true, [DemoCommand::class], false, false);
$app->run();

Execution: php myapp.php then php myapp.php --goodbye

patinthehat / glacier

Maintainers

Details