313 lines
8.3 KiB
PHP
313 lines
8.3 KiB
PHP
<?php
|
|
|
|
namespace Stripe;
|
|
|
|
/**
|
|
* Class Collection.
|
|
*
|
|
* @template TStripeObject of StripeObject
|
|
* @template-implements \IteratorAggregate<TStripeObject>
|
|
*
|
|
* @property string $object
|
|
* @property string $url
|
|
* @property bool $has_more
|
|
* @property TStripeObject[] $data
|
|
*/
|
|
class Collection extends StripeObject implements \Countable, \IteratorAggregate
|
|
{
|
|
const OBJECT_NAME = 'list';
|
|
|
|
use ApiOperations\Request;
|
|
|
|
/** @var array */
|
|
protected $filters = [];
|
|
|
|
/**
|
|
* @return string the base URL for the given class
|
|
*/
|
|
public static function baseUrl()
|
|
{
|
|
return Stripe::$apiBase;
|
|
}
|
|
|
|
/**
|
|
* Returns the filters.
|
|
*
|
|
* @return array the filters
|
|
*/
|
|
public function getFilters()
|
|
{
|
|
return $this->filters;
|
|
}
|
|
|
|
/**
|
|
* Sets the filters, removing paging options.
|
|
*
|
|
* @param array $filters the filters
|
|
*/
|
|
public function setFilters($filters)
|
|
{
|
|
$this->filters = $filters;
|
|
}
|
|
|
|
#[\ReturnTypeWillChange]
|
|
public function offsetGet($k)
|
|
{
|
|
if (\is_string($k)) {
|
|
return parent::offsetGet($k);
|
|
}
|
|
$msg = "You tried to access the {$k} index, but Collection " .
|
|
'types only support string keys. (HINT: List calls ' .
|
|
'return an object with a `data` (which is the data ' .
|
|
"array). You likely want to call ->data[{$k}])";
|
|
|
|
throw new Exception\InvalidArgumentException($msg);
|
|
}
|
|
|
|
/**
|
|
* @param null|array $params
|
|
* @param null|array|string $opts
|
|
*
|
|
* @throws Exception\ApiErrorException
|
|
*
|
|
* @return Collection<TStripeObject>
|
|
*/
|
|
public function all($params = null, $opts = null)
|
|
{
|
|
self::_validateParams($params);
|
|
list($url, $params) = $this->extractPathAndUpdateParams($params);
|
|
|
|
list($response, $opts) = $this->_request('get', $url, $params, $opts);
|
|
$obj = Util\Util::convertToStripeObject($response, $opts);
|
|
if (!($obj instanceof \Stripe\Collection)) {
|
|
throw new \Stripe\Exception\UnexpectedValueException(
|
|
'Expected type ' . \Stripe\Collection::class . ', got "' . \get_class($obj) . '" instead.'
|
|
);
|
|
}
|
|
$obj->setFilters($params);
|
|
|
|
return $obj;
|
|
}
|
|
|
|
/**
|
|
* @param null|array $params
|
|
* @param null|array|string $opts
|
|
*
|
|
* @throws Exception\ApiErrorException
|
|
*
|
|
* @return TStripeObject
|
|
*/
|
|
public function create($params = null, $opts = null)
|
|
{
|
|
self::_validateParams($params);
|
|
list($url, $params) = $this->extractPathAndUpdateParams($params);
|
|
|
|
list($response, $opts) = $this->_request('post', $url, $params, $opts);
|
|
|
|
return Util\Util::convertToStripeObject($response, $opts);
|
|
}
|
|
|
|
/**
|
|
* @param string $id
|
|
* @param null|array $params
|
|
* @param null|array|string $opts
|
|
*
|
|
* @throws Exception\ApiErrorException
|
|
*
|
|
* @return TStripeObject
|
|
*/
|
|
public function retrieve($id, $params = null, $opts = null)
|
|
{
|
|
self::_validateParams($params);
|
|
list($url, $params) = $this->extractPathAndUpdateParams($params);
|
|
|
|
$id = Util\Util::utf8($id);
|
|
$extn = \urlencode($id);
|
|
list($response, $opts) = $this->_request(
|
|
'get',
|
|
"{$url}/{$extn}",
|
|
$params,
|
|
$opts
|
|
);
|
|
|
|
return Util\Util::convertToStripeObject($response, $opts);
|
|
}
|
|
|
|
/**
|
|
* @return int the number of objects in the current page
|
|
*/
|
|
#[\ReturnTypeWillChange]
|
|
public function count()
|
|
{
|
|
return \count($this->data);
|
|
}
|
|
|
|
/**
|
|
* @return \ArrayIterator an iterator that can be used to iterate
|
|
* across objects in the current page
|
|
*/
|
|
#[\ReturnTypeWillChange]
|
|
public function getIterator()
|
|
{
|
|
return new \ArrayIterator($this->data);
|
|
}
|
|
|
|
/**
|
|
* @return \ArrayIterator an iterator that can be used to iterate
|
|
* backwards across objects in the current page
|
|
*/
|
|
public function getReverseIterator()
|
|
{
|
|
return new \ArrayIterator(\array_reverse($this->data));
|
|
}
|
|
|
|
/**
|
|
* @return \Generator|TStripeObject[] A generator that can be used to
|
|
* iterate across all objects across all pages. As page boundaries are
|
|
* encountered, the next page will be fetched automatically for
|
|
* continued iteration.
|
|
*/
|
|
public function autoPagingIterator()
|
|
{
|
|
$page = $this;
|
|
|
|
while (true) {
|
|
$filters = $this->filters ?: [];
|
|
if (\array_key_exists('ending_before', $filters)
|
|
&& !\array_key_exists('starting_after', $filters)) {
|
|
foreach ($page->getReverseIterator() as $item) {
|
|
yield $item;
|
|
}
|
|
$page = $page->previousPage();
|
|
} else {
|
|
foreach ($page as $item) {
|
|
yield $item;
|
|
}
|
|
$page = $page->nextPage();
|
|
}
|
|
|
|
if ($page->isEmpty()) {
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Returns an empty collection. This is returned from {@see nextPage()}
|
|
* when we know that there isn't a next page in order to replicate the
|
|
* behavior of the API when it attempts to return a page beyond the last.
|
|
*
|
|
* @param null|array|string $opts
|
|
*
|
|
* @return Collection
|
|
*/
|
|
public static function emptyCollection($opts = null)
|
|
{
|
|
return Collection::constructFrom(['data' => []], $opts);
|
|
}
|
|
|
|
/**
|
|
* Returns true if the page object contains no element.
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function isEmpty()
|
|
{
|
|
return empty($this->data);
|
|
}
|
|
|
|
/**
|
|
* Fetches the next page in the resource list (if there is one).
|
|
*
|
|
* This method will try to respect the limit of the current page. If none
|
|
* was given, the default limit will be fetched again.
|
|
*
|
|
* @param null|array $params
|
|
* @param null|array|string $opts
|
|
*
|
|
* @return Collection<TStripeObject>
|
|
*/
|
|
public function nextPage($params = null, $opts = null)
|
|
{
|
|
if (!$this->has_more) {
|
|
return static::emptyCollection($opts);
|
|
}
|
|
|
|
$lastId = \end($this->data)->id;
|
|
|
|
$params = \array_merge(
|
|
$this->filters ?: [],
|
|
['starting_after' => $lastId],
|
|
$params ?: []
|
|
);
|
|
|
|
return $this->all($params, $opts);
|
|
}
|
|
|
|
/**
|
|
* Fetches the previous page in the resource list (if there is one).
|
|
*
|
|
* This method will try to respect the limit of the current page. If none
|
|
* was given, the default limit will be fetched again.
|
|
*
|
|
* @param null|array $params
|
|
* @param null|array|string $opts
|
|
*
|
|
* @return Collection<TStripeObject>
|
|
*/
|
|
public function previousPage($params = null, $opts = null)
|
|
{
|
|
if (!$this->has_more) {
|
|
return static::emptyCollection($opts);
|
|
}
|
|
|
|
$firstId = $this->data[0]->id;
|
|
|
|
$params = \array_merge(
|
|
$this->filters ?: [],
|
|
['ending_before' => $firstId],
|
|
$params ?: []
|
|
);
|
|
|
|
return $this->all($params, $opts);
|
|
}
|
|
|
|
/**
|
|
* Gets the first item from the current page. Returns `null` if the current page is empty.
|
|
*
|
|
* @return null|TStripeObject
|
|
*/
|
|
public function first()
|
|
{
|
|
return \count($this->data) > 0 ? $this->data[0] : null;
|
|
}
|
|
|
|
/**
|
|
* Gets the last item from the current page. Returns `null` if the current page is empty.
|
|
*
|
|
* @return null|TStripeObject
|
|
*/
|
|
public function last()
|
|
{
|
|
return \count($this->data) > 0 ? $this->data[\count($this->data) - 1] : null;
|
|
}
|
|
|
|
private function extractPathAndUpdateParams($params)
|
|
{
|
|
$url = \parse_url($this->url);
|
|
if (!isset($url['path'])) {
|
|
throw new Exception\UnexpectedValueException("Could not parse list url into parts: {$url}");
|
|
}
|
|
|
|
if (isset($url['query'])) {
|
|
// If the URL contains a query param, parse it out into $params so they
|
|
// don't interact weirdly with each other.
|
|
$query = [];
|
|
\parse_str($url['query'], $query);
|
|
$params = \array_merge($params ?: [], $query);
|
|
}
|
|
|
|
return [$url['path'], $params];
|
|
}
|
|
}
|