Programming eBay Web Services with PHP 5 and Services_Ebay

by Adam Trachtenberg
01/27/2005

Over the last ten years, eBay has emerged as a platform where people can buy and sell practically anything. With more than 135 million users worldwide, eBay is a thriving online marketplace. Best of all, eBay isn't constrained by HTML. By using eBay's web services APIs, members of the eBay Developers Program can hook into the eBay platform using XML to integrate eBay into their own applications.

Like many web services, the eBay API comes in multiple flavors. There's the original XML-over-HTTPS POST interface, a format that's quite similar to REST. There's also a newer, more fashionable SOAP interface, which uses the Doc/Literal format.

Both have their own benefits and weaknesses. Pure XML is easy to produce and consume on any platform, something that's vital given the shaky state of PHP's SOAP support. However, SOAP has the advantage of eliminating the trouble of manually parsing XML into usable data structures.

PHP programmers have a third alternative, which combines the best parts of both interfaces: Services_Ebay. Written primarily by Stephan Schmidt, Services_Ebay is a PEAR package that wraps around the XML API to provide an object-oriented interface to eBay. Additionally, it takes advantage of several new PHP 5 features to create powerful code that's simple to use. You can't run this code under PHP 4 because PHP 5 plays such a key role.

This article demonstrates how to use Services_Ebay to search eBay and display results, similar to what an eBay affiliate might write. In the process, it gives a small taste of what you can begin to do with the package. Additionally, it shows off a real-world implementation of a PHP 5 program, one that showcases many of the reasons to upgrade from PHP 4 to PHP 5. Throughout the piece, I highlight all the places where a PHP 5 feature has come into play, so you can see where PHP 5 makes a real difference.

Installing

Before you can use Services_Ebay, you need to install it using the PEAR package manager tool. The easiest way to do this is with the upgrade -a command:

$ pear upgrade -a Services_Ebay-alpha

The upgrade -a flag causes PEAR not only to install Services_Ebay but also to automatically upgrade all package dependencies. The -alpha portion at the end lets PEAR know that it's OK to install an alpha version of the package, which is necessary because Services_Ebay is not yet tagged as stable.

Configuring

Now that you've installed Services_Ebay, you need to configure it with your authentication credentials. This is developer-specific information that allows eBay to identify you and your application.

require_once 'Services/Ebay.php';

// load authentication data from config file 
$config = parse_ini_file('ebay.ini');

// pass authentication data to Services_Ebay
$session = Services_Ebay::getSession($config['devId'],
                                     $config['appId'],
                                     $config['certId']);

$session->setToken($config['authToken']);
$session->setUrl(Services_Ebay_Session::URL_PRODUCTION);

After including the Services_Ebay package, the code loads in a configuration file, ebay.ini, using parse_ini_file(). This file contains the credentials you must provide when making an eBay services API call. Specifically, these are your:

• developer ID
• application ID
• certification
• Auth & Auth Token

The first three authentication credentials are collectively developer keys, and they identify the developer that's contacting eBay.

The fourth, Auth & Auth Token, identifies the user making the request without exposing her username and password. This person is frequently distinct from the application's developer, and the feature allows programmers to write applications for others to use without compromising security.

To acquire your own credentials, sign up for the eBay Developers Program.

Now that you have the data loaded, the next step is to create an eBay web services session. This session is an object that holds your credential data. Create a session by calling Services_Ebay::getSession() and passing your keys as arguments. In this case, the keys are in the $config array created by parse_ini_file().

The next two steps modify the session to set the Auth & Auth Token and the URL of the web service by using the setToken() and setUrl() methods. By default, the session points itself at eBay's testing server (known as the Sandbox). To override this value and direct the server at the live Production site, pass the Services_Ebay_Session::URL_PRODUCTION constant.

Searching

With the session configured, it's time to create the Services_Ebay object used to make eBay web services API calls. Instantiate a new instance, passing $session to the constructor.

// create new proxy object
$ebay = new Services_Ebay($session);

// search eBay
$searchTerms = 'new ipod mini';
$items = $ebay->GetSearchResults($searchTerms);

// print the results
foreach ($items as $item) {
	echo $item;
	echo "<br />";
}

Related Reading Upgrading to PHP 5 By Adam Trachtenberg

Now you can go ahead and search eBay using the GetSearchResults() method, or GSR for short. The easiest way to use GSR is to pass a single argument: your search terms. Here you're searching for a "new ipod mini".

Calling this method causes Services_Ebay to construct an XML web services request, contact eBay's servers, fetch a response, and then return the returned items in $items. In many ways, this process is similar to what occurs when you use a SOAP client; however, it has the benefits of being able to extend beyond the definitions in the WSDL file.

You can't tell from the code, but the Services_Ebay class doesn't actually define the GSR method. Instead, Services_Ebay uses the magical __call() method to trap the method invocation and automagically load in and execute the appropriate code. In PHP 5, you can define a method named __call(); then, any time you call an unimplemented method, PHP will invoke __call() instead of dying an ugly death.

Normally, once you've retrieved a list of search results, you want to loop through them and print them out. That's why the $items object uses a new PHP 5 feature, iterators, to allow to you cycle through the items inside of a foreach() loop.

Inside the foreach(), you receive an $item, which is an object that represents an eBay item. This class uses yet another PHP 5 feature that allows you to specify an object's "stringification." When you print or echo an object, PHP calls the object's __toString() method and displays what it returns.

Printing out a list of search results is a piece of cake:

// print the results
foreach ($items as $item) {
	echo $item;
	echo "<br />";
}

Figure 1. A list of search results

There's no need to extract the individual items from the object, nor to retrieve their individual properties to create a string description. It's all encapsulated inside the class, and accessible using regular PHP language constructs.

Pages: 1, 2

Next Page