The Push Notification Provider. More...

Inheritance diagram for ApnsPHP_Push:

Collaboration diagram for ApnsPHP_Push:

Public Member Functions
void	add (ApnsPHP_Message $message)
	Adds a message to the message queue. More...

array	getErrors (boolean $bEmpty=true)
	Returns messages not delivered to the end user because one (or more) error occurred. More...

array	getQueue (boolean $bEmpty=true)
	Returns messages in the message queue. More...

integer	getSendRetryTimes ()
	Get the send retry time value. More...

void	send ()
	Sends all messages in the message queue to Apple Push Notification Service. More...

void	setSendRetryTimes (integer $nRetryTimes)
	Set the send retry times value. More...

Public Member Functions inherited from ApnsPHP_Abstract
void	__construct (integer $nEnvironment, string $sProviderCertificateFile)
	Constructor. More...

void	connect ()
	Connects to Apple Push Notification service server. More...

boolean	disconnect ()
	Disconnects from Apple Push Notifications service server. More...

string	getCertificateAuthority ()
	Get the Root Certification Authority file path. More...

integer	getConnectRetryInterval ()
	Get the connect retry interval. More...

integer	getConnectRetryTimes ()
	Get the connect retry time value. More...

integer	getConnectTimeout ()
	Get the connection timeout. More...

ApnsPHP_Log_Interface	getLogger ()
	Get the Logger instance. More...

integer	getSocketSelectTimeout ()
	Get the TCP socket select timeout. More...

integer	getWriteInterval ()
	Get the write interval. More...

void	setConnectRetryInterval (integer $nRetryInterval)
	Set the connect retry interval. More...

void	setConnectRetryTimes (integer $nRetryTimes)
	Set the connect retry times value. More...

void	setConnectTimeout (integer $nTimeout)
	Set the connection timeout. More...

void	setLogger (ApnsPHP_Log_Interface $logger)
	Set the Logger instance to use for logging purpose. More...

void	setProviderCertificatePassphrase (string $sProviderCertificatePassphrase)
	Set the Provider Certificate passphrase. More...

void	setRootCertificationAuthority (string $sRootCertificationAuthorityFile)
	Set the Root Certification Authority file. More...

void	setSocketSelectTimeout (integer $nSelectTimeout)
	Set the TCP socket select timeout. More...

void	setWriteInterval (integer $nWriteInterval)
	Set the write interval. More...

Data Fields
const	COMMAND_PUSH = 1
	integer Payload command. More...

const	ERROR_RESPONSE_COMMAND = 8
	integer Error-response command code. More...

const	ERROR_RESPONSE_SIZE = 6
	integer Error-response packet size. More...

const	STATUS_CODE_INTERNAL_ERROR = 999
	integer Status code for internal error (not Apple). More...

Data Fields inherited from ApnsPHP_Abstract
const	CONNECT_RETRY_INTERVAL = 1000000
	integer Default connect retry interval in micro seconds. More...

const	DEVICE_BINARY_SIZE = 32
	integer Device token length. More...

const	ENVIRONMENT_PRODUCTION = 0
	integer Production environment. More...

const	ENVIRONMENT_SANDBOX = 1
	integer Sandbox environment. More...

const	SOCKET_SELECT_TIMEOUT = 1000000
	integer Default socket select timeout in micro seconds. More...

const	WRITE_INTERVAL = 10000
	integer Default write interval in micro seconds. More...

Protected Member Functions
string	_getBinaryNotification (string $sDeviceToken, string $sPayload, integer $nMessageID=0, integer $nExpire=604800)
	Generate a binary notification from a device token and a JSON-encoded payload. More...

array	_parseErrorMessage (string $sErrorMessage)
	Parses the error message. More...

array null	_readErrorMessage ()
	Reads an error message (if present) from the main stream. More...

void	_removeMessageFromQueue (integer $nMessageID, boolean $bError=false)
	Remove a message from the message queue. More...

boolean	_updateQueue (array $aErrorMessage=null)
	Checks for error message and deletes messages successfully sent from message queue. More...

Protected Member Functions inherited from ApnsPHP_Abstract
boolean	_connect ()
	Connects to Apple Push Notification service server. More...

void	_log (string $sMessage)
	Logs a message through the Logger. More...

Protected Attributes
	$_aErrorResponseMessages
	array Error-response messages. More...

array	$_aErrors = array()
	Error container. More...

array	$_aMessageQueue = array()
	Message queue. More...

	$_aServiceURLs
	array Service URLs environments. More...

integer	$_nSendRetryTimes = 3
	Send retry times. More...

Protected Attributes inherited from ApnsPHP_Abstract
array	$_aServiceURLs = array()
	Container for service URLs environments. More...

resource	$_hSocket
	SSL Socket. More...

ApnsPHP_Log_Interface	$_logger
	Logger. More...

integer	$_nConnectRetryInterval
	Connect retry interval in micro seconds. More...

integer	$_nConnectRetryTimes = 3
	Connect retry times. More...

integer	$_nConnectTimeout
	Connect timeout in seconds. More...

integer	$_nEnvironment
	Active environment. More...

integer	$_nSocketSelectTimeout
	Socket select timeout in micro seconds. More...

integer	$_nWriteInterval
	Write interval in micro seconds. More...

string	$_sProviderCertificateFile
	Provider certificate file with key (Bundled PEM). More...

string	$_sProviderCertificatePassphrase
	Provider certificate passphrase. More...

string	$_sRootCertificationAuthorityFile
	Root certification authority file. More...

Detailed Description

The Push Notification Provider.

The class manages a message queue and sends notifications payload to Apple Push Notification Service.

Definition at line 33 of file Push.php.

Member Function Documentation

string _getBinaryNotification	(	string	$sDeviceToken,
		string	$sPayload,
		integer	$nMessageID = `0`,
		integer	$nExpire = `604800`
	)

protected

Generate a binary notification from a device token and a JSON-encoded payload.

See Also: http://tinyurl.com/ApplePushNotificationBinary

Parameters

$sDeviceToken	The device token.
$sPayload	The JSON-encoded payload.
$nMessageID	[optional] Message unique ID.
$nExpire	[optional] Seconds, starting from now, that identifies when the notification is no longer valid and can be discarded. Pass a negative value (-1 for example) to request that APNs not store the notification at all. Default is 86400 * 7, 7 days.

Returns: A binary notification.

Definition at line 263 of file Push.php.

Referenced by add().

     {
         $nTokenLength = strlen($sDeviceToken);
         $nPayloadLength = strlen($sPayload);
 
         $sRet  = pack('CNNnH*', self::COMMAND_PUSH, $nMessageID, $nExpire > 0 ? time() + $nExpire : 0, self::DEVICE_BINARY_SIZE, $sDeviceToken);
         $sRet .= pack('n', $nPayloadLength);
         $sRet .= $sPayload;
 
         return $sRet;
     }

Here is the caller graph for this function:

array _parseErrorMessage ( string $sErrorMessage )

protected

Parses the error message.

Parameters

$sErrorMessage The Error Message.

Returns: Array with command, statusCode and identifier keys.

Definition at line 281 of file Push.php.

Referenced by _readErrorMessage().

     {
         return unpack('Ccommand/CstatusCode/Nidentifier', $sErrorMessage);
     }

Here is the caller graph for this function:

array null _readErrorMessage ( )

protected

Reads an error message (if present) from the main stream.

If the error message is present and valid the error message is returned, otherwhise null is returned.

Returns: Return the error message array.

Definition at line 293 of file Push.php.

References _parseErrorMessage().

Referenced by _updateQueue().

     {
         $sErrorResponse = @fread($this->_hSocket, self::ERROR_RESPONSE_SIZE);
         if ($sErrorResponse === false || strlen($sErrorResponse) != self::ERROR_RESPONSE_SIZE) {
             return;
         }
         $aErrorResponse = $this->_parseErrorMessage($sErrorResponse);
         if (!is_array($aErrorResponse) || empty($aErrorResponse)) {
             return;
         }
         if (!isset($aErrorResponse['command'], $aErrorResponse['statusCode'], $aErrorResponse['identifier'])) {
             return;
         }
         if ($aErrorResponse['command'] != self::ERROR_RESPONSE_COMMAND) {
             return;
         }
         $aErrorResponse['time'] = time();
         $aErrorResponse['statusMessage'] = 'None (unknown)';
         if (isset($this->_aErrorResponseMessages[$aErrorResponse['statusCode']])) {
             $aErrorResponse['statusMessage'] = $this->_aErrorResponseMessages[$aErrorResponse['statusCode']];
         }
         return $aErrorResponse;
     }

Here is the call graph for this function:

Here is the caller graph for this function:

void _removeMessageFromQueue	(	integer	$nMessageID,
		boolean	$bError = `false`
	)

protected

Remove a message from the message queue.

Parameters

$nMessageID	The Message ID.
$bError	[optional] Insert the message in the Error container.

Exceptions

ApnsPHP_Push_Exception if the Message ID is not valid or message does not exists.

Definition at line 371 of file Push.php.

Referenced by send().

     {
         if (!is_numeric($nMessageID) || $nMessageID <= 0) {
             throw new ApnsPHP_Push_Exception(
                 'Message ID format is not valid.'
             );
         }
         if (!isset($this->_aMessageQueue[$nMessageID])) {
             throw new ApnsPHP_Push_Exception(
                 "The Message ID {$nMessageID} does not exists."
             );
         }
         if ($bError) {
             $this->_aErrors[$nMessageID] = $this->_aMessageQueue[$nMessageID];
         }
         unset($this->_aMessageQueue[$nMessageID]);
     }

Here is the caller graph for this function:

boolean _updateQueue ( array $aErrorMessage = null )

protected

Checks for error message and deletes messages successfully sent from message queue.

Parameters

$aErrorMessage [optional] The error message. It will anyway always be read from the main stream. The latest successful message sent is the lowest between this error message and the message that was read from the main stream.

See Also: _readErrorMessage()

Returns: True if an error was received.

Definition at line 327 of file Push.php.

References ApnsPHP_Abstract::_log(), _readErrorMessage(), ApnsPHP_Abstract::connect(), and ApnsPHP_Abstract::disconnect().

Referenced by send().

     {
         $aStreamErrorMessage = $this->_readErrorMessage();
         if (!isset($aErrorMessage) && !isset($aStreamErrorMessage)) {
             return false;
         } else if (isset($aErrorMessage, $aStreamErrorMessage)) {
             if ($aStreamErrorMessage['identifier'] <= $aErrorMessage['identifier']) {
                 $aErrorMessage = $aStreamErrorMessage;
                 unset($aStreamErrorMessage);
             }
         } else if (!isset($aErrorMessage) && isset($aStreamErrorMessage)) {
             $aErrorMessage = $aStreamErrorMessage;
             unset($aStreamErrorMessage);
         }
 
         $this->_log('ERROR: Unable to send message ID ' .
             $aErrorMessage['identifier'] . ': ' .
             $aErrorMessage['statusMessage'] . ' (' . $aErrorMessage['statusCode'] . ').');
 
         $this->disconnect();
 
         foreach($this->_aMessageQueue as $k => &$aMessage) {
             if ($k < $aErrorMessage['identifier']) {
                 unset($this->_aMessageQueue[$k]);
             } else if ($k == $aErrorMessage['identifier']) {
                 $aMessage['ERRORS'][] = $aErrorMessage;
             } else {
                 break;
             }
         }
 
         $this->connect();
 
         return true;
     }

Here is the call graph for this function:

Here is the caller graph for this function:

void add ( ApnsPHP_Message $message )

Adds a message to the message queue.

Parameters

$message The message.

Definition at line 93 of file Push.php.

References _getBinaryNotification(), ApnsPHP_Message::getExpiry(), ApnsPHP_Message::getPayload(), ApnsPHP_Message::getRecipient(), and ApnsPHP_Message::getRecipientsNumber().

     {
         $sMessagePayload = $message->getPayload();
         $nRecipients = $message->getRecipientsNumber();
 
         $nMessageQueueLen = count($this->_aMessageQueue);
         for ($i = 0; $i < $nRecipients; $i++) {
             $nMessageID = $nMessageQueueLen + $i + 1;
             $this->_aMessageQueue[$nMessageID] = array(
                 'MESSAGE' => $message,
                 'BINARY_NOTIFICATION' => $this->_getBinaryNotification(
                     $message->getRecipient($i),
                     $sMessagePayload,
                     $nMessageID,
                     $message->getExpiry()
                 ),
                 'ERRORS' => array()
             );
         }
     }

Here is the call graph for this function:

array getErrors ( boolean $bEmpty = true )

Returns messages not delivered to the end user because one (or more) error occurred.

Parameters

$bEmpty [optional] Empty message container.

Returns: Array of messages not delivered because one or more errors occurred.

Definition at line 240 of file Push.php.

References $_aErrors.

     {
         $aRet = $this->_aErrors;
         if ($bEmpty) {
             $this->_aErrors = array();
         }
         return $aRet;
     }

array getQueue ( boolean $bEmpty = true )

Returns messages in the message queue.

When a message is successful sent or reached the maximum retry time is removed from the message queue and inserted in the Errors container. Use the getErrors() method to retrive messages with delivery error(s).

Parameters

$bEmpty [optional] Empty message queue.

Returns: Array of messages left on the queue.

Definition at line 223 of file Push.php.

References $_aMessageQueue.

     {
         $aRet = $this->_aMessageQueue;
         if ($bEmpty) {
             $this->_aMessageQueue = array();
         }
         return $aRet;
     }

integer getSendRetryTimes ( )

Get the send retry time value.

Returns: Send retry times.

Definition at line 83 of file Push.php.

References $_nSendRetryTimes.

     {
         return $this->_nSendRetryTimes;
     }

void send ( )

Sends all messages in the message queue to Apple Push Notification Service.

Exceptions

ApnsPHP_Push_Exception if not connected to the service or no notification queued.

Definition at line 120 of file Push.php.

References ApnsPHP_Abstract::_log(), _removeMessageFromQueue(), and _updateQueue().

     {
         if (!$this->_hSocket) {
             throw new ApnsPHP_Push_Exception(
                 'Not connected to Push Notification Service'
             );
         }
 
         if (empty($this->_aMessageQueue)) {
             throw new ApnsPHP_Push_Exception(
                 'No notifications queued to be sent'
             );
         }
 
         $this->_aErrors = array();
         $nRun = 1;
         while (($nMessages = count($this->_aMessageQueue)) > 0) {
             $this->_log("INFO: Sending messages queue, run #{$nRun}: $nMessages message(s) left in queue.");
 
             $bError = false;
             foreach($this->_aMessageQueue as $k => &$aMessage) {
                 if (function_exists('pcntl_signal_dispatch')) {
                     pcntl_signal_dispatch();
                 }
 
                 $message = $aMessage['MESSAGE'];
                 $sCustomIdentifier = (string)$message->getCustomIdentifier();
                 $sCustomIdentifier = sprintf('[custom identifier: %s]', empty($sCustomIdentifier) ? 'unset' : $sCustomIdentifier);
 
                 $nErrors = 0;
                 if (!empty($aMessage['ERRORS'])) {
                     foreach($aMessage['ERRORS'] as $aError) {
                         if ($aError['statusCode'] == 0) {
                             $this->_log("INFO: Message ID {$k} {$sCustomIdentifier} has no error ({$aError['statusCode']}), removing from queue...");
                             $this->_removeMessageFromQueue($k);
                             continue 2;
                         } else if ($aError['statusCode'] > 1 && $aError['statusCode'] <= 8) {
                             $this->_log("WARNING: Message ID {$k} {$sCustomIdentifier} has an unrecoverable error ({$aError['statusCode']}), removing from queue without retrying...");
                             $this->_removeMessageFromQueue($k, true);
                             continue 2;
                         }
                     }
                     if (($nErrors = count($aMessage['ERRORS'])) >= $this->_nSendRetryTimes) {
                         $this->_log(
                             "WARNING: Message ID {$k} {$sCustomIdentifier} has {$nErrors} errors, removing from queue..."
                         );
                         $this->_removeMessageFromQueue($k, true);
                         continue;
                     }
                 }
 
                 $nLen = strlen($aMessage['BINARY_NOTIFICATION']);
                 $this->_log("STATUS: Sending message ID {$k} {$sCustomIdentifier} (" . ($nErrors + 1) . "/{$this->_nSendRetryTimes}): {$nLen} bytes.");
 
                 $aErrorMessage = null;
                 if ($nLen !== ($nWritten = (int)@fwrite($this->_hSocket, $aMessage['BINARY_NOTIFICATION']))) {
                     $aErrorMessage = array(
                         'identifier' => $k,
                         'statusCode' => self::STATUS_CODE_INTERNAL_ERROR,
                         'statusMessage' => sprintf('%s (%d bytes written instead of %d bytes)',
                             $this->_aErrorResponseMessages[self::STATUS_CODE_INTERNAL_ERROR], $nWritten, $nLen
                         )
                     );
                 }
                 usleep($this->_nWriteInterval);
 
                 $bError = $this->_updateQueue($aErrorMessage);
                 if ($bError) {
                     break;
                 }
             }
 
             if (!$bError) {
                 $read = array($this->_hSocket);
                 $null = NULL;
                 $nChangedStreams = @stream_select($read, $null, $null, 0, $this->_nSocketSelectTimeout);
                 if ($nChangedStreams === false) {
                     $this->_log('ERROR: Unable to wait for a stream availability.');
                     break;
                 } else if ($nChangedStreams > 0) {
                     $bError = $this->_updateQueue();
                     if (!$bError) {
                         $this->_aMessageQueue = array();
                     }
                 } else {
                     $this->_aMessageQueue = array();
                 }
             }
 
             $nRun++;
         }
     }

Here is the call graph for this function:

void setSendRetryTimes ( integer $nRetryTimes )

Set the send retry times value.

If the client is unable to send a payload to to the server retries at least for this value. The default send retry times is 3.

Parameters

$nRetryTimes Send retry times.

Definition at line 73 of file Push.php.

     {
         $this->_nSendRetryTimes = (int)$nRetryTimes;
     }

Field Documentation

$_aErrorResponseMessages

protected

Initial value:

= array(
        0   => 'No errors encountered',
        1   => 'Processing error',
        2   => 'Missing device token',
        3   => 'Missing topic',
        4   => 'Missing payload',
        5   => 'Invalid token size',
        6   => 'Invalid topic size',
        7   => 'Invalid payload size',
        8   => 'Invalid token',
        self::STATUS_CODE_INTERNAL_ERROR => 'Internal error'
    )

array Error-response messages.

Definition at line 42 of file Push.php.

array $_aErrors = array()

protected

Error container.

Definition at line 63 of file Push.php.

Referenced by getErrors().

array $_aMessageQueue = array()

protected

Message queue.

Definition at line 62 of file Push.php.

Referenced by getQueue().

$_aServiceURLs

protected

Initial value:

= array(
        'tls://gateway.push.apple.com:2195', 
        'tls://gateway.sandbox.push.apple.com:2195' 
    )

array Service URLs environments.

Definition at line 57 of file Push.php.

integer $_nSendRetryTimes = 3

protected

Send retry times.

Definition at line 55 of file Push.php.

Referenced by getSendRetryTimes().

const COMMAND_PUSH = 1

integer Payload command.

Definition at line 35 of file Push.php.

const ERROR_RESPONSE_COMMAND = 8

integer Error-response command code.

Definition at line 38 of file Push.php.

const ERROR_RESPONSE_SIZE = 6

integer Error-response packet size.

Definition at line 37 of file Push.php.

const STATUS_CODE_INTERNAL_ERROR = 999

integer Status code for internal error (not Apple).

Definition at line 40 of file Push.php.

The documentation for this class was generated from the following file:

Push.php

Public Member Functions

Data Fields

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

Field Documentation