Feed Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require argentum/feed-bundle
   

   Enable in config/bundles.php:

   Argentum\FeedBundle\ArgentumFeedBundle::class => ['all' => true],
   

2. Configure Basic Feed Add minimal config in config/packages/argentum_feed.yaml:

   argentum_feed:
       channels:
           news:
               title: 'My News Feed'
               link: '/'
               description: 'Latest updates'
   

3. First Use Case: Generate a Feed In a controller or service:

   use Argentum\FeedBundle\Feed\Feedable;
   
   class News implements Feedable {
       // Implement getFeedItem() as shown in README
   }
   
   // Controller action
   public function generateFeed(FeedFactory $feedFactory) {
       $newsItems = $this->newsRepository->findAllPublished();
       $rss = $feedFactory->createFeed('news')
           ->addFeedableItems($newsItems)
           ->render();
       return new Response($rss, 200, ['Content-Type' => 'application/rss+xml']);
   }
   

Implementation Patterns

1. Feedable Entities

• Pattern: Implement Feedable interface for Eloquent models or DTOs.

• Workflow:

  • Define getFeedItem() to map entity fields to FeedItem properties.
  • Use setRouteName()/setRouteParameters() for Symfony routing (e.g., for link in RSS).
  • Add custom values (e.g., yandex:full-text) via addCustomValue().
  • Attach enclosures (images, files) with addEnclosure().

  Example:

  $item->setRouteName('blog_post_show')
       ->setRouteParameters(['slug' => $post->slug])
       ->addCustomValue('media:content', $post->getFeaturedImageUrl());
  

2. Data Providers

• Pattern: Use repository-based providers to auto-fetch feed items.
• Workflow:
  1. Configure provider in config/argentum_feed.yaml:

     provider:
         repository: 'App\Repository\PostRepository'
         method: 'findPublished'
         arguments: [10]  # Limit 10 items
     

  2. Call render() without manually adding items:

     $feedFactory->createFeed('blog')->render();
     

3. Dynamic Configuration

• Pattern: Override feed settings at runtime.
• Workflow:

  $feed = $feedFactory->createFeed('news')
      ->setTitle('Breaking News')
      ->addCustomNamespace('custom', 'http://example.com/ns')
      ->addCustomElement('custom:priority', 'high');
  

4. Custom Renderers

• Pattern: Extend functionality with custom renderers.
• Workflow:
  1. Create a service tagged argentum_feed.renderer:

     services:
         app.custom_renderer:
             class: App\Feed\CustomRenderer
             tags: ['argentum_feed.renderer']
     

  2. Implement Argentum\FeedBundle\Feed\RendererInterface.

5. Twig Integration

• Pattern: Render feeds in Twig templates.
• Workflow:

  {{ render(controller('App\Controller\FeedController::generateFeed')) }}
  

  Or pass the feed XML directly:

  <iframe srcdoc="{{ feedXml|raw }}"></iframe>
  

6. Namespaces and Custom Elements

• Pattern: Support third-party extensions (e.g., Yandex, Mail.Ru).
• Workflow:
  1. Define namespaces in config:

     namespaces:
         yandex: 'http://news.yandex.ru'
     

  2. Use in Feedable:

     $item->addCustomValue('yandex:full-text', $content);
     

Gotchas and Tips

Pitfalls

1. Routing Issues:

   • If using setRouteName(), ensure the route exists and parameters match.
   • Fix: Test routes with php bin/console debug:router.

2. Absolute URLs:

   • Relative links (e.g., link: '/' in config) are auto-converted to absolute using the request host.
   • Gotcha: In CLI or non-HTTP contexts, use setBaseUrl() explicitly:

     $feed->setBaseUrl('https://example.com');
     

3. Translation Domain:

   • Text fields (e.g., title, description) are translated using translationDomain.
   • Gotcha: Missing translations will render as keys (e.g., {{ news.title }}).
   • Fix: Ensure translations exist in translations/{locale}/news.yaml.

4. Namespace Conflicts:

   • Custom namespaces/elements must match the configured namespaces and customElements in the feed config.
   • Gotcha: Undefined namespaces will cause XML validation errors.
   • Fix: Pre-register namespaces in config or use addCustomNamespace() at runtime.

5. Provider Errors:

   • If provider.repository is misconfigured, render() will fail silently.
   • Fix: Validate repository/method existence:

     $this->newsRepository->findPublished()->count(); // Test first
     

6. Caching:

   • The bundle doesn’t cache feeds by default. For performance:

     $feed->setCacheTTL(3600); // Cache for 1 hour
     

Debugging Tips

1. Inspect FeedItem:

   $item = $news->getFeedItem();
   var_dump($item->toArray()); // Debug structure
   

2. Validate XML: Use an online validator (e.g., W3C Feed Validation) to check output.

3. Log Renderer: Override the renderer to log output:

   class DebugRenderer implements RendererInterface {
       public function render(Feed $feed) {
           file_put_contents('debug_feed.xml', $feed->getXml());
           return parent::render($feed);
       }
   }
   

Extension Points

1. Custom Feed Types:

   • Create a new feed type by extending Argentum\FeedBundle\Feed\Feed and tagging it as argentum_feed.feed.

2. Event Listeners:

   • Listen to argentum_feed.build or argentum_feed.render events to modify feeds dynamically:

     services:
         app.feed_listener:
             class: App\EventListener\FeedListener
             tags:
                 - { name: kernel.event_listener, event: argentum_feed.build, method: onBuild }
     

3. Symfony Cache: Integrate with Symfony’s cache system for feed caching:

   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Contracts\Cache\CacheInterface;
   
   public function generateFeed(FeedFactory $factory, CacheInterface $cache) {
       return $cache->get('feed_news', function() use ($factory) {
           return new Response($factory->createFeed('news')->render(), 200, ['Content-Type' => 'application/rss+xml']);
       }, 3600);
   }
   

Performance Tips

1. Lazy Loading:

   • Use addFeedableItems() with a lazy collection (e.g., Cursor from Doctrine) to avoid loading all items at once.

2. Batch Processing:

   • For large feeds, process items in batches:

     $feed->setBatchSize(50); // Process 50 items per batch
     

3. Disable Unused Features:

   • Remove unused config (e.g., cloud, textInput) to reduce parsing overhead.

Configuration Quirks

1. Default Values:

   • Missing config fields (e.g., language, encoding) use sensible defaults (en, UTF-8).
   • Override: Explicitly set in config or via setLanguage()/setEncoding().

2. PubDate Handling:

   • pubDate: 'now' uses the current timestamp. For dynamic dates:

     $feed->setPubDate(new \DateTime());
     

3. Image URLs:

   • Ensure image.url is absolute or prepend {% app.url %} in Twig:

     image:
         url: '{{ app.url }}/images/logo.png'