Data source: SQS

1Presentation

Amazon SQS (Simple Queue Service) is a message queue used to record processing orders on one side, and to retrieve these orders for processing on the other.

If you have correctly configured the SQS connection parameters, Temma automatically creates an object of type \Temma\Datasources\Sqs. By convention, we'll assume that you've named this connection sqs in the etc/temma.php file (see configuration documentation).

The connection is then available in the controller by writing: 

$sqs = $this->sqs;

In other objects managed by the dependency injection component, the SQS connection is accessible by writing: 

$sqs = $loader->dataSources->sqs;
$sqs = $loader->dataSources['sqs'];

2Installation

To connect to AWS (Amazon Web Services), Temma needs access to the AWS PHP SDK. This can be done by installing it with Composer, or by installing it manually.

2.1Installation with Composer

To install the AWS PHP SDK with Composer, simply type this command from the project root: 

$ composer require aws/aws-sdk-php

2.2Manual installation

To install the AWS PHP SDK manually, download the aws.phar file and place it in the project's lib/ directory. For example, by running the following command: 

$ wget -O lib/aws.phar https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar

You can also choose to install the AWS PHP SDK at system level, so you don't have to reinstall it for each project. To do this, simply copy the aws.phar file to a directory that is part of the include paths, such as /usr/share/php (instead of putting it in your project's lib/ directory).

3Configuration

In the etc/temma.php file (see configuration documentation), you declare the DSN (Data Source Name) used to connect to SQS.

The DSN used to connect to SQS is written as: sqs://ACCESS_KEY:PRIVATE_KEY@QUEUE_URL[#WAIT_POLLING]

  • The access key and private key are supplied by AWS.
  • QUEUE_URL corresponds to the URL of the message queue, without the "https://" prefix.
    Example: sqs://AKXYZ:PWD@sqs.eu-west-3.amazonaws.com/123456789012/queue_name
  • WAIT_POLLING is the optional length of time (in seconds) that reading will wait to receive a message before failing and returning an empty message. Can take a value between 1 and 20.
    Example: sqs://AKXYZ:PWD@sqs.eu-west-3.amazonaws.com/123456789012/queue_name#8

4Specific features of message queues

Unlike other data sources, messages are added to a message queue without providing an identifier (name, key, path, etc.). The identifier is created automatically by SQS. When a message is read, its identifier is returned along with its data; this identifier is subsequently used to delete the message from the queue.

Consequently, SQS does not allow you to check the existence of a message based on its identifier, nor to select a message, nor to define a default value when retrieving a message.

Please note that unlike Beanstalk, where readings are blocked until a message is available, readings on SQS are not blocked. It is possible to perform long polling by setting a timeout of up to 20 seconds. However, if the read call returns a null value, you'll have to try again.

5Unified calls

5.1Array-type access

// write a message (serialized)
$sqs[''] = $data;

// read a message (deserialized)
// returns an associative array with the "id" and "data" keys
$msg = $sqs[''];

// message deletion
unset($sqs[$msg['id']]);

// waiting messages count
$nbr = count($sqs);

5.2General methods

// delete a message
$sqs->remove($msg['id']);

// delete all messages
$sqs->flush();

5.3Management of complex serialized data

// read a message (deserialized)
// returns an associative array with the "id" and "data" keys
$msg = $sqs->get('');

// read a message (deserialized) with a maximum wait of 8 seconds
// returns an associative array with the "id" and "data" keys
$msg = $sqs->get('', options: 8);

// write a message (serialized)
$sqs->set('', $msgData);

// write multiple messages (serialized)
$sqs->mSet([
    $user1data,
    $user2data,
    $user3data,
]);

5.4Raw data management

// read a message (raw)
// returns an associative array with the "id" and "data" keys
$html = $sqs->read('');

// read a message (raw) with a maximum wait of 8 seconds
// returns an associative array with the "id" and "data" keys
$msg = $sqs->read('', options: 8);

// write a message (raw)
$sqs->write('', $msgData);

// write multiple messages (raw)
$sqs->mWrite({
    $user1data,
    $user2data,
    $user3data,
]);

// write a message (raw) from a local file
$sqs->copyTo('', '/path/to/file');

// write multiple messages (raw) from local files
$sqs->mCopyTo([
    '/path/to/file1',
    '/path/to/file2',
    '/path/to/file3',
]);