Architecture

Overview of Services_Ebay architecture

Services_Ebay consists of a lot of small classes, which keeps the used codebase small, as only the functionality that you use in your applications are loaded and parsed.

This will give you a short overview of the different types of objects that are provided and for which tasks they are used.

Services_Ebay

The Services_Ebay class is used for the following tasks:

1. Provides factory methods.

   The Services_Ebay provides methods to load and instantiate all of the other classes, that are included in the Services_Ebay distribution. That means that this is the only class you should include and instantiate yourself. Factory methods include loadApiCall(), getSession() and loadModel().

2. Provides constants.

   This class also defines some constants like the eBay site ids that you will need in your applications, constants include Services_Ebay::SITEID_ID, Services_Ebay::AUTH_TYPE_TOKEN or Services_Ebay::FEEDBACK_BRIEF. Whenever the eBay webservice expects an integer value in an XML tag, Services_Ebay tries to provide a matching constant.

3. Provides static helper methods.

   The class also provides some helper methods, which can be called statically like getAvailableApiCalls().

4. Acts as a proxy class.

   The most important usage is that Services_Ebay acts as a proxy class for the API calls, that means you can call methods on the class which will then be redirected to the appropriate call object.

Services_Ebay_Session

The Services_Ebay_Session class is used to handle the serialization and unserialization of the incoming and outgoing XML streams. Furthermore it builds the HTTP headers that are needed and manages all user authentication.

You will probably always use the session indirectly by at first passing it to the Services_Ebay object which will then use the session for making API calls.

require_once 'Services/Ebay.php';
    
// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

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

Services_Ebay_Transport

The Services_Ebay_Transport classes are used to build up network connections to the eBay webservices and send and recieve the raw data which has been created by Services_Ebay_Session.

Theoretically there may be different transport classes, but due to bugs in PHP's stream functions and some SSL libraries, the only working transport class is Services_Ebay_Transport_Curl, which uses PHP's curl extension.

Services_Ebay_Call

The Services_Ebay_Call classes contain information about the API calls that the eBay webservice offers. Each API call is encapsulated in an object that contains information about the API call, which XML tags have to be used and what the call is expected to return.

There are two ways in which the call objects can be used:

1. Instantiate them directly (best via the factory method of Services_Ebay), pass all parameters and invoke Services_Ebay_Call::call() while passing the session object to this method.

2. Use Services_Ebay as a proxy object which is able to do all the work by using PHP5's new object overloading features.

It is recommended to use Services_Ebay as a proxy instead of working directly on the Call objects. Services_Ebay will instantiate the class, pass the parameters and invoke the call method on the Call object.

Services_Ebay_Model

The Services_Ebay_Model classes act as local containers for the remote data stored on the eBay server. For example, when calling Services_Ebay::getItem(), the method will return an instance of Services_Ebay_Model_Item, which contains information about the item as well as some helper methods like Services_Ebay_Model_Item::addToDescription() which encapsulates a new API call.

Currently Services_Ebay provides models for accounts, disputes (single dispute and a list of disputes), user feedback (summary and a single feedback entry), items and list of items, MyeBay, orders, preferences, search results, shipments, eBay stores, transactions and users.

Services_Ebay_Cache

The Services_Ebay_Cache classes allow you to locally cache information that you retrieved from the eBay webservice without changing anything in your scripts. After registering a cache instance for any model type, Services_Ebay will query the cache before making a time-consuming API call.

The cache classes use a very high abstraction and allow you to create new cache containers, so you could store the data in a database, shared memory or wherever you like. Currently there is only one container available, which stores the data in the local filesystem.

To determine, whether a cache is still valid an instance of Services_Ebay_Cache_ExpiryCheck is used, which allows you to build "intelligent" caches that have a shorter expiry time the nearer the end of an auction is.