php-opencloud / openstack

src/Common/Resource/HasWaiterTrait.php

<?php declare(strict_types=1);

namespace OpenStack\Common\Resource;

use OpenStack\Common\Error\BadResponseError;

/**
 * Contains reusable functionality for resources that have long operations which require waiting in
 * order to reach a particular state.
 *
 * @codeCoverageIgnore
 *
 * @package OpenStack\Common\Resource
 */
trait HasWaiterTrait
{
    /**
     * Provides a blocking operation until the resource has reached a particular state. The method
     * will enter a loop, requesting feedback from the remote API until it sends back an appropriate
     * status.
     *
     * @param string $status      The state to be reached
     * @param int    $timeout     The maximum timeout. If the total time taken by the waiter has reached
     *                            or exceed this timeout, the blocking operation will immediately cease.
     * @param int    $sleepPeriod The amount of time to pause between each HTTP request.
     */
    public function waitUntil(string $status, $timeout = 60, int $sleepPeriod = 1)
    {
        $startTime = time();

        while (true) {
            $this->retrieve();

It seems like retrieve() must be provided by classes using this trait. How about adding it as abstract method to this trait?

            if ($this->status == $status || $this->shouldHalt($timeout, $startTime)) {

The property status does not exist. Did you maybe forget to declare it?

                break;
            }

            sleep($sleepPeriod);
        }
    }

    /**
     * Provides a blocking operation until the resource has reached a particular state. The method
     * will enter a loop, executing the callback until TRUE is returned. This provides great
     * flexibility.
     *
     * @param callable $fn          An anonymous function that will be executed on every iteration. You can
     *                              encapsulate your own logic to determine whether the resource has
     *                              successfully transitioned. When TRUE is returned by the callback,
     *                              the loop will end.
     * @param int|bool $timeout     The maximum timeout in seconds. If the total time taken by the waiter has reached
     *                              or exceed this timeout, the blocking operation will immediately cease. If FALSE
     *                              is provided, the timeout will never be considered.
     * @param int      $sleepPeriod The amount of time to pause between each HTTP request.
     */
    public function waitWithCallback(callable $fn, $timeout = 60, int $sleepPeriod = 1)
    {
        $startTime = time();

        while (true) {
            $this->retrieve();

It seems like retrieve() must be provided by classes using this trait. How about adding it as abstract method to this trait?

            $response = call_user_func_array($fn, [$this]);

            if ($response === true || $this->shouldHalt($timeout, $startTime)) {
                break;
            }

            sleep($sleepPeriod);
        }
    }

    /**
     * Internal method used to identify whether a timeout has been exceeded.
     *
     * @param bool|int $timeout
     * @param int      $startTime
     *
     * @return bool
     */
    private function shouldHalt($timeout, int $startTime)
    {
        if ($timeout === false) {
            return false;
        }

        return time() - $startTime >= $timeout;
    }

    /**
     * Convenience method providing a blocking operation until the resource transitions to an
     * ``ACTIVE`` status.
     *
     * @param int|bool $timeout The maximum timeout in seconds. If the total time taken by the waiter has reached
     *                          or exceed this timeout, the blocking operation will immediately cease. If FALSE
     *                          is provided, the timeout will never be considered.
     */
    public function waitUntilActive($timeout = false)
    {
        $this->waitUntil('ACTIVE', $timeout);

It seems like $timeout defined by parameter $timeout on line 98 can also be of type boolean; however, OpenStack\Common\Resource\HasWaiterTrait::waitUntil() does only seem to accept integer, maybe add an additional type check?

    }

    public function waitUntilDeleted($timeout = 60, int $sleepPeriod = 1)
    {
        $startTime = time();

        while (true) {
            try {
                $this->retrieve();

It seems like retrieve() must be provided by classes using this trait. How about adding it as abstract method to this trait?

            } catch (BadResponseError $e) {
                if ($e->getResponse()->getStatusCode() === 404) {
                    break;
                }
                throw $e;
            }

            if ($this->shouldHalt($timeout, $startTime)) {
                break;
            }

            sleep($sleepPeriod);
        }
    }
}