Sakonnin Bundle Laravel Package

Getting Started

Minimal Setup

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

   composer require bisonlab/sakonnin-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       BisonLab\SakonninBundle\SakonninBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Publish the default config:

   php bin/console sakonnin:install
   

   Review config/packages/sakonnin.yaml for message handlers, callbacks, and routing.

3. First Use Case: Logging an Email Inject the SakonninManager and log a message:

   use BisonLab\SakonninBundle\Manager\SakonninManager;
   
   public function someAction(SakonninManager $sakonnin)
   {
       $sakonnin->logMessage([
           'type' => 'email',
           'subject' => 'Order Confirmation',
           'body' => 'Your order #12345 is confirmed.',
           'context' => [
               'system' => 'ecommerce',
               'object_name' => 'order',
               'external_id' => '12345',
           ],
       ]);
   }
   

Implementation Patterns

Core Workflows

1. Message Handling

   • Logging Messages: Use SakonninManager to log emails, SMS, or internal PMs with metadata (e.g., context for entity linking).

     $sakonnin->logMessage([
         'type' => 'sms',
         'content' => 'Alert: Low stock!',
         'context' => ['system' => 'inventory', 'external_id' => 'product_42'],
     ]);
     

   • File Attachments: Extend the system to handle files by defining a custom handler (see Extension Points).

2. Callbacks & Replies

   • Automated Actions: Define callbacks in config/packages/sakonnin.yaml to trigger actions on messages (e.g., forward emails with "ERROR" to SMS).

     sakonnin:
         callbacks:
             email:
                 - { action: 'forward_to_sms', condition: { subject: '/ERROR/i' } }
     

   • Reply Handling: Use SakonninManager::replyToMessage() to generate responses programmatically:

     $reply = $sakonnin->replyToMessage($messageId, 'Support team replied: ...');
     

3. Context-Based Routing

   • Link messages to entities (e.g., orders, users) via context:

     $context = ['system' => 'support', 'object_name' => 'ticket', 'external_id' => 'T-1001'];
     $sakonnin->logMessage(['type' => 'pm', 'body' => 'User complaint', 'context' => $context]);
     

   • Query messages by context:

     $messages = $sakonnin->getMessagesByContext(['system' => 'support']);
     

Integration Tips

• Symfony Events: Trigger Sakonnin actions via Symfony events (e.g., kernel.exception to log errors).

  // src/EventListener/ErrorLogger.php
  public function onKernelException(GetResponseForExceptionEvent $event)
  {
      $sakonnin->logMessage([
          'type' => 'error',
          'body' => $event->getThrowable()->getMessage(),
          'context' => ['system' => 'app', 'external_id' => uniqid()],
      ]);
  }
  

• API Endpoints: Expose message retrieval/reply via API:

  // src/Controller/MessageController.php
  public function getMessages(SakonninManager $sakonnin)
  {
      return $this->json($sakonnin->getMessages(['type' => 'email']));
  }
  

Gotchas and Tips

Pitfalls

1. Context Precision

   • Overly broad context queries (e.g., system: '*') may return unintended messages. Always specify object_name or external_id where possible.
   • Debug Tip: Use var_dump($sakonnin->getMessages(['context' => [...]])) to verify context matching.

2. Callback Order

   • Callbacks in sakonnin.yaml execute in declaration order. Reorder or use priorities (e.g., priority: 100) for critical actions.
   • Example:

     callbacks:
         email:
             - { action: 'archive', priority: 200 }  # Runs after 'forward_to_sms'
             - { action: 'forward_to_sms', condition: { subject: '/ERROR/i' } }
     

3. Message Type Validation

   • Unsupported type values (e.g., 'chat') will silently fail. Extend the bundle or validate inputs:

     $allowedTypes = ['email', 'sms', 'pm', 'error'];
     if (!in_array($message['type'], $allowedTypes)) {
         throw new \InvalidArgumentException("Unsupported message type");
     }
     

Debugging

• Log Level: Enable debug mode in sakonnin.yaml:

  debug: true  # Logs callback execution and message routing
  

• Doctrine Queries: Use Symfony’s profiler (/_profiler) to inspect database queries for context-based lookups.

Extension Points

1. Custom Handlers

   • Add new message types by implementing BisonLab\SakonninBundle\Handler\MessageHandlerInterface:

     // src/Handler/CustomHandler.php
     class CustomHandler implements MessageHandlerInterface
     {
         public function handle(array $message): void
         {
             // Logic for 'custom_type' messages
         }
     }
     

   • Register in services.yaml:

     services:
         App\Handler\CustomHandler:
             tags: [sakonnin.handler]
     

2. Dynamic Context

   • Override context resolution by extending BisonLab\SakonninBundle\Context\ContextResolver:

     // src/Context/CustomResolver.php
     class CustomResolver extends ContextResolver
     {
         protected function resolveContext(array $message): array
         {
             $context = parent::resolveContext($message);
             $context['custom_field'] = 'value'; // Add dynamic fields
             return $context;
         }
     }
     

   • Bind the service in services.yaml:

     BisonLab\SakonninBundle\Context\ContextResolver: '@App\Context\CustomResolver'
     

3. File Handling

   • The README mentions file support. Implement a file handler by extending MessageHandlerInterface and integrating with Symfony’s Filesystem or UploadedFile components.

Configuration Quirks

• Default Handlers: The bundle ships with basic handlers for email, sms, and pm. Disable unused ones in sakonnin.yaml:

  handlers:
      email: false  # Disable if not using email messages
  

• Reply Templates: Customize reply templates by overriding the twig configuration:

  twig:
      templates:
          reply: 'bundles/sakonnin/email/reply.html.twig'