Docs For Class xPDO

Class xPDO

Class Overview

A wrapper for PDO that powers an object-relational data model.

xPDO provides centralized data access via a simple object-oriented API, to and defined data structure. It provides the de facto methods for connecting to a data source, getting persistence metadata for any class extended from the xPDOObject class (core or custom), loading data source managers when needed to manage table structures, and retrieving instances (or rows) of any object in the model.

Through various extensions, you can also reverse and forward engineer classes and metadata maps for XPDO, have classes, models, and properties maintain their own containers (databases, tables, columns, etc.) or changes to them, and much more.

Located in /xpdo.class.php [line 210]

[ Top ]

Property Summary

xPDOCacheManager	$cacheManager
string	$cachePath
array	$config	A array of xPDO configuration attributes.
int	$executedQueries
integer	$logLevel
string	$logTarget
xPDOManager	$manager	xPDOManager instance, loaded only if needed to manage datasource containers, data structures, etc.
array	$map	A map of data source meta data for all loaded classes.
string	$package	A default package for specifying classes by name.
mixed	$packages	An array storing packages and package-specific information.
PDO	$pdo	A PDO instance used by xPDO for database access.
int	$queryTime
float	$startTime
mixed	$_cacheEnabled
mixed	$_debug
mixed	$_escapeChar
mixed	$_nativeMode

[ Top ]

Method Summary

xPDO	__construct()
xPDO	xPDO()	The xPDO Constructor.
void	beginTransaction()
void	commit()
void	connect()
void	errorCode()
void	errorInfo()
void	exec()
void	fromCache()
void	fromJSON()
array	getAggregates()	Gets a collection of aggregate foreign key relationship definitions.
array	getAncestry()	Retrieves the complete ancestry for a class.
void	getAttribute()
object The	getCacheManager()	Gets the xPDOCacheManager instance.
string	getCachePath()	Gets the absolute path to the cache directory.
array\|null	getCollection()	Retrieves a collection of xPDOObjects by the specified xPDOCriteria.
void	getCollectionGraph()	Retrieves a collection of xPDOObject instances with related objects.
array	getComposites()	Gets a collection of composite foreign key relationship definitions.
void	getCount()	Retrieves a count of xPDOObjects by the specified xPDOCriteria.
xPDOCriteria	getCriteria()	Gets criteria pre-defined in an xPDOObject class metadata definition.
boolean	getDebug()	Returns the debug state for the XPDO connection.
array	getFieldMeta()	Gets a list of field (or column) definitions for an object by class name.
array	getFields()	Gets a list of fields (or columns) for an object by class name.
void	getFKDefinition()
object\|null	getManager()	Gets the manager class for this XPDO connection.
void	getMicroTime()
object\|null	getObject()	Retrieves a single object instance by the specified criteria.
void	getObjectGraph()	Retrieves an xPDOObject instance with specified related objects.
mixed	getPK()	Gets the primary key field(s) for a class.
string	getPKType()	Gets the type of primary key field for a class.
string	getSelectColumns()	Gets select columns from a specific class for building a query.
string	getTableMeta()	Gets the actual run-time table metadata from a specified class name.
string	getTableName()	Gets the actual run-time table name from a specified class name.
void	lastInsertId()
string\|boolean	loadClass()	Load a class by fully qualified name.
object\|null	newObject()	Creates a new instance of a specified class.
void	newQuery()
array	parseDSN()	Parses a DSN and returns an array of the connection details.
void	prepare()
void	query()
void	quote()
void	rollBack()
void	setAttribute()
void	setDebug()	Sets the debug state for the XPDO connection.
void	setLogLevel()	Sets the logging level state for the XPDO instance.
void	setLogTarget()
void	setPackage()	Sets a specific model package to use when looking up classes.
void	toCache()
void	toJSON()
string	_getFullTableName()	Adds the table prefix, and optionally database name, to a given table.
string	_getLogLevel()	Gets a logging level as a string representation.
void	_log()	Log a message as appropriate for the level and target.

[ Top ]

Properties

xPDOCacheManager $cacheManager = null [line 250]

[ Top ]

string $cachePath = null [line 254]

[ Top ]

array $config = null [line 222]

A array of xPDO configuration attributes.

API Tags:

Access:

public

[ Top ]

int $executedQueries = 0 [line 263]

[ Top ]

integer $logLevel = XPDO_LOG_LEVEL_FATAL [line 272]

[ Top ]

string $logTarget = 'ECHO' [line 277]

[ Top ]

xPDOManager $manager = null [line 245]

xPDOManager instance, loaded only if needed to manage datasource containers, data structures, etc.

API Tags:

Access:

public

[ Top ]

array $map = array () [line 228]

A map of data source meta data for all loaded classes.

API Tags:

Access:

public

[ Top ]

string $package = '' [line 234]

A default package for specifying classes by name.

API Tags:

Access:

public

[ Top ]

mixed $packages = array () [line 238]

An array storing packages and package-specific information.

[ Top ]

PDO $pdo = null [line 216]

A PDO instance used by xPDO for database access.

API Tags:

Access:

public

[ Top ]

int $queryTime = 0 [line 267]

[ Top ]

float $startTime = 0 [line 259]

[ Top ]

mixed $_cacheEnabled = false [line 281]

[ Top ]

mixed $_debug = false [line 279]

[ Top ]

mixed $_escapeChar = '' [line 282]

[ Top ]

mixed $_nativeMode = true [line 280]

[ Top ]

Methods

Constructor __construct [line 301]

xPDO __construct(

$dsn, [
$username = ''], [
$password = ''], [
$tablePrefix = ''], [
$driverOptions = null] 
)

Parameters:

	$dsn:
	$username:
	$password:
	$tablePrefix:
	$driverOptions:

[ Top ]

Constructor xPDO [line 298]

xPDO xPDO(
mixed
$dsn, [string
$username = ''], [string
$password = ''], [string
$tablePrefix = ''], [mixed
$driverOptions = null] 
)

The xPDO Constructor.

This method is used to create a new xPDO object with a connection to a specific database container.

Parameters:

mixed	$dsn:	A valid DSN connection string.
string	$username:	The database username with proper permissions.
string	$password:	The password for the database user.
string	$tablePrefix:	A prefix applied to all database container names, to isolate multiple installations or conflicting table names that might need to coexist in a single database container.
mixed	$driverOptions:	Driver-specific PDO options.

[ Top ]

beginTransaction [line 1198]

void beginTransaction(
)

API Tags:

See:

http://php.net/manual/en/function.pdo-begintransaction.php

[ Top ]

commit [line 1208]

void commit(
)

API Tags:

See:

http://php.net/manual/en/function.pdo-commit.php

[ Top ]

connect [line 325]

void connect(
[
$driverOptions = array ()] 
)

Parameters:

$driverOptions:

[ Top ]

errorCode [line 1234]

void errorCode(
)

API Tags:

See:

http://php.net/manual/en/function.pdo-errorcode.php

[ Top ]

errorInfo [line 1244]

void errorInfo(
)

API Tags:

See:

http://php.net/manual/en/function.pdo-errorinfo.php

[ Top ]

exec [line 1218]

void exec(

$query 
)

Parameters:

$query:

API Tags:

See:

http://php.net/manual/en/function.pdo-exec.php

[ Top ]

fromCache [line 1100]

void fromCache(

$signature, [
$class = ''], [
$format = 'php'] 
)

Parameters:

	$signature:
	$class:
	$format:

[ Top ]

fromJSON [line 1176]

void fromJSON(

$src, [
$asArray = true] 
)

Parameters:

	$src:
	$asArray:

[ Top ]

getAggregates [line 796]

array getAggregates(
string
$className 
)

Gets a collection of aggregate foreign key relationship definitions.

Parameters:

string

$className:

The fully-qualified name of the class.

API Tags:

Return:

An array of aggregate foreign key relationship definitions.

[ Top ]

getAncestry [line 839]

array getAncestry(
string
$className, [boolean
$includeSelf = true] 
)

Retrieves the complete ancestry for a class.

Parameters:

string	$className:	className The name of the class.
boolean	$includeSelf:	includeSelf Determines if the specified class should be included in the resulting array.

API Tags:

Return:

An array of string class names representing the class hierarchy, or an empty array if unsuccessful.

[ Top ]

getAttribute [line 1254]

void getAttribute(

$attribute 
)

Parameters:

$attribute:

API Tags:

See:

http://php.net/manual/en/function.pdo-getattribute.php

[ Top ]

getCacheManager [line 943]

object The getCacheManager(
[string
$class = 'cache.xPDOCacheManager'], [string
$path = XPDO_CORE_PATH] 
)

Gets the xPDOCacheManager instance.

This class is responsible for handling all types of caching operations for the xPDO core.

Parameters:

string	$class:	Optional name of a derivative xPDOCacheManager class.
string	$path:	Optional root path for looking up the $class.

API Tags:

Return:

xPDOCacheManager for this xPDO instance.

[ Top ]

getCachePath [line 923]

string getCachePath(
)

Gets the absolute path to the cache directory.

API Tags:

Return:

The full cache directory path.

[ Top ]

getCollection [line 510]

array|null getCollection(
string
$className, [object|array|string
$criteria = null], [mixed
$cacheFlag = false] 
)

Retrieves a collection of xPDOObjects by the specified xPDOCriteria.

Parameters:

string	$className:	Name of the class to search for instances of.
object\|array\|string	$criteria:	An xPDOCriteria object or an array search expression.
mixed	$cacheFlag:	If an integer value is provided, this specifies the time to live in the result set cache; if cacheFlag === false, caching is ignored for the collection and if cacheFlag === true, the objects will live in cache until flushed by another process.

API Tags:

Return:

An array of class instances retrieved.

[ Top ]

getCollectionGraph [line 568]

void getCollectionGraph(
string
$className, string|array
$graph, [mixed
$criteria = null], [boolean
$cacheFlag = false] 
)

Retrieves a collection of xPDOObject instances with related objects.

Parameters:

string	$className:	The name of the class to return a collection of.
string\|array	$graph:	A related object graph in array or JSON format, e.g. array('ClassName'=>array('relationKey'=>array())) or '{"ClassName":{"relationKey":{}}}'
mixed	$criteria:	A valid xPDOCriteria instance or condition string.
boolean	$cacheFlag:	Indicates if the result set should be cached.

[ Top ]

getComposites [line 816]

array getComposites(
string
$className 
)

Gets a collection of composite foreign key relationship definitions.

Parameters:

string

$className:

The fully-qualified name of the class.

API Tags:

Return:

An array of composite foreign key relationship definitions.

[ Top ]

getCount [line 522]

void getCount(
string
$className, [mixed
$criteria = null] 
)

Retrieves a count of xPDOObjects by the specified xPDOCriteria.

Parameters:

string	$className:	Class of xPDOObject to count instances of.
mixed	$criteria:	Any valid xPDOCriteria object or expression.

[ Top ]

getCriteria [line 595]

xPDOCriteria getCriteria(
string
$className, [string
$type = null], [
$cacheFlag = true] 
)

Gets criteria pre-defined in an xPDOObject class metadata definition.

Parameters:

string	$className:	The class to get predefined criteria for.
string	$type:	The type of criteria to get (you can define any type you want, but 'object' and 'collection' are the typical criteria for retrieving single and multiple instances of an object).
	$cacheFlag:

API Tags:

Return:

A criteria object or null if not found.

Information Tags:

Todo:	Define callback functions as an alternative to retreiving criteria sql and/or bindings from the metadata.
Todo:	Move quotable operators to the db specific xPDOObject implementation.

[ Top ]

getDebug [line 960]

boolean getDebug(
)

Returns the debug state for the XPDO connection.

API Tags:

Return:

The current debug state for the connection, true for on, false for off.

[ Top ]

getFieldMeta [line 700]

array getFieldMeta(
string
$className 
)

Gets a list of field (or column) definitions for an object by class name.

These definitions are used by the objects themselves to build their own meta data based on class inheritence.

Parameters:

string

$className:

The name of the class to lookup fields meta data for.

API Tags:

Return:

An array featuring field names as the array keys, and arrays of metadata information as the array values; empty array is returned if unsuccessful.

[ Top ]

getFields [line 674]

array getFields(
string
$className 
)

Gets a list of fields (or columns) for an object by class name.

This includes default values for each field and is used by the objects themselves to build their initial attributes based on class inheritence.

Parameters:

string

$className:

The name of the class to lookup fields for.

API Tags:

Return:

An array featuring field names as the array keys, and default field values as the array values; empty array is returned if unsuccessful.

[ Top ]

getFKDefinition [line 871]

void getFKDefinition(

$parentClass, 
$alias 
)

Parameters:

	$parentClass:
	$alias:

[ Top ]

getManager [line 905]

object|null getManager(
)

Gets the manager class for this XPDO connection.

The manager class can perform operations such as creating or altering table structures, creating data containers, generating custom persistence classes, and other advanced operations that do not need to be loaded frequently.

API Tags:

Return:

A manager instance for the XPDO connection, or null if a manager class can not be instantiated.

[ Top ]

getMicroTime [line 1327]

void getMicroTime(
)

[ Top ]

getObject [line 490]

object|null getObject(
string
$className, [mixed
$criteria = null], [mixed
$cacheFlag = false] 
)

Retrieves a single object instance by the specified criteria.

The criteria can be a primary key value, and array of primary key values (for multiple primary key objects) or an xPDOCriteria object. If no $criteria parameter is specified, no class is found, or an object cannot be located by the supplied criteria, null is returned.

Parameters:

string	$className:	Name of the class to get an instance of.
mixed	$criteria:	Primary key of the record or a xPDOCriteria object.
mixed	$cacheFlag:	If an integer value is provided, this specifies the time to live in the object cache; if cacheFlag === false, caching is ignored for the object and if cacheFlag === true, the object will live in cache indefinitely.

API Tags:

Return:

An instance of the class, or null if it could not be instantiated.

[ Top ]

getObjectGraph [line 547]

void getObjectGraph(
string
$className, string|array
$graph, [mixed
$criteria = null], [boolean
$cacheFlag = false] 
)

Retrieves an xPDOObject instance with specified related objects.

Parameters:

string	$className:	The name of the class to return an instance of.
string\|array	$graph:	A related object graph in array or JSON format, e.g. array('ClassName'=>array('relationKey'=>array())) or {ClassName:{relationKey:{}}}
mixed	$criteria:	A valid xPDOCriteria instance or condition string.
boolean	$cacheFlag:	Indicates if the result set should be cached.

[ Top ]

getPK [line 723]

mixed getPK(
string
$className 
)

Gets the primary key field(s) for a class.

Parameters:

string

$className:

The name of the class to lookup the primary key for.

API Tags:

Return:

The name of the field representing a class instance primary key, an array of key names for compound primary keys, or null if no primary key is found or defined for the class.

[ Top ]

getPKType [line 767]

string getPKType(
string
$className, [
$pk = false] 
)

Gets the type of primary key field for a class.

Parameters:

string	$className:	className The name of the class to lookup the primary key type for.
	$pk:

API Tags:

Return:

The type of the field representing a class instance primary key, or null if no primary key is found or defined for the class.

Information Tags:

Todo:

Refactor method to return array of types rather than compound!

[ Top ]

getSelectColumns [line 867]

string getSelectColumns(
string
$className, [string
$tableAlias = ''], [string
$columnPrefix = ''], [array
$columns = array ()], [boolean
$exclude = false] 
)

Gets select columns from a specific class for building a query.

Parameters:

string	$className:	The name of the class to build the column list from.
string	$tableAlias:	An optional alias for the class table, to be used in complex queries with multiple tables.
string	$columnPrefix:	An optional string with which to prefix the columns returned, to avoid name collisions in return columns.
array	$columns:	An optional array of columns to include.
boolean	$exclude:	If true, will exclude columns in the previous parameter, instead of including them.

API Tags:

Return:

A valid SQL string of column names for a SELECT statement.

[ Top ]

getTableMeta [line 644]

string getTableMeta(
string
$className 
)

Gets the actual run-time table metadata from a specified class name.

Parameters:

string

$className:

The name of the class to lookup a table name for.

API Tags:

Return:

The table meta data for the class, or null if unsuccessful.

[ Top ]

getTableName [line 613]

string getTableName(
string
$className, [boolean
$includeDb = false] 
)

Gets the actual run-time table name from a specified class name.

Parameters:

string	$className:	The name of the class to lookup a table name for.
boolean	$includeDb:	Qualify the table name with the database name.

API Tags:

Return:

The table name for the class, or null if unsuccessful.

[ Top ]

lastInsertId [line 1264]

void lastInsertId(
)

API Tags:

See:

http://php.net/manual/en/function.pdo-lastinsertid.php

[ Top ]

loadClass [line 382]

string|boolean loadClass(
string
$fqn, [
$path = ''], [
$ignorePkg = false], [
$transient = false] 
)

Load a class by fully qualified name.

The $fqn should in the format:

dir_a.dir_b.dir_c.classname

which will translate to:

XPDO_CORE_PATH/om/dir_a/dir_b/dir_c/dbtype/classname.class.php

Parameters:

string	$fqn:	The fully-qualified name of the class to load.
	$path:
	$ignorePkg:
	$transient:

API Tags:

Return:

The actual classname if successful, or false if not.

[ Top ]

newObject [line 460]

object|null newObject(
string
$className, [array
$fields = array ()] 
)

Creates a new instance of a specified class.

All new objects created with this method are transient until saved for the first time.

Parameters:

string	$className:	Name of the class to get a new instance of.
array	$fields:	An associated array of field names/values to populate the object with.

API Tags:

Return:

A new instance of the specified class, or null if a new object could not be instantiated.

[ Top ]

newQuery [line 1332]

void newQuery(

$class, [
$criteria = null], [
$cacheFlag = true] 
)

Parameters:

	$class:
	$criteria:
	$cacheFlag:

[ Top ]

parseDSN [line 1084]

array parseDSN(
string
$string 
)

Parses a DSN and returns an array of the connection details.

Parameters:

string

$string:

The DSN to parse.

API Tags:

Return:

An array of connection details from the DSN.

Information Tags:

Todo:

Have this method handle all methods of DSN specification as handled by latest native PDO implementation.

[ Top ]

prepare [line 1274]

void prepare(

$statement, [
$driver_options = array ()] 
)

Parameters:

	$statement:
	$driver_options:

API Tags:

See:

http://php.net/manual/en/function.pdo-prepare.php

[ Top ]

query [line 1284]

void query(

$query 
)

Parameters:

$query:

API Tags:

See:

http://php.net/manual/en/function.pdo-query.php

[ Top ]

quote [line 1300]

void quote(

$string, [
$parameter_type = PDO_PARAM_STR] 
)

Parameters:

	$string:
	$parameter_type:

API Tags:

See:

http://php.net/manual/en/function.pdo-quote.php

[ Top ]

rollBack [line 1310]

void rollBack(
)

API Tags:

See:

http://php.net/manual/en/function.pdo-rollback.php

[ Top ]

setAttribute [line 1320]

void setAttribute(

$attribute, 
$value 
)

Parameters:

	$attribute:
	$value:

API Tags:

See:

http://php.net/manual/en/function.pdo-setattribute.php

[ Top ]

setDebug [line 969]

void setDebug(
[boolean
$v = true] 
)

Sets the debug state for the XPDO connection.

Parameters:

boolean

$v:

The debug status, true for on, false for off.

[ Top ]

setLogLevel [line 978]

void setLogLevel(
[integer
$level = XPDO_LOG_LEVEL_FATAL] 
)

Sets the logging level state for the XPDO instance.

Parameters:

integer

$level:

The logging level to switch to.

[ Top ]

setLogTarget [line 982]

void setLogTarget(
[
$target = 'ECHO'] 
)

Parameters:

$target:

[ Top ]

setPackage [line 360]

void setPackage(
[string
$pkg = ''], [string
$path = ''] 
)

Sets a specific model package to use when looking up classes.

This package is of the form package.subpackage.subsubpackage and will be added to the beginning of every XPDO class that is referenced in XPDO methods such as loadClass(), getObject(), getCollection(), getOne(), addOne(), etc.

Parameters:

string	$pkg:	A package name to use when looking up classes in XPDO.
string	$path:	The root path for looking up classes in this package.

[ Top ]

toCache [line 1129]

void toCache(

$signature, 
$object, [
$lifetime = 0], [
$compressed = false] 
)

Parameters:

	$signature:
	$object:
	$lifetime:
	$compressed:

[ Top ]

toJSON [line 1161]

void toJSON(

$array 
)

Parameters:

$array:

[ Top ]

_getFullTableName [line 1065]

string _getFullTableName(
string
$baseTableName, [boolean
$includeDb = false] 
)

Adds the table prefix, and optionally database name, to a given table.

Parameters:

string	$baseTableName:	The table name as specified in the object model.
boolean	$includeDb:	Qualify the table name with the database name.

API Tags:

Return:

The fully-qualified and quoted table name for the

[ Top ]

_getLogLevel [line 1036]

string _getLogLevel(
integer
$level 
)

Gets a logging level as a string representation.

Parameters:

integer

$level:

The logging level to retrieve a string for.

API Tags:

Return:

The string representation of a valid logging level.

[ Top ]

_log [line 993]

void _log(
integer
$level, string
$msg, [string
$target = ''], [
$def = ''], [
$file = ''], [
$line = ''] 
)

Log a message as appropriate for the level and target.

Parameters:

integer	$level:	The level of the logged message.
string	$msg:	The message to log.
string	$target:	The logging target.
	$def:
	$file:
	$line:

[ Top ]

XPDO

xPDO

xpdo

Packages

Files

Classes

Class xPDO

Class Overview

Properties

Methods

Property Summary

Method Summary

Properties

Methods