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
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
This will accept features that allow to make request to every API avaliable at eBay Webservices API
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
4. Dependencies on Other Framework Components
Zend_Rest
Zend_Service_Exception
5. Theory of 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.
<ac:macro ac:name="note"><ac:parameter ac:name="title">Zend Acceptance</ac:parameter><ac:rich-text-body>
<p>This proposal is accepted for immediate development in the standard incubator. We have the following requests/questions:</p>
<ul>
<li>Constructors should accept an assoc array or Zend_Config object as the sole argument. This allows for simplified dependency injection, and is a pattern we've been promoting for some time now; it provides some consistency to the framework.</li>
<li>Why are you defining error classes instead of exceptions? The latter are the preferred mechanism for reporting errors within ZF, and should generally be used.</li>
</ul>
</ac:rich-text-body></ac:macro>
<p>follow some messages between me and Mathew by email</p>
<ac:macro ac:name="noformat"><ac:plain-text-body><![CDATA[Constructors should accept an assoc array or Zend_Config object as the sole argument. This allows for simplified dependency injection, and is a pattern we've been promoting for some time now; it provides some consistency to the framework.
To be clear: it should accept both either assoc array or a
Zend_Config object – both should be considered valid arguments. As an
example:
class Foo
{
public function __construct($options = array())
{
if ($options instanceof Zend_Config)
Unknown macro: { throw new Exception('Invalid options provided'); }
// ...
}
]]></ac:plain-text-body></ac:macro>
<p>sure, we will allow this for constructors</p>
<ac:macro ac:name="noformat"><ac:plain-text-body><![CDATA[Why are you defining error classes instead of exceptions? The latter are the preferred mechanism for reporting errors within ZF, and should generally be used.]]></ac:plain-text-body></ac:macro>
<p>actually, the error class doesn't mean exception, ebay returns us XML, so the idea is provide a easy way to handle this, the error class represents a simple tag into xml, sometimes ebay give us a xml with response <strong>AND</strong> some erros, like a PHP "notice"... but when the severity error is "Error" Zend_Service_Ebay will throw an exception</p>
<p>so i think users should be able to access warning messages when a "Warning" is returned, but we should throw a exception when severity is "Error"</p>
<ac:macro ac:name="noformat"><ac:plain-text-body><![CDATA[Okay, this makes sense. It wasn't clear from the proposal, so I just
wanted to understand the purpose of the class. Thanks!]]></ac:plain-text-body></ac:macro>
<p>news! I've commited files to incubator, now there is a working implemantation <ac:emoticon ac:name="smile" /> . It had to change some little things, just details, nothing very problematic. I will update this proposal wiki entry soon.</p>
<p>Nice work. I'm looking at your code in preparation for a project using eBay Trading API, but I've got a concern about how this will fit in with your structure.</p>
<p>It looks like your Zend_Service_Ebay_Abstract class makes the assumption that we are always communicating with eBay via REST. The Trading API supports XML/HTTPs or SOAP, not REST. Should the REST-related methods be in Zend_Service_Ebay_Finding since they don't appear to apply to all APIs?</p>
<p>Nice notice about REST providing in Ebay_Abstract. My goal was Ebay_Abstract could work as a connector factory, in the future it could provide for extended class others connectors like SOAP or raw HTTP. This time the class provides only Rest because Finding require this.</p>
<p>Anyway I agree what you saying. I think we can improve this one. Ebay_Abstract could define two abstract methods: setClient($client) and getClient() Each class that extends Ebay_Abstract must implement those</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
/**
@param mixed $client
@return Zend_Service_Ebay_Abstract Provides a fluent interface
*/
abstract public function setClient($client);
/**
@return mixed
*/
abstract public function getClient();
]]></ac:plain-text-body></ac:macro>
<p>This suggestion will change the API approved in this proposal, but i think it's a good improvement. Please send me your feedback.</p>
<p>Sorry, I did not know there was an issue tracker for incubator classes. I just created <a href="http://framework.zend.com/issues/browse/ZFINC-129">ZFINC-129</a>.</p>
<p>Quick note, for PHP 5.3 future proofing, you will need to change your constant named "NAMESPACE" in the Zend_Service_Ebay_Finding class as it is a newly reserved word.</p>
8 Comments
comments.show.hideOct 29, 2009
Matthew Weier O'Phinney
<ac:macro ac:name="note"><ac:parameter ac:name="title">Zend Acceptance</ac:parameter><ac:rich-text-body>
<p>This proposal is accepted for immediate development in the standard incubator. We have the following requests/questions:</p>
<ul>
<li>Constructors should accept an assoc array or Zend_Config object as the sole argument. This allows for simplified dependency injection, and is a pattern we've been promoting for some time now; it provides some consistency to the framework.</li>
<li>Why are you defining error classes instead of exceptions? The latter are the preferred mechanism for reporting errors within ZF, and should generally be used.</li>
</ul>
</ac:rich-text-body></ac:macro>
Oct 30, 2009
Renan de Lima
<p>follow some messages between me and Mathew by email</p>
<ac:macro ac:name="noformat"><ac:plain-text-body><![CDATA[Constructors should accept an assoc array or Zend_Config object as the sole argument. This allows for simplified dependency injection, and is a pattern we've been promoting for some time now; it provides some consistency to the framework.
To be clear: it should accept both either assoc array or a
Zend_Config object – both should be considered valid arguments. As an
example:
class Foo
{
public function __construct($options = array())
{
if ($options instanceof Zend_Config)
if (!is_array($options))
// ...
}
]]></ac:plain-text-body></ac:macro>
<p>sure, we will allow this for constructors</p>
<ac:macro ac:name="noformat"><ac:plain-text-body><![CDATA[Why are you defining error classes instead of exceptions? The latter are the preferred mechanism for reporting errors within ZF, and should generally be used.]]></ac:plain-text-body></ac:macro>
<p>actually, the error class doesn't mean exception, ebay returns us XML, so the idea is provide a easy way to handle this, the error class represents a simple tag into xml, sometimes ebay give us a xml with response <strong>AND</strong> some erros, like a PHP "notice"... but when the severity error is "Error" Zend_Service_Ebay will throw an exception</p>
<p>look at this: <a class="external-link" href="http://developer.ebay.com/DevZone/finding/CallRef/types/ErrorData.html">http://developer.ebay.com/DevZone/finding/CallRef/types/ErrorData.html</a><br />
and this one: <a class="external-link" href="http://developer.ebay.com/DevZone/finding/CallRef/types/ErrorSeverity.html">http://developer.ebay.com/DevZone/finding/CallRef/types/ErrorSeverity.html</a><br />
text from later one: "The request was successfully processed, but eBay encountered a non-fatal error during the processing that could affect the data returned...."</p>
<p>so i think users should be able to access warning messages when a "Warning" is returned, but we should throw a exception when severity is "Error"</p>
<ac:macro ac:name="noformat"><ac:plain-text-body><![CDATA[Okay, this makes sense. It wasn't clear from the proposal, so I just
wanted to understand the purpose of the class. Thanks!]]></ac:plain-text-body></ac:macro>
Dec 23, 2009
Renan de Lima
<p>news! I've commited files to incubator, now there is a working implemantation <ac:emoticon ac:name="smile" /> . It had to change some little things, just details, nothing very problematic. I will update this proposal wiki entry soon.</p>
<p>i'm working on unit tests</p>
Feb 01, 2010
Patrick Schwisow
<p>Nice work. I'm looking at your code in preparation for a project using eBay Trading API, but I've got a concern about how this will fit in with your structure.</p>
<p>It looks like your Zend_Service_Ebay_Abstract class makes the assumption that we are always communicating with eBay via REST. The Trading API supports XML/HTTPs or SOAP, not REST. Should the REST-related methods be in Zend_Service_Ebay_Finding since they don't appear to apply to all APIs?</p>
Jun 14, 2010
Renan de Lima
<p>Nice notice about REST providing in Ebay_Abstract. My goal was Ebay_Abstract could work as a connector factory, in the future it could provide for extended class others connectors like SOAP or raw HTTP. This time the class provides only Rest because Finding require this.</p>
<p>Anyway I agree what you saying. I think we can improve this one. Ebay_Abstract could define two abstract methods: setClient($client) and getClient() Each class that extends Ebay_Abstract must implement those</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
/**
*/
abstract public function setClient($client);
/**
*/
abstract public function getClient();
]]></ac:plain-text-body></ac:macro>
<p>This suggestion will change the API approved in this proposal, but i think it's a good improvement. Please send me your feedback.</p>
<p>Please, add a issue
<a class="external-link" href="http://framework.zend.com/issues/browse/ZFINC">http://framework.zend.com/issues/browse/ZFINC</a></p>
Jun 15, 2010
Patrick Schwisow
<p>Sorry, I did not know there was an issue tracker for incubator classes. I just created <a href="http://framework.zend.com/issues/browse/ZFINC-129">ZFINC-129</a>.</p>
Jun 01, 2010
Ryan Horn
<p>Quick note, for PHP 5.3 future proofing, you will need to change your constant named "NAMESPACE" in the Zend_Service_Ebay_Finding class as it is a newly reserved word.</p>
Jun 14, 2010
Renan de Lima
<p>sure!</p>
<p>i'm gonna change this from NAMESPACE to XML_NAMESPACE or XML_NS</p>
<p>please, for next issues use also
<a class="external-link" href="http://framework.zend.com/issues/browse/ZFINC">http://framework.zend.com/issues/browse/ZFINC</a></p>
<p>thanks for reporting</p>