Inboxbundle Laravel Package

Getting Started

First Steps

1. Installation Add the bundle via Composer:

   composer require atm/inboxbundle
   

   Register the bundle in config/app.php under providers:

   Atm\InboxBundle\AtmInboxBundle::class,
   

   Publish the bundle’s assets and configuration:

   php artisan atm:inbox:install
   

2. Basic Setup

   • Configure the bundle via config/atm_inbox.php (e.g., default inbox types, notification channels).
   • Define your first inbox type (e.g., user_notifications) in the database via migrations or the admin interface (if provided).

3. First Use Case: Displaying an Inbox Inject the Atm\InboxBundle\Service\InboxService into a controller or service:

   use Atm\InboxBundle\Service\InboxService;
   
   public function showInbox(InboxService $inboxService)
   {
       $inboxItems = $inboxService->getInboxItems('user_notifications', auth()->id());
       return view('inbox.show', compact('inboxItems'));
   }
   

   Render items in a Blade template:

   @foreach($inboxItems as $item)
       <div class="inbox-item">
           <h4>{{ $item->title }}</h4>
           <p>{{ $item->content }}</p>
           <small>{{ $item->created_at->diffForHumans() }}</small>
       </div>
   @endforeach
   

Implementation Patterns

Core Workflows

1. Creating Inbox Items Use the InboxService to create items programmatically:

   $inboxService->createInboxItem([
       'type' => 'user_notifications',
       'user_id' => auth()->id(),
       'title' => 'New Message',
       'content' => 'You have a new message in your inbox.',
       'metadata' => ['url' => '/messages/123'],
       'is_read' => false,
   ]);
   

   • Trigger from Events: Attach listeners to Laravel events (e.g., OrderShipped) to auto-populate the inbox:

     event(new OrderShipped($order));
     // In listener:
     $inboxService->createInboxItem([...]);
     

2. Bulk Actions Mark items as read/unread or delete them:

   $inboxService->markAsRead('user_notifications', [1, 2, 3]);
   $inboxService->deleteItems('user_notifications', [1, 2, 3]);
   

3. Custom Inbox Types Extend the bundle by defining new inbox types in the database:

   // Migration for a new type (e.g., 'system_alerts')
   Schema::create('inbox_types', function (Blueprint $table) {
       $table->id();
       $table->string('name')->unique();
       $table->timestamps();
   });
   

   Register the type in config/atm_inbox.php:

   'types' => [
       'user_notifications' => ['label' => 'User Notifications'],
       'system_alerts' => ['label' => 'System Alerts'],
   ],
   

4. Integration with Notifications Use Laravel’s notification system to auto-create inbox items:

   use Atm\InboxBundle\Notification\InboxNotification;
   
   Notification::route('inbox', 'user_notifications')
               ->notify(new InboxNotification('New Alert', 'Check your system alerts.'));
   

Advanced Patterns

• Scoped Inboxes: Filter items by custom logic (e.g., only unread items older than 7 days):

  $inboxService->getInboxItems('user_notifications', auth()->id(), [
      'read' => false,
      'older_than_days' => 7,
  ]);
  

• Webhooks/External Triggers: Use HTTP endpoints to create items from external systems:

  Route::post('/api/inbox/webhook', function (Request $request) {
      $inboxService->createInboxItem([
          'type' => 'system_alerts',
          'user_id' => $request->user_id,
          'title' => $request->title,
          // ...
      ]);
  });
  

• Custom Views: Override default templates by publishing and extending the bundle’s views:

  php artisan vendor:publish --tag=atm-inbox-views
  

Gotchas and Tips

Common Pitfalls

1. Missing Database Tables

   • Run migrations after installation:

     php artisan migrate
     

   • If using custom types, ensure their tables are created (e.g., inbox_items_user_notifications).

2. Permission Issues

   • The bundle may require middleware to restrict access to inbox routes. Add this to app/Http/Kernel.php:

     'web' => [
         \Atm\InboxBundle\Http\Middleware\CheckInboxPermissions::class,
         // ...
     ],
     

3. Event Listeners Not Triggering

   • Ensure listeners are registered in EventServiceProvider:

     protected $listen = [
         'order.shipped' => [
             'Atm\InboxBundle\Listeners\CreateInboxItemListener',
         ],
     ];
     

4. Metadata Serialization

   • The metadata field is JSON-encoded. Ensure your data is serializable:

     'metadata' => json_encode(['key' => 'value']), // ✅
     'metadata' => new \DateTime(), // ❌ (will fail)
     

Debugging Tips

• Log Creation: Enable debug mode in config/atm_inbox.php to log item creation:

  'debug' => env('APP_DEBUG', false),
  

• Query Builder: Use toSql() to inspect generated queries:

  $query = $inboxService->getQueryBuilder('user_notifications', auth()->id());
  dd($query->toSql(), $query->getBindings());
  

• Admin Interface: If the bundle includes an admin panel, check for UI errors in browser dev tools (e.g., 404s for JS/CSS).

Extension Points

1. Custom Item Models Extend the base InboxItem model to add fields:

   class CustomInboxItem extends \Atm\InboxBundle\Entity\InboxItem
   {
       protected $attributes = [
           'custom_field' => null,
       ];
   }
   

   Update the bundle’s configuration to use your model.

2. Override Services Bind your custom service in config/services.php:

   'inbox' => [
       'service' => \App\Services\CustomInboxService::class,
   ],
   

3. Add Custom Actions Extend the inbox item actions (e.g., "Archive", "Share") by publishing the bundle’s assets and overriding the action logic:

   php artisan vendor:publish --tag=atm-inbox-actions
   

Performance Considerations

• Pagination: Always paginate inbox items in views to avoid N+1 queries:

  $inboxItems = $inboxService->getInboxItems('user_notifications', auth()->id(), [
      'paginate' => 20,
  ]);
  

• Indexing: Add indexes to user_id and type columns in the inbox_items table for large datasets:

  Schema::table('inbox_items', function (Blueprint $table) {
      $table->index('user_id');
      $table->index('type');
  });