Jump to main content Jump to doc navigation

When 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)


As you can see, there are 5 parameters available in the constructor; the only necessary one is the first:


This parameter asks you for your DSN value, which is formatted like so:


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.


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, any xPDOCache 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 an xPDOCache 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 using xPDOFileCache; 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 attempts xPDOFileCache 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.


An optional array of driver-specific PDO options. More info can be found here.

See Also

More information about options

  1. Hydrating Fields

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.



$0 per month—let's make that $500!

Learn more