Blog Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cedricziel/blog-bundle
   

   Add to config/bundles.php:

   Cedricziel\BlogBundle\CedriczielBlogBundle::class => ['all' => true],
   

2. Database Migration Run migrations (if included) or manually create tables based on the bundle’s Schema (check Resources/config/doctrine/ for YAML/XML definitions).

3. First Use Case

   • Create a Post entity via the bundle’s CRUD interface (if provided) or manually:

     use Cedricziel\BlogBundle\Entity\Post;
     
     $post = new Post();
     $post->setTitle('Hello World');
     $post->setContent('First blog post!');
     $em->persist($post);
     $em->flush();
     

   • Display posts in a controller:

     use Cedricziel\BlogBundle\Entity\Post;
     use Doctrine\ORM\EntityManagerInterface;
     
     public function index(EntityManagerInterface $em)
     {
         $posts = $em->getRepository(Post::class)->findAll();
         return $this->render('blog/index.html.twig', ['posts' => $posts]);
     }
     

4. Routing Check Resources/config/routing.yml for default routes (e.g., /blog/{slug}). Override or extend as needed.

Implementation Patterns

Core Workflows

1. Entity Management

   • Posts: Extend Post entity (e.g., add custom fields) by overriding the bundle’s Post class.

     namespace App\Entity;
     
     use Cedricziel\BlogBundle\Entity\Post as BasePost;
     
     class Post extends BasePost
     {
         // Custom fields/methods
     }
     

   • Categories/Tags: If supported, use the bundle’s Category/Tag entities similarly.

2. Repository Patterns

   • Customize queries in a service:

     public function getFeaturedPosts(EntityManagerInterface $em, int $limit = 3)
     {
         return $em->getRepository(Post::class)
             ->createQueryBuilder('p')
             ->where('p.published = :published')
             ->setParameter('published', true)
             ->orderBy('p.createdAt', 'DESC')
             ->setMaxResults($limit)
             ->getQuery()
             ->getResult();
     }
     

3. Form Handling

   • Use the bundle’s PostType (if provided) or create a custom form:

     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
     
     class PostType extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder
                 ->add('title')
                 ->add('content', TextareaType::class)
                 ->add('published', CheckboxType::class);
         }
     }
     

4. Twig Integration

   • Pass posts to templates:

     {% for post in posts %}
         <h2>{{ post.title }}</h2>
         <p>{{ post.content|truncate(200) }}</p>
         <a href="{{ path('blog_show', {'slug': post.slug}) }}">Read more</a>
     {% endfor %}
     

   • Extend with custom Twig functions/filters if needed.

5. Event Listeners

   • Hook into lifecycle events (e.g., prePersist for slug generation):

     // src/EventListener/PostListener.php
     public function prePersist(Post $post)
     {
         if (empty($post->getSlug())) {
             $post->setSlug(StringUtil::slugify($post->getTitle()));
         }
     }
     

     Register in services.yaml:

     services:
         App\EventListener\PostListener:
             tags:
                 - { name: doctrine.event_listener, event: prePersist }
     

Integration Tips

• Symfony Flex: If the bundle lacks Flex recipes, manually configure autoloading in composer.json:

  "autoload": {
      "psr-4": {
          "Cedricziel\\BlogBundle\\": "vendor/cedricziel/blog-bundle/src/"
      }
  }
  

• Asset Management: Override bundle assets (CSS/JS) by copying files from vendor/cedricziel/blog-bundle/Resources/public/ to public/bundles/blog/.
• Testing: Mock the Post repository in PHPUnit:

  $this->entityManager->getRepository(Post::class)
      ->method('findAll')
      ->willReturn([$mockPost]);
  

Gotchas and Tips

Pitfalls

1. Lack of Documentation

   • The bundle’s simplicity may hide missing features (e.g., no built-in admin UI, minimal validation). Assume nothing is pre-configured beyond basic CRUD.
   • Workaround: Use EasyAdmin or SonataAdmin for admin interfaces.

2. No Default Fixtures

   • No pre-loaded test data. Manually seed the database or use DoctrineFixturesBundle.

3. Routing Conflicts

   • Default routes may clash with existing routes. Override in config/routes.yaml:

     blog:
         resource: "@CedriczielBlogBundle/Resources/config/routing.yml"
         prefix: "/my-custom-prefix"
     

4. Entity Inheritance

   • Extending Post may break bundle updates. Prefer composition (e.g., add a PostExtension trait) or use Doctrine Extensions.

5. Translation Support

   • No built-in translation. Use Symfony’s translator or add translatable behavior:

     # config/packages/gedmo_translatable.yaml
     gedmo_translatable:
         default_locale: en
         ignore_fields: [slug, createdAt]
     

Debugging

• Entity Not Found: Ensure the Post entity is mapped correctly. Check:
  • vendor/cedricziel/blog-bundle/src/Entity/Post.php for annotations.
  • config/packages/doctrine.yaml for orm mappings.
• Route Errors: Clear cache (php bin/console cache:clear) and verify routing.yml paths.
• Form Validation: Add constraints to the Post entity:

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

Extension Points

1. Custom Fields Add fields to Post and update forms/repositories:

   // Add to Post entity
   private $views = 0;
   
   // Add to PostType
   ->add('views', HiddenType::class)
   

   Increment views via a listener:

   public function postView(Post $post)
   {
       $post->setViews($post->getViews() + 1);
       $em->flush();
   }
   

2. API Endpoints Use ApiPlatform or manually create controllers:

   #[Route('/api/posts', name: 'api_posts', methods: ['GET'])]
   public function getPosts(EntityManagerInterface $em): JsonResponse
   {
       $posts = $em->getRepository(Post::class)->findAll();
       return new JsonResponse($posts);
   }
   

3. Search Functionality Integrate with Elasticsearch or Algolia:

   // Example: Sync posts to Algolia
   $client->saveObjects([
       [
           'objectID' => $post->getId(),
           'title' => $post->getTitle(),
           // ...
       ]
   ]);
   

4. Media Handling Use VichUploaderBundle for file uploads:

   // Add to Post entity
   use Vich\UploaderBundle\Mapping\Annotation as Vich;
   
   #[Vich\Uploadable]
   private ?File $imageFile;
   

Configuration Quirks

• Doctrine Migrations: If the bundle includes migrations, run:

  php bin/console doctrine:migrations:execute --up
  

  Otherwise, manually create tables based on the bundle’s Schema files.
• Environment Variables: No built-in support. Use Symfony’s %env% or env() in services:

  # config/services.yaml
  parameters:
      blog.posts_per_page: '%env(int:POSTS_PER_PAGE, 10)%'