View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFPROP:Proposal Zone Template}

{zone-data:component-name}
Zend_Service_Ebay
{zone-data}

{zone-data:proposer-list}
[Renan de Lima|mailto:renandelima@gmail.com]
[Don Bosco Nguyen Van Hoi|mailto:donbosco.rulz@gmail.com]
[Ramon Henrique Ornelas|mailto:ramon.ornela@gmail.com]
{zone-data}

{zone-data:liaison}
TBD
{zone-data}

{zone-data:revision}
0.1 - 07 May 2009: initial draft

0.2 - 22 Jul 2009: eBay API review #1

0.3 - 24 Jul 2009: eBay API review #2

0.4 - 27 Jul 2009: eBay API review #3

0.5 - 29 Jul 2009: ready for review

0.6 - 03 Aug 2009: eBay API review #4 and response objects improvements
* Response->__construct() was removed
* added Response->setOperation() and getOperation()
* added Response->setOption()

0.7 - 15 Aug 2009: eBay API review #5 and response objects improvements
* added Finding_Abstract->getDom()
enables external xml manipulation for every entry
* added Finding_Abstract->getProxy()
provides a reference to api proxy object that made request
* removed prefix "get" from page methods of Response_Items class
old: getPage(), getPageFisrt(), getPageLast(), getPageNext(), getPagePrevious()
current: page(), pageFist(), pageLast(), pageNext(), pagePrevious()
to avoid confusion among getters and setters in the future
* moved Zend_Rest object handling from Ebay_Finding class to Ebay_Abstract
current: getRestClient(), setRestClient() and $_rest
* Ebay_Finding->appName renamed and moved to Ebay_Abstract->_app
Ebay_Abstract->setApp() and Ebay_Abstract->getApp() was created
application client id is available for every ebay api
* Ebay_Finding->globalId renamed and moved to Ebay_Abstract->_site
Ebay_Abstract->getSite() and Ebay_Abstract->getSite() was created
endpoint site id to make requests is available for every ebay api

0.8 - 22 Aug 2009: commom options for API requests
* removed from Ebay_Abstract: $_app, setApp(), getApp(), $_site, setSite(), getSite()
* added to Ebay_Abstract: $_param, setParam(), getParam()
added constants for commom parameters as well
it means it will not necessary to create a lot of getters and setters for odd parameteres of any new eBay API in the future

0.9 - 23 Aug 2009: performance changes
* removed Zend_Date and Zend_Uri dependencies
Zend_Date type changed to string
Zend_Uri type changed to string
it makes objects faster
* removed Finding_Abstract->_proxy and getProxy()
it makes objects simpler
* added $proxy argument for methods that make requests
due $_proxy was deleted, this is necessary
it provides an easer interaction among eBay APIs in the future

0.10 - 28 Dec 2009: working implementation
* Zend_Service_Ebay_Finding constructor receives only one argument (code standard)
it expects a Zend_Config object, assoc array or a string of Application Id
in replace of second arg it was created a const that contain default value of Global Id
every Zend_Service_Ebay_Finding method can receive a Zend_Config as last argument as well

* default value of argument $productIdType of findItemsByProduct() setted to null (code standard)
method body changes its to 'ReferenceId' internally when it's null

* renamed "param" to "option" at Zend_Service_Ebay_Abstract (code standard)
all zend classes use the name "option", it makes easier to understand what this does
::PARAM_APP_ID and ::PARAM_GLOBAL_ID to ::OPTION_APP_ID and ::OPTION_GLOBAL_ID
->setParam() and ->setOption() to ->getParam() and ->getOption()

* type of _Finding_Error_Message->error changed to _Finding_Error_Data_Set (adjusting)
an XML returned may contain more than one error
see more at http://developer.ebay.com/DevZone/finding/CallRef/types/ErrorMessage.html
it was necessary to create this class Zend_Service_Ebay_Finding_Error_Data_Set for that

* integer parser returns string instead of integer (adjusting)
PHP integer (32 bit system) does not work for ebay "long" type
see more at http://developer.ebay.com/DevZone/finding/CallRef/types/simpleTypes.html#long
anyway I still kept the @var value as "integer"

* DOMXPath (code standard)
renamed _Finding_Abstract->_xpath to ->_xPath
created _Finding_Abstract->getXPath()
allow using of this object outside, like ->getDom()

* _Finding_Category_Histogram extends _Finding_Category (adjusting)
once this class has the same attributes from basic Category class
_Finding_Category->findItems() will work for both

* added galleryPlusPictureURL attribute to Zend_Service_Ebay_Finding_Search_Item (adjusting)

* added topRatedSeller attribute to Zend_Service_Ebay_Finding_SellerInfo (adjusting)

* some float attributes changed to integer (fix)
Zend_Service_Ebay_Finding_Aspect_Histogram_Value->count
Zend_Service_Ebay_Finding_Category_Histogram->count
Zend_Service_Ebay_Finding_Error_Data->errorId
Zend_Service_Ebay_Finding_SellerInfo->feedbackScore

0.11 - 15 Jun 2010: working implementation

* client management moved away from Zend_Service_Ebay_Abstract
removed in Zend_Service_Ebay_Abstract $_rest, getRestClient() and setRestClient($rest)
added to Zend_Service_Ebay_Abstract $_client and two abstract methods: getClient() and setClient($client)
implementation of those methods in Zend_Service_Ebay_Finding

* renamed constant Zend_Ebay_Service_Finding::NAMESPACE to Zend_Ebay_Service_Finding::XMLNS
NAMESPACE is a reserved word http://www.php.net/manual/en/reserved.keywords.php

{zone-data}

{zone-data:overview}
Zend_Service_Ebay is a component that allows to do request to eBay web services easily.
{zone-data}

{zone-data:references}
* [eBay Developer Documentation Center|http://developer.ebay.com/support/docs/]
* [eBay Finding - Call Reference|http://developer.ebay.com/DevZone/finding/CallRef/index.html]
{zone-data}

{zone-data:requirements}
* This will implement *only* [eBay Finding API|http://developer.ebay.com/DevZone/finding/CallRef/index.html]
** This will accept features that allow to make request to every API avaliable at [eBay Webservices API|http://developer.ebay.com/support/docs/]
* This will allow to make requests to eBay through objects returned from operations available in the front-end
* This will allow to send every filter options for any service
** This will provide a simple options structure handling, easer than [ebay call structure|http://developer.ebay.com/DevZone/finding/Concepts/MakingACall.html#callstruct]
{zone-data}

{zone-data:dependencies}
* Zend_Rest
* Zend_Service_Exception
{zone-data}

{zone-data:operation}
Every eBay API is repesented by a class. These classes has the webservice operations as public methods. The operations' name are identical to eBay documentation.

The most commom arguments are explicit in the methods signature, but advanced arguments is available for every operations as well. Operations has as last argument: $options, this one is optional.

{code}
$finding = new Zend_Service_Ebay_Finding( ... needed finding args ... );
$finding->operation1( ... operation1 args ..., $options);

$trading = new Zend_Service_Ebay_Trading( ... needed trading args ... );
$trading->operation2( ... operation2 args ..., $options);

$xyz = new Zend_Service_Ebay_Xyz( ... needed xyz args ... );
$xyz->operation3( ... operation3 args ..., $options);
{code}

Options are translated from [php array|http://php.net/array] to [eBay array syntax|http://developer.ebay.com/DevZone/finding/Concepts/MakingACall.html#URLExamples]. Example:
{code}
array(
'paginationInput' => array(
'entriesPerPage' => 5,
'pageNumber' => 2,
),
'itemFilter' => array(
array(
'name' => 'MaxPrice',
'value' => 25,
'paramName' => 'Currency',
'paramValue' => 'USD',
),
array(
'name' => 'FreeShippingOnly',
'value' => true,
),
array(
'name' => 'ListingType',
'value' => array(
'AuctionWithBIN',
'FixedPrice',
'StoreInventory',
),
),
'productId' => array(
'' => 123,
'type' => 'UPC'
)
)
);

// this will be translated to

array(
'paginationInput.entriesPerPage' => '5',
'paginationInput.pageNumber' => '2',
'itemFilter(0).name' => 'MaxPrice',
'itemFilter(0).value' => '25',
'itemFilter(0).paramName' => 'Currency',
'itemFilter(0).paramValue' => 'USD',
'itemFilter(1).name' => 'FreeShippingOnly',
'itemFilter(1).value' => 'true',
'itemFilter(2).value(0)' => 'AuctionWithBIN',
'itemFilter(2).value(1)' => 'FixedPrice',
'itemFilter(2).value(2)' => 'StoreInventory',
'productId' => '123',
'productId.@type' => 'UPC'
);

// the result is used to make request via rest.
{code}
{zone-data}

{zone-data:milestones}
* Milestone 1: \[DONE\] Finished
* Milestone 2: \[DONE\] Reviewed
* Milestone 3: \[DONE\] Accepted
* Milestone 4: \[DONE\] Working implementation
* Milestone 5: \[DONE\] Unit tests
* Milestone 6: \[DONE\] Documentation
* Milestone 7: Moved to core
{zone-data}

{zone-data:class-list}
General
* Zend_Service_Ebay_Abstract
* Zend_Service_Ebay_Exception
* Zend_Service_Ebay_Finding_Exception

Api proxy
* Zend_Service_Ebay_Finding

Response
* Zend_Service_Ebay_Finding_Response_Abstract
* Zend_Service_Ebay_Finding_Response_Histograms
* Zend_Service_Ebay_Finding_Response_Items
* Zend_Service_Ebay_Finding_Response_Keywords

Abstract types
* Zend_Service_Ebay_Finding_Abstract
* Zend_Service_Ebay_Finding_Set_Abstract

Aspect
* Zend_Service_Ebay_Finding_Aspect
* Zend_Service_Ebay_Finding_Aspect_Histogram_Container
* Zend_Service_Ebay_Finding_Aspect_Histogram_Value
* Zend_Service_Ebay_Finding_Aspect_Histogram_Value_Set
* Zend_Service_Ebay_Finding_Aspect_Set

Category
* Zend_Service_Ebay_Finding_Category
* Zend_Service_Ebay_Finding_Category_Histogram
* Zend_Service_Ebay_Finding_Category_Histogram_Container
* Zend_Service_Ebay_Finding_Category_Histogram_Set

Error
* Zend_Service_Ebay_Finding_Error_Data
* Zend_Service_Ebay_Finding_Error_Message

Search
* Zend_Service_Ebay_Finding_Search_Item
* Zend_Service_Ebay_Finding_Search_Item_Set
* Zend_Service_Ebay_Finding_Search_Result

More types
* Zend_Service_Ebay_Finding_ListingInfo
* Zend_Service_Ebay_Finding_PaginationOutput
* Zend_Service_Ebay_Finding_SellingStatus
* Zend_Service_Ebay_Finding_ShippingInfo
* Zend_Service_Ebay_Finding_Storefront
{zone-data}

{zone-data:use-cases}
||UC-01 Find for items||
{code}
<?php

$ebay = new Zend_Service_Ebay_Finding('My-App-Id');

$resultItems = $ebay->findItemsByKeywords('php book');
// or $ebay->findItemsAdvanced('php book', true);
// or $ebay->findItemsByCategory('123');
// or $ebay->findItemsByProduct('456');
// or $ebay->findItemsInEbayStores("Joe's Store");

do {
// current page number
$resultItems->paginationOutput->pageNumber;

// list items in current page
foreach ($resultItems->searchResult->item as $item) {
$item->title;
$item->listingInfo->buyItNowPrice;
$item->listingInfo->viewItemURL;
// and much more ...

// inner call, find for items of same current product
// like $ebay->findItemsByProduct($item->productId, $item->productId_type)
$resultItems2 = $item->findItemsByProduct($ebay);
// ...

// inner call, find for items of same store
// like $ebay->findItemsInEbayStores($item->storeInfo->storeName)
$resultItems3 = $item->storeInfo->findItems($ebay);
// ...
}

} while ($resultItems = $resultItems->pageNext($ebay));
{code}
||UC-02 Get histograms||
{code}
<?php

$ebay = new Zend_Service_Ebay_Finding('My-App-Id');

$resultHistogram = $ebay->getHistograms('123');

foreach ($resultHistogram->categoryHistogramContainer->categoryHistogram as $category) {
$category->categoryId;
$category->categoryName;
// ...

// inner call
// like $ebay->findItemsByCategory($category->categoryId);
$resultItems = $category->findItems($ebay);
// ...
}
{code}
||UC-03 Get keywords||
{code}
<?php

$ebay = new Zend_Service_Ebay_Finding('My-App-Id');

$resultKeyword = $ebay->getSearchKeywordsRecommendation('zend');

echo 'Did you mean ' . $resultKeyword->keyword . '?';

// inner call
// like $ebay->findItemsByKeywords($resultKeyword->keyword)
$resultItems = $resultKeyword->findItems($ebay);
// ...
{code}
||UC-04 Service configuration||
{code}
// above how to set up commom data for every ebay service
// first of all get a instance of some ebay api
//
$client = Zend_Service_Ebay_Xyz(); // extends Zend_Service_Ebay_Abstract

$client->setOption(Zend_Service_Ebay_Abstract::OPTION_APP_ID, 'My-App-Id')
->setOption(Zend_Service_Ebay_Abstract::OPTION_GLOBAL_ID, 'EBAY-US');

$appId = $client->getOption(Zend_Service_Ebay_Abstract::OPTION_APP_ID);
$globalId = $client->getOption(Zend_Service_Ebay_Abstract::OPTION_GLOBAL_ID);
{code}
{zone-data}

{zone-data:skeletons}
||General||
{code}
class Zend_Service_Ebay_Abstract
{
const OPTION_APP_ID = 'app-id';
const OPTION_GLOBAL_ID = 'global-id';
// ...

protected $_options; // array
protected $_client; // mixed

public function setOption($name, $value = null); // return self
public function getOption($name = null); // return mixed

abstract public function setClient($client); // return self
abstract public function getClient(); // return mixed
}

class Zend_Service_Ebay_Exception{}

class Zend_Service_Ebay_Finding_Exception{}
{code}

||API proxy||
{code}
class Zend_Service_Ebay_Finding extends Zend_Service_Ebay_Abstract
{
// receive Zend_Config, array or string (application id)
public function __construct($options);

public function findItemsAdvanced($keywords, $descriptionSearch = true, $categoryId = null, $options = array());
public function findItemsByCategory($categoryId, $options = array());
public function findItemsByKeywords($keywords, $options = array());
public function findItemsByProduct($productId, $productIdType = null, $options = array());
public function findItemsInEbayStores($storeName, $options = array());
// return Zend_Service_Ebay_Finding_Response_Items

public function getHistograms($categoryId, $options = array());
// return Zend_Service_Ebay_Finding_Response_Histograms

public function getSearchKeywordsRecommendation($keywords, $options = array());
// return Zend_Service_Ebay_Finding_Response_Keywords
}
{code}

||Response||
{code}
abstract class Zend_Service_Ebay_Finding_Response_Abstract extends Zend_Service_Ebay_Finding_Abstract
{
public $ack; // string
public $errorMessage; // Zend_Service_Ebay_Finding_Error_Message
public $timestamp; // string
public $version; // string

protected $_operation; // string
protected $_options; // array

public function setOperation($operation); // return itself
public function getOperation(); // return string

public function setOption($name, $value = null) // return itself
public function getOption($name = null); // return mixed
}

class Zend_Service_Ebay_Finding_Response_Histograms extends Zend_Service_Ebay_Finding_Response_Abstract
{
public $aspectHistogramContainer; // Zend_Service_Ebay_Finding_Aspect_Histogram_Container
public $categoryHistogramContainer; // Zend_Service_Ebay_Finding_Category_Histogram_Container
}

class Zend_Service_Ebay_Finding_Response_Items extends Zend_Service_Ebay_Finding_Response_Histograms
{
public $paginationOutput; // Zend_Service_Ebay_Finding_PaginationOutput
public $searchResult; // Zend_Service_Ebay_Finding_Search_Result
public $searchResult_count; // integer

// ebay allow to fetch page number up to 100
// when $max < 1, it will try fetch page until self->paginationOutput->totalPages
//
public function page(Zend_Service_Ebay_Finding $proxy, $number); // return Zend_Service_Ebay_Finding_Response_Items
public function pageFirst(Zend_Service_Ebay_Finding $proxy); // return Zend_Service_Ebay_Finding_Response_Items
public function pageLast(Zend_Service_Ebay_Finding $proxy, $max = 100); // return Zend_Service_Ebay_Finding_Response_Items
public function pageNext(Zend_Service_Ebay_Finding $proxy, $max = 100); // return Zend_Service_Ebay_Finding_Response_Items
public function pagePrevious(Zend_Service_Ebay_Finding $proxy); // return Zend_Service_Ebay_Finding_Response_Items
}

class Zend_Service_Ebay_Finding_Response_Keywords extends Zend_Service_Ebay_Finding_Response_Abstract
{
public $keywords; // string

public function findItems(Zend_Service_Ebay_Finding $proxy, array $options = array());
// return Zend_Service_Ebay_Finding_Response_Items
}
{code}

||Abstract types||
{code}
class Zend_Service_Ebay_Finding_Abstract
{
protected $_dom; // DOMElement
protected $_xPath; // DOMXPath

public function __construct(DOMElement $dom)
public function getDom(); // return DOMElement
public function getXPath(); // return DOMXPath

// post construct logic, classes must read their members here
protected function _init(); // return null
}

class Zend_Service_Ebay_Finding_Set_Abstract implements SeekableIterator, Countable
{
protected $_nodes; // DOMNodeList

public function __construct(DOMNodeList $nodes);

// post construct logic
protected function _init(); // return null

// this classe must implement every methods from Countable and SeekableIterator,
// except SeekableIterator::current()
//
// classes that extends this one must implement SeekableIterator::current()
}
{code}

||Aspect||
{code}
class Zend_Service_Ebay_Finding_Aspect extends Zend_Service_Ebay_Finding_Abstract
{
public $valueHistogram; // Zend_Service_Ebay_Finding_Aspect_Histogram_Value_Set
public $valueHistogram_valueName; // array of string
}

class Zend_Service_Ebay_Finding_Aspect_Histogram_Container extends Zend_Service_Ebay_Finding_Abstract
{
public $aspect; // Zend_Service_Ebay_Finding_Aspect_Set
public $aspect_name; // array of string
public $domainDisplayName; // string
public $domainName; // string
}

class Zend_Service_Ebay_Finding_Aspect_Histogram_Value extends Zend_Service_Ebay_Finding_Abstract
{
public $count; // integer
}

class Zend_Service_Ebay_Finding_Aspect_Histogram_Value_Set extends Zend_Service_Ebay_Finding_Set_Abstract
{
public function current(); // return Zend_Service_Ebay_Finding_Aspect_Histogram_Value
}

class Zend_Service_Ebay_Finding_Aspect_Set extends Zend_Service_Ebay_Finding_Set_Abstract
{
public function current(); // return Zend_Service_Ebay_Finding_Aspect
}
{code}

||Category||
{code}
class Zend_Service_Ebay_Finding_Category extends Zend_Service_Ebay_Finding_Abstract
{
public $categoryId; // string
public $categoryName; // string

public function findItems(Zend_Service_Ebay_Finding $proxy, $options = array()); // return Zend_Service_Ebay_Finding_Response_Items
}

class Zend_Service_Ebay_Finding_Category_Histogram extends Zend_Service_Ebay_Finding_Category
{
public $childCategoryHistogram; // Zend_Service_Ebay_Finding_Category_Histogram_Set
public $count; // integer
}

class Zend_Service_Ebay_Finding_Category_Histogram_Container extends Zend_Service_Ebay_Finding_Abstract
{
public $categoryHistogram; // Zend_Service_Ebay_Finding_Category_Histogram_Set
}

class Zend_Service_Ebay_Finding_Category_Histogram_Set extends Zend_Service_Ebay_Finding_Set_Abstract
{
public function current(); // return Zend_Service_Ebay_Finding_Category_Histogram
}
{code}

||Error||
{code}
class Zend_Service_Ebay_Finding_Error_Data extends Zend_Service_Ebay_Finding_Abstract
{
public $category; // string
public $domain; // string
public $errorId; // integer
public $exceptionId; // string
public $message; // string
public $parameter; // array of string
public $parameter_name; // array of string
public $severity; // string
public $subdomain; // string
}

class Zend_Service_Ebay_Finding_Error_Data_Set extends Zend_Service_Ebay_Finding_Set_Abstract
{
public function current(); // return Zend_Service_Ebay_Finding_Error_Data
}

class Zend_Service_Ebay_Finding_Error_Message extends Zend_Service_Ebay_Finding_Abstract
{
public $error; // Zend_Service_Ebay_Finding_Error_Data_Set
}
{code}

||Search||
{code}
class Zend_Service_Ebay_Finding_Search_Item extends Zend_Service_Ebay_Finding_Abstract
{
public $autoPay; // boolean
public $charityId; // integer
public $country; // string
public $distance; // float
public $distance_unit; // string
public $galleryPlusPictureURL; // array of string
public $galleryURL; // string
public $globalId; // string
public $itemId; // string
public $listingInfo; // Zend_Service_Ebay_Finding_ListingInfo
public $location; // string
public $paymentMethod; // array of string
public $postalCode; // string
public $primaryCategory; // Zend_Service_Ebay_Finding_Category
public $productId; // string
public $productId_type; // tring
public $secondaryCategory; // Zend_Service_Ebay_Finding_Category
public $sellerInfo; // Zend_Service_Ebay_Finding_SellerInfo
public $sellingStatus; // Zend_Service_Ebay_Finding_SellingStatus
public $shippingInfo; // Zend_Service_Ebay_Finding_ShippingInfo
public $storeInfo; // Zend_Service_Ebay_Finding_Storefront
public $subtitle; // string
public $title; // string
public $viewItemURL; // string

public function findItemsByProduct(Zend_Service_Ebay_Finding $proxy, array $options = array());
// return Zend_Service_Ebay_Finding_Response_Items
}

class Zend_Service_Ebay_Finding_Search_Item_Set extends Zend_Service_Ebay_Finding_Set_Abstract
{
public function current(); // return Zend_Service_Ebay_Finding_Search_Item
}

class Zend_Service_Ebay_Finding_Search_Result extends Zend_Service_Ebay_Finding_Abstract
{
public $item; // Zend_Service_Ebay_Finding_Search_Item_Set
}
{code}

||More types||
{code}
class Zend_Service_Ebay_Finding_ListingInfo extends Zend_Service_Ebay_Finding_Abstract
{
public $bestOfferEnabled; // boolean
public $buyItNowAvailable; // boolean
public $buyItNowPrice; // float
public $buyItNowPrice_currencyId; // string
public $convertedBuyItNowPrice; // float
public $convertedBuyItNowPrice_currencyId; // string
public $endTime; // string
public $gift; // boolean
public $listingType; // string
public $startTime; // string
}

class Zend_Service_Ebay_Finding_PaginationOutput extends Zend_Service_Ebay_Finding_Abstract
{
public $entriesPerPage; // integer
public $pageNumber; // integer
public $totalEntries; // integer
public $totalPages; // integer
}

class Zend_Service_Ebay_Finding_SellerInfo extends Zend_Service_Ebay_Finding_Abstract
{
public $feedbackRatingStar; // string
public $feedbackScore; // integer
public $positiveFeedbackPercent; // float
public $sellerUserName; // string
public $topRatedSeller; // boolean
}

class Zend_Service_Ebay_Finding_SellingStatus extends Zend_Service_Ebay_Finding_Abstract
{
public $bidCount; // integer
public $convertedCurrentPrice; // float
public $convertedCurrentPrice_currencyId; // string
public $currentPrice; // float
public $currentPrice_currencyId; // string
public $sellingState; // string
public $timeLeft; // string
}

class Zend_Service_Ebay_Finding_ShippingInfo extends Zend_Service_Ebay_Finding_Abstract
{
public $shippingServiceCost; // float
public $shippingServiceCost_currencyId; // string
public $shippingType; // string
public $shipToLocations; // array of string
}

class Zend_Service_Ebay_Finding_Storefront extends Zend_Service_Ebay_Finding_Abstract
{
public $storeName; // string
public $storeURL; // string

public function findItems(Zend_Service_Ebay_Finding $proxy, array $options = array());
// return Zend_Service_Ebay_Finding_Response_Items
}
{code}

{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>