docs: improve Upgrade Models sample code

Author: kenjis

user_guide_src/source/installation/upgrade_models.rst

@@ -24,7 +24,9 @@ Upgrade Guide
 2. Add this line just after the opening php tag: ``namespace App\Models;``.
 3. Below the ``namespace App\Models;`` line add this line: ``use CodeIgniter\Model;``.
 4. Replace ``extends CI_Model`` with ``extends Model``.
-5. Instead of CI3's ``$this->load->model('x');``, you would now use ``$this->x = new X();``, following namespaced conventions for your component. Alternatively, you can use the :php:func:`model()` function: ``$this->x = model('X');``.
+5. Add the ``protected $table`` property and set the table name.
+6. Add the ``protected $allowedFields`` property and set the array of field names to allow to insert/update.
+7. Instead of CI3's ``$this->load->model('x');``, you would now use ``$this->x = new X();``, following namespaced conventions for your component. Alternatively, you can use the :php:func:`model()` function: ``$this->x = model('X');``.
 
 If you use sub-directories in your model structure you have to change the namespace according to that.
 Example: You have a version 3 model located in **application/models/users/user_contact.php** the namespace has to be ``namespace App\Models\Users;`` and the model path in the version 4 should look like this: **app/Models/Users/UserContact.php**
@@ -51,4 +53,10 @@ Path: **app/Models**:
 
 .. literalinclude:: upgrade_models/001.php
 
-To insert data you can just directly call the ``$model->insert()`` method because this method is built-in since CI4.
+The above code is direct translation from CI3 to CI4. It uses Query Builder
+directly in the model. Note that when you use Query Builder directly, you cannot
+use features in CodeIgniter's Model.
+
+If you want to use CodeIgniter's Model features, the code will be:
+
+.. literalinclude:: upgrade_models/002.php

user_guide_src/source/installation/upgrade_models/001.php

@@ -4,7 +4,20 @@
 
 use CodeIgniter\Model;
 
-class UserContact extends Model
+class NewsModel extends Model
 {
-    // insert() method already implemented in parent
+    // Sets the table name.
+    protected $table = 'news';
+
+    public function setNews($title, $slug, $text)
+    {
+        $data = [
+            'title' => $title,
+            'slug'  => $slug,
+            'text'  => $text,
+        ];
+
+        // Gets the Query Builder for the table, and calls `insert()`.
+        return $this->builder()->insert($data);
+    }
 }

user_guide_src/source/installation/upgrade_models/002.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Models;
+
+use CodeIgniter\Model;
+
+class NewsModel extends Model
+{
+    // Sets the table name.
+    protected $table = 'news';
+
+    // Sets the field names to allow to insert/update.
+    protected $allowedFields = ['title', 'slug', 'body'];
+
+    public function setNews($title, $slug, $text)
+    {
+        $data = [
+            'title' => $title,
+            'slug'  => $slug,
+            'text'  => $text,
+        ];
+
+        // Uses Model's`insert()` method.
+        return $this->insert($data);
+    }
+}

user_guide_src/source/installation/upgrade_models/ci3sample/001.php

@@ -1,13 +1,15 @@
 <?php
 
-class User_contact extends CI_Model
+class News_model extends CI_Model
 {
-    public function insert($name, $address, $email)
+    public function set_news($title, $slug, $text)
     {
-        $this->db->insert('user_contacts', array(
-            'name'    => $name,
-            'address' => $address,
-            'email'   => $email,
-        ));
+        $data = array(
+            'title' => $title,
+            'slug'  => $slug,
+            'text'  => $text,
+        );
+
+        return $this->db->insert('news', $data);
     }
 }