Это расширение является
ЭКСПЕРИМЕНТАЛЬНЫМ. Поведение этого расширения,
включая имена его функций и относящуюся к нему документацию, может
измениться в последующих версиях PHP без уведомления. Используйте
это расширение на свой страх и риск.
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).
A Service Data Object instance is made up of a tree of data objects.
The tree is defined by containment references between the data objects.
For example, a Company data object might consist of a number of
Department data objects and therefore the Company would have
a containment reference to the Departments.
Deleting a data object which has a containment reference to another
data object will delete the referenced data object. For example,
deleting the Company data object will also delete the Departments.
An SDO may also have non-containment references between data objects
in the tree. For example, one Employee data object might reference
another Employee to identify a career mentor. Deleting a data object
which has a non-containment reference to another data object does
not delete the referenced data object.
As well as data objects referencing each other, they can also have
primitive properties. For example, the Company data object might
have a property called "name" of type string, for holding the name
of the company (for example, "Acme").
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 6th October 2005, when PHP
5.1.0RC1 was the current release candidate for PHP, and 0.5.2 was the current beta
release of SDO.
The options are summarised in the following table:
latest/Release
Windows
Linux
latest CVS
The latest DLLs for the SDO core and the XML DAS can be downloaded from
php_sdo
and
php_sdo_das_xml
respectively.
Check out the Relational DAS from CVS to somewhere on the
PHP
include_path
.
Check out the SDO core and the XML DAS from CVS
and build according to the instructions
below for building on Linux.
Check out the Relational DAS from CVS to somewhere on the
PHP
include_path
.
Release
There is currently no way provided for building the release
version of the SDO core and XML DAS on a user's machine.
You will only be able to pick up the latest DLLs from the
snaps site (see previous row of this table).
The Relational DAS can be downloaded and installed with
the command:
pear install -B <package name and level>
Substitute the desired package name and level, for example
sdo-0.5.2, in the command above.
You can download and install all three SDO components - the
SDO core, the XML DAS and the Relational DAS - with the
command:
pear install <package name and level>
Substitute the desired package name and level, for example
sdo-0.5.2, in the command above.
This command will build the SDO and XML shared libraries as well as
installing the PHP files that make the Relational DAS.
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:
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
.
Building SDO on Linux
This section describes how to build the SDO core and XML DAS on Linux.
Currently you would only need to know how to do this if you
wish to build a recent version that you have checked out
of CVS.
Change to the main extension directory:
cd < wherever your sdo code is >
Run phpize, which will set up the environment to
compile both SDO and the XML Data Access Service.
Next, run ./configure; make; make install. Please
note, you may need to login as root to install the extension.
Make sure that these modules are loaded by PHP, by adding
extension=sdo.so and
extension=sdo_das_xml.so to your
php.ini file in the same order.
The following are limitations in the current SDO implementation:
There is no support for multi-byte character sets.
SDO Limitations
The following SDO 2.0 concepts are not supported in the current
PHP implementation.
It is not necessarily the case that these will all be added over time.
Their inclusion will depend on community requirements.
Abstract types and type derivation.
Open types.
Bi-directional relationships.
Type and property alias names.
Read-only properties.
Model introspection.
XMLHelper/XSDHelper (the XML DAS provide a lot of this functionality)
TypeHelper (the SDO_DAS_DataFactory provides this functionality)
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'.
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'.
The following examples assume $company is a data
object created from the schema and instance document shown above.
Пример 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'.
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'.
We can iterate over the properties of a data object using foreach.
The following iterates over the company properties; name,
departments and employeeOfTheMonth.
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.
Пример 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.
Пример 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.
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.
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.
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.
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.
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); } ?>
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.
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:
Sequence Index
Property Index:Name
Value
0
0:date
March 1, 2005
1
-
Mutual of Omaha
2
-
Wild Kingdom, USA
3
-
Dear
4
1:firstName
Casy
5
2:lastName
Crocodile
6
-
Please buy more shark repellent.
7
-
Your premium is past due.
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.
Пример 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.
Пример 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.').
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) { ... } ?>
Пример 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.
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');
// 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); ?>
Пример 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]); } ?>
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.
The main interface through which data objects are manipulated. In
addition to the methods below, SDO_DataObject extends the
ArrayAccess, SDO_PropertyAccess (defines __get() /
__set() methods for property access overloading),
Iterator, and Countable interfaces.
The interface through which sequenced data objects can be accessed
to preserve ordering across a data object's properties and
to allow unstructured text.
SDO_Sequence preserves contiguous indices and therefore inserting
or removing elements may shift other elements up or
down. In addition to the methods below, SDO_Sequence extends the
ArrayAccess, Iterator and Countable interface.
The interface through which many-valued properties are manipulated.
In addition to the method defined below, SDO_List extends ArrayAccess,
Iterator and Countable. SDO_List preserves contiguous indices and
therefore inserting or removing elements may shift other elements
up or down.
The interface through which data objects can be created.
A Data Access Service is responsible for populating the model
(i.e. configuring the data factory with the type and structure
information for the data objects it can create.)
for the factory and can then optionally return an instance of,
or implement, the SDO_DataFactory interface.
The interface through which a Data Access Service can access
a data object's
SDO_DAS_ChangeSummary
.
The change summary is used by the Data Access Service to check for
conflicts when applying changes back to a data source.
The interface through which the change history of a data
object is accessed. The change summary holds information for any
modifications on a data object which occurred since logging
was activated. In the case of deletions and modifications, the old
values are also held in the change summary.
If logging is no longer active
then the change summary only holds changes made up to the point when
logging was deactivated.
Reactivating logging clears the change summary.
This is useful when a set of changes have been written out by a
DAS and the data object is to be reused.
The interface for constructing the model for an SDO_DataObject.
The SDO_DAS_DataFactory is an abstract class providing a static
method which returns a concrete data factory implementation.
The implementation is used by Data Access Services to create an
SDO model from their model.
For example, a Relational Data Access Service might create and populate
an SDO_DAS_DataFactory model based on a schema for a relational
database.
Перечисленные ниже константы определены данным расширением и могут быть
доступны только в том случае, если PHP был собран с
поддержкой этого расширения или же в том случае, если
данное расширение подгружается во время выполнения.