Ticketable Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravelir/ticketable
   php artisan vendor:publish --provider="Laravelir\Ticketable\Providers\TicketableServiceProvider"
   php artisan migrate
   

   • The ticketable:install command (mentioned in README) is likely a placeholder; verify if it exists or use vendor:publish for config/migration files.

2. Publish Config:

   php artisan vendor:publish --tag="ticketable-config"
   

   • Locate the config file at config/ticketable.php and review default settings (e.g., ticket models, statuses, or queues).

3. First Use Case:

   • Attach a Ticket to a Model:

     use Laravelir\Ticketable\Traits\Ticketable;
     
     class Order extends Model
     {
         use Ticketable;
     }
     
     $order = Order::find(1);
     $ticket = $order->createTicket('Issue with payment', 'High');
     

   • Query Tickets:

     $order->tickets()->where('status', 'open')->get();
     

Implementation Patterns

Core Workflows

1. Ticket Creation:

   • Dynamic Ticket Generation:

     $ticket = $model->createTicket(
         title: 'Refund request',
         description: 'Customer needs a refund for order #123',
         status: 'pending', // Customize via config
         assignee_id: 1    // Optional: Assign to a user
     );
     

   • Mass Ticket Assignment:

     Order::where('status', 'failed')->each(function ($order) {
         $order->createTicket('Payment failed', 'Medium');
     });
     

2. Ticket Management:

   • Status Transitions:

     $ticket->updateStatus('resolved');
     // Or use events (if supported):
     $ticket->resolve();
     

   • Commenting:

     $ticket->addComment('Investigating...', $user);
     

3. Integration with Existing Systems:

   • Event Listeners:

     // Example: Auto-create tickets for failed jobs
     Failed::listen(function ($event) {
         $event->job->model()->createTicket(
             'Job failed: ' . $event->job->getName(),
             'High'
         );
     });
     

   • API Endpoints:

     Route::get('/orders/{order}/tickets', [TicketController::class, 'index']);
     

4. Customization:

   • Extend Ticket Model:

     class CustomTicket extends \Laravelir\Ticketable\Models\Ticket
     {
         protected $casts = [
             'priority' => 'string', // Override defaults
         ];
     }
     

   • Add Ticketable to Multiple Models:

     class User extends Model
     {
         use Ticketable;
         protected $ticketModel = CustomTicket::class;
     }
     

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If the package includes migrations, ensure they don’t conflict with existing tickets or ticketables tables. Check the published migration files (database/migrations/xxxx_create_ticketables_table.php).

2. Model Binding:

   • The Ticketable trait assumes a polymorphic relationship. If your tickets table uses a different structure (e.g., ticketable_id + ticketable_type), verify the trait’s bootTicketable() method aligns with your schema.

3. Performance:

   • N+1 Queries: Eager-load tickets when listing models:

     $orders = Order::with('tickets')->get();
     

   • Indexing: Add indexes to ticketable_id and status columns if querying frequently.

4. Configuration Overrides:

   • The package may default to a Ticket model. Override it globally in config/ticketable.php:

     'model' => \App\Models\CustomTicket::class,
     

Debugging

1. Missing Trait Methods:

   • If createTicket() or tickets() are undefined, ensure:
     • The trait is correctly used in your model.
     • The TicketableServiceProvider is registered in config/app.php.

2. Event Debugging:

   • Check if events (e.g., TicketCreated) are firing:

     TicketCreated::listen(function ($event) {
         Log::debug('Ticket created:', [$event->ticket]);
     });
     

3. Queue Issues:

   • If tickets are delayed or stuck, verify the queue driver (e.g., sync, database) in .env and check the failed_jobs table.

Extension Points

1. Custom Statuses:

   • Extend the status column by adding a statuses config array:

     'statuses' => [
         'open', 'pending', 'resolved', 'closed', 'escalated'
     ],
     

   • Add validation in a Creating event:

     TicketCreating::listen(function ($event) {
         if (!in_array($event->ticket->status, config('ticketable.statuses'))) {
             throw new \InvalidArgumentException('Invalid status');
         }
     });
     

2. API Resources:

   • Create a custom resource for tickets:

     php artisan make:resource TicketResource
     

     // app/Http/Resources/TicketResource.php
     public function toArray($request)
     {
         return [
             'id' => $this->id,
             'title' => $this->title,
             'status' => $this->status,
             'model_type' => $this->ticketable_type,
             'model_id' => $this->ticketable_id,
             'comments' => CommentResource::collection($this->comments),
         ];
     }
     

3. Notifications:

   • Trigger notifications when tickets are created/resolved:

     TicketCreated::listen(function ($event) {
         Notification::route('mail', $event->ticket->assignee)
             ->notify(new TicketAssigned($event->ticket));
     });
     

4. Testing:

   • Use factories for tickets:

     $ticket = Ticket::factory()->for($order)->create();
     

   • Mock the trait in tests:

     $order = new class extends Order {
         use Ticketable;
     };