Inboxbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require xlabs/inboxbundle
   

   Add to config/bundles.php:

   return [
       // ...
       XLabs\InboxBundle\XLabsInboxBundle::class => ['all' => true],
   ];
   

2. Database Migration Run the bundle’s migrations:

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

   The bundle provides default tables (inbox_messages, inbox_folders).

3. First Use Case Inject the InboxManager service in a controller:

   use XLabs\InboxBundle\Manager\InboxManager;
   
   class UserController extends Controller {
       public function __construct(private InboxManager $inboxManager) {}
   
       public function showInbox() {
           $messages = $this->inboxManager->getMessagesForUser($this->getUser());
           return $this->render('inbox/index.html.twig', ['messages' => $messages]);
       }
   }
   

4. Twig Integration Enable Twig extensions in config/packages/twig.yaml:

   twig:
       extensions:
           - XLabs\InboxBundle\Twig\InboxExtension
   

   Use in templates:

   {% for message in inbox_messages %}
       {{ message.subject }} ({{ message.createdAt|date('Y-m-d') }})
   {% endfor %}
   

Implementation Patterns

Core Workflows

1. Message Management

   • Create/Read/Update/Delete:

     $message = $this->inboxManager->createMessage(
         $userId,
         'New Task',
         'Details here...',
         ['type' => 'task']
     );
     $this->inboxManager->markAsRead($message->getId());
     $this->inboxManager->deleteMessage($message->getId());
     

   • Bulk Actions:

     $this->inboxManager->markMessagesAsRead([1, 2, 3]);
     

2. Folder System

   • Create folders dynamically:

     $folder = $this->inboxManager->createFolder($userId, 'Archived');
     $this->inboxManager->moveMessageToFolder($messageId, $folder->getId());
     

   • Default folders (inbox, sent, archive) are auto-created on user registration.

3. Event-Driven Extensions Subscribe to events (e.g., MessageCreatedEvent):

   // src/EventListener/MessageListener.php
   class MessageListener implements MessageCreatedEventSubscriber {
       public static function getSubscribedEvents() {
           return [MessageCreatedEvent::NAME => 'onMessageCreated'];
       }
   
       public function onMessageCreated(MessageCreatedEvent $event) {
           // Log, notify, or transform the message
       }
   }
   

4. API Integration Use the InboxApi service for RESTful endpoints:

   $messages = $this->inboxApi->getMessages($userId, ['limit' => 10]);
   return $this->json($messages);
   

Integration Tips

• Symfony Forms: Use the InboxType form for message creation:

  $form = $this->createForm(InboxType::class, $message);
  

• Security: Restrict access via voters:

  // src/Security/Voter/InboxVoter.php
  class InboxVoter extends AbstractVoter {
      protected function supports(string $attribute, $subject) {
          return $attribute === 'VIEW_INBOX' && $subject instanceof User;
      }
  }
  

• Search: Leverage the InboxSearch service for full-text queries:

  $results = $this->inboxSearch->search('urgent', $userId);
  

Gotchas and Tips

Common Pitfalls

1. User Context

   • Issue: Forgetting to pass the current user to methods like getMessagesForUser().
   • Fix: Use dependency injection or middleware to auto-resolve the user:

     // src/EventListener/UserContextListener.php
     class UserContextListener {
         public function onKernelRequest(GetResponseEvent $event) {
             $this->inboxManager->setCurrentUser($event->getRequest()->getUser());
         }
     }
     

2. Message Ownership

   • Issue: Attempting to modify messages not owned by the user (e.g., via API).
   • Fix: Implement a MessageOwnerChecker or use Symfony’s access control:

     $this->denyAccessUnlessGranted('EDIT_MESSAGE', $message);
     

3. Performance with Large Inboxes

   • Issue: Slow queries when fetching messages without pagination.
   • Fix: Always paginate results:

     $messages = $this->inboxManager->getMessagesForUser($user, ['page' => 1, 'limit' => 20]);
     

4. Event Ordering

   • Issue: Events firing out of expected order (e.g., MessageCreatedEvent before validation).
   • Fix: Use event priorities:

     public static function getSubscribedEvents() {
         return [MessageCreatedEvent::NAME => ['onMessageCreated', 100]]; // Higher priority
     }
     

Configuration Quirks

1. Default Folder IDs

   • The bundle auto-generates folders with hardcoded IDs (1 = inbox, 2 = sent, 3 = archive). Override in config/packages/xlabs_inbox.yaml:

     xlabs_inbox:
         default_folders:
             inbox: 100
             sent: 101
             archive: 102
     

2. Message TTL

   • Messages are soft-deleted after 30 days by default. Adjust via:

     xlabs_inbox:
         message_ttl: 90 # days
     

3. Twig Debugging

   • If Twig extensions aren’t loading, clear the cache:

     php bin/console cache:clear
     

Extension Points

1. Custom Message Types Extend the Message entity:

   // src/Entity/CustomMessage.php
   class CustomMessage extends AbstractMessage {
       #[ORM\Column]
       private string $customField;
   }
   

   Register in config/packages/xlabs_inbox.yaml:

   xlabs_inbox:
       message_classes:
           custom: App\Entity\CustomMessage
   

2. Message Attachments Use the AttachmentManager:

   $attachment = $this->attachmentManager->addAttachment($message, '/path/to/file.pdf');
   

3. Webhook Notifications Subscribe to MessageStatusChangedEvent:

   public function onMessageStatusChanged(MessageStatusChangedEvent $event) {
       if ($event->getNewStatus() === 'read') {
           $this->httpClient->request('POST', 'https://api.example.com/webhook', [
               'json' => ['message_id' => $event->getMessage()->getId()]
           ]);
       }
   }
   

4. Testing Use the InboxTestCase base class:

   class MyInboxTest extends InboxTestCase {
       public function testMessageCreation() {
           $message = $this->createMessage('Test', 'Content');
           $this->assertEquals('Test', $message->getSubject());
       }
   }