Service class for interacting with the Google Document List data API

As the Google data API protocol is based upon the Atom Publishing Protocol (APP), Gdata functionality extends the appropriate Zend_Gdata_App classes

link http://code.google.com/apis/documents/
category Zend
package Zend_Gdata
subpackage Docs
copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
license New BSD License
inherited_from \Zend_Gdata

 Methods

Provides a magic factory method to instantiate new objects with shorter syntax than would otherwise be required by the Zend Framework naming conventions. For instance, to construct a new Zend_Gdata_Calendar_Extension_Color, a developer simply needs to do $gCal->newColor(). For this magic constructor, packages are searched in the same order as which they appear in the $_registeredPackages array

__call(string $method, array $args) 
Inherited

Parameters

$method

string

The method name being called

$args

array

The arguments passed to the call

Exceptions

\Zend_Gdata_App_Exception

Create Gdata_Docs object

__construct(\Zend_Http_Client $client = null, string $applicationId = 'MyCompany-MyApp-1.0'
inherited_from \Zend_Gdata::__construct()

Parameters

$client

\Zend_Http_Client

(optional) The HTTP client to use when when communicating with the Google servers.

$applicationId

string

The identity of the app in the form of Company-AppName-Version

Create Gdata object

__construct(\Zend_Http_Client $client = null, string $applicationId = 'MyCompany-MyApp-1.0'
Inherited

Parameters

$client

\Zend_Http_Client

$applicationId

string

Creates a new folder in Google Docs

createFolder(string $folderName, string|null $folderResourceId = null) : \Zend_Gdata_Entry
todo ZF-8732: This should return a *subclass* of Zend_Gdata_Entry, but the appropriate type doesn't exist yet.

Parameters

$folderName

string

The folder name to create

$folderResourceId

stringnull

The parent folder to create it in ("folder%3Amy_parent_folder")

Returns

\Zend_Gdata_EntryThe folder entry created.

DELETE entry with client object

delete(mixed $data, $remainingRedirects = null) : void
Inherited

Parameters

$data

mixed

The Zend_Gdata_App_Entry or URL to delete

$remainingRedirects

Exceptions

\Zend_Gdata_App_Exception
\Zend_Gdata_App_HttpException
\Zend_Gdata_App_InvalidArgumentException

This method enables logging of requests by changing the Zend_Http_Client_Adapter used for performing the requests.

enableRequestDebugLogging(string $logfile) 
Inherited

NOTE: This will not work if you have customized the adapter already to use a proxy server or other interface.

Parameters

$logfile

string

The logfile to use when logging the requests

Returns the data for an If-Match header based on the current Etag property. If Etags are not supported by the server or cannot be extracted from the data, then null will be returned.

generateIfMatchHeaderData($data, $allowWeek) : string | null
Inherited

Parameters

$data

$allowWeek

Returns

stringnull$data

GET a URI using client object.

get(string $uri, array $extraHeaders = array()) : \Zend_Http_Response
Inherited

Parameters

$uri

string

GET URI

$extraHeaders

array

Extra headers to add to the request, as an array of string-based key/value pairs.

Exceptions

\Zend_Gdata_App_HttpException

Returns

\Zend_Http_Response

Retreive entry object representing a single document.

getDoc(string $docId, string $docType) : \Zend_Gdata_Docs_DocumentListEntry

This method builds the URL where this item is stored using the type and the id of the document.

Parameters

$docId

string

The URL key for the document. Examples: dcmg89gw_62hfjj8m, pKq0CzjiF3YmGd0AIlHKqeg

$docType

string

The type of the document as used in the Google Document List URLs. Examples: document, spreadsheet, presentation

Returns

\Zend_Gdata_Docs_DocumentListEntry

Retreive entry object for the desired word processing document.

getDocument(string $id) : \Zend_Gdata_Docs_DocumentListEntry

Parameters

$id

string

The URL id for the document. Example: dcmg89gw_62hfjj8m

Returns

\Zend_Gdata_Docs_DocumentListEntry

Retreive entry object representing a single document.

getDocumentListEntry(mixed $location = null) : \Zend_Gdata_Docs_DocumentListEntry

Parameters

$location

mixed

The location for the entry, as a URL or Query

Exceptions

\Zend_Gdata_App_InvalidArgumentException

Returns

\Zend_Gdata_Docs_DocumentListEntry

Retreive feed object containing entries for the user's documents.

getDocumentListFeed(mixed $location = null) : \Zend_Gdata_Docs_DocumentListFeed

Parameters

$location

mixed

The location for the feed, as a URL or Query

Returns

\Zend_Gdata_Docs_DocumentListFeed

Retrieve entry as string or object

getEntry(string $uri, string $className = 'Zend_Gdata_App_Entry') : string | \Zend_Gdata_App_Entry
Inherited

Parameters

$uri

string

$className

string

The class which is used as the return type

Returns

string\Zend_Gdata_App_EntryReturns string only if the object mapping has been disabled explicitly by passing false to the useObjectMapping() function.

Retrieve feed as string or object

getFeed(string $uri, string $className = 'Zend_Gdata_App_Feed') : string | \Zend_Gdata_App_Feed
Inherited

Parameters

$uri

string

The uri from which to retrieve the feed

$className

string

The class which is used as the return type

Returns

string\Zend_Gdata_App_FeedReturns string only if the object mapping has been disabled explicitly by passing false to the useObjectMapping() function.

Get the HTTP override state

getGzipEnabled() : boolean
InheritedStatic

Returns

boolean

Get the Zend_Http_Client object used for communication

getHttpClient() : \Zend_Http_Client
Inherited

Returns

\Zend_Http_Client

Get the HTTP override state

getHttpMethodOverride() : boolean
InheritedStatic

Returns

boolean

Get the major protocol version that is in use.

getMajorProtocolVersion() : integer
Inherited
see

Returns

integerThe major protocol version in use.

Get the maximum number of redirects to follow during HTTP operations

getMaxRedirects() : integer
InheritedStatic

Returns

integerMaximum number of redirects to follow

Get the minor protocol version that is in use.

getMinorProtocolVersion() : \(int | \NULL)
Inherited
see

Returns

\(int\NULL)The major protocol version in use, or NULL if no minor version is specified.

Retrieve next set of results based on a given feed.

getNextFeed(\Zend_Gdata_App_Feed $feed, string $className = null) : \Zend_Gdata_App_Feed | null
Inherited

Parameters

$feed

\Zend_Gdata_App_Feed

The feed from which to retreive the next set of results.

$className

string

(optional) The class of feed to be returned. If null, the next feed (if found) will be the same class as the feed that was given as the first argument.

Returns

\Zend_Gdata_App_FeednullReturns a Zend_Gdata_App_Feed or null if no next set of results exists.

Retreive entry object for the desired presentation.

getPresentation(string $id) : \Zend_Gdata_Docs_DocumentListEntry

Parameters

$id

string

The URL id for the document. Example: dcmg89gw_21gtrjcn

Returns

\Zend_Gdata_Docs_DocumentListEntry

Retrieve previous set of results based on a given feed.

getPreviousFeed(\Zend_Gdata_App_Feed $feed, string $className = null) : \Zend_Gdata_App_Feed | null
Inherited

Parameters

$feed

\Zend_Gdata_App_Feed

The feed from which to retreive the previous set of results.

$className

string

(optional) The class of feed to be returned. If null, the previous feed (if found) will be the same class as the feed that was given as the first argument.

Returns

\Zend_Gdata_App_FeednullReturns a Zend_Gdata_App_Feed or null if no previous set of results exists.

Retreive entry object for the desired spreadsheet.

getSpreadsheet(string $id) : \Zend_Gdata_Docs_DocumentListEntry

Parameters

$id

string

The URL id for the document. Example: pKq0CzjiF3YmGd0AIlHKqeg

Returns

\Zend_Gdata_Docs_DocumentListEntry

Gets the HTTP client object. If none is set, a new Zend_Http_Client will be used.

getStaticHttpClient() : \Zend_Http_Client
InheritedStatic

Returns

\Zend_Http_Client

Get whether to use verbose exception messages

getVerboseExceptionMessages() : boolean
InheritedStatic

In the case of HTTP errors, use the body of the HTTP response in the exception message.

Returns

boolean

Imports a feed located at $uri.

import(string $uri, \Zend_Http_Client $client = null, string $className = 'Zend_Gdata_App_Feed', boolean $useObjectMapping = true) : string | \Zend_Gdata_App_Feed
InheritedStatic

Parameters

$uri

string

$client

\Zend_Http_Client

The client used for communication

$className

string

The class which is used as the return type

$useObjectMapping

boolean

Enable/disable the use of XML to object mapping.

Exceptions

\Zend_Gdata_App_Exception

Returns

string\Zend_Gdata_App_FeedReturns string only if the fourth parameter ($useObjectMapping) is set to false.

Imports a feed from a file located at $filename.

importFile(string $filename, string $className = 'Zend_Gdata_App_Feed', string $useIncludePath = false) : \Zend_Gdata_App_Feed
InheritedStatic

Parameters

$filename

string

$className

string

The class which is used as the return type

$useIncludePath

string

Whether the include_path should be searched

Exceptions

\Zend_Gdata_App_Exception

Returns

\Zend_Gdata_App_Feed

Imports a feed represented by $string.

importString(string $string, string $className = 'Zend_Gdata_App_Feed', $majorProtocolVersion = null, $minorProtocolVersion = null) : \Zend_Gdata_App_Feed
InheritedStatic

Parameters

$string

string

$className

string

The class which is used as the return type

$majorProtocolVersion

$minorProtocolVersion

Exceptions

\Zend_Gdata_App_Exception

Returns

\Zend_Gdata_App_Feed

Imports the specified URL (non-statically).

importUrl(string $url, string $className = 'Zend_Gdata_App_Feed', array $extraHeaders = array()) : string | \Zend_Gdata_App_Feed
Inherited

Parameters

$url

string

The URL to import

$className

string

The class which is used as the return type

$extraHeaders

array

Extra headers to add to the request, as an array of string-based key/value pairs.

Exceptions

\Zend_Gdata_App_Exception

Returns

string\Zend_Gdata_App_FeedReturns string only if the object mapping has been disabled explicitly by passing false to the useObjectMapping() function.

Inserts an entry to a given URI and returns the response as an Entry.

insertDocument(mixed $data, string $uri, string $className = 'Zend_Gdata_Docs_DocumentListEntry') : \Zend_Gdata_Docs_DocumentListEntry

Parameters

$data

mixed

The Zend_Gdata_Docs_DocumentListEntry or media source to post. If it is a DocumentListEntry, the mediaSource should already have been set. If $data is a mediaSource, it should have the correct slug header and mime type.

$uri

string

POST URI

$className

string

(optional) The class of entry to be returned. The default is a 'Zend_Gdata_Docs_DocumentListEntry'.

Returns

\Zend_Gdata_Docs_DocumentListEntryThe entry returned by the service after insertion.

Inserts an entry to a given URI and returns the response as a fully formed Entry.

insertEntry(mixed $data, string $uri, string $className = 'Zend_Gdata_App_Entry', array $extraHeaders = array()) : \Zend_Gdata_App_Entry
Inherited

Parameters

$data

mixed

The Zend_Gdata_App_Entry or XML to post

$uri

string

POST URI

$className

string

The class of entry to be returned.

$extraHeaders

array

Extra headers to add to the request, as an array of string-based key/value pairs.

Returns

\Zend_Gdata_App_EntryThe entry returned by the service after insertion.

Determines whether service object is authenticated.

isAuthenticated() : boolean
Inherited

Returns

booleanTrue if service object is authenticated, false otherwise.

Looks up the mime type based on the file name extension. For example, calling this method with 'csv' would return 'text/comma-separated-values'. The Mime type is sent as a header in the upload HTTP POST request.

lookupMimeType(string $fileExtension) : string
Static

Parameters

$fileExtension

string

Returns

stringThe mime type to be sent to the server to tell it how the multipart mime data should be interpreted.

Performs a HTTP request using the specified method

performHttpRequest(string $method, string $url, array $headers = null, string $body = null, string $contentType = null, integer $remainingRedirects = null) : \Zend_Http_Response
Inherited

Parameters

$method

string

The HTTP method for the request - 'GET', 'POST', 'PUT', 'DELETE'

$url

string

The URL to which this request is being performed

$headers

array

An associative array of HTTP headers for this request

$body

string

The body of the HTTP request

$contentType

string

The value for the content type of the request body

$remainingRedirects

integer

Number of redirects to follow if request s results in one

Returns

\Zend_Http_ResponseThe response object

POST data with client object

post(mixed $data, string $uri = null, $remainingRedirects = null, string $contentType = null, array $extraHeaders = null) : \Zend_Http_Response
Inherited

Parameters

$data

mixed

The Zend_Gdata_App_Entry or XML to post

$uri

string

POST URI

$remainingRedirects

$contentType

string

Content-type of the data

$extraHeaders

array

Extra headers to add to the request, as an array of string-based key/value pairs.

Exceptions

\Zend_Gdata_App_Exception
\Zend_Gdata_App_HttpException
\Zend_Gdata_App_InvalidArgumentException

Returns

\Zend_Http_Response

Provides pre-processing for HTTP requests to APP services.

prepareRequest(string $method, string $url = null, array $headers = array(), mixed $data = null, string $contentTypeOverride = null) : array
Inherited
  1. Checks the $data element and, if it's an entry, extracts the XML, multipart data, edit link (PUT,DELETE), etc.
  2. If $data is a string, sets the default content-type header as 'application/atom+xml' if it's not already been set.
  3. Adds a x-http-method override header and changes the HTTP method to 'POST' if necessary as per getHttpMethodOverride()

Parameters

$method

string

The HTTP method for the request - 'GET', 'POST', 'PUT', 'DELETE'

$url

string

The URL to which this request is being performed, or null if found in $data

$headers

array

An associative array of HTTP headers for this request

$data

mixed

The Zend_Gdata_App_Entry or XML for the body of the request

$contentTypeOverride

string

The override value for the content type of the request body

Returns

arrayAn associative array containing the determined 'method', 'url', 'data', 'headers', 'contentType'

PUT data with client object

put(mixed $data, string $uri = null, $remainingRedirects = null, string $contentType = null, array $extraHeaders = null) : \Zend_Http_Response
Inherited

Parameters

$data

mixed

The Zend_Gdata_App_Entry or XML to post

$uri

string

PUT URI

$remainingRedirects

$contentType

string

Content-type of the data

$extraHeaders

array

Extra headers to add to the request, as an array of string-based key/value pairs.

Exceptions

\Zend_Gdata_App_Exception
\Zend_Gdata_App_HttpException
\Zend_Gdata_App_InvalidArgumentException

Returns

\Zend_Http_Response

Adds a Zend Framework package to the $_registeredPackages array.

registerPackage(string $name) : void
Inherited

This array is searched when using the magic __call method below to instantiante new objects.

Parameters

$name

string

The name of the package (eg Zend_Gdata_App)

Retrieve all entries for a feed, iterating through pages as necessary.

retrieveAllEntriesForFeed(object $feed) : mixed
Inherited

Be aware that calling this function on a large dataset will take a significant amount of time to complete. In some cases this may cause execution to timeout without proper precautions in place.

Parameters

$feed

object

The feed to iterate through.

Returns

mixedA new feed of the same type as the one originally passed in, containing all relevent entries.

Toggle requesting gzip encoded responses

setGzipEnabled(boolean $enabled = false) : void
InheritedStatic

Parameters

$enabled

boolean

Whether or not to enable gzipped responses

Set the Zend_Http_Client object used for communication

setHttpClient(\Zend_Http_Client $client, $applicationId = 'MyCompany-MyApp-1.0') : \Zend_Gdata_App
Inherited

Parameters

$client

\Zend_Http_Client

The client to use for communication

$applicationId

Exceptions

\Zend_Gdata_App_HttpException

Returns

\Zend_Gdata_AppProvides a fluent interface

Toggle using POST instead of PUT and DELETE HTTP methods

setHttpMethodOverride(boolean $override = true) : void
InheritedStatic

Some feed implementations do not accept PUT and DELETE HTTP methods, or they can't be used because of proxies or other measures. This allows turning on using POST where PUT and DELETE would normally be used; in addition, an X-Method-Override header will be sent with a value of PUT or DELETE as appropriate.

Parameters

$override

boolean

Whether to override PUT and DELETE with POST.

Set the major protocol version that should be used. Values < 1 will cause a Zend_Gdata_App_InvalidArgumentException to be thrown.

setMajorProtocolVersion(integer $value) 
Inherited
see

Parameters

$value

integer

The major protocol version to use.

Exceptions

\Zend_Gdata_App_InvalidArgumentException

Set the maximum number of redirects to follow during HTTP operations

setMaxRedirects(integer $maxRedirects) : void
InheritedStatic

Parameters

$maxRedirects

integer

Maximum number of redirects to follow

Set the minor protocol version that should be used. If set to NULL, no minor protocol version will be sent to the server. Values < 0 will cause a Zend_Gdata_App_InvalidArgumentException to be thrown.

setMinorProtocolVersion(\(int|\NULL) $value) 
Inherited
see

Parameters

$value

\(int\NULL)

The minor protocol version to use.

Exceptions

\Zend_Gdata_App_InvalidArgumentException

Set the static HTTP client instance

setStaticHttpClient(\Zend_Http_Client $httpClient) : void
InheritedStatic

Sets the static HTTP client object to use for retrieving the feed.

Parameters

$httpClient

\Zend_Http_Client

Set whether to use verbose exception messages

setVerboseExceptionMessages(boolean $verbose) 
InheritedStatic

In the case of HTTP errors, use the body of the HTTP response in the exception message.

Parameters

$verbose

boolean

Whether to use verbose exception messages

Update an entry

updateEntry(mixed $data, $uri = null, $className = null, array $extraHeaders = array()) : \Zend_Gdata_App_Entry
Inherited

Parameters

$data

mixed

Zend_Gdata_App_Entry or XML (w/ID and link rel='edit')

$uri

$className

$extraHeaders

array

Extra headers to add to the request, as an array of string-based key/value pairs.

Exceptions

\Zend_Gdata_App_Exception

Returns

\Zend_Gdata_App_EntryThe entry returned from the server

Upload a local file to create a new Google Document entry.

uploadFile(string $fileLocation, string $title = null, string $mimeType = null, string $uri = null) : \Zend_Gdata_Docs_DocumentListEntry

Parameters

$fileLocation

string

The full or relative path of the file to be uploaded.

$title

string

The name that this document should have on the server. If set, the title is used as the slug header in the POST request. If no title is provided, the location of the file will be used as the slug header in the request. If no mimeType is provided, this method attempts to determine the mime type based on the slugHeader by looking for .doc, .csv, .txt, etc. at the end of the file name. Example value: 'test.doc'.

$mimeType

string

Describes the type of data which is being sent to the server. This must be one of the accepted mime types which are enumerated in SUPPORTED_FILETYPES.

$uri

string

(optional) The URL to which the upload should be made. Example: 'https://docs.google.com/feeds/documents/private/full'.

Returns

\Zend_Gdata_Docs_DocumentListEntryThe entry for the newly created Google Document.

Enable/disable the use of XML to object mapping.

useObjectMapping(boolean $value) : void
Inherited

Parameters

$value

boolean

Pass in true to use the XML to object mapping. Pass in false or null to disable it.

Determine whether service object is using XML to object mapping.

usingObjectMapping() : boolean
Inherited

Returns

booleanTrue if service object is using XML to object mapping, false otherwise.

 Properties

 

Namespaces used for Gdata data

$namespaces : array

Default

array(array('gd', 'http://schemas.google.com/g/2005', 1, 0), array('openSearch', 'http://a9.com/-/spec/opensearchrss/1.0/', 1, 0), array('openSearch', 'http://a9.com/-/spec/opensearch/1.1/', 2, 0), array('rss', 'http://blogs.law.harvard.edu/tech/rss', 1, 0))
Static
 

$SUPPORTED_FILETYPES

$SUPPORTED_FILETYPES : array

Default

array('TXT' => 'text/plain', 'CSV' => 'text/csv', 'TSV' => 'text/tab-separated-values', 'TAB' => 'text/tab-separated-values', 'HTML' => 'text/html', 'HTM' => 'text/html', 'DOC' => 'application/msword', 'DOCX' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'ODS' => 'application/vnd.oasis.opendocument.spreadsheet', 'ODT' => 'application/vnd.oasis.opendocument.text', 'RTF' => 'application/rtf', 'SXW' => 'application/vnd.sun.xml.writer', 'XLS' => 'application/vnd.ms-excel', 'XLSX' => 'application/vnd.ms-excel', 'PPT' => 'application/vnd.ms-powerpoint', 'PPS' => 'application/vnd.ms-powerpoint')
Static
 

Default URI to which to POST.

$_defaultPostUri : string

Default

self::DOCUMENTS_LIST_FEED_URI
inherited_from \Zend_Gdata::_defaultPostUri
 

Default URI to which to POST.

$_defaultPostUri : string

Default

null
 

Enable gzipped responses?

$_gzipEnabled : boolean

Default

false
Static
 

Client object used to communicate

$_httpClient : \Zend_Http_Client

Default

 

Override HTTP PUT and DELETE request methods?

$_httpMethodOverride : boolean

Default

false
Static
 

Indicates the major protocol version that should be used.

$_majorProtocolVersion 

Default

At present, recognized values are either 1 or 2. However, any integer value >= 1 is considered valid.

Under most circumtances, this will be automatically set by Zend_Gdata_App subclasses.

see
see
 

Maximum number of redirects to follow during HTTP operations

$_maxRedirects : integer

Default

5
Static
 

Indicates the minor protocol version that should be used. Can be set to either an integer >= 0, or NULL if no minor version should be sent to the server.

$_minorProtocolVersion 

Default

At present, this field is not used by any Google services, but may be used in the future.

Under most circumtances, this will be automatically set by Zend_Gdata_App subclasses.

see
see
 

Packages to search for classes when using magic __call method, in order.

$_registeredPackages : array

Default

array('Zend_Gdata_App_Extension', 'Zend_Gdata_App')
 

Client object used to communicate in static context

$_staticHttpClient : \Zend_Http_Client

Default

null
Static
 

Whether we want to use XML to object mapping when fetching data.

$_useObjectMapping : boolean

Default

true
 

Use verbose exception messages. In the case of HTTP errors, use the body of the HTTP response in the exception message.

$_verboseExceptionMessages : boolean

Default

true
Static

 Constants

 

Service name for use with Google's authentication mechanisms

AUTH_SERVICE_NAME = 'writely' 
inherited_from \Zend_Gdata::AUTH_SERVICE_NAME
 

Service name for use with Google's authentication mechanisms

AUTH_SERVICE_NAME = 'xapi' : string
 

Default major protocol version.

DEFAULT_MAJOR_PROTOCOL_VERSION = 1 
see
 

Default minor protocol version.

DEFAULT_MINOR_PROTOCOL_VERSION = null 
see
 

DOCUMENTS_CATEGORY_SCHEMA

DOCUMENTS_CATEGORY_SCHEMA = 'http://schemas.google.com/g/2005#kind' 
 

DOCUMENTS_CATEGORY_TERM

DOCUMENTS_CATEGORY_TERM = 'http://schemas.google.com/docs/2007#folder' 
 

DOCUMENTS_FOLDER_FEED_URI

DOCUMENTS_FOLDER_FEED_URI = 'https://docs.google.com/feeds/folders/private/full' 
 

DOCUMENTS_LIST_FEED_URI

DOCUMENTS_LIST_FEED_URI = 'https://docs.google.com/feeds/documents/private/full'