/library/Zend/Gdata/App.php
PHP | 1240 lines | 606 code | 103 blank | 531 comment | 110 complexity | c8d9f478df287fccaad0b1de66ce19bb MD5 | raw file
Possible License(s): AGPL-1.0
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 App
19 * @copyright Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
20 * @license http://framework.zend.com/license/new-bsd New BSD License
21 * @version $Id: App.php 24594 2012-01-05 21:27:01Z matthew $
22 */
23
24/**
25 * Zend_Gdata_Feed
26 */
27require_once 'Zend/Gdata/App/Feed.php';
28
29/**
30 * Zend_Gdata_Http_Client
31 */
32require_once 'Zend/Http/Client.php';
33
34/**
35 * Zend_Version
36 */
37require_once 'Zend/Version.php';
38
39/**
40 * Zend_Gdata_App_MediaSource
41 */
42require_once 'Zend/Gdata/App/MediaSource.php';
43
44/**
45 * Zend_Uri/Http
46 */
47require_once 'Zend/Uri/Http.php';
48
49/**
50 * Provides Atom Publishing Protocol (APP) functionality. This class and all
51 * other components of Zend_Gdata_App are designed to work independently from
52 * other Zend_Gdata components in order to interact with generic APP services.
53 *
54 * @category Zend
55 * @package Zend_Gdata
56 * @subpackage App
57 * @copyright Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
58 * @license http://framework.zend.com/license/new-bsd New BSD License
59 */
60class Zend_Gdata_App
61{
62
63 /** Default major protocol version.
64 *
65 * @see _majorProtocolVersion
66 */
67 const DEFAULT_MAJOR_PROTOCOL_VERSION = 1;
68
69 /** Default minor protocol version.
70 *
71 * @see _minorProtocolVersion
72 */
73 const DEFAULT_MINOR_PROTOCOL_VERSION = null;
74
75 /**
76 * Client object used to communicate
77 *
78 * @var Zend_Http_Client
79 */
80 protected $_httpClient;
81
82 /**
83 * Client object used to communicate in static context
84 *
85 * @var Zend_Http_Client
86 */
87 protected static $_staticHttpClient = null;
88
89 /**
90 * Override HTTP PUT and DELETE request methods?
91 *
92 * @var boolean
93 */
94 protected static $_httpMethodOverride = false;
95
96 /**
97 * Enable gzipped responses?
98 *
99 * @var boolean
100 */
101 protected static $_gzipEnabled = false;
102
103 /**
104 * Use verbose exception messages. In the case of HTTP errors,
105 * use the body of the HTTP response in the exception message.
106 *
107 * @var boolean
108 */
109 protected static $_verboseExceptionMessages = true;
110
111 /**
112 * Default URI to which to POST.
113 *
114 * @var string
115 */
116 protected $_defaultPostUri = null;
117
118 /**
119 * Packages to search for classes when using magic __call method, in order.
120 *
121 * @var array
122 */
123 protected $_registeredPackages = array(
124 'Zend_Gdata_App_Extension',
125 'Zend_Gdata_App');
126
127 /**
128 * Maximum number of redirects to follow during HTTP operations
129 *
130 * @var int
131 */
132 protected static $_maxRedirects = 5;
133
134 /**
135 * Indicates the major protocol version that should be used.
136 * At present, recognized values are either 1 or 2. However, any integer
137 * value >= 1 is considered valid.
138 *
139 * Under most circumtances, this will be automatically set by
140 * Zend_Gdata_App subclasses.
141 *
142 * @see setMajorProtocolVersion()
143 * @see getMajorProtocolVersion()
144 */
145 protected $_majorProtocolVersion;
146
147 /**
148 * Indicates the minor protocol version that should be used. Can be set
149 * to either an integer >= 0, or NULL if no minor version should be sent
150 * to the server.
151 *
152 * At present, this field is not used by any Google services, but may be
153 * used in the future.
154 *
155 * Under most circumtances, this will be automatically set by
156 * Zend_Gdata_App subclasses.
157 *
158 * @see setMinorProtocolVersion()
159 * @see getMinorProtocolVersion()
160 */
161 protected $_minorProtocolVersion;
162
163 /**
164 * Whether we want to use XML to object mapping when fetching data.
165 *
166 * @var boolean
167 */
168 protected $_useObjectMapping = true;
169
170 /**
171 * Create Gdata object
172 *
173 * @param Zend_Http_Client $client
174 * @param string $applicationId
175 */
176 public function __construct($client = null, $applicationId = 'MyCompany-MyApp-1.0')
177 {
178 $this->setHttpClient($client, $applicationId);
179 // Set default protocol version. Subclasses should override this as
180 // needed once a given service supports a new version.
181 $this->setMajorProtocolVersion(self::DEFAULT_MAJOR_PROTOCOL_VERSION);
182 $this->setMinorProtocolVersion(self::DEFAULT_MINOR_PROTOCOL_VERSION);
183 }
184
185 /**
186 * Adds a Zend Framework package to the $_registeredPackages array.
187 * This array is searched when using the magic __call method below
188 * to instantiante new objects.
189 *
190 * @param string $name The name of the package (eg Zend_Gdata_App)
191 * @return void
192 */
193 public function registerPackage($name)
194 {
195 array_unshift($this->_registeredPackages, $name);
196 }
197
198 /**
199 * Retrieve feed as string or object
200 *
201 * @param string $uri The uri from which to retrieve the feed
202 * @param string $className The class which is used as the return type
203 * @return string|Zend_Gdata_App_Feed Returns string only if the object
204 * mapping has been disabled explicitly
205 * by passing false to the
206 * useObjectMapping() function.
207 */
208 public function getFeed($uri, $className='Zend_Gdata_App_Feed')
209 {
210 return $this->importUrl($uri, $className, null);
211 }
212
213 /**
214 * Retrieve entry as string or object
215 *
216 * @param string $uri
217 * @param string $className The class which is used as the return type
218 * @return string|Zend_Gdata_App_Entry Returns string only if the object
219 * mapping has been disabled explicitly
220 * by passing false to the
221 * useObjectMapping() function.
222 */
223 public function getEntry($uri, $className='Zend_Gdata_App_Entry')
224 {
225 return $this->importUrl($uri, $className, null);
226 }
227
228 /**
229 * Get the Zend_Http_Client object used for communication
230 *
231 * @return Zend_Http_Client
232 */
233 public function getHttpClient()
234 {
235 return $this->_httpClient;
236 }
237
238 /**
239 * Set the Zend_Http_Client object used for communication
240 *
241 * @param Zend_Http_Client $client The client to use for communication
242 * @throws Zend_Gdata_App_HttpException
243 * @return Zend_Gdata_App Provides a fluent interface
244 */
245 public function setHttpClient($client,
246 $applicationId = 'MyCompany-MyApp-1.0')
247 {
248 if ($client === null) {
249 $client = new Zend_Http_Client();
250 }
251 if (!$client instanceof Zend_Http_Client) {
252 require_once 'Zend/Gdata/App/HttpException.php';
253 throw new Zend_Gdata_App_HttpException(
254 'Argument is not an instance of Zend_Http_Client.');
255 }
256 $userAgent = $applicationId . ' Zend_Framework_Gdata/' .
257 Zend_Version::VERSION;
258 $client->setHeaders('User-Agent', $userAgent);
259 $client->setConfig(array(
260 'strictredirects' => true
261 )
262 );
263 $this->_httpClient = $client;
264 self::setStaticHttpClient($client);
265 return $this;
266 }
267
268 /**
269 * Set the static HTTP client instance
270 *
271 * Sets the static HTTP client object to use for retrieving the feed.
272 *
273 * @param Zend_Http_Client $httpClient
274 * @return void
275 */
276 public static function setStaticHttpClient(Zend_Http_Client $httpClient)
277 {
278 self::$_staticHttpClient = $httpClient;
279 }
280
281
282 /**
283 * Gets the HTTP client object. If none is set, a new Zend_Http_Client will be used.
284 *
285 * @return Zend_Http_Client
286 */
287 public static function getStaticHttpClient()
288 {
289 if (!self::$_staticHttpClient instanceof Zend_Http_Client) {
290 $client = new Zend_Http_Client();
291 $userAgent = 'Zend_Framework_Gdata/' . Zend_Version::VERSION;
292 $client->setHeaders('User-Agent', $userAgent);
293 $client->setConfig(array(
294 'strictredirects' => true
295 )
296 );
297 self::$_staticHttpClient = $client;
298 }
299 return self::$_staticHttpClient;
300 }
301
302 /**
303 * Toggle using POST instead of PUT and DELETE HTTP methods
304 *
305 * Some feed implementations do not accept PUT and DELETE HTTP
306 * methods, or they can't be used because of proxies or other
307 * measures. This allows turning on using POST where PUT and
308 * DELETE would normally be used; in addition, an
309 * X-Method-Override header will be sent with a value of PUT or
310 * DELETE as appropriate.
311 *
312 * @param boolean $override Whether to override PUT and DELETE with POST.
313 * @return void
314 */
315 public static function setHttpMethodOverride($override = true)
316 {
317 self::$_httpMethodOverride = $override;
318 }
319
320 /**
321 * Get the HTTP override state
322 *
323 * @return boolean
324 */
325 public static function getHttpMethodOverride()
326 {
327 return self::$_httpMethodOverride;
328 }
329
330 /**
331 * Toggle requesting gzip encoded responses
332 *
333 * @param boolean $enabled Whether or not to enable gzipped responses
334 * @return void
335 */
336 public static function setGzipEnabled($enabled = false)
337 {
338 if ($enabled && !function_exists('gzinflate')) {
339 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
340 throw new Zend_Gdata_App_InvalidArgumentException(
341 'You cannot enable gzipped responses if the zlib module ' .
342 'is not enabled in your PHP installation.');
343
344 }
345 self::$_gzipEnabled = $enabled;
346 }
347
348 /**
349 * Get the HTTP override state
350 *
351 * @return boolean
352 */
353 public static function getGzipEnabled()
354 {
355 return self::$_gzipEnabled;
356 }
357
358 /**
359 * Get whether to use verbose exception messages
360 *
361 * In the case of HTTP errors, use the body of the HTTP response
362 * in the exception message.
363 *
364 * @return boolean
365 */
366 public static function getVerboseExceptionMessages()
367 {
368 return self::$_verboseExceptionMessages;
369 }
370
371 /**
372 * Set whether to use verbose exception messages
373 *
374 * In the case of HTTP errors, use the body of the HTTP response
375 * in the exception message.
376 *
377 * @param boolean $verbose Whether to use verbose exception messages
378 */
379 public static function setVerboseExceptionMessages($verbose)
380 {
381 self::$_verboseExceptionMessages = $verbose;
382 }
383
384 /**
385 * Set the maximum number of redirects to follow during HTTP operations
386 *
387 * @param int $maxRedirects Maximum number of redirects to follow
388 * @return void
389 */
390 public static function setMaxRedirects($maxRedirects)
391 {
392 self::$_maxRedirects = $maxRedirects;
393 }
394
395 /**
396 * Get the maximum number of redirects to follow during HTTP operations
397 *
398 * @return int Maximum number of redirects to follow
399 */
400 public static function getMaxRedirects()
401 {
402 return self::$_maxRedirects;
403 }
404
405 /**
406 * Set the major protocol version that should be used. Values < 1 will
407 * cause a Zend_Gdata_App_InvalidArgumentException to be thrown.
408 *
409 * @see _majorProtocolVersion
410 * @param int $value The major protocol version to use.
411 * @throws Zend_Gdata_App_InvalidArgumentException
412 */
413 public function setMajorProtocolVersion($value)
414 {
415 if (!($value >= 1)) {
416 require_once('Zend/Gdata/App/InvalidArgumentException.php');
417 throw new Zend_Gdata_App_InvalidArgumentException(
418 'Major protocol version must be >= 1');
419 }
420 $this->_majorProtocolVersion = $value;
421 }
422
423 /**
424 * Get the major protocol version that is in use.
425 *
426 * @see _majorProtocolVersion
427 * @return int The major protocol version in use.
428 */
429 public function getMajorProtocolVersion()
430 {
431 return $this->_majorProtocolVersion;
432 }
433
434 /**
435 * Set the minor protocol version that should be used. If set to NULL, no
436 * minor protocol version will be sent to the server. Values < 0 will
437 * cause a Zend_Gdata_App_InvalidArgumentException to be thrown.
438 *
439 * @see _minorProtocolVersion
440 * @param (int|NULL) $value The minor protocol version to use.
441 * @throws Zend_Gdata_App_InvalidArgumentException
442 */
443 public function setMinorProtocolVersion($value)
444 {
445 if (!($value >= 0)) {
446 require_once('Zend/Gdata/App/InvalidArgumentException.php');
447 throw new Zend_Gdata_App_InvalidArgumentException(
448 'Minor protocol version must be >= 0');
449 }
450 $this->_minorProtocolVersion = $value;
451 }
452
453 /**
454 * Get the minor protocol version that is in use.
455 *
456 * @see _minorProtocolVersion
457 * @return (int|NULL) The major protocol version in use, or NULL if no
458 * minor version is specified.
459 */
460 public function getMinorProtocolVersion()
461 {
462 return $this->_minorProtocolVersion;
463 }
464
465 /**
466 * Provides pre-processing for HTTP requests to APP services.
467 *
468 * 1. Checks the $data element and, if it's an entry, extracts the XML,
469 * multipart data, edit link (PUT,DELETE), etc.
470 * 2. If $data is a string, sets the default content-type header as
471 * 'application/atom+xml' if it's not already been set.
472 * 3. Adds a x-http-method override header and changes the HTTP method
473 * to 'POST' if necessary as per getHttpMethodOverride()
474 *
475 * @param string $method The HTTP method for the request - 'GET', 'POST',
476 * 'PUT', 'DELETE'
477 * @param string $url The URL to which this request is being performed,
478 * or null if found in $data
479 * @param array $headers An associative array of HTTP headers for this
480 * request
481 * @param mixed $data The Zend_Gdata_App_Entry or XML for the
482 * body of the request
483 * @param string $contentTypeOverride The override value for the
484 * content type of the request body
485 * @return array An associative array containing the determined
486 * 'method', 'url', 'data', 'headers', 'contentType'
487 */
488 public function prepareRequest($method,
489 $url = null,
490 $headers = array(),
491 $data = null,
492 $contentTypeOverride = null)
493 {
494 // As a convenience, if $headers is null, we'll convert it back to
495 // an empty array.
496 if ($headers === null) {
497 $headers = array();
498 }
499
500 $rawData = null;
501 $finalContentType = null;
502 if ($url == null) {
503 $url = $this->_defaultPostUri;
504 }
505
506 if (is_string($data)) {
507 $rawData = $data;
508 if ($contentTypeOverride === null) {
509 $finalContentType = 'application/atom+xml';
510 }
511 } elseif ($data instanceof Zend_Gdata_App_MediaEntry) {
512 $rawData = $data->encode();
513 if ($data->getMediaSource() !== null) {
514 $finalContentType = $rawData->getContentType();
515 $headers['MIME-version'] = '1.0';
516 $headers['Slug'] = $data->getMediaSource()->getSlug();
517 } else {
518 $finalContentType = 'application/atom+xml';
519 }
520 if ($method == 'PUT' || $method == 'DELETE') {
521 $editLink = $data->getEditLink();
522 if ($editLink != null && $url == null) {
523 $url = $editLink->getHref();
524 }
525 }
526 } elseif ($data instanceof Zend_Gdata_App_Entry) {
527 $rawData = $data->saveXML();
528 $finalContentType = 'application/atom+xml';
529 if ($method == 'PUT' || $method == 'DELETE') {
530 $editLink = $data->getEditLink();
531 if ($editLink != null) {
532 $url = $editLink->getHref();
533 }
534 }
535 } elseif ($data instanceof Zend_Gdata_App_MediaSource) {
536 $rawData = $data->encode();
537 if ($data->getSlug() !== null) {
538 $headers['Slug'] = $data->getSlug();
539 }
540 $finalContentType = $data->getContentType();
541 }
542
543 if ($method == 'DELETE') {
544 $rawData = null;
545 }
546
547 // Set an If-Match header if:
548 // - This isn't a DELETE
549 // - If this isn't a GET, the Etag isn't weak
550 // - A similar header (If-Match/If-None-Match) hasn't already been
551 // set.
552 if ($method != 'DELETE' && (
553 !array_key_exists('If-Match', $headers) &&
554 !array_key_exists('If-None-Match', $headers)
555 ) ) {
556 $allowWeak = $method == 'GET';
557 if ($ifMatchHeader = $this->generateIfMatchHeaderData(
558 $data, $allowWeak)) {
559 $headers['If-Match'] = $ifMatchHeader;
560 }
561 }
562
563 if ($method != 'POST' && $method != 'GET' && Zend_Gdata_App::getHttpMethodOverride()) {
564 $headers['x-http-method-override'] = $method;
565 $method = 'POST';
566 } else {
567 $headers['x-http-method-override'] = null;
568 }
569
570 if ($contentTypeOverride != null) {
571 $finalContentType = $contentTypeOverride;
572 }
573
574 return array('method' => $method, 'url' => $url,
575 'data' => $rawData, 'headers' => $headers,
576 'contentType' => $finalContentType);
577 }
578
579 /**
580 * Performs a HTTP request using the specified method
581 *
582 * @param string $method The HTTP method for the request - 'GET', 'POST',
583 * 'PUT', 'DELETE'
584 * @param string $url The URL to which this request is being performed
585 * @param array $headers An associative array of HTTP headers
586 * for this request
587 * @param string $body The body of the HTTP request
588 * @param string $contentType The value for the content type
589 * of the request body
590 * @param int $remainingRedirects Number of redirects to follow if request
591 * s results in one
592 * @return Zend_Http_Response The response object
593 */
594 public function performHttpRequest($method, $url, $headers = null,
595 $body = null, $contentType = null, $remainingRedirects = null)
596 {
597 require_once 'Zend/Http/Client/Exception.php';
598 if ($remainingRedirects === null) {
599 $remainingRedirects = self::getMaxRedirects();
600 }
601 if ($headers === null) {
602 $headers = array();
603 }
604 // Append a Gdata version header if protocol v2 or higher is in use.
605 // (Protocol v1 does not use this header.)
606 $major = $this->getMajorProtocolVersion();
607 $minor = $this->getMinorProtocolVersion();
608 if ($major >= 2) {
609 $headers['GData-Version'] = $major +
610 (($minor === null) ? '.' + $minor : '');
611 }
612
613 // check the overridden method
614 if (($method == 'POST' || $method == 'PUT') && $body === null &&
615 $headers['x-http-method-override'] != 'DELETE') {
616 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
617 throw new Zend_Gdata_App_InvalidArgumentException(
618 'You must specify the data to post as either a ' .
619 'string or a child of Zend_Gdata_App_Entry');
620 }
621 if ($url === null) {
622 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
623 throw new Zend_Gdata_App_InvalidArgumentException(
624 'You must specify an URI to which to post.');
625 }
626 $headers['Content-Type'] = $contentType;
627 if (Zend_Gdata_App::getGzipEnabled()) {
628 // some services require the word 'gzip' to be in the user-agent
629 // header in addition to the accept-encoding header
630 if (strpos($this->_httpClient->getHeader('User-Agent'),
631 'gzip') === false) {
632 $headers['User-Agent'] =
633 $this->_httpClient->getHeader('User-Agent') . ' (gzip)';
634 }
635 $headers['Accept-encoding'] = 'gzip, deflate';
636 } else {
637 $headers['Accept-encoding'] = 'identity';
638 }
639
640 // Make sure the HTTP client object is 'clean' before making a request
641 // In addition to standard headers to reset via resetParameters(),
642 // also reset the Slug and If-Match headers
643 $this->_httpClient->resetParameters();
644 $this->_httpClient->setHeaders(array('Slug', 'If-Match'));
645
646 // Set the params for the new request to be performed
647 $this->_httpClient->setHeaders($headers);
648 require_once 'Zend/Uri/Http.php';
649 $uri = Zend_Uri_Http::fromString($url);
650 preg_match("/^(.*?)(\?.*)?$/", $url, $matches);
651 $this->_httpClient->setUri($matches[1]);
652 $queryArray = $uri->getQueryAsArray();
653 foreach ($queryArray as $name => $value) {
654 $this->_httpClient->setParameterGet($name, $value);
655 }
656
657
658 $this->_httpClient->setConfig(array('maxredirects' => 0));
659
660 // Set the proper adapter if we are handling a streaming upload
661 $usingMimeStream = false;
662 $oldHttpAdapter = null;
663
664 if ($body instanceof Zend_Gdata_MediaMimeStream) {
665 $usingMimeStream = true;
666 $this->_httpClient->setRawDataStream($body, $contentType);
667 $oldHttpAdapter = $this->_httpClient->getAdapter();
668
669 if ($oldHttpAdapter instanceof Zend_Http_Client_Adapter_Proxy) {
670 require_once 'Zend/Gdata/HttpAdapterStreamingProxy.php';
671 $newAdapter = new Zend_Gdata_HttpAdapterStreamingProxy();
672 } else {
673 require_once 'Zend/Gdata/HttpAdapterStreamingSocket.php';
674 $newAdapter = new Zend_Gdata_HttpAdapterStreamingSocket();
675 }
676 $this->_httpClient->setAdapter($newAdapter);
677 } else {
678 $this->_httpClient->setRawData($body, $contentType);
679 }
680
681 try {
682 $response = $this->_httpClient->request($method);
683 // reset adapter
684 if ($usingMimeStream) {
685 $this->_httpClient->setAdapter($oldHttpAdapter);
686 }
687 } catch (Zend_Http_Client_Exception $e) {
688 // reset adapter
689 if ($usingMimeStream) {
690 $this->_httpClient->setAdapter($oldHttpAdapter);
691 }
692 require_once 'Zend/Gdata/App/HttpException.php';
693 throw new Zend_Gdata_App_HttpException($e->getMessage(), $e);
694 }
695 if ($response->isRedirect() && $response->getStatus() != '304') {
696 if ($remainingRedirects > 0) {
697 $newUrl = $response->getHeader('Location');
698 $response = $this->performHttpRequest(
699 $method, $newUrl, $headers, $body,
700 $contentType, $remainingRedirects);
701 } else {
702 require_once 'Zend/Gdata/App/HttpException.php';
703 throw new Zend_Gdata_App_HttpException(
704 'Number of redirects exceeds maximum', null, $response);
705 }
706 }
707 if (!$response->isSuccessful()) {
708 require_once 'Zend/Gdata/App/HttpException.php';
709 $exceptionMessage = 'Expected response code 200, got ' .
710 $response->getStatus();
711 if (self::getVerboseExceptionMessages()) {
712 $exceptionMessage .= "\n" . $response->getBody();
713 }
714 $exception = new Zend_Gdata_App_HttpException($exceptionMessage);
715 $exception->setResponse($response);
716 throw $exception;
717 }
718 return $response;
719 }
720
721 /**
722 * Imports a feed located at $uri.
723 *
724 * @param string $uri
725 * @param Zend_Http_Client $client The client used for communication
726 * @param string $className The class which is used as the return type
727 * @throws Zend_Gdata_App_Exception
728 * @return string|Zend_Gdata_App_Feed Returns string only if the object
729 * mapping has been disabled explicitly
730 * by passing false to the
731 * useObjectMapping() function.
732 */
733 public static function import($uri, $client = null,
734 $className='Zend_Gdata_App_Feed')
735 {
736 $app = new Zend_Gdata_App($client);
737 $requestData = $app->prepareRequest('GET', $uri);
738 $response = $app->performHttpRequest(
739 $requestData['method'], $requestData['url']);
740
741 $feedContent = $response->getBody();
742 if (!$this->_useObjectMapping) {
743 return $feedContent;
744 }
745 $feed = self::importString($feedContent, $className);
746 if ($client != null) {
747 $feed->setHttpClient($client);
748 }
749 return $feed;
750 }
751
752 /**
753 * Imports the specified URL (non-statically).
754 *
755 * @param string $url The URL to import
756 * @param string $className The class which is used as the return type
757 * @param array $extraHeaders Extra headers to add to the request, as an
758 * array of string-based key/value pairs.
759 * @throws Zend_Gdata_App_Exception
760 * @return string|Zend_Gdata_App_Feed Returns string only if the object
761 * mapping has been disabled explicitly
762 * by passing false to the
763 * useObjectMapping() function.
764 */
765 public function importUrl($url, $className='Zend_Gdata_App_Feed',
766 $extraHeaders = array())
767 {
768 $response = $this->get($url, $extraHeaders);
769
770 $feedContent = $response->getBody();
771 if (!$this->_useObjectMapping) {
772 return $feedContent;
773 }
774
775 $protocolVersionStr = $response->getHeader('GData-Version');
776 $majorProtocolVersion = null;
777 $minorProtocolVersion = null;
778 if ($protocolVersionStr !== null) {
779 // Extract protocol major and minor version from header
780 $delimiterPos = strpos($protocolVersionStr, '.');
781 $length = strlen($protocolVersionStr);
782 $major = substr($protocolVersionStr, 0, $delimiterPos);
783 $minor = substr($protocolVersionStr, $delimiterPos + 1, $length);
784 $majorProtocolVersion = $major;
785 $minorProtocolVersion = $minor;
786 }
787
788 $feed = self::importString($feedContent, $className,
789 $majorProtocolVersion, $minorProtocolVersion);
790 if ($this->getHttpClient() != null) {
791 $feed->setHttpClient($this->getHttpClient());
792 }
793 $etag = $response->getHeader('ETag');
794 if ($etag !== null) {
795 $feed->setEtag($etag);
796 }
797 return $feed;
798 }
799
800
801 /**
802 * Imports a feed represented by $string.
803 *
804 * @param string $string
805 * @param string $className The class which is used as the return type
806 * @param integer $majorProcolVersion (optional) The major protocol version
807 * of the data model object that is to be created.
808 * @param integer $minorProcolVersion (optional) The minor protocol version
809 * of the data model object that is to be created.
810 * @throws Zend_Gdata_App_Exception
811 * @return Zend_Gdata_App_Feed
812 */
813 public static function importString($string,
814 $className='Zend_Gdata_App_Feed', $majorProtocolVersion = null,
815 $minorProtocolVersion = null)
816 {
817 if (!class_exists($className, false)) {
818 require_once 'Zend/Loader.php';
819 @Zend_Loader::loadClass($className);
820 }
821
822 // Load the feed as an XML DOMDocument object
823 @ini_set('track_errors', 1);
824 $doc = new DOMDocument();
825 $success = @$doc->loadXML($string);
826 @ini_restore('track_errors');
827
828 if (!$success) {
829 require_once 'Zend/Gdata/App/Exception.php';
830 throw new Zend_Gdata_App_Exception(
831 "DOMDocument cannot parse XML: $php_errormsg");
832 }
833
834 $feed = new $className();
835 $feed->setMajorProtocolVersion($majorProtocolVersion);
836 $feed->setMinorProtocolVersion($minorProtocolVersion);
837 $feed->transferFromXML($string);
838 $feed->setHttpClient(self::getstaticHttpClient());
839 return $feed;
840 }
841
842
843 /**
844 * Imports a feed from a file located at $filename.
845 *
846 * @param string $filename
847 * @param string $className The class which is used as the return type
848 * @param string $useIncludePath Whether the include_path should be searched
849 * @throws Zend_Gdata_App_Exception
850 * @return Zend_Gdata_App_Feed
851 */
852 public static function importFile($filename,
853 $className='Zend_Gdata_App_Feed', $useIncludePath = false)
854 {
855 @ini_set('track_errors', 1);
856 $feed = @file_get_contents($filename, $useIncludePath);
857 @ini_restore('track_errors');
858 if ($feed === false) {
859 require_once 'Zend/Gdata/App/Exception.php';
860 throw new Zend_Gdata_App_Exception(
861 "File could not be loaded: $php_errormsg");
862 }
863 return self::importString($feed, $className);
864 }
865
866 /**
867 * GET a URI using client object.
868 *
869 * @param string $uri GET URI
870 * @param array $extraHeaders Extra headers to add to the request, as an
871 * array of string-based key/value pairs.
872 * @throws Zend_Gdata_App_HttpException
873 * @return Zend_Http_Response
874 */
875 public function get($uri, $extraHeaders = array())
876 {
877 $requestData = $this->prepareRequest('GET', $uri, $extraHeaders);
878 return $this->performHttpRequest(
879 $requestData['method'], $requestData['url'],
880 $requestData['headers']);
881 }
882
883 /**
884 * POST data with client object
885 *
886 * @param mixed $data The Zend_Gdata_App_Entry or XML to post
887 * @param string $uri POST URI
888 * @param array $headers Additional HTTP headers to insert.
889 * @param string $contentType Content-type of the data
890 * @param array $extraHeaders Extra headers to add to the request, as an
891 * array of string-based key/value pairs.
892 * @return Zend_Http_Response
893 * @throws Zend_Gdata_App_Exception
894 * @throws Zend_Gdata_App_HttpException
895 * @throws Zend_Gdata_App_InvalidArgumentException
896 */
897 public function post($data, $uri = null, $remainingRedirects = null,
898 $contentType = null, $extraHeaders = null)
899 {
900 $requestData = $this->prepareRequest(
901 'POST', $uri, $extraHeaders, $data, $contentType);
902 return $this->performHttpRequest(
903 $requestData['method'], $requestData['url'],
904 $requestData['headers'], $requestData['data'],
905 $requestData['contentType']);
906 }
907
908 /**
909 * PUT data with client object
910 *
911 * @param mixed $data The Zend_Gdata_App_Entry or XML to post
912 * @param string $uri PUT URI
913 * @param array $headers Additional HTTP headers to insert.
914 * @param string $contentType Content-type of the data
915 * @param array $extraHeaders Extra headers to add to the request, as an
916 * array of string-based key/value pairs.
917 * @return Zend_Http_Response
918 * @throws Zend_Gdata_App_Exception
919 * @throws Zend_Gdata_App_HttpException
920 * @throws Zend_Gdata_App_InvalidArgumentException
921 */
922 public function put($data, $uri = null, $remainingRedirects = null,
923 $contentType = null, $extraHeaders = null)
924 {
925 $requestData = $this->prepareRequest(
926 'PUT', $uri, $extraHeaders, $data, $contentType);
927 return $this->performHttpRequest(
928 $requestData['method'], $requestData['url'],
929 $requestData['headers'], $requestData['data'],
930 $requestData['contentType']);
931 }
932
933 /**
934 * DELETE entry with client object
935 *
936 * @param mixed $data The Zend_Gdata_App_Entry or URL to delete
937 * @return void
938 * @throws Zend_Gdata_App_Exception
939 * @throws Zend_Gdata_App_HttpException
940 * @throws Zend_Gdata_App_InvalidArgumentException
941 */
942 public function delete($data, $remainingRedirects = null)
943 {
944 if (is_string($data)) {
945 $requestData = $this->prepareRequest('DELETE', $data);
946 } else {
947 $headers = array();
948
949 $requestData = $this->prepareRequest(
950 'DELETE', null, $headers, $data);
951 }
952 return $this->performHttpRequest($requestData['method'],
953 $requestData['url'],
954 $requestData['headers'],
955 '',
956 $requestData['contentType'],
957 $remainingRedirects);
958 }
959
960 /**
961 * Inserts an entry to a given URI and returns the response as a
962 * fully formed Entry.
963 *
964 * @param mixed $data The Zend_Gdata_App_Entry or XML to post
965 * @param string $uri POST URI
966 * @param string $className The class of entry to be returned.
967 * @param array $extraHeaders Extra headers to add to the request, as an
968 * array of string-based key/value pairs.
969 * @return Zend_Gdata_App_Entry The entry returned by the service after
970 * insertion.
971 */
972 public function insertEntry($data, $uri, $className='Zend_Gdata_App_Entry',
973 $extraHeaders = array())
974 {
975 if (!class_exists($className, false)) {
976 require_once 'Zend/Loader.php';
977 @Zend_Loader::loadClass($className);
978 }
979
980 $response = $this->post($data, $uri, null, null, $extraHeaders);
981
982 $returnEntry = new $className($response->getBody());
983 $returnEntry->setHttpClient(self::getstaticHttpClient());
984
985 $etag = $response->getHeader('ETag');
986 if ($etag !== null) {
987 $returnEntry->setEtag($etag);
988 }
989
990 return $returnEntry;
991 }
992
993 /**
994 * Update an entry
995 *
996 * @param mixed $data Zend_Gdata_App_Entry or XML (w/ID and link rel='edit')
997 * @param string|null The URI to send requests to, or null if $data
998 * contains the URI.
999 * @param string|null The name of the class that should be deserialized
1000 * from the server response. If null, then 'Zend_Gdata_App_Entry'
1001 * will be used.
1002 * @param array $extraHeaders Extra headers to add to the request, as an
1003 * array of string-based key/value pairs.
1004 * @return Zend_Gdata_App_Entry The entry returned from the server
1005 * @throws Zend_Gdata_App_Exception
1006 */
1007 public function updateEntry($data, $uri = null, $className = null,
1008 $extraHeaders = array())
1009 {
1010 if ($className === null && $data instanceof Zend_Gdata_App_Entry) {
1011 $className = get_class($data);
1012 } elseif ($className === null) {
1013 $className = 'Zend_Gdata_App_Entry';
1014 }
1015
1016 if (!class_exists($className, false)) {
1017 require_once 'Zend/Loader.php';
1018 @Zend_Loader::loadClass($className);
1019 }
1020
1021 $response = $this->put($data, $uri, null, null, $extraHeaders);
1022 $returnEntry = new $className($response->getBody());
1023 $returnEntry->setHttpClient(self::getstaticHttpClient());
1024
1025 $etag = $response->getHeader('ETag');
1026 if ($etag !== null) {
1027 $returnEntry->setEtag($etag);
1028 }
1029
1030 return $returnEntry;
1031 }
1032
1033 /**
1034 * Provides a magic factory method to instantiate new objects with
1035 * shorter syntax than would otherwise be required by the Zend Framework
1036 * naming conventions. For instance, to construct a new
1037 * Zend_Gdata_Calendar_Extension_Color, a developer simply needs to do
1038 * $gCal->newColor(). For this magic constructor, packages are searched
1039 * in the same order as which they appear in the $_registeredPackages
1040 * array
1041 *
1042 * @param string $method The method name being called
1043 * @param array $args The arguments passed to the call
1044 * @throws Zend_Gdata_App_Exception
1045 */
1046 public function __call($method, $args)
1047 {
1048 if (preg_match('/^new(\w+)/', $method, $matches)) {
1049 $class = $matches[1];
1050 $foundClassName = null;
1051 foreach ($this->_registeredPackages as $name) {
1052 try {
1053 // Autoloading disabled on next line for compatibility
1054 // with magic factories. See ZF-6660.
1055 if (!class_exists($name . '_' . $class, false)) {
1056 require_once 'Zend/Loader.php';
1057 @Zend_Loader::loadClass($name . '_' . $class);
1058 }
1059 $foundClassName = $name . '_' . $class;
1060 break;
1061 } catch (Zend_Exception $e) {
1062 // package wasn't here- continue searching
1063 }
1064 }
1065 if ($foundClassName != null) {
1066 $reflectionObj = new ReflectionClass($foundClassName);
1067 $instance = $reflectionObj->newInstanceArgs($args);
1068 if ($instance instanceof Zend_Gdata_App_FeedEntryParent) {
1069 $instance->setHttpClient($this->_httpClient);
1070
1071 // Propogate version data
1072 $instance->setMajorProtocolVersion(
1073 $this->_majorProtocolVersion);
1074 $instance->setMinorProtocolVersion(
1075 $this->_minorProtocolVersion);
1076 }
1077 return $instance;
1078 } else {
1079 require_once 'Zend/Gdata/App/Exception.php';
1080 throw new Zend_Gdata_App_Exception(
1081 "Unable to find '${class}' in registered packages");
1082 }
1083 } else {
1084 require_once 'Zend/Gdata/App/Exception.php';
1085 throw new Zend_Gdata_App_Exception("No such method ${method}");
1086 }
1087 }
1088
1089 /**
1090 * Retrieve all entries for a feed, iterating through pages as necessary.
1091 * Be aware that calling this function on a large dataset will take a
1092 * significant amount of time to complete. In some cases this may cause
1093 * execution to timeout without proper precautions in place.
1094 *
1095 * @param object $feed The feed to iterate through.
1096 * @return mixed A new feed of the same type as the one originally
1097 * passed in, containing all relevent entries.
1098 */
1099 public function retrieveAllEntriesForFeed($feed) {
1100 $feedClass = get_class($feed);
1101 $reflectionObj = new ReflectionClass($feedClass);
1102 $result = $reflectionObj->newInstance();
1103 do {
1104 foreach ($feed as $entry) {
1105 $result->addEntry($entry);
1106 }
1107
1108 $next = $feed->getLink('next');
1109 if ($next !== null) {
1110 $feed = $this->getFeed($next->href, $feedClass);
1111 } else {
1112 $feed = null;
1113 }
1114 }
1115 while ($feed != null);
1116 return $result;
1117 }
1118
1119 /**
1120 * This method enables logging of requests by changing the
1121 * Zend_Http_Client_Adapter used for performing the requests.
1122 * NOTE: This will not work if you have customized the adapter
1123 * already to use a proxy server or other interface.
1124 *
1125 * @param string $logfile The logfile to use when logging the requests
1126 */
1127 public function enableRequestDebugLogging($logfile)
1128 {
1129 $this->_httpClient->setConfig(array(
1130 'adapter' => 'Zend_Gdata_App_LoggingHttpClientAdapterSocket',
1131 'logfile' => $logfile
1132 ));
1133 }
1134
1135 /**
1136 * Retrieve next set of results based on a given feed.
1137 *
1138 * @param Zend_Gdata_App_Feed $feed The feed from which to
1139 * retreive the next set of results.
1140 * @param string $className (optional) The class of feed to be returned.
1141 * If null, the next feed (if found) will be the same class as
1142 * the feed that was given as the first argument.
1143 * @return Zend_Gdata_App_Feed|null Returns a
1144 * Zend_Gdata_App_Feed or null if no next set of results
1145 * exists.
1146 */
1147 public function getNextFeed($feed, $className = null)
1148 {
1149 $nextLink = $feed->getNextLink();
1150 if (!$nextLink) {
1151 return null;
1152 }
1153 $nextLinkHref = $nextLink->getHref();
1154
1155 if ($className === null) {
1156 $className = get_class($feed);
1157 }
1158
1159 return $this->getFeed($nextLinkHref, $className);
1160 }
1161
1162 /**
1163 * Retrieve previous set of results based on a given feed.
1164 *
1165 * @param Zend_Gdata_App_Feed $feed The feed from which to
1166 * retreive the previous set of results.
1167 * @param string $className (optional) The class of feed to be returned.
1168 * If null, the previous feed (if found) will be the same class as
1169 * the feed that was given as the first argument.
1170 * @return Zend_Gdata_App_Feed|null Returns a
1171 * Zend_Gdata_App_Feed or null if no previous set of results
1172 * exists.
1173 */
1174 public function getPreviousFeed($feed, $className = null)
1175 {
1176 $previousLink = $feed->getPreviousLink();
1177 if (!$previousLink) {
1178 return null;
1179 }
1180 $previousLinkHref = $previousLink->getHref();
1181
1182 if ($className === null) {
1183 $className = get_class($feed);
1184 }
1185
1186 return $this->getFeed($previousLinkHref, $className);
1187 }
1188
1189 /**
1190 * Returns the data for an If-Match header based on the current Etag
1191 * property. If Etags are not supported by the server or cannot be
1192 * extracted from the data, then null will be returned.
1193 *
1194 * @param boolean $allowWeak If false, then if a weak Etag is detected,
1195 * then return null rather than the Etag.
1196 * @return string|null $data
1197 */
1198 public function generateIfMatchHeaderData($data, $allowWeek)
1199 {
1200 $result = '';
1201 // Set an If-Match header if an ETag has been set (version >= 2 only)
1202 if ($this->_majorProtocolVersion >= 2 &&
1203 $data instanceof Zend_Gdata_App_Entry) {
1204 $etag = $data->getEtag();
1205 if (($etag !== null) &&
1206 ($allowWeek || substr($etag, 0, 2) != 'W/')) {
1207 $result = $data->getEtag();
1208 }
1209 }
1210 return $result;
1211 }
1212
1213 /**
1214 * Determine whether service object is using XML to object mapping.
1215 *
1216 * @return boolean True if service object is using XML to object mapping,
1217 * false otherwise.
1218 */
1219 public function usingObjectMapping()
1220 {
1221 return $this->_useObjectMapping;
1222 }
1223
1224 /**
1225 * Enable/disable the use of XML to object mapping.
1226 *
1227 * @param boolean $value Pass in true to use the XML to object mapping.
1228 * Pass in false or null to disable it.
1229 * @return void
1230 */
1231 public function useObjectMapping($value)
1232 {
1233 if ($value === True) {
1234 $this->_useObjectMapping = true;
1235 } else {
1236 $this->_useObjectMapping = false;
1237 }
1238 }
1239
1240}