Ticketit Laravel Package

Getting Started

Minimal Setup

1. Install & Publish Run the installation commands in order:

   composer require ticket/ticketit:dev-main
   php artisan vendor:publish --provider="Ticket\Ticketit\TicketitServiceProvider" --tag=ticketit-config
   php artisan vendor:publish --provider="Ticket\Ticketit\TicketitServiceProvider" --tag=ticketit-migrations
   php artisan migrate
   

   Verify config/ticketit.php exists and adjust defaults if needed.

2. User Model Integration Add HasTickets trait to your User model (both Customer and Staff models if separate):

   use Ticket\Ticketit\Traits\HasTickets;
   class User extends Authenticatable { use HasTickets; }
   

3. First Ticket Creation Use the facade or service directly:

   use Ticket\Ticketit\Facades\Ticketit;
   
   // Create a ticket for the current customer
   $ticket = Ticketit::createTicket([
       'subject' => 'Account Issue',
       'description' => 'Login not working',
       'priority' => 'high',
   ]);
   

First Use Case: Customer Support Portal

• Customer Flow:

  • Publish the ticketit::customer views to resources/views/vendor/ticketit/.
  • Add routes (published via --tag=ticketit-routes) or extend them in routes/web.php.
  • Customize the ticketit::customer.tickets.index view to match your theme.

• Staff Flow:

  • Use Ticketit::tickets() to fetch assigned tickets:

    $assignedTickets = Ticketit::tickets()->where('assigned_to', auth()->id())->get();
    

Implementation Patterns

Core Workflows

1. Ticket Lifecycle Management

• Creation:

  // Customer creates a ticket
  $ticket = auth()->user()->createTicket([
      'subject' => 'Payment Failed',
      'priority' => 'medium',
      'attachments' => ['/path/to/receipt.pdf'],
  ]);
  

• Assignment:

  // Staff assigns ticket to another agent
  $ticket->assignTo(2); // User ID
  

• Status Updates:

  $ticket->updateStatus('resolved');
  $ticket->reopen(); // Built-in method
  

2. Role-Based Access

• Admin Actions (via middleware or policy):

  // Bulk update status
  Ticketit::tickets()->whereIn('id', [1, 2, 3])->update(['status' => 'closed']);
  

• Agent Actions:

  // Add a comment (visible to customer)
  $ticket->addComment('Please check your email for updates.', ['is_private' => false]);
  

• Customer Actions:

  // Customer replies to a ticket
  $ticket->addComment('Here’s the error screenshot.', ['attachments' => ['screenshot.png']]);
  

3. Data Retrieval

• Filtered Queries:

  // Staff: Get high-priority unassigned tickets
  $tickets = Ticketit::tickets()
      ->where('priority', 'high')
      ->whereNull('assigned_to')
      ->with('comments')
      ->get();
  

• Customer View:

  // Customer: Get their open tickets
  $tickets = auth()->user()->tickets()->where('status', '!=', 'closed')->get();
  

4. Integration with Existing Systems

• Notifications:

  // Trigger when ticket status changes
  event(new TicketStatusUpdated($ticket, 'resolved'));
  

• Webhooks:

  // Listen for ticket creation
  Ticketit::onTicketCreated(function ($ticket) {
      // Send Slack notification
  });
  

Advanced Patterns

Customizing Views

Override published views in resources/views/vendor/ticketit/:

php artisan vendor:publish --provider="Ticket\Ticketit\TicketitServiceProvider" --tag=ticketit-views --force

• Extend ticketit::customer.tickets.show to add custom fields:

  @extends('ticketit::customer.tickets.show')
  @section('ticket-meta')
      <div class="custom-field">
          {{ $ticket->custom_field }}
      </div>
  @endsection
  

Extending Models

Add custom attributes to tickets via model events:

// app/Providers/TicketitServiceProvider.php
public function boot()
{
    \Ticket\Ticketit\Models\Ticket::created(function ($ticket) {
        $ticket->update(['custom_data' => json_encode(['source' => 'web'])]);
    });
}

API Endpoints

Use Laravel’s API resources to expose tickets:

// routes/api.php
Route::middleware('auth:api')->get('/tickets', function () {
    return Ticketit::tickets()->where('user_id', auth()->id())->paginate();
});

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If you modify the published migrations, always run:

     php artisan vendor:publish --tag=ticketit-migrations --force
     

     before altering them. Merge changes manually to avoid overwrites.

2. Role-Based Route Access

   • The package publishes routes but does not include middleware. Add checks in routes/web.php:

     Route::middleware(['auth', 'role:admin'])->group(function () {
         Route::get('/admin/tickets', 'TicketController@index');
     });
     

3. Attachment Handling

   • Attachments are stored in storage/app/public/ticket_attachments. Ensure the symlink exists:

     php artisan storage:link
     

   • Customize storage path in config/ticketit.php:

     'attachments' => [
         'disk' => 's3',
         'path' => 'ticket-attachments',
     ],
     

4. Priority/Status Validation

   • The package uses priority (low, medium, high) and status (open, pending, resolved, closed). Extend validation in app/Providers/TicketitServiceProvider.php:

     use Ticket\Ticketit\Rules\ValidPriority;
     
     $request->validate([
         'priority' => ['required', new ValidPriority],
     ]);
     

Debugging Tips

1. Query Logging Enable Laravel’s query logging to debug ticket queries:

   DB::enableQueryLog();
   $tickets = Ticketit::tickets()->get();
   dd(DB::getQueryLog());
   

2. Event Debugging Listen for events in AppServiceProvider:

   public function boot()
   {
       Ticket\Ticketit\Events\TicketCreated::class => function ($event) {
           \Log::info('Ticket created', ['ticket' => $event->ticket]);
       },
   }
   

3. Middleware Issues If routes fail silently, check:

   • The TicketitServiceProvider is registered in config/app.php.
   • The auth middleware is properly configured for your guards (e.g., auth:customer or auth:staff).

Extension Points

1. Custom Ticket Fields Add fields via model events or database migrations:

   // Add a 'department' field
   Schema::table('tickets', function (Blueprint $table) {
       $table->string('department')->nullable()->after('subject');
   });
   

   Update the Ticket model to cast the field:

   protected $casts = [
       'department' => 'string',
   ];
   

2. Custom Statuses/Priorities Extend the Ticket model’s getStatusOptions() and getPriorityOptions() methods:

   public function getStatusOptions()
   {
       return array_merge(parent::getStatusOptions(), ['escalated']);
   }
   

3. Custom Notifications Override the notification logic in AppServiceProvider:

   Ticket\Ticketit\Events\TicketCreated::class => [
       'TicketCreatedNotification',
   ],
   

   Create a custom notification:

   use Ticket\Ticketit\Events\TicketCreated;
   
   class TicketCreatedNotification implements ShouldQueue
   {
       public function handle(TicketCreated $event)
       {
           Notification::route('mail', $event->ticket->customer->email)
               ->notify(new TicketCreatedNotification($event->ticket));
       }
   }
   

4. API Rate Limiting Apply rate limits to ticket endpoints:

   Route::middleware(['auth:api', 'throttle:10,1'])->group(function () {
       Route::apiResource('tickets', 'TicketController');
   });
   

5. Search Functionality Use Laravel Scout for full-text search:

   // Add to Ticket model
   use Laravel\Scout\Searchable