<?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_Feed_Pubsubhubbub

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

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

 * @version    $Id: Subscriber.php 24593 2012-01-05 20:35:02Z matthew $

 */

/**

 * @see Zend_Feed_Pubsubhubbub

 */

require_once 'Zend/Feed/Pubsubhubbub.php';

/**

 * @see Zend_Date

 */

require_once 'Zend/Date.php';

/**

 * @category   Zend

 * @package    Zend_Feed_Pubsubhubbub

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

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

 */

class Zend_Feed_Pubsubhubbub_Subscriber

{

    /**

     * An array of URLs for all Hub Servers to subscribe/unsubscribe.

     *

     * @var array

     */

    protected $_hubUrls = array();

    /**

     * An array of optional parameters to be included in any

     * (un)subscribe requests.

     *

     * @var array

     */

    protected $_parameters = array();

    /**

     * The URL of the topic (Rss or Atom feed) which is the subject of

     * our current intent to subscribe to/unsubscribe from updates from

     * the currently configured Hub Servers.

     *

     * @var string

     */

    protected $_topicUrl = '';

    /**

     * The URL Hub Servers must use when communicating with this Subscriber

     *

     * @var string

     */

    protected $_callbackUrl = '';

    /**

     * The number of seconds for which the subscriber would like to have the

     * subscription active. Defaults to null, i.e. not sent, to setup a

     * permanent subscription if possible.

     *

     * @var int

     */

    protected $_leaseSeconds = null;

    /**

     * The preferred verification mode (sync or async). By default, this

     * Subscriber prefers synchronous verification, but is considered

     * desireable to support asynchronous verification if possible.

     *

     * Zend_Feed_Pubsubhubbub_Subscriber will always send both modes, whose

     * order of occurance in the parameter list determines this preference.

     *

     * @var string

     */

    protected $_preferredVerificationMode

        = Zend_Feed_Pubsubhubbub::VERIFICATION_MODE_SYNC;

    /**

     * An array of any errors including keys for 'response', 'hubUrl'.

     * The response is the actual Zend_Http_Response object.

     *

     * @var array

     */

    protected $_errors = array();

    /**

     * An array of Hub Server URLs for Hubs operating at this time in

     * asynchronous verification mode.

     *

     * @var array

     */

    protected $_asyncHubs = array();

    /**

     * An instance of Zend_Feed_Pubsubhubbub_Model_SubscriptionInterface used to background

     * save any verification tokens associated with a subscription or other.

     *

     * @var Zend_Feed_Pubsubhubbub_Model_SubscriptionInterface

     */

    protected $_storage = null;

    /**

     * An array of authentication credentials for HTTP Basic Authentication

     * if required by specific Hubs. The array is indexed by Hub Endpoint URI

     * and the value is a simple array of the username and password to apply.

     *

     * @var array

     */

    protected $_authentications = array();

    /**

     * Tells the Subscriber to append any subscription identifier to the path

     * of the base Callback URL. E.g. an identifier "subkey1" would be added

     * to the callback URL "http://www.example.com/callback" to create a subscription

     * specific Callback URL of "http://www.example.com/callback/subkey1".

     *

     * This is required for all Hubs using the Pubsubhubbub 0.1 Specification.

     * It should be manually intercepted and passed to the Callback class using

     * Zend_Feed_Pubsubhubbub_Subscriber_Callback::setSubscriptionKey(). Will

     * require a route in the form "callback/:subkey" to allow the parameter be

     * retrieved from an action using the Zend_Controller_Action::_getParam()

     * method.

     *

     * @var string

     */

    protected $_usePathParameter = false;

    /**

     * Constructor; accepts an array or Zend_Config instance to preset

     * options for the Subscriber without calling all supported setter

     * methods in turn.

     *

     * @param  array|Zend_Config $options Options array or Zend_Config instance

     * @return void

     */

    public function __construct($config = null)

    {

        if ($config !== null) {

            $this->setConfig($config);

        }

    }

    /**

     * Process any injected configuration options

     *

     * @param  array|Zend_Config $options Options array or Zend_Config instance

     * @return Zend_Feed_Pubsubhubbub_Subscriber

     */

    public function setConfig($config)

    {

        if ($config instanceof Zend_Config) {

            $config = $config->toArray();

        } elseif (!is_array($config)) {

            require_once 'Zend/Feed/Pubsubhubbub/Exception.php';

            throw new Zend_Feed_Pubsubhubbub_Exception('Array or Zend_Config object'

                . ' expected, got ' . gettype($config));

        }

        if (array_key_exists('hubUrls', $config)) {

            $this->addHubUrls($config['hubUrls']);

        }

        if (array_key_exists('callbackUrl', $config)) {

            $this->setCallbackUrl($config['callbackUrl']);

        }

        if (array_key_exists('topicUrl', $config)) {

            $this->setTopicUrl($config['topicUrl']);

        }

        if (array_key_exists('storage', $config)) {

            $this->setStorage($config['storage']);

        }

        if (array_key_exists('leaseSeconds', $config)) {

            $this->setLeaseSeconds($config['leaseSeconds']);

        }

        if (array_key_exists('parameters', $config)) {

            $this->setParameters($config['parameters']);

        }

        if (array_key_exists('authentications', $config)) {

            $this->addAuthentications($config['authentications']);

        }

        if (array_key_exists('usePathParameter', $config)) {

            $this->usePathParameter($config['usePathParameter']);

        }

        if (array_key_exists('preferredVerificationMode', $config)) {

            $this->setPreferredVerificationMode(

                $config['preferredVerificationMode']

            );

        }

        return $this;

    }

    /**

     * Set the topic URL (RSS or Atom feed) to which the intended (un)subscribe

     * event will relate

     *

     * @param  string $url

     * @return Zend_Feed_Pubsubhubbub_Subscriber

     */

    public function setTopicUrl($url)

    {

        if (empty($url) || !is_string($url) || !Zend_Uri::check($url)) {

            require_once 'Zend/Feed/Pubsubhubbub/Exception.php';

            throw new Zend_Feed_Pubsubhubbub_Exception('Invalid parameter "url"'

                .' of "' . $url . '" must be a non-empty string and a valid'

                .' URL');

        }

        $this->_topicUrl = $url;

        return $this;

    }

    /**

     * Set the topic URL (RSS or Atom feed) to which the intended (un)subscribe

     * event will relate

     *

     * @return string

     */

    public function getTopicUrl()

    {

        if (empty($this->_topicUrl)) {

            require_once 'Zend/Feed/Pubsubhubbub/Exception.php';

            throw new Zend_Feed_Pubsubhubbub_Exception('A valid Topic (RSS or Atom'

                . ' feed) URL MUST be set before attempting any operation');

        }

        return $this->_topicUrl;

    }

    /**

     * Set the number of seconds for which any subscription will remain valid

     *

     * @param  int $seconds

     * @return Zend_Feed_Pubsubhubbub_Subscriber

     */

    public function setLeaseSeconds($seconds)

    {

        $seconds = intval($seconds);

        if ($seconds <= 0) {

            require_once 'Zend/Feed/Pubsubhubbub/Exception.php';

            throw new Zend_Feed_Pubsubhubbub_Exception('Expected lease seconds'

                . ' must be an integer greater than zero');

        }

        $this->_leaseSeconds = $seconds;

        return $this;

    }

    /**

     * Get the number of lease seconds on subscriptions

     *

     * @return int

     */

    public function getLeaseSeconds()

    {

        return $this->_leaseSeconds;

    }

    /**

     * Set the callback URL to be used by Hub Servers when communicating with

     * this Subscriber

     *

     * @param  string $url

     * @return Zend_Feed_Pubsubhubbub_Subscriber

     */

    public function setCallbackUrl($url)

    {

        if (empty($url) || !is_string($url) || !Zend_Uri::check($url)) {

            require_once 'Zend/Feed/Pubsubhubbub/Exception.php';

            throw new Zend_Feed_Pubsubhubbub_Exception('Invalid parameter "url"'

                . ' of "' . $url . '" must be a non-empty string and a valid'

                . ' URL');

        }

        $this->_callbackUrl = $url;

        return $this;

    }

    /**

     * Get the callback URL to be used by Hub Servers when communicating with

     * this Subscriber

     *

     * @return string

     */

    public function getCallbackUrl()

    {

        if (empty($this->_callbackUrl)) {

            require_once 'Zend/Feed/Pubsubhubbub/Exception.php';

            throw new Zend_Feed_Pubsubhubbub_Exception('A valid Callback URL MUST be'

                . ' set before attempting any operation');

        }

        return $this->_callbackUrl;

    }

    /**

     * Set preferred verification mode (sync or async). By default, this

     * Subscriber prefers synchronous verification, but does support

     * asynchronous if that's the Hub Server's utilised mode.

     *

     * Zend_Feed_Pubsubhubbub_Subscriber will always send both modes, whose

     * order of occurance in the parameter list determines this preference.

     *

     * @param  string $mode Should be 'sync' or 'async'

     * @return Zend_Feed_Pubsubhubbub_Subscriber

     */

    public function setPreferredVerificationMode($mode)

    {

        if ($mode !== Zend_Feed_Pubsubhubbub::VERIFICATION_MODE_SYNC

        && $mode !== Zend_Feed_Pubsubhubbub::VERIFICATION_MODE_ASYNC) {

            require_once 'Zend/Feed/Pubsubhubbub/Exception.php';

            throw new Zend_Feed_Pubsubhubbub_Exception('Invalid preferred'

                . ' mode specified: "' . $mode . '" but should be one of'

                . ' Zend_Feed_Pubsubhubbub::VERIFICATION_MODE_SYNC or'

                . ' Zend_Feed_Pubsubhubbub::VERIFICATION_MODE_ASYNC');

        }

        $this->_preferredVerificationMode = $mode;

        return $this;

    }

    /**

     * Get preferred verification mode (sync or async).

     *

     * @return string

     */

    public function getPreferredVerificationMode()

    {

        return $this->_preferredVerificationMode;

    }

    /**

     * Add a Hub Server URL supported by Publisher

     *

     * @param  string $url

     * @return Zend_Feed_Pubsubhubbub_Subscriber

     */

    public function addHubUrl($url)

    {

        if (empty($url) || !is_string($url) || !Zend_Uri::check($url)) {

            require_once 'Zend/Feed/Pubsubhubbub/Exception.php';

            throw new Zend_Feed_Pubsubhubbub_Exception('Invalid parameter "url"'

                . ' of "' . $url . '" must be a non-empty string and a valid'

                . ' URL');

        }

        $this->_hubUrls[] = $url;

        return $this;

    }

    /**

     * Add an array of Hub Server URLs supported by Publisher

     *

     * @param  array $urls

     * @return Zend_Feed_Pubsubhubbub_Subscriber

     */

    public function addHubUrls(array $urls)

    {

        foreach ($urls as $url) {

            $this->addHubUrl($url);

        }

        return $this;

    }

    /**

     * Remove a Hub Server URL

     *

     * @param  string $url

     * @return Zend_Feed_Pubsubhubbub_Subscriber

     */

    public function removeHubUrl($url)

    {

        if (!in_array($url, $this->getHubUrls())) {

            return $this;

        }

        $key = array_search($url, $this->_hubUrls);

        unset($this->_hubUrls[$key]);

        return $this;

    }

    /**

     * Return an array of unique Hub Server URLs currently available

     *

     * @return array

     */

    public function getHubUrls()

    {

        $this->_hubUrls = array_unique($this->_hubUrls);

        return $this->_hubUrls;

    }

    /**

     * Add authentication credentials for a given URL

     *

     * @param  string $url

     * @param  array $authentication

     * @return Zend_Feed_Pubsubhubbub_Subscriber

     */

    public function addAuthentication($url, array $authentication)

    {

        if (empty($url) || !is_string($url) || !Zend_Uri::check($url)) {

            require_once 'Zend/Feed/Pubsubhubbub/Exception.php';

            throw new Zend_Feed_Pubsubhubbub_Exception('Invalid parameter "url"'

                . ' of "' . $url . '" must be a non-empty string and a valid'

                . ' URL');

        }

        $this->_authentications[$url] = $authentication;

        return $this;

    }

    /**

     * Add authentication credentials for hub URLs

     *

     * @param  array $authentications

     * @return Zend_Feed_Pubsubhubbub_Subscriber

     */

    public function addAuthentications(array $authentications)

    {

        foreach ($authentications as $url => $authentication) {

            $this->addAuthentication($url, $authentication);

        }

        return $this;

    }

    /**

     * Get all hub URL authentication credentials

     *

     * @return array

     */

    public function getAuthentications()

    {

        return $this->_authentications;

    }

    /**

     * Set flag indicating whether or not to use a path parameter

     *

     * @param  bool $bool

     * @return Zend_Feed_Pubsubhubbub_Subscriber

     */

    public function usePathParameter($bool = true)

    {

        $this->_usePathParameter = $bool;

        return $this;

    }

    /**

     * Add an optional parameter to the (un)subscribe requests