p/iris

This package is abandoned and no longer maintained. The author suggests using the guzzlehttp/guzzle package instead.

Curl Wrapper to ease curl* and curl_multi* functions usage

0.2.1 2014-03-05 11:06 UTC

Requires

• php: >=5.3.0
• ext-curl: *

MIT

• Ignace Nyamagana Butera
• Bertrand Andres

• curl
• http
• communication

README

THIS PACKAGE IS ABANDONNED PLEASE USE A MORE MODERN APPROACH LIKE guzzle

#Iris

Iris is a simple library that wrap cURL functions to ease their use. Iris can dot that using a simple OOP approach to cURL.

This package is compliant with PSR-1, PSR-2, and PSR-4.

Iris was built to understand cURL advance features. It is loosely based on phpmulticurl.

Features & Roadmap

• [TODO] Add Unit Testing

Requirements

You need PHP >= 5.3.0 and the cURL extension to use Iris but the latest stable version of PHP is recommended.

Installation

You may install the Iris package with Composer.

{
    "require": {
        "P\Iris": "0.*"
    }
}

Or you can download the library and point to its autoloading script.

<?php
require '/path/to/iris/autoload.php';

use P\Iris\Message;

$request = new Message;

Usage

• Sending a simple request
• Sending a batch of request

Documentation

Iris\Message

Instantiation

to perform simple requests you need to instantiate the P\Iris\Message object.

$request = new Message;
$request->setUserAgent('My beautiful user agent/1.0');

Before anything else you may want to specify your own user agent. By defaut the library set its own user agent. You can override this behaviour by setting you own user agent using the P\Iris\Message::setUserAgent method. Once set, the user agent won't change even if you reset the Iris\Message object.

At any given time you can reset the current cURL handler allowing you to perform multiple call using the same P\Iris\Message object. Once resetted, the object will loose any reference to the old request, except for the user agent and the event listerners attached to it.

$request->reset();

Adding Options

cURL calls are all about options, P\Iris\Message help you set them using the setOption method.

the setOption method can accept an array as a single value or a cURL options and its value.

$request->setOption(CURLOPT_NOBODY, true);
//or
$request->setOption([
    CURLOPT_NOBODY => true,
    CURLOPT_HEADER_OUT => true
]);

The options can be changed and altered at any given times before performing the request as their are applied only when the request is performed.

Performing a request

Using Procedural code

To perform a request you need to call the Iris\Message::execute method.

$request = new Message;
$request->setUserAgent('My beautiful user agent/1.0');
$request->setOption(CURLOPT_URL, 'http://www.example.com');
$request->setOption(CURLOPT_RETURNTRANSFER, true);
$request->execute();
if ($request->getErrorCode()) {
    echo $curl->getErrorCode().': '. $curl->getErrorMessage();
} else {
    $status = $request->getInfo(CURLOPTINFO_HTTP_CODE); //return the Status Code
    echo $request->getResponse();
}

You'll get access to:

• the response by using the P\Iris\Message::getResponse method.
• the cURL request information using the P\Iris\Message::getInfo method. This method by default return an array of all available information. If you are only interested in one value then use its CURLINFO_* index;
• the cURL errors are accessible through P\Iris\Message::getErrorCode and P\Iris\Message::getErrorMessage methods;

Using Events

Another way to deal with the result is by using event listener. The \Iris\Message comes with a simple event listener mechanism. You can register as many callback functions as you want and they will be executed on request success or on request error like explain below:

$request = new Message;
$request->setUserAgent('My beautiful user agent/1.0');
$request->setOption(CURLOPT_URL, 'http://www.example.com');
$request->setOption(CURLOPT_RETURNTRANSFER, true);
$request->addListener(Message::EVENT_ON_SUCCESS, function ($res, $curl) {
    echo $curl->getInfo(CURLOPTINFO_HTTP_CODE); //return the Status Code
});
$request->addListener(Message::EVENT_ON_FAIL, function ($res, $curl) {
    echo $curl->getErrorCode().': '. $curl->getErrorMessage();
});
$request->execute();

Depending on the result of the cURL request one of the event will be called. Of course you can remove the callback by using the P\Iris\Message::removeListener with the same parameters used to add the callback.

Simple Requests (GET, POST, PUT, DELETE, HEAD)

The class comes with specialized method to perform usual calls used in REST API:

• P\Iris\Message::get to issue a GET request;
• P\Iris\Message::post to issue a POST request;
• P\Iris\Message::put to issue a PUT request;
• P\Iris\Message::delete to issue a DELETE request;
• P\Iris\Message::head to issue a HEAD request;

These methods takes up to 3 parameters:

• the first parameter is the URL you want to request;
• the second parameter can be an array, a Traversable object or a string. This is the data that will be used with the URL;
• the third parameter is to indicate if the request must be delayed or not. By default, the request is not delayed and the value is false (ie: usefull when combine with P\Iris\Batch);

Here's a simple example:

$request = new Message;
$request->addListener(Message::EVENT_ON_SUCCESS, function ($res, $curl) {
    echo $request->getResponse();
});
$request->addListener(Message::EVENT_ON_FAIL, function ($res, $curl) {
    echo $curl->getErrorCode().': '. $curl->getErrorMessage();
});
$request->get(
    'http://www.example.com/path/to/my/script',
    ['var1' => 'value2',   ...]
);

You do not need to use the P\Iris\Message::execute method as it is called directly by the P\Iris\Message::get method. If you do not want the request to be directly issue then you have to specify it using the third argument.

$request = new Message;
$request->get(
    'http://www.example.com/path/to/my/script',
    json_encode(['var1' => 'value2', ...]),
    true
);
$request->execute();
echo $request->getResponse();

The request is registered but not execute, you will need to call explicitly P\Iris\Message::execute or P\Iris\Batch::execute to perform the request.

Iris\Envelope

This class is responsible for wrapping curl_multi_* function. As it is you could use it to perform parallel calls using cURL but really don't, there's a simpler way using P\Iris\Batch.

The sole purpose of this function is to configure how cURL may behave when using parallel request. You can specify:

• the maximum number of parallel requests you want to perform. By default This number is 10 but you can change the number using the setOption method just like with the P\Iris\Message class Of note:

  • Settings options was not possible before PHP 5.5
  • The class comes with a constant called P\Iris\Envelope::MAXCONNECTS the value of this value matches the value of the PHP5.5+ constant CURLMOPT_MAXCONNECTS so both constants are interchangeable.

• to set the selectTimeout and the execTimeout used by cURL to perform the requests. These values can be set and get using simple getter and setter methods.

  • The selectTimeout must be a float;
  • The execTimeout must be a integer;

Iris\Batch

Instantiation

This class was build to simplify parallel calls. To instantiate this class you must give it a object of type Iris\Enveloppe

<?php
use P\Iris\Envelope;
use P\Iris\Batch;

$envelope = new Envelope;
$envelope->setSelectTimeout(10.00);
$evenlope->setExecTimeout(100);
$envelope->setOption(Envelope::MAXCONNECTS, 3);
$batch = new Batch($enveloppe);

Adding Request

Once the \P\Iris\Batch is instantiate you just need to provide the cURL requests to perform in parallel.

To do so you can use the \P\Iris\Batch::addOne function that will had a single \P\Iris\Message object or the \P\Iris\Batch::addMany that will accept an array or any Traversable object that contained only \P\Iris\Message objects.

$batch->addOne($request);
//or
$batch->addMany([$request1, $request2]);

At any given time you can count the number of \P\Iris\Message objects present in the \P\Iris\Batch object. This number will decrease as the object performs the requests.

$nb_messages = count($batch);

Performing the requests

$batch->execute();

Once you have added all the \P\Iris\Message objects you can safely perform you parallel requests using the \P\Iris\Batch::execute method.

When using the \P\Iris\Batch you must use \P\Iris\Message event listeners to process each cURL request individually.

Contribution

Please see CONTRIBUTING for details.

Credits

• ignace nyamagana butera
• bertrand andres