Paginator.php — Kirki – Freeform Page Builder, Website Builder & Customizer 6.0.13

kirki / libraries / framework / Database / Query / Paginator.php

kirki / libraries / framework / Database / Query Last commit date

Relations 3 weeks ago Collection.php 3 weeks ago EagerLoader.php 3 weeks ago Expression.php 3 weeks ago JoinClause.php 3 weeks ago Model.php 3 weeks ago Paginator.php 3 weeks ago QueryBuilder.php 3 weeks ago QueryCompiler.php 3 weeks ago

Paginator.php

268 lines

1	<?php
2
3	/**
4	* Represent a paginated slice of results with metadata.
5	* Wrap a collection of items and expose helpful pagination helpers such as current page, last page, and range indices.
6	* Typically constructed by the query builder when using paginate to return both data and context.
7	*
8	* @package Framework
9	* @subpackage Database\Query
10	* @since 1.0.0
11	*/
12	namespace Kirki\Framework\Database\Query;
13
14	\defined('ABSPATH') \|\| exit;
15	use Kirki\Framework\Contracts\Support\Arrayable;
16	use Kirki\Framework\Contracts\Support\Jsonable;
17	use Kirki\Framework\Collections\Collection;
18	use Kirki\Framework\Supports\Arr;
19	class Paginator implements Arrayable, Jsonable
20	{
21	/**
22	* The collection of items for the current page.
23	*
24	* @var Collection
25	*
26	* @since 1.0.0
27	*/
28	protected $items;
29	/**
30	* The total number of matching records across all pages.
31	*
32	* @var int
33	*
34	* @since 1.0.0
35	*/
36	protected $total;
37	/**
38	* The number of items displayed per page.
39	*
40	* @var int
41	*
42	* @since 1.0.0
43	*/
44	protected $per_page;
45	/**
46	* The current page number (1-based index).
47	*
48	* @var int
49	*
50	* @since 1.0.0
51	*/
52	protected $current_page;
53	/**
54	* The last page number, calculated from total and per_page.
55	*
56	* @var int
57	*
58	* @since 1.0.0
59	*/
60	protected $last_page;
61	/**
62	* Create a new paginator instance from items and counts.
63	*
64	* Accepts the current page's items and the total count to compute page
65	* numbers and boundaries. The last page is derived by dividing total by
66	* per-page and rounding up to the nearest integer.
67	*
68	* @param Collection $items The items for the current page
69	* @param int $total The total number of matching records
70	* @param int $per_page The number of items per page
71	* @param int $current_page The current page number (1-based)
72	*
73	* @return void No return value
74	*
75	* @since 1.0.0
76	*/
77	public function __construct(Collection $items, $total, $per_page, $current_page)
78	{
79	$this->items = $items;
80	$this->total = $total;
81	$this->per_page = $per_page;
82	$this->current_page = $current_page;
83	$this->last_page = $total > 0 ? (int) \ceil($total / $per_page) : $current_page;
84	}
85	/**
86	* Get the collection of items for the current page.
87	*
88	* Returns the items as a collection to support further transformations or
89	* serialization by callers.
90	*
91	* @return Collection The items contained in this paginator page
92	*
93	* @since 1.0.0
94	*/
95	public function items()
96	{
97	return $this->items;
98	}
99	/**
100	* Get the total number of matching records.
101	*
102	* Represents the count across all pages, not just the current slice of
103	* items returned.
104	*
105	* @return int The total number of records
106	*
107	* @since 1.0.0
108	*/
109	public function total()
110	{
111	return $this->total;
112	}
113	/**
114	* Get the per-page size for this pagination context.
115	*
116	* Reflects the limit applied when the paginator was constructed and used
117	* to compute page counts and range indices.
118	*
119	* @return int The number of items per page
120	*
121	* @since 1.0.0
122	*/
123	public function get_per_page()
124	{
125	return $this->per_page;
126	}
127	/**
128	* Get the current page number.
129	*
130	* This value is 1-based and corresponds to the offset and limit used when
131	* fetching the current slice of results.
132	*
133	* @return int The current page number
134	*
135	* @since 1.0.0
136	*/
137	public function get_current_page()
138	{
139	return $this->current_page;
140	}
141	/**
142	* Get the last page number based on total and per-page.
143	*
144	* Calculated by dividing total by per-page and rounding up. Represents the
145	* upper bound for valid page navigation.
146	*
147	* @return int The highest page number available
148	*
149	* @since 1.0.0
150	*/
151	public function get_last_page()
152	{
153	return $this->last_page;
154	}
155	/**
156	* Determine if more pages are available after the current page.
157	*
158	* Compares the current page to the last page to signal whether forward
159	* navigation is possible.
160	*
161	* @return bool True when there are additional pages; false otherwise
162	*
163	* @since 1.0.0
164	*/
165	public function has_more_page()
166	{
167	return $this->current_page < $this->last_page;
168	}
169	/**
170	* Determine if pagination spans more than one page.
171	*
172	* Returns true when not on the first page or when more pages exist. This
173	* is useful for conditionally rendering pagination controls.
174	*
175	* @return bool True when multiple pages exist; false for a single page
176	*
177	* @since 1.0.0
178	*/
179	public function has_pages()
180	{
181	return $this->current_page !== 1 \|\| $this->has_more_page();
182	}
183	/**
184	* Determine if the paginator is on the first page.
185	*
186	* Useful for disabling previous navigation controls in UIs.
187	*
188	* @return bool True when on page 1; false otherwise
189	*
190	* @since 1.0.0
191	*/
192	public function on_first_page()
193	{
194	return $this->current_page === 1;
195	}
196	/**
197	* Determine if the paginator is on the last page.
198	*
199	* Useful for disabling next navigation controls in UIs.
200	*
201	* @return bool True when on the last page; false otherwise
202	*
203	* @since 1.0.0
204	*/
205	public function on_last_page()
206	{
207	return $this->current_page === $this->last_page;
208	}
209	/**
210	* Get the index (1-based) of the first item on the current page.
211	*
212	* Returns null when there are no items in the result set. Calculated from
213	* current page and per-page values.
214	*
215	* @return int\|null The starting item index or null when empty
216	*
217	* @since 1.0.0
218	*/
219	public function first_item()
220	{
221	return $this->total > 0 ? ($this->current_page - 1) * $this->per_page + 1 : null;
222	}
223	/**
224	* Get the index (1-based) of the last item on the current page.
225	*
226	* Returns null when there are no items. Computed as first item index plus
227	* the number of items in the current page minus one.
228	*
229	* @return int\|null The ending item index or null when empty
230	*
231	* @since 1.0.0
232	*/
233	public function last_item()
234	{
235	return $this->total > 0 ? $this->first_item() + $this->items->count() - 1 : null;
236	}
237	/**
238	* Convert the paginator to an array including items and metadata.
239	*
240	* Returns an associative array describing the current slice, total, page
241	* counts, range, and flags commonly used by consumers to render controls.
242	*
243	* @return array The array representation of the paginator
244	*
245	* @since 1.0.0
246	*/
247	public function to_array()
248	{
249	return ['results' => $this->items->all(), 'total' => $this->total, 'count' => $this->items->count(), 'per_page' => $this->per_page, 'current_page' => $this->current_page, 'last_page' => $this->last_page, 'from' => $this->first_item(), 'to' => $this->last_item(), 'has_more_pages' => $this->has_more_page()];
250	}
251	/**
252	* Convert the paginator to a JSON string.
253	*
254	* Encodes the array form of the paginator for straightforward transport or
255	* logging purposes.
256	*
257	* @param mixed $options The options array.
258	*
259	* @return string The JSON-encoded paginator representation
260	*
261	* @since 1.0.0
262	*/
263	public function to_json($options = 0)
264	{
265	return Arr::json_encode($this->to_array(), $options);
266	}
267	}
268