search

iron-io / iron_mq_php

PHP client for IronMQ.
www.iron.io
BSD 2-Clause "Simplified" License
89 stars 43 forks source link

readme

IronMQ v4 PHP Client Library

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

This library uses IronMQ API v3.

Branches

*If you're using laravel and see "Class IronMQ not found" error set iron_mq version to `1.` and install/update dependencies**

Update notes

Getting Started

Get credentials

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

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

--

Install iron_mq_php

There are two ways to use iron_mq_php:

Using composer

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();
Using classes directly (strongly not recommended)
  1. Copy classes from src to target directory
  2. Grab IronCore classes there and copy to target directory
  3. 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();

--

Configure

Three ways to configure IronMQ:

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

--

Keystone Authentication

Via Configuration File

Add keystone section to your iron.json file:

{
  "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:

<?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
));

--

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).

Reserve multiple messages in one API call:

<?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:

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

--

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

<?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.

It's also possible to delete array of message objects:

<?php
$messages = $ironmq->reserveMessages($queue_name, 3);
$ironmq->deleteMessage($queue_name, $messages);

--

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:

  1. Disable SSL sertificate verification - add this line after IronMQ initialization: $ironmq->ssl_verifypeer = false;
  2. Switch to http protocol - add this to configuration options: protocol = http and port = 80
  3. 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

--

Queues

IronMQ Client

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'
));

--

List Queues

This code will return first 30 queues sorted by name.

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

Optional parameters:

Assume you have queues named "a", "b", "c", "d", "e". The following code will list "c", "d" and "e" queues:

<?php
$queues = $ironmq->getQueues('b', 3);

--

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(
    'delay' => 2,
    'expires_in' => 2*24*3600 # 2 days
));

Multiple messages:

<?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):

--

Get Messages from a Queue

Single message:

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

Multiple messages:

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

Optional parameters:

--

Touch a Message on a Queue

Touching a reserved message returns new reservation with specified or default timeout.

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

--

Release Message

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

Parameters:

--

Delete a Message from a Queue

<?php
$ironmq->deleteMessage($queue_name, $message_id, $reservation_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);

--

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.

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:

The following parameters are all related to Push Queues:

--

Update Queue Information

Same as create queue. A push queue couldn't be changed into a pull queue, so vice versa too.

Add/Remove Subscribers on a Queue

Add subscribers to Push Queue:

<?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")
    )
);

--

Replace Subscribers on a Queue

Sets list of subscribers to a queue. Older subscribers will be removed.

<?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.

<?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.

--

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.

<?php
$ironmq->deletePushMessage($queue_name, $message_id, $reservation_id, $subscriber_name);

--

Further Links

© 2011 - 2013 Iron.io Inc. All Rights Reserved.