DBDO - DB_DataObject as a C extension

Source :    http://cvs.php.net/pecl/dbdo/ or  http://devel.akbkhome.com/svn/index.php/dbdo/

What is it?

DataObjects was very successful, in design terms, it provided a simple, easy method to access and manipulate data from databases. The idea behind DBDO, the next generation of DataObjects, written in C, is to take advantage of

• libgda to provide complete backend support for all databases
• faster writing to properties on fetching.
  
• support for multiple databases, and sources
  
• simpler configuration
  
• full introspection
• (eventually full data validation and trimming)
• A Database designer??? maybe??
  

Status (Bold indicates mostly implemented)
Orange indicates todo

Bugs / TODO fixes:

• Serialize and unserialize hooks for dealing with session etc.
• Check effect of declaring privates for object vars.
  

Configuration / Connection

• __construct($dsn,$table)
  
• currently connects to the database, and loads schema
• Throws exceptions
  
• connect failure.
• ** we dont check that the table exists!!!
  
• ->schema([$col])
• returns a list of columns in the table or exact info about a column
• the big question, is should this be cached among objects?
  
• probably not! - caching should be only be done with the explicit cacheGet / cacheFind. commands..
• Cloning
  
• cloning works, it copies the holding object.
• Memory Management
• Refcounting results..DONE
  We need to refcount the results, so we know when it's no longer used and free it..
• General Freeing
  Need to look at freeing stuff more.
• Linked list freeing..
• ?? utilize g_new /g_free for  dbdo_object stuff, and efree /emalloc for dbdo_object.c stuff
• 
  
  
  
• DBDO::config($dsn,$key,$value) or DBDO::config($dsn,$array)  or $current = DBDO::config($dsn);
• Available config settings
  
• provider = Mysql|Pgsql|.....
• cnc = "USER=xxxx;PASS=yyy;DATABASE=test" (connection stuff)
  
• require_path = dirname(__FILE__)./DataObjects/%s.php    (NO DEFAULT)
  
• if require_path = an empty string (eg. "") - factory will not attempt to include anything. (you can use this to write your own loader...)
  
• class_name = DBDO_%s  (NO DEFAULT)
• if clase_name =  "DBDO" - factory will just return a DBDO object (eg. behaving like $x = new DBDO('dsn','table');)
  
• lowercase_columns = true|false           (portibility option)   needs using in lots of places
  
• links  =  dirname(__FILE__)/link1.php;link2.php;...... (location of links file)  needs using in links code
• quote_identifiers = true|false  (add `?? where is the standard for this?)    needs using in lots of places

Core Features

• DBDO::factory($dsn, $table)
• Includes (optionally) and instantates class based on name
• It is recommended to use this (even if with blank require_path and class_name) as it makes it easy to change your code later to use extended classes.
  
• see notes on require_path and class_name (which must be set for this to work.
• dsn = 'really a connection name'
• table = tablename
  
• ->get($value) ->get($key,$value)
  
• ->query([$query])
• No arguments autobuilds query. (previously find())
  
• returns number of rows found
• all conditions are honoured
• limit for anything other than MySQL/PostgresSQL throws error
• TODO: detect transaction calls (BEGIN|ROLLBACK|COMMIT)
• ->fetchAll([$mode])
• fetches all results as
  
• an array of objects (default or DBDO::OBJECTS)
  
• single object?? same as running fetch() on the current object and cloning it.. DBDO::CLONED?
  
• key value array (with arg DBDO::KEY_VALUE) (Nr x 2c)
  
• single array (with arg DBDO::VALUE) (Nr x 1c)
  
• single item (with arg DBDO::SINGLE) (1rx1c)
• array of arrays?? - classic behavior? DBDO::ARRAY
  
• ->fetch()
• same as dataobjects ?? should it allow you to fetch a specific row?
  
• ->count()
• do a select count(....) query
• ->insert() 
• assign next_insert_id to sequenceColumn
• deal with sequences (other than mysql autoincrement)
  
• assign database row data to properties on insert.
  
• ->update([DBDO::BUILD])
  
• DBDO::BUILD - based on where values, rather than sequence key / keys()..
• ->delete([DBDO::BUILD]) 
• without argument, deletes based on sequences (and in future keys())
• with argument - builds based on object variables.

• ->quoted($string)
• returns a quoted version of a string, eg with quotes and \'s infront of stuff this is supposed to.
  
• Recovery from sending sprintf formated items the wrong strings (eg. %d_xxx to setFrom())...
• Wiping of  ->condition after query (and checking whenever it's used.)
• Serialization for sessions/sleeping etc.

Query Modification

• ->selectAdd([$values]) 
• ->whereAdd([$values],[or|add]) ---- should the be just 'where' ?
• ->limit([$a],[$b])
• ->orderBy([$str]) 
• ->groupBy([$str])
  
• ->having([$str])
• memory management - condition struct should be read only after a results set is obtained.
  

Linking and Joining
A big question.. - should these be done PHPland side, other than join([$string]]), with the caveat that we allow configuration for it to use DBDO::config($dsn),
This is mostly due to the fact, that there is little benifit in doing it in C??? - ** will mock this up first to see feasibility **

• ->getLink()
• ->getLinks()
• ->selectAs() 
• ->joinAdd() 

Interaction Utils

• 
  
• ->assignFrom($object|$array, [$format]) was setFrom()
  
• calls setter if it exists
• works with objects and arrays
• formater works?
  TODO: call the equiviant to toValue()
  
• ->toArray([$format]) 
• coverts the results to an array (optionally formating the keys with  sprintf format (eg. test_%s)
• ->set*() and ->get*()
• does the same as valueSet/valueGet
  
• ->valueSet($columnName,$value)
• assign a Value throw an exception if it's invalid.
  
• ->valueGet($columnName)
• Designed for use when you implement private members...??
  

Information / set /get

• mixed $dbdo->info([string $what]) 
• Returns information about an object. (without arguments returns array with all of them.)
• $what can be:
• table
• dsn
• database
• cnc
• provider
• username
• password
• row
• rows
• fetched
• config
• sequence_column
• sequence_is_native
• sequence_assigned
• sequence_name
• where
• group_by
  
• order_by
• having
• limit_from
• limit_qty
  
• select
• .... more ??? ..
  
• ->sequenceKey($name,$isNative=false,$sequence_name)
• sets the column used for insert/update/delete!
• these are stored in a linked list of type struct dbdo_sequence
• returns the current sequence config, it does attempt to guess the value, unless you set it first.
• guessing only working based on autoincrement so far : need to do other types of databases
• ->keys($key1,$key2,key3) - designed to be used where multiple primary keys are used.
  
• used by
  
• update - if set
  
• will update fetched row based on the value of these, rather than the sequence Key
  
• delete
• will delete based on the value of these, rather than the sequence Key
• insert
• will insert based on the value of the key items. (no auto increment / sequence used???
• assignFrom
• will ignore these values if found.
  

• DBDO::debugLevel($level)
• turns debuging on  - which is emited as php Warnings (catch it with set_error_handler, and look for DBDO:(debug)
• 1 = ???
• 2 = ???
• ..
• 32 = Internal debugging (lots of crap)
  

Removed/Renamed Features

• ->find() now called query()
• ->setFrom() renamed to assignFrom()
  
• ->table() removed - use schema()
• ->keys() removed - use sequenceKey() or schema()
  
• ->getDatabaseConnection()  not needed, you never work with connections etc.
  
• ->getDatabaseResult()  not needed, you never work with results etc.
• DB_DataObject::raiseError() not required - we throw up now :)?
• ->validate() - removed valueGet() provides sufficient checking.. - other checking is up to the overloaded classes.
• ->free(), last object destructor should free up the data automatically.
  

Other ideas:

• cachedGet()
• cachedLinks()
  
• cachedLink()
  
• linkJoined (from the patch recieved for Dataobjects)
  

Not implemented and reasoning:

• StaticGet()
• This could easily be implemented in PHP land ?? or should it be added to factory?
  
•  all in one static factory/select
• This could easily be implemented in PHP land, it also has the downside of creating a method with lots of args to confuse people
• ->find(true)
• it may be implemented as queryFetch([$query]), but it's a 2 liner replacement?
  

Essential reading
Gnome-db documentation
CVS Source of libgda