Overview

Table 1. All classes
Name Description

Net_Growl

A PHP library that talk to Growl

Net_Growl_Application

Application object for Net_Growl

Net_Growl_Exception

Dedicated Exception for Net_Growl

Net_Growl_Udp

UDP adapter

Net_Growl_Gntp

GNTP adapter

Net_Growl_GntpMock

GNTP Mock adapter intended for test only

Net_Growl_Response

GNTP specialized response

Net_Growl Class

Synopsis

<?php
class Net_Growl
{
    /* constants */
    const string VERSION;
    const int UDP_PORT;
    const int GNTP_PORT;
    const int PRIORITY_LOW;
    const int PRIORITY_MODERATE;
    const int PRIORITY_NORMAL;
    const int PRIORITY_HIGH;
    const int PRIORITY_EMERGENCY;

    /* properties */
    protected array $options;
    protected array $growlNotificationCallback;
    protected int $growlNotificationCount;
    protected bool $isRegistered;
    protected static object $instance;

    private object $_application;
    private int $_growlNotificationLimit;
    private resource $_fp;

    /* methods */
    public static final object singleton(mixed &$application, array $notifications [, string $password = '' [, array $options = array()]] );
    public static final void reset();
    public void __destruct();
    public array getOptions();
    public void setNotificationLimit($max);
    public object getApplication();
    public bool | Net_Growl_Response register();
    public bool | Net_Growl_Response notify(string $name, string $title [, string $description = '' [, array $options = array()]] )
    public bool | Net_Growl_Response publish(string $name, string $title [, string $description = '' [, array $options = array()]] )
    public string getDefaultGrowlIcon();
    public static void autoload($class);
    public void errorHandler(int $errno, string $errstr, string $errfile, int $errline);

    protected object __construct(mixed &$application, array $notifications [, string $password = '' [, array $options = array()]] );
    protected bool | Net_Growl_Response sendRequest(string $method, mixed $data [, bool $callback = false] );
    protected void debug(string $message [, string $priority = 'debug']);
    protected string utf8Encode($data);
    protected int strByteLen($string);

    private string _readLine(resource $fp);
}

Constants

Table 2. Net_Growl Constants
Name Value Description

VERSION

n/a

PHP/Net_Growl version

UDP_PORT

9887

Growl default UDP port

GNTP_PORT

23053

Growl default GNTP port

PRIORITY_LOW

-2

Growl low priority

PRIORITY_MODERATE

-1

Growl moderate priority

PRIORITY_NORMAL

0

Growl normal priority

PRIORITY_HIGH

1

Growl high priority

PRIORITY_EMERGENCY

2

Growl emergency priority

Methods

Table 3. Net_Growl Methods
Name Description

singleton

Makes sure there is only one Growl connection open

setNotificationLimit

Limit the number of notifications

getApplication

Returns the registered application object

register

Sends a application register to Growl

notify

Sends a notification to Growl

getDefaultGrowlIcon

Returns Growl default icon logo binary data

autoload

Autoloader for PEAR compatible classes

errorHandler

Converts standard error into exception

getOptions

Gets options used with current Growl object

publish

Sends a notification to Growl (alias of notify method)

Net_Growl::singleton
Synopsis

require_once ‘Net/Growl/Autoload.php’;

object Net_Growl::singleton( &$application, $notifications, $password = ", $options = array() )

Description

Makes sure there is only one Growl connection open.

Parameter
mixed $application

Can be either a Net_Growl_Application object or the application name string

array $notifications

List of notification types

string $password

(optional) Password for Growl

array $options

(optional) List of options :

  • host, port, protocol, timeout

    • for Growl socket server

  • passwordHashAlgorithm, encryptionAlgorithm

    • to secure communications

  • debug

    • to know what data are sent and received.

Throws
Net_Growl_Exception

if class handler does not exists

Return value

object - Net_Growl

Net_Growl::setNotificationLimit
Synopsis

require_once ‘Net/Growl/Autoload.php’;

void Net_Growl::setNotificationLimit( $max )

Description

This method limits the number of notifications to be displayed on the Growl user desktop. By default, there is no limit. It is used mostly to prevent problem with notifications within loops.

Parameter
int $max

Maximum number of notifications

Throws

no exceptions thrown

Return value

void

Net_Growl::getApplication
Synopsis

require_once ‘Net/Growl/Autoload.php’;

object Net_Growl::getApplication( )

Description

Returns the registered application object

Throws

no exceptions thrown

Return value

object - Net_Growl_Application

Net_Growl::register
Synopsis

require_once ‘Net/Growl/Autoload.php’;

bool | Net_Growl_Response Net_Growl::register( )

Description

Sends a application register to Growl

Throws
Net_Growl_Exception

if REGISTER failed

Return value

void

Net_Growl::notify
Synopsis

require_once ‘Net/Growl/Autoload.php’;

bool | Net_Growl_Response Net_Growl::notify( $name, $title, $description = ", $options = array() )

Description

Sends a notification to Growl

Growl notifications have a name, a title, a description and a few options, depending on the kind of display plugin you use. The bubble plugin is recommended, until there is a plugin more appropriate for these kind of notifications.

The current options supported by most Growl plugins are:

<?php
 array('priority' => 0, 'sticky' => false);
  • sticky: whether the bubble stays on screen until the user clicks on it.

  • priority: a number from -2 (low) to 2 (high), default is 0 (normal).

Parameter
string $name

Notification name

string $title

Notification title

string $description

(optional) Notification description

string $options

(optional) few Notification options

Throws
Net_Growl_Exception

if NOTIFY failed

Return value

bool - true

Net_Growl::getDefaultGrowlIcon
Synopsis

require_once ‘Net/Growl/Autoload.php’;

string Net_Growl::getDefaultGrowlIcon( $return = true, $ver = 2 )

Description

Returns Growl default icon logo binary data. Decodes data encoded with MIME base64

Parameter
bool $return

(optional) If used and set to FALSE, getDefaultGrowlIcon() will output the binary representation instead of return it

string $ver

(optional) Icon version

Throws

no exceptions thrown

Return value

string - icon logo binary data

Example 1. Display Growl Icon
<?php
require_once 'Net/Growl/Autoload.php';

Net_Growl::getDefaultGrowlIcon(false);
?>
Net_Growl::autoload
Synopsis

require_once ‘Net/Growl/Autoload.php’;

void Net_Growl::autoload( $class )

Description

Autoloader for PEAR compatible classes

Parameter
string $class

Class name

Throws
Net_Growl_Exception

if class handler cannot be loaded

Return value

void

Net_Growl::errorhandler
Synopsis

require_once ‘Net/Growl/Autoload.php’;

void Net_Growl::errorhandler( $errno, $errstr, $errfile, $errline )

Description

Throws ErrorException when a standard error occured with severity level we are asking for (uses error_reporting)

Parameter
int $errno

contains the level of the error raised

string $errstr

contains the error message

string $errfile

contains the filename that the error was raised in

string $errline

contains the line number the error was raised at

Throws
ErrorException

corresponding to standard error/warning/notice raised

Return value

void

Net_Growl::getOptions
Synopsis

require_once ‘Net/Growl/Autoload.php’;

array Net_Growl::getOptions()

Description

Gets options used with current Growl object

Return value

array

Net_Growl::publish
Synopsis

require_once ‘Net/Growl/Autoload.php’;

bool | Net_Growl_Response Net_Growl::publish( $name, $title, $description = ", $options = array() )

Description

Sends a notification to Growl. Alias of notify() method.

Growl notifications have a name, a title, a description and a few options, depending on the kind of display plugin you use. The bubble plugin is recommended, until there is a plugin more appropriate for these kind of notifications.

The current options supported by most Growl plugins are:

<?php
 array('priority' => 0, 'sticky' => false);
  • sticky: whether the bubble stays on screen until the user clicks on it.

  • priority: a number from -2 (low) to 2 (high), default is 0 (normal).

Parameter
string $name

Notification name

string $title

Notification title

string $description

(optional) Notification description

string $options

(optional) few Notification options

Throws
Net_Growl_Exception

if NOTIFY failed

Return value

bool - true

Net_Growl_Application Class

Synopsis

<?php
class Net_Growl_Application
{
    /* properties */
    private string $_growlAppName;
    private string $_growlAppPassword;
    private Net_Growl_Icon $_growlAppIcon;
    private array $_growlNotifications;

    /* methods */
    public object __construct([mixed $appName = null [, array $notifications = null [, string $password = null [, string $appIcon = null]]]] );
    public void addGrowlNotifications(array $notifications);
    public array getGrowlNotifications();
    public string setGrowlName(string $appName);
    public string getGrowlName();
    public string setGrowlPassword(string $password);
    public string getGrowlPassword();
    public string setGrowlIcon(mixed $appIcon);
    public string getGrowlIcon();

}

Methods

Table 4. Net_Growl_Application Methods
Name Description

__construct

Constructs a new application to be registered by Growl

addGrowlNotifications

Adds notifications supported by this application

getGrowlNotifications

Returns the notifications accepted by Growl for this application

setGrowlName

Sets the application name for registration in Growl

getGrowlName

Returns the application name for registration in Growl

setGrowlPassword

Sets the password to be used by Growl to accept notification packets

getGrowlPassword

Returns the password to be used by Growl to accept notification packets

setGrowlIcon

Sets the application icon for registration in Growl

getGrowlIcon

Returns the application icon for registration in Growl

Net_Growl_Application::__construct
Synopsis

require_once ‘Net/Growl/Autoload.php’;

object new Net_Growl_Application( $appName, $notifications, $password = ", $appIcon = " )

Description

Constructs a new application to be registered by Growl

Parameter
string $appName

Application name

array $notifications

Array of notifications

string $password

(optional) Password to be used to notify Growl

string $appIcon

(optional) Application icon

Throws

no exceptions thrown

Return value

object - Net_Growl_Application

Example 2. PEAR_Error growl handler
<?php
require_once 'Net/Growl/Autoload.php';
require_once 'PEAR.php';

define('GROWL_NOTIFY_PEARERROR', 'PEAR_Error');

function growlErrors($error)
{
    static $app;

    if (!isset($app)) {
        $app = new Net_Growl_Application(
            'Net_Growl', array(GROWL_NOTIFY_PEARERROR), 'mamasam'
        );
    }

    $growl = Net_Growl::singleton(
        $app, null, null, array('host' => '127.0.0.1')
    );
    $growl->notify(GROWL_NOTIFY_PEARERROR,
        get_class($error),
        $error->message.' in '.$_SERVER['SCRIPT_NAME'],
        array('sticky' => true)
    );
}

PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'growlErrors');

PEAR::raiseError("The expected error you submitted does not exist");
?>
Net_Growl_Application::addGrowlNotifications
Synopsis

require_once ‘Net/Growl/Autoload.php’;

void Net_Growl_Application::addGrowlNotifications( $notifications )

Description

Adds notifications supported by this application

Expected array format is:

<?php
 array('notification name' => array('option name' => 'option value'));

At the moment, only option name enabled is supported. Example:

<?php
 $notifications = array('Test Notification' => array('enabled' => true));
Parameter
array $notifications

Array of notifications to support

Throws

InvalidArgumentException

Return value

void

Net_Growl_Application::getGrowlNotifications
Synopsis

require_once ‘Net/Growl/Autoload.php’;

array Net_Growl_Application::getGrowlNotifications( )

Description

Returns the notifications accepted by Growl for this application

Expected array format is:

<?php
 array('notification name' => array('option name' => 'option value'));

At the moment, only option name enabled is supported. Example:

<?php
 $notifications = array('Test Notification' => array('enabled' => true));
 return $notifications;
Throws

no exceptions thrown

Return value

array - list of notifications type

Net_Growl_Application::setGrowlName
Synopsis

require_once ‘Net/Growl/Autoload.php’;

string Net_Growl_Application::setGrowlName( $appName )

Description

Sets the application name for registration in Growl

Throws

InvalidArgumentException

Return value

void

Net_Growl_Application::getGrowlName
Synopsis

require_once ‘Net/Growl/Autoload.php’;

string Net_Growl_Application::getGrowlName( )

Description

Returns the application name for registration in Growl

Throws

no exceptions thrown

Return value

string — application name

Net_Growl_Application::setGrowlPassword
Synopsis

require_once ‘Net/Growl/Autoload.php’;

string Net_Growl_Application::setGrowlPassword( $password )

Description

Sets the password to be used by Growl to accept notification packets

Throws

InvalidArgumentException

Return value

void

Net_Growl_Application::getGrowlPassword
Synopsis

require_once ‘Net/Growl/Autoload.php’;

string Net_Growl_Application::getGrowlPassword( )

Description

Returns the password to be used by Growl to accept notification packets

Throws

no exceptions thrown

Return value

string — password

Net_Growl_Application::setGrowlIcon
Synopsis

require_once ‘Net/Growl/Autoload.php’;

string Net_Growl_Application::setGrowlIcon( $appIcon )

Description

Sets the application icon for registration in Growl

Throws

InvalidArgumentException

Return value

void

Net_Growl_Application::getGrowlIcon
Synopsis

require_once ‘Net/Growl/Autoload.php’;

string Net_Growl_Application::getGrowlIcon( )

Description

Returns the application icon for registration in Growl

Throws

no exceptions thrown

Return value

string — application icon binary data or empty if default image

Net_Growl_Exception Class

Synopsis

<?php
class Net_Growl_Exception extends Exception
{
}

Methods

Important Inherit all methods and properties from base Exception class. More details at http://www.php.net/manual/en/class.exception.php

Net_Growl_Udp Class

Synopsis

<?php
class Net_Growl_Udp
{
    /* methods */
    public object __construct(mixed $application [, array $notifications = array() [, string $password = '' [, array $options = array()]]] );
    public bool sendRegister();
    public bool sendNotify($name, $title, $description, $options);

}

Methods

Table 5. Net_Growl_Udp Methods
Name Description

__construct

Constructs a new UDP adapter

sendRegister

Sends the REGISTER message type

sendNotify

Sends the NOTIFY message type

Net_Growl_Udp::__construct
Synopsis

require_once ‘Net/Growl.php’;

object new Net_Growl_Udp( $application, $notifications = array(), $password = ", $options = array() )

Description

Constructs a new UDP adapter

Parameter
mixed $application

Application name

array $notifications

List of notification types

string $password

(optional) Password for Growl

array $options

(optional) List of options :

  • host, port, protocol, timeout

    • for Growl socket server

  • debug

    • to know what data are sent and received.

Throws

no exceptions thrown

Return value

object - Net_Growl_Udp

Net_Growl_Udp::sendRegister
Synopsis

require_once ‘Net/Growl.php’;

bool Net_Growl_Udp::sendRegister( )

Description

Sends the REGISTER message type

Throws
Net_Growl_Exception

if remote server communication failure

Return value

true

Net_Growl_Udp::sendNotify
Synopsis

require_once ‘Net/Growl.php’;

bool Net_Growl_Udp::sendNotify( )

Description

Sends the NOTIFY message type

Throws
Net_Growl_Exception

if remote server communication failure

Return value

true

Net_Growl_Gntp Class

Synopsis

<?php
class Net_Growl_Gntp
{
    /* properties */
    private array $_passwordHashAlgorithm;

    /* methods */
    public object __construct(mixed $application [, array $notifications = array() [, string $password = '' [, array $options = array()]]] );
    public Net_Growl_Response sendRegister();
    public Net_Growl_Response sendNotify($name, $title, $description, $options);

    protected string genMessageStructure($method, $data [, $binaries = false]);

    private array _genKey($password);
    private array _genEncryption($key, $plainText);
    private string _toBool($value);
}

Methods

Table 6. Net_Growl_Gntp Methods
Name Description

__construct

Constructs a new GNTP adapter

sendRegister

Sends the REGISTER message type

sendNotify

Sends the NOTIFY message type

Net_Growl_Gntp::__construct
Synopsis

require_once ‘Net/Growl.php’;

object new Net_Growl_Gntp( $application, $notifications = array(), $password = ", $options = array() )

Description

Constructs a new GNTP adapter

Parameter
mixed $application

Application name

array $notifications

List of notification types

string $password

(optional) Password for Growl

array $options

(optional) List of options :

  • host, port, protocol, timeout

    • for Growl socket server

  • passwordHashAlgorithm, encryptionAlgorithm

    • to secure communications

  • debug

    • to know what data are sent and received.

  • resourceDir

    • location of default icons; default to false, so use the @data_dir@ of PEAR

  • defaultIcon

    • the default icon filename

Throws

no exceptions thrown

Return value

object - Net_Growl_Gntp

Net_Growl_Gntp::sendRegister
Synopsis

require_once ‘Net/Growl.php’;

Net_Growl_Response Net_Growl_Gntp::sendRegister( )

Description

Sends the REGISTER message type

Throws
Net_Growl_Exception

if remote server communication failure

Return value

Net_Growl_Response object

Net_Growl_Gntp::sendNotify
Synopsis

require_once ‘Net/Growl.php’;

Net_Growl_Response Net_Growl_Gntp::sendNotify( )

Description

Sends the NOTIFY message type

Throws
Net_Growl_Exception

if remote server communication failure

Return value

Net_Growl_Response object

Net_Growl_GntpMock Class

Synopsis

<?php
class Net_Growl_GntpMock
{
    /* properties */
    protected $responses = array();

    /* methods */
    public object __construct(mixed $application [, array $notifications = array() [, string $password = '' [, array $options = array()]]] );
    public Net_Growl_Response sendRegister();
    public Net_Growl_Response sendNotify($name, $title, $description, $options);
    public void addResponse($response)

    protected Net_Growl_Response sendRequest()
    protected Net_Growl_Response createResponseFromString($str)
    protected Net_Growl_Response createResponseFromFile($fp)
}

Methods

Table 7. Net_Growl_GntpMock Methods
Name Description

__construct

Constructs a new GNTP Mock adapter

sendRegister

Mock sending the REGISTER message type

sendNotify

Mock sending the NOTIFY message type

addResponse

Adds response to the queue

Net_Growl_Gntp::__construct
Synopsis

require_once ‘Net/Growl.php’;

object new Net_Growl_Gntp( $application, $notifications = array(), $password = ", $options = array() )

Description

Constructs a new GNTP adapter

Parameter
mixed $application

Application name

array $notifications

List of notification types

string $password

(optional) Password for Growl

array $options

(optional) List of options :

  • host, port, protocol, timeout

    • for Growl socket server

  • passwordHashAlgorithm, encryptionAlgorithm

    • to secure communications

  • debug

    • to know what data are sent and received.

Throws

no exceptions thrown

Return value

object - Net_Growl_GntpMock

Net_Growl_GntpMock::sendRegister
Synopsis

require_once ‘Net/Growl.php’;

Net_Growl_Response Net_Growl_GntpMock::sendRegister( )

Description

Mock sending the REGISTER message type

Throws
Net_Growl_Exception

if Net_Growl_Response not received

Return value

Net_Growl_Response object

Net_Growl_GntpMock::sendNotify
Synopsis

require_once ‘Net/Growl.php’;

Net_Growl_Response Net_Growl_GntpMock::sendNotify( )

Description

Mock sending the NOTIFY message type

Throws
Net_Growl_Exception

if Net_Growl_Response not received

Return value

Net_Growl_Response object

Net_Growl_GntpMock::addResponse
Synopsis

require_once ‘Net/Growl.php’;

void Net_Growl_GntpMock::addResponse( $response )

Description

Adds response expected to the queue

Throws
Net_Growl_Exception

if $response is different to file pointer, string or Net_Growl_Exception

Return value

void

Net_Growl_Response Class

Synopsis

<?php
class Net_Growl_Response
{
    /* properties */
    protected string $version;
    protected string $code;
    protected string $action;
    protected integer $errorCode;
    protected string $errorDescription;
    protected string $machineName;
    protected string $softwareName;
    protected string $softwareVersion;
    protected string $platformName;
    protected string $platformVersion;
    protected string $body;

    /* methods */
    public object __construct(string $statusLine );
    public void appendBody(string $bodyChunk );
    public string getVersion();
    public string getStatus();
    public string getResponseAction();
    public integer getErrorCode();
    public string getErrorDescription();
    public string getOriginMachineName();
    public string getOriginSoftwareName();
    public string getOriginSoftwareVersion();
    public string getOriginPlatformName();
    public string getOriginPlatformVersion();
    public string __toString();

}

Methods

Table 8. Net_Growl_Response Methods
Name Description

__construct

Constructs a new GNTP specialized response

appendBody

Append a string to the response body

getVersion

Returns GNTP protocol version

getStatus

Returns the status code

getResponseAction

Returns the request action

getErrorCode

Returns the error code

getErrorDescription

Returns the error description

getOriginMachineName

Returns the machine name/host name of the sending computer

getOriginSoftwareName

Returns the identity of the sending framework

getOriginSoftwareVersion

Returns the version of the sending framework

getOriginPlatformName

Returns the identify of the sending computer OS/platform

getOriginPlatformVersion

Returns the version of the sending computer OS/platform

__toString

Returns the String representation of the Growl response

Net_Growl_Response::__construct
Synopsis

require_once ‘Net/Growl.php’;

object new Net_Growl_Response( $statusLine )

Description

Constructs a specialized response to a GNTP request

Parameter
mixed $statusLine

Response status line (e.g. "GNTP/1.0 -OK NONE")

Throws

no exceptions thrown

Return value

object - Net_Growl_Response

Net_Growl_Response::appendBody
Synopsis

require_once ‘Net/Growl.php’;

void Net_Growl_Response::appendBody( )

Description

Append a string to the response body excluding the protocol identifier, version, message type, and encryption algorithm id

Throws

no exceptions thrown

Return value

void

Net_Growl_Response::getVersion
Synopsis

require_once ‘Net/Growl.php’;

string Net_Growl_Response::getVersion( )

Description

Returns GNTP protocol version (e.g. 1.0, 1.1)

Throws

no exceptions thrown

Return value

string

Net_Growl_Response::getStatus
Synopsis

require_once ‘Net/Growl.php’;

string Net_Growl_Response::getStatus( )

Description

Returns the status code (OK | ERROR)

Throws

no exceptions thrown

Return value

string

Net_Growl_Response::getResponseAction
Synopsis

require_once ‘Net/Growl.php’;

string Net_Growl_Response::getResponseAction( )

Description

Returns the request action (REGITER | NOTIFY)

Throws

no exceptions thrown

Return value

string

Net_Growl_Response::getErrorCode
Synopsis

require_once ‘Net/Growl.php’;

int Net_Growl_Response::getErrorCode( )

Description

Returns the error code

Throws

no exceptions thrown

Return value

integer

Net_Growl_Response::getErrorDescription
Synopsis

require_once ‘Net/Growl.php’;

string Net_Growl_Response::getErrorDescription( )

Description

Returns the error description

Throws

no exceptions thrown

Return value

string

Net_Growl_Response::getOriginMachineName
Synopsis

require_once ‘Net/Growl.php’;

string Net_Growl_Response::getOriginMachineName( )

Description

Returns the machine name/host name of the sending computer

Throws

no exceptions thrown

Return value

string

Net_Growl_Response::getOriginSoftwareName
Synopsis

require_once ‘Net/Growl.php’;

string Net_Growl_Response::getOriginSoftwareName( )

Description

Returns the identity of the sending framework

  • Example1: Growl/Win

  • Example2: GrowlAIRConnector

Throws

no exceptions thrown

Return value

string

Net_Growl_Response::getOriginSoftwareVersion
Synopsis

require_once ‘Net/Growl.php’;

string Net_Growl_Response::getOriginSoftwareVersion( )

Description

Returns the version of the sending framework

  • Example1: 2.0.0.28

  • Example2: 1.2

Throws

no exceptions thrown

Return value

string

Net_Growl_Response::getOriginPlatformName
Synopsis

require_once ‘Net/Growl.php’;

string Net_Growl_Response::getOriginPlatformName( )

Description

Returns the identify of the sending computer OS/platform

  • Example1: Microsoft Windows NT 5.1.2600 Service Pack 3

  • Example2: Mac OS X

Throws

no exceptions thrown

Return value

string

Net_Growl_Response::getOriginPlatformVersion
Synopsis

require_once ‘Net/Growl.php’;

string Net_Growl_Response::getOriginPlatformVersion( )

Description

Returns the version of the sending computer OS/platform

  • Example1: 5.1.2600.196608

  • Example2: 10.6

Throws

no exceptions thrown

Return value

string

Net_Growl_Response::__toString
Synopsis

require_once ‘Net/Growl.php’;

string Net_Growl_Response::__toString( )

Description

Returns the String representation of the Growl response

  • Example1: Response REGISTER OK (Growl/Win 2.0.0.28)

  • Example2: Response ERROR 300 No notifications registered (Growl/Win 2.0.0.28)

Throws

no exceptions thrown

Return value

string