Icicle

Icicle is a PHP library for writing asynchronous code using synchronous coding techniques.

Icicle uses Coroutines built with Awaitables to facilitate writing asynchronous code using techniques normally used to write synchronous code, such as returning values and throwing exceptions, instead of using nested callbacks typically found in asynchronous code.

Library Components

Coroutines: Interruptible functions for building asynchronous code using synchronous coding patterns and error handling.
Awaitables: Placeholders for future values of asynchronous operations. Awaitables can be yielded in coroutines to define interruption points. Callbacks registered with awaitables may return values and throw exceptions.
Loop (event loop): Used to schedule functions, run timers, handle signals, and poll sockets for pending data or await for space to write.

Available Components

Stream: Common coroutine-based interface for reading and writing data.
Socket: Asynchronous stream socket server and client.
Concurrent: Provides an easy to use interface for parallel execution with non-blocking communication and task execution.
DNS: Asynchronous DNS query executor, resolvern and connector.
Filesystem: Asynchronous filesystem access (under development).
HTTP: Asynchronous HTTP server and client (under development).
WebSocket: Asynchronous WebSocket server and client (under development).
React Adapter: Adapts the event loop and awaitables of Icicle to interfaces compatible with components built for React.

Requirements

PHP 5.5+ for v0.9.x branch (current stable) and v1.x branch (mirrors current stable)
PHP 7 for v2.0 branch (under development) supporting generator delegation and return expressions

Installation

The recommended way to install Icicle is with the Composer package manager. (See the Composer installation guide for information on installing and using Composer.)

Run the following command to use Icicle in your project:

composer require icicleio/icicle

You can also manually edit composer.json to add Icicle as a project requirement.

// composer.json
{
    "require": {
        "icicleio/icicle": "^0.9"
    }
}

Suggested

pcntl extension: Enables custom signal handling.
ev extension: Extension providing the most performant event loop implementation.
uv extension (PHP 7 only): Another extension providing a more performant event loop implementation (experimental).

Example

The example script below demonstrates how awaitables can be yielded in a coroutine to create interruption points. Fulfillment values of awaitables are sent to the coroutine and rejection exceptions are thrown into the coroutine.

#!/usr/bin/env php
<?php

require dirname(__DIR__) . '/vendor/autoload.php';

use Icicle\Awaitable;
use Icicle\Coroutine\Coroutine;
use Icicle\Loop;

$generator = function () {
    try {
        // Sets $start to the value returned by microtime() after approx. 1 second.
        $start = (yield Awaitable\resolve(microtime(true))->delay(1));

        echo "Sleep time: ", microtime(true) - $start, "\n";

        // Throws the exception from the rejected promise into the coroutine.
        yield Awaitable\reject(new Exception('Rejected promise'));
    } catch (Exception $e) { // Catches promise rejection reason.
        echo "Caught exception: ", $e->getMessage(), "\n";
    }

    yield Awaitable\resolve('Coroutine completed');
};

$coroutine = new Coroutine($generator());

$coroutine->done(function ($data) {
    echo $data, "\n";
});

Loop\run();

adrian-green / icicle