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.
If you're using laravel and see "Class IronMQ not found"
error set iron_mq
version to 1.*
and install dependencies
1.*
- Laravel 4.0/4.1/4.2/5.0 compatible, PHP 5.2 compatible version. No namespaces. Using default IronMQ servers.2.*
- Laravel 5.1/5.2 compatible, PSR-4 compatible version. With namespaces. Using default IronMQ servers. If you're not using laravel 4.0-5.0 stick with it.3.*
- Special version for IronMQ API v3. Laravel 4.0/4.1/4.2/5.0 compatible, PHP 5.2 compatible version.Different API (v3), different server endpoints.4.*
- Special version for IronMQ API v3. Laravel 5.1/5.2 compatible, PSR-4 compatible version. With namespaces. Different API (v3), different server endpoints. Go with it if you're using IronMQ on-premisemaster
branch - same as2.*
- 1.3.0 - changed argument list in methods
postMessage
andpostMessages
. Please revise code that uses these methods. - 1.4.5 - added
getMessagePushStatuses
anddeleteMessagePushStatus
methods. - 2.0.0 - version 2.0 introduced some backward incompatible changes. IronMQ client finally PSR-4 compatible and using namespaces & other php 5.3 stuff. If you're migrating from previous (1.x) version, please carefully check how iron_mq / iron_core classes loaded.
If you need some 1.x features like
.phar
archives, use latest 1.x stable version: https://github.com/iron-io/iron_mq_php/releases/tag/1.5.3
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
--
There are two ways to use iron_mq_php:
Create composer.json
file in project directory:
{
"require": {
"iron-io/iron_mq": "2.*"
}
}
Do composer install
(install it if needed: https://getcomposer.org/download/)
And use it:
require __DIR__ . '/vendor/autoload.php';
$ironmq = new \IronMQ\IronMQ();
- Copy classes from
src
to target directory - Grab IronCore classes there and copy to target directory
- Include them all.
require 'src/HttpException.php';
require 'src/IronCore.php';
require 'src/IronMQ.php';
require 'src/IronMQException.php';
require 'src/IronMQMessage.php';
require 'src/JsonException.php';
$ironmq = new \IronMQ\IronMQ();
--
Three ways to configure IronMQ:
- Passing array with options:
<?php
$ironmq = new \IronMQ\IronMQ(array(
"token" => 'XXXXXXXXX',
"project_id" => 'XXXXXXXXX'
));
- Passing json (or ini) file name which stores your configuration options (usually
token
andproject_id
):
<?php
$ironmq = new \IronMQ\IronMQ('iron.json');
-
Automatic config search - pass zero arguments to constructor and library will try to find config file in following locations:
iron.ini
in current directoryiron.json
in current directoryIRON_MQ_TOKEN
,IRON_MQ_PROJECT_ID
and other environment variablesIRON_TOKEN
,IRON_PROJECT_ID
and other environment variables.iron.ini
in user's home directory.iron.json
in user's home directory
--
<?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
));
--
<?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->getMessages($queue_name, 3);
--
<?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.
--
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
andport = 80
- Fix the error! Recommended solution: download actual certificates - cacert.pem and add them to
php.ini
:
[PHP]
curl.cainfo = "path\to\cacert.pem"
--
IronMQ
is based on IronCore
and provides easy access to the whole IronMQ API.
<?php
$ironmq = new \IronMQ\IronMQ(array(
"token" => 'XXXXXXXXX',
"project_id" => 'XXXXXXXXX'
));
--
<?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
--
<?php
$qinfo = $ironmq->getQueue($queue_name);
--
<?php
$response = $ironmq->deleteQueue($queue_name);
--
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).
--
Single message:
<?php
$message = $ironmq->getMessage($queue_name, $timeout, $wait);
Multiple messages:
<?php
$message = $ironmq->getMessages($queue_name, $count, $timeout, $wait);
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). -
$wait
: Time in seconds to wait for a message to become available. This enables long polling. Default is 0 (does not wait), maximum is 30.
--
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);
--
<?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).
--
<?php
$ironmq->deleteMessage($queue_name, $message_id);
--
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);
--
<?php
$ironmq->clearQueue($queue_name);
--
<?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));
<?php
$res = $ironmq->updateAlerts("test_alert_queue", array($first_alert, $second_alert));
<?php
$ironmq->deleteAlerts("test_alert_queue", $alert_ids);
<?php
$ironmq->deleteAlertById("test_alert_queue", $alert_id);
--
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.
<?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
: Eithermulticast
to push to all subscribers orunicast
to push to one and only one subscriber. Default ismulticast
.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 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"
));
--
<?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.
--
<?php
$statuses = $ironmq->getMessagePushStatuses($queue_name, $message_id);
foreach ($statuses as $status) {
$ironmq->deleteMessagePushStatus($queue_name, $message_id, $status["id"]);
}
--
If you want to revert your queue just update push_type
to "pull"
.
<?php
$params = array("push_type" => "pull");
$ironmq->updateQueue($queue_name, $params);
--
© 2011 - 2013 Iron.io Inc. All Rights Reserved.