<?php

/**

 * Zend Framework

 *

 * LICENSE

 *

 * This source file is subject to the new BSD license that is bundled

 * with this package in the file LICENSE.txt.

 * It is also available through the world-wide-web at this URL:

 * http://framework.zend.com/license/new-bsd

 * If you did not receive a copy of the license and are unable to

 * obtain it through the world-wide-web, please send an email

 * to license@zend.com so we can send you a copy immediately.

 *

 * @category   Zend

 * @package    Zend_Gdata

 * @subpackage App

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 * @version    $Id: App.php 22972 2010-09-18 20:33:53Z ramon $

 */

/**

 * Zend_Gdata_Feed

 */

require_once 'Zend/Gdata/App/Feed.php';

/**

 * Zend_Gdata_Http_Client

 */

require_once 'Zend/Http/Client.php';

/**

 * Zend_Version

 */

require_once 'Zend/Version.php';

/**

 * Zend_Gdata_App_MediaSource

 */

require_once 'Zend/Gdata/App/MediaSource.php';

/**

 * Provides Atom Publishing Protocol (APP) functionality.  This class and all

 * other components of Zend_Gdata_App are designed to work independently from

 * other Zend_Gdata components in order to interact with generic APP services.

 *

 * @category   Zend

 * @package    Zend_Gdata

 * @subpackage App

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 */

class Zend_Gdata_App

{

    /** Default major protocol version.

      *

      * @see _majorProtocolVersion

      */

    const DEFAULT_MAJOR_PROTOCOL_VERSION = 1;

    /** Default minor protocol version.

      *

      * @see _minorProtocolVersion

      */

    const DEFAULT_MINOR_PROTOCOL_VERSION = null;

    /**

     * Client object used to communicate

     *

     * @var Zend_Http_Client

     */

    protected $_httpClient;

    /**

     * Client object used to communicate in static context

     *

     * @var Zend_Http_Client

     */

    protected static $_staticHttpClient = null;

    /**

     * Override HTTP PUT and DELETE request methods?

     *

     * @var boolean

     */

    protected static $_httpMethodOverride = false;

    /**

     * Enable gzipped responses?

     *

     * @var boolean

     */

    protected static $_gzipEnabled = false;

    /**

     * Use verbose exception messages.  In the case of HTTP errors,

     * use the body of the HTTP response in the exception message.

     *

     * @var boolean

     */

    protected static $_verboseExceptionMessages = true;

    /**

     * Default URI to which to POST.

     *

     * @var string

     */

    protected $_defaultPostUri = null;

    /**

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

     *

     * @var array

     */

    protected $_registeredPackages = array(

            'Zend_Gdata_App_Extension',

            'Zend_Gdata_App');

    /**

     * Maximum number of redirects to follow during HTTP operations

     *

     * @var int

     */

    protected static $_maxRedirects = 5;

    /**

      * Indicates the major protocol version that should be used.

      * 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 setMajorProtocolVersion()

      * @see getMajorProtocolVersion()

      */

    protected $_majorProtocolVersion;

    /**

      * 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.

      *

      * 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 setMinorProtocolVersion()

      * @see getMinorProtocolVersion()

      */

    protected $_minorProtocolVersion;

    /**

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

     *

     * @var boolean

     */

    protected $_useObjectMapping = true;

    /**

     * Create Gdata object

     *

     * @param Zend_Http_Client $client

     * @param string $applicationId

     */

    public function __construct($client = null, $applicationId = 'MyCompany-MyApp-1.0')

    {

        $this->setHttpClient($client, $applicationId);

        // Set default protocol version. Subclasses should override this as

        // needed once a given service supports a new version.

        $this->setMajorProtocolVersion(self::DEFAULT_MAJOR_PROTOCOL_VERSION);

        $this->setMinorProtocolVersion(self::DEFAULT_MINOR_PROTOCOL_VERSION);

    }

    /**

     * Adds a Zend Framework package to the $_registeredPackages array.

     * This array is searched when using the magic __call method below

     * to instantiante new objects.

     *

     * @param string $name The name of the package (eg Zend_Gdata_App)

     * @return void

     */

    public function registerPackage($name)

    {

        array_unshift($this->_registeredPackages, $name);

    }

    /**

     * Retrieve feed as string or object

     *

     * @param string $uri The uri from which to retrieve the feed

     * @param string $className The class which is used as the return type

     * @return string|Zend_Gdata_App_Feed Returns string only if the object

     *                                    mapping has been disabled explicitly

     *                                    by passing false to the

     *                                    useObjectMapping() function.

     */

    public function getFeed($uri, $className='Zend_Gdata_App_Feed')

    {

        return $this->importUrl($uri, $className, null);

    }

    /**

     * Retrieve entry as string or object

     *

     * @param string $uri

     * @param string $className The class which is used as the return type

     * @return string|Zend_Gdata_App_Entry Returns string only if the object

     *                                     mapping has been disabled explicitly

     *                                     by passing false to the

     *                                     useObjectMapping() function.

     */

    public function getEntry($uri, $className='Zend_Gdata_App_Entry')

    {

        return $this->importUrl($uri, $className, null);

    }

    /**

     * Get the Zend_Http_Client object used for communication

     *

     * @return Zend_Http_Client

     */

    public function getHttpClient()

    {

        return $this->_httpClient;

    }

    /**

     * Set the Zend_Http_Client object used for communication

     *

     * @param Zend_Http_Client $client The client to use for communication

     * @throws Zend_Gdata_App_HttpException

     * @return Zend_Gdata_App Provides a fluent interface

     */

    public function setHttpClient($client,

        $applicationId = 'MyCompany-MyApp-1.0')

    {

        if ($client === null) {

            $client = new Zend_Http_Client();

        }

        if (!$client instanceof Zend_Http_Client) {

            require_once 'Zend/Gdata/App/HttpException.php';

            throw new Zend_Gdata_App_HttpException(

                'Argument is not an instance of Zend_Http_Client.');

        }

        $userAgent = $applicationId . ' Zend_Framework_Gdata/' .

            Zend_Version::VERSION;

        $client->setHeaders('User-Agent', $userAgent);

        $client->setConfig(array(

            'strictredirects' => true

            )

        );

        $this->_httpClient = $client;

        self::setStaticHttpClient($client);

        return $this;

    }

    /**

     * Set the static HTTP client instance

     *

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

     *

     * @param  Zend_Http_Client $httpClient

     * @return void

     */

    public static function setStaticHttpClient(Zend_Http_Client $httpClient)

    {

        self::$_staticHttpClient = $httpClient;

    }

    /**

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

     *

     * @return Zend_Http_Client

     */

    public static function getStaticHttpClient()

    {

        if (!self::$_staticHttpClient instanceof Zend_Http_Client) {

            $client = new Zend_Http_Client();

            $userAgent = 'Zend_Framework_Gdata/' . Zend_Version::VERSION;

            $client->setHeaders('User-Agent', $userAgent);

            $client->setConfig(array(

                'strictredirects' => true

                )

            );

            self::$_staticHttpClient = $client;

        }

        return self::$_staticHttpClient;

    }

    /**

     * Toggle using POST instead of PUT and DELETE HTTP methods

     *

     * 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.

     *

     * @param  boolean $override Whether to override PUT and DELETE with POST.

     * @return void

     */

    public static function setHttpMethodOverride($override = true)

    {

        self::$_httpMethodOverride = $override;

    }

    /**

     * Get the HTTP override state

     *

     * @return boolean

     */

    public static function getHttpMethodOverride()

    {

        return self::$_httpMethodOverride;

    }

    /**

     * Toggle requesting gzip encoded responses

     *

     * @param  boolean $enabled Whether or not to enable gzipped responses

     * @return void

     */

    public static function setGzipEnabled($enabled = false)

    {

        if ($enabled && !function_exists('gzinflate')) {

            require_once 'Zend/Gdata/App/InvalidArgumentException.php';

            throw new Zend_Gdata_App_InvalidArgumentException(

                    'You cannot enable gzipped responses if the zlib module ' .

                    'is not enabled in your PHP installation.');

        }

        self::$_gzipEnabled = $enabled;

    }

    /**

     * Get the HTTP override state

     *

     * @return boolean

     */

    public static function getGzipEnabled()

    {

        return self::$_gzipEnabled;

    }

    /**

     * Get whether to use verbose exception messages

     *

     * In the case of HTTP errors,  use the body of the HTTP response

     * in the exception message.

     *

     * @return boolean

     */

    public static function getVerboseExceptionMessages()

    {

        return self::$_verboseExceptionMessages;

    }

    /**

     * Set whether to use verbose exception messages

     *

     * In the case of HTTP errors, use the body of the HTTP response

     * in the exception message.

     *

     * @param boolean $verbose Whether to use verbose exception messages

     */

    public static function setVerboseExceptionMessages($verbose)

    {

        self::$_verboseExceptionMessages = $verbose;

    }

    /**

     * Set the maximum number of redirects to follow during HTTP operations

     *

     * @param int $maxRedirects Maximum number of redirects to follow

     * @return void

     */

    public static function setMaxRedirects($maxRedirects)

    {

        self::$_maxRedirects = $maxRedirects;

    }

    /**

     * Get the maximum number of redirects to follow during HTTP operations

     *

     * @return int Maximum number of redirects to follow

     */

    public static function getMaxRedirects()

    {

        return self::$_maxRedirects;

    }

    /**

     * Set the major protocol version that should be used. Values < 1 will

     * cause a Zend_Gdata_App_InvalidArgumentException to be thrown.

     *

     * @see _majorProtocolVersion

     * @param int $value The major protocol version to use.

     * @throws Zend_Gdata_App_InvalidArgumentException

     */

    public function setMajorProtocolVersion($value)

    {

        if (!($value >= 1)) {

            require_once('Zend/Gdata/App/InvalidArgumentException.php');

            throw new Zend_Gdata_App_InvalidArgumentException(

                    'Major protocol version must be >= 1');

        }

        $this->_majorProtocolVersion = $value;

    }

    /**

     * Get the major protocol version that is in use.

     *

     * @see _majorProtocolVersion

     * @return int The major protocol version in use.

     */

    public function getMajorProtocolVersion()

    {

        return $this->_majorProtocolVersion;

    }

    /**

     * 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.

     *

     * @see _minorProtocolVersion

     * @param (int|NULL) $value The minor protocol version to use.

     * @throws Zend_Gdata_App_InvalidArgumentException

     */

    public function setMinorProtocolVersion($value)

    {

        if (!($value >= 0)) {

            require_once('Zend/Gdata/App/InvalidArgumentException.php');

            throw new Zend_Gdata_App_InvalidArgumentException(

                    'Minor protocol version must be >= 0');

        }

        $this->_minorProtocolVersion = $value;

    }

    /**

     * Get the minor protocol version that is in use.

     *

     * @see _minorProtocolVersion

     * @return (int|NULL) The major protocol version in use, or NULL if no

     *         minor version is specified.

     */

    public function getMinorProtocolVersion()

    {

        return $this->_minorProtocolVersion;

    }

    /**

     * Provides pre-processing for HTTP requests to APP services.

     *

     * 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()

     *

     * @param string $method The HTTP method for the request - 'GET', 'POST',

     *                       'PUT', 'DELETE'