// include a class-loading function
require_once("classes/include.php");

// import XML and XMLDocument classes
import("org.active-link.xml.XML");
import("org.active-link.xml.XMLDocument");

EXAMPLE 1

In the first example, let's construct a simple XML tree from scratch. Let's make the root element called PREFERENCES and store some user preferences in XML format. First, let's create an XML object $myXML by:

$myXML = new XML("PREFERENCES");

This creates an XML object and assigns PREFERENCES as its root tag name. Now, let's add couple of sub-branches (child tags) under the root tag, let's say COLORSCHEME and ICONS. This is easily accomplished by calling setTagContent method as follows:

$myXML->setTagContent("Blue", "PREFERENCES/COLORSCHEME");
$myXML->setTagContent("Motif", "PREFERENCES/ICONS");

setTagContent method takes the supplied tag path and either searches and replaces existing tag contents, or, as in this case, creates new set of tags. Notice that we set "Blue" and "Motif" as tag contents of respective branch (children) tags.

Next, let's add another branch (child tag) NEWS, but now let's also add a grandchild tag also and let's call it HEADLINES.

$myXML->setTagContent("", "PREFERENCES/NEWS/HEADLINES");

Notice that, just like before, by specifying the tagpath setTagContent in this case creates a new set of tags. The tag path can be as deep as necessary, or left unspecified to assume current context.

Here is the final output from our $myXML object at the end of example 1:

<PREFERENCES>
	<COLORSCHEME>Blue</COLORSCHEME>
	<ICONS>Motif</ICONS>
	<NEWS>
		<HEADLINES />
	</NEWS>
</PREFERENCES>

EXAMPLE 2

In the second example, let's perform a slightly more complex manipulation of our $myXML object that we created in example 1. Under HEADLINES let's add three "item" branches (child tags) all with different contents. But this time, let's use a different method - let's first create 3 item branches as separate unassociated objects and then add them under HEADLINES in the XML tree.

$headline1 = new XMLBranch("item");
$headline2 = new XMLBranch("item");
$headline3 = new XMLBranch("item");

The above syntax should look familiar. XMLBranch class extends XML class, so all methods present in XML also are available under XMLBranch and work exactly the same way. So, let's assign new contents to each of our new branches.

$headline1->setTagContent("headline 1 content");
$headline2->setTagContent("headline 2 content");
$headline3->setTagContent("headline 3 content");

To complicate things a little more, let's set tag "id" attributes to each of the created branches so that they are easy to locate and identify. Let's assign each of their IDs as 1, 2, and 3 respectively.

$headline1->setTagAttribute("id", "1");
$headline2->setTagAttribute("id", "2");
$headline3->setTagAttribute("id", "3");

Now these branches are ready to be added to our $myXML tree.

To add our new branches under HEADLINES, first we have to access and retrieve the HEADLINES branch. To do so, we use getBranches method as follows:

$headlines = $myXML->getBranches("PREFERENCES/NEWS", "HEADLINES");

getBranches method, in this case, accepts tag path argument to search the tags in; and also tag name argument to retrieve only tags with that name. Also, getBranches method returns an array when match(es) are found, or false when none are. Since we know that $myXML contains one HEADLINES match under PREFERENCES/NEWS, we can directly go to that element in the array - $headlines[0] and add our newly created branches.

$headlines[0]->addXMLBranch($headline1);
$headlines[0]->addXMLBranch($headline2);
$headlines[0]->addXMLBranch($headline3);

As you can see, addXMLBranch method takes our headline branches and adds them to HEADLINES branch in our main XML tree - $myXML. It is important to remember that getBranches method returns an array of references to actual branches, so, by modifying $headlines array we are also modifying $myXML object.

Here is the final output from our $myXML object at the end of example 2:

<PREFERENCES>
	<COLORSCHEME>Blue</COLORSCHEME>
	<ICONS>Motif</ICONS>
	<NEWS>
		<HEADLINES>
			<item id="1">headline 1 content</item>
			<item id="2">headline 2 content</item>
			<item id="3">headline 3 content</item>
		</HEADLINES>
	</NEWS>
</PREFERENCES>

EXAMPLE 3

In the third example, we will create an XML object by parsing through an existing XML string, modify one specific branch, and remove (delete) another completely. Let's assume that the final output from the previous example is stored in $myXMLString variable. To create a new XML object by parsing a string, we simply call:

$myNewXML = new XML($myXMLString);

That was easy! The XML class constructor is smart and knows when it should create a root element (like in example 1) or parse the string into an XML object itself. In this case, we should have a $myNewXML object that is identical to previously created $myXML object.

Now, let's access the second "item" branch under HEADLINES and modify its content. To do so, we use getBranches method again as follows:

$myItems = $myNewXML->getBranches("PREFERENCES/NEWS/HEADLINES", "item", "id", "2");

Notice that getBranches can query a specified tag path by tag name, tag attribute name, and tag attribute value, and return only those matching branches in an array. It's worth pointing out that all arguments for getBranches method are optional. Now, since we know that there's only one branch that will match the specified getBranches query we can go directly to that branch and modify its contents:

$myItems[0]->setTagContent("NEW headline 2 content updated!");

It is also important to note that when querying XML object in such way it is a good practice to test for getBranches returning false when no matches are found; and when matches are found, iterating through the array to access all getBranches query results.

Now that we updated the second "item" contents under PREFERENCES, let's remove the third item tag altogether. To remove a branch, we use removeBranches method:

$myNewXML->removeBranches("PREFERENCES/NEWS/HEADLINES", "item", "id", "3");

Notice that the syntax of removeBranches method is similar to getBranches method.

Here is the final output from our $myNewXML object at the end of example 3:

<PREFERENCES>
	<COLORSCHEME>Blue</COLORSCHEME>
	<ICONS>Motif</ICONS>
	<NEWS>
		<HEADLINES>
			<item id="1">headline 1 content</item>
			<item id="2">NEW headline 2 content updated!</item>
		</HEADLINES>
	</NEWS>
</PREFERENCES>

EXAMPLE 4

In the 4th and final example, we will learn how to save an XML document via an XMLDocument class and how to read saved XML documents from a file.

To save an XML document, first we create an XMLDocument object:

$myXMLDoc = new XMLDocument();

Then we associate our XML object with the newly created XMLDocument object. Let's say we want to save our $myNewXML object output from previous example in an XML document:

$myXMLDoc->setXML($myNewXML);

And, finally, we call save method and supply a filename to save the XML document:

$myXMLDoc->save("example.xml");

To read and parse an XML document, we create an XMLDocument object and pass the filename to its constructor:

$myNewXMLDoc = new XMLDocument("example.xml");

It's that easy! The XML document "example.xml" is read and parsed into $myNewXMLDoc object. Next, we access XML object stored inside the $myNewXMLDoc by calling getXML method as follows:

$myXMLFromFile =& $myNewXMLDoc->getXML();

PHP4 users: notice that if we use =& we will actually retrieve a reference to the actual XML object stored inside $myNewXMLDoc; this way, all modifications to $myXMLFromFile will reflect in $myNewXMLDoc object automatically. If such functionality is not desired, we can simply use an assignment operator (=) and work on a copy of an XML object instead.