Chris@18: <?php
Chris@18: 
Chris@18: namespace Drupal\jsonapi\Query;
Chris@18: 
Chris@18: use Drupal\Core\Cache\CacheableMetadata;
Chris@18: use Drupal\Core\Http\Exception\CacheableBadRequestHttpException;
Chris@18: 
Chris@18: /**
Chris@18:  * Value object for containing the requested offset and page parameters.
Chris@18:  *
Chris@18:  * @internal JSON:API maintains no PHP API since its API is the HTTP API. This
Chris@18:  *   class may change at any time and this will break any dependencies on it.
Chris@18:  *
Chris@18:  * @see https://www.drupal.org/project/jsonapi/issues/3032787
Chris@18:  * @see jsonapi.api.php
Chris@18:  */
Chris@18: class OffsetPage {
Chris@18: 
Chris@18:   /**
Chris@18:    * The JSON:API pagination key name.
Chris@18:    *
Chris@18:    * @var string
Chris@18:    */
Chris@18:   const KEY_NAME = 'page';
Chris@18: 
Chris@18:   /**
Chris@18:    * The offset key in the page parameter: page[offset].
Chris@18:    *
Chris@18:    * @var string
Chris@18:    */
Chris@18:   const OFFSET_KEY = 'offset';
Chris@18: 
Chris@18:   /**
Chris@18:    * The size key in the page parameter: page[limit].
Chris@18:    *
Chris@18:    * @var string
Chris@18:    */
Chris@18:   const SIZE_KEY = 'limit';
Chris@18: 
Chris@18:   /**
Chris@18:    * Default offset.
Chris@18:    *
Chris@18:    * @var int
Chris@18:    */
Chris@18:   const DEFAULT_OFFSET = 0;
Chris@18: 
Chris@18:   /**
Chris@18:    * Max size.
Chris@18:    *
Chris@18:    * @var int
Chris@18:    */
Chris@18:   const SIZE_MAX = 50;
Chris@18: 
Chris@18:   /**
Chris@18:    * The offset for the query.
Chris@18:    *
Chris@18:    * @var int
Chris@18:    */
Chris@18:   protected $offset;
Chris@18: 
Chris@18:   /**
Chris@18:    * The size of the query.
Chris@18:    *
Chris@18:    * @var int
Chris@18:    */
Chris@18:   protected $size;
Chris@18: 
Chris@18:   /**
Chris@18:    * Instantiates an OffsetPage object.
Chris@18:    *
Chris@18:    * @param int $offset
Chris@18:    *   The query offset.
Chris@18:    * @param int $size
Chris@18:    *   The query size limit.
Chris@18:    */
Chris@18:   public function __construct($offset, $size) {
Chris@18:     $this->offset = $offset;
Chris@18:     $this->size = $size;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Returns the current offset.
Chris@18:    *
Chris@18:    * @return int
Chris@18:    *   The query offset.
Chris@18:    */
Chris@18:   public function getOffset() {
Chris@18:     return $this->offset;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Returns the page size.
Chris@18:    *
Chris@18:    * @return int
Chris@18:    *   The requested size of the query result.
Chris@18:    */
Chris@18:   public function getSize() {
Chris@18:     return $this->size;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Creates an OffsetPage object from a query parameter.
Chris@18:    *
Chris@18:    * @param mixed $parameter
Chris@18:    *   The `page` query parameter from the Symfony request object.
Chris@18:    *
Chris@18:    * @return \Drupal\jsonapi\Query\OffsetPage
Chris@18:    *   An OffsetPage object with defaults.
Chris@18:    */
Chris@18:   public static function createFromQueryParameter($parameter) {
Chris@18:     if (!is_array($parameter)) {
Chris@18:       $cacheability = (new CacheableMetadata())->addCacheContexts(['url.query_args:page']);
Chris@18:       throw new CacheableBadRequestHttpException($cacheability, 'The page parameter needs to be an array.');
Chris@18:     }
Chris@18: 
Chris@18:     $expanded = $parameter + [
Chris@18:       static::OFFSET_KEY => static::DEFAULT_OFFSET,
Chris@18:       static::SIZE_KEY => static::SIZE_MAX,
Chris@18:     ];
Chris@18: 
Chris@18:     if ($expanded[static::SIZE_KEY] > static::SIZE_MAX) {
Chris@18:       $expanded[static::SIZE_KEY] = static::SIZE_MAX;
Chris@18:     }
Chris@18: 
Chris@18:     return new static($expanded[static::OFFSET_KEY], $expanded[static::SIZE_KEY]);
Chris@18:   }
Chris@18: 
Chris@18: }