core/xpdo/xpdo.class.php

Show: inherited
Table of Contents

This is the main file to include in your scripts to use xPDO.

Author
Jason Coward  
Copyright
Copyright (C) 2006-2012, Jason Coward  
License
GNU Public License v2  
Package
xpdo  

Constants

Constant  XPDO_PHP_VERSION = phpversion()

Defines the PHP version string xPDO is running under.

Constantstring  XPDO_CORE_PATH = $xpdo_core_path

Access
public  
string
The full path to the xPDO root directory. Use of this constant is recommended for use when building any path in your xPDO code.

\xPDO

Package: xpdo

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

xPDO provides centralized data access via a simple object-oriented API, to a defined data structure. It provides the de facto methods for connecting to a data source, getting persistence metadata for any class extended from the {@link 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.

Children
\modX

Constants

Constant  OPT_AUTO_CREATE_TABLES = 'auto_create_tables'
Constant  OPT_BASE_CLASSES = 'base_classes'
Constant  OPT_BASE_PACKAGES = 'base_packages'
Constant  OPT_CACHE_COMPRESS = 'cache_compress'
Constant  OPT_CACHE_DB = 'cache_db'
Constant  OPT_CACHE_DB_COLLECTIONS = 'cache_db_collections'
Constant  OPT_CACHE_DB_OBJECTS_BY_PK = 'cache_db_objects_by_pk'
Constant  OPT_CACHE_DB_EXPIRES = 'cache_db_expires'
Constant  OPT_CACHE_DB_HANDLER = 'cache_db_handler'
Constant  OPT_CACHE_DB_SIG_CLASS = 'cache_db_sig_class'
Constant  OPT_CACHE_DB_SIG_GRAPH = 'cache_db_sig_graph'
Constant  OPT_CACHE_EXPIRES = 'cache_expires'
Constant  OPT_CACHE_FORMAT = 'cache_format'
Constant  OPT_CACHE_HANDLER = 'cache_handler'
Constant  OPT_CACHE_KEY = 'cache_key'
Constant  OPT_CACHE_PATH = 'cache_path'
Constant  OPT_CACHE_PREFIX = 'cache_prefix'
Constant  OPT_CACHE_ATTEMPTS = 'cache_attempts'
Constant  OPT_CACHE_ATTEMPT_DELAY = 'cache_attempt_delay'
Constant  OPT_CALLBACK_ON_REMOVE = 'callback_on_remove'
Constant  OPT_CALLBACK_ON_SAVE = 'callback_on_save'
Constant  OPT_CONNECTIONS = 'connections'
Constant  OPT_CONN_INIT = 'connection_init'
Constant  OPT_CONN_MUTABLE = 'connection_mutable'
Constant  OPT_HYDRATE_FIELDS = 'hydrate_fields'
Constant  OPT_HYDRATE_ADHOC_FIELDS = 'hydrate_adhoc_fields'
Constant  OPT_HYDRATE_RELATED_OBJECTS = 'hydrate_related_objects'
Constant  OPT_LOADER_CLASSES = 'loader_classes'

Deprecated
 
See
\call()  
Constant  OPT_ON_SET_STRIPSLASHES = 'on_set_stripslashes'
Constant  OPT_SETUP = 'setup'
Constant  OPT_TABLE_PREFIX = 'table_prefix'
Constant  OPT_VALIDATE_ON_SAVE = 'validate_on_save'
Constant  OPT_VALIDATOR_CLASS = 'validator_class'
Constant  LOG_LEVEL_FATAL = 0
Constant  LOG_LEVEL_ERROR = 1
Constant  LOG_LEVEL_WARN = 2
Constant  LOG_LEVEL_INFO = 3
Constant  LOG_LEVEL_DEBUG = 4
Constant  SCHEMA_VERSION = '1.1'

Properties

Propertypublicboolean  $_cacheEnabled= 'false'

A global cache flag that can be used to enable/disable all xPDO caching.

All caching is disabled by default.
Default valuefalseDetails
Type
boolean
Access
public  
Propertyprivatearray  $_connections= 'array()'

PDO connections managed by this xPDO instance.
Default valuearray()Details
Type
array
Propertyprotectedboolean  $_debug= 'false'

Indicates the debug state of this instance.

Default is false.
Default valuefalseDetails
Type
boolean
Access
protected  
Propertypublicstring  $_escapeCharClose= ''''

Indicates the closing escape character used for a particular database engine.

Default value''Details
Type
string
Access
public  
Propertypublicstring  $_escapeCharOpen= ''''

Indicates the opening escape character used for a particular database engine.

Default value''Details
Type
string
Access
public  
Propertypublicstring  $_quoteChar= '"'"'

Represents the character used for quoting strings for a particular driver.

Default value"'"Details
Type
string
Propertypublic\xPDOCacheManager  $cacheManager= 'null'

The cache service provider registered for this xPDO instance.
Default valuenullDetails
Type
\xPDOCacheManager
Propertyprivatestring  $cachePath= 'null'

A root path for file-based caching services to use.
Default valuenullDetails
Type
string
Propertypublic  $classMap= 'array()'
Default valuearray()Details
Type
n/a
Propertypublicarray  $config= 'null'

Configuration options for the xPDO instance.
Default valuenullDetails
Type
array
Propertypublic\xPDOConnection  $connection= 'null'

The current xPDOConnection for this xPDO instance.
Default valuenullDetails
Type
\xPDOConnection
Propertypublic\xPDODriver  $driver= 'null'

An xPDODriver instance for the xPDOConnection instances to use.
Default valuenullDetails
Type
\xPDODriver
Propertypublicint  $executedQueries= '0'

The number of direct DB queries executed during a request.
Default value0Details
Type
int
Propertyprotectedarray  $instances= 'array()'
static

A static collection of xPDO instances.
Default valuearray()Details
Type
array
Propertyprotectedinteger  $logLevel= 'xPDO::LOG_LEVEL_FATAL'

The logging level for the xPDO instance.
Default valuexPDO::LOG_LEVEL_FATALDetails
Type
integer
Propertyprotectedstring  $logTarget= ''ECHO''

The default logging target for the xPDO instance.
Default value'ECHO'Details
Type
string
Propertypublic\xPDOManager  $manager= 'null'

{@link xPDOManager} instance, loaded only if needed to manage datasource containers, data structures, etc.

Default valuenullDetails
Type
\xPDOManager
Access
public  
Propertypublicarray  $map= 'array ()'

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

Default valuearray ()Details
Type
array
Access
public  
Propertypublicstring  $package= ''''

A default package for specifying classes by name.

Default value''Details
Type
string
Access
public  
Propertypublicarray  $packages= 'array ()'

An array storing packages and package-specific information.

Default valuearray ()Details
Type
array
Access
public  
Propertypublic\PDO  $pdo= 'null'

A reference to the PDO instance used by the current xPDOConnection.
Default valuenullDetails
Type
\PDO
Propertypublicint  $queryTime= '0'

The amount of request handling time spent with DB queries.
Default value0Details
Type
int
Propertypublicarray  $services= 'array ()'

An array of supplemental service classes for this xPDO instance.
Default valuearray ()Details
Type
array
Propertypublicfloat  $startTime= '0'

Start time of the request, initialized when the constructor is called.
Default value0Details
Type
float

Methods

methodpublic__construct( mixed $dsn, string $username = '', string $password = '', array | string $options = array(), array | null $driverOptions = null ) : \xPDO

The xPDO Constructor.

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

Parameters
Name Type Description
$dsn mixed

A valid DSN connection string.

$username string

The database username with proper permissions.

$password string

The password for the database user.

$options array | string

An array of xPDO options. For compatibility with previous releases, this can also be a single string representing a prefix to be applied to all database container (i. e. table) names, to isolate multiple installations or conflicting table names that might need to coexist in a single database container. It is preferrable to include the table_prefix option in the array for future compatibility.

$driverOptions array | null

Driver-specific PDO options.

Returns
Type Description
\xPDO A unique xPDO instance.
methodprivate_getFullTableName( string $baseTableName, boolean $includeDb = false ) : string

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

Parameters
Name Type Description
$baseTableName string

The table name as specified in the object model.

$includeDb boolean

Qualify the table name with the database name.

Returns
Type Description
string The fully-qualified and quoted table name for the
methodprotected_getLogLevel( integer $level ) : string

Gets a logging level as a string representation.

Parameters
Name Type Description
$level integer

The logging level to retrieve a string for.

Returns
Type Description
string The string representation of a valid logging level.
methodprotected_loadClass(  $class,  $fqn,  $included = false,  $path = '',  $transient = false ) : void

Parameters
Name Type Description
$class
$fqn
$included
$path
$transient
methodprotected_log( integer $level, string $msg, string $target = '', string $def = '', string $file = '', string $line = '' ) : void

Log a message as appropriate for the level and target.

Parameters
Name Type Description
$level integer

The level of the logged message.

$msg string

The message to log.

$target string

The logging target.

$def string

The name of a defining structure (such as a class) to help identify the log event source.

$file string

A filename in which the log event occured.

$line string

A line number to help locate the source of the event within the indicated file.

methodpublicaddConnection( string $dsn, string $username = '', string $password = '', array $options = array(), null $driverOptions = null ) : boolean

Add an xPDOConnection instance to the xPDO connection pool.

Parameters
Name Type Description
$dsn string

A PDO DSN representing the connection details.

$username string

The username credentials for the connection.

$password string

The password credentials for the connection.

$options array

An array of options for the connection.

$driverOptions null

An array of PDO driver options for the connection.

Returns
Type Description
boolean True if a valid connection was added.
methodpublicaddDerivativeCriteria( string $className, \xPDOCriteria $criteria ) : void

Add criteria when requesting a derivative class row automatically.

This applies class_key filtering for single-table inheritance queries and may provide a convenient location for similar features in the future.

Parameters
Name Type Description
$className string

A valid xPDOObject derivative table class.

$criteria \xPDOCriteria

A valid xPDOCriteria instance.

methodpublicaddPackage( string $pkg = '', string $path = '', string | null $prefix = null ) : bool

Adds a model package and base class path for including classes and/or maps from.

Parameters
Name Type Description
$pkg string

A package name to use when looking up classes/maps in xPDO.

$path string

The root path for looking up classes in this package.

$prefix string | null

Provide a string to define a package-specific table_prefix.

Returns
Type Description
bool
methodpublicbeginTransaction( ) : void

Details
See
\http://php.net/manual/en/function.pdo-begintransaction.php  
methodpubliccall( string $class, string $method, array $args = array(), boolean $transient = false ) : mixed | null

Call a static method from a valid package class with arguments.

Will always search for database-specific class files first.

Parameters
Name Type Description
$class string

The name of a class to to get the static method from.

$method string

The name of the method you want to call.

$args array

An array of arguments for the method.

$transient boolean

Indicates if the class has dbtype derivatives. Set to true if you want to use on classes not derived from xPDOObject.

Returns
Type Description
mixed | null The callback method's return value or null if no valid method is found.
methodpubliccommit( ) : void

Details
See
\http://php.net/manual/en/function.pdo-commit.php  
methodpublicconnect( array $driverOptions = array (),  $options = array() ) : boolean

Get or create a PDO connection to a database specified in the configuration.

Parameters
Name Type Description
$driverOptions array

An optional array of driver options to use when creating the connection.

$options
Returns
Type Description
boolean Returns true if the PDO connection was created successfully.
methodpublicerrorCode( ) : void

Details
See
\http://php.net/manual/en/function.pdo-errorcode.php  
methodpublicerrorInfo( ) : void

Details
See
\http://php.net/manual/en/function.pdo-errorinfo.php  
methodpublicescSplit( string $char, string $str, string $escToken = '`', integer $limit = 0 ) : array
static

Splits a string on a specified character, ignoring escaped content.

Parameters
Name Type Description
$char string

A character to split the tag content on.

$str string

The string to operate on.

$escToken string

A character used to surround escaped content; all content within a pair of these tokens will be ignored by the split operation.

$limit integer

Limit the number of results. Default is 0 which is no limit. Note that setting the limit to 1 will only return the content up to the first instance of the split character and will discard the remainder of the string.

Returns
Type Description
array An array of results from the split operation, or an empty array.
Details
Static
 
methodpublicescape( string $string ) : string

Escapes the provided string using the platform-specific escape character.

Different database engines escape string literals in SQL using different characters. For example, this is used to escape column names that might match a reserved string for that SQL interpreter. To write database agnostic queries with xPDO, it is highly recommend to escape any database or column names in any native SQL strings used.

Parameters
Name Type Description
$string string

A string to escape using the platform-specific escape characters.

Returns
Type Description
string The string escaped with the platform-specific escape characters.
methodpublicexec(  $query ) : void

Parameters
Name Type Description
$query
Details
See
\http://php.net/manual/en/function.pdo-exec.php  
methodpublicfromCache( string | \xPDOCriteria $signature, string $class = '', array $options = array() ) : array | string | null

Retrieves a result array from the object cache.

Parameters
Name Type Description
$signature string | \xPDOCriteria

A unique string or xPDOCriteria object that represents the query identifying the result set.

$class string

An optional classname the result represents.

$options array

Various cache options.

Returns
Type Description
array | string | null A PHP array or JSON object representing the result set, or null if no cache representation is found.
methodpublicfromJSON( string $src, boolean $asArray = true ) : mixed

Converts a JSON source string into an equivalent PHP representation.

Parameters
Name Type Description
$src string

A JSON source string.

$asArray boolean

Indicates if the result should treat objects as associative arrays; since all JSON associative arrays are objects, the default is true. Set to false to have JSON objects returned as PHP objects.

Returns
Type Description
mixed The PHP representation of the JSON source.
methodpublicgetAggregates( string $className ) : array

Gets a collection of aggregate foreign key relationship definitions.

Parameters
Name Type Description
$className string

The fully-qualified name of the class.

Returns
Type Description
array An array of aggregate foreign key relationship definitions.
methodpublicgetAncestry( string $className, boolean $includeSelf = true ) : array

Retrieves the complete ancestry for a class.

Parameters
Name Type Description
$className string

className The name of the class.

$includeSelf boolean

includeSelf Determines if the specified class should be included in the resulting array.

Returns
Type Description
array An array of string class names representing the class hierarchy, or an empty array if unsuccessful.
methodpublicgetAttribute(  $attribute ) : void

Parameters
Name Type Description
$attribute
Details
See
\http://php.net/manual/en/function.pdo-getattribute.php  
methodpublicgetCacheManager( string $class = 'cache.xPDOCacheManager', array $options = array('path' => XPDO_CORE_PATH, 'ignorePkg' => true) ) : \xPDOCacheManager

Gets an xPDOCacheManager instance.

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

Parameters
Name Type Description
$class string

Optional name of a derivative xPDOCacheManager class.

$options array

An array of options for the cache manager instance; valid options include: - path = Optional root path for looking up the $class. - ignorePkg = If false and you do not specify a path, you can look up custom xPDOCacheManager derivatives in declared packages.

Returns
Type Description
\xPDOCacheManager The xPDOCacheManager for this xPDO instance.
methodpublicgetCachePath( ) : string

Gets the absolute path to the cache directory.

Returns
Type Description
string The full cache directory path.
methodpublicgetCollection( string $className, object | array | string $criteria = null, mixed $cacheFlag = true ) : array | null

Retrieves a collection of xPDOObjects by the specified xPDOCriteria.

Parameters
Name Type Description
$className string

Name of the class to search for instances of.

$criteria object | array | string

An xPDOCriteria object or an array search expression.

$cacheFlag mixed

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.

Returns
Type Description
array | null An array of class instances retrieved.
Details
Uses
\xPDOObject::loadCollection()  
methodpublicgetCollectionGraph( string $className, string | array $graph, mixed $criteria = null, boolean $cacheFlag = true ) : array

Retrieves a collection of xPDOObject instances with related objects.

Parameters
Name Type Description
$className string

The name of the class to return a collection of.

$graph string | array

A related object graph in array or JSON format, e.g. array('relationAlias'=>array('subRelationAlias'=>array())) or {"relationAlias":{"subRelationAlias":{}}}. Note that the empty arrays are necessary in order for the relation to be recognized.

$criteria mixed

A valid xPDOCriteria instance or condition string.

$cacheFlag boolean

Indicates if the result set should be cached.

Returns
Type Description
array An array of instances matching the criteria with related objects from the graph hydrated. An empty array is returned when no matches are found.
Details
Used_by
\modX::getObjectGraph()  
Used_by
\xPDO::getObjectGraph()  
Uses
\xPDOQuery::bindGraph()  
methodpublicgetComposites( string $className ) : array

Gets a collection of composite foreign key relationship definitions.

Parameters
Name Type Description
$className string

The fully-qualified name of the class.

Returns
Type Description
array An array of composite foreign key relationship definitions.
methodpublicgetConnection( array $options = array() ) : \xPDOConnection | null

Get an xPDOConnection from the xPDO connection pool.

Parameters
Name Type Description
$options array

An array of options for getting the connection.

Returns
Type Description
\xPDOConnection | null An xPDOConnection instance or null if no connection could be retrieved.
methodpublicgetCount( string $className, mixed $criteria = null ) : integer

Retrieves a count of xPDOObjects by the specified xPDOCriteria.

Parameters
Name Type Description
$className string

Class of xPDOObject to count instances of.

$criteria mixed

Any valid xPDOCriteria object or expression.

Returns
Type Description
integer The number of instances found by the criteria.
methodpublicgetCriteria( string $className, string $type = null, boolean | integer $cacheFlag = true ) : \xPDOCriteria

Convert any valid criteria into an xPDOQuery instance.

Parameters
Name Type Description
$className string

The class to get predefined criteria for.

$type string

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 boolean | integer

Indicates if the result is cached and optionally for how many seconds.

Returns
Type Description
\xPDOCriteria A criteria object or null if not found.
Details
Todo
Get criteria pre-defined in an {@link xPDOObject} class metadata definition by name.  
Todo
Define callback functions as an alternative to retreiving criteria sql and/or bindings from the metadata.  
methodpublicgetCriteriaType( mixed $criteria ) : string | null

Validate and return the type of a specified criteria variable.

Parameters
Name Type Description
$criteria mixed

An xPDOCriteria instance or any valid criteria variable.

Returns
Type Description
string | null The type of valid criteria passed, or null if the criteria is not valid.
methodpublicgetDebug( ) : boolean

Returns the debug state for the xPDO instance.

Returns
Type Description
boolean The current debug state for the instance, true for on, false for off.
methodpublicgetDebugBacktrace( ) : array

Returns an abbreviated backtrace of debugging information.

This function returns just the fields returned via xPDOObject::toArray() on xPDOObject instances, and simply the classname for other objects, to reduce the amount of unnecessary information returned.

Returns
Type Description
array The abbreviated backtrace.
methodpublicgetDescendants( string $className ) : array

Gets a list of derivative classes for the specified xPDOObject instance.

NOTE: Will not work with xPDOObject/xPDOSimpleObject.

Parameters
Name Type Description
$className string

The name of the class to retrieve derivatives for.

Returns
Type Description
array An array of derivative classes or an empty array.
methodpublicgetDriver( ) : \xPDODriver | null

Gets the driver class for this xPDO connection.

The driver class provides baseline data and operations for a specific database driver.

Returns
Type Description
\xPDODriver | null An xPDODriver instance for the xPDO connection, or null if a driver class can not be instantiated.
methodpublicgetFKDefinition( string $parentClass, string $alias ) : array

Gets an aggregate or composite relation definition from a class.

Parameters
Name Type Description
$parentClass string

The class from which the relation is defined.

$alias string

The alias identifying the related class.

Returns
Type Description
array The aggregate or composite definition details in an array or null if no definition is found.
methodpublicgetFieldAliases( string $className ) : array

Gets a collection of field aliases for an object by class name.

Parameters
Name Type Description
$className string

The name of the class to lookup field aliases for.

Returns
Type Description
array An array of field aliases with aliases as keys and actual field names as values.
methodpublicgetFieldMeta( string $className, boolean $includeExtended = false ) : array

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 inheritance.

Parameters
Name Type Description
$className string

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

$includeExtended boolean

If true, include meta from all derivative classes in loaded packages.

Returns
Type Description
array An array featuring field names as the array keys, and arrays of metadata information as the array values; empty array is returned if unsuccessful.
methodpublicgetFields( string $className ) : array

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
Name Type Description
$className string

The name of the class to lookup fields for.

Returns
Type Description
array An array featuring field names as the array keys, and default field values as the array values; empty array is returned if unsuccessful.
methodpublicgetGraph( string $className, int $depth = 3, array $parents = array(), array $visited = array() ) : array

Get a complete relation graph for an xPDOObject class.

Parameters
Name Type Description
$className string

A fully-qualified xPDOObject class name.

$depth int

The depth to retrieve relations for the graph, defaults to 3.

$parents array

&$parents An array of parent classes to avoid traversing circular dependencies.

$visited array

&$visited An array of already visited classes to avoid traversing circular dependencies.

Returns
Type Description
array An xPDOObject relation graph, or an empty array if no graph can be constructed.
methodpublicgetIndexMeta( string $className ) : array

Get indices defined for a table class.

Parameters
Name Type Description
$className string

The name of the class to lookup indices for.

Returns
Type Description
array An array of indices and their details for the specified class.
methodpublicgetInherit( \$className $className ) : string

Indicates the inheritance model for the xPDOObject class specified.

Parameters
Name Type Description
$className \$className

The class to determine the table inherit type from.

Returns
Type Description
string single, multiple, or none
methodpublicgetInstance( string | int | null $id = null, array | null $config = null, bool $forceNew = false ) : \xPDO
static

Create, retrieve, or update specific xPDO instances.

Parameters
Name Type Description
$id string | int | null

An optional identifier for the instance. If not set a uniqid will be generated and used as the key for the instance.

$config array | null

An optional array of config data for the instance.

$forceNew bool

If true a new instance will be created even if an instance with the provided $id already exists in xPDO::$instances.

Returns
Type Description
\xPDO An instance of xPDO.
Details
Static
 
methodpublicgetIterator( string $className, mixed $criteria = null, bool $cacheFlag = true ) : \xPDOIterator

Retrieves an iterable representation of a collection of xPDOObjects.

Parameters
Name Type Description
$className string

Name of the class to search for instances of.

$criteria mixed

An xPDOCriteria object or representation.

$cacheFlag bool

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.

Returns
Type Description
\xPDOIterator An iterable representation of a collection.
methodpublicgetLogLevel( ) : integer

Returns
Type Description
integer The current log level.
methodpublicgetLogTarget( ) : integer

Returns
Type Description
integer The current log level.
methodpublicgetManager( ) : \xPDOManager | null

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.

Returns
Type Description
\xPDOManager | null An xPDOManager instance for the xPDO connection, or null if a manager class can not be instantiated.
methodpublicgetMicroTime( ) : float

Convert current microtime() result into seconds.

Returns
Type Description
float
methodpublicgetModelVersion( string $className ) : string

Gets the version string of the schema the specified class was generated from.

Parameters
Name Type Description
$className string

The name of the class to get the model version from.

Returns
Type Description
string The version string for the schema model the class was generated from.
methodpublicgetObject( string $className, mixed $criteria = null, mixed $cacheFlag = true ) : object | null

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 {@link 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
Name Type Description
$className string

Name of the class to get an instance of.

$criteria mixed

Primary key of the record or a xPDOCriteria object.

$cacheFlag mixed

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.

Returns
Type Description
object | null An instance of the class, or null if it could not be instantiated.
Details
Uses
\xPDOObject::load()  
methodpublicgetObjectGraph( string $className, string | array $graph, mixed $criteria = null, boolean | integer $cacheFlag = true ) : object

Retrieves an xPDOObject instance with specified related objects.

Parameters
Name Type Description
$className string

The name of the class to return an instance of.

$graph string | array

A related object graph in array or JSON format, e.g. array('relationAlias'=>array('subRelationAlias'=>array())) or {"relationAlias":{"subRelationAlias":{}}}. Note that the empty arrays are necessary in order for the relation to be recognized.

$criteria mixed

A valid xPDOCriteria instance or expression.

$cacheFlag boolean | integer

Indicates if the result set should be cached, and optionally for how many seconds.

Returns
Type Description
object The object instance with related objects from the graph hydrated, or null if no instance can be located by the criteria.
Details
Uses
\xPDO::getCollectionGraph()  
methodpublicgetObjectLoader( string $className, string $method ) : \callable

Finds the class responsible for loading instances of the specified class.

Parameters
Name Type Description
$className string

The name of the class to find a loader for.

$method string

Indicates the specific loader method to use, loadCollection or loadObject (or other public static methods).

Returns
Type Description
\callable A callable loader function.
Details
Deprecated
Use call() instead.  
methodpublicgetOption( string $key, array $options = null, mixed $default = null,  $skipEmpty = false ) : mixed

Get an xPDO configuration option value by key.

Parameters
Name Type Description
$key string

The option key.

$options array

A set of options to override those from xPDO.

$default mixed

An optional default value to return if no value is found.

$skipEmpty
Returns
Type Description
mixed The configuration option value.
methodpublicgetPDOType( mixed $value ) : int | null

Get the appropriate PDO::PARAM_ type constant from a PHP value.

Parameters
Name Type Description
$value mixed

Any PHP scalar or null value

Returns
Type Description
int | null
methodpublicgetPK( string $className ) : mixed

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

Parameters
Name Type Description
$className string

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

Returns
Type Description
mixed 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.
methodpublicgetPKType( string $className,  $pk = false ) : string

Gets the type of primary key field for a class.

Parameters
Name Type Description
$className string

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

$pk
Returns
Type Description
string The type of the field representing a class instance primary key, or null if no primary key is found or defined for the class.
Details
Todo
Refactor method to return array of types rather than compound!  
methodpublicgetPackage( string $className ) : string

Gets the package name from a specified class name.

Parameters
Name Type Description
$className string

The name of the class to lookup the package for.

Returns
Type Description
string The package the class belongs to.
methodpublicgetSelectColumns( string $className, string $tableAlias = '', string $columnPrefix = '', array $columns = array (), boolean $exclude = false ) : string

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

Parameters
Name Type Description
$className string

The name of the class to build the column list from.

$tableAlias string

An optional alias for the class table, to be used in complex queries with multiple tables.

$columnPrefix string

An optional string with which to prefix the columns returned, to avoid name collisions in return columns.

$columns array

An optional array of columns to include.

$exclude boolean

If true, will exclude columns in the previous parameter, instead of including them.

Returns
Type Description
string A valid SQL string of column names for a SELECT statement.
Details
Uses
\xPDOObject::getSelectColumns()  
methodpublicgetService( string $name, string $class = '', string $path = '', array $params = array () ) : object | null

Load and return a named service class instance.

Parameters
Name Type Description
$name string

The variable name of the instance.

$class string

The service class name.

$path string

An optional root path to search for the class.

$params array

An array of optional params to pass to the service class constructor.

Returns
Type Description
object | null A reference to the service class instance or null if it could not be loaded.
methodpublicgetTableClass( string $className ) : null | string

Get the class which defines the table for a specified className.

Parameters
Name Type Description
$className string

The name of a class to determine the table class from.

Returns
Type Description
null | string The name of a class defining the table for the specified className; null if not found.
methodpublicgetTableMeta( string $className ) : string

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

Parameters
Name Type Description
$className string

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

Returns
Type Description
string The table meta data for the class, or null if unsuccessful.
methodpublicgetTableName( string $className, boolean $includeDb = false ) : string

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

Parameters
Name Type Description
$className string

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

$includeDb boolean

Qualify the table name with the database name.

Returns
Type Description
string The table name for the class, or null if unsuccessful.
methodpublicgetValidationRules( string $className ) : array

Gets a set of validation rules defined for an object by class name.

Parameters
Name Type Description
$className string

The name of the class to lookup validation rules for.

Returns
Type Description
array An array featuring field names as the array keys, and arrays of validation rule information as the array values; empty array is returned if unsuccessful.
methodpublicgetValue( \PDOStatement $stmt, null | integer $column = null ) : mixed

Execute a PDOStatement and get a single column value from the first row of the result set.

Parameters
Name Type Description
$stmt \PDOStatement

A prepared PDOStatement object ready to be executed.

$column null | integer

0-indexed number of the column you wish to retrieve from the row. If null or no value is supplied, it fetches the first column.

Returns
Type Description
mixed The value of the specified column from the first row of the result set, or null.
methodprotectedinitConfig( string | array $data ) : array

Initialize an xPDO config array.

Parameters
Name Type Description
$data string | array

The config input source. Currently accepts a PHP array, or a PHP string representing xPDO::OPT_TABLE_PREFIX (deprecated).

Returns
Type Description
array An array of xPDO config data.
methodpubliclastInsertId( ) : void

Details
See
\http://php.net/manual/en/function.pdo-lastinsertid.php  
methodpublicliteral( string $string ) : string

Use to insert a literal string into a SQL query without escaping or quoting.

Parameters
Name Type Description
$string string

A string to return as a literal, unescaped and unquoted.

Returns
Type Description
string The string with any escape or quote characters trimmed.
methodpublicloadClass( string $fqn,  $path = '',  $ignorePkg = false,  $transient = false ) : string | boolean

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
Name Type Description
$fqn string

The fully-qualified name of the class to load.

$path
$ignorePkg
$transient
Returns
Type Description
string | boolean The actual classname if successful, or false if not.
methodpubliclog( integer $level, string $msg, string $target = '', string $def = '', string $file = '', string $line = '' ) : void

Log a message with details about where and when an event occurs.

Parameters
Name Type Description
$level integer

The level of the logged message.

$msg string

The message to log.

$target string

The logging target.

$def string

The name of a defining structure (such as a class) to help identify the message source.

$file string

A filename in which the log event occured.

$line string

A line number to help locate the source of the event within the indicated file.

methodpublicnewObject( string $className, array $fields = array () ) : object | null

Creates a new instance of a specified class.

All new objects created with this method are transient until {@link xPDOObject::save()} is called the first time and is reflected by the {@link xPDOObject::$_new} property.

Parameters
Name Type Description
$className string

Name of the class to get a new instance of.

$fields array

An associated array of field names/values to populate the object with.

Returns
Type Description
object | null A new instance of the specified class, or null if a new object could not be instantiated.
methodpublicnewQuery( string $class, mixed $criteria = null, boolean | integer $cacheFlag = true ) : \xPDOQuery

Creates an new xPDOQuery for a specified xPDOObject class.

Parameters
Name Type Description
$class string

The class to create the xPDOQuery for.

$criteria mixed

Any valid xPDO criteria expression.

$cacheFlag boolean | integer

Indicates if the result should be cached and optionally for how many seconds (if passed an integer greater than 0).

Returns
Type Description
\xPDOQuery The resulting xPDOQuery instance or false if unsuccessful.
methodpublicparseBindings( string $sql, array $bindings ) : string

Parses parameter bindings in SQL prepared statements.

Parameters
Name Type Description
$sql string

A SQL prepared statement to parse bindings in.

$bindings array

An array of parameter bindings to use for the replacements.

Returns
Type Description
string The SQL with the binding placeholders replaced.
methodpublicparseDSN( string $string ) : array
static

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

Parameters
Name Type Description
$string string

The DSN to parse.

Returns
Type Description
array An array of connection details from the DSN.
Details
Static
 
Todo
Have this method handle all methods of DSN specification as handled by latest native PDO implementation.  
methodpublicprepare(  $statement,  $driver_options = array () ) : void

Parameters
Name Type Description
$statement
$driver_options
Details
See
\http://php.net/manual/en/function.pdo-prepare.php  
methodpublicquery(  $query ) : void

Parameters
Name Type Description
$query
Details
See
\http://php.net/manual/en/function.pdo-query.php  
methodpublicquote(  $string,  $parameter_type = PDO::PARAM_STR ) : void

Parameters
Name Type Description
$string
$parameter_type
Details
See
\http://php.net/manual/en/function.pdo-quote.php  
methodpublicremoveCollection( string $className, mixed $criteria ) : boolean | integer

Remove a collection of instances by the supplied className and criteria.

Parameters
Name Type Description
$className string

The name of the class to remove a collection of.

$criteria mixed

Valid xPDO criteria for selecting a collection.

Returns
Type Description
boolean | integer False if the remove encounters an error, otherwise an integer value representing the number of rows that were removed.
methodpublicremoveObject( string $className, mixed $criteria ) : boolean

Remove an instance of the specified className by a supplied criteria.

Parameters
Name Type Description
$className string

The name of the class to remove an instance of.

$criteria mixed

Valid xPDO criteria for selecting an instance.

Returns
Type Description
boolean True if the instance is successfully removed.
methodpublicrollBack( ) : void

Details
See
\http://php.net/manual/en/function.pdo-rollback.php  
methodpublicsetAttribute(  $attribute,  $value ) : void

Parameters
Name Type Description
$attribute
$value
Details
See
\http://php.net/manual/en/function.pdo-setattribute.php  
methodpublicsetDebug( boolean | integer $v = true ) : void

Sets the debug state for the xPDO instance.

Parameters
Name Type Description
$v boolean | integer

The debug status, true for on, false for off, or a valid error_reporting level for PHP.

methodpublicsetLogLevel( integer $level = xPDO::LOG_LEVEL_FATAL ) : integer

Sets the logging level state for the xPDO instance.

Parameters
Name Type Description
$level integer

The logging level to switch to.

Returns
Type Description
integer The previous log level.
methodpublicsetLogTarget( string $target = 'ECHO' ) : mixed

Sets the log target for xPDO::_log() calls.

Valid target values include:

  • 'ECHO': Returns output to the STDOUT.
  • 'HTML': Returns output to the STDOUT with HTML formatting.
  • 'FILE': Sends output to a log file.
  • An array with at least one element with key 'target' matching one of the valid log targets listed above. For 'target' => 'FILE' you can specify a second element with key 'options' with another associative array with one or both of the elements 'filename' and 'filepath'
Parameters
Name Type Description
$target string

An identifier indicating the target of the logging.

Returns
Type Description
mixed The previous log target.
methodpublicsetOption( string $key, mixed $value ) : void

Sets an xPDO configuration option value.

Parameters
Name Type Description
$key string

The option key.

$value mixed

A value to set for the given option key.

methodpublicsetPackage( string $pkg = '', string $path = '', string | null $prefix = null ) : bool

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 xPDOObject class that is referenced in xPDO methods such as {@link xPDO::loadClass()}, {@link xPDO::getObject()}, {@link xPDO::getCollection()}, {@link xPDOObject::getOne()}, {@link xPDOObject::addOne()}, etc.

Parameters
Name Type Description
$pkg string

A package name to use when looking up classes in xPDO.

$path string

The root path for looking up classes in this package.

$prefix string | null

Provide a string to define a package-specific table_prefix.

Returns
Type Description
bool
methodpublicsetPackageMeta( string $pkg, string $path = '' ) : bool

Adds metadata information about a package and loads the xPDO::$classMap.

Parameters
Name Type Description
$pkg string

A package name to use when looking up classes/maps in xPDO.

$path string

The root path for looking up classes in this package.

Returns
Type Description
bool
methodpublictoCache( string | \xPDOCriteria $signature, object $object, integer $lifetime = 0, array $options = array() ) : boolean

Places a result set in the object cache.

Parameters
Name Type Description
$signature string | \xPDOCriteria

A unique string or xPDOCriteria object representing the object.

$object object

An object to place a representation of in the cache.

$lifetime integer

An optional number of seconds the cached result will remain valid, with 0 meaning it will remain valid until replaced or removed.

$options array

Various cache options.

Returns
Type Description
boolean Indicates if the object was successfully cached.
methodpublictoJSON( array $array ) : string

Converts a PHP array into a JSON encoded string.

Parameters
Name Type Description
$array array

The PHP array to convert.

Returns
Type Description
string The JSON representation of the source array.
methodpublicupdateCollection( string $className, array $set, mixed $criteria = null ) : bool | int

Update field values across a collection of xPDOObjects.

Parameters
Name Type Description
$className string

Name of the class to update fields of.

$set array

An associative array of field/value pairs representing the updates to make.

$criteria mixed

An xPDOCriteria object or representation.

Returns
Type Description
bool | int The number of instances affected by the update or false on failure.

\xPDOConnection

Package: xpdo

Represents a unique PDO connection managed by xPDO.

Properties

Propertyprivateboolean  $_mutable= 'true'

Indicates if this connection can be written to.
Default valuetrueDetails
Type
boolean
Propertypublicarray  $config= 'array()'

An array of configuration options for this connection.
Default valuearray()Details
Type
array
Propertypublic\PDO  $pdo= 'null'

The PDO object represented by the xPDOConnection instance.
Default valuenullDetails
Type
\PDO
Propertypublic\xPDO  $xpdo= 'null'

A reference to a valid xPDO instance.
Default valuenullDetails
Type
\xPDO

Methods

methodpublic__construct( \xPDO $xpdo, string $dsn, string $username = '', string $password = '', array $options = array(), array $driverOptions = array() ) : void

Construct a new xPDOConnection instance.

Parameters
Name Type Description
$xpdo \xPDO

A reference to a valid xPDO instance to attach to.

$dsn string

A string representing the DSN connection string.

$username string

The database username credentials.

$password string

The database password credentials.

$options array

An array of xPDO options for the connection.

$driverOptions array

An array of PDO driver options for the connection.

methodpublicconnect( array $driverOptions = array() ) : bool

Actually make a connection for this instance via PDO.

Parameters
Name Type Description
$driverOptions array

An array of PDO driver options for the connection.

Returns
Type Description
bool True if a successful connection is made.
methodpublicgetOption(  $key,  $options = null,  $default = null ) : void

Parameters
Name Type Description
$key
$options
$default
methodpublicisMutable( ) : bool

Indicates if the connection can be written to, e.g. INSERT/UPDATE/DELETE.

Returns
Type Description
bool True if the connection can be written to.

\xPDOCriteria

Package: xpdo

Encapsulates a SQL query into a PDOStatement with a set of bindings.

Children
\xPDOQuery

Properties

Propertypublic  $bindings= 'array ()'
Default valuearray ()Details
Type
n/a
Propertypublic  $cacheFlag= 'false'
Default valuefalseDetails
Type
n/a
Propertypublic  $sql= ''''
Default value''Details
Type
n/a
Propertypublic  $stmt= 'null'
Default valuenullDetails
Type
n/a

Methods

methodpublic__construct( \xPDO $xpdo, string $sql = '', array $bindings = array (), boolean | integer $cacheFlag = false ) : \xPDOCriteria

The constructor for a new xPDOCriteria instance.

The constructor optionally prepares provided SQL and/or parameter bindings. Setting the bindings via the constructor or with the {@link xPDOCriteria::bind()} function allows you to make use of the data object caching layer.

The statement will not be prepared immediately if the cacheFlag value is true or a positive integer, in order to allow the result to be found in the cache before being queried from an actual database connection.

Parameters
Name Type Description
$xpdo \xPDO

&$xpdo An xPDO instance that will control this criteria.

$sql string

The SQL statement.

$bindings array

Bindings to bind to the criteria.

$cacheFlag boolean | integer

Indicates if the result set from the criteria is to be cached (true|false) or optionally a TTL in seconds.

Returns
Type Description
\xPDOCriteria
methodpublicbind( array $bindings = array (), boolean $byValue = true, boolean | integer $cacheFlag = false ) : void

Binds an array of key/value pairs to the xPDOCriteria prepared statement.

Use this method to bind parameters in a way that makes it possible to cache results of previous executions of the criteria or compare the criteria to other individual or collections of criteria.

Parameters
Name Type Description
$bindings array

Bindings to merge with any existing bindings defined for this xPDOCriteria instance. Bindings can be simple associative array of key-value pairs or the value for each key can contain elements titled value, type, and length corresponding to the appropriate parameters in the PDOStatement::bindValue() and PDOStatement::bindParam() functions.

$byValue boolean

Determines if the $bindings are to be bound as parameters (by variable reference, the default behavior) or by direct value (if true).

$cacheFlag boolean | integer

The cacheFlag indicates the cache state of the xPDOCriteria object and can be absolutely off (false), absolutely on (true), or an integer indicating the number of seconds the result will live in the cache.

methodpublicequals( object $obj ) : boolean

Compares to see if two xPDOCriteria instances are the same.

Parameters
Name Type Description
$obj object

A xPDOCriteria object to compare to this one.

Returns
Type Description
boolean true if they are both equal is SQL and bindings, otherwise false.
methodpublicprepare( array $bindings = array (), boolean $byValue = true, boolean | integer $cacheFlag = null ) : \PDOStatement

Prepares the sql and bindings of this instance into a PDOStatement.

The {@link xPDOCriteria::$sql} attribute must be set in order to prepare the statement. You can also pass bindings directly to this function and they will be run through {@link xPDOCriteria::bind()} if the statement is successfully prepared.

If the {@link xPDOCriteria::$stmt} already exists, it is simply returned.

Parameters
Name Type Description
$bindings array

Bindings to merge with any existing bindings defined for this xPDOCriteria instance. Bindings can be simple associative array of key-value pairs or the value for each key can contain elements titled value, type, and length corresponding to the appropriate parameters in the PDOStatement::bindValue() and PDOStatement::bindParam() functions.

$byValue boolean

Determines if the $bindings are to be bound as parameters (by variable reference, the default behavior) or by direct value (if true).

$cacheFlag boolean | integer

The cacheFlag indicates the cache state of the xPDOCriteria object and can be absolutely off (false), absolutely on (true), or an integer indicating the number of seconds the result will live in the cache.

Returns
Type Description
\PDOStatement The prepared statement, ready to execute.
methodpublictoSQL( ) : string

Converts the current xPDOQuery to parsed SQL.

Returns
Type Description
string The parsed SQL query.
Details
Access
public  

\xPDOException

Package: Default

A basic class for xPDO Exceptions.

Parent(s)
\Exception

Methods

methodpublic__construct( ) : void

methodpublic__toString( ) : void

methodpublicgetCode( ) : void
final

methodpublicgetFile( ) : void
final

methodpublicgetLine( ) : void
final

methodpublicgetMessage( ) : void
final

methodpublicgetPrevious( ) : void
final

methodpublicgetTrace( ) : void
final

methodpublicgetTraceAsString( ) : void
final

\xPDOIterator

Package: xpdo

An iteratable representation of an xPDOObject result set.

Use an xPDOIterator to loop over large result sets and work with one instance at a time. This greatly reduces memory usage over loading the entire collection of objects into memory at one time. It is also slightly faster.

Parent(s)
?\Iterator

Properties

Propertyprivate  $alias= 'null'
Default valuenullDetails
Type
n/a
Propertyprivate  $cacheFlag= 'false'
Default valuefalseDetails
Type
n/a
Propertyprivate  $class= 'null'
Default valuenullDetails
Type
n/a
Propertyprivate  $criteria= 'null'
Default valuenullDetails
Type
n/a
Propertyprivate  $criteriaType= ''xPDOQuery''
Default value'xPDOQuery'Details
Type
n/a
Propertyprivate  $current= 'null'
Default valuenullDetails
Type
n/a
Propertyprivate  $index= '0'
Default value0Details
Type
n/a
Propertyprivate  $stmt= 'null'
Default valuenullDetails
Type
n/a
Propertyprivate  $xpdo= 'null'
Default valuenullDetails
Type
n/a

Methods

methodpublic__construct( \xPDO $xpdo, array $options = array() ) : \xPDOIterator

Construct a new xPDOIterator instance (do not call directly).

Parameters
Name Type Description
$xpdo \xPDO

&$xpdo A reference to a valid xPDO instance.

$options array

An array of options for the iterator.

Returns
Type Description
\xPDOIterator An xPDOIterator instance.
Details
See
\xPDO::getIterator()  
methodpubliccurrent( ) : void

methodprotectedfetch( ) : void

Fetch the next row from the result set and set it as current.

Calls the _loadInstance() method for the specified class, so it properly inherits behavior from xPDOObject derivatives.

methodpublickey( ) : void

methodpublicnext( ) : void

methodpublicrewind( ) : void

methodpublicvalid( ) : void

Documentation was generated by DocBlox 0.18.1.