Cursor.php

TLDR

The Cursor.php file in the Illuminate\Pagination namespace defines a Cursor class that is responsible for managing and manipulating cursors used in pagination. The Cursor class implements the Arrayable interface and provides methods for creating, retrieving, and encoding cursors.

Methods

__construct

The __construct method is the constructor of the Cursor class. It initializes the cursor with the given parameters and sets the direction of the cursor (whether it points to the next or previous items).

parameter

The parameter method retrieves the value of a specific parameter from the cursor. It takes a parameter name as an argument and returns the corresponding parameter value. If the parameter does not exist, it throws an UnexpectedValueException.

parameters

The parameters method retrieves multiple parameters from the cursor. It takes an array of parameter names as an argument and returns an array of corresponding parameter values.

pointsToNextItems

The pointsToNextItems method determines whether the cursor points to the next set of items. It returns a boolean value indicating the direction of the cursor.

pointsToPreviousItems

The pointsToPreviousItems method determines whether the cursor points to the previous set of items. It returns a boolean value opposite to the pointsToNextItems method.

toArray

The toArray method returns the array representation of the cursor. It merges the cursor's parameters with an additional _pointsToNextItems key indicating the direction of the cursor.

encode

The encode method returns the encoded string representation of the cursor, which can be used to construct a URL. It base64 encodes the JSON representation of the cursor's array representation and replaces certain characters to make the string URL-safe.

fromEncoded

The fromEncoded method creates a Cursor instance from an encoded string representation. It takes an encoded string as an argument and returns a Cursor object if the decoding and JSON parsing are successful. If the input is not a string or the decoding fails, it returns null.

<?php

namespace Illuminate\Pagination;

use Illuminate\Contracts\Support\Arrayable;
use UnexpectedValueException;

class Cursor implements Arrayable
{
    /**
     * The parameters associated with the cursor.
     *
     * @var array
     */
    protected $parameters;

    /**
     * Determine whether the cursor points to the next or previous set of items.
     *
     * @var bool
     */
    protected $pointsToNextItems;

    /**
     * Create a new cursor instance.
     *
     * @param  array  $parameters
     * @param  bool  $pointsToNextItems
     */
    public function __construct(array $parameters, $pointsToNextItems = true)
    {
        $this->parameters = $parameters;
        $this->pointsToNextItems = $pointsToNextItems;
    }

    /**
     * Get the given parameter from the cursor.
     *
     * @param  string  $parameterName
     * @return string|null
     *
     * @throws \UnexpectedValueException
     */
    public function parameter(string $parameterName)
    {
        if (! array_key_exists($parameterName, $this->parameters)) {
            throw new UnexpectedValueException("Unable to find parameter [{$parameterName}] in pagination item.");
        }

        return $this->parameters[$parameterName];
    }

    /**
     * Get the given parameters from the cursor.
     *
     * @param  array  $parameterNames
     * @return array
     */
    public function parameters(array $parameterNames)
    {
        return collect($parameterNames)->map(function ($parameterName) {
            return $this->parameter($parameterName);
        })->toArray();
    }

    /**
     * Determine whether the cursor points to the next set of items.
     *
     * @return bool
     */
    public function pointsToNextItems()
    {
        return $this->pointsToNextItems;
    }

    /**
     * Determine whether the cursor points to the previous set of items.
     *
     * @return bool
     */
    public function pointsToPreviousItems()
    {
        return ! $this->pointsToNextItems;
    }

    /**
     * Get the array representation of the cursor.
     *
     * @return array
     */
    public function toArray()
    {
        return array_merge($this->parameters, [
            '_pointsToNextItems' => $this->pointsToNextItems,
        ]);
    }

    /**
     * Get the encoded string representation of the cursor to construct a URL.
     *
     * @return string
     */
    public function encode()
    {
        return str_replace(['+', '/', '='], ['-', '_', ''], base64_encode(json_encode($this->toArray())));
    }

    /**
     * Get a cursor instance from the encoded string representation.
     *
     * @param  string|null  $encodedString
     * @return static|null
     */
    public static function fromEncoded($encodedString)
    {
        if (! is_string($encodedString)) {
            return null;
        }

        $parameters = json_decode(base64_decode(str_replace(['-', '_'], ['+', '/'], $encodedString)), true);

        if (json_last_error() !== JSON_ERROR_NONE) {
            return null;
        }

        $pointsToNextItems = $parameters['_pointsToNextItems'];

        unset($parameters['_pointsToNextItems']);

        return new static($parameters, $pointsToNextItems);
    }
}