Proposal for "Services_Ebay"

» Metadata » Status
» Description

The eBay API

The eBay API allows you to perform business transactions efficiently and securely by using XML as the data format and HTTPS as the transport protocol.

To use the API, you'll have to register at the developer site, where you will retrieve your developer and application keys to access the API.

The eBay API uses a request token, similar to session ids (but much securer) for authentication. Your application will never receive the user-id and password directly, as this would open a lot of security holes. Instead the user will login at the ebay site, which will direct him back to your application and pass you his unique session identifier.

More on the eBay API can be found at:


Services_Ebay provides an easy-to-use wrapper class that enables you to transparently call any function provided by the eBay API.
It relies on PHP5 with curl or OpenSSL support enabled.

A small example

Before explaining the architecture of the package, let's start off with a small but powerful example.


require_once 'Services/Ebay.php';

$session = Services_Ebay::getSession($devId, $appId, $certId);

$ebay = new Services_Ebay($session);
echo $ebay->GeteBayOfficialTime();

This will fetch and output the current eBay time.

The main goal of Services_Ebay was to integrate the API into the way PHP works, so you do not have to create tons of objects that exchange data, you just tell the eBay object what you want to do. Think of it as something like simpleEbay (but with all the features eBay provides).

Architecture overview

The package consists of the following parts:

  • The Services_Ebay class
  • The Services_Ebay session
  • A collection of API calls
  • A collection of models

The Services_Ebay class

This class acts as a factory for the models and API calls as well as a proxy to the eBay API. Using PHP5's overloading capabilities, you will find yourself calling methods on this class that do not exist in the class definition.
Instead Services_Ebay will dispatch your request to one of the numerous API-calls which are loaded on demand. This keeps the package extendible and ensures that only the code that is really needed will be loaded.
Furthermore the class provides constants that may be used with some of the API calls.

The Services_Ebay session

The session object maintains the authentication and communication with the API. Whenever you want to call a method, you'll have to pass the session object, which serializes a call to XML, sends it to the eBay server and deserializes the result.
For this task, the session uses a Transport object that is interchangeable. Currently cURL is used, I'm evaluating streams and HTTP_Request.

The API-Calls

Each API call is encapsulated within one class, which is derived from an API-Call base class. The calls can be instantiated and called directly without using a proxy class, or you may use Services_Ebay which does most of the work for you.´
The following example shows how to retrieve the current time without calling a method on the proxy:


require_once 'Services/Ebay.php';

$session = Services_Ebay::getSession($devId, $appId, $certId);

$call = Services_Ebay::loadAPICall('GetEbayOfficialTime');
$result = $call->call($session);

echo $result;

This does the same:


require_once 'Services/Ebay.php';

$session = Services_Ebay::getSession($devId, $appId, $certId);

$ebay = new Services_Ebay($session);
echo $ebay->GeteBayOfficialTime();

Currently I implemented more than 50 API-calls, about 20 are left to go. You can take a look at all the calls that have been implemented in CVS.

There are always two ways of passing arguments to a call:

  • passing the most important parameters as scalar values
  • passing an associative array
While in most cases the first version is sufficient, there may be some cases where you will want to pass an exotic parameter. This is possible with all API-calls as you may specify an array that contains all parameters that are specified at the eBay website.
If you are unsure about the parameter order of a call, you may ask the call-object to display a description:


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

This will display:

API-Call : GetAccount
Parameters (max. 6)
 AccountPageType(no default value)
 Period(no default value)
 BeginDate(no default value)
 EndDate(no default value)
 PageNumber(no default value)
 Currency(no default value)

API-calls provide nearly the same functionality as the eBay website, only placing bids or buying items is not possible with the API (this is not a drawback of Services_Ebay, this is not implemented by the eBay-API).

The Models

The Services_Ebay models provide PHP objects that are local representations of the entities used at the eBay website. These include users, items, messages, transactions, feedback entries, lists and many more.
The models use SPL and overloading to be accessed in many ways. That means you may read and write properties of users by accessing the properties of the PHP object:


$user = $eBay->getUser('superman-74');
echo $user->Email;

Services_Ebay_Model::toArray() will return an associative array of all properties of the user/item or whatever if you prefer using arrays instead of objects.
Some models allow iterating, like the Feedback model:


$feedback = $ebay->GetFeedback('loislane-74', Services_Ebay::FEEDBACK_VERBOSE);

foreach ($feedback as $entry) {
    echo $entry;
    echo "<br />";

When iterating a Feedback, you will get feedback entries, objects that may be echo'd to STDOUT or used in many other fashions, like retrieving the item specifics for the feedback with $entry->getItem().Some API calls allow you to pass a model:


$item = Services_Ebay::loadModel('Item', null, $session);
$item->Category = 57882;
$item->Title = 'Supergirls\'s cape';
$item->Description = 'Another test item';
$item->Location = 'At my home';
$item->MinimumBid = '1000.0';

$item->VisaMaster = 1;

$result = $ebay->AddItem($item);

if ($result === true) {
    echo 'Item has been added with ItemId: '.$item->Id.' and ends on '.$item->EndTime.'<br />';
} else {
    echo 'An error occured while adding the item.';
Furthermore models provide shortcuts to API calls like:


$item->AddToDescription('This can also be done using $eBay->AddToItemDescription($id, $text);');

Error handling

Nearly no error handling has been implemented, as Services_Ebay is a PHP5-packages I wanted to await the outcome of the error handling RFC. I plan on converting serious errors to exceptions, while integrating PEAR_ErrorStack for warnings. Currently all API-errors result in an exception.

More examples

I'm not able to show all that's possible in the proposal itself as there are already 50+ API calls and 15+ models that provide even more features.
There is an example for every API call available, take a look at the sourcecode in CVS or test them online

The Future

I've been working on this project for about two weeks and I intend to put a lot more effort in this project. I'll add all missing API calls and improve the existing models to make the API more intuitive to use.

Possible feature additions yould be:

  • Validation of API-call arguments
  • Validation of model properties
  • Decorators for the models

Accepted by eBay?

I'm in contact with Adam Trachtenberg, technical evangelist at eBay and he is amazed by the package so far. He is constantly reviewing the source and helping me with any problems I may run into.

Competing packages

There's the eBay Acellerator Toolkit for PHP, which provides a similar functionality as Services_Ebay.
After evaluating the projects I found the following differences:

  • Services_Ebay is PHP5-only while PHPAT is focussing on PHP4
  • Services_Ebay is fully PEAR compliant, while PHPAT needs some adjustements
  • Services_Ebay has a lot less code by relying on overloading objects instead of providing setters/getters for each property
  • Services_Ebay always uses the same method and argument names as the eBay API, while PHPAT adjusted the names in some cases

These observations may be biased feel free to compare these two projects.

» Dependencies » Links
  • PHP 5.0.0
  • XML_Serializer 0.9.1
  • ext/curl
» Timeline » Changelog
  • First Draft: 2004-03-16
  • Proposal: 2004-08-31
  • Call for Votes: 2004-09-20