library/Zend/Service/Simpy.php

   1 <?php
   2
   3 /**
   4  * Zend Framework
   5  *
   6  * LICENSE
   7  *
   8  * This source file is subject to the new BSD license that is bundled
   9  * with this package in the file LICENSE.txt.
  10  * It is also available through the world-wide-web at this URL:
  11  * http://framework.zend.com/license/new-bsd
  12  * If you did not receive a copy of the license and are unable to
  13  * obtain it through the world-wide-web, please send an email
  14  * to license@zend.com so we can send you a copy immediately.
  15  *
  16  * @category   Zend
  17  * @package    Zend_Service
  18  * @subpackage Simpy
  19  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  20  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  21  * @version    $Id$
  22  */
  23
  24 /**
  25  * @see Zend_Http_Client
  26  */
  27 require_once 'Zend/Http/Client.php';
  28
  29 /**
  30  * @category   Zend
  31  * @package    Zend_Service
  32  * @subpackage Simpy
  33  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  34  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  35  * @link       http://www.simpy.com/doc/api/rest/
  36  */
  37 class Zend_Service_Simpy
  38 {
  39     /**
  40      * Base URI to which API methods and parameters will be appended
  41      *
  42      * @var string
  43      */
  44     protected $_baseUri = 'http://simpy.com/simpy/api/rest/';
  45
  46     /**
  47      * HTTP client for use in making web service calls
  48      *
  49      * @var Zend_Http_Client
  50      */
  51     protected $_http;
  52
  53     /**
  54      * Constructs a new Simpy (free) REST API Client
  55      *
  56      * @param  string $username Username for the Simpy user account
  57      * @param  string $password Password for the Simpy user account
  58      * @return void
  59      */
  60     public function __construct($username, $password)
  61     {
  62         $this->_http = new Zend_Http_Client;
  63         $this->_http->setAuth($username, $password);
  64     }
  65
  66     /**
  67      * Returns the HTTP client currently in use by this class for REST API
  68      * calls, intended mainly for testing.
  69      *
  70      * @return Zend_Http_Client
  71      */
  72     public function getHttpClient()
  73     {
  74         return $this->_http;
  75     }
  76
  77     /**
  78      * Sends a request to the REST API service and does initial processing
  79      * on the response.
  80      *
  81      * @param  string $op    Name of the operation for the request
  82      * @param  array  $query Query data for the request (optional)
  83      * @throws Zend_Service_Exception
  84      * @return DOMDocument Parsed XML response
  85      */
  86     protected function _makeRequest($op, $query = null)
  87     {
  88         if ($query != null) {
  89             $query = array_diff($query, array_filter($query, 'is_null'));
  90             $query = '?' . http_build_query($query);
  91         }
  92
  93         $this->_http->setUri($this->_baseUri . $op . '.do' . $query);
  94         $response = $this->_http->request('GET');
  95
  96         if ($response->isSuccessful()) {
  97             $doc = new DOMDocument();
  98             $doc->loadXML($response->getBody());
  99             $xpath = new DOMXPath($doc);
 100             $list = $xpath->query('/status/code');
 101
 102             if ($list->length > 0) {
 103                 $code = $list->item(0)->nodeValue;
 104
 105                 if ($code != 0) {
 106                     $list = $xpath->query('/status/message');
 107                     $message = $list->item(0)->nodeValue;
 108                     /**
 109                      * @see Zend_Service_Exception
 110                      */
 111                     require_once 'Zend/Service/Exception.php';
 112                     throw new Zend_Service_Exception($message, $code);
 113                 }
 114             }
 115
 116             return $doc;
 117         }
 118
 119         /**
 120          * @see Zend_Service_Exception
 121          */
 122         require_once 'Zend/Service/Exception.php';
 123         throw new Zend_Service_Exception($response->getMessage(), $response->getStatus());
 124     }
 125
 126     /**
 127      * Returns a list of all tags and their counts, ordered by count in
 128      * decreasing order
 129      *
 130      * @param  int $limit Limits the number of tags returned (optional)
 131      * @link   http://www.simpy.com/doc/api/rest/GetTags
 132      * @throws Zend_Service_Exception
 133      * @return Zend_Service_Simpy_TagSet
 134      */
 135     public function getTags($limit = null)
 136     {
 137         $query = array(
 138             'limit' => $limit
 139         );
 140
 141         $doc = $this->_makeRequest('GetTags', $query);
 142
 143         /**
 144          * @see Zend_Service_Simpy_TagSet
 145          */
 146         require_once 'Zend/Service/Simpy/TagSet.php';
 147         return new Zend_Service_Simpy_TagSet($doc);
 148     }
 149
 150     /**
 151      * Removes a tag.
 152      *
 153      * @param  string $tag Tag to be removed
 154      * @link   http://www.simpy.com/doc/api/rest/RemoveTag
 155      * @return Zend_Service_Simpy Provides a fluent interface
 156      */
 157     public function removeTag($tag)
 158     {
 159         $query = array(
 160             'tag' => $tag
 161         );
 162
 163         $this->_makeRequest('RemoveTag', $query);
 164
 165         return $this;
 166     }
 167
 168     /**
 169      * Renames a tag.
 170      *
 171      * @param  string $fromTag Tag to be renamed
 172      * @param  string $toTag   New tag name
 173      * @link   http://www.simpy.com/doc/api/rest/RenameTag
 174      * @return Zend_Service_Simpy Provides a fluent interface
 175      */
 176     public function renameTag($fromTag, $toTag)
 177     {
 178         $query = array(
 179             'fromTag' => $fromTag,
 180             'toTag' => $toTag
 181         );
 182
 183         $this->_makeRequest('RenameTag', $query);
 184
 185         return $this;
 186     }
 187
 188     /**
 189      * Merges two tags into a new tag.
 190      *
 191      * @param  string $fromTag1 First tag to merge.
 192      * @param  string $fromTag2 Second tag to merge.
 193      * @param  string $toTag    Tag to merge the two tags into.
 194      * @link   http://www.simpy.com/doc/api/rest/MergeTags
 195      * @return Zend_Service_Simpy Provides a fluent interface
 196      */
 197     public function mergeTags($fromTag1, $fromTag2, $toTag)
 198     {
 199         $query = array(
 200             'fromTag1' => $fromTag1,
 201             'fromTag2' => $fromTag2,
 202             'toTag' => $toTag
 203         );
 204
 205         $this->_makeRequest('MergeTags', $query);
 206
 207         return $this;
 208     }
 209
 210     /**
 211      * Splits a single tag into two separate tags.
 212      *
 213      * @param  string $tag    Tag to split
 214      * @param  string $toTag1 First tag to split into
 215      * @param  string $toTag2 Second tag to split into
 216      * @link   http://www.simpy.com/doc/api/rest/SplitTag
 217      * @return Zend_Service_Simpy Provides a fluent interface
 218      */
 219     public function splitTag($tag, $toTag1, $toTag2)
 220     {
 221         $query = array(
 222             'tag' => $tag,
 223             'toTag1' => $toTag1,
 224             'toTag2' => $toTag2
 225         );
 226
 227         $this->_makeRequest('SplitTag', $query);
 228
 229         return $this;
 230     }
 231
 232     /**
 233      * Performs a query on existing links and returns the results or returns all
 234      * links if no particular query is specified (which should be used sparingly
 235      * to prevent overloading Simpy servers)
 236      *
 237      * @param  Zend_Service_Simpy_LinkQuery $q Query object to use (optional)
 238      * @return Zend_Service_Simpy_LinkSet
 239      */
 240     public function getLinks(Zend_Service_Simpy_LinkQuery $q = null)
 241     {
 242         if ($q != null) {
 243             $query = array(
 244                 'q'          => $q->getQueryString(),
 245                 'limit'      => $q->getLimit(),
 246                 'date'       => $q->getDate(),
 247                 'afterDate'  => $q->getAfterDate(),
 248                 'beforeDate' => $q->getBeforeDate()
 249             );
 250
 251             $doc = $this->_makeRequest('GetLinks', $query);
 252         } else {
 253             $doc = $this->_makeRequest('GetLinks');
 254         }
 255
 256         /**
 257          * @see Zend_Service_Simpy_LinkSet
 258          */
 259         require_once 'Zend/Service/Simpy/LinkSet.php';
 260         return new Zend_Service_Simpy_LinkSet($doc);
 261     }
 262
 263     /**
 264      * Saves a given link.
 265      *
 266      * @param  string $title       Title of the page to save
 267      * @param  string $href        URL of the page to save
 268      * @param  int    $accessType  ACCESSTYPE_PUBLIC or ACCESSTYPE_PRIVATE
 269      * @param  mixed  $tags        String containing a comma-separated list of
 270      *                             tags or array of strings containing tags
 271      *                             (optional)
 272      * @param  string $urlNickname Alternative custom title (optional)
 273      * @param  string $note        Free text note (optional)
 274      * @link   Zend_Service_Simpy::ACCESSTYPE_PUBLIC
 275      * @link   Zend_Service_Simpy::ACCESSTYPE_PRIVATE
 276      * @link   http://www.simpy.com/doc/api/rest/SaveLink
 277      * @return Zend_Service_Simpy Provides a fluent interface
 278      */
 279     public function saveLink($title, $href, $accessType, $tags = null, $urlNickname = null, $note = null)
 280     {
 281         if (is_array($tags)) {
 282             $tags = implode(',', $tags);
 283         }
 284
 285         $query = array(
 286             'title'       => $title,
 287             'href'        => $href,
 288             'accessType'  => $accessType,
 289             'tags'        => $tags,
 290             'urlNickname' => $urlNickname,
 291             'note'        => $note
 292         );
 293
 294         $this->_makeRequest('SaveLink', $query);
 295
 296         return $this;
 297     }
 298
 299     /**
 300      * Deletes a given link.
 301      *
 302      * @param  string $href URL of the bookmark to delete
 303      * @link   http://www.simpy.com/doc/api/rest/DeleteLink
 304      * @return Zend_Service_Simpy Provides a fluent interface
 305      */
 306     public function deleteLink($href)
 307     {
 308         $query = array(
 309             'href' => $href
 310         );
 311
 312         $this->_makeRequest('DeleteLink', $query);
 313
 314         return $this;
 315     }
 316
 317     /**
 318      * Return a list of watchlists and their meta-data, including the number
 319      * of new links added to each watchlist since last login.
 320      *
 321      * @link   http://www.simpy.com/doc/api/rest/GetWatchlists
 322      * @return Zend_Service_Simpy_WatchlistSet
 323      */
 324     public function getWatchlists()
 325     {
 326         $doc = $this->_makeRequest('GetWatchlists');
 327
 328         /**
 329          * @see Zend_Service_Simpy_WatchlistSet
 330          */
 331         require_once 'Zend/Service/Simpy/WatchlistSet.php';
 332         return new Zend_Service_Simpy_WatchlistSet($doc);
 333     }
 334
 335     /**
 336      * Returns the meta-data for a given watchlist.
 337      *
 338      * @param  int $watchlistId ID of the watchlist to retrieve
 339      * @link   http://www.simpy.com/doc/api/rest/GetWatchlist
 340      * @return Zend_Service_Simpy_Watchlist
 341      */
 342     public function getWatchlist($watchlistId)
 343     {
 344         $query = array(
 345             'watchlistId' => $watchlistId
 346         );
 347
 348         $doc = $this->_makeRequest('GetWatchlist', $query);
 349
 350         /**
 351          * @see Zend_Service_Simpy_Watchlist
 352          */
 353         require_once 'Zend/Service/Simpy/Watchlist.php';
 354         return new Zend_Service_Simpy_Watchlist($doc->documentElement);
 355     }
 356
 357     /**
 358      * Returns all notes in reverse chronological order by add date or by
 359      * rank.
 360      *
 361      * @param  string $q     Query string formatted using Simpy search syntax
 362      *                       and search fields (optional)
 363      * @param  int    $limit Limits the number notes returned (optional)
 364      * @link   http://www.simpy.com/doc/api/rest/GetNotes
 365      * @link   http://www.simpy.com/simpy/FAQ.do#searchSyntax
 366      * @link   http://www.simpy.com/simpy/FAQ.do#searchFieldsLinks
 367      * @return Zend_Service_Simpy_NoteSet
 368      */
 369     public function getNotes($q = null, $limit = null)
 370     {
 371         $query = array(
 372             'q'     => $q,
 373             'limit' => $limit
 374         );
 375
 376         $doc = $this->_makeRequest('GetNotes', $query);
 377
 378         /**
 379          * @see Zend_Service_Simpy_NoteSet
 380          */
 381         require_once 'Zend/Service/Simpy/NoteSet.php';
 382         return new Zend_Service_Simpy_NoteSet($doc);
 383     }
 384
 385     /**
 386      * Saves a note.
 387      *
 388      * @param  string $title       Title of the note
 389      * @param  mixed  $tags        String containing a comma-separated list of
 390      *                             tags or array of strings containing tags
 391      *                             (optional)
 392      * @param  string $description Free-text note (optional)
 393      * @param  int    $noteId      Unique identifier for an existing note to
 394      *                             update (optional)
 395      * @link   http://www.simpy.com/doc/api/rest/SaveNote
 396      * @return Zend_Service_Simpy Provides a fluent interface
 397      */
 398     public function saveNote($title, $tags = null, $description = null, $noteId = null)
 399     {
 400         if (is_array($tags)) {
 401             $tags = implode(',', $tags);
 402         }
 403
 404         $query = array(
 405             'title'       => $title,
 406             'tags'        => $tags,
 407             'description' => $description,
 408             'noteId'      => $noteId
 409         );
 410
 411         $this->_makeRequest('SaveNote', $query);
 412
 413         return $this;
 414     }
 415
 416     /**
 417      * Deletes a given note.
 418      *
 419      * @param  int $noteId ID of the note to delete
 420      * @link   http://www.simpy.com/doc/api/rest/DeleteNote
 421      * @return Zend_Service_Simpy Provides a fluent interface
 422      */
 423     public function deleteNote($noteId)
 424     {
 425         $query = array(
 426             'noteId' => $noteId
 427         );
 428
 429         $this->_makeRequest('DeleteNote', $query);
 430
 431         return $this;
 432     }
 433 }