Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Service_Ebay Component Proposal

Proposed Component Name Zend_Service_Ebay
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Service_Ebay
Proposers Renan de Lima
Don Bosco Nguyen Van Hoi
Ramon Henrique Ornelas
Zend Liaison TBD
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()
  • 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
(wiki revision: 31)

Table of Contents

1. Overview

Zend_Service_Ebay is a component that allows to do request to eBay web services easily.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • This will implement only eBay Finding API
    • 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

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.

Options are translated from php array to eBay array syntax. Example:

6. Milestones / Tasks

  • 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

7. Class Index

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

8. Use Cases

UC-01 Find for items
UC-02 Get histograms
UC-03 Get keywords
UC-04 Service configuration

9. Class Skeletons

General
API proxy
Response
Abstract types
Aspect
Category
Error
Search
More types

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
service service Delete
proposal proposal Delete
finding finding Delete
ebay ebay Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Oct 29, 2009

    <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>

    1. Oct 30, 2009

      <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: { $options = $options->toArray(); }

      if (!is_array($options))

      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>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>

  2. Dec 23, 2009

    <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>

  3. Feb 01, 2010

    <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>

    1. Jun 14, 2010

      <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>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>

      1. Jun 15, 2010

        <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>

  4. Jun 01, 2010

    <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>

    1. Jun 14, 2010

      <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>