<?php
/**
* Link tool for DB_DataObject
*
* PHP versions 5
*
* LICENSE: This source file is subject to version 3.01 of the PHP license
* that is available through the world-wide-web at the following URI:
* http://www.php.net/license/3_01.txt. If you did not receive a copy of
* the PHP License and are unable to obtain it through the web, please
* send a note to license@php.net so we can mail you a copy immediately.
*
* @category Database
* @package DB_DataObject
* @author Alan Knowles <alan@akbkhome.com>
* @copyright 1997-2006 The PHP Group
* @license http://www.php.net/license/3_01.txt PHP License 3.01
* @version : FIXME
* @link http://pear.php.net/package/DB_DataObject
*/
/**
*
* Example of how this could be used..
*
* The lind method are now in here.
*
* Currenly only supports existing methods, and new 'link()' method
*
*/
/**
* Links class
*
* @package DB_DataObject
*/
class DB_DataObject_Links
{
/**
* @property {DB_DataObject} do DataObject to apply this to.
*/
public $do = false;
/**
* @property {Array|String} load What to load, 'all' or an array of properties. (default all)
*/
public $load = 'all';
/**
* @property {String|Boolean} scanf use part of column name as resulting
* property name. (default false)
*/
public $scanf = false;
/**
* @property {String|Boolean} printf use column name as sprintf for resulting property name..
* (default %s_link if apply is true, otherwise it is %s)
*/
public $printf = false;
/**
* @property {Boolean} cached cache the result, so future queries will use cache rather
* than running the expensive sql query.
*/
public $cached = false;
/**
* @property {Boolean} apply apply the result to this object, (default true)
*/
public $apply = true;
//------------------------- RETURN ------------------------------------
/**
* @property {Array} links key value associative array of links.
*/
public $links;
/**
* Constructor
* -- good ole style..
* @param {DB_DataObject} do DataObject to apply to.
* @param array $cfg
*/
public function __construct($do, $cfg = array())
{
// check if do is set!!!?
$this->do = $do;
foreach ($cfg as $k => $v) {
$this->$k = $v;
}
}
/**
* a generic geter/setter provider..
*
* provides a generic getter setter for the referenced object
* eg.
* $link->link('company_id') returns getLink for the object
* if nothing is linked (it will return an empty dataObject)
* $link->link('company_id', array(1)) - just sets the
*
* also array as the field speck supports
* $link->link(array('company_id', 'company:id'))
*
*
* @param string|array $field the field to fetch or link spec.
* @param array $args
* @return mixed true of false on set, the object on getter.
* @params array $args the arguments sent to the getter setter
*/
public function link($field, $args = array())
{
$info = $this->linkInfo($field);
if (!$info) {
$this->do->raiseError(
"getLink:Could not find link for row $field",
DB_DATAOBJECT_ERROR_INVALIDCONFIG
);
return false;
}
$field = $info[2];
if (empty($args)) { // either an empty array or really empty....
if (!isset($this->do->$field)) {
return $info[0]; // empty dataobject.
}
$ret = $this->getLink($field);
// nothing linked -- return new object..
return ($ret === 0) ? $info[0] : $ret;
}
$assign = is_array($args) ? $args[0] : $args;
// otherwise it's a set call..
if (!is_a($assign, 'DB_DataObject')) {
if (is_numeric($assign) && is_integer($assign * 1)) {
if ($assign > 0) {
if (!$info) {
return false;
}
// check that record exists..
if (!$info[0]->get($info[1], $assign)) {
return false;
}
}
$this->do->$field = $assign;
return true;
}
return false;
}
// otherwise we are assigning it ...
$this->do->$field = $assign->{$info[1]};
return true;
}
/**
* get link information for a field or field specification
*
* alll link (and join methods accept the 'link' info ) in various ways
* string : 'field' = which field to get (uses ???.links.ini to work out what)
* array(2) : 'field', 'table:remote_col' << just like the links.ini def.
* array(3) : 'field', $dataobject, 'remote_col' (handy for joinAdd to do nested joins.)
*
* @param string|array $field or link spec to use.
* @return array|bool (false|array) array of dataobject and linked field or false.
*
*/
public function linkInfo($field)
{
if (is_array($field)) {
if (count($field) == 3) {
// array with 3 args:
// local_col , dataobject, remote_col
return array(
$field[1],
$field[2],
$field[0]
);
}
list($table, $link) = explode(':', $field[1]);
return array(
$this->do->factory($table),
$link,
$field[0]
);
}
// work out the link.. (classic way)
$links = $this->do->links();
if (empty($links) || !is_array($links)) {
return false;
}
if (!isset($links[$field])) {
return false;
}
list($table, $link) = explode(':', $links[$field]);
//??? needed???
if ($p = strpos($field, ".")) {
$field = substr($field, 0, $p);
}
return array(
$this->do->factory($table),
$link,
$field
);
}
/**
* return name from related object
*
* The relies on a <dbname>.links.ini file, unless you specify the arguments.
*
* you can also use $this->getLink('thisColumnName','otherTable','otherTableColumnName')
*
*
* @param string $field |array either row or row.xxxxx or links spec.
* @param bool $table (optional) name of table to look up value in
* @param string $link (optional) name of column in other table to match
* @return mixed object on success false on failure or '0' when not linked
* @author Tim White <tim@cyface.com>
* @access public
*/
public function getLink($field, $table = false, $link = '')
{
static $cache = array();
// GUESS THE LINKED TABLE.. (if found - recursevly call self)
if ($table == false) {
$info = $this->linkInfo($field);
if ($info) {
return $this->getLink($field, $info[0], $link === false ? $info[1] : $link);
}
// no links defined.. - use borked BC method...
// use the old _ method - this shouldnt happen if called via getLinks()
if (!($p = strpos($field, '_'))) {
return false;
}
$table = substr($field, 0, $p);
return $this->getLink($field, $table);
}
$tn = is_string($table) ? $table : $table->tableName();
if (!isset($this->do->$field)) {
$this->do->raiseError("getLink: row not set $field", DB_DATAOBJECT_ERROR_NODATA);
return false;
}
// check to see if we know anything about this table..
if (empty($this->do->$field) || $this->do->$field < 0) {
return 0; // no record.
}
if ($this->cached && isset($cache[$tn . ':' . $link . ':' . $this->do->$field])) {
return $cache[$tn . ':' . $link . ':' . $this->do->$field];
}
$obj = is_string($table) ? $this->do->factory($tn) : $table;;
if (!is_a($obj, 'DB_DataObject')) {
$this->do->raiseError(
"getLink:Could not find class for row $field, table $tn",
DB_DATAOBJECT_ERROR_INVALIDCONFIG
);
return false;
}
// -1 or 0 -- no referenced record..
$ret = false;
if ($link) {
if ($obj->get($link, $this->do->$field)) {
$ret = $obj;
}
// this really only happens when no link config is set (old BC stuff)
} elseif ($obj->get($this->do->$field)) {
$ret = $obj;
}
if ($this->cached) {
$cache[$tn . ':' . $link . ':' . $this->do->$field] = $ret;
}
return $ret;
}
/**
* 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
*
*
* @param string format (default _%s) where %s is the table name.
* @return boolean , true on success
* @author Tim White <tim@cyface.com>
* @access public
*/
public function applyLinks($format = '_%s')
{
// get table will load the options.
if ($this->do->_link_loaded) {
return true;
}
$this->do->_link_loaded = false;
$cols = $this->do->table();
$links = $this->do->links();
$loaded = array();
if ($links) {
foreach ($links as $key => $match) {
list($table, $link) = explode(':', $match);
$k = sprintf($format, str_replace('.', '_', $key));
// makes sure that '.' is the end of the key;
if ($p = strpos($key, '.')) {
$key = substr($key, 0, $p);
}
$this->do->$k = $this->getLink($key, $table, $link);
if (is_object($this->do->$k)) {
$loaded[] = $k;
}
}
$this->do->_link_loaded = $loaded;
return true;
}
// this is the autonaming stuff..
// it sends the column name down to getLink and lets that sort it out..
// if there is a links file then it is not used!
// IT IS DEPRECATED!!!! - DO NOT USE
if (!is_null($links)) {
return false;
}
foreach (array_keys($cols) as $key) {
if (!($p = strpos($key, '_'))) {
continue;
}
// does the table exist.
$k = sprintf($format, $key);
$this->do->$k = $this->getLink($key);
if (is_object($this->do->$k)) {
$loaded[] = $k;
}
}
$this->do->_link_loaded = $loaded;
return true;
}
/**
* 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.
*
* @access public
* @param string $field - either column or column.xxxxx
* @param string $table (optional) name of table to look up value in
* @param bool $fkey (optional) fetchall key see DB_DataObject::fetchAll()
* @param bool $fval (optional) fetchall method DB_DataObject::fetchAll()
* @param bool $fmethod
* @return array - array of results (empty array on failure)
*
* Example - Getting the related objects
*
* $person = new DataObjects_Person;
* $person->get(12);
* $children = $person->getLinkArray('children');
*
* echo 'There are ', count($children), ' descendant(s):<br />';
* foreach ($children as $child) {
* echo $child->name, '<br />';
* }
*/
public function getLinkArray($field, $table = null, $fkey = false, $fval = false, $fmethod = false)
{
$ret = array();
if (!$table) {
$links = $this->do->links();
if (is_array($links)) {
if (!isset($links[$field])) {
// failed..
return $ret;
}
list($table, $link) = explode(':', $links[$field]);
return $this->getLinkArray($field, $table);
}
if (!($p = strpos($field, '_'))) {
return $ret;
}
return $this->getLinkArray($field, substr($field, 0, $p));
}
$c = $this->do->factory($table);
if (!is_object($c) || !is_a($c, 'DB_DataObject')) {
$this->do->raiseError(
"getLinkArray:Could not find class for row $field, table $table",
DB_DATAOBJECT_ERROR_INVALIDCONFIG
);
return $ret;
}
// if the user defined method list exists - use it...
if (method_exists($c, 'listFind')) {
$c->listFind($this->id);
while ($c->fetch()) {
$ret[] = clone($c);
}
return $ret;
}
return $c->fetchAll($fkey, $fval, $fmethod);
}
}