Planedo Bundle Laravel Package

Getting Started

Minimal Setup

1. Quick Start via Standalone App Run composer project-create crell/planedo to generate a pre-configured Symfony 6 project with PlanedoBundle integrated. This is the fastest way to test functionality.

2. Manual Integration For existing Symfony 6 apps:

   composer require crell/planedo-bundle
   

   Then add to config/bundles.php:

   return [
       // ...
       Crell\PlanedoBundle\PlanedoBundle::class => ['all' => true],
   ];
   

3. First Use Case Configure feeds via YAML (see config/packages/planedo.yaml in the standalone app). Example:

   planedo:
       feeds:
           - { url: 'https://example.com/feed.xml', title: 'Example Blog' }
   

   Access aggregated content at /planet (default route).

Implementation Patterns

Core Workflows

1. Feed Management

   • Dynamic Feeds: Use planedo.feed_manager service to programmatically add/remove feeds at runtime.

     $feedManager = $container->get('planedo.feed_manager');
     $feedManager->addFeed('https://new-blog.com/feed.rss', 'New Blog');
     

   • Configuration Overrides: Extend planedo.yaml with custom logic (e.g., filtering feeds by category):

     planedo:
         filters:
             - { key: 'category', value: 'tech' }
     

2. Content Processing

   • Custom Item Handlers: Override default feed item processing via event listeners. Subscribe to planedo.item_processed:

     use Crell\PlanedoBundle\Event\ItemProcessedEvent;
     
     $eventDispatcher->addListener(ItemProcessedEvent::class, function (ItemProcessedEvent $event) {
         if ($event->getItem()->getCategory() === 'ignored') {
             $event->stopPropagation();
         }
     });
     

   • Template Customization: Extend the Twig template (templates/planedo/index.html.twig) or override the controller (src/Controller/PlanetController.php).

3. Scheduling

   • Use Symfony’s CronBundle or Symfony\Component\Console to trigger feed updates:

     php bin/console planedo:update
     

   • Schedule via crontab (e.g., hourly updates):

     0 * * * * cd /path/to/project && php bin/console planedo:update
     

4. API Access

   • Expose aggregated content via API by creating a custom controller:

     use Crell\PlanedoBundle\Service\FeedAggregator;
     
     class ApiController extends AbstractController {
         public function __invoke(FeedAggregator $aggregator) {
             return $this->json($aggregator->getLatestItems());
         }
     }
     

Gotchas and Tips

Pitfalls

1. PSR-20 Dependency

   • The bundle requires a pre-release PSR-20 feed parser (not on Packagist). Ensure your composer.json includes the Git repo:

     "repositories": [
         { "type": "git", "url": "https://github.com/php-fig/feed.git" }
     ],
     "require": {
         "php-fig/feed": "dev-main"
     }
     

   • Workaround: Fork the repo and host it privately if stability is critical.

2. Feed Parsing Quirks

   • Malformed Feeds: The parser may fail silently on invalid XML/RSS. Add error handling:

     try {
         $items = $feedManager->fetchFeed($url);
     } catch (\Exception $e) {
         $this->addFlash('error', 'Failed to fetch feed: ' . $e->getMessage());
     }
     

   • Character Encoding: Ensure feeds use UTF-8. Normalize with:

     mb_convert_encoding($content, 'UTF-8', 'auto');
     

3. Caching Issues

   • Stale Content: By default, feeds are cached for 1 hour. Adjust in planedo.yaml:

     planedo:
         cache_lifetime: 3600  # 1 hour (in seconds)
     

   • Cache Invalidation: Clear manually with:

     php bin/console cache:clear
     

4. Route Conflicts

   • The default /planet route may clash with existing routes. Override in config/routes.yaml:

     planedo:
         resource: "@PlanedoBundle/Resources/config/routes.yaml"
         prefix: "/blog-aggregator"
     

Debugging Tips

1. Log Feed Processing Enable debug mode and check var/log/dev.log for parsing errors or skipped items.

2. Inspect Raw Feeds Use the planedo:debug command to inspect fetched feeds:

   php bin/console planedo:debug
   

3. Event Debugging Dump event data in listeners:

   $event->getItem()->getRawData(); // Inspect original feed item
   

Extension Points

1. Custom Feed Types Extend the FeedInterface to support non-RSS/Atom feeds (e.g., JSON feeds). Implement a custom FeedParser service.

2. Database Backend The bundle uses in-memory storage by default. Replace with Doctrine by:

   • Creating a FeedItem entity.
   • Overriding FeedAggregator to persist items.

3. Authentication for Private Feeds Use Symfony’s HttpClient with auth headers:

   $client = $this->container->get('http_client');
   $response = $client->request('GET', $feedUrl, [
       'auth_basic' => ['username', 'password']
   ]);
   

4. Testing Mock the FeedManager in tests:

   $feedManager = $this->createMock(FeedManager::class);
   $feedManager->method('getItems')->willReturn([$mockItem]);
   $this->container->set('planedo.feed_manager', $feedManager);