Creating xPDO Instance
Last updated Mar 11th, 2021 | Page history | Improve this page | Report an issue
Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
Backers
Budget
$301 per month—let's make that $500!
Learn moreWhen using xPDO within MODX, the modX
class (typically available as $modx
or $this->modx
) is an instance of xPDO so you do not need to create a separate instance.
When using xPDO standalone, or if you want to create additional instances, use the information on this page.
The constructor has the following signature:
$xpdo= new xPDO($dsn, $username= '', $password= '', $options= array(), $driverOptions= null)
Parameters¶
As you can see, there are 5 parameters available in the constructor; the only necessary one is the first:
$dsn¶
This parameter asks you for your DSN value, which is formatted like so:
mysql:host=MYHOSTNAME;dbname=MYDBNAME;charset=MYCHARSET
You'll simply have to change the values of the hostname, database name, and charset to set up the parameter. More info can be found at PHP.net's PDO page.
$username and $password¶
This is the username and password to the database. Simply specify the database login information you'd like to use for xPDO's connections.
$options¶
This allows you to pass an array of xPDO-specific options into the constructor.
Some of the xPDO-specific parameters use custom defines that you can use, such as (but not limited to):
-
xPDO::OPT_BASE_CLASSES
— An array of classes to load upon instantiation. -
xPDO::OPT_BASE_PACKAGES
— A comma-separated string of package names/paths (separated by a colon) to be loaded upon instantiation. -
xPDO::OPT_CACHE_COMPRESS
— If set, anyxPDOCache
instances using providers that support compressing data will use that option by default. -
xPDO::OPT_CACHE_DB
— If set, database result set caching will be enabled. -
xPDO::OPT_CACHE_DB_COLLECTIONS
— If set, database result set caching will attempt to cache entire collections. -
xPDO::OPT_CACHE_DB_OBJECTS_BY_PK
— If set, database result set caching will create cache entries by primary key in addition to the query signature used. -
xPDO::OPT_CACHE_DB_EXPIRES
— If set, defines the number of seconds a database result set cache entry is valid in the cache; 0 means it does not expire. -
xPDO::OPT_CACHE_DB_HANDLER
— If set, defines anxPDOCache
derivative to handle database result set caching. -
xPDO::OPT_CACHE_EXPIRES
— If set, defines the number of seconds a cache entry is valid in any cache provider by default; 0 means it does not expire. -
xPDO::OPT_CACHE_FORMAT
— If set, defines the format cache files are stored in when usingxPDOFileCache
; the default is PHP, but JSON and serialized are available. (2.1 only) -
xPDO::OPT_CACHE_KEY
— If set, defines the key of the default cache instance; the default value is default. -
xPDO::OPT_CACHE_PATH
— If set, will set a custom cachePath class variable to the xPDO object that can be used in caching. -
xPDO::OPT_CACHE_ATTEMPTS
— If set, defines the number attemptsxPDOFileCache
will attempt to lock an existing cache entry for writing; default is 1. (2.1 only) -
xPDO::OPT_CACHE_ATTEMPT_DELAY
— If set, defines the number microseconds to delay each attempt to lock existing cache entries for writing; default is 10000. (2.1 only) -
xPDO::OPT_CONNECTIONS
— Optionally defines a pool of additional connections to select from when instantiating xPDO. (2.2 only) -
xPDO::OPT_CONN_INIT
— Defines options a connection must have to be selected as the initial connection; applicable when multiple connections are defined. (2.2 only) -
xPDO::OPT_CONN_MUTABLE
— Defines if data from a connection can be changed, i.e. is writable. (2.2 only) -
xPDO::OPT_HYDRATE_FIELDS
— If true, fields will be hydrated. -
xPDO::OPT_HYDRATE_RELATED_OBJECTS
— If true, related objects will be hydrated. -
xPDO::OPT_HYDRATE_ADHOC_FIELDS
— If true, ad-hoc fields will be hydrated. -
xPDO::OPT_LOADER_CLASSES
— Can be an array of class names to load upon instantiation of the xPDO object. (deprecated in 2.0.0-pl) -
xPDO::OPT_ON_SET_STRIPSLASHES
— If set, stripslashes() is applied to values being set() on xPDOObject instances. -
xPDO::OPT_TABLE_PREFIX
— If set, all database class references will be prefixed with this prefix. -
xPDO::OPT_VALIDATOR_CLASS
— If set, will use a custom class specified that derives from xPDOValidator (the default) -
xPDO::OPT_VALIDATE_ON_SAVE
— If true,xPDOObjects
will be validated against their Validators before saving.
$driverOptions¶
An optional array of driver-specific PDO options. More info can be found here.
See Also¶
- PDO::__construct()
- Caching
- Database Connections and xPDO
- Hydrating Fields
- Object Validation
- Using Custom Object Loaders