www.aleph1.co.uk Git - yaffs-website/blob - vendor/guzzlehttp/promises/src/PromiseInterface.php

   1 <?php
   2 namespace GuzzleHttp\Promise;
   3
   4 /**
   5  * A promise represents the eventual result of an asynchronous operation.
   6  *
   7  * The primary way of interacting with a promise is through its then method,
   8  * which registers callbacks to receive either a promise’s eventual value or
   9  * the reason why the promise cannot be fulfilled.
  10  *
  11  * @link https://promisesaplus.com/
  12  */
  13 interface PromiseInterface
  14 {
  15     const PENDING = 'pending';
  16     const FULFILLED = 'fulfilled';
  17     const REJECTED = 'rejected';
  18
  19     /**
  20      * Appends fulfillment and rejection handlers to the promise, and returns
  21      * a new promise resolving to the return value of the called handler.
  22      *
  23      * @param callable $onFulfilled Invoked when the promise fulfills.
  24      * @param callable $onRejected  Invoked when the promise is rejected.
  25      *
  26      * @return PromiseInterface
  27      */
  28     public function then(
  29         callable $onFulfilled = null,
  30         callable $onRejected = null
  31     );
  32
  33     /**
  34      * Appends a rejection handler callback to the promise, and returns a new
  35      * promise resolving to the return value of the callback if it is called,
  36      * or to its original fulfillment value if the promise is instead
  37      * fulfilled.
  38      *
  39      * @param callable $onRejected Invoked when the promise is rejected.
  40      *
  41      * @return PromiseInterface
  42      */
  43     public function otherwise(callable $onRejected);
  44
  45     /**
  46      * Get the state of the promise ("pending", "rejected", or "fulfilled").
  47      *
  48      * The three states can be checked against the constants defined on
  49      * PromiseInterface: PENDING, FULFILLED, and REJECTED.
  50      *
  51      * @return string
  52      */
  53     public function getState();
  54
  55     /**
  56      * Resolve the promise with the given value.
  57      *
  58      * @param mixed $value
  59      * @throws \RuntimeException if the promise is already resolved.
  60      */
  61     public function resolve($value);
  62
  63     /**
  64      * Reject the promise with the given reason.
  65      *
  66      * @param mixed $reason
  67      * @throws \RuntimeException if the promise is already resolved.
  68      */
  69     public function reject($reason);
  70
  71     /**
  72      * Cancels the promise if possible.
  73      *
  74      * @link https://github.com/promises-aplus/cancellation-spec/issues/7
  75      */
  76     public function cancel();
  77
  78     /**
  79      * Waits until the promise completes if possible.
  80      *
  81      * Pass $unwrap as true to unwrap the result of the promise, either
  82      * returning the resolved value or throwing the rejected exception.
  83      *
  84      * If the promise cannot be waited on, then the promise will be rejected.
  85      *
  86      * @param bool $unwrap
  87      *
  88      * @return mixed
  89      * @throws \LogicException if the promise has no wait function or if the
  90      *                         promise does not settle after waiting.
  91      */
  92     public function wait($unwrap = true);
  93 }