Support Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require baks-dev/support baks-dev/support-answer
   

   • Verify baks-dev/support and baks-dev/support-answer are listed in composer.json.

2. Publish Configurations (if applicable):

   php artisan vendor:publish --provider="BaksDev\Support\SupportServiceProvider" --tag="config"
   

   • Check for config/support.php for default settings (e.g., queue drivers, logging).

3. Run Migrations:

   php artisan migrate
   

   • Inspect generated tables (e.g., support_messages, support_answers) for schema details.

4. First Use Case:

   • Create a Support Message:

     use BaksDev\Support\Facades\Support;
     
     // Send a message via facade
     $message = Support::message()
         ->from('user@example.com')
         ->subject('API Issue')
         ->body('Failed to authenticate')
         ->send();
     
     // Or via a model (if using Eloquent integration)
     $user = User::find(1);
     $user->sendSupportMessage('API Error', 'Error details here...');
     

5. Verify with Tests:

   php bin/phpunit --group=support
   

   • Confirm core functionality (e.g., message creation, reply handling) passes.

Implementation Patterns

Core Workflows

1. Message Lifecycle:

   • Creation: Use Support::message() or model methods (e.g., User::sendSupportMessage()).
   • Assignment: Assign to agents via:

     $message->assignTo($agent);
     

   • Resolution: Mark as resolved:

     $message->resolve('Issue fixed');
     

   • Replies: Attach answers:

     $message->addAnswer('Thanks for your help!');
     

2. Event-Driven Extensions:

   • Listen for events (if supported):

     // Example: Listen for message sent events
     event(new \BaksDev\Support\Events\MessageSent($message));
     

   • Register listeners in EventServiceProvider:

     protected $listen = [
         \BaksDev\Support\Events\MessageSent::class => [
             \App\Listeners\LogSupportMessage::class,
         ],
     ];
     

3. Queue Integration:

   • Delay processing with queues:

     $message = Support::message()->delay(60)->send();
     

   • Configure queue driver in config/support.php:

     'queue' => [
         'driver' => 'database', // or 'redis', 'beanstalkd'
     ],
     

4. Custom Fields:

   • Extend message models via traits or inheritance:

     namespace App\Models;
     
     use BaksDev\Support\Models\SupportMessage;
     use Illuminate\Database\Eloquent\Relations\MorphMany;
     
     class CustomSupportMessage extends SupportMessage
     {
         public function customFields()
         {
             return $this->morphMany(CustomField::class, 'fieldable');
         }
     }
     

5. API Integration:

   • Expose endpoints via Laravel routes:

     Route::middleware('auth:sanctum')->group(function () {
         Route::apiResource('support/messages', \BaksDev\Support\Http\Controllers\MessageController::class);
     });
     

   • Customize responses with API resources:

     namespace App\Http\Resources;
     
     use BaksDev\Support\Models\SupportMessage;
     use Illuminate\Http\Resources\Json\JsonResource;
     
     class SupportMessageResource extends JsonResource
     {
         public function toArray($request)
         {
             return [
                 'id' => $this->id,
                 'subject' => $this->subject,
                 'status' => $this->status,
                 // Custom fields
             ];
         }
     }
     

Integration Tips

• Authentication: Use Laravel’s built-in auth (e.g., auth:sanctum) for API access.
• Notifications: Extend with Laravel Notifications:

  $message->notify(new \App\Notifications\SupportMessageCreated($message));
  

• Real-Time Updates: Pair with Laravel Echo/Pusher for live updates:

  Echo.channel('support.messages')
      .listen('SupportMessageUpdated', (e) => {
          console.log('Message updated:', e.message);
      });
  

• Validation: Override default validation rules:

  use BaksDev\Support\Rules\ValidSupportMessage;
  
  $request->validate([
      'subject' => ['required', 'string', new ValidSupportMessage],
  ]);
  

Gotchas and Tips

Pitfalls

1. Database Conflicts:

   • Issue: Package migrations may clash with existing tables (e.g., support_messages).
   • Fix: Review migrations before running php artisan migrate. Use --pretend to dry-run:

     php artisan migrate --pretend
     

2. Undocumented Dependencies:

   • Issue: baks-dev/support-answer may introduce hidden dependencies (e.g., Laravel Nova, Spatie packages).
   • Fix: Run composer why baks-dev/support-answer to inspect dependencies.

3. Queue Stuck Jobs:

   • Issue: Messages may hang in failed_jobs table if queue workers fail.
   • Fix: Monitor with Laravel Horizon or Telescope. Retry failed jobs:

     php artisan queue:retry all
     

4. Real-Time Disconnects:

   • Issue: WebSocket broadcasting may drop if not configured properly.
   • Fix: Ensure config/broadcasting.php is set up for Pusher/Laravel WebSockets.

5. PHP 8.4+ Features:

   • Issue: Uses modern PHP features (e.g., enums, attributes) that may break older Laravel versions.
   • Fix: Test with laravel/framework:^10.0 and PHP 8.4+.

Debugging Tips

1. Enable Debug Logging:

   // In config/support.php
   'logging' => [
       'enabled' => true,
       'channel' => 'single', // or 'stack'
   ],
   

   • Check logs in storage/logs/laravel.log for errors.

2. SQL Debugging:

   • Enable query logging:

     DB::enableQueryLog();
     $message = Support::message()->send();
     dd(DB::getQueryLog());
     

3. Event Debugging:

   • Listen for all events in EventServiceProvider:

     public function boot()
     {
         if (app()->environment('local')) {
             $this->listenForAllEvents();
         }
     }
     

4. Queue Debugging:

   • Tail queue logs:

     tail -f storage/logs/laravel-queue.log
     

Extension Points

1. Custom Message Types:

   • Extend the base SupportMessage model:

     namespace App\Models;
     
     use BaksDev\Support\Models\SupportMessage;
     
     class SlackMessage extends SupportMessage
     {
         protected $channel = 'slack';
     }
     

2. Override Services:

   • Bind custom implementations in AppServiceProvider:

     public function register()
     {
         $this->app->bind(
             \BaksDev\Support\Contracts\MessageRepository::class,
             \App\Repositories\CustomMessageRepository::class
         );
     }
     

3. Add Custom Fields:

   • Use Laravel’s morph maps and polymorphic relations:

     // In AppServiceProvider
     SupportMessage::morphMap([
         'custom_field' => \App\Models\CustomField::class,
     ]);
     

4. Modify Notifications:

   • Override the default notification channel:

     // In config/support.php
     'notifications' => [
         'channel' => 'mail', // or 'slack', 'database'
     ],
     

Configuration Quirks

1. Queue Drivers:

   • Defaults to database; ensure config/queue.php is configured for your driver (e.g., Redis).

2. Broadcasting:

   • Requires config/broadcasting.php to be set up for Pusher or Laravel WebSockets.

3. Timezones:

   • Messages may use UTC by default. Override in config/support.php:

     'timezone' => 'America/New_York',
     

4. Rate Limiting:

   • If enabled, check config/support.php for limits (e.g., max_messages_per_minute).

Performance Tips

1. Eager Loading:

   • Avoid N+1 queries:

     $messages = SupportMessage::with('answers', 'agent')->get();
     

2. Caching:

   • Cache frequent queries:

     $messages = Cache::remember('support_messages', 60, function () {
         return SupportMessage::latest()->limit