Messenger Filesystem Transport Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alphasoft-fr/messenger-filesystem-transport
   

2. Enable the Bundle (Symfony 5.4+): Add to config/bundles.php:

   return [
       // ...
       \AlphaSoft\Messenger\FilesystemTransport\AsMessengerFilesystemTransportBundle::class => ['all' => true],
   ];
   

3. Configure Transport (config/packages/messenger.yaml):

   framework:
       messenger:
           transports:
               filesystem:
                   dsn: 'filesystem://'
                   options:
                       directory: '%kernel.project_dir%/var/messages'
   

First Use Case

Dispatch a message asynchronously:

use Symfony\Component\Messenger\MessageBusInterface;

class MyService {
    public function __construct(private MessageBusInterface $bus) {}

    public function triggerAsyncTask() {
        $this->bus->dispatch(new MyMessage());
    }
}

Messages will auto-persist to var/messages/ as JSON files.

Implementation Patterns

Workflow Integration

1. Transport Routing: Use async bus for filesystem transport:

   # messenger.yaml
   framework:
       messenger:
           buses:
               async:
                   default_middleware: allow_no_handlers
                   transports: [filesystem]
   

2. Handling Failed Messages: Configure a failed transport:

   transports:
       filesystem: { ... }
       failed:
           dsn: 'filesystem://'
           options:
               directory: '%kernel.project_dir%/var/messages/failed'
   

3. Worker Setup: Run the worker via CLI:

   php bin/console messenger:consume filesystem -vv
   

Common Patterns

• Message Retry: Use RetryStrategy middleware for transient failures.
• Message Prioritization: Sort files by timestamp (e.g., YYYYMMDD_HHMMSS_UID.json).
• Batch Processing: Process files in chunks (e.g., glob('var/messages/*.json')).

Debugging Tips

• Inspect Messages: Directly read JSON files in var/messages/.
• Log Processing: Enable log: true to track processed.log/failed.log.

Gotchas and Tips

Pitfalls

1. Directory Permissions: Ensure var/messages/ is writable by PHP-FPM/CLI user.

   chmod -R 775 var/messages
   

2. Message Size Limits: Large messages (>1MB) may cause performance issues. Consider:

   • Compressing payloads (e.g., gzip_encode).
   • Offloading to S3 for large files.

3. Concurrent Workers: Without locking, multiple workers may process the same file. Use:

   options:
       directory: '%kernel.project_dir%/var/messages'
       lock_timeout: 300  # 5-minute lock (default: 0)
   

Debugging

• Stuck Messages: Check for locked files (e.g., .lock suffixes).
• Corrupted Files: Delete malformed JSON files manually.
• Worker Crashes: Use --time-limit=0 to avoid timeouts.

Extension Points

1. Custom Serialization: Override SerializerInterface to handle non-JSON payloads:

   // config/packages/messenger.yaml
   options:
       serializer: App\CustomSerializer
   

2. Event Listeners: Subscribe to MessageSentToTransportEvent to log/validate messages:

   use Symfony\Component\Messenger\Event\MessageSentToTransportEvent;
   
   public function onMessageSent(MessageSentToTransportEvent $event) {
       if ($event->getTransport() instanceof FilesystemTransport) {
           // Custom logic
       }
   }
   

3. Storage Backend: Extend FilesystemTransport to support cloud storage (e.g., S3) by overriding store()/recover().

Configuration Quirks

• Relative Paths: Use %kernel.project_dir% for portability.
• Log Rotation: Manually manage processed.log/failed.log sizes.
• Time Format: Message filenames use YYYYMMDD_HHMMSS_UID (adjust via Serializer if needed).

Performance Tips

• Disable Logging: Set log: false in production.
• Batch Processing: Process files in batches (e.g., 100 at a time) to reduce I/O.
• Symlink Trick: Use symlinks for "hot" directories to avoid filesystem scans.

```markdown
## Laravel-Specific Adaptations

### Laravel Integration
1. **Service Provider**:
   Register the bundle in `config/app.php`:
   ```php
   'providers' => [
       // ...
       \AlphaSoft\Messenger\FilesystemTransport\AsMessengerFilesystemTransportBundle::class,
   ],

2. Laravel Messenger: Configure in config/messenger.php:

   'transports' => [
       'filesystem' => [
           'dsn' => 'filesystem://',
           'options' => [
               'directory' => storage_path('app/messages'),
           ],
       ],
   ],
   

3. Dispatching Messages: Use Laravel’s Bus facade:

   use Illuminate\Bus\Dispatcher;
   
   $dispatcher = app(Dispatcher::class);
   $dispatcher->dispatch(new MyMessage());
   

Laravel-Specific Gotchas

1. Storage Path: Ensure storage_path('app/messages') exists and is writable.

2. Queue Workers: Run the worker via Artisan:

   php artisan messenger:consume filesystem
   

3. Event Handling: Use Laravel’s HandleFailedJobs middleware for failed messages.

Debugging in Laravel

• Tinker Inspection:

  $messages = Storage::files('app/messages');
  $content = Storage::get($messages[0]);
  

• Log Driver: Configure failed.log to use Laravel’s logging:

  'options' => [
      'log' => true,
      'log_channel' => 'single',
  ],
  

Laravel Extension Points

1. Custom Events: Listen to Illuminate\Queue\Events\JobProcessed for post-processing.

2. Queue Connection: Extend Laravel’s FilesystemQueue to integrate with this transport.

3. Horizon Compatibility: Use horizon:consume with the filesystem connection.