Message Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cunningsoft/message-bundle:0.1.*
   

   Register the bundle in AppKernel.php:

   new Cunningsoft\MessageBundle\CunningsoftMessageBundle(),
   

2. Configure User Entity: Ensure your User entity implements Cunningsoft\MessageBundle\Entity\UserInterface with getId() and getUsername() methods.

3. Doctrine Mapping: Add the bundle’s configuration to config.yml:

   cunningsoft_message:
       user_entity: Acme\ProjectBundle\Entity\User
   

4. First Use Case: Use the MessageManager service to send a message:

   $messageManager = $this->get('cunningsoft_message.manager');
   $messageManager->sendMessage($senderUser, $recipientUser, 'Hello!');
   

Implementation Patterns

Core Workflows

1. Sending Messages:

   // In a controller/service
   $messageManager = $this->container->get('cunningsoft_message.manager');
   $message = $messageManager->createMessage($sender, $recipient, 'Test message');
   $messageManager->persist($message);
   

2. Listing Messages:

   // Fetch messages for a user (e.g., in a repository)
   $messages = $messageManager->getMessagesForUser($user, 10); // Limit 10
   

3. Reading/Marking as Read:

   $messageManager->markAsRead($message);
   

4. Event-Driven Extensions: Listen to cunningsoft_message.send or cunningsoft_message.read events via Symfony’s event dispatcher.

Integration Tips

1. Doctrine Integration: The bundle assumes Doctrine ORM. Ensure your User entity is mapped and the Message entity is auto-generated or manually defined.

2. Custom Message Fields: Extend the Message entity (if needed) by overriding the bundle’s default entity:

   cunningsoft_message:
       message_entity: Acme\ProjectBundle\Entity\CustomMessage
   

3. Twig Integration: Pass messages to templates:

   {% for message in messages %}
       <div class="message {{ message.isRead ? 'read' : 'unread' }}">
           {{ message.content }}
       </div>
   {% endfor %}
   

4. API Endpoints: Create RESTful endpoints for sending/receiving messages:

   // Example: POST /api/messages
   $sender = $this->getUser();
   $recipient = $this->getDoctrine()->getRepository('AcmeProjectBundle:User')->find($id);
   $messageManager->sendMessage($sender, $recipient, $request->request->get('content'));
   

Gotchas and Tips

Pitfalls

1. User Interface Contract: Forgetting to implement getId() or getUsername() in your User entity will cause runtime errors. Validate early:

   if (!$user instanceof MessageUserInterface) {
       throw new \InvalidArgumentException('User must implement UserInterface');
   }
   

2. Missing Doctrine Configuration: The bundle relies on Doctrine’s ORM. Ensure doctrine is properly configured in config.yml and your User entity is mapped.

3. Message Persistence: Always call $messageManager->persist($message) after creating a message; the bundle does not auto-flush.

4. Event Dispatching: Events like cunningsoft_message.send may not fire if the bundle isn’t properly registered or the event listener is misconfigured.

Debugging

1. Check Entity Mapping: Verify the Message entity is generated or manually defined. Run:

   php app/console doctrine:schema:update --dump-sql
   

2. Service Availability: Ensure the cunningsoft_message.manager service is available:

   php app/console debug:container cunningsoft_message.manager
   

3. Event Listeners: Debug event listeners with:

   php app/console debug:event-dispatcher
   

Extension Points

1. Custom Message Entity: Override the default Message entity by extending Cunningsoft\MessageBundle\Entity\Message and updating the config:

   cunningsoft_message:
       message_entity: Acme\ProjectBundle\Entity\CustomMessage
   

2. Add Fields to Messages: Extend the Message entity and update the bundle’s templates/services accordingly.

3. Custom Validation: Add validation logic in a MessageListener or override the MessageManager service:

   services:
       acme.message_manager:
           class: Acme\ProjectBundle\Service\CustomMessageManager
           decorates: cunningsoft_message.manager
   

4. Translation Support: Extend the bundle’s translation keys by overriding its templates or using Symfony’s translation system.

Configuration Quirks

• User Entity Mapping: The user_entity key in config.yml must match the fully qualified class name of your User entity.

• Default Message Entity: The bundle auto-generates a Message entity if none is specified. Avoid manually creating this entity to prevent conflicts.

• Event Priorities: Event listeners may override each other. Use priorities (e.g., 255 for high priority) in your service definitions.