autoJoin [line 3804]
array autoJoin(
[array
$cfg = array()])
|
|
autoJoin - using the links.ini file, it builds a query with all the joins
usage: $x = DB_DataObject::factory('mytable'); $x->autoJoin(); $x->get(123); will result in all of the joined data being added to the fetched object..
$x = DB_DataObject::factory('mytable'); $x->autoJoin(); $ar = $x->fetchAll(); will result in an array containing all the data from the table, and any joined tables..
$x = DB_DataObject::factory('mytable'); $jdata = $x->autoJoin(); $x->selectAdd(); //reset.. foreach($_REQUEST['requested_cols'] as $c) { if (!isset($jdata[$c])) continue; // ignore columns not available.. $x->selectAdd( $jdata[$c] . ' as ' . $c); } $ar = $x->fetchAll(); will result in only the columns requested being fetched...
Parameters:
count [line 1695]
int count(
[bool|string
$countWhat = false], [bool
$whereAddOnly = false])
|
|
Find the number of results from a simple query
for example
$object = new mytable(); $object->name = "fred"; echo $object->count(); echo $object->count(true); // dont use object vars. echo $object->count('distinct mycol'); count distinct mycol. echo $object->count('distinct mycol',true); // dont use object vars. echo $object->count('distinct'); // count distinct id (eg. the primary key)
Parameters:
database [line 2092]
string database(
string
0)
|
|
Return or assign the name of the current database
Parameters:
databaseStructure [line 1903]
true databaseStructure(
optional
0, optional
1, optional
2)
|
|
Autoload or manually load the table definitions
usage : DB_DataObject::databaseStructure( 'databasename', parse_ini_file('mydb.ini',true), parse_ini_file('mydb.link.ini',true));
obviously you dont have to use ini files.. (just return array similar to ini files..)
It should append to the table structure array
Parameters:
debug [line 4610]
none debug(
string
$message, [string
$logtype = 0], [string
$level = 1])
|
|
Debugger. - use this in your extended classes to output debugging information.
Uses DB_DataObject::DebugLevel(x) to turn it on
Parameters:
debugLevel [line 4649]
none debugLevel(
[int
$v = null])
|
|
sets and returns debug level eg. DB_DataObject::debugLevel(4);
Parameters:
delete [line 1535]
mixed delete(
[bool
$useWhere = false])
|
|
Deletes items from table which match current objects variables
Returns the true on success
for example
Designed to be extended
$object = new mytable(); $object->ID=123; echo $object->delete(); // builds a conditon
$object = new mytable(); $object->whereAdd('age > 12'); $object->limit(1); $object->orderBy('age DESC'); $object->delete(true); // dont use object vars, use the conditions, limit and order.
Parameters:
escape [line 1784]
string escape(
string
$string, [bool
$likeEscape = false])
|
|
an escape wrapper around DB->escapeSimple() can be used when adding manual queries or clauses eg.
$object->query("select * from xyz where abc like '". $object->escape($_GET['name']) . "'");
Parameters:
fetch [line 511]
fetches next row into this objects var's
returns 1 on success 0 on failure
Example $object = new mytable(); $object->name = "fred"; $object->find(); $store = array(); while ($object->fetch()) { echo $this->ID; $store[] = $object; // builds an array of object lines. }
to add features to a fetch function fetch () { $ret = parent::fetch(); $this->date_formated = date('dmY',$this->date); return $ret; }
fetchAll [line 641]
array fetchAll(
[string|false
$k = false], [string|false
$v = false], [string|false
$method = false])
|
|
fetches all results as an array,
return format is dependant on args. if selectAdd() has not been called on the object, then it will add the correct columns to the query.
A) Array of values (eg. a list of 'id')
$x = DB_DataObject::factory('mytable'); $x->whereAdd('something = 1') $ar = $x->fetchAll('id'); -- returns array(1,2,3,4,5)
B) Array of values (not from table)
$x = DB_DataObject::factory('mytable'); $x->whereAdd('something = 1'); $x->selectAdd(); $x->selectAdd('distinct(group_id) as group_id'); $ar = $x->fetchAll('group_id'); -- returns array(1,2,3,4,5) * C) A key=>value associative array
$x = DB_DataObject::factory('mytable'); $x->whereAdd('something = 1') $ar = $x->fetchAll('id','name'); -- returns array(1=>'fred',2=>'blogs',3=> .......
D) array of objects $x = DB_DataObject::factory('mytable'); $x->whereAdd('something = 1'); $ar = $x->fetchAll();
E) array of arrays (for example) $x = DB_DataObject::factory('mytable'); $x->whereAdd('something = 1'); $ar = $x->fetchAll(false,false,'toArray');
Parameters:
fetchRow [line 1617]
boolean fetchRow(
[int
$row = null])
|
|
fetches a specific row into this object variables
Not recommended - better to use fetch()
Returens true on success
Parameters:
find [line 396]
mixed find(
[boolean
$n = false])
|
|
find results, either normal or crosstable
for example
$object = new mytable(); $object->ID = 1; $object->find();
will set $object->N to number of rows, and expects next command to fetch rows will return $object->N
if an error occurs $object->N will be set to false and return value will also be false; if numRows is not supported it will
Parameters:
free [line 4746]
Free global arrays associated with this object.
fromValue [line 4425]
true| fromValue(
string
$col, mixed
$value)
|
|
standard set* implementation.
takes data and uses it to set dates/strings etc. normally called from __call..
Current supports date = using (standard time format, or unixtimestamp).... so you could create a method : function setLastread($string) { $this->fromValue('lastread',strtotime($string)); }
time = using strtotime datetime = using same as date - accepts iso standard or unixtimestamp. string = typecast only..
TODO: add formater:: eg. d/m/Y for date! ???
Parameters:
get [line 265]
int get(
[string
$k = null], [string
$v = null])
|
|
Get a result using key, value.
for example $object->get("ID",1234); Returns Number of rows located (usually 1) for success, and puts all the table columns into this classes variables
see the fetch example on how to extend this.
if no value is entered, it is assumed that $key is a value and get will then use the first key in keys() to obtain the key.
Parameters:
getDatabaseConnection [line 4276]
object The getDatabaseConnection(
)
|
|
Gets the DB object related to an object - so you can use funky peardb stuf with it :)
getDatabaseResult [line 4299]
object The getDatabaseResult(
)
|
|
Gets the DB result object related to the objects active query
- so you can use funky pear stuff with it - like pager for example.. :)
getLink [line 3232]
void getLink(
$row, [
$table = null], [
$link = false])
|
|
deprecited : @use link()
Parameters:
getLinkArray [line 3268]
array getLinkArray(
$row, [string
$table = null], string
$column)
|
|
getLinkArray Fetch an array of related objects. This should be used in conjunction with a <dbname>.links.ini file configuration (see the introduction on linking for details on this).
You may also use this with all parameters to specify, the column and related table. This is highly dependant on naming columns 'correctly' :) using colname = xxxxx_yyyyyy xxxxxx = related table; (yyyyy = user defined..) looks up table xxxxx, for value id=$this->xxxxx stores it in $this->_xxxxx_yyyyy
Parameters:
getLinks [line 3221]
boolean getLinks(
[string
$format = '_%s'])
|
|
load related objects
Generally not recommended to use this. The generator should support creating getter_setter methods which are better suited.
Relies on <dbname>.links.ini
Sets properties on the calling dataobject you can change what object vars the links are stored in by changeing the format parameter
Parameters:
groupBy [line 805]
none|PEAR::Error groupBy(
[string
$group = false])
|
|
Adds a group by condition
$object->groupBy(); //reset the grouping $object->groupBy("ID DESC"); $object->groupBy("ID,age");
Parameters:
having [line 840]
none|PEAR::Error having(
[string
$having = false])
|
|
Adds a having clause
$object->having(); //reset the grouping $object->having("sum(value) > 0 ");
Parameters:
insert [line 1056]
Insert the current objects variables into the database
Returns the ID of the inserted element (if auto increment or sequences are used.)
for example
Designed to be extended
$object = new mytable(); $object->name = "fred"; echo $object->insert();
joinAdd [line 3389]
none joinAdd(
[optional
$obj = false], [optional
$joinType = 'INNER'], [optional
$joinAs = false], [optional
$joinCol = false])
|
|
joinAdd - adds another dataobject to this, building a joined query.
example (requires links.ini to be set up correctly) // get all the images for product 24 $i = new DataObject_Image(); $pi = new DataObjects_Product_image(); $pi->product_id = 24; // set the product id to 24 $i->joinAdd($pi); // add the product_image connectoin $i->find(); while ($i->fetch()) { // do stuff } // an example with 2 joins // get all the images linked with products or productgroups $i = new DataObject_Image(); $pi = new DataObject_Product_image(); $pgi = new DataObject_Productgroup_image(); $i->joinAdd($pi); $i->joinAdd($pgi); $i->find(); while ($i->fetch()) { // do stuff }
Parameters:
keys [line 2157]
array keys(
string
0, *
1)
|
|
get/set an array of table primary keys
set usage: $do->keys('id','code');
This is defined in the table definition if it gets it wrong, or you do not want to use ini tables, you can override this.
Parameters:
limit [line 918]
none|PEAR::Error limit(
[string
$a = null], [string
$b = null])
|
|
Sets the Limit
$boject->limit(); // clear limit $object->limit(12); $object->limit(12,10);
Note this will emit an error on databases other than mysql/postgress as there is no 'clean way' to implement it. - you should consider refering to your database manual to decide how you want to implement it.
Parameters:
link [line 3196]
mixed link(
$field, [
$set_args = array()], mixed
$link_spec, mixed
$set_value)
|
|
generic getter/setter for links
This is the new 'recommended' way to get get/set linked objects. must be used with links.ini
usage: get: $obj = $do->link('company_id'); $obj = $do->link(array('local_col', 'linktable:linked_col'));
set: $do->link('company_id',0); $do->link('company_id',$obj); $do->link('company_id', array($obj));
example function
function company() { $this->link(array('company_id','company:id'), func_get_args()); }
Parameters:
links [line 3052]
array|null links(
array
$new_links)
|
|
Get the links associate array as defined by the links.ini file.
Experimental... - Should look a bit like [local_col_name] => "related_tablename:related_col_name"
Parameters:
orderBy [line 770]
none|PEAR::Error orderBy(
[string
$order = false])
|
|
Adds a order by condition
$object->orderBy(); //clears order by $object->orderBy("ID"); $object->orderBy("ID,age");
Parameters:
pid [line 306]
Get the value of the primary id
While I normally use 'id' as the PRIMARY KEY value, some database use {table}_id as the column name.
To save a bit of typing,
$id = $do->pid();
query [line 1767]
void query(
string
$string)
|
|
sends raw query to database
Since _query has to be a private 'non overwriteable method', this is a relay
Parameters:
raiseError [line 4684]
error raiseError(
int
$message, [int
$type = null], [int
$behaviour = null])
|
|
Default error handling is to create a pear error, but never return it.
if you need to handle errors you should look at setting the PEAR_Error callback this is due to the fact it would wreck havoc on the internal methods!
Parameters:
selectAdd [line 961]
mixed selectAdd(
[string
$k = null])
|
|
Adds a select columns
$object->selectAdd(); // resets select to nothing! $object->selectAdd("*"); // default select $object->selectAdd("unixtime(DATE) as udate"); $object->selectAdd("DATE");
to prepend distict: $object->selectAdd('distinct ' . $object->selectAdd());
Parameters:
selectAs [line 1001]
void selectAs(
[array|object|null
$from = null], [string
$format = '%s'], [string
$tableName = false])
|
|
Adds multiple Columns or objects to select with formating.
$object->selectAs(null); // adds "table.colnameA as colnameA,table.colnameB as colnameB,......" // note with null it will also clear the '*' default select $object->selectAs(array('a','b'),'%s_x'); // adds "a as a_x, b as b_x" $object->selectAs(array('a','b'),'ddd_%s','ccc'); // adds "ccc.a as ddd_a, ccc.b as ddd_b" $object->selectAdd($object,'prefix_%s'); // calls $object->get_table and adds it all as objectTableName.colnameA as prefix_colnameA
Parameters:
sequenceKey [line 2197]
array sequenceKey(
string
0, boolean
1, false|string
2)
|
|
get/set an sequence key
by default it returns the first key from keys() set usage: $do->sequenceKey('id',true);
override this to return array(false,false) if table has no real sequence key.
Parameters:
setFrom [line 4026]
true setFrom(
array
$from, [string
$format = '%s'], [boolean
$skipEmpty = false])
|
|
Copies items that are in the table definitions from an array or object into the current object will not override key values.
Parameters:
sqlValue [line 4001]
void sqlValue(
string
$value, string
$callvalue)
|
|
Factory method for calling DB_DataObject_Cast
if used with 1 argument DB_DataObject_Cast::sql($value) is called
if used with 2 arguments DB_DataObject_Cast::$value($callvalue) is called valid first arguments are: blob, string, date, sql
eg. $member->updated = $member->sqlValue('NOW()');
might handle more arguments for escaping later...
Parameters:
staticGet [line 4831]
void staticGet(
$class,
$k, [
$v = null])
|
|
(deprecated - use ::get / and your own caching method)
Parameters:
table [line 2111]
get/set an associative array of table columns
Parameters:
tableName [line 2069]
string tableName(
string
0)
|
|
Return or assign the name of the current table
Parameters:
toArray [line 4125]
array toArray(
[string
$format = '%s'], [bool||number
$hideEmpty = false])
|
|
Returns an associative array from the current data (kind of oblivates the idea behind DataObjects, but is usefull if you use it with things like QuickForms.
you can use the format to return things like user[key] by sending it $object->toArray('user[%s]')
will also return links converted to arrays.
Parameters:
toValue [line 4528]
true toValue(
string
$col, [format
$format = null])
|
|
standard get* implementation.
with formaters.. supported formaters: date/time : %d/%m/%Y (eg. php strftime) or pear::Date numbers : %02d (eg. sprintf) NOTE you will get unexpected results with times like 0000-00-00 !!!
Parameters:
unionAdd [line 3303]
$obj unionAdd(
$obj
$obj, [optional
$is_all = ''])
|
|
unionAdd - adds another dataobject to this, building a unioned query.
usage: $doTable1 = DB_DataObject::factory("table1"); $doTable2 = DB_DataObject::factory("table2");
$doTable1->selectAdd(); $doTable1->selectAdd("col1,col2"); $doTable1->whereAdd("col1 > 100"); $doTable1->orderBy("col1");
$doTable2->selectAdd(); $doTable2->selectAdd("col1, col2"); $doTable2->whereAdd("col2 = 'v'");
$doTable1->unionAdd($doTable2); $doTable1->find();
Note: this model may be a better way to implement joinAdd?, eg. do the building in find?
Parameters:
update [line 1331]
int update(
[object dataobject
$dataObject = false])
|
|
Updates current objects variables into the database uses the keys() to decide how to update Returns the true on success
for example
$object = DB_DataObject::factory('mytable'); $object->get("ID",234); $object->email="testing@test.com"; if(!$object->update()) echo "UPDATE FAILED";
to only update changed items : $dataobject->get(132); $original = $dataobject; // clone/copy it.. $dataobject->setFrom($_POST); if ($dataobject->validate()) { $dataobject->update($original); } // otherwise an error...
performing global updates: $object = DB_DataObject::factory('mytable'); $object->status = "dead"; $object->whereAdd('age > 150'); $object->update(DB_DATAOBJECT_WHEREADD_ONLY);
Parameters:
useIndex [line 878]
none|PEAR::Error useIndex(
[string|array
$index = false])
|
|
Adds a using Index
$object->useIndex(); //reset the use Index $object->useIndex("some_index");
Note do not put unfiltered user input into theis method. This is mysql specific at present? - might need altering to support other databases.
Parameters:
validate [line 4193]
validate the values of the object (usually prior to inserting/updating..)
Note: This was always intended as a simple validation routine. It lacks understanding of field length, whether you are inserting or updating (and hence null key values)
This should be moved to another class: DB_DataObject_Validate FEEL FREE TO SEND ME YOUR VERSION FOR CONSIDERATION!!!
Usage: if (is_array($ret = $obj->validate())) { ... there are problems with the data ... }
Logic:
- defaults to only testing strings/numbers if numbers or strings are the correct type and null values are correct
- validate Column methods : "validate{ROWNAME}()" are called if they are defined.
These methods should return
true = everything ok
false|object = something is wrong!
- This method loads and uses the PEAR Validate Class.
whereAdd [line 685]
string|PEAR::Error whereAdd(
[string
$cond = false], [string
$logic = 'AND'])
|
|
Adds a condition to the WHERE statement, defaults to AND
$object->whereAdd(); //reset or cleaer ewhwer $object->whereAdd("ID > 20"); $object->whereAdd("age > 20","OR");
Parameters:
whereAddIn [line 731]
string|PEAR::Error whereAddIn(
string
$key, array
$list, string
$type, [string
$logic = 'AND'])
|
|
Adds a 'IN' condition to the WHERE statement
$object->whereAddIn('id', $array, 'int'); //minimal usage $object->whereAddIn('price', $array, 'float', 'OR'); // cast to float, and call whereAdd with 'OR' $object->whereAddIn('name', $array, 'string'); // quote strings
Parameters:
_call [line 4334]
true? _call(
$method,
$params,
&$return)
|
|
Overload Extension support
- enables setCOLNAME/getCOLNAME
if you define a set/get method for the item it will be called.
otherwise it will just return/set the value. NOTE this currently means that a few Names are NO-NO's eg. links,link,linksarray, from, Databaseconnection,databaseresult
note
- get is automatically called by toArray()
setters return true on success. = strings on failure getters return the value!
this fires off trigger_error - if any problems.. pear_error, has problems with 4.3.2RC2 here
Parameters:
_loadConfig [line 4731]
Define the global $_DB_DATAOBJECT['CONFIG'] as an alias to PEAR::getStaticProperty('DB_DataObject','options');
After Profiling DB_DataObject, I discoved that the debug calls where taking considerable time (well 0.1 ms), so this should stop those calls happening. as all calls to debug are wrapped with direct variable queries rather than actually calling the funciton THIS STILL NEEDS FURTHER INVESTIGATION