xpdo/xpdo.class.php

Constants Classes 
author
Jason Coward <xpdo@opengeek.com>
copyright
Copyright (C) 2006-2011, Jason Coward
license
http://opensource.org/licenses/gpl-2.0.php GNU Public License v2
package
xpdo
Constants
XPDO_PHP_VERSION
XPDO_CORE_PATH
Classes
xPDO
xPDOCriteria
xPDOIterator

Description

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

Constants

XPDO_PHP_VERSION

 XPDO_PHP_VERSION = 'phpversion()'

Details

value
phpversion()

XPDO_CORE_PATH

string XPDO_CORE_PATH = '$xpdo_core_path'

Details

value
$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
Constants
LOG_LEVEL_DEBUG
LOG_LEVEL_ERROR
LOG_LEVEL_FATAL
LOG_LEVEL_INFO
LOG_LEVEL_WARN
OPT_AUTO_CREATE_TABLES
OPT_BASE_CLASSES
OPT_BASE_PACKAGES
OPT_CACHE_ATTEMPTS
OPT_CACHE_ATTEMPT_DELAY
OPT_CACHE_COMPRESS
OPT_CACHE_DB
OPT_CACHE_DB_COLLECTIONS
OPT_CACHE_DB_EXPIRES
OPT_CACHE_DB_HANDLER
OPT_CACHE_DB_OBJECTS_BY_PK
OPT_CACHE_EXPIRES
OPT_CACHE_FORMAT
OPT_CACHE_HANDLER
OPT_CACHE_KEY
OPT_CACHE_PATH
OPT_CALLBACK_ON_REMOVE
OPT_CALLBACK_ON_SAVE
OPT_HYDRATE_ADHOC_FIELDS
OPT_HYDRATE_FIELDS
OPT_HYDRATE_RELATED_OBJECTS
OPT_LOADER_CLASSES
OPT_ON_SET_STRIPSLASHES
OPT_SETUP
OPT_TABLE_PREFIX
OPT_VALIDATE_ON_SAVE
OPT_VALIDATOR_CLASS
SCHEMA_VERSION
Properties
$_cacheEnabled
$_debug
$_escapeCharClose
$_escapeCharOpen
$_quoteChar
$cacheManager
$cachePath
$config
$driver
$executedQueries
$logLevel
$logTarget
$manager
$map
$package
$packages
$pdo
$queryTime
$services
$startTime
Methods
__construct
_getFullTableName
_getLogLevel
_loadClass
_log
addDerivativeCriteria
addPackage
beginTransaction
call
commit
connect
errorCode
errorInfo
escSplit
escape
exec
fromCache
fromJSON
getAggregates
getAncestry
getAttribute
getCacheManager
getCachePath
getCollection
getCollectionGraph
getComposites
getCount
getCriteria
getCriteriaType
getDebug
getDebugBacktrace
getDriver
getFKDefinition
getFieldMeta
getFields
getIndexMeta
getIterator
getLogLevel
getLogTarget
getManager
getMicroTime
getModelVersion
getObject
getObjectGraph
getObjectLoader
getOption
getPDOType
getPK
getPKType
getPackage
getSelectColumns
getService
getTableClass
getTableMeta
getTableName
getValidationRules
getValue
lastInsertId
literal
loadClass
log
newObject
newQuery
parseBindings
parseDSN
prepare
query
quote
removeCollection
removeObject
rollBack
setAttribute
setDebug
setLogLevel
setLogTarget
setOption
setPackage
toCache
toJSON

Description

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.

Constants

OPT_AUTO_CREATE_TABLES

 OPT_AUTO_CREATE_TABLES = 'auto_create_tables'

Details

value
auto_create_tables

OPT_BASE_CLASSES

 OPT_BASE_CLASSES = 'base_classes'

Details

value
base_classes

OPT_BASE_PACKAGES

 OPT_BASE_PACKAGES = 'base_packages'

Details

value
base_packages

OPT_CACHE_COMPRESS

 OPT_CACHE_COMPRESS = 'cache_compress'

Details

value
cache_compress

OPT_CACHE_DB

 OPT_CACHE_DB = 'cache_db'

Details

value
cache_db

OPT_CACHE_DB_COLLECTIONS

 OPT_CACHE_DB_COLLECTIONS = 'cache_db_collections'

Details

value
cache_db_collections

OPT_CACHE_DB_OBJECTS_BY_PK

 OPT_CACHE_DB_OBJECTS_BY_PK = 'cache_db_objects_by_pk'

Details

value
cache_db_objects_by_pk

OPT_CACHE_DB_EXPIRES

 OPT_CACHE_DB_EXPIRES = 'cache_db_expires'

Details

value
cache_db_expires

OPT_CACHE_DB_HANDLER

 OPT_CACHE_DB_HANDLER = 'cache_db_handler'

Details

value
cache_db_handler

OPT_CACHE_EXPIRES

 OPT_CACHE_EXPIRES = 'cache_expires'

Details

value
cache_expires

OPT_CACHE_FORMAT

 OPT_CACHE_FORMAT = 'cache_format'

Details

value
cache_format

OPT_CACHE_HANDLER

 OPT_CACHE_HANDLER = 'cache_handler'

Details

value
cache_handler

OPT_CACHE_KEY

 OPT_CACHE_KEY = 'cache_key'

Details

value
cache_key

OPT_CACHE_PATH

 OPT_CACHE_PATH = 'cache_path'

Details

value
cache_path

OPT_CACHE_ATTEMPTS

 OPT_CACHE_ATTEMPTS = 'cache_attempts'

Details

value
cache_attempts

OPT_CACHE_ATTEMPT_DELAY

 OPT_CACHE_ATTEMPT_DELAY = 'cache_attempt_delay'

Details

value
cache_attempt_delay

OPT_CALLBACK_ON_REMOVE

 OPT_CALLBACK_ON_REMOVE = 'callback_on_remove'

Details

value
callback_on_remove

OPT_CALLBACK_ON_SAVE

 OPT_CALLBACK_ON_SAVE = 'callback_on_save'

Details

value
callback_on_save

OPT_HYDRATE_FIELDS

 OPT_HYDRATE_FIELDS = 'hydrate_fields'

Details

value
hydrate_fields

OPT_HYDRATE_ADHOC_FIELDS

 OPT_HYDRATE_ADHOC_FIELDS = 'hydrate_adhoc_fields'

Details

value
hydrate_adhoc_fields

OPT_HYDRATE_RELATED_OBJECTS

 OPT_HYDRATE_RELATED_OBJECTS = 'hydrate_related_objects'

Details

value
hydrate_related_objects

OPT_LOADER_CLASSES

 OPT_LOADER_CLASSES = 'loader_classes'

Details

value
loader_classes
deprecated
see
call()

OPT_ON_SET_STRIPSLASHES

 OPT_ON_SET_STRIPSLASHES = 'on_set_stripslashes'

Details

value
on_set_stripslashes

OPT_SETUP

 OPT_SETUP = 'setup'

Details

value
setup

OPT_TABLE_PREFIX

 OPT_TABLE_PREFIX = 'table_prefix'

Details

value
table_prefix

OPT_VALIDATE_ON_SAVE

 OPT_VALIDATE_ON_SAVE = 'validate_on_save'

Details

value
validate_on_save

OPT_VALIDATOR_CLASS

 OPT_VALIDATOR_CLASS = 'validator_class'

Details

value
validator_class

LOG_LEVEL_FATAL

 LOG_LEVEL_FATAL = '0'

Details

value
0

LOG_LEVEL_ERROR

 LOG_LEVEL_ERROR = '1'

Details

value
1

LOG_LEVEL_WARN

 LOG_LEVEL_WARN = '2'

Details

value
2

LOG_LEVEL_INFO

 LOG_LEVEL_INFO = '3'

Details

value
3

LOG_LEVEL_DEBUG

 LOG_LEVEL_DEBUG = '4'

Details

value
4

SCHEMA_VERSION

 SCHEMA_VERSION = '1.1'

Details

value
1.1

Properties

$_cacheEnabledAll caching is disabled by default.

boolean $_cacheEnabled = 'false'

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

Details

boolean
All caching is disabled by default.
visibility
public
default
false
final
false
static
false
access
public

$_debugDefault is false.

boolean $_debug = 'false'

Indicates the debug state of this instance.

Details

boolean
Default is false.
visibility
protected
default
false
final
false
static
false
access
protected

$_escapeCharClose

string $_escapeCharClose = ''

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

Details

string
visibility
public
default
final
false
static
false
access
public

$_escapeCharOpen

string $_escapeCharOpen = ''

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

Details

string
visibility
public
default
final
false
static
false
access
public

$_quoteChar

string $_quoteChar = ''

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

Details

string
visibility
public
default
final
false
static
false

$cacheManagerThe cache service provider registered for this xPDO instance.

\xPDOCacheManager $cacheManager = 'null'

Details

\xPDOCacheManager
The cache service provider registered for this xPDO instance.
visibility
public
default
null
final
false
static
false

$cachePathA root path for file-based caching services to use.

string $cachePath = 'null'

Details

string
A root path for file-based caching services to use.
visibility
private
default
null
final
false
static
false

$config

array $config = 'null'

A array of xPDO configuration attributes.

Details

array
visibility
public
default
null
final
false
static
false
access
public

$driver

\xPDODriver $driver = 'null'

An xPDODriver instance for the connection.

Details

\xPDODriver
visibility
public
default
null
final
false
static
false
access
public

$executedQueriesThe number of direct DB queries executed during a request.

int $executedQueries = '0'

Details

int
The number of direct DB queries executed during a request.
visibility
public
default
0
final
false
static
false

$logLevelThe logging level for the XPDO instance.

integer $logLevel = 'xPDO'

Details

integer
The logging level for the XPDO instance.
visibility
protected
default
xPDO
final
false
static
false

$logTargetThe default logging target for the XPDO instance.

string $logTarget = 'ECHO'

Details

string
The default logging target for the XPDO instance.
visibility
protected
default
ECHO
final
false
static
false

$manager

\xPDOManager $manager = 'null'

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

Details

\xPDOManager
visibility
public
default
null
final
false
static
false
access
public

$map

array $map = 'array'

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

Details

array
visibility
public
default
array
final
false
static
false
access
public

$package

string $package = ''

A default package for specifying classes by name.

Details

string
visibility
public
default
final
false
static
false
access
public

$packages

array $packages = 'array'

An array storing packages and package-specific information.

Details

array
visibility
public
default
array
final
false
static
false
access
public

$pdo

\PDO $pdo = 'null'

A PDO instance used by xPDO for database access.

Details

\PDO
visibility
public
default
null
final
false
static
false
access
public

$queryTimeThe amount of request handling time spent with DB queries.

int $queryTime = '0'

Details

int
The amount of request handling time spent with DB queries.
visibility
public
default
0
final
false
static
false

$servicesAn array of supplemental service classes for this xPDO instance.

array $services = 'array'

Details

array
An array of supplemental service classes for this xPDO instance.
visibility
public
default
array
final
false
static
false

$startTimeStart time of the request, initialized when the constructor is called.

float $startTime = '0'

Details

float
Start time of the request, initialized when the constructor is called.
visibility
public
default
0
final
false
static
false

Methods

__construct

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

The xPDO Constructor.

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

Arguments
$dsn
mixed
A valid DSN connection string.
$username
string
The database username with proper permissions.
$password
string
The password for the database user.
$options
arraystring
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
mixed
Driver-specific PDO options.
Output
\xPDO
A unique xPDO instance.
Details
visibility
public
final
false
static
false

_getFullTableName

_getFullTableName( string $baseTableName, boolean $includeDb = false ) : string

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

Arguments
$baseTableName
string
The table name as specified in the object model.
$includeDb
boolean
Qualify the table name with the database name.
Output
string
The fully-qualified and quoted table name for the
Details
visibility
private
final
false
static
false

_getLogLevel

_getLogLevel( integer $level ) : string

Gets a logging level as a string representation.

Arguments
$level
integer
The logging level to retrieve a string for.
Output
string
The string representation of a valid logging level.
Details
visibility
protected
final
false
static
false

_loadClass

_loadClass(  $class,  $fqn,  $included = false,  $path,  $transient = false ) :
Arguments
$class
$fqn
$included
$path
$transient
Details
visibility
protected
final
false
static
false

_log

_log( integer $level, string $msg, string $target, string $def, string $file, string $line ) :

Log a message as appropriate for the level and target.

Arguments
$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.
Details
visibility
protected
final
false
static
false

addDerivativeCriteria

addDerivativeCriteria( string $className, \xPDOCriteria $criteria ) :

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.

Arguments
$className
string
A valid xPDOObject derivative table class.
$criteria
\xPDOCriteria
A valid xPDOCriteria instance.
Details
visibility
public
final
false
static
false

addPackage

addPackage( string $pkg, string $path, string|null $prefix = null ) :

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

Arguments
$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
stringnull
Provide a string to define a package-specific table_prefix.
Details
visibility
public
final
false
static
false

beginTransaction

beginTransaction( ) :

Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-begintransaction.php

call

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.

Arguments
$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.
Output
mixed|null
The callback method's return value or null if no valid method is found.
Details
visibility
public
final
false
static
false

commit

commit( ) :

Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-commit.php

connect

connect( array $driverOptions = array ) : boolean

Create the PDO connection to a database specified in the configuration.

Arguments
$driverOptions
array
An optional array of driver options to use when creating the connection.
Output
boolean
Returns true if the PDO connection was created successfully.
Details
visibility
public
final
false
static
false

errorCode

errorCode( ) :

Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-errorcode.php

errorInfo

errorInfo( ) :

Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-errorinfo.php

escSplit

escSplit( string $char, string $str, string $escToken = `, integer $limit = 0 ) : array

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

Arguments
$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.
Output
array
An array of results from the split operation, or an empty array.
Details
visibility
public
final
false
static
true
static

escape

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.

Arguments
$string
string
A string to escape using the platform-specific escape characters.
Output
string
The string escaped with the platform-specific escape characters.
Details
visibility
public
final
false
static
false

exec

exec(  $query ) :

Arguments
$query
Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-exec.php

fromCache

fromCache( string|\xPDOCriteria $signature, string $class, array $options = array ) : array|string|null

Retrieves a result array from the object cache.

Arguments
$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.
Output
array|string|null
A PHP array or JSON object representing the result set, or null if no cache representation is found.
Details
visibility
public
final
false
static
false

fromJSON

fromJSON( string $src, boolean $asArray = true ) : mixed

Converts a JSON source string into an equivalent PHP representation.

Arguments
$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.
Output
mixed
The PHP representation of the JSON source.
Details
visibility
public
final
false
static
false

getAggregates

getAggregates( string $className ) : array

Gets a collection of aggregate foreign key relationship definitions.

Arguments
$className
string
The fully-qualified name of the class.
Output
array
An array of aggregate foreign key relationship definitions.
Details
visibility
public
final
false
static
false

getAncestry

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

Retrieves the complete ancestry for a class.

Arguments
$className
string
className The name of the class.
$includeSelf
boolean
includeSelf Determines if the specified class should be included in the resulting array.
Output
array
An array of string class names representing the class hierarchy, or an empty array if unsuccessful.
Details
visibility
public
final
false
static
false

getAttribute

getAttribute(  $attribute ) :

Arguments
$attribute
Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-getattribute.php

getCacheManager

getCacheManager( string $class = cache.xPDOCacheManager,  $options = array ) : object

Gets the xPDOCacheManager instance.

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

Arguments
$class
string
Optional name of a derivative xPDOCacheManager class.
$options
Output
object
The xPDOCacheManager for this xPDO instance.
Details
visibility
public
final
false
static
false
uses
xPDOCacheManager

getCachePath

getCachePath( ) : string

Gets the absolute path to the cache directory.

Output
string
The full cache directory path.
Details
visibility
public
final
false
static
false

getCollection

getCollection( string $className, object|array|string $criteria = null, mixed $cacheFlag = true ) : array|null

Retrieves a collection of xPDOObjects by the specified xPDOCriteria.

Arguments
$className
string
Name of the class to search for instances of.
$criteria
objectarraystring
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.
Output
array|null
An array of class instances retrieved.
Details
visibility
public
final
false
static
false
uses
xPDOObject::loadCollection()

getCollectionGraph

getCollectionGraph( string $className, string|array $graph, mixed $criteria = null, boolean $cacheFlag = true ) : array

Retrieves a collection of xPDOObject instances with related objects.

Arguments
$className
string
The name of the class to return a collection of.
$graph
stringarray
A related object graph in array or JSON format, e.g. array(&#039;relationAlias&#039;=&gt;array(&#039;subRelationAlias&#039;=&gt;array())) or {&quot;relationAlias&quot;:{&quot;subRelationAlias&quot;:{}}}. 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.
Output
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
visibility
public
final
false
static
false
uses
xPDOQuery::bindGraph()

getComposites

getComposites( string $className ) : array

Gets a collection of composite foreign key relationship definitions.

Arguments
$className
string
The fully-qualified name of the class.
Output
array
An array of composite foreign key relationship definitions.
Details
visibility
public
final
false
static
false

getCount

getCount( string $className, mixed $criteria = null ) : integer

Retrieves a count of xPDOObjects by the specified xPDOCriteria.

Arguments
$className
string
Class of xPDOObject to count instances of.
$criteria
mixed
Any valid xPDOCriteria object or expression.
Output
integer
The number of instances found by the criteria.
Details
visibility
public
final
false
static
false

getCriteria

getCriteria( string $className, string $type = null, boolean|integer $cacheFlag = true ) : \xPDOCriteria

Convert any valid criteria into an xPDOQuery instance.

Arguments
$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 &#039;object&#039; and &#039;collection&#039; are the typical criteria for retrieving single and multiple instances of an object).
$cacheFlag
booleaninteger
Indicates if the result is cached and optionally for how many seconds.
Output
\xPDOCriteria
A criteria object or null if not found.
Details
visibility
public
final
false
static
false
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

getCriteriaType( mixed $criteria ) : string|null

Validate and return the type of a specified criteria variable.

Arguments
$criteria
mixed
An xPDOCriteria instance or any valid criteria variable.
Output
string|null
The type of valid criteria passed, or null if the criteria is not valid.
Details
visibility
public
final
false
static
false

getDebug

getDebug( ) : boolean

Returns the debug state for the XPDO connection.

Output
boolean
The current debug state for the connection, true for on, false for off.
Details
visibility
public
final
false
static
false

getDebugBacktrace

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.

Output
array
The abbreviated backtrace.
Details
visibility
public
final
false
static
false

getDriver

getDriver( ) : object|null

Gets the driver class for this xPDO connection.

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

Output
object|null
A driver instance for the xPDO connection, or null if a driver class can not be instantiated.
Details
visibility
public
final
false
static
false
uses
xPDODriver

getFKDefinition

getFKDefinition( string $parentClass, string $alias ) : array

Gets an aggregate or composite relation definition from a class.

Arguments
$parentClass
string
The class from which the relation is defined.
$alias
string
The alias identifying the related class.
Output
array
The aggregate or composite definition details in an array or null if no definition is found.
Details
visibility
public
final
false
static
false

getFieldMeta

getFieldMeta( string $className ) : 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 inheritence.

Arguments
$className
string
The name of the class to lookup fields meta data for.
Output
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.
Details
visibility
public
final
false
static
false

getFields

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.

Arguments
$className
string
The name of the class to lookup fields for.
Output
array
An array featuring field names as the array keys, and default field values as the array values; empty array is returned if unsuccessful.
Details
visibility
public
final
false
static
false

getIndexMeta

getIndexMeta( string $className ) : array

Get indices defined for a table class.

Arguments
$className
string
The name of the class to lookup indices for.
Output
array
An array of indices and their details for the specified class.
Details
visibility
public
final
false
static
false

getIterator

getIterator( string $className, mixed $criteria = null, bool $cacheFlag = true ) : \xPDOIterator

Retreives an iterable representation of a collection of xPDOObjects.

Arguments
$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.
Output
\xPDOIterator
An iterable representation of a collection.
Details
visibility
public
final
false
static
false

getLogLevel

getLogLevel( ) : integer

Output
integer
The current log level.
Details
visibility
public
final
false
static
false

getLogTarget

getLogTarget( ) : integer

Output
integer
The current log level.
Details
visibility
public
final
false
static
false

getManager

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

Output
object|null
A manager instance for the xPDO connection, or null if a manager class can not be instantiated.
Details
visibility
public
final
false
static
false
uses
xPDOManager

getMicroTime

getMicroTime( ) : float

Convert current microtime() result into seconds.

Output
float
Details
visibility
public
final
false
static
false

getModelVersion

getModelVersion( string $className ) : string

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

Arguments
$className
string
The name of the class to get the model version from.
Output
string
The version string for the schema model the class was generated from.
Details
visibility
public
final
false
static
false

getObject

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.

Arguments
$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.
Output
object|null
An instance of the class, or null if it could not be instantiated.
Details
visibility
public
final
false
static
false
uses
xPDOObject::load()

getObjectGraph

getObjectGraph( string $className, string|array $graph, mixed $criteria = null, boolean|integer $cacheFlag = true ) : object

Retrieves an xPDOObject instance with specified related objects.

Arguments
$className
string
The name of the class to return an instance of.
$graph
stringarray
A related object graph in array or JSON format, e.g. array(&#039;relationAlias&#039;=&gt;array(&#039;subRelationAlias&#039;=&gt;array())) or {&quot;relationAlias&quot;:{&quot;subRelationAlias&quot;:{}}}. Note that the empty arrays are necessary in order for the relation to be recognized.
$criteria
mixed
A valid xPDOCriteria instance or expression.
$cacheFlag
booleaninteger
Indicates if the result set should be cached, and optionally for how many seconds.
Output
object
The object instance with related objects from the graph hydrated, or null if no instance can be located by the criteria.
Details
visibility
public
final
false
static
false
uses
xPDO::getCollectionGraph()

getObjectLoader

getObjectLoader( string $className, string $method ) : \callable

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

Arguments
$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).
Output
\callable
A callable loader function.
Details
visibility
public
final
false
static
false
deprecated
Use call() instead.

getOption

getOption( string $key, array $options = null, mixed $default = null ) : mixed

Get an xPDO configuration option value by key.

Arguments
$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.
Output
mixed
The configuration option value.
Details
visibility
public
final
false
static
false

getPDOType

getPDOType( mixed $value ) : int|null

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

Arguments
$value
mixed
Any PHP scalar or null value
Output
int|null
Details
visibility
public
final
false
static
false

getPK

getPK( string $className ) : mixed

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

Arguments
$className
string
The name of the class to lookup the primary key for.
Output
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.
Details
visibility
public
final
false
static
false

getPKType

getPKType( string $className,  $pk = false ) : string

Gets the type of primary key field for a class.

Arguments
$className
string
className The name of the class to lookup the primary key type for.
$pk
Output
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
visibility
public
final
false
static
false
todo
Refactor method to return array of types rather than compound!

getPackage

getPackage( string $className ) : string

Gets the package name from a specified class name.

Arguments
$className
string
The name of the class to lookup the package for.
Output
string
The package the class belongs to.
Details
visibility
public
final
false
static
false

getSelectColumns

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.

Arguments
$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.
Output
string
A valid SQL string of column names for a SELECT statement.
Details
visibility
public
final
false
static
false
uses
xPDOObject::getSelectColumns()

getService

getService( string $name, string $class, string $path, array $params = array ) : object

Load and return a named service class instance.

Arguments
$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.
Output
object
The service class instance or null if it could not be loaded.
Details
visibility
public
final
false
static
false

getTableClass

getTableClass( string $className ) : null|string

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

Arguments
$className
string
The name of a class to determine the table class from.
Output
null|string
The name of a class defining the table for the specified className; null if not found.
Details
visibility
public
final
false
static
false

getTableMeta

getTableMeta( string $className ) : string

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

Arguments
$className
string
The name of the class to lookup a table name for.
Output
string
The table meta data for the class, or null if unsuccessful.
Details
visibility
public
final
false
static
false

getTableName

getTableName( string $className, boolean $includeDb = false ) : string

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

Arguments
$className
string
The name of the class to lookup a table name for.
$includeDb
boolean
Qualify the table name with the database name.
Output
string
The table name for the class, or null if unsuccessful.
Details
visibility
public
final
false
static
false

getValidationRules

getValidationRules( string $className ) : array

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

Arguments
$className
string
The name of the class to lookup validation rules for.
Output
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.
Details
visibility
public
final
false
static
false

getValue

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.

Arguments
$stmt
\PDOStatement
A prepared PDOStatement object ready to be executed.
$column
nullinteger
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.
Output
mixed
The value of the specified column from the first row of the result set, or null.
Details
visibility
public
final
false
static
false

lastInsertId

lastInsertId( ) :

Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-lastinsertid.php

literal

literal( string $string ) : string

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

Arguments
$string
string
A string to return as a literal, unescaped and unquoted.
Output
string
The string with any escape or quote characters trimmed.
Details
visibility
public
final
false
static
false

loadClass

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

Arguments
$fqn
string
The fully-qualified name of the class to load.
$path
$ignorePkg
$transient
Output
string|boolean
The actual classname if successful, or false if not.
Details
visibility
public
final
false
static
false

log

log( integer $level, string $msg, string $target, string $def, string $file, string $line ) :

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

Arguments
$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.
Details
visibility
public
final
false
static
false

newObject

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.

Arguments
$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.
Output
object|null
A new instance of the specified class, or null if a new object could not be instantiated.
Details
visibility
public
final
false
static
false

newQuery

newQuery( string $class, mixed $criteria = null, boolean|integer $cacheFlag = true ) : \xPDOQuery

Creates an new xPDOQuery for a specified xPDOObject class.

Arguments
$class
string
The class to create the xPDOQuery for.
$criteria
mixed
Any valid xPDO criteria expression.
$cacheFlag
booleaninteger
Indicates if the result should be cached and optionally for how many seconds (if passed an integer greater than 0).
Output
\xPDOQuery
The resulting xPDOQuery instance or false if unsuccessful.
Details
visibility
public
final
false
static
false

parseBindings

parseBindings( string $sql, array $bindings ) : string

Parses parameter bindings in SQL prepared statements.

Arguments
$sql
string
A SQL prepared statement to parse bindings in.
$bindings
array
An array of parameter bindings to use for the replacements.
Output
string
The SQL with the binding placeholders replaced.
Details
visibility
public
final
false
static
false

parseDSN

parseDSN( string $string ) : array

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

Arguments
$string
string
The DSN to parse.
Output
array
An array of connection details from the DSN.
Details
visibility
public
final
false
static
true
static
todo
Have this method handle all methods of DSN specification as handled by latest native PDO implementation.

prepare

prepare(  $statement,  $driver_options = array ) :

Arguments
$statement
$driver_options
Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-prepare.php

query

query(  $query ) :

Arguments
$query
Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-query.php

quote

quote(  $string,  $parameter_type = PDO ) :

Arguments
$string
$parameter_type
Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-quote.php

removeCollection

removeCollection( string $className, mixed $criteria ) : boolean|integer

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

Arguments
$className
string
The name of the class to remove a collection of.
$criteria
mixed
Valid xPDO criteria for selecting a collection.
Output
boolean|integer
False if the remove encounters an error, otherwise an integer value representing the number of rows that were removed.
Details
visibility
public
final
false
static
false

removeObject

removeObject( string $className, mixed $criteria ) : boolean

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

Arguments
$className
string
The name of the class to remove an instance of.
$criteria
mixed
Valid xPDO criteria for selecting an instance.
Output
boolean
True if the instance is successfully removed.
Details
visibility
public
final
false
static
false

rollBack

rollBack( ) :

Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-rollback.php

setAttribute

setAttribute(  $attribute,  $value ) :

Arguments
$attribute
$value
Details
visibility
public
final
false
static
false
see
http://php.net/manual/en/function.pdo-setattribute.php

setDebug

setDebug( boolean $v = true ) :

Sets the debug state for the XPDO connection.

Arguments
$v
boolean
The debug status, true for on, false for off.
Details
visibility
public
final
false
static
false

setLogLevel

setLogLevel( integer $level = xPDO ) : integer

Sets the logging level state for the XPDO instance.

Arguments
$level
integer
The logging level to switch to.
Output
integer
The previous log level.
Details
visibility
public
final
false
static
false

setLogTarget

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'
Arguments
$target
string
An identifier indicating the target of the logging.
Output
mixed
The previous log target.
Details
visibility
public
final
false
static
false

setOption

setOption( string $key, mixed $value ) :

Sets an xPDO configuration option value.

Arguments
$key
string
The option key.
$value
mixed
A value to set for the given option key.
Details
visibility
public
final
false
static
false

setPackage

setPackage( string $pkg, string $path, string|null $prefix = null ) :

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.

Arguments
$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
stringnull
Provide a string to define a package-specific table_prefix.
Details
visibility
public
final
false
static
false

toCache

toCache( string|\xPDOCriteria $signature, object $object, integer $lifetime = 0, array $options = array ) : boolean

Places a result set in the object cache.

Arguments
$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.
Output
boolean
Indicates if the object was successfully cached.
Details
visibility
public
final
false
static
false

toJSON

toJSON( array $array ) : string

Converts a PHP array into a JSON encoded string.

Arguments
$array
array
The PHP array to convert.
Output
string
The JSON representation of the source array.
Details
visibility
public
final
false
static
false

\xPDOCriteria

package
xpdo
Properties
$bindings
$cacheFlag
$sql
$stmt
Methods
__construct
bind
equals
prepare
toSQL

Description

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

Properties

$bindings

 $bindings = 'array'

Details

visibility
public
default
array
final
false
static
false

$cacheFlag

 $cacheFlag = 'false'

Details

visibility
public
default
false
final
false
static
false

$sql

 $sql = ''

Details

visibility
public
default
final
false
static
false

$stmt

 $stmt = 'null'

Details

visibility
public
default
null
final
false
static
false

Methods

__construct

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

Arguments
$xpdo
\xPDO
&amp;$xpdo An xPDO instance that will control this criteria.
$sql
string
The SQL statement.
$bindings
array
Bindings to bind to the criteria.
$cacheFlag
booleaninteger
Indicates if the result set from the criteria is to be cached (true|false) or optionally a TTL in seconds.
Output
\xPDOCriteria
Details
visibility
public
final
false
static
false

bind

bind( array $bindings = array, boolean $byValue = true, boolean|integer $cacheFlag = false ) :

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.

Arguments
$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
booleaninteger
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.
Details
visibility
public
final
false
static
false

equals

equals( object $obj ) : boolean

Compares to see if two xPDOCriteria instances are the same.

Arguments
$obj
object
A xPDOCriteria object to compare to this one.
Output
boolean
true if they are both equal is SQL and bindings, otherwise false.
Details
visibility
public
final
false
static
false

prepare

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.

Arguments
$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
booleaninteger
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.
Output
\PDOStatement
The prepared statement, ready to execute.
Details
visibility
public
final
false
static
false

toSQL

toSQL( ) : string

Converts the current xPDOQuery to parsed SQL.

Output
string
The parsed SQL query.
Details
visibility
public
final
false
static
false
access
public

\xPDOIterator

Implements
package
xpdo
Properties
$alias
$cacheFlag
$class
$criteria
$criteriaType
$current
$index
$stmt
$xpdo
Methods
__construct
current
fetch
key
next
rewind
valid

Description

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.

Properties

$alias

 $alias = 'null'

Details

visibility
private
default
null
final
false
static
false

$cacheFlag

 $cacheFlag = 'false'

Details

visibility
private
default
false
final
false
static
false

$class

 $class = 'null'

Details

visibility
private
default
null
final
false
static
false

$criteria

 $criteria = 'null'

Details

visibility
private
default
null
final
false
static
false

$criteriaType

 $criteriaType = 'xPDOQuery'

Details

visibility
private
default
xPDOQuery
final
false
static
false

$current

 $current = 'null'

Details

visibility
private
default
null
final
false
static
false

$index

 $index = '0'

Details

visibility
private
default
0
final
false
static
false

$stmt

 $stmt = 'null'

Details

visibility
private
default
null
final
false
static
false

$xpdo

 $xpdo = 'null'

Details

visibility
private
default
null
final
false
static
false

Methods

__construct

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

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

Arguments
$xpdo
\xPDO
&amp;$xpdo A reference to a valid xPDO instance.
$options
array
An array of options for the iterator.
Output
\xPDOIterator
An xPDOIterator instance.
Details
visibility
public
final
false
static
false
see
xPDO::getIterator()

current

current( ) :
Details
visibility
public
final
false
static
false

fetch

fetch( ) :

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.

Details
visibility
protected
final
false
static
false

key

key( ) :
Details
visibility
public
final
false
static
false

next

next( ) :
Details
visibility
public
final
false
static
false

rewind

rewind( ) :
Details
visibility
public
final
false
static
false

valid

valid( ) :
Details
visibility
public
final
false
static
false
Documentation was generated by DocBlox 0.11.2.