Laravel Customer Support Laravel Package

Getting Started

Minimal Steps to Launch

1. Install the Package

   composer require a2zwebltd/laravel-customer-support
   php artisan migrate
   php artisan vendor:publish --tag=customer-support-config
   

2. Add the Trait to Your User Model

   // app/Models/User.php
   use A2ZWeb\CustomerSupport\Concerns\HasSupportTickets;
   
   class User extends Authenticatable implements HasMedia
   {
       use HasSupportTickets;
   }
   

3. Define Agent Gate

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       Gate::define('manage-support-tickets', fn (User $user) => $user->is_admin);
   }
   

4. Run the Escalation Command (Optional but Recommended)

   // routes/console.php
   Schedule::command('support:escalate-overdue')->hourly();
   

5. Test the UI
   • Visit /support (customer-facing) or /support/admin (agent dashboard).
   • Create a test ticket via /support/new.

First Use Case: Basic Ticket Creation

• Customer Flow:
  • Navigate to /support/new.
  • Fill out the form (subject, message, category, priority).
  • Submit to create a ticket.
• Agent Flow:
  • Log in as an agent (must pass the manage-support-tickets gate).
  • View tickets in /support/admin.
  • Reply to tickets via the threaded interface.

Where to Look First

• Configuration: config/customer-support.php (customize routes, SLA hours, email templates).
• Models: app/Models/SupportTicket.php and app/Models/SupportTicketMessage.php (extend for custom fields).
• Livewire Components: resources/views/livewire/ (override or extend Flux components).
• Mailables: app/Mail/ (customize notification emails).
• Policies: app/Policies/SupportTicketPolicy.php (fine-tune authorization).

Implementation Patterns

Core Workflows

1. Ticket Creation and Management

• Customer-Side:

  // Create a ticket via API or Livewire form
  $ticket = auth()->user()->createTicket([
      'subject' => 'Payment Issue',
      'message' => 'My order #12345 is pending...',
      'category_id' => 1,
      'priority' => 'high',
  ]);
  

• Agent-Side:

  // Assign a ticket to an agent
  $ticket->assignTo($agentUser);
  
  // Reply to a ticket
  $ticket->reply('Here’s the resolution:', ['is_internal' => false]);
  
  // Add an internal note
  $ticket->reply('Follow-up: Call customer.', ['is_internal' => true]);
  

2. SLA and Escalation

• Configure SLAs in config/customer-support.php:

  'sla_hours' => [
      'low' => 72,    // 3 days
      'normal' => 24, // 1 day
      'high' => 8,    // 8 hours
      'urgent' => 2,   // 2 hours
  ],
  

• Escalate Overdue Tickets:

  php artisan support:escalate-overdue
  

  • Automatically updates ticket status to Overdue and notifies admins.
  • Schedule via cron (Schedule::command('support:escalate-overdue')->hourly()).

3. Attachments

• Add to Tickets:

  $ticket->addMedia($file)->toMediaCollection('ticket-attachments');
  

• Add to Messages:

  $ticket->reply('Check the attached docs.', ['attachments' => [$file]]);
  

4. Email Notifications

• Customize Templates:
  • Override mailables in app/Mail/ (e.g., TicketCreated.php).
  • Use @component directives in Blade templates for Flux components.
• Queue Notifications:

  event(new TicketCreated($ticket));
  // Automatically triggers mailables via Laravel’s event system.
  

5. Nova Integration (Optional)

• Auto-registered Resources:
  • SupportTicketResource and SupportTicketMessageResource appear in Nova if installed.
• Customize Nova Fields:

  // app/Nova/SupportTicketResource.php
  public static $displayInNavigation = true;
  public static $title = 'Support Tickets';
  

Integration Tips

Livewire/Flux UI

• Override Components:
  • Copy vendor/a2zwebltd/laravel-customer-support/resources/views/livewire/ to resources/views/livewire/.
  • Extend Flux components (e.g., TicketList):

    // resources/views/livewire/ticket-list.blade.php
    @extends('livewire.flux::components.base')
    @section('content')
        <div>
            <!-- Custom logic -->
            @foreach($tickets as $ticket)
                <x-flux.card>
                    {{ $ticket->subject }}
                </x-flux.card>
            @endforeach
        </div>
    @endsection
    

• Dark Mode:
  • Use Flux’s dark class or override Tailwind config to match your theme.

Custom Fields

• Add to Tickets:

  // Migration
  Schema::table('support_tickets', function (Blueprint $table) {
      $table->string('custom_field')->nullable();
  });
  

• Update Model:

  // app/Models/SupportTicket.php
  protected $fillable = ['custom_field', ...];
  

Multi-Tenancy

• Scope Tickets by Tenant:

  // app/Models/SupportTicket.php
  public function scopeForTenant($query, $tenantId)
  {
      return $query->where('tenant_id', $tenantId);
  }
  

• Extend User Model:

  // app/Models/User.php
  public function currentTenant()
  {
      return $this->tenant; // Assuming a `tenant()` relationship.
  }
  

API Access (Headless Mode)

• Expose Endpoints:

  // routes/api.php
  Route::middleware('auth:sanctum')->group(function () {
      Route::apiResource('support/tickets', \A2ZWeb\CustomerSupport\Http\Controllers\TicketController::class);
  });
  

• Use the Package’s Controllers:
  • Extend TicketController or MessageController for custom logic.

Gotchas and Tips

Pitfalls

1. Livewire Dependency:

   • The UI requires Livewire 3/4 + Flux 2. If your app doesn’t use Livewire, you’ll need to:
     • Fork the package and remove Livewire dependencies (high effort).
     • Build a custom API layer and frontend (recommended for non-Livewire apps).
   • Workaround: Use the package’s models/controllers headlessly and replace the UI with your own.

2. MediaLibrary Conflicts:

   • The package uses spatie/laravel-medialibrary for attachments. If your app uses a different media library (e.g., intervention/image), conflicts may arise.
   • Solution: Override the HasMedia trait or use a shared media collection.

3. SLA Calculation Quirks:

   • SLAs are calculated from created_at and use sla_hours config. If tickets are edited after creation, SLAs may not recalculate automatically.
   • Fix: Add a touch() to the ticket when updating critical fields:

     $ticket->update(['subject' => 'Updated']);
     $ticket->touch(); // Resets SLA timer
     

4. Nova Auto-Registration:

   • Nova resources are auto-registered only if Nova is installed. If you install Nova later, run:

     php artisan vendor:publish --tag=customer-support-config
     

     to ensure resources are loaded.

5. Email Queueing:

   • Notifications are queueable but may fail silently if the queue worker isn’t running.
   • Tip: Test email delivery locally with php artisan queue:work.

6. Threaded Replies Pagination:

   • The SupportTicketMessage model uses paginate() for replies. If you have many messages, consider adding with(['ticket', 'user']) to avoid N+1 queries:

     $messages = $ticket->messages()->with(['ticket', 'user'])->paginate(20);
     

Debugging Tips

1. Ticket Not Showing in Admin Dashboard:

   • Verify the manage-support-tickets gate is defined and the user passes it.
   • Check if the ticket’s status is not Closed (filtered by default in the UI).

2. Attachments Not Uploading:

   • Ensure spatie/laravel-medialibrary is properly configured in `