bcrowe/growl

Growl notifications with PHP.

2.0.3 2016-03-12 00:12 UTC

README

Latest Version on Packagist Software License Build Status Coverage Status Quality Score Total Downloads

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

terminal-notifier

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

Linux

notify-send

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

Windows

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 bryan@bryan-crowe.com instead of using the issue tracker.

Credits

License

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