[Summary view] [Print] [Text view]

   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 [email protected] so we can send you a copy immediately.
  15   *
  16   * @category   Zend
  17   * @package    Zend_Gdata
  18   * @subpackage Docs
  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_Gdata
  26   */
  27  require_once 'Zend/Gdata.php';
  28  
  29  /**
  30   * @see Zend_Gdata_Docs_DocumentListFeed
  31   */
  32  require_once 'Zend/Gdata/Docs/DocumentListFeed.php';
  33  
  34  /**
  35   * @see Zend_Gdata_Docs_DocumentListEntry
  36   */
  37  require_once 'Zend/Gdata/Docs/DocumentListEntry.php';
  38  
  39  /**
  40   * @see Zend_Gdata_App_Extension_Category
  41   */
  42  require_once 'Zend/Gdata/App/Extension/Category.php';
  43  
  44  /**
  45   * @see Zend_Gdata_App_Extension_Title
  46   */
  47  require_once 'Zend/Gdata/App/Extension/Title.php';
  48  
  49  /**
  50   * Service class for interacting with the Google Document List data API
  51   * @link http://code.google.com/apis/documents/
  52   *
  53   * @category   Zend
  54   * @package    Zend_Gdata
  55   * @subpackage Docs
  56   * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  57   * @license    http://framework.zend.com/license/new-bsd     New BSD License
  58   */
  59  class Zend_Gdata_Docs extends Zend_Gdata
  60  {
  61  
  62      const DOCUMENTS_LIST_FEED_URI = 'http://docs.google.com/feeds/documents/private/full';
  63      const DOCUMENTS_FOLDER_FEED_URI = 'http://docs.google.com/feeds/folders/private/full';
  64      const DOCUMENTS_CATEGORY_SCHEMA = 'http://schemas.google.com/g/2005#kind';
  65      const DOCUMENTS_CATEGORY_TERM = 'http://schemas.google.com/docs/2007#folder';
  66      const AUTH_SERVICE_NAME = 'writely';
  67  
  68      protected $_defaultPostUri = self::DOCUMENTS_LIST_FEED_URI;
  69  
  70      private static $SUPPORTED_FILETYPES = array(
  71        'TXT'=>'text/plain',
  72        'CSV'=>'text/csv',
  73        'TSV'=>'text/tab-separated-values',
  74        'TAB'=>'text/tab-separated-values',
  75        'HTML'=>'text/html',
  76        'HTM'=>'text/html',
  77        'DOC'=>'application/msword',
  78        'ODS'=>'application/vnd.oasis.opendocument.spreadsheet',
  79        'ODT'=>'application/vnd.oasis.opendocument.text',
  80        'RTF'=>'application/rtf',
  81        'SXW'=>'application/vnd.sun.xml.writer',
  82        'XLS'=>'application/vnd.ms-excel',
  83        'XLSX'=>'application/vnd.ms-excel',
  84        'PPT'=>'application/vnd.ms-powerpoint',
  85        'PPS'=>'application/vnd.ms-powerpoint');
  86  
  87      /**
  88       * Create Gdata_Docs object
  89       *
  90       * @param Zend_Http_Client $client (optional) The HTTP client to use when
  91       *          when communicating with the Google servers.
  92       * @param string $applicationId The identity of the app in the form of Company-AppName-Version
  93       */
  94      public function __construct($client = null, $applicationId = 'MyCompany-MyApp-1.0')
  95      {
  96          $this->registerPackage('Zend_Gdata_Docs');
  97          parent::__construct($client, $applicationId);
  98          $this->_httpClient->setParameterPost('service', self::AUTH_SERVICE_NAME);
  99      }
 100  
 101      /**
 102       * Looks up the mime type based on the file name extension. For example,
 103       * calling this method with 'csv' would return
 104       * 'text/comma-separated-values'. The Mime type is sent as a header in
 105       * the upload HTTP POST request.
 106       *
 107       * @param string $fileExtension
 108       * @return string The mime type to be sent to the server to tell it how the
 109       *          multipart mime data should be interpreted.
 110       */
 111      public static function lookupMimeType($fileExtension) {
 112        return self::$SUPPORTED_FILETYPES[strtoupper($fileExtension)];
 113      }
 114  
 115      /**
 116       * Retreive feed object containing entries for the user's documents.
 117       *
 118       * @param mixed $location The location for the feed, as a URL or Query
 119       * @return Zend_Gdata_Docs_DocumentListFeed
 120       */
 121      public function getDocumentListFeed($location = null)
 122      {
 123          if ($location === null) {
 124              $uri = self::DOCUMENTS_LIST_FEED_URI;
 125          } else if ($location instanceof Zend_Gdata_Query) {
 126              $uri = $location->getQueryUrl();
 127          } else {
 128              $uri = $location;
 129          }
 130          return parent::getFeed($uri, 'Zend_Gdata_Docs_DocumentListFeed');
 131      }
 132  
 133      /**
 134       * Retreive entry object representing a single document.
 135       *
 136       * @param mixed $location The location for the entry, as a URL or Query
 137       * @return Zend_Gdata_Docs_DocumentListEntry
 138       */
 139      public function getDocumentListEntry($location = null)
 140      {
 141          if ($location === null) {
 142              require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 143              throw new Zend_Gdata_App_InvalidArgumentException(
 144                      'Location must not be null');
 145          } else if ($location instanceof Zend_Gdata_Query) {
 146              $uri = $location->getQueryUrl();
 147          } else {
 148              $uri = $location;
 149          }
 150          return parent::getEntry($uri, 'Zend_Gdata_Docs_DocumentListEntry');
 151      }
 152  
 153      /**
 154       * Retreive entry object representing a single document.
 155       *
 156       * This method builds the URL where this item is stored using the type
 157       * and the id of the document.
 158       * @param string $docId The URL key for the document. Examples:
 159       *     dcmg89gw_62hfjj8m, pKq0CzjiF3YmGd0AIlHKqeg
 160       * @param string $docType The type of the document as used in the Google
 161       *     Document List URLs. Examples: document, spreadsheet, presentation
 162       * @return Zend_Gdata_Docs_DocumentListEntry
 163       */
 164      public function getDoc($docId, $docType) {
 165          $location = 'http://docs.google.com/feeds/documents/private/full/' .
 166              $docType . '%3A' . $docId;
 167          return $this->getDocumentListEntry($location);
 168      }
 169  
 170      /**
 171       * Retreive entry object for the desired word processing document.
 172       *
 173       * @param string $id The URL id for the document. Example:
 174       *     dcmg89gw_62hfjj8m
 175       */
 176      public function getDocument($id) {
 177        return $this->getDoc($id, 'document');
 178      }
 179  
 180      /**
 181       * Retreive entry object for the desired spreadsheet.
 182       *
 183       * @param string $id The URL id for the document. Example:
 184       *     pKq0CzjiF3YmGd0AIlHKqeg
 185       */
 186      public function getSpreadsheet($id) {
 187        return $this->getDoc($id, 'spreadsheet');
 188      }
 189  
 190      /**
 191       * Retreive entry object for the desired presentation.
 192       *
 193       * @param string $id The URL id for the document. Example:
 194       *     dcmg89gw_21gtrjcn
 195       */
 196      public function getPresentation($id) {
 197        return $this->getDoc($id, 'presentation');
 198      }
 199  
 200      /**
 201       * Upload a local file to create a new Google Document entry.
 202       *
 203       * @param string $fileLocation The full or relative path of the file to
 204       *         be uploaded.
 205       * @param string $title The name that this document should have on the
 206       *         server. If set, the title is used as the slug header in the
 207       *         POST request. If no title is provided, the location of the
 208       *         file will be used as the slug header in the request. If no
 209       *         mimeType is provided, this method attempts to determine the
 210       *         mime type based on the slugHeader by looking for .doc,
 211       *         .csv, .txt, etc. at the end of the file name.
 212       *         Example value: 'test.doc'.
 213       * @param string $mimeType Describes the type of data which is being sent
 214       *         to the server. This must be one of the accepted mime types
 215       *         which are enumerated in SUPPORTED_FILETYPES.
 216       * @param string $uri (optional) The URL to which the upload should be
 217       *         made.
 218       *         Example: 'http://docs.google.com/feeds/documents/private/full'.
 219       * @return Zend_Gdata_Docs_DocumentListEntry The entry for the newly
 220       *         created Google Document.
 221       */
 222      public function uploadFile($fileLocation, $title=null, $mimeType=null,
 223                                 $uri=null)
 224      {
 225          // Set the URI to which the file will be uploaded.
 226          if ($uri === null) {
 227              $uri = $this->_defaultPostUri;
 228          }
 229  
 230          // Create the media source which describes the file.
 231          $fs = $this->newMediaFileSource($fileLocation);
 232          if ($title !== null) {
 233              $slugHeader = $title;
 234          } else {
 235              $slugHeader = $fileLocation;
 236          }
 237  
 238          // Set the slug header to tell the Google Documents server what the
 239          // title of the document should be and what the file extension was
 240          // for the original file.
 241          $fs->setSlug($slugHeader);
 242  
 243          // Set the mime type of the data.
 244          if ($mimeType === null) {
 245            $filenameParts = explode('.', $fileLocation);
 246            $fileExtension = end($filenameParts);
 247            $mimeType = self::lookupMimeType($fileExtension);
 248          }
 249  
 250          // Set the mime type for the upload request.
 251          $fs->setContentType($mimeType);
 252  
 253          // Send the data to the server.
 254          return $this->insertDocument($fs, $uri);
 255      }
 256  
 257      /**
 258       * Creates a new folder in Google Docs
 259       *
 260       * @param string $folderName The folder name to create
 261       * @param string|null $folderResourceId The parent folder to create it in
 262       *        ("folder%3Amy_parent_folder")
 263       * @return Zend_Gdata_Entry The folder entry created.
 264       * @todo ZF-8732: This should return a *subclass* of Zend_Gdata_Entry, but
 265       *       the appropriate type doesn't exist yet.
 266       */
 267      public function createFolder($folderName, $folderResourceId=null) {
 268          $category = new Zend_Gdata_App_Extension_Category(self::DOCUMENTS_CATEGORY_TERM, 
 269                                                            self::DOCUMENTS_CATEGORY_SCHEMA);
 270          $title = new Zend_Gdata_App_Extension_Title($folderName);
 271          $entry = new Zend_Gdata_Entry();
 272  
 273          $entry->setCategory(array($category));
 274          $entry->setTitle($title);
 275  
 276          $uri = self::DOCUMENTS_LIST_FEED_URI;
 277          if ($folderResourceId != null) {
 278              $uri = self::DOCUMENTS_FOLDER_FEED_URI . '/' . $folderResourceId;
 279          }
 280  
 281          return $this->insertEntry($entry, $uri);
 282      }
 283  
 284      /**
 285       * Inserts an entry to a given URI and returns the response as an Entry.
 286       *
 287       * @param mixed  $data The Zend_Gdata_Docs_DocumentListEntry or media
 288       *         source to post. If it is a DocumentListEntry, the mediaSource
 289       *         should already have been set. If $data is a mediaSource, it
 290       *         should have the correct slug header and mime type.
 291       * @param string $uri POST URI
 292       * @param string $className (optional) The class of entry to be returned.
 293       *         The default is a 'Zend_Gdata_Docs_DocumentListEntry'.
 294       * @return Zend_Gdata_Docs_DocumentListEntry The entry returned by the
 295       *     service after insertion.
 296       */
 297      public function insertDocument($data, $uri,
 298          $className='Zend_Gdata_Docs_DocumentListEntry')
 299      {
 300          return $this->insertEntry($data, $uri, $className);
 301      }
 302  
 303  }