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

Working with Related Objects

Related objects in xPDO can be accessed via newQuery, as shown earlier, or through xPDOObject's helper functions, getOne and getMany (depending on the relationship.

Retrieving Objects

First off, let's look at the related object retrieval methods:

getOne

Let's say we have a Car object, that has an Owner related object. Each Car can have only one Owner, which is a table with ID, name, and email. We want to grab the Owner, given that we have the Car object:

$car = $xpdo->getObject('Car',123);

$owner = $car->getOne('Owner');
echo 'The owner of this car is: '.$owner->get('name');

getOne also takes a $criteria and $cacheFlag parameter, similar to getObject and getCollection. This allows you to do a bit more filtering should you so desire.

getMany

Now say we have Wheel objects for our Car - obviously there can be more than one Wheel per Car, and we want to grab the whole collection of them. The Wheel object has 'id' and 'position' fields:

$car = $xpdo->getObject('Car',123);

$wheels = $car->getMany('Wheel');
foreach ($wheels as $wheel) {
   echo 'Got the '.$wheel->get('position').' wheel!<br />';
}

/* This would echo:
Got the Front Left wheel!
Got the Front Right wheel!
Got the Back Left wheel!
Got the Back Right wheel! */

As you can see, this allows us to quickly and easily grab related objects with ease.

Adding Related Objects

xPDO also has methods for adding related objects to an existing Object, to make saving easier:

addOne

So we have our Car object, but say we want to set it a new owner that we've just created. We can use addOne to easily add it in:

$car = $xpdo->getObject('Car',123);
$owner = $xpdo->getObject('Owner',array('name' => 'Mark'));
$car->addOne($owner);
$car->save(); 

Saving the Car object will save the 'owner' field on the Car row to the Owner's ID, via the relationship definition.

You can also do this with new (unsaved) objects; the save function will cascade and save both objects. Let's say we have a Car object, but we're adding an entirely new Owner:

$car = $xpdo->getObject('Car',324);

$owner = $xpdo->newObject('Owner');
$owner->set('name','John');
$owner->set('email','john@doe.com');

$car->addOne($owner);
$car->save();

This will save both the Car and the Owner object, and relate them together.

Both addOne and addMany take a 2nd parameter, called 'alias'. This should be used when an object has more than one relationship with a single class. For example, adding an Owner and Seller relationships, which are both User objects:

$car->addOne($ownerUser,'Owner');
$car->addOne($sellerUser,'Seller');

This helps xPDO differentiate between which object belongs to which relationship.

addMany

Objects with one-to-many relationships can also be batch added via the addMany method. Let's say we want to add all the Wheel objects with width of 10 to our Car:

$wheels = $xpdo->getCollection('Wheel',array(
   'width' => 10,
));

$car->addMany($wheels);
$car->save();

This will add all the 10-width Wheels and save the relationships.

See Also

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