Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
92.71% covered (success)
92.71%
89 / 96
62.50% covered (warning)
62.50%
5 / 8
CRAP
0.00% covered (danger)
0.00%
0 / 1
pagination
92.71% covered (success)
92.71%
89 / 96
62.50% covered (warning)
62.50%
5 / 8
47.86
0.00% covered (danger)
0.00%
0 / 1
 __construct
100.00% covered (success)
100.00%
4 / 4
100.00% covered (success)
100.00%
1 / 1
1
 generate_page_link
88.24% covered (warning)
88.24%
15 / 17
0.00% covered (danger)
0.00%
0 / 1
13.28
 generate_template_pagination
93.85% covered (success)
93.85%
61 / 65
0.00% covered (danger)
0.00%
0 / 1
23.12
 get_on_page
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 on_page
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
1
 validate_start
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
5
 reverse_start
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 reverse_limit
66.67% covered (warning)
66.67%
2 / 3
0.00% covered (danger)
0.00%
0 / 1
2.15
1<?php
2/**
3*
4* This file is part of the phpBB Forum Software package.
5*
6* @copyright (c) phpBB Limited <https://www.phpbb.com>
7* @license GNU General Public License, version 2 (GPL-2.0)
8*
9* For full copyright and license information, please see
10* the docs/CREDITS.txt file.
11*
12*/
13
14namespace phpbb;
15
16class pagination
17{
18    /** @var \phpbb\template\template */
19    protected $template;
20
21    /** @var \phpbb\user */
22    protected $user;
23
24    /** @var \phpbb\controller\helper */
25    protected $helper;
26
27    /** @var \phpbb\event\dispatcher_interface */
28    protected $phpbb_dispatcher;
29
30    /**
31    * Constructor
32    *
33    * @param    \phpbb\template\template            $template
34    * @param    \phpbb\user                            $user
35    * @param    \phpbb\controller\helper            $helper
36    * @param    \phpbb\event\dispatcher_interface    $phpbb_dispatcher
37    */
38    public function __construct(\phpbb\template\template $template, \phpbb\user $user, \phpbb\controller\helper $helper, \phpbb\event\dispatcher_interface $phpbb_dispatcher)
39    {
40        $this->template = $template;
41        $this->user = $user;
42        $this->helper = $helper;
43        $this->phpbb_dispatcher = $phpbb_dispatcher;
44    }
45
46    /**
47    * Generate a pagination link based on the url and the page information
48    *
49    * @param string|array $base_url is url prepended to all links generated within the function
50    *                            If you use page numbers inside your controller route, base_url should contains a placeholder (%d)
51    *                            for the page. Also be sure to specify the pagination path information into the start_name argument
52    * @param int $on_page is the page for which we want to generate the link
53    * @param string $start_name is the name of the parameter containing the first item of the given page (example: start=20)
54    *                            If you use page numbers inside your controller route, start name should be the string
55    *                            that should be removed for the first page (example: /page/%d)
56    * @param int $per_page the number of items, posts, etc. to display per page, used to determine the number of pages to produce
57    * @return string URL for the requested page
58    */
59    protected function generate_page_link($base_url, $on_page, $start_name, $per_page)
60    {
61        // A listener can set this variable to the new pagination URL
62        // to override the generate_page_link() function generated value
63        $generate_page_link_override = false;
64
65        /**
66        * Execute code and/or override generate_page_link()
67        *
68        * To override the generate_page_link() function generated value
69        * set $generate_page_link_override to the new URL value
70        *
71        * @event core.pagination_generate_page_link
72        * @var string|array base_url is url prepended to all links generated within the function
73        *                            If you use page numbers inside your controller route, base_url should contains a placeholder (%d)
74        *                            for the page. Also be sure to specify the pagination path information into the start_name argument
75        * @var int on_page is the page for which we want to generate the link
76        * @var string start_name is the name of the parameter containing the first item of the given page (example: start=20)
77        *                            If you use page numbers inside your controller route, start name should be the string
78        *                            that should be removed for the first page (example: /page/%d)
79        * @var int per_page the number of items, posts, etc. to display per page, used to determine the number of pages to produce
80        * @var bool|string generate_page_link_override Shall we return custom pagination link (string URL) or not (false)
81        * @since 3.1.0-RC5
82        */
83        $vars = array('base_url', 'on_page', 'start_name', 'per_page', 'generate_page_link_override');
84        extract($this->phpbb_dispatcher->trigger_event('core.pagination_generate_page_link', compact($vars)));
85
86        if ($generate_page_link_override)
87        {
88            return $generate_page_link_override;
89        }
90
91        if (!is_string($base_url))
92        {
93            if (is_array($base_url['routes']))
94            {
95                $route = ($on_page > 1) ? $base_url['routes'][1] : $base_url['routes'][0];
96            }
97            else
98            {
99                $route = $base_url['routes'];
100            }
101            $params = (isset($base_url['params'])) ? $base_url['params'] : array();
102            $is_amp = (isset($base_url['is_amp'])) ? $base_url['is_amp'] : true;
103            $session_id = (isset($base_url['session_id'])) ? $base_url['session_id'] : false;
104
105            if ($on_page > 1 || !is_array($base_url['routes']))
106            {
107                $params[$start_name] = (int) $on_page;
108            }
109
110            return $this->helper->route($route, $params, $is_amp, $session_id);
111        }
112        else
113        {
114            $url_delim = (strpos($base_url, '?') === false) ? '?' : ((strpos($base_url, '?') === strlen($base_url) - 1) ? '' : '&amp;');
115            return ($on_page > 1) ? $base_url . $url_delim . $start_name . '=' . (($on_page - 1) * $per_page) : $base_url;
116        }
117    }
118
119    /**
120    * Generate template rendered pagination
121    * Allows full control of rendering of pagination with the template
122    *
123    * @param string|array $base_url is url prepended to all links generated within the function
124    *                            If you use page numbers inside your controller route, base_url should contains a placeholder (%d)
125    *                            for the page. Also be sure to specify the pagination path information into the start_name argument
126    * @param string $block_var_name is the name assigned to the pagination data block within the template (example: <!-- BEGIN pagination -->)
127    * @param string $start_name is the name of the parameter containing the first item of the given page (example: start=20)
128    *                            If you use page numbers inside your controller route, start name should be the string
129    *                            that should be removed for the first page (example: /page/%d)
130    * @param int $num_items the total number of items, posts, etc., used to determine the number of pages to produce
131    * @param int $per_page the number of items, posts, etc. to display per page, used to determine the number of pages to produce
132    * @param int $start the item which should be considered currently active, used to determine the page we're on
133    * @param bool $reverse_count determines whether we weight display of the list towards the start (false) or end (true) of the list
134    * @param bool $ignore_on_page decides whether we enable an active (unlinked) item, used primarily for embedded lists
135    * @return void
136    */
137    public function generate_template_pagination($base_url, $block_var_name, $start_name, $num_items, $per_page, $start = 1, $reverse_count = false, $ignore_on_page = false)
138    {
139        if (empty($base_url))
140        {
141            return;
142        }
143
144        $total_pages = ceil($num_items / $per_page);
145        $on_page = $this->get_on_page($per_page, $start);
146        $u_previous_page = $u_next_page = '';
147
148        if ($total_pages > 1)
149        {
150            if ($reverse_count)
151            {
152                $start_page = ($total_pages > 5) ? $total_pages - 4 : 1;
153                $end_page = $total_pages;
154            }
155            else
156            {
157                // What we're doing here is calculating what the "start" and "end" pages should be. We
158                // do this by assuming pagination is "centered" around the currently active page with
159                // the three previous and three next page links displayed. Anything more than that and
160                // we display the ellipsis, likewise anything less.
161                //
162                // $start_page is the page at which we start creating the list. When we have five or less
163                // pages we start at page 1 since there will be no ellipsis displayed. Anymore than that
164                // and we calculate the start based on the active page. This is the min/max calculation.
165                // First (max) would we end up starting on a page less than 1? Next (min) would we end
166                // up starting so close to the end that we'd not display our minimum number of pages.
167                //
168                // $end_page is the last page in the list to display. Like $start_page we use a min/max to
169                // determine this number. Again at most five pages? Then just display them all. More than
170                // five and we first (min) determine whether we'd end up listing more pages than exist.
171                // We then (max) ensure we're displaying the minimum number of pages.
172                $start_page = ($total_pages > 5) ? min(max(1, $on_page - 2), $total_pages - 4) : 1;
173                $end_page = ($total_pages > 5) ? max(min($total_pages, $on_page + 2), 5) : $total_pages;
174            }
175
176            if ($on_page != 1)
177            {
178                $u_previous_page = $this->generate_page_link($base_url, $on_page - 1, $start_name, $per_page);
179
180                $this->template->assign_block_vars($block_var_name, array(
181                    'PAGE_NUMBER'    => '',
182                    'PAGE_URL'        => $u_previous_page,
183                    'S_IS_CURRENT'    => false,
184                    'S_IS_PREV'        => true,
185                    'S_IS_NEXT'        => false,
186                    'S_IS_ELLIPSIS'    => false,
187                ));
188            }
189
190            // This do...while exists purely to negate the need for start and end assign_block_vars, i.e.
191            // to display the first and last page in the list plus any ellipsis. We use this loop to jump
192            // around a little within the list depending on where we're starting (and ending).
193            $at_page = 1;
194            do
195            {
196                // We decide whether to display the ellipsis during the loop. The ellipsis is always
197                // displayed as either the second or penultimate item in the list. So are we at either
198                // of those points and of course do we even need to display it, i.e. is the list starting
199                // on at least page 3 and ending three pages before the final item.
200                $this->template->assign_block_vars($block_var_name, array(
201                    'PAGE_NUMBER'    => $at_page,
202                    'PAGE_URL'        => $this->generate_page_link($base_url, $at_page, $start_name, $per_page),
203                    'S_IS_CURRENT'    => (!$ignore_on_page && $at_page == $on_page),
204                    'S_IS_NEXT'        => false,
205                    'S_IS_PREV'        => false,
206                    'S_IS_ELLIPSIS'    => ($at_page == 2 && $start_page > 2) || ($at_page == $total_pages - 1 && $end_page < $total_pages - 1),
207                ));
208
209                // We may need to jump around in the list depending on whether we have or need to display
210                // the ellipsis. Are we on page 2 and are we more than one page away from the start
211                // of the list? Yes? Then we jump to the start of the list. Likewise are we at the end of
212                // the list and are there more than two pages left in total? Yes? Then jump to the penultimate
213                // page (so we can display the ellipsis next pass). Else, increment the counter and keep
214                // going
215                if ($at_page == 2 && $at_page < $start_page - 1)
216                {
217                    $at_page = $start_page;
218                }
219                else if ($at_page == $end_page && $end_page < $total_pages - 1)
220                {
221                    $at_page = $total_pages - 1;
222                }
223                else
224                {
225                    $at_page++;
226                }
227            }
228            while ($at_page <= $total_pages);
229
230            if ($on_page != $total_pages)
231            {
232                $u_next_page = $this->generate_page_link($base_url, $on_page + 1, $start_name, $per_page);
233
234                $this->template->assign_block_vars($block_var_name, array(
235                    'PAGE_NUMBER'    => '',
236                    'PAGE_URL'        => $u_next_page,
237                    'S_IS_CURRENT'    => false,
238                    'S_IS_PREV'        => false,
239                    'S_IS_NEXT'        => true,
240                    'S_IS_ELLIPSIS'    => false,
241                ));
242            }
243        }
244
245        // If the block_var_name is a nested block, we will use the last (most
246        // inner) block as a prefix for the template variables. If the last block
247        // name is pagination, the prefix is empty. If the rest of the
248        // block_var_name is not empty, we will modify the last row of that block
249        // and add our pagination items.
250        $tpl_block_name = $tpl_prefix = '';
251        if (strrpos($block_var_name, '.') !== false)
252        {
253            $tpl_block_name = substr($block_var_name, 0, strrpos($block_var_name, '.'));
254            $tpl_prefix = strtoupper(substr($block_var_name, strrpos($block_var_name, '.') + 1));
255        }
256        else
257        {
258            $tpl_prefix = strtoupper($block_var_name);
259        }
260        $tpl_prefix = ($tpl_prefix == 'PAGINATION') ? '' : $tpl_prefix . '_';
261
262        $template_array = array(
263            $tpl_prefix . 'BASE_URL'        => is_string($base_url) ? $base_url : '',//@todo: Fix this for routes
264            $tpl_prefix . 'START_NAME'        => $start_name,
265            $tpl_prefix . 'PER_PAGE'        => $per_page,
266            'U_' . $tpl_prefix . 'PREVIOUS_PAGE'    => ($on_page != 1) ? $u_previous_page : '',
267            'U_' . $tpl_prefix . 'NEXT_PAGE'        => ($on_page != $total_pages) ? $u_next_page : '',
268            $tpl_prefix . 'TOTAL_PAGES'        => $total_pages,
269            $tpl_prefix . 'CURRENT_PAGE'    => $on_page,
270            $tpl_prefix . 'PAGE_NUMBER'        => $this->on_page($num_items, $per_page, $start),
271        );
272
273        if ($tpl_block_name)
274        {
275            $this->template->alter_block_array($tpl_block_name, $template_array, true, 'change');
276        }
277        else
278        {
279            $this->template->assign_vars($template_array);
280        }
281    }
282
283    /**
284    * Get current page number
285    *
286    * @param int $per_page the number of items, posts, etc. per page
287    * @param int $start the item which should be considered currently active, used to determine the page we're on
288    *
289    * @return int    Current page number
290    */
291    public function get_on_page(int $per_page, int $start): int
292    {
293        return (int) floor($start / $per_page) + 1;
294    }
295
296    /**
297    * Return current page
298    *
299    * @param int $num_items the total number of items, posts, topics, etc.
300    * @param int $per_page the number of items, posts, etc. per page
301    * @param int $start the item which should be considered currently active, used to determine the page we're on
302    * @return string Descriptive pagination string (e.g. "page 1 of 10")
303    */
304    public function on_page($num_items, $per_page, $start)
305    {
306        $on_page = $this->get_on_page($per_page, $start);
307        return $this->user->lang('PAGE_OF', $on_page, max(ceil($num_items / $per_page), 1));
308    }
309
310    /**
311    * Get current page number
312    *
313    * @param int $start the item which should be considered currently active, used to determine the page we're on
314    * @param int $per_page the number of items, posts, etc. per page
315    * @param int $num_items the total number of items, posts, topics, etc.
316    * @return int    Current page number
317    */
318    public function validate_start($start, $per_page, $num_items)
319    {
320        if ($start < 0 || $start >= $num_items)
321        {
322            return ($start < 0 || $num_items <= 0) ? 0 : (int) floor(($num_items - 1) / $per_page) * $per_page;
323        }
324
325        return $start;
326    }
327
328    /**
329    * Get new start when searching from the end
330    *
331    * If the user is trying to reach late pages, start searching from the end.
332    *
333    * @param int $start the item which should be considered currently active, used to determine the page we're on
334    * @param int $limit the number of items, posts, etc. to display
335    * @param int $num_items the total number of items, posts, topics, etc.
336    * @return int    Current page number
337    */
338    public function reverse_start($start, $limit, $num_items)
339    {
340        return max(0, $num_items - $limit - $start);
341    }
342
343    /**
344    * Get new item limit when searching from the end
345    *
346    * If the user is trying to reach late pages, start searching from the end.
347    * In this case the items to display might be lower then the actual per_page setting.
348    *
349    * @param int $start the item which should be considered currently active, used to determine the page we're on
350    * @param int $per_page the number of items, posts, etc. per page
351    * @param int $num_items the total number of items, posts, topics, etc.
352    * @return int    Current page number
353    */
354    public function reverse_limit($start, $per_page, $num_items)
355    {
356        if ($start + $per_page > $num_items)
357        {
358            return min($per_page, max(1, $num_items - $start));
359        }
360
361        return $per_page;
362    }
363}