commerce_amws-8.x-1.x-dev/src/Api/ListClientTrait.php

<?php

namespace Drupal\commerce_amws\Api;

use KrystalCode\ApiIterator\Iterator;
use SellingPartnerApi\Model\ModelInterface;

/**
 * Provides methods for getting a list of items from Amazon MWS.
 */
trait ListClientTrait {

  /**
   * Fetches the list of items from the Selling Partner API.
   *
   * @param array $options
   *   An associative array of options. Supported options are:
   *   - limit (int): The number of items to get.
   * @param array $query
   *   An associative array containing additional query parameters to add to
   *   the request.
   *
   * @return \SellingPartnerApi\Model\ModelInterface
   *   The object containing the list of items.
   */
  abstract protected function listFetchList(array $options, array $query);

  /**
   * Returns the items held in the given list.
   *
   * @param \SellingPartnerApi\Model\ModelInterface $list
   *   The object containing the list of items.
   *
   * @return \SellingPartnerApi\Model\ModelInterface[]
   *   An array containing the items extracted from the list.
   */
  abstract protected function listGetItems(ModelInterface $list);

  /**
   * Implements `\KrystalCode\ApiIterator\ClientInterface::list()`.
   *
   * Note that the `page` option as defined in the interface is not
   * supported. The Selling Partner APIs use a token for getting the next page
   * of results.
   *
   * @param array $options
   *   An associative array of options. Supported options are:
   *   - limit (int): The number of items to get.
   *   - bypass_iterator (bool): The items are normally return wrapped in an
   *     API iterator. When the `bypass_iterator` option is set to, the items
   *     should be  returned without that extra wrapper iterator i.e. in just
   *     a `\CachingIterator`.
   * @param array $query
   *   An associative array containing additional query parameters to add to
   *   the request.
   *
   * @return \KrystalCode\ApiIterator\IteratorInterface|array|\CachingIterator
   *   - If the endpoint supports paging, an API iterator containing the
   *     items.
   *   - If the `bypass_iterator` option is set to `true`, an array containing
   *     the following elements in the given order.
   *     - \CachingIterator: An iterator containing the list items; items are
   *       `stdClass` objects.
   *     - int|null|false: The total number of pages, NULL if unknown, or
   *       FALSE if unknown but it is know that we have reached the last page.
   *     - array: The updated query array. This may be used to update the
   *       token or the URL that will be used to get the next page.
   *   - If the endpoint does not support paging, a `\CachingIterator`
   *     iterator containing the list items.
   *
   * @throws \InvalidArgumentException
   *   If options related to paging are set but the resource does not support
   *   paging.
   */
  public function list(array $options = [], array $query = []) {
    if (empty($options['bypass_iterator'])) {
      return new Iterator(
        $this,
        NULL,
        $options['limit'],
        $query
      );
    }

    unset($options['bypass_iterator']);

    $this->listValidateArguments($options, $query);
    $response = $this->listFetchList($options, $query);

    $list = $response->getPayload();
    $query['next_token'] = $list->getNextToken();

    $items = new \CachingIterator(
      new \ArrayIterator($this->listParseItems($list)),
      \CachingIterator::FULL_CACHE
    );

    return [
      $items,
      $query['next_token'] ? NULL : FALSE,
      $query,
    ];
  }

  /**
   * Validates the arguments given to retrieve a list of items.
   *
   * @param array $options
   *   The associative array of options passed to the `list` method for getting
   *   the list of items from Amazon MWS.
   * @param array $query
   *   The associative array of additional query parameters passed to the `list`
   *   method for getting the list of items from Amazon MWS.
   *
   * @throws \InvalidArgumentException
   *   When the options and the query arguments are invalid.
   *
   * @see \Drupal\commerce_amws_order\Api\ListClientTrait::list()
   */
  protected function listValidateArguments(
    array $options,
    array $query
  ) {
    // No validation required by default. Each client implementation can
    // override this method to provide its own validation as needed.
  }

  /**
   * Returns an array of the extracted, serialized items.
   *
   * Items are returned by the PHP SDK as objects that internally contain the
   * actual list of items that are PHP SDK objects. Here we convert them to an
   * array of `stdClass` objects as required by the Entity Synchronization
   * module.
   *
   * @param \SellingPartnerApi\Model\ModelInterface $list
   *   The list object.
   *
   * @return array
   *   An array containing the converted `stdClass` objects.
   */
  protected function listParseItems(ModelInterface $list) {
    return array_map(
      function ($item) {
        return $item->jsonSerialize();
      },
      $this->listGetItems($list)
    );
  }

}