Introduction

Service Data Objects (SDOs) enable PHP applications to work with data from different sources (like a database query, an XML file, and a spreadsheet) using a single interface.

Each different kind of data source requires a Data Access Service (DAS) to provide access to the data in the data source. In your PHP application, you use a DAS to create an SDO instance that represents some data in the data source. You can then set and get values in the SDO instance using the standard SDO interface. Finally, you use a DAS to write the modified data back to a data source (typically the same one).

See the list of Data Access Services for details on those currently available. In addition to the provided DASs, SDO also provides interfaces to enable others to be implemented (see the section on SDO Data Access Services Interface for more details).

This extension is derived from concepts taken from the Service Data Objects specification

Requirements

The SDO extension requires PHP 5.1 or higher.

SDO XML Data Access Service, which is built as part of this extension, requires libxml2 (Tested with libxml2 2.6.19) which can be downloaded from http://www.xmlsoft.org/.

Installation

There are several options, depending on whether you are installing on Windows or Linux, and depending on whether you are installing a released version (a .tgz file from the PECL site) or the latest from CVS. The Relational DAS also needs special attention as it is written in PHP.

The instructions are likely to change as PHP 5.1 progresses in status from beta to stable release. The instructions here were correct on 11th August 2005, when PHP 5.1.0b3 was the current beta release of PHP, and 0.5.1 was the current beta release of SDO.

The options are summarised in the following table:

Regardless of which platform or which level of the code you have installed you will need add the two extension libraries to your php.ini file. On Windows, add:

extension=php_sdo.dll extension=php_sdo_das_xml.dll

On Linux, add:

extension=sdo.so extension=sdo_das_xml.so

You may also need to update your extension_dir in php.ini to point to the location of these libraries.

The Relational DAS is written in PHP. You may need to update your include_path in php.ini to point to the directory that contains sdo/DAS/Relational .

Data Access Services

The table below lists the currently provided SDO Data Access Services:

Limitations

Examples

The examples below assume an SDO created with the schema and instance information shown below, using the XML Data Access Service.

The schema describes a company data object. The company contains department data objects, and each department contains employee data objects. Each data object has a number of primitive properties to describe things like name, serial number, etc. Finally, the company data object also has a non-containment reference to one of the employee data objects to identify them as the 'employeeOfTheMonth'.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sdo="commonj.sdo" xmlns:sdoxml="commonj.sdo/xml" xmlns:company="companyNS" targetNamespace="companyNS"> <xsd:element name="company" type="company:CompanyType"/> <xsd:complexType name="CompanyType"> <xsd:sequence> <xsd:element name="departments" type="company:DepartmentType" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="name" type="xsd:string"/> <xsd:attribute name="employeeOfTheMonth" type="xsd:IDREF" sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType> <xsd:complexType name="DepartmentType"> <xsd:sequence> <xsd:element name="employees" type="company:EmployeeType" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="name" type="xsd:string"/> <xsd:attribute name="location" type="xsd:string"/> <xsd:attribute name="number" type="xsd:int"/> </xsd:complexType> <xsd:complexType name="EmployeeType"> <xsd:attribute name="name" type="xsd:string"/> <xsd:attribute name="SN" type="xsd:ID"/> <xsd:attribute name="manager" type="xsd:boolean"/> </xsd:complexType> </xsd:schema>

The instance document below describes a single company, called 'MegaCorp', which contains a single department, called 'Advanced Technologies'. The Advanced Technologies department contains three employees. The company employeeOfTheMonth is referencing the second employee, 'Jane Doe'.

<?xml version="1.0" encoding="UTF-8" ?> <company xmlns="companyNS" name="MegaCorp" employeeOfTheMonth="#/departments.0/employees.1"> <departments name="Advanced Technologies" location="NY" number="123"> <employees name="John Jones" SN="E0001"/> <employees name="Jane Doe" SN="E0003"/> <employees name="Al Smith" SN="E0004" manager="true"/> </departments> </company>

Setting and Getting Property Values

The following examples assume $company is a data object created from the schema and instance document shown above.

Example 1. Access via Property names Data object properties can be accessed using the object property access syntax. The following gets the list of departments (containing a single department), and sets the company name to 'Acme'. <?php   $departments = $company->departments;   $company->name = 'Acme'; ?>

Example 2. Access via Property index Data object properties can be accessed via their property index using array syntax. The property index is the position at which the property's definition appears in the model (in this case the xml schema). We can see from the schema listing above that the departments element is the first company property defined and the company name attribute is the second company property (the SDO interface makes no distinction between XML attributes and elements). The following gets the list of departments (containing a single department), and sets the company name to 'Acme'. <?php   $departments = $company[0];   $company[1] = 'Acme'; ?>

Example 3. Data Object Iteration We can iterate over the properties of a data object using foreach. The following iterates over the company properties; name, departments and employeeOfTheMonth. <?php   foreach ($company as $name => $value) {     ...   } ?> For the first iteration, $name will be 'name' and $value will be 'Acme'. For the second iteration, $name will be 'departments' and $value will be an SDO_List (because departments is a many-valued property (stated maxOccurs="unbouded" in the schema)) containing a single data object of type DepartmentType. For the third iteration, $name will be 'employeeOfTheMonth' and $value will be a data object of type EmployeeType.

Example 4. Many-valued Property Iteration Many-valued properties can also be iterated over using foreach. The following iterates over the company's departments. <?php   foreach ($company->departments as $department) {     ...   } ?> Each iteration will assign the next department in the list to the variable $department.

Example 5. Many-valued Element Access We can access individual elements of many-valued properties using array syntax. The following accesses the first department in the company. <?php   $ad_tech_dept = $company->departments[0]; ?>

Example 6. Nested Property Access We can use nested property access to navigate the data object instance structure. The following gets and sets the name of the first department. <?php   $dept_name = $company->departments[0]->name;   $company->departments[0]->name = 'Emerging Technologies'; ?>

Example 7. Simple XPath support We can access properties using XPath-like (an augmented sub-set of XPath) expressions, the simplest form of which is the property name. The following sets the company name and gets the employeeOfTheMonth. <?php   $company['name'] = 'UltraCorp';   $eotm = $company['employeeOfTheMonth']; ?>

Example 8. Simple XPath support We can use chained array access calls to navigate the data object instance structure. The following gets and sets the name of the first department. <?php   $dept_name = $company['departments'][0]['name'];   $company['departments'][0]['name'] = 'Emerging Technologies'; ?>

Example 9. XPath Navigation We can use XPath expressions to navigate the data object instance structure. Two forms of indexing into many-valued properties are supported. The first is the standard XPath array syntax with the indexing starting at one, the second is an SDO extension to XPath with an index starting at zero. The following both get the second employee from the first department. <?php   $jane_doe = $company["departments[1]/employees[2]"];   $jane_doe = $company["departments.0/employees.1"]; ?>

Example 10. XPath Querying We can use XPath to query and identify parts of a data object based on instance data. The following retrieves the manager from the 'Advanced Technologies' department. <?php   $ad_tech_mgr = $company["departments[name=\"Advanced Technologies\"]/employees[manager=\"true\"]"]; ?>

Example 11. Creating child data object A data object can be a factory for its child data objects. A child data object is automatically part of the data graph. The following add a new employee to the 'Advanced Technologies' department. <?php   $ad_tech_dept = $company["departments[name=\"Advanced Technologoies\"]"];   $new_hire = $ad_tech_dept->createDataObject('employees');   $new_hire->name = 'John Johnson';   $new_hire->SN = 'E0005';   $new_hire->manager = false; ?>

Example 12. Unset referenced data object We can use the isset() and unset() functions to test and remove items from the data object. The following removes the 'employeeOfTheMonth' from the company. If this were a containment reference then the employee would be removed from the company (probably not a good idea to sack your best employee each month!), but since this is a non-containment reference, the employee being referenced will remain in the department in the company, but will no longer be accessible via the employeeOfTheMonth property. <?php   if (isset($company->employeeOfTheMonth) {     unset($company->employeeOfTheMonth);   } ?>

Working with Sequenced Data Objects

Sequenced data objects are SDOs which can track property ordering across the properties of a data object. They can also contain unstructured text elements (text element which do not belong to any of the SDO's properties). Sequenced data objects are useful for working with XML documents which allow unstructured text (i.e. mixed=true) or if the elements can be interleaved ( <A/><B/><A/>). This can occur for example when the schema defines maxOccurs>1 on a element which is a complexType with a choice order indicator.

The examples below assume an SDO created with the following schema and instance information, using the XML Data Access Service.

The schema below describes the format of a letter. The letter can optionally contain three properties; date, firstName, and lastName. The schema states mixed="true" which means that unstructured text can be interspersed between the three properties.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:letter="http://letterSchema" targetNamespace="http://letterSchema"> <xsd:element name="letters" type="letter:FormLetter"/> <xsd:complexType name="FormLetter" mixed="true"> <xsd:sequence> <xsd:element name="date" minOccurs="0" type="xsd:string"/> <xsd:element name="firstName" minOccurs="0" type="xsd:string"/> <xsd:element name="lastName" minOccurs="0" type="xsd:string"/> </xsd:sequence> </xsd:complexType> </xsd:schema>

The following is an instance letter document. It contains the three letter properties; date, firstName and lastName, and has unstructured text elements for the address and letter body.

<letter:letters xmlns:letter="http://letterSchema"> <date>March 1, 2005</date> Mutual of Omaha Wild Kingdom, USA Dear <firstName>Casy</firstName> <lastName>Crocodile</lastName> Please buy more shark repellent. Your premium is past due. </letter:letters>

When loaded, the letter data object will have the sequence and property indices shown in the table below:

To ensure sequence indices are maintained, sequenced data objects should be manipulated through the SDO_Sequence interface. This allows the data object's instance data to be manipulated in terms of the sequence index as opposed to the property index (shown in the table above). The following examples assume the letter instance has been loaded into a data object referenced by the variable $letter.

Example 13. Getting the SDO_Sequence interface We obtain a data object's sequence using the getSequence() method. The follow gets the sequence for the letter data object. <?php   $letter_seq = $letter->getSequence(); ?>

All subsequent examples assume that the $letter_seq variable has been assigned the sequence for the letter data object.

Example 14. Get/set sequence values We can get and set individual values (including unstructured text) using the sequence index. The following sets the firstName to 'Snappy' and gets the last sequence values (the unstructured text, 'Your premium is past due.'). <?php   $letter_seq[4] = 'Snappy';   $text = $letter_seq[count($letter_seq) - 1]; ?>

Example 15. Sequence iteration We can iterate through the individual sequence values using foreach. The following runs through the individual values in sequence order. <?php   foreach ($letter->getSequence() as $value) {     ...   } ?>

Example 16. Sequence versus Data Object Setting values through the data object interface may result in the value not being part of the sequence. A value set through the data object will only be accessible through the sequence if the property was already part of the sequence. The following example sets the lastName through the data object and gets it through the sequence. This is fine because lastName already exists in the sequence. If it had not previously been set, then lastName would be set to 'Smith', but would not be part of the sequence. <?php   $letter[2] = 'Smith';   $last_name = $letter_seq[5]; ?>

Example 17. Adding to a sequence We can add new values to a sequence using the SDO_Sequence::insert() method. The following examples assume that the 'firstName' and 'lastName' properties are initially unset. <?php   // Append a firstName value to the sequence   // value: 'Smith'   // sequence index: NULL (append)   // propertyIdentifier: 1 (firtName property index)   $letters_seq->insert('Smith', NULL, 1);   // Append a lastName value to the sequence   // value: 'Jones'   // sequence index: NULL (append)   // property identifier: 'lastName' (lastName property name)   $letters_seq->insert('Jones', NULL, 'lastName');   // Append unstructured text   // value: 'Cancel Subscription.'   // sequence index: absent (append)   // propertyIdentifier: absent (unstructured text)   $letters_seq->insert('Cancel Subscription.');   // Insert new unstructured text.  Subsequent sequence values   // are shifted up.                                          // value: 'Care of:'   // sequence index: 1 (insert as second element)   // propertyIdentifier: absent (unstructured text)   $letters_seq->insert('Care of:', 1); ?>

Example 18. Removing from a sequence We can use the isset() and unset() functions to test and remove items from the sequence (Note: unset() currently leaves the values in the data object, but this behaviour is likely to change to also remove the data from the data object). A sequence behaves like a contiguous list; therefore, removing items from the middle will shift entries at higher indices down. The following example tests to see if the first sequence element is set and unsets it if is. <?php   if (isset($letter_seq[0]) {     unset($letter_seq[0]);   } ?>

Predefined Classes

SDO consists of two sets of interfaces. The first set covers those interfaces for use by SDO client applications. These are identified by the package prefix 'SDO_'. The second set is those for use by Data Access Service implementations and are identified by the package prefix 'SDO_DAS_'. The majority of SDO users will not need to use or understand the 'SDO_DAS_' interfaces.

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.