Services_Amazon_SQS
[ class tree: Services_Amazon_SQS ] [ index: Services_Amazon_SQS ] [ all elements ]
Packages:
Services_Amazon_SQS


Classes:
Services_Amazon_SQS
Services_Amazon_SQS_Account
Services_Amazon_SQS_ChecksumException
Services_Amazon_SQS_CLI
Services_Amazon_SQS_ErrorException
Services_Amazon_SQS_Exception
Services_Amazon_SQS_HttpException
Services_Amazon_SQS_InvalidAttributeException
Services_Amazon_SQS_InvalidMessageException
Services_Amazon_SQS_InvalidPermissionLabelException
Services_Amazon_SQS_InvalidQueueException
Services_Amazon_SQS_InvalidTimeoutException
Services_Amazon_SQS_Queue
Services_Amazon_SQS_QueueManager
Services_Amazon_SQS_Response
Files:
Account.php
CLI.php
Exceptions.php
Queue.php
QueueManager.php
Response.php
SQS.php

Class: Services_Amazon_SQS_Queue

Source Location: /Services_Amazon_SQS-0.3.0/Services/Amazon/SQS/Queue.php

Class Overview

Services_Amazon_SQS
   |
   --Services_Amazon_SQS_Queue

A queue in the Amazon SQS


Author(s):

Copyright:

  • 2008 Mike Brittain, 2008 Amazon.com, 2008-2009 silverorange

Methods

Inherited Variables

Class: Services_Amazon_SQS

Services_Amazon_SQS::$account
Services_Amazon_SQS::$maximumRetries
Services_Amazon_SQS::$request

Inherited Methods

Class: Services_Amazon_SQS

Services_Amazon_SQS::__construct()
Creates a new SQS client
Services_Amazon_SQS::addRequiredParameters()
Adds required authentication and version parameters to an array of parameters
Services_Amazon_SQS::getRequestBackoffTime()
Gets the number of milliseconds to wait before the next reqeust when performing exponential backoff
Services_Amazon_SQS::isValidPermissionLabel()
Gets whether or not a permission label is valid
Services_Amazon_SQS::isValidVisibilityTimeout()
Gets whether or not a visibility timeout is valid
Services_Amazon_SQS::sendRequest()
Sends a HTTP request to the queue service
Services_Amazon_SQS::setMaximumRetries()
Sets the maximum number of retries to make when encountering internal errors on SQS
Services_Amazon_SQS::setRequest()
Sets the HTTP request object to use
Services_Amazon_SQS::signParameters()
Signs an array of request parameters using the Amazon Web Services Signature Version 2 signing method

Class Details

[line 70]
A queue in the Amazon SQS

This class allows sending objects to and receiving objects from a queue on the Amazon SQS. Use the queue URL provided by Amazon through the list or creating methods when instantiating this class.



[ Top ]

Method Detail

__construct (Constructor)   [line 107]

Services_Amazon_SQS_Queue __construct( string $queueUrl, Services_Amazon_SQS_Account|string $accessKey, [string $secretAccessKey = ''], [HTTP_Request2 $request = null])

Creates a PHP SQS queue object

Queue objects are created with the full URL because Amazon reserves the right to change the URL scheme for queues created in the future. Always use the full queue URL.

  • Access: public

Overrides Services_Amazon_SQS::__construct() (Creates a new SQS client)

Parameters:

string   $queueUrl   —  the URL of this queue.
Services_Amazon_SQS_Account|string   $accessKey   —  either a Services_Amazon_SQS_Account object or a string containing the SQS access key for an account.
string   $secretAccessKey   —  if the second parameter is an account object, this parameter is ignored. Otherwise, this parameter is required and is the secret access key for the SQS account.
HTTP_Request2   $request   —  optional. The HTTP request object to use. If not specified, a HTTP request object is created automatically.

[ Top ]

addPermission   [line 663]

void addPermission( string $label, array $principals)

Adds a permission to this queue for a specific principal

Permissions that may be granted on this queue are:

  • * (all permissions)
  • SendMessage
  • ReceiveMessage
  • DeleteMessage
  • ChangeMessageVisibility
  • GetQueueAttributes
Example use: 
  1.  <?php
    2. 

  2.  $queue->addPermission(
    3. 

  3.      'billing-read-only',
    4. 

  4.      array(
    5. 

  5.          array(
    6. 

  6.              'account'   => '123456789012',
    7. 

  7.              'permission => 'ReceiveMessage'
    8. 

  8.          ),
    9. 

  9.          array(
    10. 

  10.              'account'   => '123456789012',
    11. 

  11.              'permission => 'GetQueueAttributes'
    12. 

  12.          ),
    13. 

  13.      )
    14. 

  14.  );
    15. 

  15.  ?>
    16.

  • See: Services_Amazon_SQS_Queue::removePermission()
  • Throws: InvalidArgumentException if no principals are specified, or if the specified principals do not contain the account and permission fields.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_InvalidPermissionLabelException if the specified permission label is not valid.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string   $label   —  a unique identifier for this permission. This label can be used to revoke the permission at a later date.
array   $principals   —  an array of principals receiving the permission. Each array element is a separate array containing the following keys:
  • account - the id of the AWS account which will receive the permission. This is <em>not</em> an AWS key id.
  • permission - the permission to grant.

[ Top ]

changeMessageVisibility   [line 402]

void changeMessageVisibility( string $handle, integer $timeout)

Changes the visibility timeout for a message in this queue

Once a message is received, it is invisible to the queue for the duration of the visibility timeout. After receiving the message, the visibility timeout may be increased if the queue operation will take longer than the default visibility timeout.

Message visibility may be changed multiple times, but a single received message can not have a total visibility timeout period exceeding 12 hours.

Example usage: 

  1.  <?php
    2. 

  2.  // receive a message with a 10 second visibility timeout
    3. 

  3.  $message = $queue->receive(1, 10);
    4. 

  4.  // check if processing the message will take longer than ten seconds
    5. 

  5.  if ($message['body'] == 'this will take a long time') {
    6. 

  6.     // if so, add five minutes to the visibility timeout
    7. 

  7.     $queue->changeMessageVisibility($message['handle'], 300);
    8. 

  8.  }
    9. 

  9.  // now process the message
    10. 

  10.  ?>
    11.

  • Throws: Services_Amazon_SQS_InvalidTimeoutException if the provided $timeout is not in the valid range for the given message.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string   $handle   —  the receipt handle of the message to update.
integer   $timeout   —  the new visibility timeout for the message.

[ Top ]

delete   [line 334]

void delete( string $handle)

Deletes a message from this queue
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Access: public

Parameters:

string   $handle   —  the receipt handle of the message to delete.

[ Top ]

getAttributes   [line 487]

array getAttributes( [string|array $name = 'All'])

Gets an associative array of one or more attributes of this queue

Currently, Amazon SQS only allows retrieving the values of the following attributes:

  • ApproximateNumberOfMessages - an approximation of the number
  • CreatedTimestamp - the date this queue was created.
  • LastModifiedTimestamp - the date this queue was last modified.
  • VisibilityTimeout - the default time period for which messages are made invisible when retrieved from this queue.
Timestamp values are formatted as Unix timestamps.

Additionally, the special attribute All may be used to retrieve all available attributes.

  • Return: an associative array of available attributes. The attribute name is the array key and the attribute value is the array value.
  • Throws: Services_Amazon_SQS_InvalidAttributeException if an invalid attribute name is requested.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string|array   $name   —  optional. The name or names of the attribute values to get or All to get all available attributes. If not specified, <kbd>All</kdb> is used. Multiple specific attributes may be retrieved using an array of attribute names.

[ Top ]

receive   [line 260]

array receive( [integer $count = 1], [integer $timeout = null])

Retrieves one or more messages from this queue

Retrieved messages are made invisible to subsequent requests for the duration of the visibility timeout. To permanently remove a message from this queue, first retrieve the message and them delete it using the Services_Amazon_SQS_Queue::delete() method.

  • Return: an array containing one or more retrieved messages. Each message in the returned array is represented as an associative array with the following keys:
    • id - the message id.
    • body - the body of the message.
    • handle - the receipt handle of the message.
  • See: Services_Amazon_SQS_Queue::changeMessageVisibility()
  • Throws: Services_Amazon_SQS_InvalidTimeoutException if the provided $timeout is not in the valid range.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

integer   $count   —  optional. The number of messages to retrieve from the queue. If not specified, one message is retrieved. At most, ten messages may be retrieved.
integer   $timeout   —  optional. The number of seconds that retrieved messages should be hidden from view in the queue. If not specified, the default visibility timeout of this queue is used.

[ Top ]

removePermission   [line 776]

void removePermission( string $label)

Removes a permission from this queue by the permission's label

Example use: 

  1.  <?php
    2. 

  2.  $queue->removePermission('billing-read-only');
    3. 

  3.  ?>
    4.

  • See: Services_Amazon_SQS_Queue::addPermission()
  • Throws: Services_Amazon_SQS_InvalidPermissionLabelException if the specified permission label is not valid.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string   $label   —  the unique identifier of the permission to remove. This should be the same label used when the permission was added.

[ Top ]

send   [line 155]

string send( string $message)

Sends a message to this queue
  • Return: the message id of the message.
  • Throws: Services_Amazon_SQS_InvalidMessageException if the message contains characters outside the allowed set or if the message size is greater than 8192 bytes.
  • Throws: Services_Amazon_SQS_ChecksumException if the received checksum from Amazon does not match the calculated checksum of the sent message.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string   $message   —  the message to put in this queue.

[ Top ]

setAttribute   [line 567]

void setAttribute( string $name, mixed $value)

Sets an attribute of this queue

Currently, Amazon SQS only allows setting the VisibilityTimeout attribute. This attribute sets the default time period for which messages are made invisible when retrieved from this queue.

  • Throws: Services_Amazon_SQS_InvalidAttributeException if an invalid attribute name is set.
  • Throws: Services_Amazon_SQS_HttpException if the HTTP request fails.
  • Throws: Services_Amazon_SQS_InvalidQueueException if this queue does not exist for the Amazon SQS account.
  • Throws: Services_Amazon_SQS_ErrorException if one or more errors are returned by Amazon.
  • Access: public

Parameters:

string   $name   —  the attribute name.
mixed   $value   —  the attribute value.

[ Top ]

__toString   [line 124]

string __toString( )

Gets a string representation of this queue

Specifically, this returns the queue URL of this queue.

  • Return: the URL of this queue.
  • Access: public

[ Top ]
Documentation generated on Mon, 11 Mar 2019 15:35:28 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.