Merge pull request #83 from php-http/async

Merge Async client and Promise in Httplug

Author: joelwurtz

CHANGELOG.md

@@ -1,7 +1,14 @@
 # Change Log
 
 
-## 1.0.0 - Unreleased
+## 1.0.0-alpha2 - UNRELEASED
+
+### Added
+
+- Async client and Promise interface
+
+
+## 1.0.0-alpha - 2015-10-26
 
 ### Added
 

src/HttpAsyncClient.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Http\Client;
+
+use Psr\Http\Message\RequestInterface;
+
+/**
+ * Sends a PSR-7 Request in an asynchronous way by returning a Promise.
+ *
+ * @author Joel Wurtz <[email protected]>
+ */
+interface HttpAsyncClient
+{
+    /**
+     * Sends a PSR-7 request in an asynchronous way.
+     *
+     * @param RequestInterface $request
+     *
+     * @return Promise
+     *
+     * @throws Exception
+     */
+    public function sendAsyncRequest(RequestInterface $request);
+}

src/Promise.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace Http\Client;
+
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Promise represents a response that may not be available yet, but will be resolved at some point in future.
+ * It acts like a proxy to the actual response.
+ *
+ * This interface is an extension of the promises/a+ specification https://promisesaplus.com/
+ * Value is replaced by an object where its class implement a Psr\Http\Message\RequestInterface.
+ * Reason is replaced by an object where its class implement a Http\Client\Exception.
+ *
+ * @author Joel Wurtz <[email protected]>
+ */
+interface Promise
+{
+    /**
+     * Pending state, promise has not been fulfilled or rejected.
+     */
+    const PENDING   = "pending";
+
+    /**
+     * Fulfilled state, promise has been fulfilled with a ResponseInterface object.
+     */
+    const FULFILLED = "fulfilled";
+
+    /**
+     * Rejected state, promise has been rejected with an Exception object.
+     */
+    const REJECTED  = "rejected";
+
+    /**
+     * Add behavior for when the promise is resolved or rejected (response will be available, or error happens).
+     *
+     * If you do not care about one of the cases, you can set the corresponding callable to null
+     * The callback will be called when the response or exception arrived and never more than once.
+     *
+     * @param callable $onFulfilled Called when a response will be available.
+     * @param callable $onRejected  Called when an error happens.
+     *
+     * You must always return the Response in the interface or throw an Exception.
+     *
+     * @return Promise Always returns a new promise which is resolved with value of the executed callback (onFulfilled / onRejected).
+     */
+    public function then(callable $onFulfilled = null, callable $onRejected = null);
+
+    /**
+     * Get the state of the promise, one of PENDING, FULFILLED or REJECTED
+     *
+     * @return int
+     */
+    public function getState();
+
+    /**
+     * Return the value of the promise (fulfilled).
+     *
+     * @return ResponseInterface Response Object only when the Promise is fulfilled.
+     *
+     * @throws \LogicException When the promise is not fulfilled.
+     */
+    public function getResponse();
+
+    /**
+     * Get the reason why the promise was rejected..
+     *
+     * If the exception is an instance of Http\Client\Exception\HttpException it will contain
+     * the response object with the status code and the http reason.
+     *
+     * @return Exception Exception Object only when the Promise is rejected.
+     *
+     * @throws \LogicException When the promise is not rejected.
+     */
+    public function getException();
+
+    /**
+     * Wait for the promise to be fulfilled or rejected.
+     *
+     * When this method returns, the request has been resolved and the appropriate callable has terminated.
+     */
+    public function wait();
+}