Blog Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ekyna/blog-bundle
   

   Add to config/app.php under providers:

   Ekyna\BlogBundle\BlogBundle::class,
   

   Publish the config:

   php artisan vendor:publish --provider="Ekyna\BlogBundle\BlogBundle" --tag=config
   

2. First Use Case Create a blog post via Trait:

   use Ekyna\BlogBundle\Entity\BlogPostTrait;
   
   class MyPost
   {
       use BlogPostTrait;
   }
   

   Configure config/blog.php with basic settings (title, default author, etc.).

3. Database Migration Run:

   php artisan migrate
   

   Check database/migrations/ for generated tables (blog_posts, blog_categories, etc.).

Implementation Patterns

Core Workflows

1. Post Management

   • CRUD via Entity:

     $post = new \Ekyna\BlogBundle\Entity\BlogPost();
     $post->setTitle('First Post');
     $post->setContent('Hello, world!');
     $post->setSlug('hello-world');
     $post->setPublishedAt(new \DateTime());
     $entityManager->persist($post);
     

   • Repository Pattern: Inject BlogPostRepository (auto-registered) for queries:

     $posts = $blogPostRepo->findBy(['published' => true]);
     

2. Category Integration

   • Attach categories to posts:

     $category = new \Ekyna\BlogBundle\Entity\BlogCategory();
     $category->setName('Tutorials');
     $post->addCategory($category);
     

3. Routing & Controllers

   • Use blog.post.show route (auto-generated) or extend:

     # config/routes.yaml
     blog_post:
         resource: '@EkynaBlogBundle/Resources/config/routing/posts.yaml'
         prefix: /blog
     

4. Twig Integration

   • Access posts in templates:

     {% for post in blog_posts %}
         <h2>{{ post.title }}</h2>
         <p>{{ post.content|raw }}</p>
     {% endfor %}
     

5. Event Listeners

   • Extend default behavior (e.g., auto-slug generation):

     // src/EventListener/BlogPostListener.php
     class BlogPostListener
     {
         public function onPrePersist(BlogPost $post)
         {
             if (empty($post->getSlug())) {
                 $post->setSlug(Str::slug($post->getTitle()));
             }
         }
     }
     

     Register in services.yaml:

     services:
         App\EventListener\BlogPostListener:
             tags:
                 - { name: kernel.event_listener, event: blog.post.pre_persist, method: onPrePersist }
     

Gotchas and Tips

Pitfalls

1. Missing Configuration

   • Issue: config/blog.php may lack required keys (e.g., default_author).
   • Fix: Run php artisan vendor:publish --tag=config and verify defaults.

2. Slug Conflicts

   • Issue: Auto-generated slugs may collide (e.g., duplicate titles).
   • Fix: Override slug logic in a listener or use UUIDs:

     $post->setSlug(Uuid::v4()->toString());
     

3. Entity Inheritance

   • Issue: Extending BlogPostTrait may cause conflicts with existing traits.
   • Fix: Use composition over inheritance; inject the trait’s logic via a service.

4. Route Overrides

   • Issue: Custom routes may conflict with bundle defaults.
   • Fix: Prefix routes explicitly:

     blog_custom:
         path: /custom-blog
         controller: App\Controller\CustomBlogController::index
     

5. Translation Support

   • Issue: Hardcoded strings in templates (e.g., "Published At").
   • Fix: Wrap dynamic text in translation functions:

     {{ 'blog.post.published_at'|trans }}
     

Debugging Tips

1. Check Events Use dd() in event listeners to inspect payloads:

   public function onPostPublish(BlogPostEvent $event)
   {
       dd($event->getPost()->getData());
   }
   

2. Doctrine Events Enable SQL logging for migrations:

   // config/packages/doctrine.yaml
   doctrine:
       dbal:
           logging: true
           profiling: true
   

3. Bundle Assets Clear cache after publishing assets:

   php artisan cache:clear
   php artisan config:clear
   

Extension Points

1. Custom Fields Extend BlogPost entity with additional fields:

   /**
    * @ORM\Column(type="string", nullable=true)
    */
   private $customField;
   

2. Validation Add constraints to BlogPost:

   use Symfony\Component\Validator\Constraints as Assert;
   
   /**
    * @Assert\Length(min=10)
    */
   private $content;
   

3. API Integration Use Symfony Serializer for JSON responses:

   use Symfony\Component\Serializer\Annotation\Groups;
   
   class BlogPost
   {
       /**
        * @Groups({"blog:read"})
        */
       public function getTitle(): string
       {
           return $this->title;
       }
   }
   

4. Testing Mock the repository in tests:

   $blogPostRepo = $this->createMock(BlogPostRepository::class);
   $blogPostRepo->method('findBy')->willReturn([$mockPost]);
   $container->set(BlogPostRepository::class, $blogPostRepo);