IPromise.php 2.1 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-License-Identifier: AGPL-3.0-or-later
  6. */
  7. namespace OCP\Http\Client;
  8. use Exception;
  9. use LogicException;
  10. /**
  11. * A wrapper around Guzzle's PromiseInterface
  12. * @see \GuzzleHttp\Promise\PromiseInterface
  13. * @since 28.0.0
  14. */
  15. interface IPromise {
  16. /**
  17. * @since 28.0.0
  18. */
  19. public const STATE_PENDING = 'pending';
  20. /**
  21. * @since 28.0.0
  22. */
  23. public const STATE_FULFILLED = 'fulfilled';
  24. /**
  25. * @since 28.0.0
  26. */
  27. public const STATE_REJECTED = 'rejected';
  28. /**
  29. * Appends fulfillment and rejection handlers to the promise, and returns
  30. * a new promise resolving to the return value of the called handler.
  31. *
  32. * @param ?callable(IResponse): void $onFulfilled Invoked when the promise fulfills. Gets an \OCP\Http\Client\IResponse passed in as argument
  33. * @param ?callable(Exception): void $onRejected Invoked when the promise is rejected. Gets an \Exception passed in as argument
  34. *
  35. * @return IPromise
  36. * @since 28.0.0
  37. */
  38. public function then(
  39. ?callable $onFulfilled = null,
  40. ?callable $onRejected = null,
  41. ): IPromise;
  42. /**
  43. * Get the state of the promise ("pending", "rejected", or "fulfilled").
  44. *
  45. * The three states can be checked against the constants defined:
  46. * STATE_PENDING, STATE_FULFILLED, and STATE_REJECTED.
  47. *
  48. * @return self::STATE_*
  49. * @since 28.0.0
  50. */
  51. public function getState(): string;
  52. /**
  53. * Cancels the promise if possible.
  54. *
  55. * @link https://github.com/promises-aplus/cancellation-spec/issues/7
  56. * @since 28.0.0
  57. */
  58. public function cancel(): void;
  59. /**
  60. * Waits until the promise completes if possible.
  61. *
  62. * Pass $unwrap as true to unwrap the result of the promise, either
  63. * returning the resolved value or throwing the rejected exception.
  64. *
  65. * If the promise cannot be waited on, then the promise will be rejected.
  66. *
  67. * @param bool $unwrap
  68. *
  69. * @return mixed
  70. *
  71. * @throws LogicException if the promise has no wait function or if the
  72. * promise does not settle after waiting.
  73. * @since 28.0.0
  74. */
  75. public function wait(bool $unwrap = true): mixed;
  76. }