Documentation/database/result.html

   1 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   2 <head>
   3         <title>CarbonPHP Documentation</title>
   4         <style type="text/css">
   5                 * {
   6                         margin: 0;
   7                         padding: 0;
   8                 }
   9
  10                 html {
  11                         font-family: "Lucida Sans Unicode", "Lucida Grande";
  12                         font-size: 14px;
  13                 }
  14
  15                 body {
  16                         background: #fff;
  17                         color: #666;
  18                 }
  19
  20                 h1 {
  21                         font-size: 15px;
  22                         font-weight: bold;
  23                         margin: 0 0 5px 0;
  24                 }
  25
  26                 h2 {
  27                         font-size: 13px;
  28                         font-weight: bold;
  29                         margin: 5px 0 5px 0;
  30                 }
  31
  32                 ol, ul {
  33                         margin: 10px 0 10px 0;
  34                         list-style-position: inside;
  35                 }
  36
  37                 p {
  38                         margin: 5px 0 5px 0;
  39                 }
  40
  41                 .content {
  42                         border: 1px dotted #444;
  43                         margin: 10px;
  44                         padding: 10px;
  45                         text-align: justify;
  46                         width: 700px;
  47                 }
  48
  49                 .example {
  50                         border: 1px solid #ccc;
  51                         background: #eee;
  52                         margin: 10px;
  53                         padding: 10px;
  54                         text-align: left;
  55                 }
  56         </style>
  57 </head>
  58
  59 <body>
  60         <div class="content">
  61                 <h1>Query Results</h1>
  62
  63                 <p>There are several ways to generate query results in CarbonPHP.</p>
  64         </div>
  65
  66         <div class="content">
  67                 <h1>result()</h1>
  68
  69                 <p>This method returns the query result as an array of objects, or an empty array on failure.  Typically you'll
  70                 use this in a <b>foreach ()</b> look like the following example.</p>
  71
  72                 <div class="example">
  73                         $query = $this->db-query('SQL QUERY');<br />
  74                         <br />
  75                         foreach ($query->result() as $row)<br />
  76                         &#123;<br />
  77                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row->title;<br />
  78                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row->author;<br />
  79                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row->post;<br />
  80                         &#125;
  81                 </div>
  82
  83                 <p>This method is an alias of the <b>result_object()</b> method.  If you run queries that may not produce
  84                 any results you are encouraged to test to see if there are any results.</p>
  85
  86                 <div class="example">
  87                         $query = $this->db->query('SQL QUERY');<br />
  88                         <br />
  89                         if ($query->num_rows() > 0)<br />
  90                         &#123;<br />
  91                         &nbsp;&nbsp;&nbsp;&nbsp;foreach ($query->result() as $row)<br />
  92                         &nbsp;&nbsp;&nbsp;&nbsp;&#123;<br />
  93                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;echo $row->title;<br />
  94                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;echo $row->author;<br />
  95                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;echo $row->post;<br />
  96                         &nbsp;&nbsp;&nbsp;&nbsp;&#125;<br />
  97                         &#125;
  98                 </div>
  99         </div>
 100
 101         <div class="content">
 102                 <h1>result_array()</h1>
 103
 104                 <p>This method returns the query result as a pure array, on an empty array on failure.  Typically you will use
 105                 this in a <b>foreach ()</b> loop like the following.</p>
 106
 107                 <div class="example">
 108                         $query = $this->db-query('SQL QUERY');<br />
 109                         <br />
 110                         foreach ($query->result_array() as $row)<br />
 111                         &#123;<br />
 112                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row['title'];<br />
 113                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row['author'];<br />
 114                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row['post'];<br />
 115                         &#125;
 116                 </div>
 117         </div>
 118
 119         <div class="content">
 120                 <h1>row()</h1>
 121
 122                 <p>The method returns a single result row.  If you query has more than one result in the row it returns only
 123                 the first row.  The first is returned as an object.</p>
 124
 125                 <div class="example">
 126                         $query = $this->db->query('SQL QUERY');<br />
 127                         <br />
 128                         if ($query->num_rows() > 0)<br />
 129                         &#123;<br />
 130                         &nbsp;&nbsp;&nbsp;&nbsp;$row = $query->row();<br />
 131                         <br />
 132                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row->title;<br />
 133                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row->author;<br />
 134                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row->post;<br />
 135                         &#125;
 136                 </div>
 137
 138                 <p>If you wish to return a specific row from the result set you can pass a digit as the parameter.</p>
 139
 140                 <div class="example">
 141                         $row = $query->row(<b>4</b>);
 142                 </div>
 143         </div>
 144
 145         <div class="content">
 146                 <h1>row_array()</h1>
 147
 148                 <p>This method is identical to the above <b>row()</b> method except that it will return the row as an array.</p>
 149
 150                 <div class="example">
 151                         $query = $this->db->query('SQL QUERY');<br />
 152                         <br />
 153                         if ($query->num_rows() > 0)<br />
 154                         &#123;<br />
 155                         &nbsp;&nbsp;&nbsp;&nbsp;$row = $query->row_array();<br />
 156                         <br />
 157                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row['title'];<br />
 158                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row['author'];<br />
 159                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row['post'];<br />
 160                         &#125;
 161                 </div>
 162
 163                 <p>If you wish to return a specific row from the result set you can pass a digit as the parameter.</p>
 164
 165                 <div class="example">
 166                         $row = $query->row_array(<b>6</b>);
 167                 </div>
 168
 169                 <p>In addition to the above method you can also walk through the results forwards or backwards.  You can use
 170                 the following methods.</p>
 171
 172                 <div class="example">
 173                         $row = $query->first_row();<br />
 174                         $row = $query->last_row();<br />
 175                         $row = $query->next_row();<br />
 176                         $row = $query->previous_row();
 177                 </div>
 178
 179                 <p>By default they return an object unless you pass the parameter '<b>array</b>' like the following.</p>
 180
 181                 <div class="example">
 182                         $row = $query->first_row('array');<br />
 183                         $row = $query->last_row('array');<br />
 184                         $row = $query->next_row('array');<br />
 185                         $row = $query->previous_row('array')
 186                 </div>
 187         </div>
 188
 189         <div class="content">
 190                 <h1>num_rows()</h1>
 191
 192                 <p>This method returns the amount of rows that are returned by a query.</p>
 193
 194                 <div class="example">
 195                         $query = $this->db->query('SELECT * FROM `some_table`');<br />
 196                         <br />
 197                         echo $query->num_rows();
 198                 </div>
 199         </div>
 200
 201         <div class="content">
 202                 <h1>num_fields()</h1>
 203
 204                 <p>This method returns the number of fields returned by a query.</p>
 205
 206                 <div class="example">
 207                         $query = $this->db->query('SELECT * FROM `some_table`');<br />
 208                         <br />
 209                         echo $query->num_fields();
 210                 </div>
 211         </div>
 212
 213         <div class="content">
 214                 <h1>free_result()</h1>
 215
 216                 <p>This method will free the memory associated with the result and deletes the results resource ID.  Normally
 217                 PHP frees its memory automatically at the end of the execution of the script.  However if you are running many
 218                 queries in a speicifc script you may wish to free a result after each query to cut down on the memory usage.</p>
 219
 220                 <div class="example">
 221                         $query = $this->db->query('SELECT `title` FROM `some_table`');<br />
 222                         <br />
 223                         foreach ($query->result() as $row)<br />
 224                         &#123;<br />
 225                         &nbsp;&nbsp;&nbsp;&nbsp;echo $row->title;<br />
 226                         &#125;<br />
 227                         <br />
 228                         $query->free_result();
 229                         <br />
 230                         $query2 = $this->db->query('SELECT `author` FROM `some_table`');<br />
 231                         <br />
 232                         $row = $query2->row();<br />
 233                         echo $row->author;<br />
 234                         <br />
 235                         $query2->free_result();
 236                 </div>
 237         </div>
 238 </body>
 239
 240 </html>