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

DBDO