Zend Framework: Zend_Service_Rakuten Component Proposal

Proposed Component Name	Zend_Service_Rakuten
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Service_Rakuten
Proposers	TERUI Shingo, Satoru Yoshida Darby Felton, Zend liaison
Revision	0.7 - 26 Dec: update References, Use Cases and Class Skeletons. 0.6 - 19 Dec: update References, Class Index, Use Cases and Class Skeletons. 0.5 - 11 Dec: update References, Use Cases and Class Skeletons. 0.4 - 22 Nov: update all except Dependencies and Milestones. 0.3 - 21 May: update class skeletons. 0.2 - 15 March 2007: add class skeletons. (wiki revision: 19)

Rakuten Web Service
- for the Rakuten Ichiba (Ichiba means shopping mall in japanese.)
  - ItemSearch
    - searchItem() - Search items.
  - GenreSearch
    - searchGenreChildren() - Retrieve genre's child genres.
    - searchGenreParent() - Retrieve genre's parent genre.
    - searchGenre() - Retrieve genre's information
  - ItemCodeSearch
    - searchItemCode() - Retrieve item's information by item code.
  - CatalogSearch
    - searchCatalog() - Search items by catalog.
- for the Rakuten Books
  - BookSearch - searchBook()
  - CDSearch - searchCd()
  - DVDSearch - searchDvd()
- for the Rakuten Auction
  - AuctionItemSearch
    - searchAuctionItem() - Search items.
  - AuctionItemCodeSearch
    - searchAuctionItemCode() - Retrieve item's information by item code
- for the Rakuten Travel
  - SimpleHotelSearch
    - searchSimpleHotel() - Search hotels.
  - HotelDetailSearch
    - searchHotelDetail() - Retrieve hotel's information by hotel number.
  - VacantHotelSearch
    - searchVacantHotelRoom() - Search vacant rooms.
    - searchVacantHotel() - Search hotels that have vacant room.
  - GetAreaClass
    - getAreaClass() - Retrieve choices of area.
  - KeywordHotelSearch
    - searchKeywordHotel() - Search hotels by word.
- Other purpose
  - DynamicAd
    - dynamicAd() - Retrieve dynamic advertisements that is suitable for content in URL that you specify.

3. Component Requirements, Constraints, and Acceptance Criteria

Implements the "Rakuten Web Service" APIs.
Returns server responses as lightweight data objects.

4. Dependencies on Other Framework Components

Zend_Rest_Client
Zend_Service_Exception

5. Theory of Operation

Returns server response as the SimpleXMLElement.

6. Milestones / Tasks

Milestone 1: Class development and write proposal
Milestone 2: Unit tests and debugging
Milestone 3: Documentation

7. Class Index

Zend_Service_Rakuten

8. Use Cases

UC-01

Search 3 items by word, "Zend Studio". Its case is most simple case.

<?php
require_once 'Zend/Service/Rakuten.php';

$rakuten = new Zend_Service_Rakuten(YOUR_DEVELOPER_ID);

$params = array('keyword' => 'Zend Studio', 'hits' => 3);

try {
    $results = $rakuten->searchItem($params);
} catch (Zend_Service_Exception $e) {
    echo $e->getMessage();
    $results = array();
}

foreach ($results as $item) {
    echo '<ul>';
    echo '<li>Item : ' . $item->itemName;
    echo '<li>Code : ' . $item->itemCode;
    echo '<li>Price: ' . $item->itemPrice .'JPY';
    echo '<li><a href="' . $item->itemUrl . '" target="_blanc">';
    echo '<img src="'  . $item->mediumImageUrl . '">';
    echo 'Click to show detail in new window';
    echo '</a>';
    echo '<li>Caption:'. $item->itemCaption;
    echo '</ul>';
    echo '<hr>';
}

UC-02

Retrieve hotels that have vacant room for 1 adult person in the kasukabe city from today to tommorow.
The kasukabe city is in the saitama ward, and the saitama ward is in japan.
The checkinDate and checkoutDate are in Tokyo Time. If you use another time, you must use 3rd parameter of Zend_Service_Rakuten().

<?php
require_once 'Zend/Service/Rakuten.php';

$rakuten = new Zend_Service_Rakuten(YOUR_DEVELOPER_ID);

$params = array('largeClassCode'  => 'japan',
                'middleClassCode' => 'saitama',
                'smallClassCode'  => 'kasukabe',
                'checkinDate'     => (date('Y-m-d', strtotime('today'))),
                'checkoutDate'    => (date('Y-m-d', strtotime('+1 day'))),
                'adultNum'        => 1);

try {
    $results = $this->searchVacantHotel($params);
} catch (Zend_Service_Exception $e) {
    echo $e->getMessage();
    $results = array();
}

foreach ($results as $item) {
    echo '<ul>';
    echo '<li>Name : ' . $item->hotelName;
    echo '<li>Address: ' . $item->address1;
    echo '<li>Tel  :' . $item->telephoneNo;
    echo '</ul>';
}

UC-03

Display advertisements that is suitable for www.zend.com .
dynamicAd() needs affiliate ID in instantiation.

<?php
require_once 'Zend/Service/Rakuten.php';

$rakuten = new Zend_Service_Rakuten(YOUR_DEVELOPER_ID, YOUR_AFFILIATE_ID);

try {
    $results = $this->dynamicAd('http://www.zend.com/');
} catch (Zend_Service_Exception $e) {
    echo $e->getMessage();
    $results = array();
}

foreach ($results as $item) {
    echo '<ul>';
    echo '<li>Name : ' . $item->ItemName;
    echo '<li>Url  : ' . $item->AffiliateItemUrl;
    echo '<li>Rev  : ' . $item->ReviewCount;
    echo '</ul>';
}

9. Class Skeletons

<?php
require_once 'Zend/Rest/Client.php';
require_once 'Zend/Service/Exception.php';

/**
 * Rakuten Web Service API class
 */
class Zend_Service_Rakuten
{
    /**
     * Status from the Rakuten Web Service in success
     *
     * @var string
     */
    const STATUS_OK = 'Success';

    /**
     * Developer's ID in the Rakuten Web Service
     *
     * @var string
     */
    protected $_devId;

    /**
     * Affiliate ID in the Rakuten Web Service
     *
     * @var string
     */
    protected $_affId;

    /**
     * API Version
     *
     * @var array
     */
    protected $_apiVer;

    /**
     * Instantiation
     *
     * @param string $devId developer's ID
     * @param string $affId affiliate ID
     * @param string $zone time zone
     * @param string $encode character encode
     * @return void
     */
    public function __construct($devId, $affId = null, $zone = 'Asia/Tokyo', $encode = 'UTF-8')
    {
        $this->_devId = $devId;
        $this->_affId = $affId;
        date_default_timezone_set($zone);
        ini_set('mbstring.internal_encoding', $encode);
        $this->_apiVer = array('api_rws'      => '1.10',
                               'ItemSearch'   => '2007-10-25', 'ItemCodeSearch' => '2007-04-11',
                               'GenreSearch'  => '2007-04-11', 'CatalogSearch'  => '2007-10-25',
                               'BookSearch'   => '2007-10-25', 'CDSearch'       => '2007-10-25',
                               'DVDSearch'    => '2007-10-25',
                               'AuctionItemSearch'  => '2007-12-13', 'AuctionItemCodeSearch' => '2007-12-13',
                               'SimpleHotelSearch'  => '2007-11-21', 'HotelDetailSearch'  => '2007-11-21',
                               'VacantHotelSearch'  => '2007-11-21', 'KeywordHotelSearch' => '2007-09-19',
                               'GetAreaClass' => '2007-04-11',
                               'DynamicAd'    => '1.0'
                              );
    }

    /**
     * Retrieve version
     *
     * @param string $operation API name
     * @return string
     */
    public function getVersion($operation)
    {
        return $this->_apiVer[$operation];
    }

    /**
     * Set the version
     *
     * @param string $operation API name
     * @param string $version API version
     * @return void
     * @throws Zend_Service_Exception
     */
    public function setVersion($operation, $version)
    {
        if(key_exists($operation, $this->_apiVer) === true){
            $this->_apiVer[$operation] = $version;
            throw new Zend_Service_Exception('Invalid operation provided');
        }
    }

    /**
     * Execute on the Rakuten Web Service
     *
     * @param string $operation API name
     * @param string $xquery xquery
     * @param array  $optparams API option parameters ( name => value )
     * @return array(SimpleXMLElement)
     * @throws Zend_Service_Exception
     */
    protected function _search($operation, $xquery, $optparams = array())
    {
        $path = '/rws/' . $this->_apiVer['api_rws'] . '/rest';

        $params = array_merge(
            array('developerId' => $this->_devId,
                  'affiliateId' => $this->_affId,
                  'operation'   => $operation,
                  'version'     => $this->_apiVer[$operation]),
            $optparams
        );

        $xml = $this->_restClient('http://api.rakuten.co.jp', $path, $params);
        foreach ($xml->getNamespaces(true) as $name => $uri) {
            $xml->registerXPathNamespace($name, $uri);
        }

        $statuses = $xml->xpath('//header:Header/Status');
        $message  = strval($statuses[0]);

        if ($message === self::STATUS_OK){
            return $xml->xpath($xquery);
        }

        throw new Zend_Service_Exception($message);
    }

    /**
     * REST Client
     *
     * @param string $domaim API domain
     * @param string $path API path
     * @param array  $params API parameters ( name => value )
     * @return SimpleXMLElement
     * @throws Zend_Service_Exception
     */
    protected function _restClient($domaim, $path, $params)
    {
        $rest = new Zend_Rest_Client($domaim);

        try {
            $result = $rest->restGet($path, $params);
        } catch (Zend_Rest_Client_Exception $e) {
            throw new Zend_Service_Exception($e->getMessage());
        }

        return new SimpleXMLElement($result->getBody());
    }

    /**
     * Search items from the Rakuten Ichiba.
     *
     * @see http://webservice.rakuten.co.jp/api/itemsearch/
     * @param array $params one of keyword, genreId and catalogCode is mandatory key.
     * @return array array(SimpleXMLElement)
     */
    public function searchItem($params)
    {
        return $this->_search('ItemSearch', '//itemSearch:ItemSearch/Items/Item', $params);
    }

    /**
     * Retrieve genre's children from the Rakuten Ichiba.
     *
     * @see http://webservice.rakuten.co.jp/api/genresearch/
     * @param integer $genreId genre ID
     * @param array $optparams option parameters
     * @return array array(SimpleXMLElement)
     */
    public function searchGenreChildren($genreId = 0, $optparams = array())
    {
        /* The genrePath causes to return parent genre where it is 1.
           But, in this method parent genre is no needed.
        */
        $params = array_merge(
            array('genreId' => $genreId,
                  'genrePath' => 0),
            $optparams
        );

        return $this->_search('GenreSearch', '//genreSearch:GenreSearch/child', $params);
    }

    /**
     * Retrieve genre's parent from the Rakuten Ichiba.
     *
     * @see http://webservice.rakuten.co.jp/api/genresearch/
     * @param integer $genreId genre ID
     * @param array $optparams option parameters
     * @return array array(SimpleXMLElement)
     */
    public function searchGenreParent($genreId, $optparams = array())
    {
        /* The genrePath causes to return parent genre where it is 1.
           In this method parent genre is needed.
        */
        $params = array_merge(
            array('genreId' => $genreId,
                  'genrePath' => 1),
            $optparams
        );

        return $this->_search('GenreSearch', '//genreSearch:GenreSearch/parent', $params);
    }

    /**
     * Retrieve genre's information from the Rakuten Ichiba.
     *
     * @see http://webservice.rakuten.co.jp/api/genresearch/
     * @param integer $genreId genre ID
     * @param array $optparams option parameters
     * @return array array(SimpleXMLElement)
     */
    public function searchGenre($genreId, $optparams = array())
    {
        /* The genrePath causes to return parent genre where it is 1.
           But, in this method parent genre is no needed.
        */
        $params = array_merge(
            array('genreId' => $genreId,
                  'genrePath' => 0),
            $optparams
        );

        return $this->_search('GenreSearch', '//genreSearch:GenreSearch/current', $params);
    }

    /**
     * Retrieve item's information by the item code from the Rakuten Ichiba.
     *
     * @see http://webservice.rakuten.co.jp/api/itemcodesearch/
     * @param string $code item code
     * @param array $optparams option parameters
     * @return array array(SimpleXMLElement)
     */
    public function searchItemCode($code, $optparams = array())
    {
        $params = array_merge(
            array('itemCode' => $code),
            $optparams
        );

        return $this->_search('ItemCodeSearch', '//itemCodeSearch:ItemCodeSearch/Item', $params);
    }

    /**
     * Search items by catalog from the Rakuten Ichiba.
     *
     * @see http://webservice.rakuten.co.jp/api/catalogsearch/
     * @param array $params one of keyword and genreId is mandatory key.
     * @return array array(SimpleXMLElement)
     */
    public function searchCatalog($params)
    {
        return $this->_search('CatalogSearch', '//catalogSearch:CatalogSearch/Catalogs/Catalog', $params);
    }

    /**
     * Search books from the Rakuten books.
     *
     * @see http://webservice.rakuten.co.jp/api/booksearch/
     * @param array $params one of keyword and genreId is mandatory key.
     * @return array array(SimpleXMLElement)
     */
    public function searchBook($params)
    {
        return $this->_search('BookSearch', '//bookSearch:BookSearch/Items/Item', $params);
    }

    /**
     * Search CompactDiscs from the Rakuten books.
     *
     * @see http://webservice.rakuten.co.jp/api/cdsearch/
     * @param array $params one of keyword and genreId is mandatory key.
     * @return array array(SimpleXMLElement)
     */
    public function searchCd($params)
    {
        return $this->_search('CDSearch', '//cdSearch:CDSearch/Items/Item', $params);
    }

    /**
     * Search DVDs from the Rakuten books.
     *
     * @see http://webservice.rakuten.co.jp/api/dvdsearch/
     * @param array $params one of keyword and genreId is mandatory key.
     * @return array array(SimpleXMLElement)
     */
    public function searchDvd($params)
    {
        return $this->_search('DVDSearch', '//dvdSearch:DVDSearch/Items/Item', $params);
    }

    /**
     * Search items from the Rakuten auction.
     *
     * @see http://webservice.rakuten.co.jp/api/auctionitemsearch/
     * @param array $params one of keyword and genreId is mandatory key.
     * @return array array(SimpleXMLElement)
     */
    public function searchAuctionItem($params)
    {
        return $this->_search('AuctionItemSearch', '//auctionItemSearch:AuctionItemSearch/Items/Item', $params);
    }

    /**
     * Retrieve item's information by the item code from the Rakuten auction.
     *
     * @see http://webservice.rakuten.co.jp/api/auctionitemcodesearch/
     * @param string $code item code
     * @param array $optparams option parameters
     * @return array array(SimpleXMLElement)
     */
    public function searchAuctionItemCode($code, $optparams = array())
    {
        $params = array_merge(
            array('itemCode' => $code),
            $optparams
        );

        return $this->_search('AuctionItemCodeSearch', '//auctionItemCodeSearch:AuctionItemCodeSearch/Item', $params);
    }

    /**
     * Search hotels from the Rakuten travel.
     *
     * @see http://webservice.rakuten.co.jp/api/simplehotelsearch/
     * @param array $params one of following key pairs is mandatory.
     *  1:hotelNo.
     *  2:largeClassCode, middleClassCode, smallClassCode, detailClassCode(when it is defined).
     *  3:latitude, longitude.
     * @return array array(SimpleXMLElement)
     */
    public function searchSimpleHotel($params)
    {
        return $this->_search('SimpleHotelSearch', '//simpleHotelSearch:SimpleHotelSearch/hotel', $params);
    }

    /**
     * Retrieve hotel's information by the hotel number from the Rakuten travel.
     *
     * @see http://webservice.rakuten.co.jp/api/hoteldetailsearch/
     * @param integer $hotelNo hotel number
     * @param array $optparams option parameters
     * @return array array(SimpleXMLElement)
     */
    public function searchHotelDetail($hotelNo, $optparams = array())
    {
        $params = array_merge(
            array('hotelNo' => $hotelNo),
            $optparams
        );

        return $this->_search('HotelDetailSearch', '//hotelDetailSearch:HotelDetailSearch', $params);
    }

    /**
     * Search vacant rooms from the Rakuten travel.
     *
     * @see http://webservice.rakuten.co.jp/api/vacanthotelsearch/
     * @param array $params one of following key pairs is mandatory.
     *  1:hotelNo.
     *  2:largeClassCode, middleClassCode, smallClassCode, detailClassCode(when it is defined).
     *  3:latitude, longitude.
     * @return array array(SimpleXMLElement)
     */
    public function searchVacantHotelRoom($params)
    {
        return $this->_search('VacantHotelSearch', '//vacantHotelSearch:VacantHotelSearch/room', $params);
    }

    /**
     * Search hotels that have vacant room from the Rakuten travel.
     *
     * @see http://webservice.rakuten.co.jp/api/vacanthotelsearch/
     * @param array $params one of following key pairs is mandatory.
     *  1:hotelNo.
     *  2:largeClassCode, middleClassCode, smallClassCode, detailClassCode(when it is defined).
     *  3:latitude, longitude.
     * @return array array(SimpleXMLElement)
     */
    public function searchVacantHotel($params)
    {
        return $this->_search('VacantHotelSearch', '//vacantHotelSearch:VacantHotelSearch/hotel', $params);
    }

    /**
     * Retrieve choices of area from the Rakuten travel.
     *
     * @see http://webservice.rakuten.co.jp/api/getareaclass/
     * @return array array(SimpleXMLElement)
     */
    public function getAreaClass()
    {
        return $this->_search('GetAreaClass', '//getAreaClass:GetAreaClass/largeClass');
    }

    /**
     * Search hotels by the word from the Rakuten travel.
     *
     * @see http://webservice.rakuten.co.jp/api/keywordhotelsearch/
     * @param string $word word
     * @param array $optparams option parameters
     * @return array array(SimpleXMLElement)
     */
    public function searchKeywordHotel($word, $optparams  = array())
    {
        $params = array_merge(
            array('keyword' => $word),
            $optparams
        );

        return $this->_search('KeywordHotelSearch', '//keywordHotelSearch:KeywordHotelSearch/hotelSimple', $params);
    }

    /**
     * Retrieve advertisements that is suitable for the url.
     *
     * @see http://webservice.rakuten.co.jp/api/dynamicad/
     * @param string $url url
     * @param array  $optparams API option parameters ( name => value )
     * @return array(SimpleXMLElement)
     * @throws Zend_Service_Exception
     * @link _search()
     */
    public function dynamicAd($url, $optparams  = array())
    {
        $path = '/rcm/' . $this->_apiVer['DynamicAd'] . '/i/rest';

        $params = array_merge(
            array('developerId' => $this->_devId,
                  'affiliateId' => $this->_affId,
                  'url' => $url),
            $optparams
        );

        $xml = $this->_restClient('http://dynamic.rakuten.co.jp', $path, $params);

        $statuses = $xml->Header->Status;
        $message  = strval($statuses[0]);

        if ($message === self::STATUS_OK){
            return $xml->Body->Ads->Ad;
        }

        throw new Zend_Service_Exception($message);
    }
}

Page Operations

Browse Space

Zend_Service_Rakuten - TERUI Shingo

Labels