/zf/library/Zend/Service/Ebay/Abstract.php

  1<?php
  2/**
  3 * Zend Framework
  4 *
  5 * LICENSE
  6 *
  7 * This source file is subject to the new BSD license that is bundled
  8 * with this package in the file LICENSE.txt.
  9 * It is also available through the world-wide-web at this URL:
 10 * http://framework.zend.com/license/new-bsd
 11 * If you did not receive a copy of the license and are unable to
 12 * obtain it through the world-wide-web, please send an email
 13 * to license@zend.com so we can send you a copy immediately.
 14 *
 15 * @category   Zend
 16 * @package    Zend_Service
 17 * @subpackage Ebay
 18 * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
 19 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 20 * @version    $Id: Abstract.php 22824 2010-08-09 18:59:54Z renanbr $
 21 */
 22
 23/**
 24 * @category   Zend
 25 * @package    Zend_Service
 26 * @subpackage Ebay
 27 * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
 28 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 29 */
 30abstract class Zend_Service_Ebay_Abstract
 31{
 32    const OPTION_APP_ID    = 'app_id';
 33    const OPTION_GLOBAL_ID = 'global_id';
 34
 35    /**
 36     * @var array
 37     */
 38    protected $_options = array();
 39
 40    /**
 41     * @var mixed
 42     */
 43    protected $_client;
 44
 45    /**
 46     * @param  Zend_Config|array $options
 47     * @return void
 48     */
 49    public function __construct($options = null)
 50    {
 51        $options = self::optionsToArray($options);
 52        $this->setOption($options);
 53    }
 54
 55    /**
 56     * @param  string|Zend_Config|array $name
 57     * @param  mixed                    $value
 58     * @return Zend_Service_Ebay_Abstract Provides a fluent interface
 59     */
 60    public function setOption($name, $value = null)
 61    {
 62        if ($name instanceof Zend_Config) {
 63            $name = $name->toArray();
 64        }
 65        if (is_array($name)) {
 66            $this->_options = $name + $this->_options;
 67        } else {
 68            $this->_options[$name] = $value;
 69        }
 70        return $this;
 71    }
 72
 73    /**
 74     * @param  string $name
 75     * @return mixed
 76     */
 77    public function getOption($name = null)
 78    {
 79        if (null === $name) {
 80            return $this->_options;
 81        }
 82        if ($this->hasOption($name)) {
 83            return $this->_options[$name];
 84        }
 85        return null;
 86    }
 87
 88    /**
 89     * @param string $name
 90     * @return boolean
 91     */
 92    public function hasOption($name)
 93    {
 94        return array_key_exists($name, $this->_options);
 95    }
 96
 97    /**
 98     * @param  mixed $client
 99     * @return Zend_Service_Ebay_Abstract Provides a fluent interface
100     */
101    abstract public function setClient($client);
102
103    /**
104     * @return mixed
105     */
106    abstract public function getClient();
107
108    /**
109     * @param  Zend_Config|array $options
110     * @throws Zend_Service_Ebay_Finding_Exception When $options is not an array neither a Zend_Config object
111     * @return array
112     */
113    public static function optionsToArray($options)
114    {
115        if (null === $options) {
116            $options = array();
117        } else if ($options instanceof Zend_Config) {
118            $options = $options->toArray();
119        }
120
121        if (!is_array($options)) {
122            /**
123             * @see Zend_Service_Ebay_Exception
124             */
125            require_once 'Zend/Service/Ebay/Exception.php';
126            throw new Zend_Service_Ebay_Exception('Invalid options provided.');
127        }
128
129        return $options;
130    }
131
132    /**
133     * Implements Name-value Syntax translator.
134     *
135     * Example:
136     *
137     * array(
138     *     'paginationInput' => array(
139     *         'entriesPerPage' => 5,
140     *         'pageNumber'     => 2
141     *     ),
142     *     'itemFilter' => array(
143     *         array(
144     *             'name'       => 'MaxPrice',
145     *             'value'      => 25,
146     *             'paramName'  => 'Currency',
147     *             'paramValue' => 'USD'
148     *         ),
149     *         array(
150     *             'name'  => 'FreeShippingOnly',
151     *             'value' => true
152     *         ),
153     *         array(
154     *             'name'  => 'ListingType',
155     *             'value' => array(
156     *                 'AuctionWithBIN',
157     *                 'FixedPrice',
158     *                 'StoreInventory'
159     *             )
160     *         )
161     *     ),
162     *     'productId' => array(
163     *         ''     => 123,
164     *         'type' => 'UPC'
165     *     )
166     * )
167     *
168     * this above is translated to
169     *
170     * array(
171     *     'paginationInput.entriesPerPage' => '5',
172     *     'paginationInput.pageNumber'     => '2',
173     *     'itemFilter(0).name'             => 'MaxPrice',
174     *     'itemFilter(0).value'            => '25',
175     *     'itemFilter(0).paramName'        => 'Currency',
176     *     'itemFilter(0).paramValue'       => 'USD',
177     *     'itemFilter(1).name'             => 'FreeShippingOnly',
178     *     'itemFilter(1).value'            => '1',
179     *     'itemFilter(2).name'             => 'ListingType',
180     *     'itemFilter(2).value(0)'         => 'AuctionWithBIN',
181     *     'itemFilter(2).value(1)'         => 'FixedPrice',
182     *     'itemFilter(2).value(2)'         => 'StoreInventory',
183     *     'productId'                      => '123',
184     *     'productId.@type'                => 'UPC'
185     * )
186     *
187     * @param  Zend_Config|array $options
188     * @link   http://developer.ebay.com/DevZone/finding/Concepts/MakingACall.html#nvsyntax
189     * @return array A simple array of strings
190     */
191    protected function _optionsToNameValueSyntax($options)
192    {
193        $options  = self::optionsToArray($options);
194        ksort($options);
195        $new      = array();
196        $runAgain = false;
197        foreach ($options as $name => $value) {
198            if (is_array($value)) {
199                // parse an array value, check if it is associative
200                $keyRaw    = array_keys($value);
201                $keyNumber = range(0, count($value) - 1);
202                $isAssoc   = count(array_diff($keyRaw, $keyNumber)) > 0;
203                // check for tag representation, like <name att="sometinhg"></value>
204                // empty key refers to text value
205                // when there is a root tag, attributes receive flags
206                $hasAttribute = array_key_exists('', $value);
207                foreach ($value as $subName => $subValue) {
208                    // generate new key name
209                    if ($isAssoc) {
210                        // named keys
211                        $newName = $name;
212                        if ($subName !== '') {
213                            // when $subName is empty means that current value
214                            // is the main value for the main key
215                            $glue     = $hasAttribute ? '.@' : '.';
216                            $newName .= $glue . $subName;
217                        }
218                    } else {
219                        // numeric keys
220                        $newName = $name . '(' . $subName . ')';
221                    }
222                    // save value
223                    if (is_array($subValue)) {
224                        // it is necessary run this again, value is an array
225                        $runAgain = true;
226                    } else {
227                        // parse basic type
228                        $subValue = self::toEbayValue($subValue);
229                    }
230                    $new[$newName] = $subValue;
231                }
232            } else {
233                // parse basic type
234                $new[$name] = self::toEbayValue($value);
235            }
236        }
237        if ($runAgain) {
238            // this happens if any $subValue found is an array
239            $new = $this->_optionsToNameValueSyntax($new);
240        }
241        return $new;
242    }
243
244    /**
245     * Translate native PHP values format to ebay format for request.
246     *
247     * Boolean is translated to "0" or "1", date object generates ISO 8601,
248     * everything else is translated to string.
249     *
250     * @param  mixed $value
251     * @return string
252     */
253    public static function toEbayValue($value)
254    {
255        if (is_bool($value)) {
256            $value = $value ? '1' : '0';
257        } else if ($value instanceof Zend_Date) {
258            $value = $value->getIso();
259        } else if ($value instanceof DateTime) {
260            $value = $value->format(DateTime::ISO8601);
261        } else {
262            $value = (string) $value;
263        }
264        return $value;
265    }
266
267    /**
268     * Translate an ebay value format to native PHP type.
269     *
270     * @param  string $value
271     * @param  string $type
272     * @see    http://developer.ebay.com/DevZone/finding/CallRef/types/simpleTypes.html
273     * @throws Zend_Service_Ebay_Finding_Exception When $type is not valid
274     * @return mixed
275     */
276    public static function toPhpValue($value, $type)
277    {
278        switch ($type) {
279            // cast for: boolean
280            case 'boolean':
281                $value = (string) $value == 'true';
282                break;
283
284            // cast for: Amount, decimal, double, float, MeasureType
285            case 'float':
286                $value = floatval((string) $value);
287                break;
288
289            // cast for: int, long
290            // integer type generates a string value, because 32 bit systems
291            // have an integer range of -2147483648 to 2147483647
292            case 'integer':
293                // break intentionally omitted
294
295            // cast for: anyURI, base64Binary, dateTime, duration, string, token
296            case 'string':
297                $value = (string) $value;
298                break;
299
300            default:
301                /**
302                 * @see Zend_Service_Ebay_Exception
303                 */
304                require_once 'Zend/Service/Ebay/Exception.php';
305                throw new Zend_Service_Ebay_Exception("Invalid type '{$type}'.");
306        }
307        return $value;
308    }
309}