Blog Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cafe-culture/blog-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       CafeCulture\BlogBundle\CafeCultureBlogBundle::class => ['all' => true],
   ];
   

2. Database Migration: Run migrations (fixtures included):

   php bin/console doctrine:migrations:migrate
   php bin/console cafe:fixtures:load
   

3. First Use Case:

   • Create a coffee-themed article via CLI:

     php bin/console cafe:article:create --title="Ethiopian Yirgacheffe" --origin="Ethiopia" --roast="Light" --tags="Floral,Fruity"
     

   • Access the article at /article/1 (auto-generated slug).

Implementation Patterns

Core Workflows

1. Content Creation:

   • Use CafeArticle entity with specialized fields:

     $article = new CafeArticle();
     $article->setTitle('Brazilian Santos')
              ->setOrigin('Brazil')
              ->setAromaProfile(['Chocolate', 'Nutty'])
              ->setReadingTime(5); // minutes
     

   • Leveraging Twig extensions for display:

     {{ article|reading_time('min') }} min read
     {{ article|stars(4) }}  <!-- Renders ★★★★☆ -->
     

2. API Integration:

   • Fetch recent articles via REST:

     $recent = $this->get('cafe.api.article_recent')->getRecent(5);
     

   • Rate an article (AJAX-friendly):

     fetch(`/api/cafe/rate/123`, { method: 'POST', body: JSON.stringify({ rating: 5 }) });
     

3. Search & Autocomplete:

   • Use the CafeSearchHandler service:

     $results = $this->get('cafe.search')->search('Colombian', ['origin']);
     

   • Frontend autocomplete with Stimulus:

     // assets/controllers/autocomplete_controller.js
     connect() {
       this.element.addEventListener('input', (e) => {
         fetch(`/api/cafe/search?q=${e.target.value}`)
           .then(r => r.json())
           .then(this.displayResults.bind(this));
       });
     }
     

4. Moderation System:

   • Flag comments for review:

     $comment->setFlagged(true);
     $comment->setModerationReason('Spam');
     $em->persist($comment);
     

   • Dashboard overview via /admin/cafe/comments.

Integration Tips

• Custom Fields: Extend CafeArticle via inheritance:

  class CustomArticle extends CafeArticle {
      #[ORM\Column]
      private ?string $brewingMethod = null;
  
      public function getBrewingMethod(): ?string { return $this->brewingMethod; }
  }
  

• Event Listeners: Subscribe to cafe.article.published:

  #[AsEventListener(event: 'cafe.article.published', method: 'onArticlePublished')]
  public function onArticlePublished(CafeArticleEvent $event) {
      // Send Slack notification, etc.
  }
  

• Theming: Override templates in templates/cafe/ (e.g., article/show.html.twig).

Gotchas and Tips

Pitfalls

1. IP-Based Rating Lockout:

   • The CafeRating entity blocks duplicate ratings per IP. Test locally with:

     php bin/console cafe:rating:reset
     

   • For development, mock IPs in config/packages/cafe.yaml:

     cafe:
         rating:
             test_ips: ['127.0.0.1', '::1']
     

2. Full-Text Search Quirks:

   • Requires PostgreSQL/MySQL with fts or match support. For SQLite, disable in config/packages/doctrine.yaml:

     dbal:
         types:
             cafe_searchable: ~  # Disables searchable fields
     

3. Fixture Overwrites:

   • Fixtures load on cafe:fixtures:load. To reset:

     php bin/console doctrine:database:drop --force
     php bin/console doctrine:database:create
     php bin/console cafe:fixtures:load --reset
     

4. API Caching:

   • REST endpoints cache responses for 1 hour by default. Override in config/packages/cafe.yaml:

     cafe:
         api:
             cache_ttl: 3600  # 1 hour (default)
     

Debugging

• Twig Extensions:
  • Debug available filters/functions:

    {{ dump(_context.get('cafe.twig').getFunctions()) }}
    

• Event Dispatching:
  • Check fired events with:

    php bin/console debug:event-dispatcher
    

  • Filter for cafe.* events.

Extension Points

1. Custom Entities:

   • Add fields to CafeArticle via CafeArticleExtension trait:

     use CafeCulture\BlogBundle\Entity\Extension\CafeArticleExtension;
     
     class ExtendedArticle extends CafeArticle {
         use CafeArticleExtension;
     
         #[ORM\Column(nullable: true)]
         private ?string $cuppingNotes;
     }
     

2. Moderation Workflow:

   • Extend CafeCommentModerationHandler to add custom approval logic:

     public function shouldApprove(CafeComment $comment): bool {
         return parent::shouldApprove($comment) && $comment->getAuthor()->isTrusted();
     }
     

3. API Endpoints:

   • Add routes via cafe.api.routes YAML config:

     # config/routes/cafe.yaml
     cafe_api_custom:
         path: /api/cafe/custom
         controller: CafeCulture\BlogBundle\Controller\Api\CustomController::index
     

4. Asset Overrides:

   • Replace bundle assets by copying vendor/cafe-culture/blog-bundle/assets/ to public/build/cafe/ and updating config/packages/cafe.yaml:

     cafe:
         assets:
             base_path: /build/cafe
     

Pro Tips

• Bulk Actions:
  • Use the CafeArticleManager to update multiple articles:

    $manager->setRoastLevel('Medium', ['1', '2', '3']); // IDs
    

• SEO Optimization:
  • Auto-generate OpenGraph tags via Twig:

    {% include 'CafeCultureBlogBundle::partials/opengraph.html.twig' %}
    

• Localization:
  • Translate coffee terms (e.g., origin, roast_level) via trans:

    {{ 'cafe.origin.ethiopia'|trans }}
    

  • Add translations in translations/cafe.en.yaml:

    cafe:
        origin:
            ethiopia: "Ethiopia (Yirgacheffe, Sidamo)"