core/xpdo/xpdo.class.php

Show:

inherited

Constants
- XPDO_CORE_PATH
- XPDO_PHP_VERSION
Functions
Classes

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

 
                XPDO_PHP_VERSION
                = phpversion()

Defines the PHP version string xPDO is running under.

string 
                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
jump to top

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

 
                OPT_AUTO_CREATE_TABLES
                = 'auto_create_tables'

 
                OPT_BASE_CLASSES
                = 'base_classes'

 
                OPT_BASE_PACKAGES
                = 'base_packages'

 
                OPT_CACHE_COMPRESS
                = 'cache_compress'

 
                OPT_CACHE_DB
                = 'cache_db'

 
                OPT_CACHE_DB_COLLECTIONS
                = 'cache_db_collections'

 
                OPT_CACHE_DB_OBJECTS_BY_PK
                = 'cache_db_objects_by_pk'

 
                OPT_CACHE_DB_EXPIRES
                = 'cache_db_expires'

 
                OPT_CACHE_DB_HANDLER
                = 'cache_db_handler'

 
                OPT_CACHE_DB_SIG_CLASS
                = 'cache_db_sig_class'

 
                OPT_CACHE_DB_SIG_GRAPH
                = 'cache_db_sig_graph'

 
                OPT_CACHE_EXPIRES
                = 'cache_expires'

 
                OPT_CACHE_FORMAT
                = 'cache_format'

 
                OPT_CACHE_HANDLER
                = 'cache_handler'

 
                OPT_CACHE_KEY
                = 'cache_key'

 
                OPT_CACHE_PATH
                = 'cache_path'

 
                OPT_CACHE_PREFIX
                = 'cache_prefix'

 
                OPT_CACHE_ATTEMPTS
                = 'cache_attempts'

 
                OPT_CACHE_ATTEMPT_DELAY
                = 'cache_attempt_delay'

 
                OPT_CALLBACK_ON_REMOVE
                = 'callback_on_remove'

 
                OPT_CALLBACK_ON_SAVE
                = 'callback_on_save'

 
                OPT_CONNECTIONS
                = 'connections'

 
                OPT_CONN_INIT
                = 'connection_init'

 
                OPT_CONN_MUTABLE
                = 'connection_mutable'

 
                OPT_HYDRATE_FIELDS
                = 'hydrate_fields'

 
                OPT_HYDRATE_ADHOC_FIELDS
                = 'hydrate_adhoc_fields'

 
                OPT_HYDRATE_RELATED_OBJECTS
                = 'hydrate_related_objects'

 
                OPT_LOADER_CLASSES
                = 'loader_classes'

Deprecated
See: \call()

 
                OPT_ON_SET_STRIPSLASHES
                = 'on_set_stripslashes'

 
                OPT_SETUP
                = 'setup'

 
                OPT_TABLE_PREFIX
                = 'table_prefix'

 
                OPT_VALIDATE_ON_SAVE
                = 'validate_on_save'

 
                OPT_VALIDATOR_CLASS
                = 'validator_class'

 
                LOG_LEVEL_FATAL
                = 0

 
                LOG_LEVEL_ERROR
                = 1

 
                LOG_LEVEL_WARN
                = 2

 
                LOG_LEVEL_INFO
                = 3

 
                LOG_LEVEL_DEBUG
                = 4

 
                SCHEMA_VERSION
                = '1.1'

Properties

boolean
                 $_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

array
                 $_connections= 'array()'

PDO connections managed by this xPDO instance.

Default valuearray()Details

Type: array

boolean
                 $_debug= 'false'

Indicates the debug state of this instance.

Default is false.

Default valuefalseDetails

Type: boolean
Access: protected

string
                 $_escapeCharClose= ''''

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

Default value''Details

Type: string
Access: public

string
                 $_escapeCharOpen= ''''

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

Default value''Details

Type: string
Access: public

string
                 $_quoteChar= '"'"'

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

Default value"'"Details

Type: string

\xPDOCacheManager
                 $cacheManager= 'null'

The cache service provider registered for this xPDO instance.

Default valuenullDetails

Type: \xPDOCacheManager

string
                 $cachePath= 'null'

A root path for file-based caching services to use.

Default valuenullDetails

Type: string


                 $classMap= 'array()'

Default valuearray()Details

Type: n/a

array
                 $config= 'null'

Configuration options for the xPDO instance.

Default valuenullDetails

Type: array

\xPDOConnection
                 $connection= 'null'

The current xPDOConnection for this xPDO instance.

Default valuenullDetails

Type: \xPDOConnection

\xPDODriver
                 $driver= 'null'

An xPDODriver instance for the xPDOConnection instances to use.

Default valuenullDetails

Type: \xPDODriver

int
                 $executedQueries= '0'

The number of direct DB queries executed during a request.

Default value0Details

Type: int

array
                 $instances= 'array()'

static

A static collection of xPDO instances.

Default valuearray()Details

Type: array

integer
                 $logLevel= 'xPDO::LOG_LEVEL_FATAL'

The logging level for the xPDO instance.

Default valuexPDO::LOG_LEVEL_FATALDetails

Type: integer

string
                 $logTarget= ''ECHO''

The default logging target for the xPDO instance.

Default value'ECHO'Details

Type: string

\xPDOManager
                 $manager= 'null'

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

Default valuenullDetails

Type: \xPDOManager
Access: public

array
                 $map= 'array ()'

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

Default valuearray ()Details

Type: array
Access: public

string
                 $package= ''''

A default package for specifying classes by name.

Default value''Details

Type: string
Access: public

array
                 $packages= 'array ()'

An array storing packages and package-specific information.

Default valuearray ()Details

Type: array
Access: public

\PDO
                 $pdo= 'null'

A reference to the PDO instance used by the current xPDOConnection.

Default valuenullDetails

Type: \PDO

int
                 $queryTime= '0'

The amount of request handling time spent with DB queries.

Default value0Details

Type: int

array
                 $services= 'array ()'

An array of supplemental service classes for this xPDO instance.

Default valuearray ()Details

Type: array

float
                 $startTime= '0'

Start time of the request, initialized when the constructor is called.

Default value0Details

Type: float

Methods

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

_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

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

_loadClass(
           $class,  $fqn,  $included
              =
              false,  $path
              =
              '',  $transient
              =
              false
          )
        
        :
          void

Parameters

Name	Type	Description
$class
$fqn
$included
$path
$transient

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

addConnection(
          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.

addDerivativeCriteria(
          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.

addPackage(
          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

beginTransaction(
          
          )
        
        :
          void

Details

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

call(
          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.

commit(
          
          )
        
        :
          void

Details

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

connect(
          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.

errorCode(
          
          )
        
        :
          void

Details

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

errorInfo(
          
          )
        
        :
          void

Details

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

escSplit(
          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

escape(
          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.

exec(
           $query
          )
        
        :
          void

Parameters

Name	Type	Description
$query

Details

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

fromCache(
          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.

fromJSON(
          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.

getAggregates(
          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.

getAncestry(
          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.

getAttribute(
           $attribute
          )
        
        :
          void

Parameters

Name	Type	Description
$attribute

Details

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

getCacheManager(
          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.

getCachePath(
          
          )
        
        :
          string

Gets the absolute path to the cache directory.

Returns

Type	Description
string	The full cache directory path.

getCollection(
          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()

getCollectionGraph(
          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()

getComposites(
          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.

getConnection(
          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.

getCount(
          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.

getCriteria(
          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.

getCriteriaType(
          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.

getDebug(
          
          )
        
        :
          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.

getDebugBacktrace(
          
          )
        
        :
          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.

getDescendants(
          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.

getDriver(
          
          )
        
        :
          \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.

getFKDefinition(
          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.

getFieldAliases(
          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.

getFieldMeta(
          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.

getFields(
          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.

getGraph(
          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.

getIndexMeta(
          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.

getInherit(
          \$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

getInstance(
          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

getIterator(
          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.

getLogLevel(
          
          )
        
        :
          integer

Returns

Type	Description
integer	The current log level.

getLogTarget(
          
          )
        
        :
          integer

Returns

Type	Description
integer	The current log level.

getManager(
          
          )
        
        :
          \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.

getMicroTime(
          
          )
        
        :
          float

Convert current microtime() result into seconds.

Returns

Type	Description
float

getModelVersion(
          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.

getObject(
          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()

getObjectGraph(
          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()

getObjectLoader(
          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.

getOption(
          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.

getPDOType(
          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

getPK(
          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.

getPKType(
          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!

getPackage(
          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.

getSelectColumns(
          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()

getService(
          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.

getTableClass(
          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.

getTableMeta(
          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.

getTableName(
          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.

getValidationRules(
          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.

getValue(
          \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.

initConfig(
          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.

lastInsertId(
          
          )
        
        :
          void

Details

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

literal(
          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.

loadClass(
          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.

log(
          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.

newObject(
          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.

newQuery(
          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.

parseBindings(
          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.

parseDSN(
          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.

prepare(
           $statement,  $driver_options
              =
              array ()
          )
        
        :
          void

Parameters

Name	Type	Description
$statement
$driver_options

Details

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

query(
           $query
          )
        
        :
          void

Parameters

Name	Type	Description
$query

Details

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

quote(
           $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

removeCollection(
          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.

removeObject(
          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.

rollBack(
          
          )
        
        :
          void

Details

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

setAttribute(
           $attribute,  $value
          )
        
        :
          void

Parameters

Name	Type	Description
$attribute
$value

Details

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

setDebug(
          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.

setLogLevel(
          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.

setLogTarget(
          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.

setOption(
          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.

setPackage(
          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

setPackageMeta(
          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

toCache(
          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.

toJSON(
          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.

updateCollection(
          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
jump to top

Package: xpdo

Represents a unique PDO connection managed by xPDO.

Properties

boolean
                 $_mutable= 'true'

Indicates if this connection can be written to.

Default valuetrueDetails

Type: boolean

array
                 $config= 'array()'

An array of configuration options for this connection.

Default valuearray()Details

Type: array

\PDO
                 $pdo= 'null'

The PDO object represented by the xPDOConnection instance.

Default valuenullDetails

Type: \PDO

\xPDO
                 $xpdo= 'null'

A reference to a valid xPDO instance.

Default valuenullDetails

Type: \xPDO

Methods

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

connect(
          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.

getOption(
           $key,  $options
              =
              null,  $default
              =
              null
          )
        
        :
          void

Parameters

Name	Type	Description
$key
$options
$default

isMutable(
          
          )
        
        :
          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
jump to top

Package: xpdo

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

Children: \xPDOQuery

Properties


                 $bindings= 'array ()'

Default valuearray ()Details

Type: n/a


                 $cacheFlag= 'false'

Default valuefalseDetails

Type: n/a


                 $sql= ''''

Default value''Details

Type: n/a


                 $stmt= 'null'

Default valuenullDetails

Type: n/a

Methods

__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

bind(
          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.

equals(
          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.

prepare(
          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.

toSQL(
          
          )
        
        :
          string

Converts the current xPDOQuery to parsed SQL.

Returns

Type	Description
string	The parsed SQL query.

Details

Access: public

\xPDOException
jump to top

Package: Default

A basic class for xPDO Exceptions.

Parent(s): \Exception

Methods

__construct(
          
          )
        
        :
          void

__toString(
          
          )
        
        :
          void

getCode(
          
          )
        
        :
          void

final

getFile(
          
          )
        
        :
          void

final

getLine(
          
          )
        
        :
          void

final

getMessage(
          
          )
        
        :
          void

final

getPrevious(
          
          )
        
        :
          void

final

getTrace(
          
          )
        
        :
          void

final

getTraceAsString(
          
          )
        
        :
          void

final

\xPDOIterator
jump to top

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


                 $alias= 'null'

Default valuenullDetails

Type: n/a


                 $cacheFlag= 'false'

Default valuefalseDetails

Type: n/a


                 $class= 'null'

Default valuenullDetails

Type: n/a


                 $criteria= 'null'

Default valuenullDetails

Type: n/a


                 $criteriaType= ''xPDOQuery''

Default value'xPDOQuery'Details

Type: n/a


                 $current= 'null'

Default valuenullDetails

Type: n/a


                 $index= '0'

Default value0Details

Type: n/a


                 $stmt= 'null'

Default valuenullDetails

Type: n/a


                 $xpdo= 'null'

Default valuenullDetails

Type: n/a

Methods

__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()

current(
          
          )
        
        :
          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.

rewind(
          
          )
        
        :
          void

core/xpdo/xpdo.class.php

Constants

\xPDOjump to top

Constants

Properties

Methods

\xPDOConnectionjump to top

Properties

Methods

\xPDOCriteriajump to top

Properties

Methods

\xPDOExceptionjump to top

Methods

\xPDOIteratorjump to top

Properties

Methods

\xPDO
jump to top

\xPDOConnection
jump to top

\xPDOCriteria
jump to top

\xPDOException
jump to top

\xPDOIterator
jump to top