Chat Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   • Add the bundle via Composer:

     composer require cunningsoft/chat-bundle:0.5.*
     

   • Register the bundle in config/bundles.php (Symfony 4+):

     return [
         // ...
         Cunningsoft\ChatBundle\CunningsoftChatBundle::class => ['all' => true],
         Knp\Bundle\TimeBundle\KnpTimeBundle::class => ['all' => true],
     ];
     

   • For Symfony 3/2, update AppKernel.php as shown in the README.

2. Configure Doctrine:

   • Ensure your User entity implements AuthorInterface:

     use Cunningsoft\ChatBundle\Entity\AuthorInterface;
     
     class User implements AuthorInterface { ... }
     

   • Map the interface to your User entity in config/packages/doctrine.yaml (Symfony 4+):

     doctrine:
         orm:
             resolve_target_entities:
                 Cunningsoft\ChatBundle\Entity\AuthorInterface: App\Entity\User
     

   • Run migrations:

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

3. Basic Setup:

   • Configure the chat in config/packages/cunningsoft_chat.yaml (Symfony 4+):

     cunningsoft_chat:
         driver: doctrine # or 'mongodb' if using MongoDB
         model:
             message: App\Entity\Message
             room: App\Entity\Room
     

   • Create a Message and Room entity (see entity templates).

4. First Use Case:

   • Create a room via a controller or CLI:

     use Cunningsoft\ChatBundle\Entity\Room;
     use Cunningsoft\ChatBundle\Manager\RoomManager;
     
     $roomManager = $this->get('cunningsoft_chat.room_manager');
     $room = $roomManager->createRoom('General Chat');
     

   • Send a test message:

     use Cunningsoft\ChatBundle\Entity\Message;
     use Cunningsoft\ChatBundle\Manager\MessageManager;
     
     $messageManager = $this->get('cunningsoft_chat.message_manager');
     $message = $messageManager->createMessage($room, $user, 'Hello, world!');
     $messageManager->saveMessage($message);
     

Implementation Patterns

Core Workflows

1. Room Management

• Creating Rooms: Use RoomManager to create dynamic or static rooms. Example:

  $roomManager = $container->get('cunningsoft_chat.room_manager');
  $room = $roomManager->createRoom('Support', ['is_public' => true]);
  

• Room Hierarchy: Nest rooms for threaded conversations:

  $parentRoom = $roomManager->findRoomById(1);
  $childRoom = $roomManager->createRoom('Subtopic', ['parent' => $parentRoom]);
  

• Room Access Control: Attach metadata (e.g., is_private, moderated) via room options:

  # config/packages/cunningsoft_chat.yaml
  cunningsoft_chat:
      room_options:
          default:
              is_private: false
              max_users: 100
  

2. Message Handling

• Sending Messages: Use MessageManager for CRUD operations:

  $message = $messageManager->createMessage($room, $user, 'Content');
  $messageManager->saveMessage($message);
  

• Message Events: Listen for chat.message.sent or chat.message.edited events:

  // src/EventListener/ChatListener.php
  use Cunningsoft\ChatBundle\Event\MessageEvent;
  
  class ChatListener {
      public function onMessageSent(MessageEvent $event) {
          $message = $event->getMessage();
          // Log, notify, or process the message
      }
  }
  

  Register the listener in config/services.yaml:

  services:
      App\EventListener\ChatListener:
          tags:
              - { name: kernel.event_listener, event: chat.message.sent, method: onMessageSent }
  

3. User Integration

• Typing Indicators: Use TypingManager to show when users are typing:

  $typingManager = $container->get('cunningsoft_chat.typing_manager');
  $typingManager->userIsTyping($user, $room);
  

• User Presence: Track online/offline status via UserManager:

  $userManager = $container->get('cunningsoft_chat.user_manager');
  $userManager->setUserOnline($user);
  

4. API-Driven Chat

• RESTful Endpoints: Use Symfony’s serializers to expose chat data:

  // src/Controller/ChatController.php
  use Cunningsoft\ChatBundle\Entity\Room;
  use Symfony\Component\HttpFoundation\JsonResponse;
  
  class ChatController {
      public function getRoomMessages(Room $room) {
          $messages = $this->get('cunningsoft_chat.message_manager')->findMessages($room);
          return new JsonResponse($messages);
      }
  }
  

• WebSocket Integration: Pair with Ratchet or Mercure for real-time updates. Example with Mercure:

  # config/packages/mercure.yaml
  mercure:
      hubs:
          default:
              url: '%env(MERCURE_URL)%'
              public_id: 'https://%env(MERCURE_PUBLIC_URL)%/.well-known/mercure'
  

  Publish updates in a listener:

  use Symfony\Component\Mercure\Update;
  use Symfony\Component\Mercure\HubInterface;
  
  public function onMessageSent(MessageEvent $event, HubInterface $hub) {
      $update = new Update(
          'https://example.com/chat/' . $event->getMessage()->getRoom()->getId(),
          json_encode($event->getMessage())
      );
      $hub->publish($update);
  }
  

5. Search and Filtering

• QueryBuilder Integration: Filter messages by room, user, or timestamp:

  $qb = $messageManager->createMessageQueryBuilder('m')
      ->where('m.room = :room')
      ->andWhere('m.createdAt > :date')
      ->setParameter('room', $room)
      ->setParameter('date', new \DateTime('-1 day'));
  $messages = $qb->getQuery()->getResult();
  

• Full-Text Search: Use Doctrine extensions like Gedmo for search:

  // Add to Message entity
  use Gedmo\Mapping\Annotation as Gedmo;
  
  /**
   * @Gedmo\Indexed
   */
  private $content;
  

Integration Tips

1. Twig Integration

• Render chat UI in Twig:

  {% extends 'base.html.twig' %}
  
  {% block body %}
      <div id="chat-container">
          {% for message in messages %}
              <div class="message">
                  <strong>{{ message.author.username }}</strong>: {{ message.content }}
                  <small>{{ message.createdAt|date('H:i') }}</small>
              </div>
          {% endfor %}
      </div>
  {% endblock %}
  

• Pass messages from a controller:

  return $this->render('chat/index.html.twig', [
      'messages' => $messageManager->findMessages($room),
  ]);
  

2. Testing

• Functional Tests: Use ChatBundle's services in tests:

  public function testMessageCreation() {
      $room = $this->createMock(Room::class);
      $user = $this->createMock(User::class);
  
      $messageManager = $this->get('cunningsoft_chat.message_manager');
      $message = $messageManager->createMessage($room, $user, 'Test');
  
      $this->assertInstanceOf(Message::class, $message);
  }
  

• Event Testing: Verify listeners:

  $eventDispatcher = $this->get('event_dispatcher');
  $event = new MessageEvent($message);
  $eventDispatcher->dispatch($event, 'chat.message.sent');
  

3. Performance

• Pagination: Paginate messages in queries:

  $messages = $messageManager->findMessages($room, 10, 0); // 10 items, offset 0
  

• Caching: Cache room/message lists:

  $