Comment Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require carbocation/comment-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Carbocation\CommentBundle\CarbocationCommentBundle::class => ['all' => true],
   ];
   

2. Database Migration Run migrations to create the required tables:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. Basic Configuration Update config/packages/carbocation_comment.yaml (if it doesn’t exist, create it):

   carbocation_comment:
       driver: doctrine_orm  # Default, but confirm
       model:
           comment: App\Entity\Comment  # Your custom Comment entity
           user: App\Entity\User     # Your User entity (must implement UserInterface)
   

4. First Use Case: Displaying Comments Use the CommentManager service to fetch and render comments:

   use Carbocation\CommentBundle\Manager\CommentManager;
   
   class CommentController extends AbstractController
   {
       public function show(CommentManager $commentManager, $commentableId, string $commentableType)
       {
           $comments = $commentManager->getComments($commentableId, $commentableType);
           return $this->render('comment/show.html.twig', ['comments' => $comments]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Commenting on Entities Use the CommentManager to attach comments to any entity (e.g., blog posts, products):

   $commentManager->addComment(
       $commentableEntity,  // Your entity (e.g., Post)
       $user,               // Authorized User
       'This is a great article!',  // Content
       ['rating' => 5]      // Optional metadata
   );
   

2. Threaded Replies Reply to a comment by specifying its parent:

   $parentComment = $commentManager->getComment($commentId);
   $reply = $commentManager->addComment(
       $parentComment->getCommentable(),
       $user,
       'Thanks for your feedback!',
       ['parent' => $parentComment]
   );
   

3. Rendering Comments Use Twig extensions for nested rendering:

   {% for comment in comments %}
       {{ render_comment(comment) }}
       {% if comment.children|length > 0 %}
           <div class="replies">
               {% for child in comment.children %}
                   {{ render_comment(child) }}
               {% endfor %}
           </div>
       {% endif %}
   {% endfor %}
   

4. API Integration Expose endpoints via Symfony’s serializer:

   # config/packages/serializer.yaml
   Carbocation\CommentBundle\Entity\Comment:
       attributes:
           id: ~
           content: ~
           createdAt: ~
           author: '@api_user_serializer'
   

Integration Tips

• Event Listeners: Subscribe to CommentEvents (e.g., CommentCreatedEvent) for notifications or analytics.
• Validation: Extend the Comment entity to add custom validation (e.g., length, spam checks).
• Permissions: Use Symfony’s voter system to restrict comment actions (e.g., CommentEditVoter).

Gotchas and Tips

Pitfalls

1. Entity Mapping

   • Ensure your Comment entity extends Carbocation\CommentBundle\Entity\Comment or implements CommentInterface.
   • If using a custom User entity, confirm it implements UserInterface with getId() and getUsername().

2. Doctrine ORM Quirks

   • The bundle assumes commentable is a polymorphic relationship. If your entity uses a different strategy (e.g., ManyToOne), override the Commentable trait.
   • Error: Unknown Entity → Verify your commentableType matches the entity’s class name (e.g., App\Entity\Post).

3. Threading Logic

   • Replies are stored via parent_id in the database. If this field is missing, threaded replies will break.
   • Debug: Run php bin/console doctrine:schema:validate to check table structure.

4. Caching

   • The bundle doesn’t cache comments by default. For high-traffic sites, implement a cache layer around CommentManager::getComments().

Debugging Tips

• Enable Debug Mode: Set CARBOCATION_COMMENT_DEBUG=true in .env to log SQL queries and events.
• Check Events: Use Symfony’s event dispatcher to log CommentEvents:

  $dispatcher->addListener(CommentEvents::COMMENT_CREATED, function ($event) {
      error_log('Comment created: ' . $event->getComment()->getContent());
  });
  

Extension Points

1. Custom Fields Add fields to the Comment entity and update the form type:

   // src/Form/CommentType.php
   $builder->add('tags', EntityType::class, ['class' => Tag::class]);
   

2. Moderation Implement a CommentState system (e.g., published, pending, spam) via entity lifecycle callbacks.

3. API Filters Use Symfony’s ApiPlatform or ApiFilter to paginate/sort comments:

   # config/packages/api_platform.yaml
   Carbocation\CommentBundle\Entity\Comment:
       collectionOperations:
           get:
               filters: ['comment.filter']