Doing the curl E-shuffle with PHP

If you read Technique 53, you already know quite a bit about curl. curl is a command line tool that makes it quick and easy to upload and download data from other computers. curl can interact with

Web or FTP servers, secure servers, and even directory servers. The curl project developers have created an easy-to-use library, named libcurl, that you can use to build your own curl-enabled programs. libcurl programs can be written in a number of languages. In the previous technique, you find out how to use libcurl from a C program; in this technique, we show you how to use libcurl from a PHP script.

Combining PHP with curl and XML: An overview

PHP scripts usually run within a Web server (not within a Web browser). It might seem a bit strange for a Web server to connect to another server to retrieve information, but that’s actually a very useful thing to do. You may want to relay information (like news headlines) from a remote server to the Web browser. Or, you may want to translate information

LISTING 54-1: WEATHER REPORT FOR MICROSOFT

you obtain from another server into a more friendly and useful format. Using libcurl from a PHP script makes it easy to retrieve remote information.

Thousands of Web sites publish information in XML format (eXtensible Markup Language). We mention earlier that XML data is somewhat self-identifying; each piece of data is surrounded by a pair of tags that describe the data contained within. For example, suppose you see the following text inside an XML stream:

<Forecast>Sunny</Forecast>

You could reasonably assume that Sunny is a forecast (probably part of a weather forecast). XML was designed to make it easier for programs to make sense of a piece of data. PHP knows how to parse through an XML data stream and pick out the pieces that you’re interested in.

In this section, we show you how to use PHP, curl, and XML to display weather conditions on your Web site.

Checking out the XML file

The Web site www.ejse.com publishes XML weather conditions for your zip code. A typical weather report from EJSE might look like Listing 54-1.

(That’s not a typo; the XML stream misspells temperature.)

Notice that each piece of data is surrounded by a pair of tags that describes the data within. For example, the forecast (Cloudy) is surrounded by the tags

<Forecast> and </Forecast> — that’s the essence of XML.

Downloading and displaying the XML file with a PHP script (and curl)

Listing 54-2 shows a reasonably short PHP script that downloads the current weather conditions for a given zip code (currently hard-coded to 98052) and parses through the XML.

This script is very simple:

Line 5: The script calls loadWeather() to retrieve the current conditions and store them in $xmlData.

Line 6: parseWeather() parses the XML stream and stores the result in $weather.

Line 7: displayWeather() picks apart the $weather array and creates an HTML table that’s sent to the Web browser.

Line 9: The loadWeather() function (starting at line 9) downloads an XML stream from the URL shown on line 11. (Change the zip code at the end of the URL to match the location that you’re interested in.)

Line 12: Before you can start a transfer using libcurl, you initialize the library and save a copy of the handle returned by curl_init().

Lines 14 and 15: Next, you see two calls to curl_setopt(). The first call (line 14) gives the URL to libcurl, and the second call (line 15) tells libcurl that you want to download data and store it in a variable (as opposed to storing the data in a file).

Line 17: curl_exec() starts the download, waits for it to complete, and stores the result in $xmlData. When curl_exec() finishes, $xmlData contains the current weather conditions, in XML form, as shown in Listing 54-1.

Line 19–21: Finally, loadWeather() closes its connection to libcurl (see line 19) and returns the XML data to the caller (line 21).

Line 24: parseWeather() (lines 24–34) expects two parameters: the destination array ($weather) and the raw XML data ($data). parseWeather() doesn’t do any of the hard work itself; instead, it calls on PHP’s XML library to pick apart the XML data.

Line 26: You see a call to the xml_parser_create() function. xml_parser_create() creates a new XML parser and returns a handle. An XML parser doesn’t do much by itself; it just identifies the various pieces of an XML stream. To make use of an XML parser, you have to provide callback functions. When an XML parser recognizes a chunk of data that you’re interested in, it calls the callback function that you provide.

Line 28: The call to xml_set_element_handler() tells the parser that you’re interested in elements (or, as we call them, tags). When the parser finds the beginning of an element, it calls the startTag function. When the parser finds the end of an element, it calls endTag (you see startTag and endTag in a moment).

Here’s a typical XML element:

<Location>Redmond, WA</Location>

When the parser sees <Location>, it calls startTag(); when it sees </Location>, it calls endTag(). The stuff in between the tags is called character data — we can trap that, too (see the call to xml_set_character_ data_handler() at line 29).

Line 31: parseWeather() starts the XML parser with a call to xml_parse(), passing the raw XML data that you want to parse.

Line 32: When xml_parse() completes, the call to xml_parser_free() shuts down the parser and frees up any lingering resources.

Lines 36–42: startTag() and endTag() are simple. When the parser calls startTag(), it sends along the tag name, which you store in a global variable named $tag. The tagAttributes parameter contains XML element attributes (if there are any); the weather information that you’re looking at won’t contain attributes, so you can safely ignore this argument.

Lines 43–48: The endTag() function (lines 43–48) is called whenever the parser sees an end tag. In this function, you simply set the global variable $tag to an empty string.

Lines 50–56: In between calls to startTag() and endTag(), the XML parser calls dataHandler() to handle the data within the tags. dataHandler() simply stores the data that it’s given (a string contained between a pair of tags) in the $weather associative array.

The process is clear when you follow a typical element through the parser. Say that the parser runs into the following text:

<Location>Redmond, WA</Location>

When the parser sees the start tag, it calls startTag(). startTag() stores the tag name (Location) in the $tag global variable. (Actually, the parser converts all tag names to uppercase, so $tag is set to LOCATION.) Next, the parser calls

dataHandler() with the chunk of text (Redmond, WA) between the start tag and the end tag. dataHandler() stores the data in an element of the $weather array using the tag name as in index into the array. In other words: $weather[“LOCATION”] = “Redmond, WA”. Finally, endTag() wipes out the global $tag name (that’s not strictly necessary, but it makes your code a bit more obvious).

When the parser finishes its work, $weather looks like this:

Lines 57–81: The displayWeather() function builds an HTML page that it sends to the Web browser. The result looks similar to Listing 54-3.