Programming eBay Web Services with PHP 5 and Services_Ebay

Beautifying

Of course, that's not a very visually appealing display, but you can fix this problem with only a little bit of code:

require_once 'Services/Ebay/Model/Item.php';



class prettyItem extends Services_Ebay_Model_Item {

	public function __toString() {

		$title = $this->Title;

		$img   = $this->ItemProperties['GalleryURL'];

		$price = $this->LocalizedCurrentPrice;

		$link  = $this->Link;

		$time  = $this->EndTime;

		$bids  = $this->BidCount;

	

		// skip items without a gallery picture

		if (empty($img)) { return ''; }

		

		return <<<_HTML_

<div style="clear:left; width: 450px; padding:5px; margin:5px; background:#ddd;">

    <a href="$link"><image src="$img" 

      alt="$title" align="left" height="77" width="77" /></a>

    <b>$title</b><br/>

    Current Price: $price<br/>

    Number of Bids: $bids<br/>

    Ending Time: $time<br />

</div>

_HTML_;

	}

}



Services_Ebay::useModelClass('Item', 'prettyItem');

Services_Ebay uses a series of "model classes" to handle the dirty work of abstracting away the details behind the individual API calls. When GSR returns a list of eBay items, Services_Ebay instantiates Item models for each listing. Even better, it allows you to override the model to add or redefine methods to fix your application needs.

In this case, you're modifying the Item model's __toString() method to update the default display to a more attractive one.

First, you need to load the class, Services_Ebay_Model_Item, located inside the Models directory in Item.php. Once it's loaded, you can subclass it using the standard PHP extends syntax. In this example, the child class is prettyItem.

Inside of prettyItem::__toString(), a set of lines combines Item properties--including the title, price, and link--into a set of HTML elements.

The final step is to tell Services_Ebay to substitute your new model class for the default one. To do this, call the Services_Ebay::useModelClass() method. The first value is the model name; the second is the name of the replacement class.

Now, when you print out items, you'll have an entirely new picture:

	foreach ($items as $item) {

		echo $item;

	}

Figure 2. A new list of search results

Notice that you didn't need to modify any of the logic for cycling through the items or for printing them out.

Introspecting

Besides creating an iterable list of items, GSR returns additional information about your search. For instance, while GSR returns a maximum of 100 items per call, it does allow you to "paginate" your request. This allows you to make one request for items 1-100, a second for 101-200, and so on.

In order to do this, however, you need to know the total number of potential results. This is available as an object property:

print $items->GrandTotal;

1153

Alternatively, you can use array syntax if you prefer:

print $items['GrandTotal'];

1153

These bits of syntactical sugar again use new PHP 5 features: the accessor method, __get(), and SPL's ArrayAccess interface, respectively.

To access all the properties at once, retrieve them using the toArray() method:

print_r($items->toArray());



Array

(

    [Count] => 100

    [HasMoreItems] => 1

    [GrandTotal] => 1155

    [PageNumber] => 1

)

This method exposes everything: the count of the items returned, whether there are any more items to fetch, the total number of available items, and the "page number" within the search results.

The ability to call methods on $items is one of the advantages of using an iterable object instead of an array. With an array, you're just holding a set of individual items. Now, you can provide collection of items, packaged more tightly as parts of a whole.

On the flip side, it's useful to know what parameters GSR takes. Earlier on, I said that the first argument is the search string, but GSR actually takes up to five parameters. You could read the documentation or flip through the code, but Services_Ebay wants to make things really easy.

Therefore, every API call has a describeCall() method, which lets you retrieve a method's parameters from within the code itself:

$call = Services_Ebay::loadAPICall('GetSearchResults');

$call->describeCall();



API-Call : GetSearchResults



Parameters (max. 5)

 Query(no default value)

 SearchInDescription(no default value)

 Skip(no default value)

 MaxResults(no default value)

 Category(no default value)



API Documentation : http://developer.ebay.com/DevZone/docs/API_Doc/

Functions/GetSearchResults/GetSearchResultsLogic.htm

As you see, describeCall() returns three pieces of information:

• the name of the API call
• a list of all parameters and their default values, if any
• a link to the eBay API documentation for that call

This not only lets you figure out how Services_Ebay has modeled a call but also points you directly to the official eBay documentation, so you can read the definitive reference.

Surprisingly, even describeCall() uses a new PHP 5 feature: reflection. PHP 5's reflection classes let you retrieve information about classes and functions in a programmatic fashion. In this example, the documentation URL actually comes from a specially formatted comment above the class that phpDocumentor, an auto-documentation tool for PHP, can read. With PHP 5 you can extract these comments without reading and parsing the class file yourself by instantiating a class and invoking a single method, getDocComment().

Conclusion

You've just seen how easy it is to write a eBay web services search application in PHP with the help of Services_Ebay. Services_Ebay uses much of the power of PHP 5: the whole spectrum of the new object model, the rewritten XML and XSL extensions, iterators and SPL, reflection, and exceptions. These components combine to create a kick-ass tool that PHP 4 can't replicate without lots of work, if at all.

Furthermore, the eBay API is not restricted to read-only calls, such as searching for and viewing listings. You can do almost everything through the API, including listing items, giving and checking feedback, managing eBay Stores, retrieving data from your My eBay page, and setting preferences. Services_Ebay supports most of these calls today and is quickly adding the rest.

As a result, now's a great time for PHP developers to start exploring the power of the eBay API.

Adam Trachtenberg is the manager of technical evangelism for eBay and is the author of two O'Reilly books, "Upgrading to PHP 5" and "PHP Cookbook." In February he will be speaking at Web Services Edge 2005 on "Developing E-Commerce Applications with Web Services" and at the O'Reilly booth at LinuxWorld on "Writing eBay Web Services Applications with PHP 5."

Return to the PHP DevCenter.