Support Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aagroup/support
   php artisan vendor:publish --provider="AAGroup\Support\SupportServiceProvider" --tag=config
   php artisan migrate
   

   • Verify config/support.php is published and updated with your app’s database/queue settings.

2. First Use Case: Creating a Ticket

   use AAGroup\Support\Models\Ticket;
   
   // Create a ticket for the authenticated user
   $ticket = Ticket::create([
       'subject' => 'API Integration Issue',
       'body' => 'The endpoint /api/v1/users returns 500 errors.',
       'user_id' => auth()->id(),
       'status' => 'open', // or 'pending', 'resolved', etc.
   ]);
   

   • Key Files to Review:
     • app/Models/Ticket.php (default model)
     • routes/support.php (published routes for tickets, replies, etc.)
     • resources/views/support/ (Blade templates for ticket listings/replies)

3. Quick Integration with Auth

   • The package uses Laravel’s default users table. No extra auth setup is needed unless extending roles (e.g., "Agent" vs. "Customer").

Implementation Patterns

Core Workflows

1. Ticket Lifecycle Management

   • Create/Update:

     $ticket->update(['status' => 'resolved', 'resolved_at' => now()]);
     

   • Assign to Agents:

     $ticket->agents()->attach(auth()->id()); // For multi-agent support
     

   • Add Replies:

     $ticket->replies()->create([
         'body' => 'Debugged the issue. Try this fix...',
         'user_id' => auth()->id(),
     ]);
     

2. Querying Tickets

   • Filter by Status/User:

     $openTickets = Ticket::where('status', 'open')
         ->where('user_id', auth()->id())
         ->with('replies')
         ->get();
     

   • Search by Subject/Body:

     $searchTerm = request('q');
     $results = Ticket::where(function($query) use ($searchTerm) {
         $query->where('subject', 'like', "%{$searchTerm}%")
               ->orWhere('body', 'like', "%{$searchTerm}%");
     })->get();
     

3. Queue-Based Notifications

   • Trigger Email/Slack Alerts:

     // Dispatch a new ticket event (extend the package’s events)
     event(new \AAGroup\Support\Events\TicketCreated($ticket));
     

   • Listen for Events:

     // In EventServiceProvider
     protected $listen = [
         \AAGroup\Support\Events\TicketCreated::class => [
             \AAGroup\Support\Listeners\SendTicketNotification::class,
         ],
     ];
     

4. API Integration

   • Expose Tickets via API:

     Route::get('/api/tickets', function() {
         return Ticket::with('replies', 'user')->get();
     });
     

   • Use Laravel Sanctum/Passport for auth if needed.

Integration Tips

• Extend the Model:

  // Add custom fields (e.g., priority)
  Schema::table('tickets', function(Blueprint $table) {
      $table->string('priority')->default('medium');
  });
  

  Update Ticket model to cast/access the new field.

• Customize Views: Override published Blade templates in resources/views/support/ to match your app’s design.

• Role-Based Access: Use Laravel’s Gate/Policy system to restrict ticket actions:

  Gate::define('delete-ticket', function($user, $ticket) {
      return $user->isAdmin() || $ticket->user_id === $user->id;
  });
  

• Testing: Use Laravel’s testing helpers:

  $this->actingAs($user)
       ->post('/support/tickets', ['subject' => 'Test', 'body' => 'Body']);
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If you’ve modified the users table, the package’s migrations may fail. Solution: Manually adjust the tickets table migration to match your schema (e.g., add priority column).

2. Event Dispatching

   • The package dispatches events (e.g., TicketCreated) but doesn’t include listeners by default. Tip: Publish the events/config first:

     php artisan vendor:publish --provider="AAGroup\Support\SupportServiceProvider" --tag=events
     

3. Queue Stuck Jobs

   • If notifications fail silently, check failed_jobs table. Fix: Configure the queue driver in config/support.php (e.g., queue_connection => 'database').

4. Overwriting Routes

   • Published routes (routes/support.php) may conflict with your app’s routes. Tip: Prefix them:

     Route::prefix('helpdesk')->group(function() {
         // Published routes here
     });
     

Debugging Tips

• Log Ticket Events: Add a listener to log events:

  // In app/Listeners/LogTicketEvents.php
  public function handle($event) {
      \Log::info('Ticket event', ['event' => $event->class, 'data' => $event->ticket]);
  }
  

• Check Middleware: The package uses auth middleware. If routes fail, verify:

  Route::middleware(['auth'])->group(function() {
      // Support routes
  });
  

Extension Points

1. Custom Statuses: Extend the status field with a pivot table:

   // Add to Ticket model
   public function statuses() {
       return $this->belongsToMany(Status::class);
   }
   

2. Attachment Support: Add a ticket_attachments table and relationship:

   public function attachments() {
       return $this->hasMany(TicketAttachment::class);
   }
   

3. Webhooks: Dispatch events to external services:

   // In TicketCreated listener
   Http::post('https://your-webhook.com', ['ticket' => $ticket]);
   

4. API Rate Limiting: Use Laravel’s throttle middleware for /api/tickets:

   Route::middleware(['throttle:60,1'])->group(function() {
       // API routes
   });