README.md

Growl Notifications with PHP

This package aims to provide an easy and fluent interface to construct and execute commands for various desktop notification programs.

Requirements

PHP 5.4+ and one of the following notification programs:

OS X

Growl & GrowlNotify

• Growl
• GrowlNotify

terminal-notifier

$ gem install terminal-notifier
$ brew install terminal-notifier

Linux

notify-send

$ apt-get install libnotify-bin
$ yum install libnotify

Windows

Growl & GrowlNotify

• Growl
• GrowlNotify

Installation

Composer

$ composer require bcrowe/growl

Usage

Create a new instance of the Growl class. You can optionally supply a Builder class and its path if you don't wish for the package to choose a notification program based on your system:

<?php
use BryanCrowe\Growl\Growl;

$Growl = new Growl;

// Or...

use BryanCrowe\Growl\Growl;
use BryanCrowe\Growl\Builder\GrowlNotifyBuilder;

$Growl = new Growl(new GrowlNotifyBuilder('/usr/local/bin/growlnotify'));
?>

Now, you can set key/value options for a Builder to use with the setOption() or setOptions() methods. After setting options, the last thing to do is build the command with buildCommand() or run it with execute():

<?php
(new Growl)
    ->setOption('title', 'Hello World')
    ->setOption('message', 'How are you doing?')
    ->setOption('sticky', true)
    ->execute();

// Or...

$Growl = new Growl;
$Growl->setOptions([
        'title' => 'Hello World',
        'message' => 'How are you doing?',
        'sticky' => true
    ])
    ->buildCommand();

exec($Growl);
?>

By default, this package will escape all command arguments that are supplied as options. If you want to change this, there are two options. Either completely disable escaping, or provide a safe-list of option keys that will be bypassed while escaping is enabled.

<?php
// Completely disable escaping...
(new Growl)
    ->setOptions([
        'title' => 'Hello World',
        'message' => 'How are you doing?',
        'url' => 'http://www.google.com'
    ])
    ->setEscape(false)
    ->execute();

// Set a safe-list of option keys. Can be an array of option keys, or a string.
(new Growl)
    ->setOptions([
        'title' => 'Hello World',
        'message' => $mySafeMessage,
        'url' => $mySafeURL
    ])
    ->setSafe(['message', 'url'])
    ->execute();
?>

Builders

GrowlNotifyBuilder & GrowlNotifyWindowsBuilder

Builds commands for growlnotify.

Available option keys:

• title string The title of the growl.
• message string The growl's body.
• sticky boolean Whether or not make the growl stick until closed.
• image string A name of an application's icon to use, e.g., "Mail" (OS X only), the path to a file on the system (OS X & Windows), or a URL to an image (Windows only).
• url string A URL to open if the growl is clicked.

TerminalNotifierBuilder

Builds commands for terminal-notifier.

Available option keys:

• title string The title of the notification.
• subtitle string The notification's subtitle.
• message string The notification's body.
• image string A URL to an image to be used as the icon. (OS X Mavericks+ only)
• contentImage string A URL to an image to be in the notification body. (OS X Mavericks+ only)
• url string A URL to go to when the notification is clicked.

NotifySendBuilder

Builds commands for notify-send.

Available option keys:

• title string The title of the notification.
• message string The notification's body.
• sticky boolean Whether or not make the notification stick until closed.

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Bryan Crowe
• All Contributors

License

The MIT License (MIT). Please see License File for more information.