PX - Quick Start

New to PHP?

This project is a class library providing functionality for PHP scripting. For more information about PHP, check out their web site, here:
http://www.php.net

Getting Started

The functionality provided by the px.017.php file lets you easily build, manipulate, and display XML data using PHP. It's probably most useful if you already have some XML data to work with. HTML files can be used, as long as they are well-formed.

This "Getting Started" tutorial will show you how to use several methods of the pxObject class, which is defined in px.017.php. Once you get the hang of it, you can use the Full Documentation to learn about px methods that will meet your needs.

Before starting, you'll need to download the px.017.php file and place it somewhere on your web server that is accessible to PHP. Then, create a new php file and include px.017.php on the first line.

			// include the px file
			include_once('px.017.php');
		

Next we need some XML to work with. You can specify a file path to an XML file or a well-formed HTML file, but for the purpose of this tutorial, we'll just start with a simple string of XML text.

			// include the px file
			include_once('px.017.php');
			
			// create some xml to start with
			$xml = "<html><body><p>Hello, World!</p></body></html>";
		

Create a px object using the px() function, passing the xml text from the previous line to initialize the object.

			// include the px file
			include_once('px.017.php');
			
			// create some xml to start with
			$xml = "<html><body><p>Hello, World!</p></body></html>";
			
			// initialize a px object
			$doc = px($xml);
		

At this point, we have included the px functionality by including the px.017.php file, and we've created a px object by passing some xml text to the px() function. For the rest of this tutorial, I'll skip the "include_once" call, since that's a basic action in PHP. I'll also abbreviate the creation of the px object by passing the xml string directly.

Manipulating XML

The main purpose of a px object is to manipulate xml. In this section, we'll add a page title to the document and a paragraph at the end to express gratitude.

First, we'll use the prepend() method to put a title tag within a head section in the html. The prepend() method takes, as an argument, a string of xml text. The xml is converted to DOM objects and inserted into the owning px object's DOM document structure.

Afterward, we'll display the full contents as html.

// create a px object
$doc = px('
	<html>
		<body>
			<p>Welcome!</p>
			<p>This is my page.</p>
		</body>
	</html>
');

// prepend head and title tags
$doc->prepend(
	"<head><title>Welcome to my web page!</title></head>"
);

// display as HTML
echo $doc->html();
Result:
<html>
  <head>
    <title>Welcome to my web page!</title>
  </head>
  <body>
    <p>Welcome!</p>
    <p>This is my page.</p>
  </body>
</html>

Now we'll add a thank you paragraph at the end of the html body using the append method. We can't just call $doc->append() because the paragraph would be appended after the end of the "body" section - we'll need to use the xpath() method to show px where to append the new tag.

// create a px object
$doc = px('
	<html>
		<body>
			<p>Welcome!</p>
			<p>This is my page.</p>
		</body>
	</html>
');

// prepend head and title tags
$doc->prepend(
	"<head><title>Welcome to my web page!</title></head>"
);

// select the body tag using the xpath method, 
// then append a thank you
$doc->xpath("/html/body")
	->append("<p>Thank you for visiting!</p>");

// display as HTML
echo $doc->html();
Result:
<html>
  <head>
    <title>Welcome to my web page!</title>
  </head>
  <body>
    <p>Welcome!</p>
    <p>This is my page.</p>
    <p>Thank you for visiting!</p>
  </body>
</html>

Now you've learned how to add content and to select where content should be added. The pxObject class provides many more methods for adding, moving, altering, and removing xml elements and attributes, but you'll need to know a bit more about the xpath method first.

New to X-Path?

X-Path is a powerful method of selecting elements and attributes within an XML Document. Here's a tutorial I used to teach myself a lot about x-path:
X-Path Tutorial

Matching nodes using xpath()

The xpath() method takes, as a parameter, a string of xpath text. Though this tutorial uses only simple examples, x-path is a very powerful tool and can let you select nearly any combination of elements within an XML document.

In this section we'll use the xpath() method to select all the paragraph tags, then we'll use the attr() method to add some attributes.

First let's explore the limits of xpath() results. The elements matched by a call to xpath() are returned by the method, and thus are passed on to the next method if called like this:

$doc->xpath("/html/body")
	->append("<span>I go at the end of the body!</span>");

The result will not be carried on to the next line.

$doc->xpath("/html/body");
$doc->append(
	"<span>I'd end up at the end of the html section.</span>"
);

However, the results can be stored in a variable, as is shown below. Continuing from where we left off earlier, we have an HTML document with a title tag and three paragraphs in the body. Now let's see what the xpath method can do with it.

// Continuing from where we left off...
$doc = px('
	<html>
		<body>
			<p>Welcome!</p>
			<p>This is my page.</p>
		</body>
	</html>
');
$doc->prepend(
	"<head><title>Welcome to my web page!</title></head>"
);
$doc->xpath("/html/body")
	->append("<p>Thank you for visiting!</p>");

// ...select the paragraph tags into a variable
$pTags = $doc->xpath("//p");
echo $pTags->html();
Result:
<p>Welcome!</p><p>This is my page.</p><p>Thank you for visiting!</p>

As you can see, the xpath() function has returned a set of all three paragraph tags. Now, any operation we perform will be applied to all three tags.

$doc = px('
	<html>
		<body>
			<p>Welcome!</p>
			<p>This is my page.</p>
		</body>
	</html>
');
$doc->prepend(
	"<head><title>Welcome to my web page!</title></head>"
);
$doc->xpath("/html/body")
	->append("<p>Thank you for visiting!</p>");

// add a title attribute to each paragraph tag
$doc->xpath("//p")->attr("title", "I'm entitled!");

// show the whole body (for pretty formatting)
echo $doc->xpath("//body")->html();
Result:
<body>
  <p title="I'm entitled!">Welcome!</p>
  <p title="I'm entitled!">This is my page.</p>
  <p title="I'm entitled!">Thank you for visiting!</p>
</body>

Finally

You've learned to include the px.017.php file, to instantiate a px object with xml text, to alter that xml, and to print out the results. Now it's time to end this simple tutorial. Use the API Method List page to find exactly the methods you need.

Please use the Open Discussion Forum if you have any questions or suggestions. Good luck!