Merge pull request #7581 from kenjis/docs-model-pagination

docs: improve Paginating with Models

Author: kenjis

user_guide_src/source/database/queries.rst

@@ -15,11 +15,16 @@ Query Basics
 Regular Queries
 ===============
 
-To submit a query, use the **query** function:
+.. _db-query:
+
+$db->query()
+------------
+
+To submit a query, use the ``query()`` method:
 
 .. literalinclude:: queries/001.php
 
-The ``query()`` function returns a database result **object** when "read"
+The ``query()`` method returns a database result **object** when "read"
 type queries are run which you can use to :doc:`show your
 results <results>`. When "write" type queries are run it simply
 returns true or false depending on success or failure. When retrieving
@@ -34,6 +39,11 @@ this:
 Simplified Queries
 ==================
 
+.. _db-simplequery:
+
+$db->simpleQuery()
+------------------
+
 The ``simpleQuery()`` method is a simplified version of the
 ``$db->query()`` method. It DOES
 NOT return a database result set, nor does it set the query timer, or

user_guide_src/source/libraries/pagination.rst

@@ -39,13 +39,46 @@ The first element is the results from the database, **users**, which is retrieve
 the Model will hold on to the instance it used and store it in the public property, ``$pager``. So, we grab
 that and assign it to the ``$pager`` variable in the view.
 
-.. important:: It is important to understand that the ``Model::paginate()`` method uses the **Model** and **QueryBuilder** methods.
-    Therefore, trying to use ``$db->query()`` and ``Model::paginate()`` **will not work** because ``$db->query()`` executes
-    the query immediately and is not associated with a QueryBuilder.
+Customizing Query for Pagination
+================================
 
-To define conditions for pagination in a model, you can:
+To customize a query for pagination in a model, you can add
+:doc:`Query Builder <../database/query_builder>` methods before ``paginate()``
+method.
+
+Adding WHERE
+------------
+
+If you want to add WHERE conditions, you can specify conditions directly:
 
 .. literalinclude:: pagination/003.php
+    :lines: 2-
+
+You can move the conditions to a separate method:
+
+.. literalinclude:: pagination/017.php
+
+.. literalinclude:: pagination/018.php
+    :lines: 2-
+
+Adding JOIN
+-----------
+
+You can join another table:
+
+.. literalinclude:: pagination/016.php
+
+.. important:: It is important to understand that the ``Model::paginate()`` method
+    uses the **Model** and the **Query Builder** instance in the Model.
+    Therefore, trying to use ``Model::paginate()`` with :ref:`db-query`
+    **will not work** because ``$db->query()`` executes the query immediately
+    and is not associated with the Query Builder.
+
+If you need a complicated SQL query that you cannot write with Query Builder,
+try using :ref:`db-query` and `Manual Pagination`_.
+
+Displaying Pager Links
+======================
 
 Within the view, we then need to tell it where to display the resulting links::
 

user_guide_src/source/libraries/pagination/002.php

@@ -2,9 +2,7 @@
 
 namespace App\Controllers;
 
-use CodeIgniter\Controller;
-
-class UserController extends Controller
+class UserController extends BaseController
 {
     public function index()
     {

user_guide_src/source/libraries/pagination/003.php

@@ -1,26 +1,9 @@
 <?php
 
-// You can specify conditions directly.
+// In your Controller.
 $model = new \App\Models\UserModel();
 
 $data = [
     'users' => $model->where('ban', 1)->paginate(10),
     'pager' => $model->pager,
 ];
-
-// You can move the conditions to a separate method.
-// Model method
-class UserModel extends Model
-{
-    public function banned()
-    {
-        $this->builder()->where('ban', 1);
-
-        return $this; // This will allow the call chain to be used.
-    }
-}
-
-$data = [
-    'users' => $model->banned()->paginate(10),
-    'pager' => $model->pager,
-];

user_guide_src/source/libraries/pagination/004.php

@@ -2,9 +2,7 @@
 
 namespace App\Controllers;
 
-use CodeIgniter\Controller;
-
-class UserController extends Controller
+class UserController extends BaseController
 {
     public function index()
     {

user_guide_src/source/libraries/pagination/015.php

@@ -2,9 +2,7 @@
 
 namespace App\Controllers;
 
-use CodeIgniter\Controller;
-
-class UserController extends Controller
+class UserController extends BaseController
 {
     public function index()
     {

user_guide_src/source/libraries/pagination/016.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Models;
+
+use CodeIgniter\Model;
+
+class NewsModel extends Model
+{
+    protected $table = 'news';
+
+    // ...
+
+    public function getPagination(?int $perPage = null): array
+    {
+        $this->builder()
+            ->select('news.*, category.name')
+            ->join('category', 'news.category_id = category.id');
+
+        return [
+            'news'  => $this->paginate($perPage),
+            'pager' => $this->pager,
+        ];
+    }
+}

user_guide_src/source/libraries/pagination/017.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Models;
+
+use CodeIgniter\Model;
+
+class UserModel extends Model
+{
+    // ...
+
+    public function banned()
+    {
+        $this->builder()->where('ban', 1);
+
+        return $this; // This will allow the call chain to be used.
+    }
+}

user_guide_src/source/libraries/pagination/018.php

@@ -0,0 +1,9 @@
+<?php
+
+// In your Controller.
+$model = new \App\Models\UserModel();
+
+$data = [
+    'users' => $model->banned()->paginate(10),
+    'pager' => $model->pager,
+];