library/Zend/Gdata/Docs.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 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 }