Rss Atom Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require debril/rss-atom-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Debril\RssAtomBundle\DebrilRssAtomBundle::class => ['all' => true],
   ];
   

2. First Use Case: Consuming a Feed Inject the FeedIo service and fetch a feed:

   use Debril\RssAtomBundle\FeedIo;
   
   public function __construct(private FeedIo $feedIo) {}
   
   public function getFeed(string $url): array
   {
       return $this->feedIo->load($url);
   }
   

3. First Use Case: Generating a Feed Create a controller extending StreamController:

   use Debril\RssAtomBundle\Controller\StreamController;
   
   class MyFeedController extends StreamController
   {
       public function feedAction()
       {
           return $this->renderFeed(
               'my_feed',
               [
                   'title' => 'My Feed',
                   'items' => [
                       ['title' => 'Item 1', 'link' => '/item1'],
                       ['title' => 'Item 2', 'link' => '/item2'],
                   ],
               ]
           );
       }
   }
   

   Route it in config/routes.yaml:

   my_feed:
       path: /feed
       controller: App\Controller\MyFeedController::feedAction
       methods: GET
   

Implementation Patterns

Consuming Feeds

1. Fetching and Parsing Use FeedIo to load and parse feeds dynamically:

   $feed = $this->feedIo->load('https://example.com/feed.rss');
   $items = $feed->getItems(); // Array of parsed feed items
   

2. Detecting Feed Type Automatically detect format (RSS, Atom, JSONFeed):

   $format = $this->feedIo->detectFormat($url);
   

3. Handling Enclosures Extract media attachments:

   foreach ($feed->getItems() as $item) {
       if ($enclosure = $item->getEnclosure()) {
           $url = $enclosure->getUrl();
           $type = $enclosure->getType();
       }
   }
   

Generating Feeds

1. StreamController Workflow Extend StreamController for efficient feed generation:

   public function feedAction()
   {
       return $this->renderFeed(
           'blog_feed',
           [
               'title' => 'Blog Updates',
               'items' => $this->getLatestPosts(),
           ],
           ['format' => 'atom'] // Optional: Force format
       );
   }
   

2. Dynamic Feed Updates Leverage HTTP caching (304 Not Modified) by comparing ETags:

   $this->renderFeed('feed', $data, [
       'etag' => md5(json_encode($data)),
   ]);
   

3. Custom Templates Override default templates in templates/DebrilRssAtomBundle/:

   • atom.xml.twig
   • rss.xml.twig
   • jsonfeed.json.twig

4. Integration with Doctrine Fetch entities and map to feed items:

   $items = $this->entityManager
       ->getRepository(Post::class)
       ->findBy([], ['createdAt' => 'DESC'], 10)
       ->map(fn(Post $post) => [
           'title' => $post->getTitle(),
           'link' => $post->getSlug(),
           'published' => $post->getCreatedAt()->format(DATE_ATOM),
       ]);
   

Gotchas and Tips

Common Pitfalls

1. ETag Mismatches

   • Ensure ETags are consistent across requests. Use a deterministic hash (e.g., md5(json_encode($data))).
   • Avoid regenerating ETags for unchanged data to prevent unnecessary 200 responses.

2. Template Overrides

   • If custom templates aren’t loading, verify the templates/DebrilRssAtomBundle/ directory exists and permissions are correct.
   • Clear the cache after adding new templates:

     php bin/console cache:clear
     

3. FeedIo Timeouts

   • Default timeout is 10 seconds. Adjust in config (config/packages/debril_rss_atom.yaml):

     debril_rss_atom:
         feed_io:
             timeout: 30
     

4. Character Encoding

   • Ensure feed items use UTF-8. Sanitize content before rendering:

     $title = mb_convert_encoding($post->getTitle(), 'UTF-8');
     

Debugging Tips

1. Log Feed Parsing Issues Enable debug mode to log parsing errors:

   debril_rss_atom:
       feed_io:
           debug: true
   

2. Validate Feed Output Use online validators (e.g., W3C Feed Validation) to check generated feeds.

3. Check Headers Inspect HTTP headers for caching issues:

   curl -I http://your-app/feed
   

   Look for ETag and Last-Modified headers.

Extension Points

1. Custom Feed Formats Extend Debril\RssAtomBundle\Feed\FeedInterface to support additional formats.

2. Event Listeners Subscribe to feed events (e.g., feed.io.load):

   // config/services.yaml
   services:
       App\EventListener\FeedListener:
           tags:
               - { name: kernel.event_listener, event: feed.io.load, method: onFeedLoad }
   

3. Twig Extensions Add custom Twig filters for feed-specific logic:

   // src/Twig/AppExtension.php
   class AppExtension extends \Twig\Extension\AbstractExtension
   {
       public function getFilters()
       {
           return [
               new \Twig\TwigFilter('feed_date', [$this, 'formatFeedDate']),
           ];
       }
   
       public function formatFeedDate(\DateTimeInterface $date): string
       {
           return $date->format(DATE_ATOM);
       }
   }
   

4. Symfony Messenger Integration Use Messenger to asynchronously process feed updates:

   $this->messageBus->dispatch(new UpdateFeedMessage($feedUrl));