AbstractCursorPaginator.php
TLDR
This file, AbstractCursorPaginator.php, is a class that provides pagination functionality for a list of items. It is an abstract class that can be extended to implement specific pagination logic.
Methods
url($cursor)
This method returns the URL for a given cursor.
previousPageUrl()
This method returns the URL for the previous page.
nextPageUrl()
This method returns the URL for the next page.
previousCursor()
This method returns the cursor that points to the previous set of items.
nextCursor()
This method returns the cursor that points to the next set of items.
getCursorForItem($item, $isNext = true)
This method returns a cursor instance for the given item.
getParametersForItem($item)
This method returns the cursor parameters for a given item.
getPivotParameterForItem($item, $parameterName)
This method returns the cursor parameter value from a pivot model if applicable.
ensureParameterIsPrimitive($parameter)
This method ensures that the parameter is a primitive type.
fragment($fragment = null)
This method gets or sets the URL fragment to be appended to URLs.
appends($key, $value = null)
This method adds a set of query string values to the paginator.
withQueryString()
This method adds all current query string values to the paginator.
addQuery($key, $value)
This method adds a query string value to the paginator.
buildFragment()
This method builds the full fragment portion of a URL.
loadMorph($relation, $relations)
This method loads a set of relationships onto the mixed relationship collection.
loadMorphCount($relation, $relations)
This method loads a set of relationship counts onto the mixed relationship collection.
items()
This method gets the slice of items being paginated.
through($callback)
This method transforms each item in the slice of items using a callback.
perPage()
This method gets the number of items shown per page.
cursor()
This method gets the current cursor being paginated.
getCursorName()
This method gets the query string variable used to store the cursor.
setCursorName($name)
This method sets the query string variable used to store the cursor.
withPath($path)
This method sets the base path to assign to all URLs.
path()
This method gets the base path for paginator generated URLs.
resolveCurrentCursor($cursorName = 'cursor', $default = null)
This method resolves the current cursor or returns the default value.
currentCursorResolver(Closure $resolver)
This method sets the current cursor resolver callback.
viewFactory()
This method gets an instance of the view factory from the resolver.
getIterator()
This method gets an iterator for the items.
isEmpty()
This method determines if the list of items is empty.
isNotEmpty()
This method determines if the list of items is not empty.
count()
This method gets the number of items for the current page.
getCollection()
This method gets the paginator's underlying collection.
setCollection(Collection $collection)
This method sets the paginator's underlying collection.
getOptions()
This method gets the paginator options.
offsetExists($key)
This method determines if the given item exists.
offsetGet($key)
This method gets the item at the given offset.
offsetSet($key, $value)
This method sets the item at the given offset.
offsetUnset($key)
This method unsets the item at the given key.
toHtml()
This method renders the contents of the paginator to HTML.
__call($method, $parameters)
This magic method forwards dynamic calls to the underlying collection.
__toString()
This magic method renders the contents of the paginator when casting to a string.
Classes
No classes found in the provided file.
<?php
namespace Illuminate\Pagination;
use ArrayAccess;
use Closure;
use Exception;
use Illuminate\Contracts\Support\Htmlable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\Pivot;
use Illuminate\Http\Resources\Json\JsonResource;
use Illuminate\Support\Arr;
use Illuminate\Support\Collection;
use Illuminate\Support\Str;
use Illuminate\Support\Traits\ForwardsCalls;
use Illuminate\Support\Traits\Tappable;
use Stringable;
use Traversable;
/**
* @mixin \Illuminate\Support\Collection
*/
abstract class AbstractCursorPaginator implements Htmlable, Stringable
{
use ForwardsCalls, Tappable;
/**
* All of the items being paginated.
*
* @var \Illuminate\Support\Collection
*/
protected $items;
/**
* The number of items to be shown per page.
*
* @var int
*/
protected $perPage;
/**
* The base path to assign to all URLs.
*
* @var string
*/
protected $path = '/';
/**
* The query parameters to add to all URLs.
*
* @var array
*/
protected $query = [];
/**
* The URL fragment to add to all URLs.
*
* @var string|null
*/
protected $fragment;
/**
* The cursor string variable used to store the page.
*
* @var string
*/
protected $cursorName = 'cursor';
/**
* The current cursor.
*
* @var \Illuminate\Pagination\Cursor|null
*/
protected $cursor;
/**
* The paginator parameters for the cursor.
*
* @var array
*/
protected $parameters;
/**
* The paginator options.
*
* @var array
*/
protected $options;
/**
* The current cursor resolver callback.
*
* @var \Closure
*/
protected static $currentCursorResolver;
/**
* Get the URL for a given cursor.
*
* @param \Illuminate\Pagination\Cursor|null $cursor
* @return string
*/
public function url($cursor)
{
// If we have any extra query string key / value pairs that need to be added
// onto the URL, we will put them in query string form and then attach it
// to the URL. This allows for extra information like sortings storage.
$parameters = is_null($cursor) ? [] : [$this->cursorName => $cursor->encode()];
if (count($this->query) > 0) {
$parameters = array_merge($this->query, $parameters);
}
return $this->path()
.(str_contains($this->path(), '?') ? '&' : '?')
.Arr::query($parameters)
.$this->buildFragment();
}
/**
* Get the URL for the previous page.
*
* @return string|null
*/
public function previousPageUrl()
{
if (is_null($previousCursor = $this->previousCursor())) {
return null;
}
return $this->url($previousCursor);
}
/**
* The URL for the next page, or null.
*
* @return string|null
*/
public function nextPageUrl()
{
if (is_null($nextCursor = $this->nextCursor())) {
return null;
}
return $this->url($nextCursor);
}
/**
* Get the "cursor" that points to the previous set of items.
*
* @return \Illuminate\Pagination\Cursor|null
*/
public function previousCursor()
{
if (is_null($this->cursor) ||
($this->cursor->pointsToPreviousItems() && ! $this->hasMore)) {
return null;
}
if ($this->items->isEmpty()) {
return null;
}
return $this->getCursorForItem($this->items->first(), false);
}
/**
* Get the "cursor" that points to the next set of items.
*
* @return \Illuminate\Pagination\Cursor|null
*/
public function nextCursor()
{
if ((is_null($this->cursor) && ! $this->hasMore) ||
(! is_null($this->cursor) && $this->cursor->pointsToNextItems() && ! $this->hasMore)) {
return null;
}
if ($this->items->isEmpty()) {
return null;
}
return $this->getCursorForItem($this->items->last(), true);
}
/**
* Get a cursor instance for the given item.
*
* @param \ArrayAccess|\stdClass $item
* @param bool $isNext
* @return \Illuminate\Pagination\Cursor
*/
public function getCursorForItem($item, $isNext = true)
{
return new Cursor($this->getParametersForItem($item), $isNext);
}
/**
* Get the cursor parameters for a given object.
*
* @param \ArrayAccess|\stdClass $item
* @return array
*
* @throws \Exception
*/
public function getParametersForItem($item)
{
return collect($this->parameters)
->flip()
->map(function ($_, $parameterName) use ($item) {
if ($item instanceof JsonResource) {
$item = $item->resource;
}
if ($item instanceof Model &&
! is_null($parameter = $this->getPivotParameterForItem($item, $parameterName))) {
return $parameter;
} elseif ($item instanceof ArrayAccess || is_array($item)) {
return $this->ensureParameterIsPrimitive(
$item[$parameterName] ?? $item[Str::afterLast($parameterName, '.')]
);
} elseif (is_object($item)) {
return $this->ensureParameterIsPrimitive(
$item->{$parameterName} ?? $item->{Str::afterLast($parameterName, '.')}
);
}
throw new Exception('Only arrays and objects are supported when cursor paginating items.');
})->toArray();
}
/**
* Get the cursor parameter value from a pivot model if applicable.
*
* @param \ArrayAccess|\stdClass $item
* @param string $parameterName
* @return string|null
*/
protected function getPivotParameterForItem($item, $parameterName)
{
$table = Str::beforeLast($parameterName, '.');
foreach ($item->getRelations() as $relation) {
if ($relation instanceof Pivot && $relation->getTable() === $table) {
return $this->ensureParameterIsPrimitive(
$relation->getAttribute(Str::afterLast($parameterName, '.'))
);
}
}
}
/**
* Ensure the parameter is a primitive type.
*
* This can resolve issues that arise the developer uses a value object for an attribute.
*
* @param mixed $parameter
* @return mixed
*/
protected function ensureParameterIsPrimitive($parameter)
{
return is_object($parameter) && method_exists($parameter, '__toString')
? (string) $parameter
: $parameter;
}
/**
* Get / set the URL fragment to be appended to URLs.
*
* @param string|null $fragment
* @return $this|string|null
*/
public function fragment($fragment = null)
{
if (is_null($fragment)) {
return $this->fragment;
}
$this->fragment = $fragment;
return $this;
}
/**
* Add a set of query string values to the paginator.
*
* @param array|string|null $key
* @param string|null $value
* @return $this
*/
public function appends($key, $value = null)
{
if (is_null($key)) {
return $this;
}
if (is_array($key)) {
return $this->appendArray($key);
}
return $this->addQuery($key, $value);
}
/**
* Add an array of query string values.
*
* @param array $keys
* @return $this
*/
protected function appendArray(array $keys)
{
foreach ($keys as $key => $value) {
$this->addQuery($key, $value);
}
return $this;
}
/**
* Add all current query string values to the paginator.
*
* @return $this
*/
public function withQueryString()
{
if (! is_null($query = Paginator::resolveQueryString())) {
return $this->appends($query);
}
return $this;
}
/**
* Add a query string value to the paginator.
*
* @param string $key
* @param string $value
* @return $this
*/
protected function addQuery($key, $value)
{
if ($key !== $this->cursorName) {
$this->query[$key] = $value;
}
return $this;
}
/**
* Build the full fragment portion of a URL.
*
* @return string
*/
protected function buildFragment()
{
return $this->fragment ? '#'.$this->fragment : '';
}
/**
* Load a set of relationships onto the mixed relationship collection.
*
* @param string $relation
* @param array $relations
* @return $this
*/
public function loadMorph($relation, $relations)
{
$this->getCollection()->loadMorph($relation, $relations);
return $this;
}
/**
* Load a set of relationship counts onto the mixed relationship collection.
*
* @param string $relation
* @param array $relations
* @return $this
*/
public function loadMorphCount($relation, $relations)
{
$this->getCollection()->loadMorphCount($relation, $relations);
return $this;
}
/**
* Get the slice of items being paginated.
*
* @return array
*/
public function items()
{
return $this->items->all();
}
/**
* Transform each item in the slice of items using a callback.
*
* @param callable $callback
* @return $this
*/
public function through(callable $callback)
{
$this->items->transform($callback);
return $this;
}
/**
* Get the number of items shown per page.
*
* @return int
*/
public function perPage()
{
return $this->perPage;
}
/**
* Get the current cursor being paginated.
*
* @return \Illuminate\Pagination\Cursor|null
*/
public function cursor()
{
return $this->cursor;
}
/**
* Get the query string variable used to store the cursor.
*
* @return string
*/
public function getCursorName()
{
return $this->cursorName;
}
/**
* Set the query string variable used to store the cursor.
*
* @param string $name
* @return $this
*/
public function setCursorName($name)
{
$this->cursorName = $name;
return $this;
}
/**
* Set the base path to assign to all URLs.
*
* @param string $path
* @return $this
*/
public function withPath($path)
{
return $this->setPath($path);
}
/**
* Set the base path to assign to all URLs.
*
* @param string $path
* @return $this
*/
public function setPath($path)
{
$this->path = $path;
return $this;
}
/**
* Get the base path for paginator generated URLs.
*
* @return string|null
*/
public function path()
{
return $this->path;
}
/**
* Resolve the current cursor or return the default value.
*
* @param string $cursorName
* @return \Illuminate\Pagination\Cursor|null
*/
public static function resolveCurrentCursor($cursorName = 'cursor', $default = null)
{
if (isset(static::$currentCursorResolver)) {
return call_user_func(static::$currentCursorResolver, $cursorName);
}
return $default;
}
/**
* Set the current cursor resolver callback.
*
* @param \Closure $resolver
* @return void
*/
public static function currentCursorResolver(Closure $resolver)
{
static::$currentCursorResolver = $resolver;
}
/**
* Get an instance of the view factory from the resolver.
*
* @return \Illuminate\Contracts\View\Factory
*/
public static function viewFactory()
{
return Paginator::viewFactory();
}
/**
* Get an iterator for the items.
*
* @return \ArrayIterator
*/
public function getIterator(): Traversable
{
return $this->items->getIterator();
}
/**
* Determine if the list of items is empty.
*
* @return bool
*/
public function isEmpty()
{
return $this->items->isEmpty();
}
/**
* Determine if the list of items is not empty.
*
* @return bool
*/
public function isNotEmpty()
{
return $this->items->isNotEmpty();
}
/**
* Get the number of items for the current page.
*
* @return int
*/
public function count(): int
{
return $this->items->count();
}
/**
* Get the paginator's underlying collection.
*
* @return \Illuminate\Support\Collection
*/
public function getCollection()
{
return $this->items;
}
/**
* Set the paginator's underlying collection.
*
* @param \Illuminate\Support\Collection $collection
* @return $this
*/
public function setCollection(Collection $collection)
{
$this->items = $collection;
return $this;
}
/**
* Get the paginator options.
*
* @return array
*/
public function getOptions()
{
return $this->options;
}
/**
* Determine if the given item exists.
*
* @param mixed $key
* @return bool
*/
public function offsetExists($key): bool
{
return $this->items->has($key);
}
/**
* Get the item at the given offset.
*
* @param mixed $key
* @return mixed
*/
public function offsetGet($key): mixed
{
return $this->items->get($key);
}
/**
* Set the item at the given offset.
*
* @param mixed $key
* @param mixed $value
* @return void
*/
public function offsetSet($key, $value): void
{
$this->items->put($key, $value);
}
/**
* Unset the item at the given key.
*
* @param mixed $key
* @return void
*/
public function offsetUnset($key): void
{
$this->items->forget($key);
}
/**
* Render the contents of the paginator to HTML.
*
* @return string
*/
public function toHtml()
{
return (string) $this->render();
}
/**
* Make dynamic calls into the collection.
*
* @param string $method
* @param array $parameters
* @return mixed
*/
public function __call($method, $parameters)
{
return $this->forwardCallTo($this->getCollection(), $method, $parameters);
}
/**
* Render the contents of the paginator when casting to a string.
*
* @return string
*/
public function __toString()
{
return (string) $this->render();
}
}