sunloverz/iron_mq_php

IronMQ PHP Client Library

IronMQ is an elastic message queue for managing data and event flow within cloud applications and between systems.

The full API documentation is here and this client tries to stick to the API as much as possible so if you see an option in the API docs, you can use it in the methods below.

Getting Started

Get credentials

To start using iron_mq_php, you need to sign up and get an oauth token.

Go to http://iron.io/ and sign up.
Get an Oauth Token at http://hud.iron.io/tokens

Install iron_mq_php

There are two ways to use iron_mq_php:

Using precompiled phar archive

Copy iron_mq.phar to target directory and include it:

<?php
require_once "phar://iron_mq.phar";

Please note, phar extension available by default only from php 5.3.0 For php 5.2 you should install phar manually or use second option.

Using classes directly

Copy IronMQ.class.php to target directory
Grab IronCore.class.php there and copy to target directory
Include both of them:

<?php
require_once "IronCore.class.php"
require_once "IronMQ.class.php"

Configure

Three ways to configure IronMQ:

Passing array with options:

<?php
$ironmq = new IronMQ(array(
    "token" => 'XXXXXXXXX',
    "project_id" => 'XXXXXXXXX'
));

Passing ini file name which stores your configuration options. Rename sample_config.ini to config.ini and include your Iron.io credentials (token and project_id):

<?php
$ironmq = new IronMQ('config.ini');

Automatic config search - pass zero arguments to constructor and library will try to find config file in following locations:
- iron.ini in current directory
- iron.json in current directory
- IRON_MQ_TOKEN, IRON_MQ_PROJECT_ID and other environment variables
- IRON_TOKEN, IRON_PROJECT_ID and other environment variables
- .iron.ini in user's home directory
- .iron.json in user's home directory

The Basics

Post a Message to the Queue

<?php
$ironmq->postMessage($queue_name, "Hello world");

More complex example:

<?php
$ironmq->postMessage($queue_name, "Test Message", array(
    "timeout" => 120, # Timeout, in seconds. After timeout, item will be placed back on queue. Defaults to 60.
    "delay" => 5, # The item will not be available on the queue until this many seconds have passed. Defaults to 0.
    "expires_in" => 2*24*3600 # How long, in seconds, to keep the item on the queue before it is deleted.
));

Post multiple messages in one API call:

<?php
$ironmq->postMessages($queue_name, array("Message 1", "Message 2"), array(
    "timeout" => 120
));

Get a Message off the Queue

<?php
$ironmq->getMessage($queue_name);

When you pop/get a message from the queue, it will NOT be deleted. It will eventually go back onto the queue after a timeout if you don't delete it (default timeout is 60 seconds).

Get multiple messages in one API call:

<?php
$ironmq->getMessage($queue_name, 3);

Delete a Message from the Queue

<?php
$ironmq->deleteMessage($queue_name, $message_id);

Delete a message from the queue when you're done with it.

Delete multiple messages in one API call:

<?php
$ironmq->deleteMessages($queue_name, array("xxxxxxxxx", "xxxxxxxxx"));

Delete multiple messages specified by messages id array.

Troubleshooting

http error: 0

If you see Uncaught exception 'Http_Exception' with message 'http error: 0 | ' it most likely caused by misconfigured cURL https sertificates. There are two ways to fix this error:

Disable SSL sertificate verification - add this line after IronMQ initialization: $ironmq->ssl_verifypeer = false;
Switch to http protocol - add this to configuration options: protocol = http and port = 80
Fix the error! Recommended solution: download actual certificates - cacert.pem and add them to php.ini:

[PHP]

curl.cainfo = "path\to\cacert.pem"

Updating notes

1.3.0 - changed argument list in methods postMessage and postMessages. Please revise code that uses these methods.
1.4.5 - added getMessagePushStatuses and deleteMessagePushStatus methods.

Queues

IronMQ Client

IronMQ is based on IronCore and provides easy access to the whole IronMQ API.

<?php
$ironmq = new IronMQ(array(
    "token" => 'XXXXXXXXX',
    "project_id" => 'XXXXXXXXX'
));

List Queues

<?php
$queues = $ironmq->getQueues($page, $per_page);

Optional parameters:

$page: The 0-based page to view. The default is 0.
$per_page: The number of queues to return per page. The default is 30, the maximum is 100.

<?php
$queues_page_four = $ironmq->getQueues(3, 20); // get 4th page, 20 queues per page

Retrieve Queue Information

<?php
$qinfo = $ironmq->getQueue($queue_name);

Delete a Message Queue

<?php
$response = $ironmq->deleteQueue($queue_name);

Post Messages to a Queue

Single message:

<?php
$ironmq->postMessage($queue_name, "Test Message", array(
    'timeout' => 120,
    'delay' => 2,
    'expires_in' => 2*24*3600 # 2 days
));

Multiple messages:

<?php
$ironmq->postMessages($queue_name, array("Lorem", "Ipsum"), array(
    "timeout" => 120,
    "delay" => 2,
    "expires_in" => 2*24*3600 # 2 days
));

Optional parameters (3rd, array of key-value pairs):

timeout: After timeout (in seconds), item will be placed back onto queue. You must delete the message from the queue to ensure it does not go back onto the queue. Default is 60 seconds. Minimum is 30 seconds. Maximum is 86,400 seconds (24 hours).
delay: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days).
expires_in: How long in seconds to keep the item on the queue before it is deleted. Default is 604,800 seconds (7 days). Maximum is 2,592,000 seconds (30 days).

Get Messages from a Queue

Single message:

<?php
$message = $ironmq->getMessage($queue_name, $timeout);

Multiple messages:

<?php
$message = $ironmq->getMessages($queue_name, $count, $timeout);

Optional parameters:

$count: The maximum number of messages to get. Default is 1. Maximum is 100.
$timeout: After timeout (in seconds), item will be placed back onto queue. You must delete the message from the queue to ensure it does not go back onto the queue. If not set, value from POST is used. Default is 60 seconds. Minimum is 30 seconds. Maximum is 86,400 seconds (24 hours).

Touch a Message on a Queue

Touching a reserved message extends its timeout by the duration specified when the message was created, which is 60 seconds by default.

<?php
$ironmq->touchMessage($queue_name, $message_id);

Release Message

<?php
$ironmq->releaseMessage($queue_name, $message_id, $delay);

Optional parameters:

$delay: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days).

Delete a Message from a Queue

<?php
$ironmq->deleteMessage($queue_name, $message_id);

Peek Messages from a Queue

Peeking at a queue returns the next messages on the queue, but it does not reserve them.

Single message:

<?php
$message = $ironmq->peekMessage($queue_name);

Multiple messages:

<?php
$messages = $ironmq->peekMessages($queue_name, $count);

Clear a Queue

<?php
$ironmq->clearQueue($queue_name);

Add alerts to a queue. This is for Pull Queue only.

<?php
$first_alert = array(
        'type' => 'fixed',
        'direction' => 'desc',
        'trigger' => 1001,
        'snooze' => 10,
        'queue' => 'test_alert_queue');
$second_alert = array(
        'type' => 'fixed',
        'direction' => 'asc',
        'trigger' => 1000,
        'snooze' => 5,
        'queue' => 'test_alert_queue',);

$res = $ironmq->addAlerts("test_alert_queue", array($first_alert, $second_alert));

Replace current queue alerts with a given list of alerts. This is for Pull Queue only.

<?php
$res = $ironmq->updateAlerts("test_alert_queue", array($first_alert, $second_alert));

Remove alerts from a queue. This is for Pull Queue only.

<?php
$ironmq->deleteAlerts("test_alert_queue", $alert_ids);

Remove alert from a queue by its ID. This is for Pull Queue only.

<?php
$ironmq->deleteAlertById("test_alert_queue", $alert_id);

Push Queues

IronMQ push queues allow you to setup a queue that will push to an endpoint, rather than having to poll the endpoint. Here's the announcement for an overview.

Update a Message Queue

<?php
$params = array(
    "push_type" => "multicast",
    "retries" => 5,
    "subscribers" => array(
        array("url" => "http://your.first.cool.endpoint.com/push"),
        array("url" => "http://your.second.cool.endpoint.com/push")
    ),
    "error_queue" => "my_error_queue_name")
);

$ironmq->updateQueue($queue_name, $params);

The following parameters are all related to Push Queues:

subscribers: An array of subscriber hashes containing a “url” field. This set of subscribers will replace the existing subscribers. To add or remove subscribers, see the add subscribers endpoint or the remove subscribers endpoint. See below for example json.
push_type: Either multicast to push to all subscribers or unicast to push to one and only one subscriber. Default is multicast.
retries: How many times to retry on failure. Default is 3. Maximum is 100.
retries_delay: Delay between each retry in seconds. Default is 60.
error_queue: The name of another queue where information about messages that can't be delivered after retrying retries number of times will be placed. Pass in an empty string to disable error queues. Default is disabled. see: http://dev.iron.io/mq/reference/push_queues/#error_queues

Add/Remove Subscribers on a Queue

Add subscriber to Push Queue:

<?php
$ironmq->addSubscriber($queue_name, array(
    "url" => "http://cool.remote.endpoint.com/push"
));

$ironmq->removeSubscriber($queue_name, array(
    "url" => "http://cool.remote.endpoint.com/push"
));

Get Message Push Status

<?php
$response = $ironmq->postMessage('push me!');

$message_id = $response["ids"][0];
$statuses = $ironmq->getMessagePushStatuses($queue_name, $message_id);

Returns an array of subscribers with status.

Acknowledge / Delete Message Push Status

<?php
$statuses = $ironmq->getMessagePushStatuses($queue_name, $message_id);

foreach ($statuses as $status) {
    $ironmq->deleteMessagePushStatus($queue_name, $message_id, $status["id"]);
}

Revert Queue Back to Pull Queue

If you want to revert your queue just update push_type to "pull".

<?php
$params = array("push_type" => "pull");

$ironmq->updateQueue($queue_name, $params);

sunloverz / iron_mq_php

IronMQ PHP Client Library

Getting Started

Get credentials

Install iron_mq_php

Using precompiled phar archive

Using classes directly

Configure

The Basics

Post a Message to the Queue

Get a Message off the Queue

Delete a Message from the Queue

Troubleshooting

http error: 0

Updating notes

Queues

IronMQ Client

List Queues

Retrieve Queue Information

Delete a Message Queue

Post Messages to a Queue

Get Messages from a Queue

Touch a Message on a Queue

Release Message

Delete a Message from a Queue

Peek Messages from a Queue

Clear a Queue

Add alerts to a queue. This is for Pull Queue only.

Replace current queue alerts with a given list of alerts. This is for Pull Queue only.

Remove alerts from a queue. This is for Pull Queue only.

Remove alert from a queue by its ID. This is for Pull Queue only.

Push Queues

Update a Message Queue

Add/Remove Subscribers on a Queue

Get Message Push Status

Acknowledge / Delete Message Push Status

Revert Queue Back to Pull Queue

Further Links

About