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

Upgrading Models to Schema Version 1.1

Upgrading Models from Schema Version 1.0 to 1.1

In xPDO 2.0.0-rc3, a new schema element for describing table indexes was added to the object element of the xPDO schema. To maintain backwards compatibility in the runtime code with older schemas, where the indexes were described using the index and index_group attributes of the field elements, schemas created with this new element must be differentiated from the older schemas. As a result, the version attribute was added to the model element with a value of 1.1. All legacy models without the version element are assumed to be version 1.0.

To make conversion of existing mysql models easier, a tool is provided in xPDO that can be executed from the command line or a browser.

xpdo/tools/schema/upgrade-mysql-1.1.php

This simple tool takes a few arguments and automatically converts your 1.0 model's index definitions to the 1.1 format and adds version="1.1" to the model element.

  • Required Arguments
    • pkg — The name of the model package being converted.
    • pkg_path — The root path of the model package.
    • schema_name — The xPDO schema filename to convert.
    • schema_path — The path to the schema file.
  • Optional Arguments
    • backup_path — The path to write the backup schema file. If not specified, the backup is written to the same directory (schema_path).
    • backup_prefix — A string to prepend to the backup schema file. Default is '~'.
    • dsn — A valid PDO DSN connection string.
    • dbuser — A valid database user with access to the specified DSN.
    • dbpass — The password for the specified dbuser.
    • regen — If true, will regenerate the model after the schema is updated.
    • write — If true, will write the updated schema to file and backup the original.
    • echo — If true, will echo the updated schema to STDOUT.
    • debug — Sets the debug level of xPDO; if true, echo is automatically set true.
    • include — An external properties file to include arguments from.
    • error_reporting — Set the PHP error_reporting level for the script. Default is -1 (does not report errors).
    • display_errors — Set the PHP display_errors setting. Default is true.
Argument Rules
  • At least one of the four arguments, echo, write, regen, or debug, must be set.
  • The write argument cannot be used when the debug argument is true.
  • regen can only be used when write is set or the schema is already at version 1.1.

Usage

realpath() used on path arguments
All values for _path arguments (and the include argument) are passed through realpath().

Running as CLI script

CLI arguments for the script are specified in the format:

--argument[=value]
boolean arguments
If the equal sign and value are not provided, the argument value is set to boolean true.

Here is an example CLI usage:

user@hostname:/home/user/xpdo$ php xpdo/tools/schema/upgrade-mysql-1.1.php --pkg=sample --pkg_path=models/ --schema_name=sample.mysql.schema.xml --schema_path=schemas/ --echo --write --regen

Alternatively, you can use the include argument to set properties from an external file.

An example properties file, sample.schema.properties.php:

<?php
$pkg='sample';
$pkg_path='models/';
$schema_name='sample.mysql.schema.xml';
$schema_path='schemas/';
$echo=true;
$write=true;
$regen=true;

And the example CLI call to use the properties file:

user@hostname:/home/user/xpdo$ php xpdo/tools/schema/upgrade-mysql-1.1.php --include=sample.schema.properties.php
CLI arguments override properties file
Please note that any arguments provided in the CLI call will override values set in and included from the properties file.

Running as web request

You can also execute the script as a web request, passing the arguments as $_REQUEST variables, $_GET, $_POST, or $_COOKIE. An example URL for such a call might look like this:

http://localhost/food/xpdo/tools/schema/upgrade-mysql-1.1.php?pkg=sample&pkg_path=models/&schema_name=sample.mysql.schema.xml&schema_path=schemas/&echo=true&write=true&regen=true
boolean arguments
To set a boolean value of true, make sure you pass the string 'true', otherwise the value is assumed to be boolean false.

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