Zend/Gdata/Photos.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_Gdata
  18  * @subpackage Photos
  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
  22  */
  23
  24 /**
  25  * @see Zend_Gdata
  26  */
  27 require_once 'Zend/Gdata.php';
  28
  29 /**
  30  * @see Zend_Gdata_Photos_UserFeed
  31  */
  32 require_once 'Zend/Gdata/Photos/UserFeed.php';
  33
  34 /**
  35  * @see Zend_Gdata_Photos_AlbumFeed
  36  */
  37 require_once 'Zend/Gdata/Photos/AlbumFeed.php';
  38
  39 /**
  40  * @see Zend_Gdata_Photos_PhotoFeed
  41  */
  42 require_once 'Zend/Gdata/Photos/PhotoFeed.php';
  43
  44 /**
  45  * Service class for interacting with the Google Photos Data API.
  46  *
  47  * Like other service classes in this module, this class provides access via
  48  * an HTTP client to Google servers for working with entries and feeds.
  49  *
  50  * @link http://code.google.com/apis/picasaweb/gdata.html
  51  *
  52  * @category   Zend
  53  * @package    Zend_Gdata
  54  * @subpackage Photos
  55  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  56  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  57  */
  58 class Zend_Gdata_Photos extends Zend_Gdata
  59 {
  60
  61     const PICASA_BASE_URI = 'http://picasaweb.google.com/data';
  62     const PICASA_BASE_FEED_URI = 'http://picasaweb.google.com/data/feed';
  63     const AUTH_SERVICE_NAME = 'lh2';
  64
  65     /**
  66      * Default projection when interacting with the Picasa server.
  67      */
  68     const DEFAULT_PROJECTION = 'api';
  69
  70     /**
  71      * The default visibility to filter events by.
  72      */
  73     const DEFAULT_VISIBILITY = 'all';
  74
  75     /**
  76      * The default user to retrieve feeds for.
  77      */
  78     const DEFAULT_USER = 'default';
  79
  80     /**
  81      * Path to the user feed on the Picasa server.
  82      */
  83     const USER_PATH = 'user';
  84
  85     /**
  86      * Path to album feeds on the Picasa server.
  87      */
  88     const ALBUM_PATH = 'albumid';
  89
  90     /**
  91      * Path to photo feeds on the Picasa server.
  92      */
  93     const PHOTO_PATH = 'photoid';
  94
  95     /**
  96      * The path to the community search feed on the Picasa server.
  97      */
  98     const COMMUNITY_SEARCH_PATH = 'all';
  99
 100     /**
 101      * The path to use for finding links to feeds within entries
 102      */
 103     const FEED_LINK_PATH = 'http://schemas.google.com/g/2005#feed';
 104
 105     /**
 106      * The path to use for the determining type of an entry
 107      */
 108     const KIND_PATH = 'http://schemas.google.com/g/2005#kind';
 109
 110     /**
 111      * Namespaces used for Zend_Gdata_Photos
 112      *
 113      * @var array
 114      */
 115     public static $namespaces = array(
 116         array('gphoto', 'http://schemas.google.com/photos/2007', 1, 0),
 117         array('photo', 'http://www.pheed.com/pheed/', 1, 0),
 118         array('exif', 'http://schemas.google.com/photos/exif/2007', 1, 0),
 119         array('georss', 'http://www.georss.org/georss', 1, 0),
 120         array('gml', 'http://www.opengis.net/gml', 1, 0),
 121         array('media', 'http://search.yahoo.com/mrss/', 1, 0)
 122     );
 123
 124     /**
 125      * Create Zend_Gdata_Photos object
 126      *
 127      * @param Zend_Http_Client $client (optional) The HTTP client to use when
 128      *          when communicating with the servers.
 129      * @param string $applicationId The identity of the app in the form of Company-AppName-Version
 130      */
 131     public function __construct($client = null, $applicationId = 'MyCompany-MyApp-1.0')
 132     {
 133         $this->registerPackage('Zend_Gdata_Photos');
 134         $this->registerPackage('Zend_Gdata_Photos_Extension');
 135         parent::__construct($client, $applicationId);
 136         $this->_httpClient->setParameterPost('service', self::AUTH_SERVICE_NAME);
 137     }
 138
 139     /**
 140      * Retrieve a UserFeed containing AlbumEntries, PhotoEntries and
 141      * TagEntries associated with a given user.
 142      *
 143      * @param string $userName The userName of interest
 144      * @param mixed $location (optional) The location for the feed, as a URL
 145      *          or Query. If not provided, a default URL will be used instead.
 146      * @return Zend_Gdata_Photos_UserFeed
 147      * @throws Zend_Gdata_App_Exception
 148      * @throws Zend_Gdata_App_HttpException
 149      */
 150     public function getUserFeed($userName = null, $location = null)
 151     {
 152         if ($location instanceof Zend_Gdata_Photos_UserQuery) {
 153             $location->setType('feed');
 154             if ($userName !== null) {
 155                 $location->setUser($userName);
 156             }
 157             $uri = $location->getQueryUrl();
 158         } else if ($location instanceof Zend_Gdata_Query) {
 159             if ($userName !== null) {
 160                 $location->setUser($userName);
 161             }
 162             $uri = $location->getQueryUrl();
 163         } else if ($location !== null) {
 164             $uri = $location;
 165         } else if ($userName !== null) {
 166             $uri = self::PICASA_BASE_FEED_URI . '/' .
 167                 self::DEFAULT_PROJECTION . '/' . self::USER_PATH . '/' .
 168                 $userName;
 169         } else {
 170             $uri = self::PICASA_BASE_FEED_URI . '/' .
 171                 self::DEFAULT_PROJECTION . '/' . self::USER_PATH . '/' .
 172                 self::DEFAULT_USER;
 173         }
 174
 175         return parent::getFeed($uri, 'Zend_Gdata_Photos_UserFeed');
 176     }
 177
 178     /**
 179      * Retreive AlbumFeed object containing multiple PhotoEntry or TagEntry
 180      * objects.
 181      *
 182      * @param mixed $location (optional) The location for the feed, as a URL or Query.
 183      * @return Zend_Gdata_Photos_AlbumFeed
 184      * @throws Zend_Gdata_App_Exception
 185      * @throws Zend_Gdata_App_HttpException
 186      */
 187     public function getAlbumFeed($location = null)
 188     {
 189         if ($location === null) {
 190             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 191             throw new Zend_Gdata_App_InvalidArgumentException(
 192                     'Location must not be null');
 193         } else if ($location instanceof Zend_Gdata_Photos_UserQuery) {
 194             $location->setType('feed');
 195             $uri = $location->getQueryUrl();
 196         } else if ($location instanceof Zend_Gdata_Query) {
 197             $uri = $location->getQueryUrl();
 198         } else {
 199             $uri = $location;
 200         }
 201         return parent::getFeed($uri, 'Zend_Gdata_Photos_AlbumFeed');
 202     }
 203
 204     /**
 205      * Retreive PhotoFeed object containing comments and tags associated
 206      * with a given photo.
 207      *
 208      * @param mixed $location (optional) The location for the feed, as a URL
 209      *          or Query. If not specified, the community search feed will
 210      *          be returned instead.
 211      * @return Zend_Gdata_Photos_PhotoFeed
 212      * @throws Zend_Gdata_App_Exception
 213      * @throws Zend_Gdata_App_HttpException
 214      */
 215     public function getPhotoFeed($location = null)
 216     {
 217         if ($location === null) {
 218             $uri = self::PICASA_BASE_FEED_URI . '/' .
 219                 self::DEFAULT_PROJECTION . '/' .
 220                 self::COMMUNITY_SEARCH_PATH;
 221         } else if ($location instanceof Zend_Gdata_Photos_UserQuery) {
 222             $location->setType('feed');
 223             $uri = $location->getQueryUrl();
 224         } else if ($location instanceof Zend_Gdata_Query) {
 225             $uri = $location->getQueryUrl();
 226         } else {
 227             $uri = $location;
 228         }
 229         return parent::getFeed($uri, 'Zend_Gdata_Photos_PhotoFeed');
 230     }
 231
 232     /**
 233      * Retreive a single UserEntry object.
 234      *
 235      * @param mixed $location The location for the feed, as a URL or Query.
 236      * @return Zend_Gdata_Photos_UserEntry
 237      * @throws Zend_Gdata_App_Exception
 238      * @throws Zend_Gdata_App_HttpException
 239      */
 240     public function getUserEntry($location)
 241     {
 242         if ($location === null) {
 243             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 244             throw new Zend_Gdata_App_InvalidArgumentException(
 245                     'Location must not be null');
 246         } else if ($location instanceof Zend_Gdata_Photos_UserQuery) {
 247             $location->setType('entry');
 248             $uri = $location->getQueryUrl();
 249         } else if ($location instanceof Zend_Gdata_Query) {
 250             $uri = $location->getQueryUrl();
 251         } else {
 252             $uri = $location;
 253         }
 254         return parent::getEntry($uri, 'Zend_Gdata_Photos_UserEntry');
 255     }
 256
 257     /**
 258      * Retreive a single AlbumEntry object.
 259      *
 260      * @param mixed $location The location for the feed, as a URL or Query.
 261      * @return Zend_Gdata_Photos_AlbumEntry
 262      * @throws Zend_Gdata_App_Exception
 263      * @throws Zend_Gdata_App_HttpException
 264      */
 265     public function getAlbumEntry($location)
 266     {
 267         if ($location === null) {
 268             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 269             throw new Zend_Gdata_App_InvalidArgumentException(
 270                     'Location must not be null');
 271         } else if ($location instanceof Zend_Gdata_Photos_UserQuery) {
 272             $location->setType('entry');
 273             $uri = $location->getQueryUrl();
 274         } else if ($location instanceof Zend_Gdata_Query) {
 275             $uri = $location->getQueryUrl();
 276         } else {
 277             $uri = $location;
 278         }
 279         return parent::getEntry($uri, 'Zend_Gdata_Photos_AlbumEntry');
 280     }
 281
 282     /**
 283      * Retreive a single PhotoEntry object.
 284      *
 285      * @param mixed $location The location for the feed, as a URL or Query.
 286      * @return Zend_Gdata_Photos_PhotoEntry
 287      * @throws Zend_Gdata_App_Exception
 288      * @throws Zend_Gdata_App_HttpException
 289      */
 290     public function getPhotoEntry($location)
 291     {
 292         if ($location === null) {
 293             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 294             throw new Zend_Gdata_App_InvalidArgumentException(
 295                     'Location must not be null');
 296         } else if ($location instanceof Zend_Gdata_Photos_UserQuery) {
 297             $location->setType('entry');
 298             $uri = $location->getQueryUrl();
 299         } else if ($location instanceof Zend_Gdata_Query) {
 300             $uri = $location->getQueryUrl();
 301         } else {
 302             $uri = $location;
 303         }
 304         return parent::getEntry($uri, 'Zend_Gdata_Photos_PhotoEntry');
 305     }
 306
 307     /**
 308      * Retreive a single TagEntry object.
 309      *
 310      * @param mixed $location The location for the feed, as a URL or Query.
 311      * @return Zend_Gdata_Photos_TagEntry
 312      * @throws Zend_Gdata_App_Exception
 313      * @throws Zend_Gdata_App_HttpException
 314      */
 315     public function getTagEntry($location)
 316     {
 317         if ($location === null) {
 318             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 319             throw new Zend_Gdata_App_InvalidArgumentException(
 320                     'Location must not be null');
 321         } else if ($location instanceof Zend_Gdata_Photos_UserQuery) {
 322             $location->setType('entry');
 323             $uri = $location->getQueryUrl();
 324         } else if ($location instanceof Zend_Gdata_Query) {
 325             $uri = $location->getQueryUrl();
 326         } else {
 327             $uri = $location;
 328         }
 329         return parent::getEntry($uri, 'Zend_Gdata_Photos_TagEntry');
 330     }
 331
 332     /**
 333      * Retreive a single CommentEntry object.
 334      *
 335      * @param mixed $location The location for the feed, as a URL or Query.
 336      * @return Zend_Gdata_Photos_CommentEntry
 337      * @throws Zend_Gdata_App_Exception
 338      * @throws Zend_Gdata_App_HttpException
 339      */
 340     public function getCommentEntry($location)
 341     {
 342         if ($location === null) {
 343             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 344             throw new Zend_Gdata_App_InvalidArgumentException(
 345                     'Location must not be null');
 346         } else if ($location instanceof Zend_Gdata_Photos_UserQuery) {
 347             $location->setType('entry');
 348             $uri = $location->getQueryUrl();
 349         } else if ($location instanceof Zend_Gdata_Query) {
 350             $uri = $location->getQueryUrl();
 351         } else {
 352             $uri = $location;
 353         }
 354         return parent::getEntry($uri, 'Zend_Gdata_Photos_CommentEntry');
 355     }
 356
 357     /**
 358      * Create a new album from a AlbumEntry.
 359      *
 360      * @param Zend_Gdata_Photos_AlbumEntry $album The album entry to
 361      *          insert.
 362      * @param string $url (optional) The URI that the album should be
 363      *          uploaded to. If null, the default album creation URI for
 364      *          this domain will be used.
 365      * @return Zend_Gdata_Photos_AlbumEntry The inserted album entry as
 366      *          returned by the server.
 367      * @throws Zend_Gdata_App_Exception
 368      * @throws Zend_Gdata_App_HttpException
 369      */
 370     public function insertAlbumEntry($album, $uri = null)
 371     {
 372         if ($uri === null) {
 373             $uri = self::PICASA_BASE_FEED_URI . '/' .
 374                 self::DEFAULT_PROJECTION . '/' . self::USER_PATH . '/' .
 375                 self::DEFAULT_USER;
 376         }
 377         $newEntry = $this->insertEntry($album, $uri, 'Zend_Gdata_Photos_AlbumEntry');
 378         return $newEntry;
 379     }
 380
 381     /**
 382      * Create a new photo from a PhotoEntry.
 383      *
 384      * @param Zend_Gdata_Photos_PhotoEntry $photo The photo to insert.
 385      * @param string $url The URI that the photo should be uploaded
 386      *          to. Alternatively, an AlbumEntry can be provided and the
 387      *          photo will be added to that album.
 388      * @return Zend_Gdata_Photos_PhotoEntry The inserted photo entry
 389      *          as returned by the server.
 390      * @throws Zend_Gdata_App_Exception
 391      * @throws Zend_Gdata_App_HttpException
 392      */
 393     public function insertPhotoEntry($photo, $uri = null)
 394     {
 395         if ($uri instanceof Zend_Gdata_Photos_AlbumEntry) {
 396             $uri = $uri->getLink(self::FEED_LINK_PATH)->href;
 397         }
 398         if ($uri === null) {
 399             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 400             throw new Zend_Gdata_App_InvalidArgumentException(
 401                     'URI must not be null');
 402         }
 403         $newEntry = $this->insertEntry($photo, $uri, 'Zend_Gdata_Photos_PhotoEntry');
 404         return $newEntry;
 405     }
 406
 407     /**
 408      * Create a new tag from a TagEntry.
 409      *
 410      * @param Zend_Gdata_Photos_TagEntry $tag The tag entry to insert.
 411      * @param string $url The URI where the tag should be
 412      *          uploaded to. Alternatively, a PhotoEntry can be provided and
 413      *          the tag will be added to that photo.
 414      * @return Zend_Gdata_Photos_TagEntry The inserted tag entry as returned
 415      *          by the server.
 416      * @throws Zend_Gdata_App_Exception
 417      * @throws Zend_Gdata_App_HttpException
 418      */
 419     public function insertTagEntry($tag, $uri = null)
 420     {
 421         if ($uri instanceof Zend_Gdata_Photos_PhotoEntry) {
 422             $uri = $uri->getLink(self::FEED_LINK_PATH)->href;
 423         }
 424         if ($uri === null) {
 425             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 426             throw new Zend_Gdata_App_InvalidArgumentException(
 427                     'URI must not be null');
 428         }
 429         $newEntry = $this->insertEntry($tag, $uri, 'Zend_Gdata_Photos_TagEntry');
 430         return $newEntry;
 431     }
 432
 433     /**
 434      * Create a new comment from a CommentEntry.
 435      *
 436      * @param Zend_Gdata_Photos_CommentEntry $comment The comment entry to
 437      *          insert.
 438      * @param string $url The URI where the comment should be uploaded to.
 439      *          Alternatively, a PhotoEntry can be provided and
 440      *          the comment will be added to that photo.
 441      * @return Zend_Gdata_Photos_CommentEntry The inserted comment entry
 442      *          as returned by the server.
 443      * @throws Zend_Gdata_App_Exception
 444      * @throws Zend_Gdata_App_HttpException
 445      */
 446     public function insertCommentEntry($comment, $uri = null)
 447     {
 448         if ($uri instanceof Zend_Gdata_Photos_PhotoEntry) {
 449             $uri = $uri->getLink(self::FEED_LINK_PATH)->href;
 450         }
 451         if ($uri === null) {
 452             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 453             throw new Zend_Gdata_App_InvalidArgumentException(
 454                     'URI must not be null');
 455         }
 456         $newEntry = $this->insertEntry($comment, $uri, 'Zend_Gdata_Photos_CommentEntry');
 457         return $newEntry;
 458     }
 459
 460     /**
 461      * Delete an AlbumEntry.
 462      *
 463      * @param Zend_Gdata_Photos_AlbumEntry $album The album entry to
 464      *          delete.
 465      * @param boolean $catch Whether to catch an exception when
 466      *            modified and re-delete or throw
 467      * @return void.
 468      * @throws Zend_Gdata_App_Exception
 469      * @throws Zend_Gdata_App_HttpException
 470      */
 471     public function deleteAlbumEntry($album, $catch)
 472     {
 473         if ($catch) {
 474             try {
 475                 $this->delete($album);
 476             } catch (Zend_Gdata_App_HttpException $e) {
 477                 if ($e->getResponse()->getStatus() === 409) {
 478                     $entry = new Zend_Gdata_Photos_AlbumEntry($e->getResponse()->getBody());
 479                     $this->delete($entry->getLink('edit')->href);
 480                 } else {
 481                     throw $e;
 482                 }
 483             }
 484         } else {
 485             $this->delete($album);
 486         }
 487     }
 488
 489     /**
 490      * Delete a PhotoEntry.
 491      *
 492      * @param Zend_Gdata_Photos_PhotoEntry $photo The photo entry to
 493      *          delete.
 494      * @param boolean $catch Whether to catch an exception when
 495      *            modified and re-delete or throw
 496      * @return void.
 497      * @throws Zend_Gdata_App_Exception
 498      * @throws Zend_Gdata_App_HttpException
 499      */
 500     public function deletePhotoEntry($photo, $catch)
 501     {
 502         if ($catch) {
 503             try {
 504                 $this->delete($photo);
 505             } catch (Zend_Gdata_App_HttpException $e) {
 506                 if ($e->getResponse()->getStatus() === 409) {
 507                     $entry = new Zend_Gdata_Photos_PhotoEntry($e->getResponse()->getBody());
 508                     $this->delete($entry->getLink('edit')->href);
 509                 } else {
 510                     throw $e;
 511                 }
 512             }
 513         } else {
 514             $this->delete($photo);
 515         }
 516     }
 517
 518     /**
 519      * Delete a CommentEntry.
 520      *
 521      * @param Zend_Gdata_Photos_CommentEntry $comment The comment entry to
 522      *          delete.
 523      * @param boolean $catch Whether to catch an exception when
 524      *            modified and re-delete or throw
 525      * @return void.
 526      * @throws Zend_Gdata_App_Exception
 527      * @throws Zend_Gdata_App_HttpException
 528      */
 529     public function deleteCommentEntry($comment, $catch)
 530     {
 531         if ($catch) {
 532             try {
 533                 $this->delete($comment);
 534             } catch (Zend_Gdata_App_HttpException $e) {
 535                 if ($e->getResponse()->getStatus() === 409) {
 536                     $entry = new Zend_Gdata_Photos_CommentEntry($e->getResponse()->getBody());
 537                     $this->delete($entry->getLink('edit')->href);
 538                 } else {
 539                     throw $e;
 540                 }
 541             }
 542         } else {
 543             $this->delete($comment);
 544         }
 545     }
 546
 547     /**
 548      * Delete a TagEntry.
 549      *
 550      * @param Zend_Gdata_Photos_TagEntry $tag The tag entry to
 551      *          delete.
 552      * @param boolean $catch Whether to catch an exception when
 553      *            modified and re-delete or throw
 554      * @return void.
 555      * @throws Zend_Gdata_App_Exception
 556      * @throws Zend_Gdata_App_HttpException
 557      */
 558     public function deleteTagEntry($tag, $catch)
 559     {
 560         if ($catch) {
 561             try {
 562                 $this->delete($tag);
 563             } catch (Zend_Gdata_App_HttpException $e) {
 564                 if ($e->getResponse()->getStatus() === 409) {
 565                     $entry = new Zend_Gdata_Photos_TagEntry($e->getResponse()->getBody());
 566                     $this->delete($entry->getLink('edit')->href);
 567                 } else {
 568                     throw $e;
 569                 }
 570             }
 571         } else {
 572             $this->delete($tag);
 573         }
 574     }
 575
 576 }