Laravel Customer Support Laravel Package

Getting Started

Minimal Setup for First Use Case

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. Schedule SLA Escalation (Optional but Recommended)

   // routes/console.php
   use Illuminate\Support\Facades\Schedule;
   
   Schedule::command('support:escalate-overdue')->hourly();
   

5. Test the UI

   • Visit /support to see the public ticket interface.
   • Visit /support/admin (if authenticated as an agent) to access the admin dashboard.

First Use Case: Creating a Ticket

1. Customer Submits a Ticket

   • Navigate to /support/new and fill out the form (title, description, category, priority).
   • The system automatically:
     • Creates a SupportTicket record.
     • Sends a confirmation email to the customer.
     • Notifies admins (if configured in mail.admin_recipients).

2. Agent Responds

   • Log in as an agent and navigate to /support/admin.
   • Select the ticket, reply via the threaded interface, and update the status.
   • Attachments can be added using Spatie’s MediaLibrary.

Implementation Patterns

Core Workflows

1. Ticket Creation and Management

• Customer Flow:

  // In a controller or Livewire component
  $ticket = auth()->user()->createTicket([
      'title' => 'Issue with payment',
      'description' => 'My order #12345 failed to process.',
      'category_id' => 1, // e.g., "Payments"
      'priority' => 'high',
  ]);
  

• Agent Flow:

  // Assign a ticket to an agent
  $ticket->assignTo($agentUser);
  
  // Reply to a ticket
  $ticket->reply('We are investigating this issue.', [
      'is_internal' => false, // Visible to customer
  ]);
  

2. SLA Tracking

• 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 hourly via the EscalateOverdueTickets command.

3. Attachments

• Use Spatie’s MediaLibrary to attach files to tickets or messages:

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

4. Email Notifications

• Customize email templates in resources/views/vendor/customer-support/emails.
• Queue emails for performance:

  Mail::to($ticket->user)->queue(new TicketCreated($ticket));
  

5. Livewire UI Customization

• Extend or replace Livewire components in resources/views/vendor/customer-support/livewire.
• Use Flux for theming:

  // config/customer-support.php
  'theme' => [
      'accent' => 'teal-500',
  ],
  

6. Nova Integration (Optional)

• If using Nova, the package auto-registers resources for SupportTicket and SupportTicketMessage.
• Customize Nova resources by publishing the config:

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

Integration Tips

API-First Approach (Headless)

• If you don’t want to use the Livewire UI, expose the models via API:

  // routes/api.php
  Route::apiResource('tickets', \A2ZWeb\CustomerSupport\Http\Controllers\Api\TicketController::class);
  

• Use Laravel’s built-in API resources to return ticket data.

Multi-Tenant Support

• For multi-tenant apps, scope tickets to the current tenant:

  // app/Models/SupportTicket.php
  protected static function booted()
  {
      static::addGlobalScope(new TenantScope(function (Builder $builder) {
          $builder->where('tenant_id', auth()->user()->tenant_id);
      }));
  }
  

Custom Ticket Fields

• Add custom fields via migrations:

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

• Extend the SupportTicket model to include the new field.

Domain Events

• Listen to events for custom logic:

  // app/Providers/EventServiceProvider.php
  protected $listen = [
      \A2ZWeb\CustomerSupport\Events\TicketCreated::class => [
          \App\Listeners\LogTicketCreation::class,
      ],
  ];
  

Automated Workflows

• Use Laravel’s task scheduling to automate actions:

  // routes/console.php
  Schedule::call(function () {
      $overdueTickets = SupportTicket::where('due_at', '<', now())
          ->where('status', '!=', 'resolved')
          ->get();
  
      foreach ($overdueTickets as $ticket) {
          // Send escalation email or notify Slack
      }
  })->hourly();
  

Gotchas and Tips

Pitfalls

1. Livewire Dependency

   • The UI is tightly coupled to Livewire. If you’re not using Livewire, you’ll need to:
     • Replace the Livewire components with Blade or another frontend framework.
     • Fork the package and remove Livewire dependencies (high effort).
   • Workaround: Use the package’s API endpoints to build a custom frontend.

2. SLA Configuration Quirks

   • SLAs are configured in hours but may not account for business hours or holidays.
   • Tip: Extend the Sla model or use a package like spatie/laravel-holidays to adjust due dates dynamically.

3. Attachment Storage

   • The package uses Spatie’s MediaLibrary, which defaults to local storage. If you’re using S3 or another cloud provider, ensure the config/filesystems.php is properly configured.
   • Tip: Test attachment uploads thoroughly, especially for large files.

4. Email Delays

   • Email notifications are queueable but may delay if the queue is backed up.
   • Tip: Monitor the failed_jobs table and set up retries for critical emails.

5. Nova Auto-Registration

   • If you’re not using Nova, the auto-registration of resources may cause errors.
   • Tip: Disable Nova integration by setting 'nova' => false in the config.

6. Threaded Replies Pagination

   • The SupportTicketMessage model may return large datasets if not paginated.
   • Tip: Use cursor() or simplePaginate() when fetching messages in Livewire.

7. Gate Misconfiguration

   • The manage-support-tickets gate must be defined correctly; otherwise, agents won’t have access.
   • Tip: Test the gate with php artisan gate:test manage-support-tickets.

8. Time Zone Handling

   • SLAs and due dates use the server’s time zone. If your app supports multiple time zones, ensure consistency.
   • Tip: Use Carbon::setToStringFormat() or middleware to standardize time zones.

Debugging Tips

1. Ticket Not Showing in Admin Dashboard

   • Check if the user has the manage-support-tickets gate.
   • Verify the assigned_to field is populated or the ticket is unassigned.

2. Attachments Not Uploading

   • Ensure Spatie’s MediaLibrary is properly configured.
   • Check the config/customer-support.php for attachment settings.

3. SLA Not Triggering

   • Verify the EscalateOverdueTickets command is scheduled.
   • Check the due_at field is calculated correctly (e.g., created_at + sla_hours).

4. Livewire Component Errors

   • Clear the Livewire cache:

     php artisan livewire:discover
     

   • Check the browser’s console for JavaScript errors.

5. Email Notifications Failing

   • Test email sending with:

     php artisan queue:work
     

   • Check the failed_jobs table for errors.

Extension Points

1. Custom Ticket Statuses
   • Extend