Feed Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

   composer require anh/feed-bundle
   

   Register the bundle in config/app.php under providers:

   Anh\FeedBundle\AnhFeedBundle::class,
   

2. Basic Configuration Publish the default config (if needed) and update config/anh_feed.php:

   php artisan vendor:publish --provider="Anh\FeedBundle\AnhFeedBundle" --tag="config"
   

3. First Use Case: Generate a Simple RSS Feed Create a controller method to generate an RSS feed:

   use Anh\FeedBundle\Builder\FeedBuilder;
   use Anh\FeedBundle\Builder\FeedBuilderInterface;
   
   public function generateFeed(FeedBuilderInterface $feedBuilder)
   {
       $feed = $feedBuilder
           ->setTitle('My Blog')
           ->setLink('https://example.com')
           ->setDescription('Latest blog posts');
   
       // Add items
       $feed->addItem()
           ->setTitle('First Post')
           ->setLink('https://example.com/post/1')
           ->setDescription('Content of the first post');
   
       return $feed->build();
   }
   

   Route it to /feed.rss:

   Route::get('/feed.rss', [FeedController::class, 'generateFeed']);
   

Implementation Patterns

Common Workflows

1. Dynamic Feed Generation Fetch data from a repository or service and loop to build feed items:

   public function generateDynamicFeed(FeedBuilderInterface $feedBuilder, PostRepository $posts)
   {
       $feed = $feedBuilder
           ->setTitle('Dynamic Blog')
           ->setLink(url('/'));
   
       $posts->latest()->take(10)->each(function ($post) use ($feed) {
           $feed->addItem()
               ->setTitle($post->title)
               ->setLink($post->url)
               ->setDescription($post->excerpt)
               ->setDate($post->published_at->format('c'));
       });
   
       return $feed->build();
   }
   

2. Reusable Feed Builders Create a service to encapsulate feed logic:

   class BlogFeedService
   {
       protected $feedBuilder;
   
       public function __construct(FeedBuilderInterface $feedBuilder)
       {
           $this->feedBuilder = $feedBuilder;
       }
   
       public function buildFeed(array $posts)
       {
           $feed = $this->feedBuilder->setTitle('Blog Feed');
   
           foreach ($posts as $post) {
               $feed->addItem()->setTitle($post['title']);
           }
   
           return $feed->build();
       }
   }
   

3. Atom vs. RSS Switching Dynamically switch feed types based on route parameters:

   public function generateFeed(FeedBuilderInterface $feedBuilder, Request $request)
   {
       $type = $request->query('type', 'rss');
       $feed = $feedBuilder->setType($type);
   
       // Rest of the feed logic...
   }
   

Integration Tips

• Caching Feeds Cache the generated feed for performance:

  return Cache::remember('blog_feed', now()->addHours(1), function () use ($feedBuilder) {
      return $feedBuilder->buildFeed($posts)->build();
  });
  

• Validation Use the built-in validator to ensure feed compliance:

  $feed = $feedBuilder->buildFeed($posts);
  if (!$feed->validate()) {
      throw new \RuntimeException('Feed validation failed: ' . $feed->getErrors());
  }
  

• Laravel Mixins Extend the builder with custom methods in a service provider:

  $this->app->extend(FeedBuilderInterface::class, function ($builder) {
      $builder->addMethod('addAuthor', function ($name) {
          $this->addItem()->setAuthor($name);
          return $this;
      });
      return $builder;
  });
  

Gotchas and Tips

Pitfalls

1. Date Formatting Ensure dates are in ISO 8601 format (c or rss format) for compatibility:

   $item->setDate($post->published_at->toAtomString());
   

2. Character Encoding Always set UTF-8 encoding to avoid issues with special characters:

   $feed->setEncoding('UTF-8');
   

3. Namespace Conflicts The bundle uses Anh\FeedBundle namespace. Avoid naming conflicts with custom classes/services.

4. Deprecated Methods Check for deprecated methods in anh/feed-builder (e.g., setLastBuildDate may be replaced by setDate).

Debugging

• Validation Errors Enable debug mode in the config to get detailed validation feedback:

  'validation' => [
      'debug' => true,
  ],
  

• Output Inspection Use dd($feed->build()) to inspect the raw XML output before sending it to the client.

Extension Points

1. Custom Feed Types Extend the builder to support additional feed formats (e.g., JSON Feed):

   $feedBuilder->addType('json', function () {
       return new JsonFeedBuilder();
   });
   

2. Item Factories Create a factory to standardize item creation:

   class PostItemFactory
   {
       public static function createFromPost(Post $post, FeedItemBuilder $item)
       {
           return $item
               ->setTitle($post->title)
               ->setLink($post->url)
               ->setDate($post->published_at)
               ->setGuid($post->id);
       }
   }
   

3. Event Listeners Attach listeners to feed events (e.g., feed.item.added):

   $feedBuilder->addListener('feed.item.added', function ($item) {
       $item->setCustomElement('custom', 'value');
   });
   

Config Quirks

• Default Values The bundle uses sensible defaults (e.g., RSS_2.0 as default type). Override in config/anh_feed.php if needed:

  'default_type' => 'atom_1.0',
  'default_encoding' => 'UTF-8',
  

• Service Binding Ensure the FeedBuilderInterface is bound correctly in Laravel’s container. If issues arise, manually bind it:

  $this->app->bind(FeedBuilderInterface::class, function ($app) {
      return new FeedBuilder();
  });