Chris@0: # Zend\\Feed\\PubSubHubbub
Chris@0: 
Chris@0: `Zend\Feed\PubSubHubbub` is an implementation of the [PubSubHubbub Core 0.2/0.3
Chris@0: Specification (Working Draft)](http://pubsubhubbub.googlecode.com/svn/trunk/pubsubhubbub-core-0.3.html).
Chris@0: It offers implementations of a Pubsubhubbub Publisher and Subscriber suited to
Chris@0: PHP applications.
Chris@0: 
Chris@0: ## What is PubSubHubbub?
Chris@0: 
Chris@0: Pubsubhubbub is an open, simple, web-scale, pubsub protocol. A common use case
Chris@0: to enable blogs (Publishers) to "push" updates from their RSS or Atom feeds
Chris@0: (Topics) to end Subscribers. These Subscribers will have subscribed to the
Chris@0: blog's RSS or Atom feed via a Hub, a central server which is notified of any
Chris@0: updates by the Publisher, and which then distributes these updates to all
Chris@0: Subscribers. Any feed may advertise that it supports one or more Hubs using an
Chris@0: Atom namespaced link element with a rel attribute of "hub" (i.e., `rel="hub"`).
Chris@0: 
Chris@0: Pubsubhubbub has garnered attention because it is a pubsub protocol which is
Chris@0: easy to implement and which operates over HTTP. Its philosophy is to replace the
Chris@0: traditional model where blog feeds have been polled at regular intervals to
Chris@0: detect and retrieve updates. Depending on the frequency of polling, this can
Chris@0: take a lot of time to propagate updates to interested parties from planet
Chris@0: aggregators to desktop readers. With a pubsub system in place, updates are not
Chris@0: simply polled by Subscribers, they are pushed to Subscribers, eliminating any
Chris@0: delay. For this reason, Pubsubhubbub forms part of what has been dubbed the
Chris@0: real-time web.
Chris@0: 
Chris@0: The protocol does not exist in isolation. Pubsub systems have been around for a
Chris@0: while, such as the familiar Jabber Publish-Subscribe protocol,
Chris@0: [XEP-0060](http://www.xmpp.org/extensions/xep-0060.html), or the less well-known
Chris@0: [rssCloud](http://www.rssboard.org/rsscloud-interface) (described in 2001).
Chris@0: However, these have not achieved widespread adoption due to either their
Chris@0: complexity, poor timing, or lack of suitability for web applications. rssCloud,
Chris@0: which was recently revived as a response to the appearance of Pubsubhubbub, has
Chris@0: also seen its usage increase significantly, though it lacks a formal
Chris@0: specification and currently does not support Atom 1.0 feeds.
Chris@0: 
Chris@0: Perhaps surprisingly given its relative early age, Pubsubhubbub is already in
Chris@0: use including in Google Reader and Feedburner, and there are plugins available
Chris@0: for Wordpress blogs.
Chris@0: 
Chris@0: ## Architecture
Chris@0: 
Chris@0: `Zend\Feed\PubSubHubbub` implements two sides of the Pubsubhubbub 0.2/0.3
Chris@0: Specification: a Publisher and a Subscriber. It does not currently implement a
Chris@0: Hub Server.
Chris@0: 
Chris@0: A Publisher is responsible for notifying all supported Hubs (many can be
Chris@0: supported to add redundancy to the system) of any updates to its feeds, whether
Chris@0: they be Atom or RSS based. This is achieved by pinging the supported Hub Servers
Chris@0: with the URL of the updated feed. In Pubsubhubbub terminology, any updatable
Chris@0: resource capable of being subscribed to is referred to as a Topic. Once a ping
Chris@0: is received, the Hub will request the updated feed, process it for updated
Chris@0: items, and forward all updates to all Subscribers subscribed to that feed.
Chris@0: 
Chris@0: A Subscriber is any party or application which subscribes to one or more Hubs to
Chris@0: receive updates from a Topic hosted by a Publisher. The Subscriber never
Chris@0: directly communicates with the Publisher since the Hub acts as an intermediary,
Chris@0: accepting subscriptions and sending updates to Subscribers. The Subscriber
Chris@0: therefore communicates only with the Hub, either to subscribe or unsubscribe to
Chris@0: Topics, or when it receives updates from the Hub. This communication design
Chris@0: ("Fat Pings") effectively removes the possibility of a "Thundering Herd" issue.
Chris@0: (Thundering Herds occur in a pubsub system where the Hub merely informs
Chris@0: Subscribers that an update is available, prompting all Subscribers to
Chris@0: immediately retrieve the feed from the Publisher, giving rise to a traffic
Chris@0: spike.) In Pubsubhubbub, the Hub distributes the actual update in a "Fat Ping"
Chris@0: so the Publisher is not subjected to any traffic spike.
Chris@0: 
Chris@0: `Zend\Feed\PubSubHubbub` implements Pubsubhubbub Publishers and Subscribers with
Chris@0: the classes `Zend\Feed\PubSubHubbub\Publisher` and
Chris@0: `Zend\Feed\PubSubHubbub\Subscriber`. In addition, the Subscriber implementation
Chris@0: may handle any feed updates forwarded from a Hub by using
Chris@0: `Zend\Feed\PubSubHubbub\Subscriber\Callback`. These classes, their use cases,
Chris@0: and etheir APIs are covered in subsequent sections.
Chris@0: 
Chris@0: ## Zend\\Feed\\PubSubHubbub\\Publisher
Chris@0: 
Chris@0: In Pubsubhubbub, the Publisher is the party publishing a live feed with content
Chris@0: updates. This may be a blog, an aggregator, or even a web service with a public
Chris@0: feed based API. In order for these updates to be pushed to Subscribers, the
Chris@0: Publisher must notify all of its supported Hubs that an update has occurred
Chris@0: using a simple HTTP POST request containing the URI of the updated Topic (i.e.,
Chris@0: the updated RSS or Atom feed). The Hub will confirm receipt of the notification,
Chris@0: fetch the updated feed, and forward any updates to any Subscribers who have
Chris@0: subscribed to that Hub for updates from the relevant feed.
Chris@0: 
Chris@0: By design, this means the Publisher has very little to do except send these Hub
Chris@0: pings whenever its feeds change. As a result, the Publisher implementation is
Chris@0: extremely simple to use and requires very little work to setup and use when
Chris@0: feeds are updated.
Chris@0: 
Chris@0: `Zend\Feed\PubSubHubbub\Publisher` implements a full Pubsubhubbub Publisher. Its
Chris@0: setup for use primarily requires that it is configured with the URI endpoint for
Chris@0: all Hubs to be notified of updates, and the URIs of all Topics to be included in
Chris@0: the notifications.
Chris@0: 
Chris@0: The following example shows a Publisher notifying a collection of Hubs about
Chris@0: updates to a pair of local RSS and Atom feeds. The class retains a collection of
Chris@0: errors which include the Hub URLs, so that notification can be attempted again
Chris@0: later and/or logged if any notifications happen to fail.  Each resulting error
Chris@0: array also includes a "response" key containing the related HTTP response
Chris@0: object. In the event of any errors, it is strongly recommended to attempt the
Chris@0: operation for failed Hub Endpoints at least once more at a future time. This may
Chris@0: require the use of either a scheduled task for this purpose or a job queue,
Chris@0: though such extra steps are optional.
Chris@0: 
Chris@0: ```php
Chris@0: use Zend\Feed\PubSubHubbub\Publisher;
Chris@0: 
Chris@0: $publisher = Publisher;
Chris@0: $publisher->addHubUrls([
Chris@0:     'http://pubsubhubbub.appspot.com/',
Chris@0:     'http://hubbub.example.com',
Chris@0: ]);
Chris@0: $publisher->addUpdatedTopicUrls([
Chris@0:     'http://www.example.net/rss',
Chris@0:     'http://www.example.net/atom',
Chris@0: ]);
Chris@0: $publisher->notifyAll();
Chris@0: 
Chris@0: if (! $publisher->isSuccess()) {
Chris@0:     // check for errors
Chris@0:     $errors     = $publisher->getErrors();
Chris@0:     $failedHubs = [];
Chris@0:     foreach ($errors as $error) {
Chris@0:         $failedHubs[] = $error['hubUrl'];
Chris@0:     }
Chris@0: }
Chris@0: 
Chris@0: // reschedule notifications for the failed Hubs in $failedHubs
Chris@0: ```
Chris@0: 
Chris@0: If you prefer having more concrete control over the Publisher, the methods
Chris@0: `addHubUrls()` and `addUpdatedTopicUrls()` pass each array value to the singular
Chris@0: `addHubUrl()` and `addUpdatedTopicUrl()` public methods. There are also matching
Chris@0: `removeUpdatedTopicUrl()` and `removeHubUrl()` methods.
Chris@0: 
Chris@0: You can also skip setting Hub URIs, and notify each in turn using the
Chris@0: `notifyHub()` method which accepts the URI of a Hub endpoint as its only
Chris@0: argument.
Chris@0: 
Chris@0: There are no other tasks to cover. The Publisher implementation is very simple
Chris@0: since most of the feed processing and distribution is handled by the selected
Chris@0: Hubs. It is, however, important to detect errors and reschedule notifications as
Chris@0: soon as possible (with a reasonable maximum number of retries) to ensure
Chris@0: notifications reach all Subscribers. In many cases, as a final alternative, Hubs
Chris@0: may frequently poll your feeds to offer some additional tolerance for failures
Chris@0: both in terms of their own temporary downtime or Publisher errors or downtime.
Chris@0: 
Chris@0: ## Zend\\Feed\\PubSubHubbub\\Subscriber
Chris@0: 
Chris@0: In Pubsubhubbub, the Subscriber is the party who wishes to receive updates to
Chris@0: any Topic (RSS or Atom feed). They achieve this by subscribing to one or more of
Chris@0: the Hubs advertised by that Topic, usually as a set of one or more Atom 1.0
Chris@0: links with a rel attribute of "hub" (i.e., `rel="hub"`). The Hub from that point
Chris@0: forward will send an Atom or RSS feed containing all updates to that
Chris@0: Subscriber's callback URL when it receives an update notification from the
Chris@0: Publisher. In this way, the Subscriber need never actually visit the original
Chris@0: feed (though it's still recommended at some level to ensure updates are
Chris@0: retrieved if ever a Hub goes offline). All subscription requests must contain
Chris@0: the URI of the Topic being subscribed and a callback URL which the Hub will use
Chris@0: to confirm the subscription and to forward updates.
Chris@0: 
Chris@0: The Subscriber therefore has two roles. The first is to *create* and *manage*
Chris@0: subscriptions, including subscribing for new Topics with a Hub, unsubscribing
Chris@0: (if necessary), and periodically renewing subscriptions, since they may have an
Chris@0: expiry set by the Hub. This is handled by `Zend\Feed\PubSubHubbub\Subscriber`.
Chris@0: 
Chris@0: The second role is to *accept updates* sent by a Hub to the Subscriber's
Chris@0: callback URL, i.e. the URI the Subscriber has assigned to handle updates. The
Chris@0: callback URL also handles events where the Hub contacts the Subscriber to
Chris@0: confirm all subscriptions and unsubscriptions. This is handled by using an
Chris@0: instance of `Zend\Feed\PubSubHubbub\Subscriber\Callback` when the callback URL
Chris@0: is accessed.
Chris@0: 
Chris@0: > ### Query strings in callback URLs
Chris@0: >
Chris@0: > `Zend\Feed\PubSubHubbub\Subscriber` implements the Pubsubhubbub 0.2/0.3
Chris@0: > specification. As this is a new specification version, not all Hubs currently
Chris@0: > implement it. The new specification allows the callback URL to include a query
Chris@0: > string which is used by this class, but not supported by all Hubs. In the
Chris@0: > interests of maximising compatibility, it is therefore recommended that the
Chris@0: > query string component of the Subscriber callback URI be presented as a path
Chris@0: > element, i.e. recognised as a parameter in the route associated with the
Chris@0: > callback URI and used by the application's router.
Chris@0: 
Chris@0: ### Subscribing and Unsubscribing
Chris@0: 
Chris@0: `Zend\Feed\PubSubHubbub\Subscriber` implements a full Pubsubhubbub Subscriber
Chris@0: capable of subscribing to, or unsubscribing from, any Topic via any Hub
Chris@0: advertised by that Topic. It operates in conjunction with
Chris@0: `Zend\Feed\PubSubHubbub\Subscriber\Callback`, which accepts requests from a Hub
Chris@0: to confirm all subscription or unsubscription attempts (to prevent third-party
Chris@0: misuse).
Chris@0: 
Chris@0: Any subscription (or unsubscription) requires the relevant information before
Chris@0: proceeding, i.e. the URI of the Topic (Atom or RSS feed) to be subscribed to for
Chris@0: updates, and the URI of the endpoint for the Hub which will handle the
Chris@0: subscription and forwarding of the updates. The lifetime of a subscription may
Chris@0: be determined by the Hub, but most Hubs should support automatic subscription
Chris@0: refreshes by checking with the Subscriber. This is supported by
Chris@0: `Zend\Feed\PubSubHubbub\Subscriber\Callback` and requires no other work on your
Chris@0: part. It is still strongly recommended that you use the Hub-sourced subscription
Chris@0: time-to.live (ttl) to schedule the creation of new subscriptions (the process is
Chris@0: identical to that for any new subscription) to refresh it with the Hub. While it
Chris@0: should not be necessary per se, it covers cases where a Hub may not support
Chris@0: automatic subscription refreshing, and rules out Hub errors for additional
Chris@0: redundancy.
Chris@0: 
Chris@0: With the relevant information to hand, a subscription can be attempted as
Chris@0: demonstrated below:
Chris@0: 
Chris@0: ```php
Chris@0: use Zend\Feed\PubSubHubbub\Model\Subscription;
Chris@0: use Zend\Feed\PubSubHubbub\Subscriber;
Chris@0: 
Chris@0: $storage    = new Subscription;
Chris@0: $subscriber = new Subscriber;
Chris@0: $subscriber->setStorage($storage);
Chris@0: $subscriber->addHubUrl('http://hubbub.example.com');
Chris@0: $subscriber->setTopicUrl('http://www.example.net/rss.xml');
Chris@0: $subscriber->setCallbackUrl('http://www.mydomain.com/hubbub/callback');
Chris@0: $subscriber->subscribeAll();
Chris@0: ```
Chris@0: 
Chris@0: In order to store subscriptions and offer access to this data for general use,
Chris@0: the component requires a database (a schema is provided later in this section).
Chris@0: By default, it is assumed the table name is "subscription", and it utilises
Chris@0: `Zend\Db\TableGateway\TableGateway` in the background, meaning it will use the
Chris@0: default adapter you have set for your application. You may also pass a specific
Chris@0: custom `Zend\Db\TableGateway\TableGateway` instance into the associated model
Chris@0: `Zend\Feed\PubSubHubbub\Model\Subscription`. This custom adapter may be as
Chris@0: simple in intent as changing the table name to use or as complex as you deem
Chris@0: necessary.
Chris@0: 
Chris@0: While this model is offered as a default ready-to-roll solution, you may create
Chris@0: your own model using any other backend or database layer (e.g. Doctrine) so long
Chris@0: as the resulting class implements the interface
Chris@0: `Zend\Feed\PubSubHubbub\Model\SubscriptionInterface`.
Chris@0: 
Chris@0: An example schema (MySQL) for a subscription table accessible by the provided
Chris@0: model may look similar to:
Chris@0: 
Chris@0: ```sql
Chris@0: CREATE TABLE IF NOT EXISTS `subscription` (
Chris@0:   `id` varchar(32) COLLATE utf8_unicode_ci NOT NULL DEFAULT '',
Chris@0:   `topic_url` varchar(255) COLLATE utf8_unicode_ci DEFAULT NULL,
Chris@0:   `hub_url` varchar(255) COLLATE utf8_unicode_ci DEFAULT NULL,
Chris@0:   `created_time` datetime DEFAULT NULL,
Chris@0:   `lease_seconds` bigint(20) DEFAULT NULL,
Chris@0:   `verify_token` varchar(255) COLLATE utf8_unicode_ci DEFAULT NULL,
Chris@0:   `secret` varchar(255) COLLATE utf8_unicode_ci DEFAULT NULL,
Chris@0:   `expiration_time` datetime DEFAULT NULL,
Chris@0:   `subscription_state` varchar(12) COLLATE utf8_unicode_ci DEFAULT NULL,
Chris@0:   PRIMARY KEY (`id`)
Chris@0: ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;
Chris@0: ```
Chris@0: 
Chris@0: Behind the scenes, the Subscriber above will send a request to the Hub endpoint
Chris@0: containing the following parameters (based on the previous example):
Chris@0: 
Chris@0: Parameter | Value | Explanation
Chris@0: --------- | ----- | -----------
Chris@0: `hub.callback` | `http://www.mydomain.com/hubbub/callback?xhub.subscription=5536df06b5dcb966edab3a4c4d56213c16a8184` | The URI used by a Hub to contact the Subscriber and either request confirmation of a (un)subscription request, or send updates from subscribed feeds. The appended query string contains a custom parameter (hence the xhub designation). It is a query string parameter preserved by the Hub and re-sent with all Subscriber requests. Its purpose is to allow the Subscriber to identify and look up the subscription associated with any Hub request in a backend storage medium. This is a non-standard parameter used by this component in preference to encoding a subscription key in the URI path, which is difficult to enforce generically. Nevertheless, since not all Hubs support query string parameters, we still strongly recommend adding the subscription key as a path component in the form `http://www.mydomain.com/hubbub/callback/5536df06b5dcb966edab3a4c4d56213c16a8184`.  This requires defining a route capable of parsing out the final value of the key, retrieving the value, and passing it to the Subscriber callback object. The value should be passed into the method `Zend\PubSubHubbub\Subscriber\Callback::setSubscriptionKey()`. A detailed example is offered later.
Chris@0: `hub.lease_seconds` | `2592000` | The number of seconds for which the Subscriber would like a new subscription to remain valid (i.e. a TTL). Hubs may enforce their own maximum subscription period. All subscriptions should be renewed by re-subscribing before the subscription period ends to ensure continuity of updates. Hubs should additionally attempt to automatically refresh subscriptions before they expire by contacting Subscribers (handled automatically by the `Callback` class).
Chris@0: `hub.mode` | `subscribe` | Value indicating this is a subscription request. Unsubscription requests would use the "unsubscribe" value.
Chris@0: `hub.topic` | `http://www.example.net/rss.xml` | The URI of the Topic (i.e. Atom or RSS feed) which the Subscriber wishes to subscribe to for updates.
Chris@0: `hub.verify` | `sync` or `async` | Indicates to the Hub the preferred mode of verifying subscriptions or unsubscriptions. It is repeated twice in order of preference. Technically this component does not distinguish between the two modes and treats both equally.
Chris@0: `hub.verify_token` | `3065919804abcaa7212ae89.879827871253878386` | A verification token returned to the Subscriber by the Hub when it is confirming a subscription or unsubscription. Offers a measure of reliance that the confirmation request originates from the correct Hub to prevent misuse.
Chris@0: 
Chris@0: You can modify several of these parameters to indicate a different preference.
Chris@0: For example, you can set a different lease seconds value using
Chris@0: `Zend\Feed\PubSubHubbub\Subscriber::setLeaseSeconds(),` or show a preference for
Chris@0: the `async` verify mode by using `setPreferredVerificationMode(Zend\Feed\PubSubHubbub\PubSubHubbub::VERIFICATION_MODE_ASYNC)`.
Chris@0: However, the Hubs retain the capability to enforce their own preferences, and
Chris@0: for this reason the component is deliberately designed to work across almost any
Chris@0: set of options with minimum end-user configuration required. Conventions are
Chris@0: great when they work!
Chris@0: 
Chris@0: > ### Verification modes
Chris@0: >
Chris@0: > While Hubs may require the use of a specific verification mode (both are
Chris@0: > supported by `Zend\Feed\PubSubHubbub`), you may indicate a specific preference
Chris@0: > using the `setPreferredVerificationMode()` method. In `sync` (synchronous)
Chris@0: > mode, the Hub attempts to confirm a subscription as soon as it is received,
Chris@0: > and before responding to the subscription request. In `async` (asynchronous)
Chris@0: > mode, the Hub will return a response to the subscription request immediately,
Chris@0: > and its verification request may occur at a later time. Since
Chris@0: > `Zend\Feed\PubSubHubbub` implements the Subscriber verification role as a
Chris@0: > separate callback class and requires the use of a backend storage medium, it
Chris@0: > actually supports both transparently. In terms of end-user performance,
Chris@0: > asynchronous verification is very much preferred to eliminate the impact of a
Chris@0: > poorly performing Hub tying up end-user server resources and connections for
Chris@0: > too long.
Chris@0: 
Chris@0: Unsubscribing from a Topic follows the exact same pattern as the previous
Chris@0: example, with the exception that we should call `unsubscribeAll()` instead. The
Chris@0: parameters included are identical to a subscription request with the exception
Chris@0: that `hub.mode` is set to "unsubscribe".
Chris@0: 
Chris@0: By default, a new instance of `Zend\PubSubHubbub\Subscriber` will attempt to use
Chris@0: a database backed storage medium which defaults to using the default zend-db
Chris@0: adapter with a table name of "subscription". It is recommended to set a custom
Chris@0: storage solution where these defaults are not apt either by passing in a new
Chris@0: model supporting the required interface or by passing a new instance of
Chris@0: `Zend\Db\TableGateway\TableGateway` to the default model's constructor to change
Chris@0: the used table name.
Chris@0: 
Chris@0: ### Handling Subscriber Callbacks
Chris@0: 
Chris@0: Whenever a subscription or unsubscription request is made, the Hub must verify
Chris@0: the request by forwarding a new verification request to the callback URL set in
Chris@0: the subscription or unsubscription parameters. To handle these Hub requests,
Chris@0: which will include all future communications containing Topic (feed) updates,
Chris@0: the callback URL should trigger the execution of an instance of
Chris@0: `Zend\Feed\PubSubHubbub\Subscriber\Callback` to handle the request.
Chris@0: 
Chris@0: The `Callback` class should be configured to use the same storage medium as the
Chris@0: `Subscriber` class. The bulk of the work is handled internal to these classes.
Chris@0: 
Chris@0: ```php
Chris@0: use Zend\Feed\PubSubHubbub\Model\Subscription;
Chris@0: use Zend\Feed\PubSubHubbub\Subscriber\Callback;
Chris@0: 
Chris@0: $storage = new Subscription();
Chris@0: $callback = new Callback();
Chris@0: $callback->setStorage($storage);
Chris@0: $callback->handle();
Chris@0: $callback->sendResponse();
Chris@0: 
Chris@0: /*
Chris@0:  * Check if the callback resulting in the receipt of a feed update.
Chris@0:  * Otherwise it was either a (un)sub verification request or invalid request.
Chris@0:  * Typically we need do nothing other than add feed update handling; the rest
Chris@0:  * is handled internally by the class.
Chris@0:  */
Chris@0: if ($callback->hasFeedUpdate()) {
Chris@0:     $feedString = $callback->getFeedUpdate();
Chris@0:     /*
Chris@0:      * Process the feed update asynchronously to avoid a Hub timeout.
Chris@0:      */
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: > #### Query and body parameters
Chris@0: >
Chris@0: > It should be noted that `Zend\Feed\PubSubHubbub\Subscriber\Callback` may
Chris@0: > independently parse any incoming query string and other parameters. This is
Chris@0: > necessary since PHP alters the structure and keys of a query string when it is
Chris@0: > parsed into the `$_GET` or `$_POST` superglobals; for example, all duplicate
Chris@0: > keys are ignored and periods are converted to underscores. Pubsubhubbub
Chris@0: > features both of these in the query strings it generates.
Chris@0: 
Chris@0: > #### Always delay feed processing
Chris@0: >
Chris@0: > It is essential that developers recognise that Hubs are only concerned with
Chris@0: > sending requests and receiving a response which verifies its receipt. If a
Chris@0: > feed update is received, it should never be processed on the spot since this
Chris@0: > leaves the Hub waiting for a response. Rather, any processing should be
Chris@0: > offloaded to another process or deferred until after a response has been
Chris@0: > returned to the Hub. One symptom of a failure to promptly complete Hub
Chris@0: > requests is that a Hub may continue to attempt delivery of the update or
Chris@0: > verification request leading to duplicated update attempts being processed by
Chris@0: > the Subscriber. This appears problematic, but in reality a Hub may apply a
Chris@0: > timeout of just a few seconds, and if no response is received within that time
Chris@0: > it may disconnect (assuming a delivery failure) and retry later. Note that
Chris@0: > Hubs are expected to distribute vast volumes of updates so their resources are
Chris@0: > stretched; please process feeds asynchronously (e.g. in a separate process or
Chris@0: > a job queue or even a cronjob) as much as possible.
Chris@0: 
Chris@0: ### Setting Up And Using A Callback URL Route
Chris@0: 
Chris@0: As noted earlier, the `Zend\Feed\PubSubHubbub\Subscriber\Callback` class
Chris@0: receives the combined key associated with any subscription from the Hub via one
Chris@0: of two methods. The technically preferred method is to add this key to the
Chris@0: callback URL employed by the Hub in all future requests using a query string
Chris@0: parameter with the key `xhub.subscription`. However, for historical reasons
Chris@0: (primarily that this was not supported in Pubsubhubbub 0.1, and a late addition
Chris@0: to 0.2 ), it is strongly recommended to use the most compatible means of adding
Chris@0: this key to the callback URL by appending it to the URL's path.
Chris@0: 
Chris@0: Thus the URL `http://www.example.com/callback?xhub.subscription=key` would become
Chris@0: `http://www.example.com/callback/key`.
Chris@0: 
Chris@0: Since the query string method is the default in anticipation of a greater level
Chris@0: of future support for the full 0.2/0.3 specification, this requires some
Chris@0: additional work to implement.
Chris@0: 
Chris@0: The first step is to make the `Zend\Feed\PubSubHubbub\Subscriber\Callback` class
Chris@0: aware of the path contained subscription key. It's manually injected; therefore
Chris@0: it also requires manually defining a route for this purpose. This is achieved by
Chris@0: called the method `Zend\Feed\PubSubHubbub\Subscriber\Callback::setSubscriptionKey()`
Chris@0: with the parameter being the key value available from the router. The example
Chris@0: below demonstrates this using a zend-mvc controller.
Chris@0: 
Chris@0: ```php
Chris@0: use Zend\Feed\PubSubHubbub\Model\Subscription;
Chris@0: use Zend\Feed\PubSubHubbub\Subscriber\Callback;
Chris@0: use Zend\Mvc\Controller\AbstractActionController;
Chris@0: 
Chris@0: class CallbackController extends AbstractActionController
Chris@0: {
Chris@0: 
Chris@0:     public function indexAction()
Chris@0:     {
Chris@0:         $storage = new Subscription();
Chris@0:         $callback = new Callback();
Chris@0:         $callback->setStorage($storage);
Chris@0: 
Chris@0:         /*
Chris@0:          * Inject subscription key parsing from URL path using
Chris@0:          * a parameter from the router.
Chris@0:          */
Chris@0:         $subscriptionKey = $this->params()->fromRoute('subkey');
Chris@0:         $callback->setSubscriptionKey($subscriptionKey);
Chris@0:         $callback->handle();
Chris@0:         $callback->sendResponse();
Chris@0: 
Chris@0:         /*
Chris@0:          * Check if the callback resulting in the receipt of a feed update.
Chris@0:          * Otherwise it was either a (un)sub verification request or invalid
Chris@0:          * request. Typically we need do nothing other than add feed update
Chris@0:          * handling; the rest is handled internally by the class.
Chris@0:          */
Chris@0:         if ($callback->hasFeedUpdate()) {
Chris@0:             $feedString = $callback->getFeedUpdate();
Chris@0:             /*
Chris@0:              *  Process the feed update asynchronously to avoid a Hub timeout.
Chris@0:              */
Chris@0:         }
Chris@0:     }
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: The example below illustrates adding a route mapping the path segment to a route
Chris@0: parameter, using zend-mvc:
Chris@0: 
Chris@0: ```php
Chris@0: use Zend\Mvc\Router\Http\Segment as SegmentRoute;;
Chris@0: 
Chris@0: // Route defininition for enabling appending of a PuSH Subscription's lookup key
Chris@0: $route = SegmentRoute::factory([
Chris@0:    'route' => '/callback/:subkey',
Chris@0:    'constraints' => [
Chris@0:       'subkey' => '[a-z0-9]+',
Chris@0:    ],
Chris@0:    'defaults' => [
Chris@0:       'controller' => 'application-index',
Chris@0:       'action' => 'index',
Chris@0:    ]
Chris@0: ]);
Chris@0: ```