Getting Started

This simple tutorial will show you how to send different messages to Growl.

Before to send any notification, you should register your application to Growl.

Consider an application as a group of elements included :

a unique name to identify the application (required)
one icon to represent visually your application (optional - used default growl icon if missing)
a list of notification types that will receive future messages (required - an empty list does not have sense)

Do not register each time you send a new notification. It’s unnecessary.

Net_Growl will register your application at first notification send, if it was not implicitly called before with Net_Growl::register().

<?php
require_once 'Net/Growl/Autoload.php';

$notifications = array(
    'GROWL_NOTIFY_STATUS' => array(
        'display' => 'Status',
    ),
    'GROWL_NOTIFY_PHPERROR' => array(
        'display' => 'Error-Log'
    )
);
$appName  = 'PHP App Example using GNTP';
$password = '';
$options  = array(
    'protocol' => 'gntp',
    'timeout'  => 15,
);

try {
    $growl = Net_Growl::singleton($appName, $notifications, $password, $options);
    $growl->register();

} catch (Net_Growl_Exception $e) {
    echo 'Caught Growl exception: ' . $e->getMessage() . PHP_EOL;
?>

Previously, we have seen how to register an application with all definitions given by the Net_Growl class constructor. Now we will see an alternative solution using a Net_Growl_Application object.

<?php
require_once 'Net/Growl/Autoload.php';

$notifications = array(
    'GROWL_NOTIFY_PHPERROR'
);
$appName  = 'PHP App Example using GNTP';
$password = '';

$app = new Net_Growl_Application(
    $appName,
    $notifications,
    $password
);
$options = array(
    'protocol' => 'gntp',
);

$growl = Net_Growl::singleton($app, null, null, $options);
$growl->register();
?>

Distinct UDP and GNTP communication

Default options will used the basic UDP protocol on port 9887.

If you want to use the new GNTP, you should specify options protocol (= gntp)

See singleton method, and options parameter (#4).

We will reused the source code presented in register application feature, and used tip to auto-register application at first notification call.

<?php
require_once 'Net/Growl/Autoload.php';

$notifications = array(
    'GROWL_NOTIFY_STATUS' => array(
        'display' => 'Status',
    ),
    'GROWL_NOTIFY_PHPERROR' => array(
        'display' => 'Error-Log'
    )
);
$appName  = 'PHP App Example using GNTP';
$password = '';
$options  = array(
    'protocol' => 'gntp',
    'timeout'  => 15,
);

try {
    $growl = Net_Growl::singleton($appName, $notifications, $password, $options);

    $name        = 'GROWL_NOTIFY_STATUS';
    $title       = 'Congratulation';
    $description = 'You have successfully installed PEAR/Net_Growl.';
    $growl->publish($name, $title, $description);

} catch (Net_Growl_Exception $e) {
    echo 'Caught Growl exception: ' . $e->getMessage() . PHP_EOL;
?>

We have defined two notifications type
[GROWL_NOTIFY_STATUS and GROWL_NOTIFY_PHPERROR]
when register application on getting a Growl instance. But we use only one of them to send our basic Congratulation message.

You can define as much notification types as you want, depending of your need. For example, Gmail Growl sets 3 types

New Mail
state
New Version

Here, in our example, we will set 2 notification types

Status (GROWL_NOTIFY_STATUS)
Error-Log (GROWL_NOTIFY_PHPERROR)

and send messages on both channels.

Here are the full script, we will explain just after :

<?php
require_once 'Net/Growl/Autoload.php';

$notifications = array(
    'GROWL_NOTIFY_STATUS' => array(
        'display' => 'Status',
    ),
    'GROWL_NOTIFY_PHPERROR' => array(
        'icon'    => 'http://www.laurent-laville.org/growl/images/firephp.png',
        'display' => 'Error-Log'
    )
);
$appName  = 'PHP App Example using GNTP';
$password = '';
$options  = array(
    'protocol' => 'gntp',
    'timeout'  => 15,
    'AppIcon'  => 'http://www.laurent-laville.org/growl/images/Help.png',
);

try {
    $growl = Net_Growl::singleton($appName, $notifications, $password, $options);

    $name        = 'GROWL_NOTIFY_STATUS';
    $title       = 'Congratulation';
    $description = 'You have successfully installed PEAR/Net_Growl.';
    $growl->publish($name, $title, $description);

    $name        = GROWL_NOTIFY_PHPERROR;
    $title       = 'New Error';
    $description = 'You have a new PHP error in your script.';
    $options     = array(
        'priority' => Net_Growl::PRIORITY_HIGH,
    );
    $growl->publish($name, $title, $description, $options);

    $name        = GROWL_NOTIFY_STATUS;
    $title       = 'Welcome';
    $description = "Welcome in PHP/GNTP world ! \n"
                 . "New GNTP protocol add icon support.";
    $options     = array(
        'icon'   => 'http://www.laurent-laville.org/growl/images/unknown.png',
        'sticky' => false,
    );
    $growl->publish($name, $title, $description, $options);

} catch (Net_Growl_Exception $e) {
    echo 'Caught Growl exception: ' . $e->getMessage() . PHP_EOL;
?>

First message notified by code below

<?php
    $name        = 'GROWL_NOTIFY_STATUS';
    $title       = 'Congratulation';
    $description = 'You have successfully installed PEAR/Net_Growl.';
    $growl->publish($name, $title, $description);

will show the Toast notification (only on first script run)

Net_Growl Register

Followed by

Notify Status 1

Second message sent over the other channel (notification type) on a highest priority

<?php
    $name        = GROWL_NOTIFY_PHPERROR;
    $title       = 'New Error';
    $description = 'You have a new PHP error in your script.';
    $options     = array(
        'priority' => Net_Growl::PRIORITY_HIGH,
    );
    $growl->publish($name, $title, $description, $options);

will show this Toast notification

Notify PHP Error

And finally the third and last message with default application icon
[http://www.laurent-laville.org/growl/images/Help.png (AppIcon option of singleton method)]
because resource http://www.laurent-laville.org/growl/images/unknown.png does not exist.

<?php
    $name        = GROWL_NOTIFY_STATUS;
    $title       = 'Welcome';
    $description = "Welcome in PHP/GNTP world ! \n"
                 . "New GNTP protocol add icon support.";
    $options     = array(
        'icon'   => 'http://www.laurent-laville.org/growl/images/unknown.png',
        'sticky' => true,
    );
    $growl->publish($name, $title, $description, $options);

will show this other one Toast notification

Notify Status 2

Getting Started

Register your application

Notify a simple basic message

Notify different message types