1. Overview
      1. What It Is
      2. Why I Would Want to Use It
      3. Known Issues
    2. Getting Started
      1. Fundamentals
        1. Design Patterns
        2. xPDO, the Class
          1. As Object and Relational Mapper
          2. As PDO Wrapper
          3. As Service Layer
          4. The xPDO Constructor
            1. Hydrating Fields
      2. Introduction to the xPDO Object Model
        1. Understanding xPDOCriteria and xPDOQuery
      3. Creating a Model With xPDO
        1. Defining a Schema
          1. Defining Relationships
          2. Defining the Database and Tables
            1. Upgrading Models to Schema Version 1.1
          3. More Examples of xPDO XML Schema Files
          4. Validation Rules in your Schema
        2. Generating the Model Code
          1. Domain Classes
          2. O-R Maps
          3. Table Classes
      4. Using Your xPDO Model
        1. Creating Objects
        2. Database Connections and xPDO
        3. Loading Packages
        4. Removing Objects
          1. removeCollection
        5. Retrieving Objects
          1. getCollectionGraph
        6. Setting Object Fields
        7. Working with Related Objects
    3. Extending Your xPDO Model
      1. Overriding Derived Behavior
        1. Using Custom Object Loaders
      2. Working With Transient Object Classes
    4. Advanced Features
      1. Caching
        1. Caching Tutorial - Basic Snippets
        2. Caching Tutorial - Lifetimes
      2. Object Validation
        1. xPDOForeignKeyConstraint
        2. xPDOMaxLengthValidationRule
        3. xPDOMaxValueValidationRule
        4. xPDOMinLengthValidationRule
        5. xPDOMinValueValidationRule
        6. xPDOObjectExistsValidationRule
    5. xPDO Development
      1. Testing
      2. Building
      3. Documentation and Tutorials
    6. Class Reference
      1. xPDO
        1. xPDO.addPackage
        2. xPDO.beginTransaction
        3. xPDO.commit
        4. xPDO.connect
        5. xPDO.fromJSON
        6. xPDO.getCollection
        7. xPDO.getCollectionGraph
        8. xPDO.getCount
        9. xPDO.getDebug
        10. xPDO.getFields
        11. xPDO.getIterator
        12. xPDO.getManager
        13. xPDO.getObject
        14. xPDO.getObjectGraph
        15. xPDO.getOption
        16. xPDO.getTableName
        17. xPDO.loadClass
        18. xPDO.log
        19. xPDO.newObject
        20. xPDO.newQuery
        21. xPDO.query
        22. xPDO.setDebug
        23. xPDO.setLogLevel
        24. xPDO.setLogTarget
        25. xPDO.setOption
        26. xPDO.toJSON
      2. xPDOCacheManager
        1. xPDOCacheManager.copyFile
        2. xPDOCacheManager.copyTree
        3. xPDOCacheManager.delete
        4. xPDOCacheManager.deleteTree
        5. xPDOCacheManager.endsWith
        6. xPDOCacheManager.escapeSingleQuotes
        7. xPDOCacheManager.get
        8. xPDOCacheManager.getCachePath
        9. xPDOCacheManager.getCacheProvider
        10. xPDOCacheManager.matches
        11. xPDOCacheManager.replace
        12. xPDOCacheManager.set
        13. xPDOCacheManager.writeFile
        14. xPDOCacheManager.writeTree
      3. xPDOGenerator
        1. xPDOGenerator.parseSchema
        2. xPDOGenerator.writeSchema
      4. xPDOManager
        1. xPDOManager.createObjectContainer
        2. xPDOManager.createSourceContainer
        3. xPDOManager.removeObjectContainer
        4. xPDOManager.removeSourceContainer
      5. xPDOObject
        1. Configuration Accessors
          1. getOption
          2. setOption
        2. Field Accessors
          1. fromArray
          2. fromJSON
          3. get
          4. set
          5. toArray
          6. toJSON
        3. Metadata Accessors
          1. getFieldName
          2. getFKClass
          3. getFKDefinition
          4. getPK
          5. getPKType
          6. getSelectColumns
        4. Persistence Methods
          1. remove
          2. save
        5. Related Object Accessors
          1. addMany
          2. addOne
          3. getMany
          4. getOne
        6. State Accessors
          1. isDirty
          2. isLazy
          3. isNew
        7. Static Object Loaders
          1. _loadCollectionInstance
          2. _loadInstance
          3. _loadRows
          4. load
          5. loadCollection
          6. loadCollectionGraph
          7. Using Custom Loader Classes
        8. Validation
          1. addValidationRule
          2. getValidator
          3. isValidated
          4. removeValidationRules
          5. validate
      6. xPDOQuery
        1. xPDOQuery.andCondition
        2. xPDOQuery.groupby
        3. xPDOQuery.innerJoin
        4. xPDOQuery.leftJoin
        5. xPDOQuery.limit
        6. xPDOQuery.orCondition
        7. xPDOQuery.rightJoin
        8. xPDOQuery.select
        9. xPDOQuery.setClassAlias
        10. xPDOQuery.sortby
        11. xPDOQuery.where
      7. xPDORevisionControl
      8. xPDOTransport
        1. xPDOTransport.install
        2. xPDOTransport.pack
        3. xPDOTransport.uninstall
      9. xPDOValidator
        1. xPDOValidator.addMessage
        2. xPDOValidator.getMessages
        3. xPDOValidator.hasMessages
        4. xPDOValidator.validate

Database Connections and xPDO

Last edited by Mark Hamstra on Sep 18, 2016.

xPDO Database Connections

Database connectivity in xPDO is done in the constructor. The xPDO object can only hold one database connection per instance, but you are free to instantiate as many xPDO instances as you need. The syntax of the constructor is such:

function xPDO($dsn, $username= '', $password= '', $options= array(), $driverOptions= null)

So let's say we want to connect to a localhost database named 'test' on port 3306, with a utf-8 charset:

$dsn = 'mysql:host=localhost;dbname=test;port=3306;charset=utf8';
$xpdo = new xPDO($dsn,'username','password');

And you're done!

Optionally verify the connection, by simply adding the following line afterward

echo $o=($xpdo->connect()) ? 'Connected' : 'Not Connected';
xPDO creates a PDO object, and thus connects to the database, only when a PDO method is called and the connection is needed. This connect-on-demand feature allows xPDO caching to work without a database connection being required (assuming everything is cached).

More information on these parameters can be found on The xPDO Constructor page.

Once you're connected, you'll need to load your package.

Example Connection

Here's an example script that can be used to connect to a foreign database:

<?php

define('MODX_CORE_PATH', '/path/to/revo/core/');
define('MODX_CONFIG_KEY','config');
require_once MODX_CORE_PATH . 'model/modx/modx.class.php';

// Criteria for foreign Database
$host = 'localhost';
$username = 'your_username';
$password = 'your_password';
$dbname = 'your_database';
$port = 3306;
$charset = 'utf8';

$dsn = "mysql:host=$host;dbname=$dbname;port=$port;charset=$charset";
$xpdo = new xPDO($dsn, $username, $password);

// Test your connection
echo $o = ($xpdo->connect()) ? 'Connected' : 'Not Connected';

// Issue queries against the foreign database:
$results = $xpdo->query("SELECT id FROM some_table"); 
$recordCount = $results->rowCount();
print $recordCount;

Defining Multiple Connections (xPDO 2.2+)

xPDO 2.2 introduces the ability to define multiple connections, and includes configuration options for specifying read-only attributes per connection. This allows the use of xPDO with various kinds of master/slave database configurations. The feature is not meant to allow connecting to a specific database node, it is for configuring master/slave configurations where one (or more) nodes are read-only and at least one is writable (aka mutable). In that case you can request the initial connection be read-only and xPDO will automatically switch to a writable connection if a write operation is performed on a database object.

xPDO::OPT_CONNECTIONS

To define additional connections for an xPDO instance, you can pass an array of connection configuration arrays in the $options parameter of the xPDO constructor. Each connection array defines the same parameters as an xPDO constructor call. Here is an example constructor call with multiple read-only connections specified:

$xpdo = new xPDO('mysql:host=127.0.0.1:19570;dbname=xpdotest;charset=utf8', 'username', 'password' array(
    xPDO::OPT_CONN_MUTABLE => true,
    xPDO::OPT_CONN_INIT => array(xPDO::OPT_CONN_MUTABLE => false),
    xPDO::OPT_CONNECTIONS => array(
            array(
                'dsn' => 'mysql:host=127.0.0.1:19571;dbname=xpdotest;charset=utf8',
                'username' => 'username',
                'password' => 'password',
                'options' => array(
                    xPDO::OPT_CONN_MUTABLE => false,
                ),
                'driverOptions' => array(),
            ),
            array(
                'dsn' => 'mysql:host=127.0.0.1:19572;dbname=xpdotest;charset=utf8',
                'username' => 'username',
                'password' => 'password',
                'options' => array(
                    xPDO::OPT_CONN_MUTABLE => false,
                ),
                'driverOptions' => array(),
            ),
        ),
));

xPDO::OPT_CONN_MUTABLE

This option defines the mutability of a defined connection, i.e. is it a read-only connection or can we write to it. It can be specified in the $options array of the constructor as well as in the options for each additional connection.

xPDO::OPT_CONN_INIT

This option defines criteria that a connection must meet to be considered for use as the initial connection created by xPDO. In master/slave configurations, a typical value for this option (which is specified only once in the main configuration options) would indicate to initialize a read-only or immutable connection.

xPDO::OPT_CONN_INIT => array(xPDO::_OPT_CONN_MUTABLE => false)

This makes sure that xPDO selects a connection with that option set to false to start with. If a write operation is performed within xPDO after a read-only connection is initialized, a new mutable connection will be selected and cached for reuse by other write operations within the same execution cycle.

See Also

The xPDO Constructor
PDO::__construct()

Comment Policy

These comments are not for usage questions or support. See below for support options.

Comments intended add specific value for other users with this document are welcome! Have a suggestion to improve this document? Suggest an edit (requires GitHub account). Have suggestions for code changes or feature requests? Submit to the xPDO project at GitHub..

Support Options

If you need assistance, you can get it via the MODX Forums or the MODX Community Slack.

Suggest an edit to this page on GitHub (Requires GitHub account. Opens a new window/tab) or become an editor of the MODX Documentation.