vendor/pagerfanta/pagerfanta/lib/Core/Pagerfanta.php line 246

Open in your IDE?
  1. <?php declare(strict_types=1);
  3. namespace Pagerfanta;
  5. use Pagerfanta\Adapter\AdapterInterface;
  6. use Pagerfanta\Exception\LessThan1CurrentPageException;
  7. use Pagerfanta\Exception\LessThan1MaxPagesException;
  8. use Pagerfanta\Exception\LessThan1MaxPerPageException;
  9. use Pagerfanta\Exception\LogicException;
  10. use Pagerfanta\Exception\OutOfBoundsException;
  11. use Pagerfanta\Exception\OutOfRangeCurrentPageException;
  13. /**
  14. * @template T
  15. * @implements PagerfantaInterface<T>
  16. */
  17. class Pagerfanta implements PagerfantaInterface, \JsonSerializable
  18. {
  19. /**
  20. * @var AdapterInterface<T>
  21. */
  22. private AdapterInterface $adapter;
  24. private bool $allowOutOfRangePages = false;
  25. private bool $normalizeOutOfRangePages = false;
  27. /**
  28. * @phpstan-var positive-int
  29. */
  30. private int $maxPerPage = 10;
  32. /**
  33. * @phpstan-var positive-int
  34. */
  35. private int $currentPage = 1;
  37. /**
  38. * @phpstan-var int<0, max>|null
  39. */
  40. private ?int $nbResults = null;
  42. /**
  43. * @phpstan-var positive-int|null
  44. */
  45. private ?int $maxNbPages = null;
  47. /**
  48. * @phpstan-var iterable<array-key, T>|null
  49. */
  50. private ?iterable $currentPageResults = null;
  52. /**
  53. * @param AdapterInterface<T> $adapter
  54. */
  55. public function __construct(AdapterInterface $adapter)
  56. {
  57. $this->adapter = $adapter;
  58. }
  60. /**
  61. * @param AdapterInterface<T> $adapter
  62. *
  63. * @return self<T>
  64. */
  65. public static function createForCurrentPageWithMaxPerPage(AdapterInterface $adapter, int $currentPage, int $maxPerPage): self
  66. {
  67. $pagerfanta = new self($adapter);
  68. $pagerfanta->setMaxPerPage($maxPerPage);
  69. $pagerfanta->setCurrentPage($currentPage);
  71. return $pagerfanta;
  72. }
  74. /**
  75. * @return AdapterInterface<T>
  76. *
  77. * @deprecated to be removed in 4.0
  78. */
  79. public function getAdapter(): AdapterInterface
  80. {
  81. trigger_deprecation('pagerfanta/pagerfanta', '3.2', 'Retrieving the %s from "%s" implementations is deprecated and will be removed in 4.0.', AdapterInterface::class, PagerfantaInterface::class);
  83. return $this->adapter;
  84. }
  86. /**
  87. * @return $this<T>
  88. */
  89. public function setAllowOutOfRangePages(bool $allowOutOfRangePages): PagerfantaInterface
  90. {
  91. $this->allowOutOfRangePages = $allowOutOfRangePages;
  93. return $this;
  94. }
  96. public function getAllowOutOfRangePages(): bool
  97. {
  98. return $this->allowOutOfRangePages;
  99. }
  101. public function setNormalizeOutOfRangePages(bool $normalizeOutOfRangePages): PagerfantaInterface
  102. {
  103. $this->normalizeOutOfRangePages = $normalizeOutOfRangePages;
  105. return $this;
  106. }
  108. public function getNormalizeOutOfRangePages(): bool
  109. {
  110. return $this->normalizeOutOfRangePages;
  111. }
  113. /**
  114. * @return $this<T>
  115. *
  116. * @throws LessThan1MaxPerPageException if the page is less than 1
  117. */
  118. public function setMaxPerPage(int $maxPerPage): PagerfantaInterface
  119. {
  120. $this->filterMaxPerPage($maxPerPage);
  122. $this->maxPerPage = $maxPerPage;
  123. $this->resetForMaxPerPageChange();
  124. $this->filterOutOfRangeCurrentPage($this->currentPage);
  126. return $this;
  127. }
  129. private function filterMaxPerPage(int $maxPerPage): void
  130. {
  131. $this->checkMaxPerPage($maxPerPage);
  132. }
  134. /**
  135. * @throws LessThan1MaxPerPageException if the page is less than 1
  136. */
  137. private function checkMaxPerPage(int $maxPerPage): void
  138. {
  139. if ($maxPerPage < 1) {
  140. throw new LessThan1MaxPerPageException();
  141. }
  142. }
  144. private function resetForMaxPerPageChange(): void
  145. {
  146. $this->currentPageResults = null;
  147. }
  149. /**
  150. * @phpstan-return positive-int
  151. */
  152. public function getMaxPerPage(): int
  153. {
  154. return $this->maxPerPage;
  155. }
  157. /**
  158. * @return $this<T>
  159. *
  160. * @throws LessThan1CurrentPageException if the current page is less than 1
  161. * @throws OutOfRangeCurrentPageException if It is not allowed out of range pages and they are not normalized
  162. */
  163. public function setCurrentPage(int $currentPage): PagerfantaInterface
  164. {
  165. $this->currentPage = $this->filterCurrentPage($currentPage);
  166. $this->resetForCurrentPageChange();
  168. return $this;
  169. }
  171. /**
  172. * @phpstan-return positive-int
  173. */
  174. private function filterCurrentPage(int $currentPage): int
  175. {
  176. $this->checkCurrentPage($currentPage);
  178. return $this->filterOutOfRangeCurrentPage($currentPage);
  179. }
  181. /**
  182. * @throws LessThan1CurrentPageException if the current page is less than 1
  183. */
  184. private function checkCurrentPage(int $currentPage): void
  185. {
  186. if ($currentPage < 1) {
  187. throw new LessThan1CurrentPageException();
  188. }
  189. }
  191. /**
  192. * @phpstan-return positive-int
  193. */
  194. private function filterOutOfRangeCurrentPage(int $currentPage): int
  195. {
  196. if ($this->notAllowedCurrentPageOutOfRange($currentPage)) {
  197. return $this->normalizeOutOfRangeCurrentPage($currentPage);
  198. }
  200. return $currentPage;
  201. }
  203. private function notAllowedCurrentPageOutOfRange(int $currentPage): bool
  204. {
  205. return !$this->getAllowOutOfRangePages() && $this->currentPageOutOfRange($currentPage);
  206. }
  208. private function currentPageOutOfRange(int $currentPage): bool
  209. {
  210. return $currentPage > 1 && $currentPage > $this->getNbPages();
  211. }
  213. /**
  214. * @phpstan-return positive-int
  215. *
  216. * @throws OutOfRangeCurrentPageException if the page should not be normalized
  217. */
  218. private function normalizeOutOfRangeCurrentPage(int $currentPage): int
  219. {
  220. if ($this->getNormalizeOutOfRangePages()) {
  221. return $this->getNbPages();
  222. }
  224. throw new OutOfRangeCurrentPageException(sprintf('Page "%d" does not exist. The currentPage must be inferior to "%d"', $currentPage, $this->getNbPages()));
  225. }
  227. private function resetForCurrentPageChange(): void
  228. {
  229. $this->currentPageResults = null;
  230. }
  232. /**
  233. * @phpstan-return positive-int
  234. */
  235. public function getCurrentPage(): int
  236. {
  237. return $this->currentPage;
  238. }
  240. /**
  241. * @phpstan-return iterable<array-key, T>
  242. */
  243. public function getCurrentPageResults(): iterable
  244. {
  245. if (null === $this->currentPageResults) {
  246. $this->currentPageResults = $this->getCurrentPageResultsFromAdapter();
  247. }
  249. return $this->currentPageResults;
  250. }
  252. /**
  253. * @return iterable<array-key, T>
  254. */
  255. private function getCurrentPageResultsFromAdapter(): iterable
  256. {
  257. $offset = $this->calculateOffsetForCurrentPageResults();
  258. $length = $this->getMaxPerPage();
  260. return $this->adapter->getSlice($offset, $length);
  261. }
  263. /**
  264. * @phpstan-return int<0, max>
  265. */
  266. private function calculateOffsetForCurrentPageResults(): int
  267. {
  268. return ($this->getCurrentPage() - 1) * $this->getMaxPerPage();
  269. }
  271. /**
  272. * @phpstan-return int<0, max>
  273. */
  274. public function getCurrentPageOffsetStart(): int
  275. {
  276. return $this->getNbResults() ? $this->calculateOffsetForCurrentPageResults() + 1 : 0;
  277. }
  279. /**
  280. * @phpstan-return int<0, max>
  281. */
  282. public function getCurrentPageOffsetEnd(): int
  283. {
  284. return $this->hasNextPage() ? $this->getCurrentPage() * $this->getMaxPerPage() : $this->getNbResults();
  285. }
  287. /**
  288. * @phpstan-return int<0, max>
  289. */
  290. public function getNbResults(): int
  291. {
  292. if (null === $this->nbResults) {
  293. $this->nbResults = $this->adapter->getNbResults();
  294. }
  296. return $this->nbResults;
  297. }
  299. /**
  300. * @phpstan-return positive-int
  301. */
  302. public function getNbPages(): int
  303. {
  304. $nbPages = $this->calculateNbPages();
  306. if (0 === $nbPages) {
  307. return $this->minimumNbPages();
  308. }
  310. if (null !== $this->maxNbPages && $this->maxNbPages < $nbPages) {
  311. return $this->maxNbPages;
  312. }
  314. return $nbPages;
  315. }
  317. /**
  318. * @phpstan-return int<0, max>
  319. */
  320. private function calculateNbPages(): int
  321. {
  322. return (int) ceil($this->getNbResults() / $this->getMaxPerPage());
  323. }
  325. /**
  326. * @phpstan-return positive-int
  327. */
  328. private function minimumNbPages(): int
  329. {
  330. return 1;
  331. }
  333. /**
  334. * @return $this<T>
  335. *
  336. * @throws LessThan1MaxPagesException if the max number of pages is less than 1
  337. */
  338. public function setMaxNbPages(int $maxNbPages): PagerfantaInterface
  339. {
  340. if ($maxNbPages < 1) {
  341. throw new LessThan1MaxPagesException();
  342. }
  344. $this->maxNbPages = $maxNbPages;
  346. return $this;
  347. }
  349. /**
  350. * @return $this<T>
  351. */
  352. public function resetMaxNbPages(): PagerfantaInterface
  353. {
  354. $this->maxNbPages = null;
  356. return $this;
  357. }
  359. public function haveToPaginate(): bool
  360. {
  361. return $this->getNbResults() > $this->maxPerPage;
  362. }
  364. public function hasPreviousPage(): bool
  365. {
  366. return $this->currentPage > 1;
  367. }
  369. /**
  370. * @phpstan-return positive-int
  371. *
  372. * @throws LogicException if there is no previous page
  373. */
  374. public function getPreviousPage(): int
  375. {
  376. if (!$this->hasPreviousPage()) {
  377. throw new LogicException('There is no previous page.');
  378. }
  380. return $this->currentPage - 1;
  381. }
  383. public function hasNextPage(): bool
  384. {
  385. return $this->currentPage < $this->getNbPages();
  386. }
  388. /**
  389. * @phpstan-return positive-int
  390. *
  391. * @throws LogicException if there is no next page
  392. */
  393. public function getNextPage(): int
  394. {
  395. if (!$this->hasNextPage()) {
  396. throw new LogicException('There is no next page.');
  397. }
  399. return $this->currentPage + 1;
  400. }
  402. /**
  403. * @phpstan-return int<0, max>
  404. */
  405. public function count(): int
  406. {
  407. return $this->getNbResults();
  408. }
  410. /**
  411. * @return \Traversable<array-key, T>
  412. */
  413. public function getIterator(): \Traversable
  414. {
  415. $results = $this->getCurrentPageResults();
  417. if ($results instanceof \Iterator) {
  418. return $results;
  419. }
  421. if ($results instanceof \IteratorAggregate) {
  422. return $results->getIterator();
  423. }
  425. if (\is_array($results)) {
  426. return new \ArrayIterator($results);
  427. }
  429. throw new \InvalidArgumentException(sprintf('Cannot create iterator with page results of type "%s".', get_debug_type($results)));
  430. }
  432. public function jsonSerialize(): array
  433. {
  434. $results = $this->getCurrentPageResults();
  436. if ($results instanceof \Traversable) {
  437. return iterator_to_array($results);
  438. }
  440. return $results;
  441. }
  443. /**
  444. * Get page number of the item at specified position (1-based index).
  445. *
  446. * @phpstan-param positive-int $position
  447. *
  448. * @phpstan-return positive-int
  449. *
  450. * @throws OutOfBoundsException if the item is outside the result set
  451. */
  452. public function getPageNumberForItemAtPosition(int $position): int
  453. {
  454. if ($this->getNbResults() < $position) {
  455. throw new OutOfBoundsException(sprintf('Item requested at position %d, but there are only %d items.', $position, $this->getNbResults()));
  456. }
  458. return (int) ceil($position / $this->getMaxPerPage());
  459. }
  460. }