annotate core/modules/jsonapi/src/Query/OffsetPage.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@18 1 <?php
Chris@18 2
Chris@18 3 namespace Drupal\jsonapi\Query;
Chris@18 4
Chris@18 5 use Drupal\Core\Cache\CacheableMetadata;
Chris@18 6 use Drupal\Core\Http\Exception\CacheableBadRequestHttpException;
Chris@18 7
Chris@18 8 /**
Chris@18 9 * Value object for containing the requested offset and page parameters.
Chris@18 10 *
Chris@18 11 * @internal JSON:API maintains no PHP API since its API is the HTTP API. This
Chris@18 12 * class may change at any time and this will break any dependencies on it.
Chris@18 13 *
Chris@18 14 * @see https://www.drupal.org/project/jsonapi/issues/3032787
Chris@18 15 * @see jsonapi.api.php
Chris@18 16 */
Chris@18 17 class OffsetPage {
Chris@18 18
Chris@18 19 /**
Chris@18 20 * The JSON:API pagination key name.
Chris@18 21 *
Chris@18 22 * @var string
Chris@18 23 */
Chris@18 24 const KEY_NAME = 'page';
Chris@18 25
Chris@18 26 /**
Chris@18 27 * The offset key in the page parameter: page[offset].
Chris@18 28 *
Chris@18 29 * @var string
Chris@18 30 */
Chris@18 31 const OFFSET_KEY = 'offset';
Chris@18 32
Chris@18 33 /**
Chris@18 34 * The size key in the page parameter: page[limit].
Chris@18 35 *
Chris@18 36 * @var string
Chris@18 37 */
Chris@18 38 const SIZE_KEY = 'limit';
Chris@18 39
Chris@18 40 /**
Chris@18 41 * Default offset.
Chris@18 42 *
Chris@18 43 * @var int
Chris@18 44 */
Chris@18 45 const DEFAULT_OFFSET = 0;
Chris@18 46
Chris@18 47 /**
Chris@18 48 * Max size.
Chris@18 49 *
Chris@18 50 * @var int
Chris@18 51 */
Chris@18 52 const SIZE_MAX = 50;
Chris@18 53
Chris@18 54 /**
Chris@18 55 * The offset for the query.
Chris@18 56 *
Chris@18 57 * @var int
Chris@18 58 */
Chris@18 59 protected $offset;
Chris@18 60
Chris@18 61 /**
Chris@18 62 * The size of the query.
Chris@18 63 *
Chris@18 64 * @var int
Chris@18 65 */
Chris@18 66 protected $size;
Chris@18 67
Chris@18 68 /**
Chris@18 69 * Instantiates an OffsetPage object.
Chris@18 70 *
Chris@18 71 * @param int $offset
Chris@18 72 * The query offset.
Chris@18 73 * @param int $size
Chris@18 74 * The query size limit.
Chris@18 75 */
Chris@18 76 public function __construct($offset, $size) {
Chris@18 77 $this->offset = $offset;
Chris@18 78 $this->size = $size;
Chris@18 79 }
Chris@18 80
Chris@18 81 /**
Chris@18 82 * Returns the current offset.
Chris@18 83 *
Chris@18 84 * @return int
Chris@18 85 * The query offset.
Chris@18 86 */
Chris@18 87 public function getOffset() {
Chris@18 88 return $this->offset;
Chris@18 89 }
Chris@18 90
Chris@18 91 /**
Chris@18 92 * Returns the page size.
Chris@18 93 *
Chris@18 94 * @return int
Chris@18 95 * The requested size of the query result.
Chris@18 96 */
Chris@18 97 public function getSize() {
Chris@18 98 return $this->size;
Chris@18 99 }
Chris@18 100
Chris@18 101 /**
Chris@18 102 * Creates an OffsetPage object from a query parameter.
Chris@18 103 *
Chris@18 104 * @param mixed $parameter
Chris@18 105 * The `page` query parameter from the Symfony request object.
Chris@18 106 *
Chris@18 107 * @return \Drupal\jsonapi\Query\OffsetPage
Chris@18 108 * An OffsetPage object with defaults.
Chris@18 109 */
Chris@18 110 public static function createFromQueryParameter($parameter) {
Chris@18 111 if (!is_array($parameter)) {
Chris@18 112 $cacheability = (new CacheableMetadata())->addCacheContexts(['url.query_args:page']);
Chris@18 113 throw new CacheableBadRequestHttpException($cacheability, 'The page parameter needs to be an array.');
Chris@18 114 }
Chris@18 115
Chris@18 116 $expanded = $parameter + [
Chris@18 117 static::OFFSET_KEY => static::DEFAULT_OFFSET,
Chris@18 118 static::SIZE_KEY => static::SIZE_MAX,
Chris@18 119 ];
Chris@18 120
Chris@18 121 if ($expanded[static::SIZE_KEY] > static::SIZE_MAX) {
Chris@18 122 $expanded[static::SIZE_KEY] = static::SIZE_MAX;
Chris@18 123 }
Chris@18 124
Chris@18 125 return new static($expanded[static::OFFSET_KEY], $expanded[static::SIZE_KEY]);
Chris@18 126 }
Chris@18 127
Chris@18 128 }