From cf3cc1dadd44c4dee21978238125355826e5fb24 Mon Sep 17 00:00:00 2001 From: Lonnie Ezell Date: Tue, 21 Jul 2015 10:22:41 -0500 Subject: Adding Custom Result object documentation to Query Results docs. --- user_guide_src/source/database/results.rst | 87 ++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index ac44566d3..54465b39a 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -172,6 +172,93 @@ the returned value's type:: $query->unbuffered_row('object'); // object $query->unbuffered_row('array'); // associative array +********************* +Custom Result Objects +********************* + +You can have the results returned as an instance of a custom class instead of a stdClass or array, +as the ``result()`` and ``result_array()`` methods allow.This requires that the class is already +loaded into memory. The class will have all values returned from the database set on the class +as class variables. If your class already has those class variables created and ``protected`` then +you should provide a ``__set()`` method to allow the class variables to be set. + +Example:: + + class User { + protected $id; + protected $email; + protected $username; + protected $last_login; + + public function last_login($format) + { + return date($format, $this->last_login); + } + + public function __set($name, $value) + { + $allowed_vars = array('id', 'email', 'username'); + + if (in_array($allowed_vars, $name) + { + $this->$name = $value; + } + } + + public function __get($name) + { + if (isset($this->$name)) + { + return $this->$name; + } + } + } + +In addition to the two methods listed below, the following methods also can take a class name +to return the results as: ``first_row()``, ``last_row()``, ``next_row()``, and ``previous_row()``. + +**custom_result_object()** + +Returns the entire result set as an array of instances of the class requested. The only parameter +is the name of the class to instantiate. + +Example:: + + $query = $this->db->query("YOUR QUERY"); + + if ($query->num_rows() > 0) + { + foreach ($query->custom_result_object('User') as $row) + { + echo $row->id; + echo $row->email; + echo $row->last_login('Y-m-d'); + } + } + +**custom_row_object()** + +Returns a single row from your query results. The first parameter is the row number of the results. +The second parameter is the class name to instantiate. + +Example:: + + $query = $this->db->query("YOUR QUERY"); + + if ($query->num_rows() > 0) + { + $row = $query->custom_row_object(0, 'User); + + echo $row->email; // access attributes + echo $row->last_login('Y-m-d'); // access class methods + } + +You can also use the ``row()`` method in exactly the same way. + +Example:: + + $row = $query->custom_row_object(0, 'User); + ********************* Result Helper Methods ********************* -- cgit v1.2.3-24-g4f1b From d30f35d361c3038c77fd97747d8083a8022855ac Mon Sep 17 00:00:00 2001 From: Lonnie Ezell Date: Tue, 21 Jul 2015 10:48:50 -0500 Subject: Added missing space. --- user_guide_src/source/database/results.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index 54465b39a..658b0bc59 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -177,7 +177,7 @@ Custom Result Objects ********************* You can have the results returned as an instance of a custom class instead of a stdClass or array, -as the ``result()`` and ``result_array()`` methods allow.This requires that the class is already +as the ``result()`` and ``result_array()`` methods allow. This requires that the class is already loaded into memory. The class will have all values returned from the database set on the class as class variables. If your class already has those class variables created and ``protected`` then you should provide a ``__set()`` method to allow the class variables to be set. -- cgit v1.2.3-24-g4f1b From 2520182d875b6b5c9589cc6d8b55ce9c6a6ce5ce Mon Sep 17 00:00:00 2001 From: Lonnie Ezell Date: Tue, 21 Jul 2015 21:32:43 -0500 Subject: Rewording and typos --- user_guide_src/source/database/results.rst | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index 658b0bc59..2a2cf38ab 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -178,13 +178,14 @@ Custom Result Objects You can have the results returned as an instance of a custom class instead of a stdClass or array, as the ``result()`` and ``result_array()`` methods allow. This requires that the class is already -loaded into memory. The class will have all values returned from the database set on the class -as class variables. If your class already has those class variables created and ``protected`` then -you should provide a ``__set()`` method to allow the class variables to be set. +loaded into memory. The object will have all values returned from the database set as properties. +If these have been declared and are non-public then you should provide a ``__set()`` +method to allow them to be set. Example:: class User { + protected $id; protected $email; protected $username; @@ -192,7 +193,8 @@ Example:: public function last_login($format) { - return date($format, $this->last_login); + $date = DateTime::setTimestamp($this->last_login); + return $date->format($format); } public function __set($name, $value) @@ -226,14 +228,13 @@ Example:: $query = $this->db->query("YOUR QUERY"); - if ($query->num_rows() > 0) + $rows = $query->custom_result_object('User'); + + foreach ($rows as $row) { - foreach ($query->custom_result_object('User') as $row) - { - echo $row->id; - echo $row->email; - echo $row->last_login('Y-m-d'); - } + echo $row->id; + echo $row->email; + echo $row->last_login('Y-m-d'); } **custom_row_object()** @@ -247,7 +248,7 @@ Example:: if ($query->num_rows() > 0) { - $row = $query->custom_row_object(0, 'User); + $row = $query->custom_row_object(0, 'User'); echo $row->email; // access attributes echo $row->last_login('Y-m-d'); // access class methods @@ -257,7 +258,7 @@ You can also use the ``row()`` method in exactly the same way. Example:: - $row = $query->custom_row_object(0, 'User); + $row = $query->custom_row_object(0, 'User'); ********************* Result Helper Methods -- cgit v1.2.3-24-g4f1b From abf089a6c8f50c86601548abf7e827f4d067a348 Mon Sep 17 00:00:00 2001 From: Lonnie Ezell Date: Wed, 22 Jul 2015 09:00:37 -0500 Subject: Revamping User class example for Custom Result Objects --- user_guide_src/source/database/results.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index 2a2cf38ab..3837a7736 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -193,18 +193,15 @@ Example:: public function last_login($format) { - $date = DateTime::setTimestamp($this->last_login); - return $date->format($format); + return $this->last_login->format($format); } public function __set($name, $value) { - $allowed_vars = array('id', 'email', 'username'); - - if (in_array($allowed_vars, $name) - { - $this->$name = $value; - } + if ($name === 'last_login') + { + $this->last_login = DateTime::createFromFormat('U', $value); + } } public function __get($name) -- cgit v1.2.3-24-g4f1b From c87a66b4023396900aa349a42f4a93bc9f6e8fa9 Mon Sep 17 00:00:00 2001 From: Lonnie Ezell Date: Wed, 22 Jul 2015 21:48:02 -0500 Subject: Tabs vs Spaces and the forgotten rewrite. --- user_guide_src/source/database/results.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index 3837a7736..071d9718e 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -199,9 +199,9 @@ Example:: public function __set($name, $value) { if ($name === 'last_login') - { - $this->last_login = DateTime::createFromFormat('U', $value); - } + { + $this->last_login = DateTime::createFromFormat('U', $value); + } } public function __get($name) @@ -243,10 +243,10 @@ Example:: $query = $this->db->query("YOUR QUERY"); - if ($query->num_rows() > 0) - { - $row = $query->custom_row_object(0, 'User'); + $row = $query->custom_row_object(0, 'User'); + if (is_object($row)) + { echo $row->email; // access attributes echo $row->last_login('Y-m-d'); // access class methods } -- cgit v1.2.3-24-g4f1b