a copy of the original data structure, saved before set(). Used to create the WHERE clause in save()

• access: protected
• see: Storable::$_data

the string to pass to DB to connect to the database.

Initialized to the _DSN constant, but can be overriden in child classes.

• access: protected

the join statement, inserted between the FROM and the WHERE

• access: protected

a cache of the numRows*() functions

• access: protected

the offset and count

intialized in the constructor, used to create the LIMIT part of the SELECT.

• access: protected

the main SELECT result database handle

• access: protected

Main constructor

This constructor takes care of most of the initialization of the internal structures. It is how data is "loaded" from the storage, into the internal $_data array. A lookup into the database is made in function of the $match parameter.

Example usage:

 require_once('Storable.php');
 
 class Users extends Storable {}
 
 /* list all entries in the 'user' table */
 $u = new User();
 // option 1: current API
 while ($u->next()) {
   print $u->get('name') . '<br />';
 }
 // option 2: if next() was called in the constructor
 for ($u = new User("name LIKE '%oey%'"); $u->exists() ; $u->next()) {
   print "...";
 }

But the most interesting facette about this class is how you can use it to save data back to the storage:

 $u = new User(array('name' => 'joey'));
 
 if ($u->next()) {
   $u->set('name', 'joe');
 } else {
   print "not found, creating new";
 }
 $u->save();
 
 // You could also eventually do this, but Storable would then need
// to DESCRIBE the table and fetch the primary key values to be
 // able to save
 
 $u = new User("dfjfkldsjfs", null, null, null, "* JOIN `tablename` ON jkflkdsjlsd");
 $u = new User("dfjfkldsjfs", null, null, null, "name,desc");

Note: this constructor doesn't call next() anymore, so the proper way to loop over next() is with a while loop:

 $store = new Storable();
 while ($store->next()) {
   // do stuff
 }

While you also have to call next() to load a single object, in opposition with how ecdTable traditionnally worked, but much like how ecdIterator works:

 $store = new Storable(array('foo' => 'bar'));
 $store->next();
 $store->set('foo', 'quux');
 $store->save();

• see: http://dev.mysql.com/doc/mysql/en/SELECT.html
• see: Storable::next()

• mixed $match:

  Either:

  an associative array where key => value pairs correspond to columns => values. The key and value are equal'd and AND'd in a WHERE request.

  $match can also be a string, in which case it is taken verbatim as a WHERE. The programmer is then responsible of properly escaping the request. Also, this can create problems when the WHERE does not match anything and the programmer creates a row from the resulting object: Storable::save() will attempt an INSERT which might fail if the row already exists.

  Example:

   $user = new User(Array('firstname' => 'joe', 'lastname' => 'smith'));
  

  is equivalent to:

   $user = new User("`firstname` = 'joe' AND `lastname` = 'smith'");
  

• int $offset: the number of elements to skip before considering results. Equivalent to the offset parameter to LIMIT. Defaults to 0 (skip no element, start from the first).
• int $count: the number of elements to give. Equivalent to the row_count parameter to LIMIT. Defaults to -1 (everything).
• string $order: an arbitrary string appended after the LIMIT, usually a ORDER BY statement, but could be anything.
• string $select:

  the SELECT part, * by default. Be *really* careful with what you put here, as Storable relies on the result set to construct a WHERE clause for the INSERT or UPDATE queries, when the object is saved back in the storage.

  Example:

   // this will work
   $st = new Storable(null, null, null, null, "primarykey,anothercol");
   $st->next(); $st->save();
   
   // this is almost guarenteed to crash
   $st = new Storable(null, null, null, null, "notaprimarykey");
   $st->next(); // this works, though
   $st->save(); 
  

• string $join: the JOIN part, which is inserted between the FROM and the WHERE clauses. Is empty by default. Also be very careful with this as save() will attempt to save the columns from the joined table in the original table, which will cause queries to fail.

Take care of the DB magic to connect to the database

• usedby: Storable::start_request()
• usedby: Storable::save()
• usedby: Storable::next()
• uses: Storable::handle_result()
• access: protected

disconnect the database handle

• access: protected

Set the values of this object to the keys and values of the array.

• uses: array_merge()

• Array $hash: col -> value associative array
• Array $only_keys: import only those keys from the $hash array

• return: copy of the $_data array

The number of rows matchnig all predicates.

Note: this can be lower or equal (but not higher) than the requested count, if the number of rows matching the predicates is smaller the the requested count.

• return: number of records matching all predicates (WHERE, ORDER and LIMIT)
• usedby: Storable::num_rows_unlimited()
• see: Storable::count()
• see: Storable::num_rows_unlimited()
• uses: Storable::start_request()
• uses: DB::numRows()

The offset requested in the constructor.

• return: the current offset
• see: Storable::Storable()

Save the object in underlying storage.

If the object exists(), the request done will be an UPDATE, otherwise it will obviously be an INSERT. save() uses some magic from PEAR (autoExect()) to ease the construction of the request.

save() will not try to save an unmodified object (one that hasn't had set() called on it).

save() will happily try to save non-existant fields. It is the duty of the programmer to make sure the fields exist in the underlying storage.

The where_clause() is based on the original result set fetched from the database ($_data_orig pour les intimes), and totally ignores primary keys. This has the advantage of avoiding costly DESCRIBE statement in the constructor, but might create problems with JOINs or custom SELECT statements.

• return: whatever handle_result() will return
• uses: DB::autoExecute()
• uses: DB::quoteIdentifier()
• uses: Storable::handle_result()
• uses: Storable::connect()
• see: Storable::set()

• User::save() : override the parent save()
• StorableTree::save() : overload parent save function to make sure that the 'path' is

Assign the associative array directly to the internal structures.

• uses: Storable::backup_data()

• array $hash: an associative "column => value" array

What table represents this object. Currently returns the lowercased class name.

Can of course be overriden in child classes.

• return: the table name
• uses: get_class()

• OldProject::tablename()