IronMQ v4 PHP Client Library
IronMQ is an elastic message queue for managing data and event flow within cloud applications and between systems., (*1)
This library uses IronMQ API v3., (*2)
Branches
If you're using laravel and see "Class IronMQ not found" error set iron_mq version to 1.* and install/update dependencies, (*3)
-
1.* - Laravel 4.0/4.1/4.2/5.0 compatible, PHP 5.2 compatible version. No namespaces. Using IronMQv2 servers (deprecated).
-
2.* - Laravel 5.1/5.2 compatible, PSR-4 compatible version. With namespaces. Using IronMQv2 servers (deprecated).
-
3.* - Laravel 4.0/4.1/4.2/5.0 compatible, PHP 5.2 compatible version. IronMQv3.
-
4.* - (recommended) Laravel 5.1/5.2 compatible, PSR-4 compatible version. With namespaces. IronMQv3. Current default.
-
master branch - same as 4.*
Update 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.
- 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
Getting Started
Get credentials
To start using iron_mq_php, you need to sign up and get an oauth token., (*4)
- Go to http://iron.io/ and sign up.
- Get an Oauth Token at http://hud.iron.io/tokens
--, (*5)
Install iron_mq_php
There are two ways to use iron_mq_php:, (*6)
Using composer
Create composer.json file in project directory:, (*7)
{
"require": {
"iron-io/iron_mq": "2.*"
}
}
Do composer install (install it if needed: https://getcomposer.org/download/), (*8)
And use it:, (*9)
require __DIR__ . '/vendor/autoload.php';
$ironmq = new \IronMQ\IronMQ();
Using classes directly (strongly not recommended)
- 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();
--, (*10)
Three ways to configure IronMQ:, (*11)
- Passing array with options:
<?php
$ironmq = new \IronMQ\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\IronMQ('config.json');
--, (*13)
Keystone Authentication
Via Configuration File
Add keystone section to your iron.json file:, (*14)
{
"project_id": "57a7b7b35e8e331d45000001",
"keystone": {
"server": "http://your.keystone.host/v2.0/",
"tenant": "some-group",
"username": "name",
"password": "password"
}
}
In Code
$keystone = array(
"server" => "http://your.keystone.host/v2.0/",
"tenant" => "some-gorup",
"username" => "name",
"password" => "password"
);
$ironmq = new \IronMQ\IronMQ(array(
"project_id" => '57a7b7b35e8e331d45000001',
"keystone" => $keystone
));
The Basics
Post a Message to the Queue
<?php
$ironmq->postMessage($queue_name, "Hello world");
More complex example:, (*15)
<?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:, (*16)
<?php
$ironmq->postMessages($queue_name, array("Message 1", "Message 2"), array(
"timeout" => 120
));
--, (*17)
Reserve a Message
<?php
$ironmq->reserveMessage($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)., (*18)
Reserve multiple messages in one API call:, (*19)
<?php
$ironmq->reserveMessages($queue_name, 3);
Reservation Id is needed for operations like delete, touch or release a message. It could be obtained from
message model after reserving it:, (*20)
<?php
$message = $ironmq->reserveMessage($queue_name);
$reservation_id = $message->reservation_id;
--, (*21)
Delete a Message from the Queue
<?php
$ironmq->deleteMessage($queue_name, $message_id, $reservation_id);
If message isn't reserved, you don't need to provide reservation id, (*22)
<?php
$ironmq->deleteMessage($queue_name, $message_id);
Delete a message from the queue when you're done with it., (*23)
Delete multiple messages in one API call:, (*24)
<?php
$ironmq->deleteMessages($queue_name, array("xxxxxxxxx", "xxxxxxxxx"));
Delete multiple messages specified by messages id array., (*25)
It's also possible to delete array of message objects:, (*26)
<?php
$messages = $ironmq->reserveMessages($queue_name, 3);
$ironmq->deleteMessage($queue_name, $messages);
--, (*27)
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:, (*28)
- 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"
--, (*29)
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.
--, (*30)
Queues
IronMQ Client
IronMQ is based on IronCore and provides easy access to the whole IronMQ API., (*31)
<?php
$ironmq = new \IronMQ\IronMQ(array(
"token" => 'XXXXXXXXX',
"project_id" => 'XXXXXXXXX'
));
--, (*32)
List Queues
This code will return first 30 queues sorted by name., (*33)
<?php
$queues = $ironmq->getQueues();
Optional parameters:, (*34)
-
per_page: number of elements in response, default is 30.
-
previous: this is the last queue on the previous page, it will start from the next one. If queue with specified name doesn’t exist result will contain first per_page queues that lexicographically greater than previous
Assume you have queues named "a", "b", "c", "d", "e". The following code will list "c", "d" and
"e" queues:, (*35)
<?php
$queues = $ironmq->getQueues('b', 3);
--, (*36)
<?php
$qinfo = $ironmq->getQueue($queue_name);
--, (*37)
Delete a Message Queue
<?php
$response = $ironmq->deleteQueue($queue_name);
--, (*38)
Post Messages to a Queue
Single message:, (*39)
<?php
$ironmq->postMessage($queue_name, "Test Message", array(
'delay' => 2,
'expires_in' => 2*24*3600 # 2 days
));
Multiple messages:, (*40)
<?php
$ironmq->postMessages($queue_name, array("Lorem", "Ipsum"), array(
"delay" => 2,
"expires_in" => 2*24*3600 # 2 days
));
Optional parameters (3rd, array of key-value pairs):, (*41)
-
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)., (*42)
-
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)., (*43)
-
~~timeout~~: Deprecated. Can no longer set timeout when posting a message, only when reserving one., (*44)
--, (*45)
Get Messages from a Queue
Single message:, (*46)
<?php
$message = $ironmq->reserveMessage($queue_name, $timeout);
Multiple messages:, (*47)
<?php
$message = $ironmq->reserveMessages($queue_name, $count, $timeout, $wait);
Optional parameters:, (*48)
-
$count: The maximum number of messages to get. Default is 1. Maximum is 100., (*49)
-
$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)., (*50)
-
$wait: Time to long poll for messages, in seconds. Max is 30 seconds. Default 0., (*51)
--, (*52)
Touch a Message on a Queue
Touching a reserved message returns new reservation with specified or default timeout., (*53)
<?php
$ironmq->touchMessage($queue_name, $message_id, $reservation_id, $timeout);
--, (*54)
Release Message
<?php
$ironmq->releaseMessage($queue_name, $message_id, $reservation_id, $delay);
Parameters:, (*55)
-
$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).
--, (*56)
Delete a Message from a Queue
<?php
$ironmq->deleteMessage($queue_name, $message_id, $reservation_id);
--, (*57)
Peek Messages from a Queue
Peeking at a queue returns the next messages on the queue, but it does not reserve them., (*58)
Single message:, (*59)
<?php
$message = $ironmq->peekMessage($queue_name);
Multiple messages:, (*60)
<?php
$messages = $ironmq->peekMessages($queue_name, $count);
--, (*61)
Clear a Queue
<?php
$ironmq->clearQueue($queue_name);
--, (*62)
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., (*63)
Create a Queue
<?php
$params = array(
"message_timeout" => 120,
"message_expiration" => 24 * 3600,
"push" => array(
"subscribers" => array(
array("url" => "http://your.first.cool.endpoint.com/push", "name" => "first"),
array("url" => "http://your.second.cool.endpoint.com/push", "name" => "second")
),
"retries" => 4,
"retries_delay" => 30,
"error_queue" => "error_queue_name"
)
);
$ironmq->createQueue($queue_name, $params);
Options:, (*64)
-
type: String or symbol. Queue type. :pull, :multicast, :unicast. Field required and static.
-
message_timeout: Integer. Number of seconds before message back to queue if it will not be deleted or touched.
-
message_expiration: Integer. Number of seconds between message post to queue and before message will be expired.
The following parameters are all related to Push Queues:, (*65)
-
push: subscribers: An array of subscriber hashes containing a name and a url required fields,
and optional headers hash. headers's keys are names and values are means of HTTP headers.
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: retries: How many times to retry on failure. Default is 3. Maximum is 100.
-
push: retries_delay: Delay between each retry in seconds. Default is 60.
-
push: error_queue: String. Queue name to post push errors to.
--, (*66)
Same as create queue. A push queue couldn't be changed into a pull queue, so vice versa too., (*67)
Add/Remove Subscribers on a Queue
Add subscribers to Push Queue:, (*68)
<?php
$ironmq->addSubscriber($queue_name, array(
"url" => "http://cool.remote.endpoint.com/push",
"name" => "subscriber_name",
"headers" => array(
"Content-Type" => "application/json"
)
)
);
$ironmq->addSubscribers($queue_name, array(
array(
"url" => "http://first.remote.endpoint.com/push",
"name" => "first"),
array(
"url" => "http://second.remote.endpoint.com/push",
"name" => "second")
)
);
--, (*69)
Replace Subscribers on a Queue
Sets list of subscribers to a queue. Older subscribers will be removed., (*70)
<?php
$ironmq->replaceSubscriber($queue_name, array(
"url" => "http://cool.remote.endpoint.com/push",
"name" => "subscriber_name"
)
);
$ironmq->addSubscribers($queue_name, array(
array(
"url" => "http://first.remote.endpoint.com/push",
"name" => "first"),
array(
"url" => "http://second.remote.endpoint.com/push",
"name" => "second")
)
);
Remove Subscribers from a Queue
Remove subscriber from a queue. This is for Push Queues only., (*71)
<?php
$ironmq->removeSubscriber($queue_name, array(
"name" => "subscriber_name"
)
);
$ironmq->removeSubscribers($queue_name, array(
array("name" => "first"),
array("name" => "second")
)
);
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., (*72)
--, (*73)
Acknowledge, That Push Message Is Processed
This method could be used to acknowledgement process of push messages.
See IronMQ v3 documentation
on long-processing for further information., (*74)
<?php
$ironmq->deletePushMessage($queue_name, $message_id, $reservation_id, $subscriber_name);
--, (*75)
Further Links
© 2011 - 2013 Iron.io Inc. All Rights Reserved., (*76)
Wallogit.com
