DB_DataObject

An SQL Builder, Object Interface to Database Tables

DataObject performs 2 tasks: 1. Builds SQL statements based on the objects vars and the builder methods. 2. acts as a datastore for a table row. The core class is designed to be extended for each of your tables so that you put the data logic inside the data classes. included is a Generator to make your configuration files and your base classes. nd alan_k Alan Knowles alan@akbkhome.com lead 1.7.2 2004-08-28 PHP License stable Minor bug fix / Minor feature addition release Bug Fixes: #1835 - more fixes to ensure that joinAdd works correctly. #2106 - Update with old object having no changes does not raise an error #---- - fixed problem of call() code producing parse error on PHP5.0.1 #2205 - fixed case sensitivity of PHP5 call() #---- - fixed undefined index in delete after a fetch() Features Added: #2086 - Support for buliding dataobjects for Views (use option build_view=1) #2240 - factory() called on a dataobject returns a new instance of that object. DB Validate Date 1.7.1 2004-08-09 stable Minor bug fix release Bug Fixes: #2088 - class_prefix may be left out. #------ php4.2 compatibility should work as advertised in last realease #------ Generator didnt have DB loaded due to lazy load changes. 1.7.0 2004-06-03 stable Major bug fix release, Minor features added. Bug Fixes: #1559 - __FUNCTION__ remove, so dependancy on php 4.2 may still be valid. #1595 - regex include/exclude working correctly (Thanks to Stephane Gully) #1664 - configuration line links_{databasename} now available #1726 - enable orderby and limit can be used with delete() #1697 - prevent generator from adding an extra line created after definition. #1704 - update only adds null when the column is not marked 'not null' #1778 - toArray() returns a merge of defined table and actual results #1828 - Generator will die, if tableinfo is not supported. #1833 - links() now returns an empty array (no links) or null (no links.ini) so it can be used generically with : $ar = (array) $do->links(); #1835 - getLinks, getLink etc. now use ->links(), so you can define your own links() to return table links, rather than use links.ini files. #1923 - removed all @ silencers, and replace with empty/isset. #1935 - selectAs() - removed double quoteIdentifiers #2068 - workaround for DB bug, postgres nextval() being rawurlencoded #1980 - logic error when using quoteIdentifiers Changes: * DebugLevel(1) now displays native errors from database when queries fail. * Result Field names now stored seperately from Result Object * free() method added, to clean up memory instantly, if you are doing alot of queries. = Cleans Result Fields, Result Object, NumRows returned in Connection object. * include path is used to do file hunting if factory fails to find file. * DB is lazy loaded on connection.b 1.6.1 2004-06-03 stable Minor Bug Fix * fixed count() breaks when countWhat used. 1.6.0 2004-04-24 stable Minor Feature Release and many bug fixes.. * DB_DataObject_Error added to enable testing for dataobject errors * Date fixes - needs latest date package. * Generator fails with clear message if backend doesnt support tableInfo * added cidr, inet, macaddr for postgres * new options to filter generation of classes generator_include_regex = /foo_.*/i generator_exclude_regex = /tmp_.*/i * result column list is now stored for all queries (in the result object) so toArray() allways relates to the query. * php version correted in package file. * getLinks called before other database call fixed. * Updating without changing things, no longer raises a pear error, it just returns 0 (eg. no rows affected) * now Depends on 1.4 DB - escapeSimple is now used * extra option to disable assumtions to use pear db's nextID dont_use_pear_sequences = true * DebugLevel($val) if $val is not an integer - it is assumed to be a callback. * fixed clearing of data results after last fetch (reduces memory consumption when doing many queries) * strtolower any class name tests. * count accepts 1 or 2 arguments $countWhat or $whereAddonly, or $countWhat and $whereAddonly eg. $countWhat = "distinct id" eg. $countWhat = true (means $whereAdd = true) * selectAdd() returns existing value, so you can modify it. * most debugging & raiseError calls are dynamic, so you can overload them. * numbers allowed in tablenames. * ini filename uses database_{projectname} => {projectname}.ini so database names are portable, and multiple projects are theoretically feasible. * __clone is replaced with clone() for PHP5 compaitiblity. * use PEAR::getStaticProperty("DB","options") for oracle portablity settings. * null checked against not null spec. And probably a few more - as it's been quite a while since the last release.. 1.5.3 2004-01-29 stable Bug fix release. Changes: - fixed toValue() ** previously did not work correclty.. ** getXXX($format) correctly relays into toValue - see strftime / Data::format or sprintf for formats, depending on column type. Fixes * fix bug #630 - correct handling of YEAR (it's an int) * fix bug #630 - mysql timestamps are ingored for updated and insert (use query() if you want to change them manually. * fix bug #620 - limit accepts floats and doubles, as long as they are really integers.. 1.5.2 2004-01-24 stable Bug fix release. Changes: - removed automatic strtotime() in setters and setFrom ** this is closer to the previous behaviour (it caused too many problems with strange dates ** if you set a date/time column with a number, it assumes it is a unixtimestamp -- enables you to write setters like function setSome_Date($value) { $this->fromValue('some_date',strtotime($value)); } Fixes * $DB_DataObject->getDatabaseConnection() will return a pear error if dont_die is set, so it can be used to test connections. * note changed on databaseStructure, it can be called statically and dynamically. * fix bug #612 databaseStructure('databasename') will output the ini file structure array , with __keys * fix bug #611 corrected comment about NO_OVERLOAD * fix bug #603 to prevent clearing of queries after fetch, use the option keep_query_after_fetch = 1 * fix bug #359 (again) - _link_loaded array should only contain links that where sucessfully loaded 1.5.1 2004-01-22 stable Bug fix release. Fixes * fixed fromValue had problems with null and DataOBject_Cast objects * NOT NULL checking enabled in fromValue (eg. setters) * fix bug #605 - ability to specify sequence names option sequence_{tablename} = {column} // default {tablename}_seq option sequence_{tablename} = {column}:{sequence_name} * Dependancy on Date added. (it is used by the setter/getters) 1.5 2004-01-20 stable New Features / Fixes * proxy and auto schema building - you can use dataobjects wihout running create tables. - schema is created on the fly if no schema file exists - using config option proxy=full, a class is generated on the fly to represent the tables. * toValue and fromValue added as getter and setter providers - they include date formating tools - eg. $do->getBirthDay('%d/%m/%Y') will work with overload and PEAR::Date to provide formated dates. (works with date/time and datetime) - set*() will also call strtotime and PEAR::Date to try and read dates.\ setFrom will relay into fromValue() - hence auto fixing date entries * make native key recognision a little better - changes ini file format (key=N|K) - native or key. - BC protected... - ignores it when it finds a number.. (Fixes bug #532) * allow multiple updates on the same object - without adding lots of id=.... on the end.. * transactions support works transparently by sending $do->query('BEGIN'), $do->query('COMMIT'),$do->query('ROLLBACK') will automatically relay into the DB methods. * re-add support for sequence_{tablename} - prefered method is still overriding sequenceKey, and returning correct values. Bug Fixes * fix bug #595 - replace non letters in class names with underscore.. * fix bug #532 - better recoginsion of sequence keys * fix bug #528/#476 - typo fix (E_NOTICE error on $valu) * fix bug #473 - query can return a DB_Error * fix bug #501 - autoload/factory now uses full path (not require path) * fix bug #507 - sequences broken 1.4 2003-12-20 stable 1.3 2003-11-14 stable New Features - Inserts and updates do not use keys in the data creation part of the query (Markus Wolff) - MsSQL native get_last_insert ID using SELECT @@IDENTITY ** you may want to consider using this with transactions eg. $dataobject->query('BEGIN') and $dataobject->query('COMMIT') to ensure thread safety. (Markus Wolff) - DB_DataObject_Cast - a experimental generic casting feature for assigning variables * Common usages: // blobs $dataObject->someblobfield = DB_DataObject_Cast::blob(file_get_contents('xxx.jpg')); $dataObject->someblobfield = DB_DataObject_Cast::string('xxxxx'); // dates? $dataObject->at_date = DB_DataObject_Cast::date('12/12/2000'); //Human $dataObject->at_date = DB_DataObject_Cast::date('2000-12-12'); //ISO $dataObject->at_date = DB_DataObject_Cast::date(2000,12,12); //YYYY,dd,mm $d2 = DB_DataObject_Cast::date(); // today! // some addition $dataObject->expires = DB_DataObject_Cast::date($d1->year, $d1->month+30, $d1->day+30); // raw sql???? $dataObject->maxids = DB_DataObject_Cast::sql('max(id) > 12'); $dataObject->emptyfield = DB_DataObject_Cast::sql('NULL'); You can extend this object to provide your own datatypes.. - PHP5 Compatibility Return values should work with PHP5beta2 Overload (__call) should work with PHP5beta2 - table() and keys() Allow setting of data with a value (so you can use dataobjects without extended instances.) - factory/ getLinks and autoloading Will use the full path location in config to check if the file exists, after that it is included without warnings turned off.. (autoloading check to see if class exists first - should be faster) Fixes: - Validate is an optional dependency (Arnaud Limbourg) - Bug #228, BOOL type on postgresql correctly quoted. - Bug #133, No error is raised when calling fetch with no data returned, just produces a debug warning now - Bug #172,Turning of Overload If you define DB_DATAOBJECT_NO_OVERLOAD to any value, then dataobjects will not be overloaded, This is usefull when working with ZendOptimizer, that may segfault with certain optimization levels 1.2 2003-08-07 stable New Features: - A Number of the private methods have been made Public, changes: - _get_table() = table() - _get_keys() = keys() additions - tableName() = returns or assign the table name - database() = returns or assign the database name changes by Markus Wolff POSSIBLE BC IMPLICATIONS: If you define _get_table or _get_keys manually (rather than using the ini file) you should rename your methods table() and keys() Fixes: - Generator is now more tollerant of editors that alter the spaces before the autocode markers ### (Andreas Ljunggren) 1.1 2003-08-07 stable Bug Fixes - limit argument testing now accepts "10" (a string with an integer in it, as a valid argument) (Demian Turner) New Features - JoinAdd has additional Argument $joinCol, so you can specify multiple targets links of the same table, eg. user->friend, user->parent both connect to the user table.. (Andy Crain) 1.0.2 2003-07-31 stable Minor Bugfix Release - Fix static Get call, case sensitivity properly. 1.0.1 2003-07-18 stable Minor Bugfix Release - Fix Select defaults back to * after an fetch - Fix Update with NULL values 1.0 2003-07-16 stable - Gold 1.0 Release.. - final stable release in this series. Future versions (eg. 1.1.*(dev)->1.2.*(release)) series will be generally API compatible, however is likely to use MDB rather than DB. - fix bug #23983 - argument checking on whereAdd, orderBy, limit and a few others (Mike Carter) - fix bug with cache clearing not working with staticGet and update/insert - null comparison for $object->var = 'null' will generate IS NULL query - null insert/update works when using 'null' as a value. - getLinks returns true on success - getLinks now has a formatter eg. '_%s' is default to allow user to define the format of variables to assign child objects to. - generator uses UNIQUE only if no primary/autoincrement type field is found. - added support for $object->having('sum(value) > 10'); - fetch will remove some query lines (so if you want to see how the query was built you will have to print_r() the object after find(), and before fetch(), or just use debugLevel(1) - overload calls from setFrom and toArray do method checks, as overload is still proving to be a little unstable especially with Zend Encoder. (Note: if DataObjects causes crashes , remove the overload code at the bottom of DataObjects.php) 0.19 2003-05-22 stable - fix bug #23712 - deleting (and probably updating as well) an object while being fetched. (Michael McCarthy for spotting this) - fix generator overwriting code when file was edited in a Windows editor (Robert Janeczek) - validation will not produce errors on empty numeric data by default. - overload extension enabled to relay setFrom and toArray calls to get*, set* methods, which are predefined as getXXX = returns $object->XXX setXXX($V) = returns true (or an error string if you create your own) (only affects php-4.3.2RC2 or later..) - selectAs($dataobject,'prefix_%s') to help control the way join queries return their data * doing selectAs() - clears the select and sets it to table.id as id ... etc. - joinAdd has 2 extra optional arguments $dataObject->joinAdd($otherDataObject, $joinType, $joinAs) existing behaviour (INNER Joins) is default (eg. no value) $joinType can be: INNER,LEFT,RIGHT = eg. INNER JOIN ... etc. '' = just added with a , and the link conditions are added with a WHERE statement. $joinAs can be used to name the table differently in the join eg. SELECT .. FROM person INNER JOIN address as homeaddress ...... - setFrom has an extra optional parameter for formating: eg. $object->setFrom($_POST,'prefix_%s') would map prefix_name to $object->name the default is '%s' which is the same as the previous behaviour - added option dont_die (default no) to ini file default (no) means that DataObjects will emit a PEAR_ERROR_DIE on configuration and programming errors true or 1 means that you can write a PEAR::error handler to catch the errors and display a nice it's not working message 0.18 2003-05-17 stable - add table prefix to autobuilt queries (assist in ambigous querys for joins) (Daniel Von Fange) - change update and delete to return the number of rows affected or false on failure - various code tidy ups - standards etc. (Arnaud Limbourg) - fix generator for postgres and mdb - use unique keys and look for 'nextval' as keys. - fix no key insert bug (G Moxley Kempster) - fix empty table bug in generator (Robert Janeczek) - staticAutoloadTable(), now handles parse errors in included files alot cleaner - added dependancies on PHP4.3, DB 1.3 and Validate (although Validate is optional) - added table prefix to count query (Richard Wallace) 0.17 2003-03-12 stable - Usual post feature bug fix release - fix loading of links.ini for joinAdd, getLinks etc. (Geoff Hopson) 0.16 2003-03-06 stable - replaced config storage - should improve performance - removed production option (not required due to improved config storage) - bugfix : added checks for is_array on ignore_sequence_keys (Hermen Heinen) - add toArray($format) which supports sprintf to enable easy integration with Quickforms etc. (Demian Turner) - add optional dataobject as variable to update(), so you can update will only create an update based on what has changed. (Geoff Hopson) - add join condition to count() (Daniel Von Fange) - modify limit() to work with postgresql and make it emit a fatal error if you try this on databases that do not directly support limit queries. (Geoff Hopson) * I'm open on better ideas for this - probably wrapping the find() select call 0.15 2003-02-13 stable - modified find(true), so that it calls fetch rather than fetchrow so that overriding fetch will affect get() calls. (probably depreciates fetchrow now .. shout if anyone is using it) - added escape method as a quasi quote wrapper into pear::DB - useful for building your own queries - eg. like requests.. (does not add quotes) - fixed bug with delete not using primary key if it was set. (Ian Eure) 0.14 2003-02-06 stable - added get affected rows to update/insert/delete they will return false if no data is affected and set the Objects lastError value. Note: databases that do not support affectedRows(), will always return false. 0.13 2003-01-23 stable - bug fix release - debug_ignore_updates worked in reverse.. (Alexander Mazurov) 0.12 2003-01-22 stable - Usual post release bug fix. - fixes *.links.ini incorrectly using *.links (Damian Turner) - Adds the ability to get PEAR Connection and result objects getDatabaseConnection() and getDatabaseResult() (jason rust) 0.11 2003-01-21 stable - changed connecition and result caching to use global private variable, rather than getStaticProperty - results objects are not stored on insert/update/delete (speed increase on large inserts can be as much as 10x faster) - bug fix - Checks that primary keys are integers (Anthony Juou) - typo on No data returned warning - unit tests in CVS - new configuration option for whether to use insert id's and sequences. - Generator no creates boolean bit (mitchell perilstein) 0.10 2002-12-09 stable - bug fix - Generator incorrectly set _database, causing generation of database.ini files to fail - change addslashes to PEAR::DB::quote() - generator now only replaces DB_DataObjects with extends variable if set, you can use generator_rewrite_class to set what is a valid replacement. 0.9 2002-12-06 stable - bug fix release - dsn was not set correctly 0.8 2002-09-21 stable - changed to stable status as it appears to be pretty stable now. - update and insert now return FALSE on error conditions (Peter Gebauer) which can be checked using === FALSE, and the error obtained using $object->_lastError - delete will only use primary keys if they are set, otherwise it will use all object variables to build the condition. (Daniel Ferreira) - Added derivedHookFunctions(), and derivedHookVar() to enable extensions to generator to make user defined methods. (Michael Lund Rasmussen) - support for INT4, BPCHAR, TIMESTAMPTZ and postres Primary keys (Xavier) - better PEAR CS complience (tabs and TRUE -> true), removed short open tags in generator (Thomas Volkmar Worm) - experimental addJoin method (Stijn de Reede) - Allow active options array (eg. dynamic changing of database config) (Sergey Lipnevich) 0.6 2002-09-10 beta - bug fix release on insert (broke due to compatibility fixes) 0.5 2002-09-07 beta - fixed database.links.ini file loading in wrong location (Jens Fischer) - fixed type on extends (Jens Fischer) - added __clone() support to pre- php5 classes - added multiple linked table support 0.4 2002-08-21 beta - Bug fix release - createTables used wrong argv 0.3 2002-08-16 beta - Fixed Globals requirement in createTables, 0.2 2002-07-12 beta Removed list method, First upload as pear package. - Documentation now in PEAR Manual 0.1 2002-06-25 beta PEARified