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

Source for file Queue.php

Documentation is available at Queue.php

  1. <?php
  2.  
  3. /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
  4.  
  5. /**
  6.  * Contains a class representing a queue in the Amazon Simple Queue
  7.  * Service (SQS)
  8.  *
  9.  * PHP version 5
  10.  *
  11.  * LICENSE:
  12.  *
  13.  * Copyright 2008 Mike Brittain, Amazon.com, silverorange
  14.  *
  15.  * Licensed under the Apache License, Version 2.0 (the "License");
  16.  * you may not use this file except in compliance with the License.
  17.  * You may obtain a copy of the License at
  18.  *
  19.  *   http://www.apache.org/licenses/LICENSE-2.0
  20.  *
  21.  * Unless required by applicable law or agreed to in writing, software
  22.  * distributed under the License is distributed on an "AS IS" BASIS,
  23.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  24.  * See the License for the specific language governing permissions and
  25.  * limitations under the License.
  26.  *
  27.  *   Portions of this code were taken from the Amazon SQS PHP5 Library which
  28.  *   is distributed under the Apache 2.0 license
  29.  *   (http://aws.amazon.com/apache2.0).
  30.  *
  31.  * @category  Services
  32.  * @package   Services_Amazon_SQS
  33.  * @author    Mike Brittain <mike@mikebrittain.com>
  34.  * @author    Michael Gauthier <mike@silverorange.com>
  35.  * @copyright 2008 Mike Brittain, 2008 Amazon.com, 2008 silverorange
  36.  * @license   http://www.apache.org/licenses/LICENSE-2.0 Apache License 2.0
  37.  * @version   CVS: $Id: Queue.php 283528 2009-07-05 18:53:10Z gauthierm $
  38.  * @link      http://pear.php.net/package/Services_Amazon_SQS
  39.  * @link      http://aws.amazon.com/sqs/
  40.  * @link      http://s3.amazonaws.com/awsdocs/SQS/20080101/sqs-dg-20080101.pdf
  41.  */
  42.  
  43. /**
  44.  * Exception classes.
  45.  */
  46. require_once 'Services/Amazon/SQS/Exceptions.php';
  47.  
  48. /**
  49.  * Amazon SQS client base class.
  50.  */
  51. require_once 'Services/Amazon/SQS.php';
  52.  
  53. /**
  54.  * A queue in the Amazon SQS
  55.  *
  56.  * This class allows sending objects to and receiving objects from a queue on
  57.  * the Amazon SQS. Use the queue URL provided by Amazon through the list or
  58.  * creating methods when instantiating this class.
  59.  *
  60.  * @category  Services
  61.  * @package   Services_Amazon_SQS
  62.  * @author    Mike Brittain <mike@mikebrittain.com>
  63.  * @author    Michael Gauthier <mike@silverorange.com>
  64.  * @copyright 2008 Mike Brittain, 2008 Amazon.com, 2008-2009 silverorange
  65.  * @license   http://www.apache.org/licenses/LICENSE-2.0 Apache License 2.0
  66.  * @link      http://pear.php.net/package/Services_Amazon_SQS
  67.  * @link      http://aws.amazon.com/sqs/
  68.  * @link      http://s3.amazonaws.com/awsdocs/SQS/20080101/sqs-dg-20080101.pdf
  69.  */
  70. {
  71.     // {{{ private properties
  72.  
  73.     /**
  74.      * The URL of this queue provided by Amazon when the queue was created
  75.      *
  76.      * @var string 
  77.      */
  78.     private $_queueUrl;
  79.  
  80.     // }}}
  81.     // {{{ __construct()
  82.  
  83.     /**
  84.      * Creates a PHP SQS queue object
  85.      *
  86.      * Queue objects are created with the full URL because Amazon reserves the
  87.      * right to change the URL scheme for queues created in the future. Always
  88.      * use the full queue URL.
  89.      *
  90.      * @param string                             $queueUrl        the URL of
  91.      *         this queue.
  92.      *
  93.      * @param Services_Amazon_SQS_Account|string$accessKey       either a
  94.      *         {@link Services_Amazon_SQS_Account} object or a string containing
  95.      *         the SQS access key for an account.
  96.      *
  97.      * @param string                             $secretAccessKey if the second
  98.      *         parameter is an account object, this parameter is ignored.
  99.      *         Otherwise, this parameter is required and is the secret access
  100.      *         key for the SQS account.
  101.      *
  102.      * @param HTTP_Request2                      $request         optional. The
  103.      *         HTTP request object to use. If not specified, a HTTP request
  104.      *         object is created automatically.
  105.      */
  106.     public function __construct($queueUrl$accessKey$secretAccessKey '',
  107.         HTTP_Request2 $request = null
  108.     {
  109.         parent::__construct($accessKey$secretAccessKey$request);
  110.         $this->_queueUrl $queueUrl;
  111.     }
  112.  
  113.     // }}}
  114.     // {{{ __toString()
  115.  
  116.     /**
  117.      * Gets a string representation of this queue
  118.      *
  119.      * Specifically, this returns the queue URL of this queue.
  120.      *
  121.      * @return string the URL of this queue.
  122.      */
  123.     public function __toString()
  124.     {
  125.         return $this->_queueUrl;
  126.     }
  127.  
  128.     // }}}
  129.     // {{{ send()
  130.  
  131.     /**
  132.      * Sends a message to this queue
  133.      *
  134.      * @param string $message the message to put in this queue.
  135.      *
  136.      * @return string the message id of the message.
  137.      *
  138.      * @throws Services_Amazon_SQS_InvalidMessageException if the message
  139.      *          contains characters outside the allowed set or if the message
  140.      *          size is greater than 8192 bytes.
  141.      *
  142.      * @throws Services_Amazon_SQS_ChecksumException if the received checksum
  143.      *          from Amazon does not match the calculated checksum of the
  144.      *          sent message.
  145.      *
  146.      * @throws Services_Amazon_SQS_InvalidQueueException if this queue does
  147.      *          not exist for the Amazon SQS account.
  148.      *
  149.      * @throws Services_Amazon_SQS_ErrorException if one or more errors are
  150.      *          returned by Amazon.
  151.      *
  152.      * @throws Services_Amazon_SQS_HttpException if the HTTP request fails.
  153.      */
  154.     public function send($message)
  155.     {
  156.         $params = array();
  157.  
  158.         $params['Action']      'SendMessage';
  159.         $params['MessageBody'$message;
  160.  
  161.         try {
  162.             $response $this->sendRequest($params$this->_queueUrl);
  163.         catch (Services_Amazon_SQS_ErrorException $e{
  164.             switch ($e->getError()) {
  165.             case 'InvalidMessageContents':
  166.                 throw new Services_Amazon_SQS_InvalidMessageException(
  167.                     'The message contains characters outside the allowed set.',
  168.                     0,
  169.                     $message
  170.                 );
  171.             case 'MessageTooLong':
  172.                 throw new Services_Amazon_SQS_InvalidMessageException(
  173.                     'The message size can not exceed 8192 bytes.',
  174.                     0,
  175.                     $message
  176.                 );
  177.             case 'InvalidParameterValue':
  178.                 $tooLongMessage 'Value for parameter MessageBody is '
  179.                     . 'invalid. Reason: Message body must be shorter than '
  180.                     . '8192 bytes.';
  181.  
  182.                 if ($e->getMessage(=== $tooLongMessage{
  183.                     throw new Services_Amazon_SQS_InvalidMessageException(
  184.                         'The message size can not exceed 8192 bytes.',
  185.                         0,
  186.                         $message
  187.                     );
  188.                 }
  189.                 throw $e;
  190.             case 'AWS.SimpleQueueService.NonExistentQueue':
  191.                 throw new Services_Amazon_SQS_InvalidQueueException(
  192.                     'The queue "' $this '" does not exist.',
  193.                     0,
  194.                     $this->_queueUrl
  195.                 );
  196.             default:
  197.                 throw $e;
  198.             }
  199.         }
  200.  
  201.         $messages     = array();
  202.         $xpath        $response->getXPath();
  203.         $messageNodes $xpath->query('//sqs:Message');
  204.         $expectedMd5  md5($message);
  205.  
  206.         $id  $xpath->evaluate('string(//sqs:MessageId/text())');
  207.         $md5 $xpath->evaluate('string(//sqs:MD5OfMessageBody/text())');
  208.  
  209.         if ($md5 !== $expectedMd5{
  210.             throw new Services_Amazon_SQS_ChecksumException('Message ' .
  211.                 'body was not received by Amazon correctly. Expected ' .
  212.                 'MD5 was: "' $expectedMd5 '", but received MD5 was: "' .
  213.                 $md5 .'".'0$id);
  214.         }
  215.  
  216.         return $id;
  217.     }
  218.  
  219.     // }}}
  220.     // {{{ receive()
  221.  
  222.     /**
  223.      * Retrieves one or more messages from this queue
  224.      *
  225.      * Retrieved messages are made invisible to subsequent requests for the
  226.      * duration of the visibility timeout. To permanently remove a message from
  227.      * this queue, first retrieve the message and them delete it using the
  228.      * {@link Services_Amazon_SQS_Queue::delete()} method.
  229.      *
  230.      * @param integer $count   optional. The number of messages to retrieve from
  231.      *                          the queue. If not specified, one message is
  232.      *                          retrieved. At most, ten messages may be
  233.      *                          retrieved.
  234.      * @param integer $timeout optional. The number of seconds that retrieved
  235.      *                          messages should be hidden from view in the queue.
  236.      *                          If not specified, the default visibility timeout
  237.      *                          of this queue is used.
  238.      *
  239.      * @return array an array containing one or more retrieved messages. Each
  240.      *                message in the returned array is represented as an
  241.      *                associative array with the following keys:
  242.      *                - <kbd>id</kbd>     - the message id.
  243.      *                - <kbd>body</kbd>   - the body of the message.
  244.      *                - <kbd>handle</kbd> - the receipt handle of the message.
  245.      *
  246.      * @throws Services_Amazon_SQS_InvalidTimeoutException if the provided
  247.      *          <kbd>$timeout</kbd> is not in the valid range.
  248.      *
  249.      * @throws Services_Amazon_SQS_InvalidQueueException if this queue does
  250.      *          not exist for the Amazon SQS account.
  251.      *
  252.      * @throws Services_Amazon_SQS_ErrorException if one or more errors are
  253.      *          returned by Amazon.
  254.      *
  255.      * @throws Services_Amazon_SQS_HttpException if the HTTP request fails.
  256.      *
  257.      * @see Services_Amazon_SQS_Queue::changeMessageVisibility()
  258.      */
  259.     public function receive($count = 1$timeout = null)
  260.     {
  261.         if ($timeout !== null && !$this->isValidVisibilityTimeout($timeout)) {
  262.             throw new Services_Amazon_SQS_InvalidTimeoutException('The ' .
  263.                 'specified timeout falls outside the allowable range (0-7200)',
  264.                 0$timeout);
  265.         }
  266.  
  267.         // normalize count if it's outside of Amazon's constraints
  268.         $count max($count1);
  269.         $count min($count10);
  270.  
  271.         $params = array();
  272.  
  273.         $params['Action']              'ReceiveMessage';
  274.         $params['MaxNumberOfMessages'$count;
  275.  
  276.         if ($timeout{
  277.             $params['VisibilityTimeout'$timeout;
  278.         }
  279.  
  280.         try {
  281.             $response $this->sendRequest($params$this->_queueUrl);
  282.         catch (Services_Amazon_SQS_ErrorException $e{
  283.             switch ($e->getError()) {
  284.             case 'AWS.SimpleQueueService.NonExistentQueue':
  285.                 throw new Services_Amazon_SQS_InvalidQueueException('The ' .
  286.                     'queue "' $this '" does not exist.'0,
  287.                     $this->_queueUrl);
  288.  
  289.             default:
  290.                 throw $e;
  291.             }
  292.         }
  293.  
  294.         // get messages from response
  295.         $messages = array();
  296.         $xpath    $response->getXPath();
  297.         $nodes    $xpath->query('//sqs:Message');
  298.  
  299.         foreach ($nodes as $node{
  300.             $id     $xpath->evaluate('string(sqs:MessageId/text())'$node);
  301.             $handle $xpath->evaluate('string(sqs:ReceiptHandle/text())'$node);
  302.             $body   $xpath->evaluate('string(sqs:Body/text())'$node);
  303.  
  304.             $message           = array();
  305.             $message['id']     $id;
  306.             $message['body']   $body;
  307.             $message['handle'$handle;
  308.  
  309.             $messages[$message;
  310.         }
  311.  
  312.         return $messages;
  313.     }
  314.  
  315.     // }}}
  316.     // {{{ delete()
  317.  
  318.     /**
  319.      * Deletes a message from this queue
  320.      *
  321.      * @param string $handle the receipt handle of the message to delete.
  322.      *
  323.      * @return void 
  324.      *
  325.      * @throws Services_Amazon_SQS_InvalidQueueException if this queue does
  326.      *          not exist for the Amazon SQS account.
  327.      *
  328.      * @throws Services_Amazon_SQS_ErrorException if one or more errors are
  329.      *          returned by Amazon.
  330.      *
  331.      * @throws Services_Amazon_SQS_HttpException if the HTTP request fails.
  332.      */
  333.     public function delete($handle)
  334.     {
  335.         $params = array();
  336.  
  337.         $params['Action']        'DeleteMessage';
  338.         $params['ReceiptHandle'$handle;
  339.  
  340.         try {
  341.             $this->sendRequest($params$this->_queueUrl);
  342.         catch (Services_Amazon_SQS_ErrorException $e{
  343.             switch ($e->getError()) {
  344.             case 'AWS.SimpleQueueService.NonExistentQueue':
  345.                 throw new Services_Amazon_SQS_InvalidQueueException('The ' .
  346.                     'queue "' $this '" does not exist.'0,
  347.                     $this->_queueUrl);
  348.  
  349.             default:
  350.                 throw $e;
  351.             }
  352.         }
  353.     }
  354.  
  355.     // }}}
  356.     // {{{ changeMessageVisibility()
  357.  
  358.     /**
  359.      * Changes the visibility timeout for a message in this queue
  360.      *
  361.      * Once a message is received, it is invisible to the queue for the
  362.      * duration of the visibility timeout. After receiving the message, the
  363.      * visibility timeout may be increased if the queue operation will take
  364.      * longer than the default visibility timeout.
  365.      *
  366.      * Message visibility may be changed multiple times, but a single received
  367.      * message can not have a total visibility timeout period exceeding 12
  368.      * hours.
  369.      *
  370.      * Example usage:
  371.      * <code>
  372.      * <?php
  373.      * // receive a message with a 10 second visibility timeout
  374.      * $message = $queue->receive(1, 10);
  375.      * // check if processing the message will take longer than ten seconds
  376.      * if ($message['body'] == 'this will take a long time') {
  377.      *    // if so, add five minutes to the visibility timeout
  378.      *    $queue->changeMessageVisibility($message['handle'], 300);
  379.      * }
  380.      * // now process the message
  381.      * ?>
  382.      * </code>
  383.      *
  384.      * @param string  $handle  the receipt handle of the message to update.
  385.      * @param integer $timeout the new visibility timeout for the message.
  386.      *
  387.      * @return void 
  388.      *
  389.      * @throws Services_Amazon_SQS_InvalidTimeoutException if the provided
  390.      *          <kbd>$timeout</kbd> is not in the valid range for the given
  391.      *          message.
  392.      *
  393.      * @throws Services_Amazon_SQS_InvalidQueueException if this queue does
  394.      *          not exist for the Amazon SQS account.
  395.      *
  396.      * @throws Services_Amazon_SQS_ErrorException if one or more errors are
  397.      *          returned by Amazon.
  398.      *
  399.      * @throws Services_Amazon_SQS_HttpException if the HTTP request fails.
  400.      */
  401.     public function changeMessageVisibility($handle$timeout)
  402.     {
  403.         $params = array();
  404.  
  405.         $params['Action']            'ChangeMessageVisibility';
  406.         $params['ReceiptHandle']     $handle;
  407.         $params['VisibilityTimeout'$timeout;
  408.  
  409.         try {
  410.             $this->sendRequest($params$this->_queueUrl);
  411.         catch (Services_Amazon_SQS_ErrorException $e{
  412.             switch ($e->getError()) {
  413.             case 'AWS.SimpleQueueService.NonExistentQueue':
  414.                 throw new Services_Amazon_SQS_InvalidQueueException('The ' .
  415.                     'queue "' $this '" does not exist.'0,
  416.                     $this->_queueUrl);
  417.  
  418.             case 'InvalidParameterValue':
  419.                 $exp '/^Value .*? for parameter VisibilityTimeout is ' .
  420.                     'invalid\. Reason: VisibilityTimeout must be an integer ' .
  421.                     'between 0 and 43200\.$/';
  422.  
  423.                 if (preg_match($exp$e->getMessage()) === 1{
  424.                    throw new Services_Amazon_SQS_InvalidTimeoutException(
  425.                         'The timeout "' $timeout '" is not valid for ' .
  426.                         'the specified message.',
  427.                         0,
  428.                         $timeout
  429.                     );
  430.                 }
  431.  
  432.                 throw $e;
  433.  
  434.             default:
  435.                 throw $e;
  436.             }
  437.         }
  438.     }
  439.  
  440.     // }}}
  441.     // {{{ getAttributes()
  442.  
  443.     /**
  444.      * Gets an associative array of one or more attributes of this queue
  445.      *
  446.      * Currently, Amazon SQS only allows retrieving the values of the
  447.      * following attributes:
  448.      *
  449.      * - <kbd>ApproximateNumberOfMessages</kbd> - an approximation of the number
  450.      * - <kbd>CreatedTimestamp</kbd>            - the date this queue was
  451.      *                                            created.
  452.      * - <kbd>LastModifiedTimestamp</kbd>       - the date this queue was
  453.      *                                            last modified.
  454.      * - <kbd>VisibilityTimeout</kbd>           - the default time period for
  455.      *                                            which messages are made
  456.      *                                            invisible when retrieved from
  457.      *                                            this queue.
  458.      *
  459.      * Timestamp values are formatted as Unix timestamps.
  460.      *
  461.      * Additionally, the special attribute <kbd>All</kbd> may be used to
  462.      * retrieve all available attributes.
  463.      *
  464.      * @param string|array$name optional. The name or names of the attribute
  465.      *                            values to get or <kbd>All</kbd> to get all
  466.      *                            available attributes. If not specified,
  467.      *                            <i><kbd>All</kdb></i> is used. Multiple
  468.      *                            specific attributes may be retrieved using an
  469.      *                            array of attribute names.
  470.      *
  471.      * @return array an associative array of available attributes. The attribute
  472.      *                name is the array key and the attribute value is the
  473.      *                array value.
  474.      *
  475.      * @throws Services_Amazon_SQS_InvalidAttributeException if an invalid
  476.      *          attribute name is requested.
  477.      *
  478.      * @throws Services_Amazon_SQS_InvalidQueueException if this queue does
  479.      *          not exist for the Amazon SQS account.
  480.      *
  481.      * @throws Services_Amazon_SQS_ErrorException if one or more errors are
  482.      *          returned by Amazon.
  483.      *
  484.      * @throws Services_Amazon_SQS_HttpException if the HTTP request fails.
  485.      */
  486.     public function getAttributes($name 'All')
  487.     {
  488.         $params = array('Action' => 'GetQueueAttributes');
  489.  
  490.         if (!is_array($name)) {
  491.             $name = array($name);
  492.         }
  493.  
  494.         $count count($name);
  495.  
  496.         if ($count === 1{
  497.             $params['AttributeName'reset($name);
  498.         elseif ($count > 1{
  499.             $count = 1;
  500.             foreach ($name as $attributeName{
  501.                 $params['AttributeName.' $count$attributeName;
  502.                 $count++;
  503.             }
  504.         }
  505.  
  506.         try {
  507.             $response $this->sendRequest($params$this->_queueUrl);
  508.         catch (Services_Amazon_SQS_ErrorException $e{
  509.             switch ($e->getError()) {
  510.             case 'InvalidAttributeName':
  511.                 throw new Services_Amazon_SQS_InvalidAttributeException('The ' .
  512.                     'attribute name "' $name '" is not a valid attribute ' .
  513.                     'name.'0$name);
  514.  
  515.             case 'AWS.SimpleQueueService.NonExistentQueue':
  516.                 throw new Services_Amazon_SQS_InvalidQueueException('The ' .
  517.                     'queue "' $this '" does not exist.'0,
  518.                     $this->_queueUrl);
  519.  
  520.             default:
  521.                 throw $e;
  522.             }
  523.         }
  524.  
  525.         $attributes = array();
  526.         $xpath      $response->getXPath();
  527.         $nodes      $xpath->query('//sqs:Attribute');
  528.  
  529.         foreach ($nodes as $node{
  530.             $name  $xpath->evaluate('string(sqs:Name/text())'$node);
  531.             $value $xpath->evaluate('string(sqs:Value/text())'$node);
  532.  
  533.             $attributes[$name$value;
  534.         }
  535.  
  536.         return $attributes;
  537.     }
  538.  
  539.     // }}}
  540.     // {{{ setAttribute()
  541.  
  542.     /**
  543.      * Sets an attribute of this queue
  544.      *
  545.      * Currently, Amazon SQS only allows setting the
  546.      * <kbd>VisibilityTimeout</kbd> attribute. This attribute sets the default
  547.      * time period for which messages are made invisible when retrieved from
  548.      * this queue.
  549.      *
  550.      * @param string $name  the attribute name.
  551.      * @param mixed  $value the attribute value.
  552.      *
  553.      * @return void 
  554.      *
  555.      * @throws Services_Amazon_SQS_InvalidAttributeException if an invalid
  556.      *          attribute name is set.
  557.      *
  558.      * @throws Services_Amazon_SQS_InvalidQueueException if this queue does
  559.      *          not exist for the Amazon SQS account.
  560.      *
  561.      * @throws Services_Amazon_SQS_ErrorException if one or more errors are
  562.      *          returned by Amazon.
  563.      *
  564.      * @throws Services_Amazon_SQS_HttpException if the HTTP request fails.
  565.      */
  566.     public function setAttribute($name$value)
  567.     {
  568.         $params = array();
  569.  
  570.         $params['Action']          'SetQueueAttributes';
  571.         $params['Attribute.Name']  $name;
  572.         $params['Attribute.Value'$value;
  573.  
  574.         try {
  575.             $response $this->sendRequest($params$this->_queueUrl);
  576.         catch (Services_Amazon_SQS_ErrorException $e{
  577.             switch ($e->getError()) {
  578.             case 'InvalidAttributeName':
  579.                 throw new Services_Amazon_SQS_InvalidAttributeException('The ' .
  580.                     'attribute name "' $name '" is not a valid attribute ' .
  581.                     'name.'0$name);
  582.  
  583.             case 'AWS.SimpleQueueService.NonExistentQueue':
  584.                 throw new Services_Amazon_SQS_InvalidQueueException('The ' .
  585.                     'queue "' $this '" does not exist.'0,
  586.                     $this->_queueUrl);
  587.  
  588.             default:
  589.                 throw $e;
  590.             }
  591.         }
  592.     }
  593.  
  594.     // }}}
  595.     // {{{ addPermission()
  596.  
  597.     /**
  598.      * Adds a permission to this queue for a specific principal
  599.      *
  600.      * Permissions that may be granted on this queue are:
  601.      *
  602.      * - <kbd>*</kbd> (all permissions)
  603.      * - <kbd>SendMessage</kbd>
  604.      * - <kbd>ReceiveMessage</kbd>
  605.      * - <kbd>DeleteMessage</kbd>
  606.      * - <kbd>ChangeMessageVisibility</kbd>
  607.      * - <kbd>GetQueueAttributes</kbd>
  608.      *
  609.      * Example use:
  610.      * <code>
  611.      * <?php
  612.      * $queue->addPermission(
  613.      *     'billing-read-only',
  614.      *     array(
  615.      *         array(
  616.      *             'account'   => '123456789012',
  617.      *             'permission => 'ReceiveMessage'
  618.      *         ),
  619.      *         array(
  620.      *             'account'   => '123456789012',
  621.      *             'permission => 'GetQueueAttributes'
  622.      *         ),
  623.      *     )
  624.      * );
  625.      * ?>
  626.      * </code>
  627.      *
  628.      * @param string $label      a unique identifier for this permission. This
  629.      *                            label can be used to revoke the permission at
  630.      *                            a later date.
  631.      * @param array  $principals an array of principals receiving the
  632.      *                            permission. Each array element is a
  633.      *                            separate array containing the following keys:
  634.      *                            - <kbd>account</kbd>    - the id of the AWS
  635.      *                                                      account which will
  636.      *                                                      receive the
  637.      *                                                      permission. This is
  638.      *                                                      <em>not</em> an
  639.      *                                                      AWS key id.
  640.      *                            - <kbd>permission</kbd> - the permission to
  641.      *                                                      grant.
  642.      *
  643.      * @return void 
  644.      *
  645.      * @throws InvalidArgumentException if no principals are specified, or if
  646.      *          the specified principals do not contain the <kbd>account</kbd>
  647.      *          and <kbd>permission</kbd> fields.
  648.      *
  649.      * @throws Services_Amazon_SQS_InvalidPermissionLabelException if the
  650.      *          specified permission label is not valid.
  651.      *
  652.      * @throws Services_Amazon_SQS_InvalidQueueException if this queue does
  653.      *          not exist for the Amazon SQS account.
  654.      *
  655.      * @throws Services_Amazon_SQS_ErrorException if one or more errors are
  656.      *          returned by Amazon.
  657.      *
  658.      * @throws Services_Amazon_SQS_HttpException if the HTTP request fails.
  659.      *
  660.      * @see Services_Amazon_SQS_Queue::removePermission()
  661.      */
  662.     public function addPermission($labelarray $principals)
  663.     {
  664.         if (!$this->isValidPermissionLabel($label)) {
  665.             throw new Services_Amazon_SQS_InvalidPermissionLabelException(
  666.                 'The permission label "' $label '" is not a valid ' .
  667.                 'permission label. Permission labels must be 1-80 ' .
  668.                 'characters long and must consist only of alphanumeric ' .
  669.                 'characters, dashes or underscores.',
  670.                 0,
  671.                 $label
  672.             );
  673.         }
  674.  
  675.         // validate principals
  676.         if (count($principals=== 0{
  677.             throw new InvalidArgumentException(
  678.                 'At least one principal must be specified.'
  679.             );
  680.         }
  681.         foreach ($principals as $principal{
  682.             if (   !is_array($principal)
  683.                 || !array_key_exists('account'$principal)
  684.                 || !array_key_exists('permission'$principal)
  685.             {
  686.                 throw new InvalidArgumentException(
  687.                     'Each principal must be specified as an associative ' .
  688.                     'array with the following keys: "account", and ' .
  689.                     '"permission".'
  690.                 );
  691.             }
  692.         }
  693.  
  694.         $params = array();
  695.  
  696.         $params['Action''AddPermission';
  697.         $params['Label']  $label;
  698.  
  699.         if (count($principals=== 1{
  700.             $principal reset($principals);
  701.             $params['AWSAccountId'$principal['account'];
  702.             $params['ActionName']   $principal['permission'];
  703.         else {
  704.             $count = 1;
  705.             foreach ($principals as $principal{
  706.                 $params['AWSAccountId.' $count$principal['account'];
  707.                 $params['ActionName.' $count]   $principal['permission'];
  708.                 $count++;
  709.             }
  710.         }
  711.  
  712.         try {
  713.             $this->sendRequest($params$this->_queueUrl);
  714.         catch (Services_Amazon_SQS_ErrorException $e{
  715.             switch ($e->getError()) {
  716.             case 'AWS.SimpleQueueService.NonExistentQueue':
  717.                 throw new Services_Amazon_SQS_InvalidQueueException('The ' .
  718.                     'queue "' $this '" does not exist.'0,
  719.                     $this->_queueUrl);
  720.  
  721.             case 'InvalidParameterValue':
  722.                 $exp '/^Value .*? for parameter Label is invalid\. ' .
  723.                     'Reason: Already exists\.\.$/';
  724.  
  725.                 if (preg_match($exp$e->getMessage()) === 1{
  726.                     throw new Services_Amazon_SQS_InvalidPermissionLabelException(
  727.                         'Permission label "' $label '" is already used ' .
  728.                         'for another permission. A different label must be ' .
  729.                         'used for this permission.',
  730.                         0,
  731.                         $label
  732.                     );
  733.                 }
  734.  
  735.                 throw $e;
  736.  
  737.             default:
  738.                 throw $e;
  739.             }
  740.         }
  741.     }
  742.  
  743.     // }}}
  744.     // {{{ removePermission()
  745.  
  746.     /**
  747.      * Removes a permission from this queue by the permission's label
  748.      *
  749.      * Example use:
  750.      * <code>
  751.      * <?php
  752.      * $queue->removePermission('billing-read-only');
  753.      * ?>
  754.      * </code>
  755.      *
  756.      * @param string $label the unique identifier of the permission to remove.
  757.      *                       This should be the same label used when the
  758.      *                       permission was added.
  759.      *
  760.      * @return void 
  761.      *
  762.      * @throws Services_Amazon_SQS_InvalidPermissionLabelException if the
  763.      *          specified permission label is not valid.
  764.      *
  765.      * @throws Services_Amazon_SQS_InvalidQueueException if this queue does
  766.      *          not exist for the Amazon SQS account.
  767.      *
  768.      * @throws Services_Amazon_SQS_ErrorException if one or more errors are
  769.      *          returned by Amazon.
  770.      *
  771.      * @throws Services_Amazon_SQS_HttpException if the HTTP request fails.
  772.      *
  773.      * @see Services_Amazon_SQS_Queue::addPermission()
  774.      */
  775.     public function removePermission($label)
  776.     {
  777.         if (!$this->isValidPermissionLabel($label)) {
  778.             throw new Services_Amazon_SQS_InvalidPermissionLabelException(
  779.                 'The permission label "' $label '" is not a valid ' .
  780.                 'permission label. Permission labels must be 1-80 ' .
  781.                 'characters long and must consist only of alphanumeric ' .
  782.                 'characters, dashes or underscores.',
  783.                 0,
  784.                 $label
  785.             );
  786.         }
  787.  
  788.         $params = array();
  789.  
  790.         $params['Action''RemovePermission';
  791.         $params['Label']  $label;
  792.  
  793.         try {
  794.             $this->sendRequest($params$this->_queueUrl);
  795.         catch (Services_Amazon_SQS_ErrorException $e{
  796.             switch ($e->getError()) {
  797.             case 'AWS.SimpleQueueService.NonExistentQueue':
  798.                 throw new Services_Amazon_SQS_InvalidQueueException('The ' .
  799.                     'queue "' $this '" does not exist.'0,
  800.                     $this->_queueUrl);
  801.  
  802.             case 'InvalidParameterValue':
  803.                 $exp '/^Value .*? for parameter Label is invalid\. ' .
  804.                     'Reason: Does not exist\.\.$/';
  805.  
  806.                 if (preg_match($exp$e->getMessage()) === 1{
  807.                     throw new Services_Amazon_SQS_InvalidPermissionLabelException(
  808.                         'Permission label "' $label '" does not exist ' .
  809.                         'for this queue and cannot be removed.',
  810.                         0,
  811.                         $label
  812.                     );
  813.                 }
  814.  
  815.                 throw $e;
  816.  
  817.             default:
  818.                 throw $e;
  819.             }
  820.         }
  821.     }
  822.  
  823.     // }}}
  824. }
  825.  
  826. ?>

Documentation generated on Tue, 24 Nov 2009 17:00:04 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.