Merge branch 'codeigniter4:develop' into add-curlrequest-curlopt_ssl_verifyhost

Author: NicolaeIotu

system/Pager/PagerRenderer.php

@@ -25,14 +25,14 @@
 class PagerRenderer
 {
     /**
-     * First page number.
+     * First page number in the set of links to be displayed.
      *
      * @var int
      */
     protected $first;
 
     /**
-     * Last page number.
+     * Last page number in the set of links to be displayed.
      *
      * @var int
      */
@@ -85,8 +85,11 @@ class PagerRenderer
      */
     public function __construct(array $details)
     {
-        $this->first        = 1;
-        $this->last         = $details['pageCount'];
+        // `first` and `last` will be updated by `setSurroundCount()`.
+        // You must call `setSurroundCount()` after instantiation.
+        $this->first = 1;
+        $this->last  = $details['pageCount'];
+
         $this->current      = $details['currentPage'];
         $this->total        = $details['total'];
         $this->uri          = $details['uri'];
@@ -122,8 +125,6 @@ public function hasPrevious(): bool
      * page before the current page, but is the page just before the
      * "first" page.
      *
-     * You MUST call hasPrevious() first, or this value may be invalid.
-     *
      * @return string|null
      */
     public function getPrevious()
@@ -162,8 +163,6 @@ public function hasNext(): bool
      * page after the current page, but is the page that follows the
      * "last" page.
      *
-     * You MUST call hasNext() first, or this value may be invalid.
-     *
      * @return string|null
      */
     public function getNext()
@@ -260,6 +259,8 @@ public function getCurrent(): string
      * is represented by another array containing of the URI the link
      * should go to, the title (number) of the link, and a boolean
      * value representing whether this link is active or not.
+     *
+     * @return list<array{uri:string, title:int, active:bool}>
      */
     public function links(): array
     {
@@ -381,7 +382,7 @@ public function getNextPage()
     }
 
     /**
-     * Returns the page number of the first page.
+     * Returns the page number of the first page in the set of links to be displayed.
      */
     public function getFirstPageNumber(): int
     {
@@ -397,7 +398,7 @@ public function getCurrentPageNumber(): int
     }
 
     /**
-     * Returns the page number of the last page.
+     * Returns the page number of the last page in the set of links to be displayed.
      */
     public function getLastPageNumber(): int
     {

user_guide_src/source/libraries/pagination.rst

@@ -227,32 +227,39 @@ setSurroundCount()
 In the first line, the ``setSurroundCount()`` method specifies than we want to show two links to either side of
 the current page link. The only parameter that it accepts is the number of links to show.
 
+.. note:: You must call this method first to generate correct pagination links.
+
 hasPrevious() & hasNext()
 -------------------------
 
-These methods return a boolean true if there are more links that can be displayed on either side of the current page,
-based on the value passed to ``setSurroundCount()``. For example, let's say we have 20 pages of data. The current
-page is page 3. If the surrounding count is 2, then the following links would show up in the list: 1, 2, 3, 4, and 5.
-Since the first link displayed is page one, ``hasPrevious()`` would return **false** since there is no page zero. However,
-``hasNext()`` would return **true** since there are 15 additional pages of results after page five.
+These methods return a boolean ``true`` if there are more links that can be displayed on either side of the current page,
+based on the value passed to `setSurroundCount()`_.
+
+For example, let's say we have 20 pages of data. The current
+page is page 3. If the surrounding count is 2, then the following links would show up like this::
+
+    1  |  2  |  3  |  4  |  5
+
+Since the first link displayed is page one, ``hasPrevious()`` would return ``false`` since there is no page zero. However,
+``hasNext()`` would return ``true`` since there are 15 additional pages of results after page five.
 
 getPrevious() & getNext()
 -------------------------
 
-These methods return the URL for the previous or next pages of results on either side of the numbered links.
+These methods return the **URL** for the previous or next pages of results on either side of the numbered links.
 
 For example, you have the current page set at 5 and you want to have the links before and after (the surroundCount) to be 2 each, that will give you something like this::
 
     3  |  4  |  5  |  6  |  7
 
 ``getPrevious()`` returns the URL for page 2. ``getNext()`` returns the URL for page 8.
 
-If you want to get page 4 and page 6, use ``getPreviousPage()`` and ``getNextPage()`` instead.
+If you want to get page 4 and page 6, use `getPreviousPage() & getNextPage()`_ instead.
 
 getFirst() & getLast()
 ----------------------
 
-Much like ``getPrevious()`` and ``getNext()``, these methods return links to the first and last pages in the
+Much like `getPrevious() & getNext()`_, these methods return the **URL** to the first and last pages in the
 result set.
 
 links()
@@ -263,9 +270,9 @@ title, which is just the number, and a boolean that tells whether the link is th
 
 .. literalinclude:: pagination/013.php
 
-In the code presented for the standard pagination structure, the methods ``getPrevious()`` and ``getNext()`` are used to obtain the links to the previous and next pagination groups respectively.
+In the code presented for the standard pagination structure, the methods `getPrevious() & getNext()`_ are used to obtain the links to the previous and next pagination groups respectively.
 
-If you want to use the pagination structure where prev and next will be links to the previous and next pages based on the current page, just replace the ``getPrevious()`` and ``getNext()`` methods with ``getPreviousPage()`` and ``getNextPage()``, and the methods ``hasPrevious()`` and ``hasNext()`` by ``hasPreviousPage()`` and ``hasNextPage()`` respectively.
+If you want to use the pagination structure where prev and next will be links to the previous and next pages based on the current page, just replace the `getPrevious() & getNext()`_ methods with `getPreviousPage() & getNextPage()`_, and the methods `hasPrevious() & hasNext()`_ by `hasPreviousPage() & hasNextPage()`_ respectively.
 
 See following an example with these changes:
 
@@ -274,21 +281,35 @@ See following an example with these changes:
 hasPreviousPage() & hasNextPage()
 ---------------------------------
 
-This method returns a boolean true if there are links to a page before and after, respectively, the current page being displayed.
+This method returns a boolean ``true`` if there are links to a page before and after, respectively, the current page being displayed.
+
+For example, let's say we have 20 pages of data. The current
+page is page 3. If the surrounding count is 2, then the following links would show up like this::
+
+    1  |  2  |  3  |  4  |  5
+
+``hasPreviousPage()`` would return ``true`` since there is page 2. And,
+``hasNextPage()`` would return ``true`` since there is page 4.
 
-Their difference to ``hasPrevious()`` and ``hasNext()`` is that they are based on the current page while ``hasPrevious()`` and ``hasNext()`` are based on the set of links to be displayed before and after the current page based on the value passed in ``setSurroundCount()``.
+.. note:: The difference to `hasPrevious() & hasNext()`_ is that they are based
+    on the current page while `hasPrevious() & hasNext()`_ are based on the set
+    of links to be displayed before and after the current page based on the value
+    passed in `setSurroundCount()`_.
 
 getPreviousPage() & getNextPage()
 ---------------------------------
 
-These methods return a URL for the previous and next pages in relation to the current page being displayed, unlike ``getPrevious()`` and ``getNext()`` that return the URL for the previous or next pages of results on either side of the numbered links. See the previous paragraph for a full explanation.
+These methods return a **URL** for the previous and next pages in relation to the current page being displayed.
 
 For example, you have the current page set at 5 and you want to have the links before and after (the surroundCount) to be 2 each, that will give you something like this::
 
     3  |  4  |  5  |  6  |  7
 
 ``getPreviousPage()`` returns the URL for page 4. ``getNextPage()`` returns the URL for page 6.
 
+.. note:: `getPrevious() & getNext()`_ returns the URL for the previous or next
+    pages of results on either side of the numbered links.
+
 If you want page numbers instead of URLs, you can use the following methods:
 
 getPreviousPageNumber() & getNextPageNumber()
@@ -299,8 +320,16 @@ These methods return the page number for the previous or next pages in relation
 getFirstPageNumber() & getLastPageNumber()
 ------------------------------------------
 
-These methods return page numbers to the first and last pages in the
-result set.
+These methods return the page numbers of the first and last pages in the set of
+links to be displayed. For example, if the set of links to be displayed is something like this::
+
+    3  |  4  |  5  |  6  |  7
+
+``getFirstPageNumber()`` will return 3 while ``getLastPageNumber()`` will return 7.    
+
+.. note:: To obtain the page numbers of the first and last pages in the entire
+    result set, you can use the following approach: The first page number is always 1, and `getPageCount()`_ can be used to
+    retrieve the last page number.
 
 getCurrentPageNumber()
 ----------------------