documentation/manual/en/module_specs/Zend_Db_Table_Rowset.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.db.table.rowset">
   4     <title>Zend_Db_Table_Rowset</title>
   5
   6     <sect2 id="zend.db.table.rowset.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             When you run a query against a Table class using the <methodname>find()</methodname> or
  11             <methodname>fetchAll()</methodname> methods, the result is returned in an object of type
  12             <classname>Zend_Db_Table_Rowset_Abstract</classname>. A Rowset contains a collection of
  13             objects descending from <classname>Zend_Db_Table_Row_Abstract</classname>. You can
  14             iterate through the Rowset and access individual Row objects, reading or modifying data
  15             in the Rows.
  16         </para>
  17     </sect2>
  18
  19     <sect2 id="zend.db.table.rowset.fetch">
  20         <title>Fetching a Rowset</title>
  21
  22         <para>
  23             <classname>Zend_Db_Table_Abstract</classname> provides methods
  24             <methodname>find()</methodname> and <methodname>fetchAll()</methodname>, each of which
  25             returns an object of type <classname>Zend_Db_Table_Rowset_Abstract</classname>.
  26         </para>
  27
  28         <example id="zend.db.table.rowset.fetch.example">
  29             <title>Example of fetching a rowset</title>
  30
  31             <programlisting language="php"><![CDATA[
  32 $bugs   = new Bugs();
  33 $rowset = $bugs->fetchAll("bug_status = 'NEW'");
  34 ]]></programlisting>
  35         </example>
  36     </sect2>
  37
  38     <sect2 id="zend.db.table.rowset.rows">
  39         <title>Retrieving Rows from a Rowset</title>
  40
  41         <para>
  42             The Rowset itself is usually less interesting than the Rows that it contains. This
  43             section illustrates how to get the Rows that comprise the Rowset.
  44         </para>
  45
  46         <para>
  47             A legitimate query returns zero rows when no rows in the database match the query
  48             conditions. Therefore, a Rowset object might contain zero Row objects. Since
  49             <classname>Zend_Db_Table_Rowset_Abstract</classname> implements the
  50             <classname>Countable</classname> interface, you can use <methodname>count()</methodname>
  51             to determine the number of Rows in the Rowset.
  52         </para>
  53
  54         <example id="zend.db.table.rowset.rows.counting.example">
  55             <title>Counting the Rows in a Rowset</title>
  56
  57             <programlisting language="php"><![CDATA[
  58 $rowset   = $bugs->fetchAll("bug_status = 'FIXED'");
  59
  60 $rowCount = count($rowset);
  61
  62 if ($rowCount > 0) {
  63     echo "found $rowCount rows";
  64 } else {
  65     echo 'no rows matched the query';
  66 }
  67 ]]></programlisting>
  68         </example>
  69
  70         <example id="zend.db.table.rowset.rows.current.example">
  71             <title>Reading a Single Row from a Rowset</title>
  72
  73             <para>
  74                 The simplest way to access a Row from a Rowset is to use the
  75                 <methodname>current()</methodname> method. This is particularly appropriate when the
  76                 Rowset contains exactly one Row.
  77             </para>
  78
  79             <programlisting language="php"><![CDATA[
  80 $bugs   = new Bugs();
  81 $rowset = $bugs->fetchAll("bug_id = 1");
  82 $row    = $rowset->current();
  83 ]]></programlisting>
  84         </example>
  85
  86         <para>
  87             If the Rowset contains zero rows, <methodname>current()</methodname> returns
  88             <acronym>PHP</acronym>'s <constant>NULL</constant> value.
  89         </para>
  90
  91         <example id="zend.db.table.rowset.rows.iterate.example">
  92             <title>Iterating through a Rowset</title>
  93
  94             <para>
  95                 Objects descending from <classname>Zend_Db_Table_Rowset_Abstract</classname>
  96                 implement the <classname>SeekableIterator</classname> interface, which means you can
  97                 loop through them using the <methodname>foreach()</methodname> construct. Each value
  98                 you retrieve this way is a <classname>Zend_Db_Table_Row_Abstract</classname> object
  99                 that corresponds to one record from the table.
 100             </para>
 101
 102             <programlisting language="php"><![CDATA[
 103 $bugs = new Bugs();
 104
 105 // fetch all records from the table
 106 $rowset = $bugs->fetchAll();
 107
 108 foreach ($rowset as $row) {
 109
 110     // output 'Zend_Db_Table_Row' or similar
 111     echo get_class($row) . "\n";
 112
 113     // read a column in the row
 114     $status = $row->bug_status;
 115
 116     // modify a column in the current row
 117     $row->assigned_to = 'mmouse';
 118
 119     // write the change to the database
 120     $row->save();
 121 }
 122 ]]></programlisting>
 123         </example>
 124
 125         <example id="zend.db.table.rowset.rows.seek.example">
 126             <title>Seeking to a known position into a Rowset</title>
 127
 128             <para>
 129                 <classname>SeekableIterator</classname> allows you to seek to a position that you
 130                 would like the iterator to jump to. Simply use the <methodname>seek()</methodname>
 131                 method for that. Pass it an integer representing the number of the Row you would
 132                 like your Rowset to point to next, don't forget that it starts with index 0. If the
 133                 index is wrong, ie doesn't exist, an exception will be thrown. You should use
 134                 <methodname>count()</methodname> to check the number of results before seeking to a
 135                 position.
 136             </para>
 137
 138             <programlisting language="php"><![CDATA[
 139 $bugs = new Bugs();
 140
 141 // fetch all records from the table
 142 $rowset = $bugs->fetchAll();
 143
 144 // takes the iterator to the 9th element (zero is one element) :
 145 $rowset->seek(8);
 146
 147 // retrieve it
 148 $row9 = $rowset->current();
 149
 150 // and use it
 151 $row9->assigned_to = 'mmouse';
 152 $row9->save();
 153 ]]></programlisting>
 154         </example>
 155
 156         <para>
 157             <methodname>getRow()</methodname> allows you to get a specific row in the Rowset,
 158             knowing its position; don't forget however that positions start with index zero. The
 159             first parameter for <methodname>getRow()</methodname> is an integer for the position
 160             asked. The second optional parameter is a boolean; it tells the Rowset iterator if
 161             it must seek to that position in the same time, or not (default is
 162             <constant>FALSE</constant>). This method returns a
 163             <classname>Zend_Db_Table_Row</classname> object by default. If the
 164             position requested does not exist, an exception will be thrown. Here is an example:
 165         </para>
 166
 167         <programlisting language="php"><![CDATA[
 168 $bugs = new Bugs();
 169
 170 // fetch all records from the table
 171 $rowset = $bugs->fetchAll();
 172
 173 // retrieve the 9th element immediately:
 174 $row9->getRow(8);
 175
 176 // and use it:
 177 $row9->assigned_to = 'mmouse';
 178 $row9->save();
 179 ]]></programlisting>
 180
 181         <para>
 182             After you have access to an individual Row object, you can manipulate the Row using
 183             methods described in <link linkend="zend.db.table.row">Zend_Db_Table_Row</link>.
 184         </para>
 185     </sect2>
 186
 187     <sect2 id="zend.db.table.rowset.to-array">
 188         <title>Retrieving a Rowset as an Array</title>
 189
 190         <para>
 191             You can access all the data in the Rowset as an array using the
 192             <methodname>toArray()</methodname> method of the Rowset object. This returns an array
 193             containing one entry per Row. Each entry is an associative array having keys that
 194             correspond to column names and elements that correspond to the respective column values.
 195         </para>
 196
 197         <example id="zend.db.table.rowset.to-array.example">
 198             <title>Using toArray()</title>
 199
 200             <programlisting language="php"><![CDATA[
 201 $bugs   = new Bugs();
 202 $rowset = $bugs->fetchAll();
 203
 204 $rowsetArray = $rowset->toArray();
 205
 206 $rowCount = 1;
 207 foreach ($rowsetArray as $rowArray) {
 208     echo "row #$rowCount:\n";
 209     foreach ($rowArray as $column => $value) {
 210         echo "\t$column => $value\n";
 211     }
 212     ++$rowCount;
 213     echo "\n";
 214 }
 215 ]]></programlisting>
 216         </example>
 217
 218         <para>
 219             The array returned from <methodname>toArray()</methodname> is not updateable. That is,
 220             you can modify values in the array as you can with any array, but changes to the array
 221             data are not propagated to the database.
 222         </para>
 223     </sect2>
 224
 225     <sect2 id="zend.db.table.rowset.serialize">
 226         <title>Serializing and Unserializing a Rowset</title>
 227
 228         <para>
 229             Objects of type <classname>Zend_Db_Table_Rowset_Abstract</classname> are serializable.
 230             In a similar fashion to serializing an individual Row object, you can serialize a Rowset
 231             and unserialize it later.
 232         </para>
 233
 234         <example id="zend.db.table.rowset.serialize.example.serialize">
 235             <title>Serializing a Rowset</title>
 236
 237             <para>
 238                 Simply use <acronym>PHP</acronym>'s <methodname>serialize()</methodname> function to
 239                 create a string containing a byte-stream representation of the Rowset object
 240                 argument.
 241             </para>
 242
 243             <programlisting language="php"><![CDATA[
 244 $bugs   = new Bugs();
 245 $rowset = $bugs->fetchAll();
 246
 247 // Convert object to serialized form
 248 $serializedRowset = serialize($rowset);
 249
 250 // Now you can write $serializedRowset to a file, etc.
 251 ]]></programlisting>
 252         </example>
 253
 254         <example id="zend.db.table.rowset.serialize.example.unserialize">
 255             <title>Unserializing a Serialized Rowset</title>
 256
 257             <para>
 258                 Use <acronym>PHP</acronym>'s <methodname>unserialize()</methodname> function to
 259                 restore a string containing a byte-stream representation of an object. The function
 260                 returns the original object.
 261             </para>
 262
 263             <para>
 264                 Note that the Rowset object returned is in a <emphasis>disconnected</emphasis>
 265                 state. You can iterate through the Rowset and read the Row objects and their
 266                 properties, but you cannot change values in the Rows or execute other methods that
 267                 require a database connection (for example, queries against related tables).
 268             </para>
 269
 270             <programlisting language="php"><![CDATA[
 271 $rowsetDisconnected = unserialize($serializedRowset);
 272
 273 // Now you can use object methods and properties, but read-only
 274 $row = $rowsetDisconnected->current();
 275 echo $row->bug_description;
 276 ]]></programlisting>
 277         </example>
 278
 279         <note>
 280             <title>Why do Rowsets unserialize in a disconnected state?</title>
 281
 282             <para>
 283                 A serialized object is a string that is readable to anyone who possesses it. It
 284                 could be a security risk to store parameters such as database account and password
 285                 in plain, unencrypted text in the serialized string. You would not want to store
 286                 such data to a text file that is not protected, or send it in an email or other
 287                 medium that is easily read by potential attackers. The reader of the serialized
 288                 object should not be able to use it to gain access to your database without knowing
 289                 valid credentials.
 290             </para>
 291         </note>
 292
 293         <para>
 294             You can reactivate a disconnected Rowset using the <methodname>setTable()</methodname>
 295             method. The argument to this method is a valid object of type
 296             <classname>Zend_Db_Table_Abstract</classname>, which you create. Creating a Table object
 297             requires a live connection to the database, so by reassociating the Table with the
 298             Rowset, the Rowset gains access to the database. Subsequently, you can change values in
 299             the Row objects contained in the Rowset and save the changes to the database.
 300         </para>
 301
 302         <example id="zend.db.table.rowset.serialize.example.set-table">
 303             <title>Reactivating a Rowset as Live Data</title>
 304
 305             <programlisting language="php"><![CDATA[
 306 $rowset = unserialize($serializedRowset);
 307
 308 $bugs = new Bugs();
 309
 310 // Reconnect the rowset to a table, and
 311 // thus to a live database connection
 312 $rowset->setTable($bugs);
 313
 314 $row = $rowset->current();
 315
 316 // Now you can make changes to the row and save them
 317 $row->bug_status = 'FIXED';
 318 $row->save();
 319 ]]></programlisting>
 320         </example>
 321
 322         <para>
 323             Reactivating a Rowset with <methodname>setTable()</methodname> also reactivates all the
 324             Row objects contained in that Rowset.
 325         </para>
 326     </sect2>
 327
 328     <sect2 id="zend.db.table.rowset.extending">
 329         <title>Extending the Rowset class</title>
 330
 331         <para>
 332             You can use an alternative concrete class for instances of Rowsets
 333             by extending <classname>Zend_Db_Table_Rowset_Abstract</classname>. Specify the custom
 334             Rowset class by name either in the <varname>$_rowsetClass</varname>
 335             protected member of a Table class, or in the array argument of the
 336             constructor of a Table object.
 337         </para>
 338
 339         <example id="zend.db.table.rowset.extending.example">
 340             <title>Specifying a custom Rowset class</title>
 341
 342             <programlisting language="php"><![CDATA[
 343 class MyRowset extends Zend_Db_Table_Rowset_Abstract
 344 {
 345     // ...customizations
 346 }
 347
 348 // Specify a custom Rowset to be used by default
 349 // in all instances of a Table class.
 350 class Products extends Zend_Db_Table_Abstract
 351 {
 352     protected $_name = 'products';
 353     protected $_rowsetClass = 'MyRowset';
 354 }
 355
 356 // Or specify a custom Rowset to be used in one
 357 // instance of a Table class.
 358 $bugs = new Bugs(array('rowsetClass' => 'MyRowset'));
 359 ]]></programlisting>
 360         </example>
 361
 362         <para>
 363             Typically, the standard <classname>Zend_Db_Rowset</classname> concrete class is
 364             sufficient for most usage. However, you might find it useful
 365             to add new logic to a Rowset, specific to a given Table.
 366             For example, a new method could calculate an aggregate
 367             over all the Rows in the Rowset.
 368         </para>
 369
 370         <example id="zend.db.table.rowset.extending.example-aggregate">
 371             <title>Example of Rowset class with a new method</title>
 372
 373             <programlisting language="php"><![CDATA[
 374 class MyBugsRowset extends Zend_Db_Table_Rowset_Abstract
 375 {
 376     /**
 377      * Find the Row in the current Rowset with the
 378      * greatest value in its 'updated_at' column.
 379      */
 380     public function getLatestUpdatedRow()
 381     {
 382         $max_updated_at = 0;
 383         $latestRow = null;
 384         foreach ($this as $row) {
 385             if ($row->updated_at > $max_updated_at) {
 386                 $latestRow = $row;
 387             }
 388         }
 389         return $latestRow;
 390     }
 391 }
 392
 393 class Bugs extends Zend_Db_Table_Abstract
 394 {
 395     protected $_name = 'bugs';
 396     protected $_rowsetClass = 'MyBugsRowset';
 397 }
 398 ]]></programlisting>
 399         </example>
 400     </sect2>
 401 </sect1>
 402 <!--
 403 vim:se ts=4 sw=4 et:
 404 -->