Ce module est
EXPERIMENTAL. Cela signifie que le comportement de ces
fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut
changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez
ce module à vos risques et périls.
Afin d'utiliser le Service d'Accès de Données XML pour les Objets de
Service de Données, vous aurez besoin de comprendre certains concepts
derrière le SDO : les graphiques de données, les objets de données, XPath
et ses expressions, et ainsi de suite.
Si vous n'êtes pas familier avec ces idées, vous devriez jeter un oeil sur
la section sur SDO.
Le travail de XML DAS est de déplacer les données entre l'application et
un fichier source XML, qui peut être soit un fichier ou une adresse URL.
SDO est créé et maintenu en accord avec un modèle qui définit les
types des noms et quels noms de propriétés chaque type doit avoir.
Pour les données qui proviennent d'un fichier XML, le modèle SDO
est construit depuis un fichier de schéma écrit dans un langage XML
(un fichier xsd). Ce schéma est habituellement passé Ã la méthode créée
lorsque l'objet XMLDAS est initialisé. La
spécification SDO 2.0
définit le lien entre les types XML et les types SDO. Il y a
quelques limitations dans le support PHP - tout ce qui se
trouve dans la spécification ne peut pas être fait - et ces limitations
sont énumérées dans une section suivante.
Le Service d'Accès de Données requiert PHP 5.1 ou supérieur. Il est
fonctionnel avec l'extension SDO et requiert que SDO soit installée. Voyez
les
instructions d'installation SDO
pour plus de détails sur comment faire cela.
La plupart des exemples suivants sont basés sur l'exemple de la lettre décrite dans la
documentation SDO. Les exemples assument
que le Schéma XML pour la lettre est contenu dans un fichier
lettre.xsd et que l'instance de la lettre est dans le
fichier lettre.xml. Ces deux fichiers sont reproduits
ici :
<lettre:lettres xmlns:lettre="http://lettreSchema">
<date>1er Mars 2005</date>
Mutual of Omaha
Wild Kingdom, USA
Chère
<prenom>Casy</prenom>
<nomFamille>Crocodile</nomFamille>
S'il vous plaît, achetez plus de requin imperméable.
Votre prime est passée date.
</lettre:lettres>
Exemple 1. Chargement, modification et sauvegarde d'un document XML
L'exemple suivant montre comment un document XML peut être chargé
provenant d'un fichier, altéré et récrit.
<?php /** * Charge, met à jour et sauvegarde un document XML */ try { $xmldas = SDO_DAS_XML::create("letter.xsd"); $document = $xmldas->loadFile("letter.xml"); $root_data_object = $document->getRootDataObject(); $root_data_object->date = "September 03, 2004"; $root_data_object->firstName = "Anantoju"; $root_data_object->lastName = "Madhu"; $xmldas->saveFile($document, "letter-out.xml"); echo "Nouveau fichier écrit :\n"; print file_get_contents("letter-out.xml"); } catch (SDO_Exception $e) { print($e->getMessage()); } ?>
Une instance du XML DAS est la première obtenue de la méthode
SDO_DAS_XML::create() qui est une méthode statique de
la classe SDO_DAS_XML.
L'emplacement du xsd est passé en paramètre.
Une fois que nous avons une instance de XML DAS initialisée avec un
schéma donné, nous pouvons l'utiliser pour charger l'instance du document
en utilisant la méthode loadFile().
Il y a aussi la méthode loadString() si vous
voulez charger une instance de document XML provenant d'une chaîne de
caractères.
Si l'instance du document se charge correctement, un objet de type
SDO_DAS_XML_Document sera retourné sur lequel vous
pourrez appeler la méthode getRootDataObject() pour
obtenir l'objet de données SDO qui est la racine de votre graphique de
données SDO. Vous pouvez alors utiliser les opérations SDO pour changer
le graphique SDO. Dans cet exemple, nous modifions les propriétés
date, prenom et
nomFamille.
Ensuite, nous utilisons la méthode
saveFile() pour écrire les changements dans
un fichier système.
La méthode saveFile a un argument optionnel qui, s'il est spécifié,
fera que le XML DAS formatera le XML en utilisant cet argument pour indenter
chaque changement dans le niveau du document.
This will write the following to letter-out.xml.
<?xml version="1.0" encoding="UTF-8"?>
<FormLetter xmlns="http://letterSchema" xsi:type="FormLetter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<date>September 03, 2004</date>
Mutual of Omaha
Wild Kingdom, USA
Dear
<firstName>Anantoju</firstName>
<lastName>Madhu</lastName>
Please buy more shark repellent.
Your premium is past due.
</FormLetter>
Exemple 2. Création d'un nouveau document XML
L'exemple précédent charge le document depuis un fichier.
Cet exemple montre comment créer un graphique de données
SDO en mémoire. Dans cet exemple, il est sauvegardé dans une
chaîne XML. En outre, vu que la lettre contient à la fois du contenu structuré
et non-structuré, on utilise
l'API séquence
pour assigner les propriétés pour construire le graphique des données.
<?php /** * Création d'un document XML */ try { $xmldas = SDO_DAS_XML::create("letter.xsd"); try { $doc = $xmldas->createDocument(); $rdo = $doc->getRootDataObject(); $seq = $rdo->getSequence(); $seq->insert("April 09, 2005", NULL, 'date'); $seq->insert("Acme Inc. ", NULL, NULL); $seq->insert("United Kingdom. "); $seq->insert("Dear", NULL, NULL); $seq->insert("Tarun", NULL, "firstName"); $seq->insert("Nayaraaa", NULL, "lastName"); $rdo->lastName = "Nayar"; $seq->insert("Please note that your order number "); $seq->insert(12345); $seq->insert(" has been dispatched today. Thanks for your business with us."); print($xmldas->saveString($doc)); } catch (SDO_Exception $e) { print($e); } } catch (SDO_Exception $e) { print("Problème lors de la création du document XML : " . $e->getMessage()); } ?>
La méthode createDocument() du XLM DAS
retourne un objet document avec une donnée racine simple correspondant
à un élément du document vide. Le nom de l'élément du document
est connu du fichier de schéma. S'il y a le moindre doute quant à la valeur
de l'élément du document, par exemple lorsque plus d'un schéma
a été chargé dans le même XML DAS, le nom de l'élément et l'URI de
l'espace de noms peuvent être passés à la méthode
createDocument().
Ceci affichera (les retours à la ligne ont été insérés pour une meilleure lisibilité) :
<?xml version="1.0" encoding="UTF-8"?>
<FormLetter xmlns="http://letterSchema" xsi:type="FormLetter"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<date>April 09, 2005</date>
Acme Inc. United Kingdom.
Dear
<firstName>Tarun</firstName>
<lastName>Nayar</lastName>
Please note that your order number 12345 has been
dispatched today. Thanks for your business with us.
</FormLetter>
Exemple 3. Définission des propriétés du document XML
Ce troisième exemple montre comment définir la version XML
ainsi que l'encodage de l'objet document. Ceci sera utilisé
lors de l'écriture du document XML. Si aucune déclaration XML
n'est désirée (peut-être voulez-vous générer du XML sous
la forme d'une chaîne à incorporer quelque part), alors, vous
pouvez utiliser la méthode setXMLDeclaration()
pour supprimer la déclaration.
<?php /** * Illustration des appels qui contrôlent la déclaration XML */ $xmldas = SDO_DAS_XML::create("letter.xsd"); $document = $xmldas->loadFile("letter.xml"); $document->setXMLVersion("1.1"); $document->setEncoding("ISO-8859-1"); print($xmldas->saveString($document)); ?>
La version et l'encodage du XML sont définis dans la déclaration XML
en haut du document XML.
Ce quatrième exemple illustre l'utilisation d'un type ouvert SDO
ainsi que l'utilisation de la méthode
createDataObject(). Pour cet exemple, nous
utilisons les deux schémas suivants :
Notez la présence de l'élément
any
dans la définission. Ce premier schéma définit
le type complexe jungle
qui contient une séquence de n'importe quel autre type.
Les autres types que cet exemple utilise, sont définis
dans un second fichier de schéma :
Voici l'exemple de code PHP qui utilise ces deux fichiers de schéma :
<?php
/** * Illustration de types ouverts et de l'utilisaton de la méthode addTypes() */
$xmldas = SDO_DAS_XML::create(); $xmldas->addTypes("jungle.xsd"); // ceci est un type ouvert, i.e. la xsd spécifiée peut contenir le type "any" $xmldas->addTypes('animalTypes.xsd');
Ces deux fichiers de schéma sont chargés dans le XML DAS avec les méthodes
create() et addTypes().
La méthode createDataObject() est utilisée pour
créer les trois objets de données. Dans chaque cas, l'URI de l'espace de noms
et le nom du type sont passés à la méthode createDataObject() :
dans cet exemple, l'URI de l'espace de nom est vide car aucun espace de noms
n'est utilisé dans ce schéma. Une fois que les trois objets - représentant
un ours, une penthère et un serpent - ont été créés, un objet document est créé
avec la méthode createDocument(). Dans ce cas,
il n'y a aucune ambiguité sur l'élément document - vu que le second fichier de
schéma définit uniquement des types complexes, l'élément document ne
peut être que l'élément global jungle défini dans
le premier schéma. Ce document aura un objet racine simple correspondant
à un élément document jungle vide.
Vu que c'est un type ouvert, les propriétés peuvent y être ajoutées.
Lorsque le premier assignement est effectué sur $do->bear,
une propriété bear est ajoutée à l'objet racine :
de la même façon que pour les deux assignements suivants.
Lorsque le document est écrit via la méthode
saveString(), le document résultant sera :
Exemple 5. Trouver ce que vous voulez dans un document
Cet exemple illustre comment trouver un nom d'élément et l'espace
de noms d'un élément du document depuis un objet XML Document, le
type SDO et l'espace de noms depuis l'élément racine de données XML.
Ceci peut être difficle à comprendre car il y a 4 méthodes à appeler :
deux peuvent être exécutées sur l'objet Document, et deux sur n'importe
quelle donnée y compris l'objet racine. Parceque les règles qui définissent
la façon dont le modèle SDO est dérivé du modèle XML, lorsque l'objet
de données concerné est l'objet racine qui représente l'objet document
pour le document, seulement trois valeurs possibles peuvent revenir
de l'appels des quatres méthodes.
Les deux appels de méthodes qui peuvent être exécutés sur le document sont
getRootElementName() et getRootEelementURI().
Elles retournent respectivement le nom de l'élément et l'espace de noms de l'élément document.
Les deux appels de méthodes qui peuvent être exécutés sur tous les objets
de données sont getTypeName() et
getTypeNamespaceURI().
Elles retournent respectivement le nom du type SDO et l'espace de noms du type de l'objet de données.
Dans tous les cas, l'appel à la méthode getRootElementURI()
sur l'objet document retournera la même valeur que l'appel à la méthode
getNamespaceURI() sur l'objet racine.
Les informations sont toutes dérivées depuis les premières lignes du fichier
schéma, où il y a trois sortes distinctes d'informations.
Pour illustrer ceci, voici les premières lignes du fichier
letter.xsd qui nous avons utilisé plus haut.
FormLetter, le nom du type complexe de l'élément document.
C'est également le nom du type SDO de l'objet racine.
http://letterSchema, l'espace de noms auquel l'élément document appartient.
C'est également l'URI de l'espace de noms du type SDO de l'objet racine.
C'est une partie des règles XML-SDO qui, lorsque le modèle SDO
est construit depuis le fichier schéma, sont utilisé pour récupérer
le nom du type et l'URI de l'espace de noms des types SDO pour
l'élément racine pour les types complexes de l'élément document,
lorsqu'ils existent. Dans cet exemple, le nom du type de l'objet
racine est FormLetter. Dans le cas où il n'y a pas de définission de
type complexe séparé pour l'élément document, lorsque le type
est défini en ligne et qu'il est anonyme, le nom du type SDO
sera le même que le nom de l'élément.
Le programme suivant charge le document lettre et vérifie les valeurs
retournées de chaque des quatres appels.
/** * Le "root element name" est le nom de l'élément de l'élément document * dans ce cas 'letters' * Ceci correspond à l'attribut 'name' de l'élément document dans le fichier xsd et correspond * au nom de l'élément depuis le XML */ echo "Le nom de l'élément document est " . $document->getRootElementName() . "\n"; assert($document->getRootElementName() == 'letters'); // une propriété du document
/** * Le "root element URI" est l'espace de noms du nom de l'élément de l'élément document * dans ce cas 'http://letterSchema' vu que 'letters' est dans l'espace de noms. * Il est récupéré depuis le xsd et correspond à l'espace de noms récupéré du XML */ echo "L'élément document est dans l'espace de noms " . $document->getRootElementURI() . "\n"; assert($document->getRootElementURI() == 'http://letterSchema'); // une propriété du document
/** * Le nom du type est récupéré depuis le modèle SDO * Les règles XML-SDO utilisées pour cela sont : * Le nom du type complexe s'il existe (ici, c'est le cas) * Le nom de l'élément document s'il n'y a pas de type complexe * Il est récupéré depuis le xsd */ echo "Le nom du type de l'objet racine est " . $root_do->getTypeName() . "\n"; assert($root_do->getTypeName() == 'FormLetter');
/** * Le type de l'espace de noms est récupéré depuis le modèle SDO * Les règles XML-SDO assurent que ce sera toujours le même que l'URI de * l'espace de noms de l'élément document */ echo "L'URI de l'espace de noms de l'objet racine est " . $root_do->getTypeNamespaceURI() . "\n"; assert($root_do->getTypeNamespaceURI() == 'http://letterSchema');
?>
Ce programme affichera :
Le nom de l'élément document est letters
L'élément document est dans l'espace de noms http://letterSchema
Le nom du type de l'objet racine est FormLetter
L'URI de l'espace de noms de l'objet racine est http://letterSchema
Exemple 6. Affichage du modèle SDO
Le XML DAS fournit une signification simple pour voir quels types et
propriétés ont été chargés. L'instruction PHP "print" ou "echo"
affichera les types et les propriétés.
Le XML DAS fournit deux classes principales.
La première est SDO_DAS_XML qui est la classe principale utilisée
pour récupérer les données depuis le source XML et utilisée
pour écrire les données.
La seconde est la classe SDO_DAS_XML_Document
qui représente les données du document XML.
Il y a également quelques classes d'exceptions qui peuvent
être lançées si des erreurs sont trouvées lors d'une recherche
ou de l'analyse du fichier xsd ou du fichier XML.
create
C'est une méthode statique disponible dans la classe SDO_DAS_XML.
Utilisée pour construire l'objet SDO_DAS_XML.
addTypes
Fonctionne de la même manière que la méthode create()
mais utilisée pour ajouter de contenu d'un second fichier schéma dans
un XML DAS qui a déjà été créé.
createDataObject
Peut être utilisée pour construire l'objet de données SDO d'un type donnée.
createDocument
Peut être utilisée pour construire l'objet Document XML.
loadFile
Charge une instance XML depuis un ficiher. Ce fichier peut
être en local ou sur un hôte distant.
loadString
la même chose que la méthode ci-dessus. Charge l'instance XML
qui est disponible sous la forme d'une chaîne de caractères.
saveFile
sauvegarde l'objet SDO_DAS_XML_Document en tant qu'un fichier XML.
saveString
sauvegarde l'objet SDO_DAS_XML_Document en tant qu'une chaîne de caractères.
Cette classe peut être utilisée pour récupérer le nom et l'espace de noms
de l'élément document et pour récupérer l'objet racine du document.
De plus, elle peut également être utilisée pour définir la version XML
et l'encodage du document de sortie.
Est une sous classe de
SDO_Exception.
Lançée par toutes les méthodes qui chargent des données depuis
un fichier, lorsque le fichier ne peut être trouvé.
Les spécifications SDO 2.0 définissent la
concordance entre les types XML et les types SDO. Avec Java SDO, la
concordance est implémentée par le XMLHelper. Avec SDO pour PHP, cette
concordance est implémentée par les Services d'Accès de Données XML. Le
XML DAS implémente la concordance décrite dans les spécifications SDO 2.0
avec les restrictions suivantes :
Types Simples XML
Type Simple avec sdoJava:instanceClass
- aucun support PHP fourni
Type simple avec sdoJava:extendedInstanceClass
- aucun support PHP fourni
Type Simple avec une liste de itemType.
Type Simple avec union.
Types Complex XML
Type complexe avec sdo:aliasName
- aucun support PHP pour ces types d'alias SDO.
Attribut XSD
Attribut avec sdo:aliasName
- aucun support PHP pour les alias des propriétés SDO.
Attribut avec une valeur par défaut
- aucun support PHP pour les propriétés par défaut SDO.
Attribut avec une valeur fixe
- aucun support PHP pour les propriétés SDO en lecture-seules ou les valeurs par défaut.
Attribut référençant un DataObject avec
sdo:propertyType - aucun support pour sdo:propertyType="...".
Attribut avec des propriétés bi-directionnelles d'un DataObject avec
sdo:oppositeProperty et sdo:propertyType
- aucun support PHP pour l'opposition SDO.
Éléments XSD
Élément avec sdo:aliasName
- aucun support PHP pour les alias de propriétés SDO.
Élément avec un groupe de substitution.
Éléments XSD avec un type simple
Élément de SimpleType avec une valeur par défaut
- aucun support PHP pour les valeurs par défaut SDO
Élément de SimpleType avec une valeur fixe
- aucun support PHP pour les propriétés en lecture-seules SDO ou les valeurs par défaut.
Élément de SimpleType avec sdo:string
- aucun support pour sdo:string="true".
Élément référençant un objet DataObject avec
sdo:propertyType - aucun support pour sdo:propertyType="..."
Élément avec une référence bi-directionnelle pour un object
DataObject avec sdo:oppositeProperty et sdo:propertyType
- aucun support PHP pour l'opposition SDO.
SDO_DAS_XML::createDocument --
Crée un objet de document XML Ã partir de zéro, sans avoir besoin de
charger un document à partir d'un fichier ou d'une chaîne de caractère
SDO_DAS_XML::loadFile --
Retourne un objet SDO_DAS_XML_Document pour un chemin donné d'une instance de document xml
SDO_DAS_XML::loadString --
Retourne un SDO_DAS_XML_Document pour une chaîne de caractères d'instance xml donnée
