├── .gitignore
├── test
    ├── phpt
    │   ├── error_handler_002.phpt
    │   ├── error_handler_005.phpt
    │   ├── error_handler_006.phpt
    │   ├── error_handler_001.phpt
    │   ├── error_handler_003.phpt
    │   └── error_handler_004.phpt
    └── ErrorHandlerTest.php
├── .travis.yml
├── phpunit.xml.dist
├── src
    ├── Promise.php
    └── Promise
    │   └── ErrorHandler.php
├── composer.json
├── LICENSE
├── META.md
└── README.md


/.gitignore:
--------------------------------------------------------------------------------
1 | /composer.lock
2 | /vendor/


--------------------------------------------------------------------------------
/test/phpt/error_handler_002.phpt:
--------------------------------------------------------------------------------
 1 | --TEST--
 2 | ErrorHandler::notify() does not fatal with a handler
 3 | --FILE--
 4 | <?php
 5 | 
 6 | require __DIR__ . "/../../vendor/autoload.php";
 7 | 
 8 | AsyncInterop\Promise\ErrorHandler::set(function () { print "1"; });
 9 | AsyncInterop\Promise\ErrorHandler::notify(new Exception);
10 | 
11 | ?>
12 | --EXPECT--
13 | 1
14 | 


--------------------------------------------------------------------------------
/test/ErrorHandlerTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace AsyncInterop\Promise\Test;
 4 | 
 5 | use AsyncInterop\Promise;
 6 | 
 7 | class ErrorHandlerTest extends \PHPUnit_Framework_TestCase {
 8 |     function testSetReturnsPreviousErrorHandler() {
 9 |         $old = Promise\ErrorHandler::set($f = function() {});
10 |         $expectedF = Promise\ErrorHandler::set($old);
11 |         $this->assertEquals($f, $expectedF);
12 |     }
13 | }
14 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
 1 | language: php
 2 | 
 3 | php:
 4 |   - 5.4
 5 |   - 5.5
 6 |   - 5.6
 7 |   - 7.0
 8 |   - nightly
 9 |   - hhvm
10 | 
11 | matrix:
12 |   allow_failures:
13 |    - php: nightly
14 |   fast_finish: true
15 | 
16 | cache:
17 |   directories:
18 |     - $HOME/.composer/cache
19 | 
20 | install:
21 |   - composer install
22 |   - composer show -t
23 | 
24 | script:
25 |   - php vendor/bin/parallel-lint --exclude vendor .
26 |   - php vendor/bin/phpunit --coverage-text
27 | 


--------------------------------------------------------------------------------
/test/phpt/error_handler_005.phpt:
--------------------------------------------------------------------------------
 1 | --TEST--
 2 | ErrorHandler::set() replaces the current handler
 3 | --FILE--
 4 | <?php
 5 | 
 6 | require __DIR__ . "/../../vendor/autoload.php";
 7 | 
 8 | AsyncInterop\Promise\ErrorHandler::set(function () { print "1"; });
 9 | AsyncInterop\Promise\ErrorHandler::set(function () { print "2"; });
10 | AsyncInterop\Promise\ErrorHandler::set(function () { print "3"; });
11 | AsyncInterop\Promise\ErrorHandler::notify(new Exception);
12 | 
13 | ?>
14 | --EXPECT--
15 | 3
16 | 


--------------------------------------------------------------------------------
/phpunit.xml.dist:
--------------------------------------------------------------------------------
 1 | <phpunit bootstrap="./vendor/autoload.php" colors="true">
 2 |     <testsuites>
 3 |         <testsuite name="Main Tests">
 4 |             <directory>./test</directory>
 5 |         </testsuite>
 6 |         <testsuite name="PHPT Tests">
 7 |             <directory suffix=".phpt">./test/phpt</directory>
 8 |         </testsuite>
 9 |     </testsuites>
10 |     <filter>
11 |         <whitelist addUncoveredFilesFromWhitelist="true">
12 |             <directory>./src</directory>
13 |         </whitelist>
14 |     </filter>
15 | </phpunit>


--------------------------------------------------------------------------------
/test/phpt/error_handler_006.phpt:
--------------------------------------------------------------------------------
 1 | --TEST--
 2 | ErrorHandler::notify() fatals if handler throws
 3 | --FILE--
 4 | <?php
 5 | 
 6 | require __DIR__ . "/../../vendor/autoload.php";
 7 | 
 8 | AsyncInterop\Promise\ErrorHandler::set(function ($e) { throw $e; });
 9 | AsyncInterop\Promise\ErrorHandler::notify(new Exception);
10 | 
11 | ?>
12 | --EXPECTF--
13 | Fatal error: An exception has been thrown from the promise error handler registered to AsyncInterop\Promise\ErrorHandler::set().
14 | 
15 | %s in %s:%d
16 | Stack trace:
17 | #0 {main} in %s on line %d
18 | 


--------------------------------------------------------------------------------
/src/Promise.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace AsyncInterop;
 4 | 
 5 | /**
 6 |  * Representation of the future value of an asynchronous operation.
 7 |  */
 8 | interface Promise
 9 | {
10 |     /**
11 |      * Registers a callback to be invoked when the promise is resolved.
12 |      *
13 |      * If the promise is already resolved, the callback MUST be executed immediately.
14 |      *
15 |      * @param callable(\Throwable|\Exception|null $reason, $value) $onResolved `$reason` shall be `null` on
16 |      *     success, `$value` shall be `null` on failure.
17 |      *
18 |      * @return mixed Return type and value are unspecified.
19 |      */
20 |     public function when(callable $onResolved);
21 | }
22 | 


--------------------------------------------------------------------------------
/test/phpt/error_handler_001.phpt:
--------------------------------------------------------------------------------
 1 | --TEST--
 2 | ErrorHandler::notify() fatals without a handler
 3 | --FILE--
 4 | <?php
 5 | 
 6 | require __DIR__ . "/../../vendor/autoload.php";
 7 | 
 8 | AsyncInterop\Promise\ErrorHandler::notify(new Exception);
 9 | 
10 | ?>
11 | --EXPECTF--
12 | Fatal error: An exception has been thrown from an AsyncInterop\Promise::when() handler, but no handler has been registered via AsyncInterop\Promise\ErrorHandler::set(). A handler has to be registered to prevent exceptions from going unnoticed. Do NOT install an empty handler that just does nothing. If the handler is called, there is ALWAYS something wrong.
13 | 
14 | %s in %s:%d
15 | Stack trace:
16 | #0 {main} in %s on line %d
17 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "async-interop/promise",
 3 |     "description": "A promise interface for interoperability in async operations.",
 4 |     "keywords": ["promise", "future", "awaitable", "async", "interop"],
 5 |     "license": "MIT",
 6 |     "require": {
 7 |         "php": ">=5.4.0"
 8 |     },
 9 |     "require-dev": {
10 |         "phpunit/phpunit": "^4.8.25|^5.3.3",
11 |         "jakub-onderka/php-parallel-lint": "^0.9.2",
12 |         "jakub-onderka/php-console-highlighter": "^0.3.2"
13 |     },
14 |     "autoload": {
15 |         "psr-4": {
16 |             "AsyncInterop\\": "src"
17 |         }
18 |     },
19 |     "autoload-dev": {
20 |         "psr-4": {
21 |             "AsyncInterop\\Promise\\Test\\": "test"
22 |         }
23 |     }
24 | }
25 | 


--------------------------------------------------------------------------------
/test/phpt/error_handler_003.phpt:
--------------------------------------------------------------------------------
 1 | --TEST--
 2 | ErrorHandler::notify() fatals after handlers have been removed with ErrorHandler::set(null)
 3 | --FILE--
 4 | <?php
 5 | 
 6 | require __DIR__ . "/../../vendor/autoload.php";
 7 | 
 8 | AsyncInterop\Promise\ErrorHandler::set(function () { print "1"; });
 9 | AsyncInterop\Promise\ErrorHandler::set(null);
10 | AsyncInterop\Promise\ErrorHandler::notify(new Exception);
11 | 
12 | ?>
13 | --EXPECTF--
14 | Fatal error: An exception has been thrown from an AsyncInterop\Promise::when() handler, but no handler has been registered via AsyncInterop\Promise\ErrorHandler::set(). A handler has to be registered to prevent exceptions from going unnoticed. Do NOT install an empty handler that just does nothing. If the handler is called, there is ALWAYS something wrong.
15 | 
16 | %s in %s:%d
17 | Stack trace:
18 | #0 {main} in %s on line %d
19 | 


--------------------------------------------------------------------------------
/test/phpt/error_handler_004.phpt:
--------------------------------------------------------------------------------
 1 | --TEST--
 2 | ErrorHandler::notify() converts non-exception to exception
 3 | --FILE--
 4 | <?php
 5 | 
 6 | require __DIR__ . "/../../vendor/autoload.php";
 7 | 
 8 | AsyncInterop\Promise\ErrorHandler::notify(42);
 9 | 
10 | ?>
11 | --EXPECTF--
12 | Fatal error: An exception has been thrown from an AsyncInterop\Promise::when() handler, but no handler has been registered via AsyncInterop\Promise\ErrorHandler::set(). A handler has to be registered to prevent exceptions from going unnoticed. Do NOT install an empty handler that just does nothing. If the handler is called, there is ALWAYS something wrong.
13 | 
14 | %SException%SPromise implementation called AsyncInterop\Promise\ErrorHandler::notify() with an invalid argument of type 'integer'%S in %s:%d
15 | Stack trace:
16 | #0 %s(%d): AsyncInterop\Promise\ErrorHandler::notify(%S)
17 | #1 {main} in %s on line %d
18 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2016 PHP Asynchronous Interoperability Group
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/META.md:
--------------------------------------------------------------------------------
 1 | # Promise
 2 | 
 3 | This document describes a few design considerations, for the main specification, refer to [the README document](README.md).
 4 | 
 5 | ## Recommended usage of Promises
 6 | 
 7 | We are explicitly _not_ providing a chainable method, thus we are also not recommending to chain them, but rather to use coroutines in form of generators inside application code.
 8 | 
 9 | Coroutines solve the problem of the so-called callback hell very nicely and also allow proper usage of `try` / `catch`.
10 | 
11 | ## Choice of `when()`
12 | 
13 | The specification proposes `when()` in order to only expose the most primitive common denominator needed for interoperability, which is a simple callable to be executed after the resolution.
14 | 
15 | If implementations wish to adhere to e.g. [Promises/A+ from Javascript](https://promisesaplus.com) (which had been implemented in many PHP Promise libraries at the time of writing this specification) or implement any other methods, they still may do so; `when()` however is the fundamental interoperable primitive every `Promise` is guaranteed to have.
16 | 
17 | Additionally, coroutines do not use the returned `Promise` of a `then()` callback, but returning a `Promise` is required by Promises/A+. Thus there's a lot of useless object creations when using Promises the recommended way, which isn't cheap and adds up. This conflicts with the goal of being as lightweight as possible.
18 | 
19 | ## Naming
20 | 
21 | `Promise` is a recognized and accepted name for future value placeholders, it's not strictly tied to the `Thenable` API.
22 | 
23 | ## Creation of Promises
24 | 
25 | `Promise` creation and managing is out of scope of this specification, as managing never shall cross library boundaries and thus does not need to be interoperable at all. Each library shall resolve the `Promise` it created itself.
26 | 
27 | ## Resolution of Promises
28 | 
29 | The specification defines that the value of a `Promise` must never be another `Promise`. Implementations may still accept to be resolved by a promise and then defer the resolution until the passed promise resolves.
30 | 


--------------------------------------------------------------------------------
/src/Promise/ErrorHandler.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | namespace AsyncInterop\Promise;
  4 | 
  5 | /**
  6 |  * Global error handler for promises.
  7 |  *
  8 |  * Callbacks passed to `Promise::when()` should never throw, but they might. Such errors have to be passed to this
  9 |  * global error handler to make them easily loggable. These can't be handled gracefully in any way, so we just enable
 10 |  * logging with this handler and ignore them otherwise.
 11 |  *
 12 |  * If no handler is set or that handler rethrows, it will fail hard by triggering an E_USER_ERROR leading to script
 13 |  * abortion.
 14 |  */
 15 | final class ErrorHandler
 16 | {
 17 |     /** @var callable|null */
 18 |     private static $callback = null;
 19 | 
 20 |     private function __construct()
 21 |     {
 22 |         // disable construction, only static helper
 23 |     }
 24 | 
 25 |     /**
 26 |      * Set a new handler that will be notified on uncaught errors during promise resolution callback invocations.
 27 |      *
 28 |      * This callback can attempt to log the error or exit the execution of the script if it sees need. It receives the
 29 |      * exception as first and only parameter.
 30 |      *
 31 |      * As it's already a last chance handler, the script will be aborted using E_USER_ERROR if the handler throws. Thus
 32 |      * it's suggested to always wrap the body of your callback in a generic `try` / `catch` block, if you want to avoid
 33 |      * that.
 34 |      *
 35 |      * @param callable|null $onError Callback to invoke on errors or `null` to reset.
 36 |      *
 37 |      * @return callable|null Previous callback.
 38 |      */
 39 |     public static function set(callable $onError = null)
 40 |     {
 41 |         $previous = self::$callback;
 42 |         self::$callback = $onError;
 43 |         return $previous;
 44 |     }
 45 | 
 46 |     /**
 47 |      * Notifies the registered handler, that an exception occurred.
 48 |      *
 49 |      * This method MUST be called by every promise implementation if a callback passed to `Promise::when()` throws upon
 50 |      * invocation. It MUST NOT be called otherwise.
 51 |      *
 52 |      * @param \Exception|\Throwable $error Exception that occurred.
 53 |      */
 54 |     public static function notify($error)
 55 |     {
 56 |         // No type declaration, because of PHP 5 + PHP 7 support.
 57 |         if (!$error instanceof \Exception && !$error instanceof \Throwable) {
 58 |             // We have this error handler specifically so we never throw from Promise::when(), so it doesn't make sense
 59 |             // to throw here. We just forward a generic exception to the registered handlers.
 60 |             $error = new \Exception(\sprintf(
 61 |                 "Promise implementation called %s() with an invalid argument of type '%s'",
 62 |                 __METHOD__,
 63 |                 \is_object($error) ? \get_class($error) : \gettype($error)
 64 |             ));
 65 |         }
 66 | 
 67 |         if (self::$callback === null) {
 68 |             self::triggerErrorHandler(
 69 |                 "An exception has been thrown from an AsyncInterop\\Promise::when() handler, but no handler has been"
 70 |                 . " registered via AsyncInterop\\Promise\\ErrorHandler::set(). A handler has to be registered to"
 71 |                 . " prevent exceptions from going unnoticed. Do NOT install an empty handler that just does nothing."
 72 |                 . " If the handler is called, there is ALWAYS something wrong.",
 73 |                 $error
 74 |             );
 75 | 
 76 |             return;
 77 |         }
 78 | 
 79 |         try {
 80 |             \call_user_func(self::$callback, $error);
 81 |         } catch (\Exception $e) {
 82 |             self::triggerErrorHandler(
 83 |                 "An exception has been thrown from the promise error handler registered to"
 84 |                 . " AsyncInterop\\Promise\\ErrorHandler::set().",
 85 |                 $e
 86 |             );
 87 |         } catch (\Throwable $e) {
 88 |             self::triggerErrorHandler(
 89 |                 "An exception has been thrown from the promise error handler registered to"
 90 |                 . " AsyncInterop\\Promise\\ErrorHandler::set().",
 91 |                 $e
 92 |             );
 93 |         }
 94 |     }
 95 | 
 96 |     private static function triggerErrorHandler($message, $error) {
 97 |         // We're already a last chance handler, throwing doesn't make sense, so use E_USER_ERROR.
 98 |         // E_USER_ERROR is recoverable by a handler set via set_error_handler, which might throw, too.
 99 | 
100 |         $message .= "\n\n" . (string) $error;
101 | 
102 |         try {
103 |             \trigger_error($message, E_USER_ERROR);
104 |         } catch (\Exception $e) {
105 |             \set_error_handler(null);
106 |             \trigger_error($message, E_USER_ERROR);
107 |         } catch (\Throwable $e) {
108 |             \set_error_handler(null);
109 |             \trigger_error($message, E_USER_ERROR);
110 |         }
111 |     }
112 | }
113 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Promise
 2 | 
 3 | The purpose of this specification is to provide a common interface for simple placeholder objects returned from async operations. This allows libraries and components from different vendors to create coroutines regardless of the placeholder implementation used. This specification is not designed to replace promise implementations that may be chained. Instead, the common interface may be extended by promise implementations.
 4 | 
 5 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
 6 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
 7 | interpreted as described in [RFC 2119][].
 8 | 
 9 | A `Promise` represents the eventual result of an asynchronous operation. Interaction with a `Promise` happens through its `when()` method, which registers a callback to receive either a `Promise`'s eventual value, or reason for failure.
10 | 
11 | `Promise` is the fundamental primitive in asynchronous programming. It should be as lightweight as possible, as any cost adds up significantly.
12 | 
13 | This specification defines the absolute minimum for interoperable coroutines, which can be implemented in PHP using generators.
14 | 
15 | This specification does not deal with how a `Promise` should be created, succeed, or fail, as only the consumption of `Promise` is required to be interoperable.
16 | 
17 | For further design explanations and notes, please refer to [the meta document](META.md).
18 | 
19 | ## Terminology
20 | 
21 | 1. _Promise_ is an object implementing `AsyncInterop\Promise` and conforming to this specification.
22 | 2. _Value_ is any legal PHP value (including `null`), but not an instance of `AsyncInterop\Promise`.
23 | 3. _Error_ is any value that can be thrown using the `throw` statement.
24 | 4. _Reason_ is an error indicating why a `Promise` has failed.
25 | 
26 | ## States
27 | 
28 | A `Promise` MUST be in one of three states: `pending`, `succeeded`, `failed`.
29 | 
30 | | A promise in … state | &nbsp; |
31 | |----------------------|--------|
32 | |`pending`  | <ul><li>MAY transition to either the `succeeded` or `failed` state.</li></ul>                                |
33 | |`succeeded`| <ul><li>MUST NOT transition to any other state.</li><li>MUST have a value which MUST NOT change.*</li></ul>  |
34 | |`failed`   | <ul><li>MUST NOT transition to any other state.</li><li>MUST have a reason which MUST NOT change.*</li></ul> |
35 | 
36 | * _Must not change_ refers to the _reference_ being immutable in case of an object, _not the object itself_ being immutable.
37 | 
38 | A `Promise` is resolved once it either succeeded or failed.
39 | 
40 | ## Consumption
41 | 
42 | A `Promise` MUST implement `AsyncInterop\Promise` and thus provide a `when()` method to access its value or reason.
43 | 
44 | ```php
45 | <?php
46 | 
47 | namespace AsyncInterop;
48 | 
49 | /**
50 |  * Representation of the future value of an asynchronous operation.
51 |  */
52 | interface Promise
53 | {
54 |     /**
55 |      * Registers a callback to be invoked when the promise is resolved.
56 |      *
57 |      * If the promise is already resolved, the callback MUST be executed immediately.
58 |      *
59 |      * @param callable(\Throwable|\Exception|null $reason, $value) $onResolved `$reason` shall be `null` on
60 |      *     success, `$value` shall be `null` on failure.
61 |      *
62 |      * @return mixed Return type and value are unspecified.
63 |      */
64 |     public function when(callable $onResolved);
65 | }
66 | ```
67 | 
68 | All callbacks registered before the `Promise` is resolved MUST be executed in the order they were registered after the `Promise` has been resolved. Callbacks registered after the resolution MUST be executed immediately.
69 | 
70 | The invocation of `Promise::when()` MUST NOT throw exceptions bubbling up from an `$onResolved` invocation. If one of the callbacks throws an `Exception` or `Throwable`, the `Promise` implementation MUST catch it and call `AsyncInterop\Promise\ErrorHandler::notify()` with the `Exception` or `Throwable` as first argument. The `Promise` implementation MUST then continue to call the remaining callbacks with the original parameters.
71 | 
72 | Registered callbacks MUST NOT be called from a file with strict types enabled (`declare(strict_types=1)`).
73 | 
74 | ## Error Handling
75 | 
76 | Uncaught exceptions thrown from callbacks registered to `Promise::when()` are forwarded to the `ErrorHandler` by `Promise` implementations. `ErrorHandler::set()` can be used to register a callable to handle these exceptions gracefully, e.g. by logging them. In case the handler throws again or is not set, an `E_USER_ERROR` is triggered. If a PHP error handler is set using `set_error_handler` and it throws, a short message is written to STDERR and the program exits with code `255`. Thus, it's RECOMMENDED to set an error handler and ensure it doesn't throw, especially if the PHP error handler is set up to convert errors to exceptions.
77 | 
78 | ## Contributors
79 | 
80 | * [Aaron Piotrowski](https://github.com/trowski)
81 | * [Andrew Carter](https://github.com/AndrewCarterUK)
82 | * [Bob Weinand](https://github.com/bwoebi)
83 | * [Cees-Jan Kiewiet](https://github.com/WyriHaximus)
84 | * [Christopher Pitt](https://github.com/assertchris)
85 | * [Daniel Lowrey](https://github.com/rdlowrey)
86 | * [Niklas Keller](https://github.com/kelunik)
87 | * [Stephen M. Coakley](https://github.com/coderstephen)
88 | 
89 | [RFC 2119]: http://tools.ietf.org/html/rfc2119
90 | 


--------------------------------------------------------------------------------