diff --git a/user_guide_src/source/models/model.rst b/user_guide_src/source/models/model.rst index 08224c7157ec..9d80b03c74a7 100644 --- a/user_guide_src/source/models/model.rst +++ b/user_guide_src/source/models/model.rst @@ -24,7 +24,7 @@ You can access models within your classes by creating a new instance or using th :: // Create a new class manually - $userModel = new App\Models\UserModel(); + $userModel = new \App\Models\UserModel(); // Create a new class with the model function $userModel = model('App\Models\UserModel', false); @@ -59,14 +59,14 @@ Creating Your Model To take advantage of CodeIgniter's model, you would simply create a new model class that extends ``CodeIgniter\Model``:: - find($user_id); + $user = $userModel->find($user_id); The value is returned in the format specified in $returnType. You can specify more than one row to return by passing an array of primaryKey values instead of just one:: - $users = $userModel->find([1,2,3]); + $users = $userModel->find([1,2,3]); If no parameters are passed in, will return all rows in that model's table, effectively acting like findAll(), though less explicit. **findColumn()** - Returns null or an indexed array of column values:: +Returns null or an indexed array of column values:: - $user = $userModel->findColumn($column_name); + $user = $userModel->findColumn($column_name); - $column_name should be a name of single column else you will get the DataException. +$column_name should be a name of single column else you will get the DataException. **findAll()** Returns all results:: - $users = $userModel->findAll(); + $users = $userModel->findAll(); This query may be modified by interjecting Query Builder commands as needed prior to calling this method:: - $users = $userModel->where('active', 1) - ->findAll(); + $users = $userModel->where('active', 1) + ->findAll(); You can pass in a limit and offset values as the first and second parameters, respectively:: - $users = $userModel->findAll($limit, $offset); + $users = $userModel->findAll($limit, $offset); **first()** Returns the first row in the result set. This is best used in combination with the query builder. :: - $user = $userModel->where('deleted', 0) - ->first(); + $user = $userModel->where('deleted', 0) + ->first(); **withDeleted()** @@ -281,20 +281,20 @@ If $useSoftDeletes is true, then the find* methods will not return any rows wher To temporarily override this, you can use the withDeleted() method prior to calling the find* method. :: - // Only gets non-deleted rows (deleted = 0) - $activeUsers = $userModel->findAll(); + // Only gets non-deleted rows (deleted = 0) + $activeUsers = $userModel->findAll(); - // Gets all rows - $allUsers = $userModel->withDeleted() - ->findAll(); + // Gets all rows + $allUsers = $userModel->withDeleted() + ->findAll(); **onlyDeleted()** Whereas withDeleted() will return both deleted and not-deleted rows, this method modifies the next find* methods to return only soft deleted rows:: - $deletedUsers = $userModel->onlyDeleted() - ->findAll(); + $deletedUsers = $userModel->onlyDeleted() + ->findAll(); Saving Data ----------- @@ -305,12 +305,12 @@ An associative array of data is passed into this method as the only parameter to row of data in the database. The array's keys must match the name of the columns in a $table, while the array's values are the values to save for that key:: - $data = [ - 'username' => 'darth', - 'email' => 'd.vader@theempire.com' - ]; + $data = [ + 'username' => 'darth', + 'email' => 'd.vader@theempire.com' + ]; - $userModel->insert($data); + $userModel->insert($data); **update()** @@ -318,20 +318,20 @@ Updates an existing record in the database. The first parameter is the $primaryK An associative array of data is passed into this method as the second parameter. The array's keys must match the name of the columns in a $table, while the array's values are the values to save for that key:: - $data = [ - 'username' => 'darth', - 'email' => 'd.vader@theempire.com' - ]; + $data = [ + 'username' => 'darth', + 'email' => 'd.vader@theempire.com' + ]; - $userModel->update($id, $data); + $userModel->update($id, $data); Multiple records may be updated with a single call by passing an array of primary keys as the first parameter:: $data = [ - 'active' => 1 - ]; + 'active' => 1 + ]; - $userModel->update([1, 2, 3], $data); + $userModel->update([1, 2, 3], $data); When you need a more flexible solution, you can leave the parameters empty and it functions like the Query Builder's update command, with the added benefit of validation, events, etc:: @@ -346,24 +346,24 @@ update command, with the added benefit of validation, events, etc:: This is a wrapper around the insert() and update() methods that handle inserting or updating the record automatically, based on whether it finds an array key matching the $primaryKey value:: - // Defined as a model property - $primaryKey = 'id'; + // Defined as a model property + $primaryKey = 'id'; - // Does an insert() - $data = [ - 'username' => 'darth', - 'email' => 'd.vader@theempire.com' - ]; + // Does an insert() + $data = [ + 'username' => 'darth', + 'email' => 'd.vader@theempire.com' + ]; - $userModel->save($data); + $userModel->save($data); - // Performs an update, since the primary key, 'id', is found. - $data = [ - 'id' => 3, - 'username' => 'darth', - 'email' => 'd.vader@theempire.com' - ]; - $userModel->save($data); + // Performs an update, since the primary key, 'id', is found. + $data = [ + 'id' => 3, + 'username' => 'darth', + 'email' => 'd.vader@theempire.com' + ]; + $userModel->save($data); The save method also can make working with custom class result objects much simpler by recognizing a non-simple object and grabbing its public and protected values into an array, which is then passed to the appropriate @@ -373,59 +373,59 @@ class is responsible for maintaining the business logic surrounding the object i elements in a certain way, etc. They shouldn't have any idea about how they are saved to the database. At their simplest, they might look like this:: - namespace App\Entities; - - class Job - { - protected $id; - protected $name; - protected $description; - - public function __get($key) - { - if (property_exists($this, $key)) - { - return $this->$key; - } - } - - public function __set($key, $value) - { - if (property_exists($this, $key)) - { - $this->$key = $value; - } - } - } + namespace App\Entities; + + class Job + { + protected $id; + protected $name; + protected $description; + + public function __get($key) + { + if (property_exists($this, $key)) + { + return $this->$key; + } + } + + public function __set($key, $value) + { + if (property_exists($this, $key)) + { + $this->$key = $value; + } + } + } A very simple model to work with this might look like:: - use CodeIgniter\Model; + use CodeIgniter\Model; - class JobModel extends Model - { - protected $table = 'jobs'; - protected $returnType = '\App\Entities\Job'; - protected $allowedFields = [ - 'name', 'description' - ]; - } + class JobModel extends Model + { + protected $table = 'jobs'; + protected $returnType = '\App\Entities\Job'; + protected $allowedFields = [ + 'name', 'description' + ]; + } This model works with data from the ``jobs`` table, and returns all results as an instance of ``App\Entities\Job``. When you need to persist that record to the database, you will need to either write custom methods, or use the model's ``save()`` method to inspect the class, grab any public and private properties, and save them to the database:: - // Retrieve a Job instance - $job = $model->find(15); + // Retrieve a Job instance + $job = $model->find(15); - // Make some changes - $job->name = "Foobar"; + // Make some changes + $job->name = "Foobar"; - // Save the changes - $model->save($job); + // Save the changes + $model->save($job); .. note:: If you find yourself working with Entities a lot, CodeIgniter provides a built-in :doc:`Entity class ` - that provides several handy features that make developing Entities simpler. + that provides several handy features that make developing Entities simpler. Deleting Data ------------- @@ -434,7 +434,7 @@ Deleting Data Takes a primary key value as the first parameter and deletes the matching record from the model's table:: - $userModel->delete(12); + $userModel->delete(12); If the model's $useSoftDeletes value is true, this will update the row to set ``deleted_at`` to the current date and time. You can force a permanent delete by setting the second parameter as true. @@ -452,7 +452,7 @@ previously:: Cleans out the database table by permanently removing all rows that have 'deleted_at IS NOT NULL'. :: - $userModel->purgeDeleted(); + $userModel->purgeDeleted(); Validating Data --------------- @@ -464,81 +464,81 @@ prior to saving to the database with the ``insert()``, ``update()``, or ``save() The first step is to fill out the ``$validationRules`` class property with the fields and rules that should be applied. If you have custom error message that you want to use, place them in the ``$validationMessages`` array:: - class UserModel extends Model - { - protected $validationRules = [ - 'username' => 'required|alpha_numeric_space|min_length[3]', - 'email' => 'required|valid_email|is_unique[users.email]', - 'password' => 'required|min_length[8]', - 'pass_confirm' => 'required_with[password]|matches[password]' - ]; - - protected $validationMessages = [ - 'email' => [ - 'is_unique' => 'Sorry. That email has already been taken. Please choose another.' - ] - ]; - } + class UserModel extends Model + { + protected $validationRules = [ + 'username' => 'required|alpha_numeric_space|min_length[3]', + 'email' => 'required|valid_email|is_unique[users.email]', + 'password' => 'required|min_length[8]', + 'pass_confirm' => 'required_with[password]|matches[password]' + ]; + + protected $validationMessages = [ + 'email' => [ + 'is_unique' => 'Sorry. That email has already been taken. Please choose another.' + ] + ]; + } The other way to set the validation message to fields by functions, .. php:function:: setValidationMessage($field, $fieldMessages) - :param string $field - :param array $fieldMessages + :param string $field: + :param array $fieldMessages: - This function will set the field wise error messages. + This function will set the field wise error messages. - Usage example:: + Usage example:: - $fieldName = 'name'; - $fieldValidationMessage = array( - 'required' => 'Your name is required here', - ); - $model->setValidationMessage($fieldName, $fieldValidationMessage); + $fieldName = 'name'; + $fieldValidationMessage = [ + 'required' => 'Your name is required here', + ]; + $model->setValidationMessage($fieldName, $fieldValidationMessage); .. php:function:: setValidationMessages($fieldMessages) - :param array $fieldMessages + :param array $fieldMessages: - This function will set the field messages. + This function will set the field messages. - Usage example:: + Usage example:: - $fieldValidationMessage = array( - 'name' => array( - 'required' => 'Your baby name is missing.', - 'min_length' => 'Too short, man!', - ), - ); - $model->setValidationMessages($fieldValidationMessage); + $fieldValidationMessage = [ + 'name' => [ + 'required' => 'Your baby name is missing.', + 'min_length' => 'Too short, man!', + ], + ]; + $model->setValidationMessages($fieldValidationMessage); Now, whenever you call the ``insert()``, ``update()``, or ``save()`` methods, the data will be validated. If it fails, the model will return boolean **false**. You can use the ``errors()`` method to retrieve the validation errors:: - if ($model->save($data) === false) - { - return view('updateUser', ['errors' => $model->errors()]; - } + if ($model->save($data) === false) + { + return view('updateUser', ['errors' => $model->errors()]; + } This returns an array with the field names and their associated errors that can be used to either show all of the errors at the top of the form, or to display them individually:: - -
= $error ?>
- -= $error ?>
+ +