Data source: Beanstalk

---

1Presentation

Beanstalkd is a message queue server, which on the one hand registers processing orders, and on the other hand retrieves these orders for processing.

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

The connection is then available in the controller by writing:

$beanstalk = $this->beanstalk;

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

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

---

2Installation

To connect to a Beanstalk server, you need to install the Pheanstalk library. To do this, you can use the Composer dependency manager.

At the root of the project, execute the folling command:

$ composer require pda/pheanstalk

---

3Configuration

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

The DSN used to connect to the Beanstalkd server is written as:

beanstalk://SERVER[:PORT]/TUBE_NAME

The default port number is 11300.
Example: beanstalk://localhost/tube3

---

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 Beanstalkd. 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, Beanstalkd 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.

---

5Unified calls

5.1Array-type access

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

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

// delete a message
unset($beanstalk[$msg['id']]);

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

---

5.2General methods

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

---

5.3Management of complex serialized data

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

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

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

---

5.4Raw data management

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

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

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

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

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

6Specific calls

6.1touch()

touch(string $id) : \Temma\Datasources\Beanstalk

This method tells the Beanstalkd server that the message is still being processed, thus preventing it from being distributed again.
Example:

// retrieve the next message to be processed
$msg = $beanstalk->get('');

// processing...

// tells the server that processing is still in progress
$beanstalk->touch($msg['id']);

// further processing...

// delete the message
$beanstalk->remove($msg['id']);