debril / rss-atom-bundle
RSS / Atom and JSONFeed support for Symfony
Installs: 1 115 249
Dependents: 7
Suggesters: 0
Security: 0
Stars: 139
Watchers: 7
Forks: 49
Open Issues: 4
Type:symfony-bundle
Requires
- php: >=7.1
- debril/feed-io: ~3.0|~4.0|~5.0
- symfony/config: ~3.4|~4.0|^5.0|^6.0|^7.0
- symfony/dependency-injection: ~3.4|~4.0|^5.0|^6.0|^7.0
- symfony/http-foundation: ~3.4|~4.0|^5.0|^6.0|^7.0
- symfony/http-kernel: ~3.4|~4.0|^5.0|^6.0|^7.0
Requires (Dev)
- doctrine/common: ~2.3
- phpunit/phpunit: ~7.0
- symfony/browser-kit: >3.0
- symfony/finder: >3.0
- symfony/framework-bundle: ^4.3|^5.0|^6.0|^7.0
- symfony/validator: >3.0
- symfony/yaml: ^4.0|^5.0|^6.0|^7.0
- dev-master
- v5.2.0
- v5.1.3
- v5.1.2
- v5.1.1
- v5.1.0
- v5.0.5
- v5.0.4
- v5.0.3
- v5.0.2
- v5.0.1
- v5.0
- v4.3.0
- v4.2.2
- v4.2.1
- v4.2.0
- v4.1.1
- v4.1.0
- v4.0.4
- v4.0.3
- v4.0.2
- v4.0.1
- v4.0.0
- v3.0.11
- v3.0.10
- v3.0.9
- v3.0.8
- v3.0.7
- v3.0.6
- v3.0.5
- v3.0.4
- v3.0.3
- v3.0.2
- v3.0.1
- v3.0.0
- v2.5.3
- v2.5.2
- v2.5.1
- v2.5.0
- v2.4.3
- v2.4.2
- v2.4.1
- v2.4.0
- v2.3.3
- v2.3.2
- v2.3.2-rc1
- v2.3.1
- v2.3.0
- v2.2.0
- 2.1.0
- 2.0.0
- 1.8.2
- 1.8.1
- 1.8.0
- 1.7.0
- 1.6.0
- 1.5.6
- 1.5.5
- 1.5.4
- 1.5.3
- 1.5.2
- 1.5.1
- 1.5.0
- 1.5-beta
- 1.4.4
- 1.4.3
- 1.4.2
- 1.4.0
- 1.3.2
- 1.3.1
- 1.2.15
- 1.2.0
- 1.1.6
- 1.1.0
- 1.0.1
- 1.0.0
- dev-dependabot/composer/guzzlehttp/psr7-1.9.1
- dev-feature/php-7.4
- dev-bsod85-issue170
- dev-issue/158
- dev-release/4.1
- dev-release/4.0
- dev-release/3.x
- dev-release/2.x
This package is auto-updated.
Last update: 2024-11-30 01:59:13 UTC
README
RssAtomBundle is a Bundle for Symfony made to easily access and deliver JSON / RSS / Atom feeds. It is built on top of feed-io and features:
- Detection of the feed format (JSON / RSS / Atom)
- enclosures support
- A generic StreamController built to write all your feeds. This controller is able to send a 304 HTTP Code if the feed didn't change since the last visit
- HTTP Headers support when reading feeds in order to save network traffic
- Content filtering to fetch only the newest items
- multiple feeds writing
- Ability to use doctrine as a data source
- PSR compliant logging
- DateTime detection and conversion
- Guzzle Client integration
Keep informed about new releases and incoming features : http://debril.org/category/rss-atom-bundle
You can try rss-atom-bundle through its Demo.
Installation
Dependencies
As a Symfony Bundle, RssAtomBundle must be installed using Composer. If you do not know Composer, please refer to its website: http://getcomposer.org/
Your application uses Symfony 3.3 or later
Activate Symfony's contrib recipes and use Composer to require the bundle :
composer config extra.symfony.allow-contrib true
composer require debril/rss-atom-bundle
That's it. To check the installation, you can start your application and hit http://localhost:8000/rss in your browser. You should see a mock RSS stream.
If your application uses Symfony < 3.3
Install the bundle using Composer :
composer require debril/rss-atom-bundle
Add the bundle's routing configuration in app/config/routing.yml :
rssatom: resource: "@DebrilRssAtomBundle/Resources/config/routing.yml"
Edit your app/AppKernel.php to register the bundle in the registerBundles() method as above:
class AppKernel extends Kernel { public function registerBundles() { $bundles = array( new Symfony\Bundle\FrameworkBundle\FrameworkBundle(), // ... // register the bundle here new Debril\RssAtomBundle\DebrilRssAtomBundle(),
Usage
rss-atom-bundle is designed to read feeds across the internet and to publish your own using feed-io feed-io provides two interfaces, each one being dedicated to feed's consuming and publishing :
- FeedInterface to handle the feed
- ItemInterface to handle feed's items
Getting a FeedIo instance
You can fetch a FeedIo\FeedIo
instance through dependency injection or the service container.
Dependency injection (highly recommended)
namespace App\Feed; class Consumer { /** * @type \FeedIo\FeedIo */ private $feedIo; public function __construct(FeedIo $feedIo) { $this->feedIo = $feedIo; } }
Service Container
Wherever you have access to the service container :
<?php // get feedio $feedIo = $this->container->get('feedio');
Feed Reading
To read a feed you need to use the feedio
service which provides two methods for that : read()
and readSince()
. This service is based upon FeedIo.
using read()
read()
is designed to give a brand new Feed instance or any object of your own, as long as it implements the FeedInterface interface. It takes three arguments :
$url
: URL of the RSS/Atom feed you want to read (eg: http://php.net/feed.atom)$feed
(optional) : a FeedInterface instance. The default is a new\FeedIo\Feed
instance$modifiedSince
(optional) : the last time you read this feed. This is useful to fetch only the articles which were published after your last hit.
With a \FeedIo\FeedIo
instance called $feedIo
:
<?php // this date is used to fetch only the latest items $modifiedSince = new \DateTime($date); // the feed you want to read $url = 'http://host.tld/feed'; // now fetch its (fresh) content $feed = $feedIo->read($url, new \Acme\Entity\Feed, $modifiedSince)->getFeed(); foreach ( $feed as $item ) { echo "item title : {$item->getTitle()} \n "; // getMedias() returns enclosures if any $medias = $item->getMedias(); } ?>
read()
fetches the feed hosted at $url
and removes items prior to $modifiedSince
. If it is the first time you read this feed, then you must specify a date far enough in the past to keep all the items. This method does not loop until the $modifiedSince
is reached, it justs performs one hit and filters the response to keep only the fresh articles.
using readSince()
readSince()
helps you get a \FeedIo\Feed
without creating its instance :
<?php // get feedio $feedIo = $this->container->get('feedio'); // this date is used to fetch only the latest items $modifiedSince = new \DateTime($date); // the feed you want to read $url = 'http://host.tld/feed'; // now fetch its (fresh) content $feed = $feedIo->readSince($url, $modifiedSince)->getFeed(); ?>
Providing feeds
RssAtomBundle offers the ability to provide JSON/RSS/Atom feeds. The route will match the following pattern : /{format}/{contentId}
- {format} must be "rss" or "atom" (or whatever you want if you add the good routing rule in routing.yml)
- {contentId} is an optional argument. Use it you have several feeds
The request will be handled by StreamController
, according to the following steps :
- 1 : grabs the ModifiedSince header if it exists
- 2 : creates an
Options
instance holding the request's parameters (contentId if it exists) - 3 : gets the provider defined in services.yml and calls the
getFeedContent(Options $options)
method - 4 : compare the feed's LastModified property with the ModifiedSince header
- 5 : if LastModified is prior or equal to ModifiedSince then the response contains only a "NotModified" header and the 304 code. Otherwise, the stream is built and sent to the client
Defining you own provider
You must give to RssAtomBundle the content you want it to display in the feed. For that, two steps :
- write a class that implements
FeedProviderInterface
. This class that we call a 'provider' will be in charge of building the feed. - configure the dependency injection to make RssAtomBundle use it
FeedContentProviderInterface implementation
Your class just needs to implement the Debril\RssAtomBundle\Provider\FeedProviderInterface
interface, for instance :
<?php # src/Feed/Provider.php namespace App\Feed; use FeedIo\Feed; use FeedIo\FeedInterface; use FeedIo\Feed\Item; use Debril\RssAtomBundle\Provider\FeedContentProviderInterface; class Provider implements FeedProviderInterface { /** * @param array $options * @return \FeedIo\FeedInterface * @throws \Debril\RssAtomBundle\Exception\FeedNotFoundException */ public function getFeed(Request $request) : FeedInterface { // build the feed the way you want $feed = new Feed(); $feed->setTitle('your title'); foreach($this->getItems() as $item ) { $feed->add($item); } return $feed; } protected function getItems() { foreach($this->fetchFromStorage() as $storedItem) { $item = new Item; $item->setTitle($storedItem->getTitle()); // ... yield $item; } } protected function fetchFromStorage() { // query the database to fetch items } }
StreamController expects the getFeed()'s return value to be a FeedIo\FeedInterface
instance. It can be a FeedIo\Feed
or a class of your own and if so, your class MUST implement \FeedIo\FeedInterface
.
You can also start from this class to save some time : App\Feed\Provider.php
<?php interface FeedInterface extends \Iterator, NodeInterface { /** * This method MUST return the feed's full URL * @return string */ public function getUrl(); /** * @param string $url * @return FeedInterface */ public function setUrl($url); // Full source can be read in the repository ....... ?>
configuration
Now, you need to configure the debril.rss_atom.provider
service with the provider's class in your project's services.yml :
# config/services.yaml parameters: debril.rss_atom.provider.class: 'App\Feed\Provider'
Or, if you need to build it with arguments, you can override debril.rss_atom.provider
's declaration :
# config/services.yaml services: debril.rss_atom.provider: class: App\Feed\Provider arguments: ["@logger", "@doctrine"]
That's it. Go to http://localhost:8000/atom, it should display your feed.
Make the StreamController answer with a 404
If the reclaimed feed does not exist, you just need to throw a FeedNotFoundException to make the StreamController answer with a 404 error. Otherwise, getFeedContent(Options $options)
must return a \FeedIo\FeedInterface
instance. Then, the controller properly turns the object into a XML stream.
More information on the FeedContentProviderInterface interface and how to interface rss-atom-bundle directly with doctrine can be found in the Providing Feeds section
Useful Tips
Skipping 304 HTTP Code
The HTTP cache handling can be annoying during development process, you can skip it through configuration in your app/config/config.yml file :
# config/packages/rss_atom.yaml debril_rss_atom: force_refresh: true
This way, the StreamController
will always display your feed's content and return a 200 HTTP code.
Private feeds
You may have private feeds, user-specific or behind some authentication.
In that case, you don't want to Cache-Control: public
header to be added, not to have your feed cached by a reverse-proxy (such as Symfony AppCache or Varnish).
You can do so by setting private
parameter to true
in config:
# config/packages/rss_atom.yaml debril_rss_atom: private: true
Adding non-standard date formats
Some feeds use date formats which are not compliant with the specifications. You can fix this by adding the format in your configuration
# config/packages/rss_atom.yaml debril_rss_atom: date_formats: - 'Y/M/d'
Using custom Content Type header for feed generation
If you need to customize the Content-Type header of your feed you can specify the value in your configuration
# config/packages/rss_atom.yaml debril_rss_atom: content_type_json: application/json content_type_xml: application/xhtml+xml
Going back to feed-io 3.0
Starting from version 4.1 rss-atom-bundle comes with feed-io 4 if your application depends on PHP 7.1+. If you need to use feed-io 3 instead for some reason, you can do it in composer.json
:
"debril/rss-atom-bundle": "^4.1", "debril/feed-io": "~3.0",
Override tip
It could happen that according to the order of the bundles registered in AppKernel
, this override procedures do not work properly. This happens when a bundle is registered before rss-atom-bundle
.
In this case, you should use the Symfony CompilerPass
as reported in the documentation.
Vendor/Bundle/VendorBundle.php
:
use Vendor\Bundle\DependencyInjection\Compiler\OverrideRssAtomBundleProviderCompilerPass; use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\HttpKernel\Bundle\Bundle; class VendorBundle extends Bundle { public function build(ContainerBuilder $container) { parent::build($container); $container->addCompilerPass(new OverrideRssAtomBundleProviderCompilerPass()); } }
and Vendor/Bundle/DependencyInjection/Compiler/OverrideRssAtomBundleProviderCompilerPass.php
:
use Vendor\Bundle\Provider\FeedProvider; use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface; use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Reference; class OverrideRssAtomBundleProviderCompilerPass implements CompilerPassInterface { public function process(ContainerBuilder $container) { $definition = $container->getDefinition('debril.rss_atom.provider'); $definition->setClass(FeedProvider::class); $definition->addArgument(new Reference('my.service1')); $definition->addArgument(new Reference('my.service2')); } }
You can follow either services.xml
or CompilerPass
but with services, you have to pay attention to bundles registration order.
Fetching the repository
Do this if you want to contribute (and you're welcome to do so):
git clone https://github.com/alexdebril/rss-atom-bundle.git
composer.phar install --dev
Unit Testing
You can run the unit test suites using the following command in the Bundle's source director:
bin/phpunit