documentation/manual/en/module_specs/Zend_Service_Amazon_Sqs.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.amazon.sqs">
   4     <title>Zend_Service_Amazon_Sqs</title>
   5
   6     <sect2 id="zend.service.amazon.sqs.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <ulink url="http://aws.amazon.com/sqs/">Amazon Simple Queue Service
  11                 (Amazon SQS)</ulink> offers a reliable, highly scalable, hosted
  12             queue for storing messages as they travel between computers. By
  13             using Amazon SQS, developers can simply move data between
  14             distributed components of their applications that perform different
  15             tasks, without losing messages or requiring each component to be
  16             always available. Amazon SQS makes it easy to build an automated
  17             workflow, working in close conjunction with the Amazon Elastic
  18             Compute Cloud (Amazon EC2) and the other <acronym>AWS</acronym> infrastructure web
  19             services.
  20         </para>
  21
  22         <para>
  23             Amazon SQS works by exposing Amazon's web-scale messaging
  24             infrastructure as a web service. Any computer on the Internet can
  25             add or read messages without any installed software or special
  26             firewall configurations. Components of applications using Amazon SQS
  27             can run independently, and do not need to be on the same network,
  28             developed with the same technologies, or running at the same time.
  29         </para>
  30     </sect2>
  31
  32     <sect2 id="zend.service.amazon.sqs.registering">
  33         <title>Registering with Amazon SQS</title>
  34
  35         <para>
  36             Before you can get started with
  37             <classname>Zend_Service_Amazon_Sqs</classname>, you must first
  38             register for an account. Please see the <ulink
  39                 url="http://aws.amazon.com/sqs/faqs/">SQS FAQ</ulink> page on
  40             the Amazon website for more information.
  41         </para>
  42
  43         <para>
  44             After registering, you will receive an application key and a secret key.
  45             You will need both to access the SQS service.
  46         </para>
  47     </sect2>
  48
  49     <sect2 id="zend.service.amazon.sqs.apiDocumentation">
  50         <title>API Documentation</title>
  51
  52         <para>
  53             The <classname>Zend_Service_Amazon_Sqs</classname> class provides
  54             the <acronym>PHP</acronym> wrapper to the Amazon SQS REST interface. Please consult the
  55             <ulink
  56                 url="http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=31">Amazon
  57                 SQS documentation</ulink> for detailed description of the
  58             service. You will need to be familiar with basic concepts in order
  59             to use this service.
  60         </para>
  61     </sect2>
  62
  63     <sect2 id="zend.service.amazon.sqs.features">
  64         <title>Features</title>
  65
  66         <para>
  67             <classname>Zend_Service_Amazon_Sqs</classname> provides the
  68             following functionality:
  69         </para>
  70
  71         <itemizedlist>
  72             <listitem>
  73                 <para>
  74                     A single point for configuring your amazon.sqs
  75                     authentication credentials that can be used across the
  76                     amazon.sqs namespaces.
  77                 </para>
  78             </listitem>
  79
  80             <listitem>
  81                 <para>
  82                     A proxy object that is more convenient to use than an <acronym>HTTP</acronym>
  83                     client alone, mostly removing the need to manually construct
  84                     <acronym>HTTP</acronym> POST requests to access the REST service.
  85                 </para>
  86             </listitem>
  87
  88             <listitem>
  89                 <para>
  90                     A response wrapper that parses each response body and throws
  91                     an exception if an error occurred, alleviating the need to
  92                     repeatedly check the success of many commands.
  93                 </para>
  94             </listitem>
  95
  96             <listitem>
  97                 <para>
  98                     Additional convenience methods for some of the more common
  99                     operations.
 100                 </para>
 101             </listitem>
 102         </itemizedlist>
 103     </sect2>
 104
 105     <sect2 id="zend.service.amazon.sqs.storing-your-first">
 106         <title>Getting Started</title>
 107
 108         <para>
 109             Once you have registered with Amazon SQS, you're ready to create
 110             your queue and store some messages on SQS. Each queue can contain
 111             unlimited amount of messages, identified by name.
 112         </para>
 113
 114         <para>
 115             The following example demonstrates creating a queue, storing and
 116             retrieving messages.
 117         </para>
 118
 119         <example id="zend.service.amazon.sqs.storing-your-first.example">
 120             <title>Zend_Service_Amazon_Sqs Usage Example</title>
 121
 122             <programlisting language="php"><![CDATA[
 123 $sqs = new Zend_Service_Amazon_Sqs($my_aws_key, $my_aws_secret_key);
 124
 125 $queue_url = $sqs->create('test');
 126
 127 $message = 'this is a test';
 128 $message_id = $sqs->send($queue_url, $message);
 129
 130 foreach ($sqs->receive($queue_url) as $message) {
 131     echo $message['body'].'<br/>';
 132 }
 133 ]]></programlisting>
 134         </example>
 135
 136         <para>
 137             Since the <classname>Zend_Service_Amazon_Sqs</classname> service
 138             requires authentication, you should pass your credentials (AWS key
 139             and secret key) to the constructor. If you only use one account,
 140             you can set default credentials for the service:
 141         </para>
 142
 143         <programlisting language="php"><![CDATA[
 144 Zend_Service_Amazon_Sqs::setKeys($my_aws_key, $my_aws_secret_key);
 145 $sqs = new Zend_Service_Amazon_Sqs();
 146 ]]></programlisting>
 147     </sect2>
 148
 149     <sect2 id="zend.service.amazon.sqs.queues">
 150         <title>Queue operations</title>
 151
 152         <para>
 153             All messages SQS are stored in queues. A queue has to be created
 154             before any message operations. Queue names must be unique under your
 155             access key and secret key.
 156         </para>
 157
 158         <para>
 159             Queue names can contain lowercase letters, digits, periods (.),
 160             underscores (_), and dashes (-). No other symbols allowed. Queue
 161             names can be a maximum of 80 characters.
 162         </para>
 163
 164         <itemizedlist>
 165             <listitem>
 166                 <para>
 167                     <methodname>create()</methodname> creates a new queue.
 168                 </para>
 169             </listitem>
 170
 171             <listitem>
 172                 <para>
 173                     <methodname>delete()</methodname> removes all messages in
 174                     the queue.
 175                 </para>
 176
 177                 <example id="zend.service.amazon.sqs.queues.removalExample">
 178                     <title>Zend_Service_Amazon_Sqs Queue Removal Example</title>
 179
 180                     <programlisting language="php"><![CDATA[
 181 $sqs = new Zend_Service_Amazon_Sqs($my_aws_key, $my_aws_secret_key);
 182 $queue_url = $sqs->create('test_1');
 183 $sqs->delete($queue_url);
 184 ]]></programlisting>
 185                 </example>
 186             </listitem>
 187
 188             <listitem>
 189                 <para>
 190                     <methodname>count()</methodname> gets the approximate number
 191                     of messages in the queue.
 192                 </para>
 193
 194                 <example id="zend.service.amazon.sqs.queues.countExample">
 195                     <title>Zend_Service_Amazon_Sqs Queue Count Example</title>
 196
 197                     <programlisting language="php"><![CDATA[
 198 $sqs = new Zend_Service_Amazon_Sqs($my_aws_key, $my_aws_secret_key);
 199 $queue_url = $sqs->create('test_1');
 200 $sqs->send($queue_url, 'this is a test');
 201 $count = $sqs->count($queue_url); // Returns '1'
 202 ]]></programlisting>
 203                 </example>
 204             </listitem>
 205
 206             <listitem>
 207                 <para>
 208                     <methodname>getQueues()</methodname> returns the list of the
 209                     names of all queues belonging to the user.
 210                 </para>
 211
 212                 <example id="zend.service.amazon.sqs.queues.listExample">
 213                     <title>Zend_Service_Amazon_Sqs Queue Listing Example</title>
 214
 215                     <programlisting language="php"><![CDATA[
 216 $sqs = new Zend_Service_Amazon_Sqs($my_aws_key, $my_aws_secret_key);
 217 $list = $sqs->getQueues();
 218 foreach($list as $queue) {
 219    echo "I have queue $queue\n";
 220 }
 221 ]]></programlisting>
 222                 </example>
 223             </listitem>
 224         </itemizedlist>
 225     </sect2>
 226
 227     <sect2 id="zend.service.amazon.sqs.messages">
 228         <title>Message operations</title>
 229
 230         <para>
 231             After a queue is created, simple messages can be sent into the queue
 232             then received at a later point in time. Messages can be up to 8KB in
 233             length. If longer messages are needed please see <ulink
 234                 url="http://framework.zend.com/manual/en/zend.service.amazon.s3.html">S3</ulink>.
 235             There is no limit to the number of messages a queue can contain.
 236         </para>
 237
 238         <itemizedlist>
 239             <listitem>
 240                 <para>
 241                     <methodname>sent($queue_url, $message)</methodname> send the
 242                     <varname>$message</varname> to the <varname>$queue_url</varname> SQS
 243                     queue <acronym>URL</acronym>.
 244                 </para>
 245
 246                 <example id="zend.service.amazon.sqs.messages.sendExample">
 247                     <title>Zend_Service_Amazon_Sqs Message Send Example</title>
 248
 249                     <programlisting language="php"><![CDATA[
 250 $sqs = new Zend_Service_Amazon_Sqs($my_aws_key, $my_aws_secret_key);
 251 $queue_url = $sqs->create('test_queue');
 252 $sqs->send($queue_url, 'this is a test message');
 253 ]]></programlisting>
 254                 </example>
 255             </listitem>
 256
 257             <listitem>
 258                 <para>
 259                     <methodname>receive($queue_url)</methodname> retrieves
 260                     messages from the queue.
 261                 </para>
 262
 263                 <example id="zend.service.amazon.sqs.messages.receiveExample">
 264                     <title>Zend_Service_Amazon_Sqs Message Receive Example</title>
 265
 266                     <programlisting language="php"><![CDATA[
 267 $sqs = new Zend_Service_Amazon_Sqs($my_aws_key, $my_aws_secret_key);
 268 $queue_url = $sqs->create('test_queue');
 269 $sqs->send($queue_url, 'this is a test message');
 270 foreach ($sqs->receive($queue_url) as $message) {
 271     echo "got message ".$message['body'].'<br/>';
 272 }
 273 ]]></programlisting>
 274                 </example>
 275             </listitem>
 276
 277             <listitem>
 278                 <para>
 279                     <methodname>deleteMessage($queue_url, $handle)</methodname>
 280                     deletes a message from a queue. A message must first be
 281                     received using the <methodname>receive()</methodname> method
 282                     before it can be deleted.
 283                 </para>
 284
 285                 <example id="zend.service.amazon.sqs.messages.deleteExample">
 286                     <title>Zend_Service_Amazon_Sqs Message Delete Example</title>
 287
 288                     <programlisting language="php"><![CDATA[
 289 $sqs = new Zend_Service_Amazon_Sqs($my_aws_key, $my_aws_secret_key);
 290 $queue_url = $sqs->create('test_queue');
 291 $sqs->send($queue_url, 'this is a test message');
 292 foreach ($sqs->receive($queue_url) as $message) {
 293     echo "got message ".$message['body'].'<br/>';
 294
 295     if ($sqs->deleteMessage($queue_url, $message['handle'])) {
 296         echo "Message deleted";
 297     }
 298     else {
 299         echo "Message not deleted";
 300     }
 301 }
 302 ]]></programlisting>
 303                 </example>
 304             </listitem>
 305        </itemizedlist>
 306     </sect2>
 307 </sect1>