/zf/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-2011 Zend Technologies USA Inc. (http://www.zend.com)
 20 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 21 * @version    $Id: Docs.php 24396 2011-08-21 14:28:50Z padraic $
 22 */
 23
 24/**
 25 * @see Zend_Gdata
 26 */
 27require_once 'Zend/Gdata.php';
 28
 29/**
 30 * @see Zend_Gdata_Docs_DocumentListFeed
 31 */
 32require_once 'Zend/Gdata/Docs/DocumentListFeed.php';
 33
 34/**
 35 * @see Zend_Gdata_Docs_DocumentListEntry
 36 */
 37require_once 'Zend/Gdata/Docs/DocumentListEntry.php';
 38
 39/**
 40 * @see Zend_Gdata_App_Extension_Category
 41 */
 42require_once 'Zend/Gdata/App/Extension/Category.php';
 43
 44/**
 45 * @see Zend_Gdata_App_Extension_Title
 46 */
 47require_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-2011 Zend Technologies USA Inc. (http://www.zend.com)
 57 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 58 */
 59class Zend_Gdata_Docs extends Zend_Gdata
 60{
 61
 62    const DOCUMENTS_LIST_FEED_URI = 'https://docs.google.com/feeds/documents/private/full';
 63    const DOCUMENTS_FOLDER_FEED_URI = 'https://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 = 'https://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: 'https://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}