Ticketit Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aytaceminoglu/ticketit
   php artisan vendor:publish --provider="Ticketit\TicketitServiceProvider" --tag=config
   php artisan migrate
   

2. Configuration

   • Publish the config file (config/ticketit.php) and adjust settings like:
     • ticket_table (default: tickets)
     • ticket_statuses (e.g., open, pending, closed)
     • default_assignee (e.g., admin@domain.com)

3. First Use Case

   • Create a ticket via Tinker or a controller:

     use Ticketit\Ticket;
     $ticket = Ticket::create([
         'title' => 'Test Ticket',
         'description' => 'This is a test ticket.',
         'user_id' => auth()->id(), // Laravel's default auth user
     ]);
     

   • Access the demo at http://ticketit.kordy.info/tickets for UI reference.

Implementation Patterns

Core Workflows

1. Ticket Creation

   • Use the Ticket model to create, update, or delete tickets:

     // Create with assignee
     $ticket = Ticket::create([
         'title' => 'Bug Report',
         'description' => 'Login fails on mobile.',
         'user_id' => auth()->id(),
         'assignee_id' => 1, // User ID of assignee
         'status' => 'open',
     ]);
     

   • Validation: Leverage Laravel’s built-in validation or extend the Ticket model’s rules() method.

2. Status Transitions

   • Use the status field to track workflow (e.g., open → pending → closed).
   • Example in a controller:

     $ticket->update(['status' => 'pending']);
     

3. Attachments

   • Store files in storage/app/public/ticket_attachments and save paths in the attachments JSON column:

     $ticket->attachments = json_encode(['file1.pdf', 'file2.jpg']);
     $ticket->save();
     

4. Notifications

   • Extend the TicketObserver or use Laravel’s notify() to send emails/Slack alerts on status changes:

     use Ticketit\Observers\TicketObserver;
     class CustomTicketObserver extends TicketObserver {
         public function updated(Ticket $ticket) {
             if ($ticket->wasChanged('status')) {
                 $ticket->user->notify(new TicketStatusUpdated($ticket));
             }
         }
     }
     

5. API Integration

   • Use Laravel’s API resources to expose tickets:

     // routes/api.php
     Route::apiResource('tickets', 'TicketController')->middleware('auth:api');
     

   • Example resource:

     public function toArray($request) {
         return [
             'id' => $this->id,
             'title' => $this->title,
             'status' => $this->status,
             'created_at' => $this->created_at->diffForHumans(),
         ];
     }
     

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If you customize the tickets table, ensure the ticketit migrations don’t overwrite your changes. Run php artisan vendor:publish --tag=migrations to customize them first.

2. Auth Integration

   • The package assumes Laravel’s default users table. If using a custom auth system, override the user() relationship in the Ticket model:

     public function user() {
         return $this->belongsTo('App\Models\CustomUser');
     }
     

3. Attachment Handling

   • The attachments field is a JSON column. Ensure your database supports JSON (e.g., MySQL 5.7+). For older versions, use a text column and manually serialize/deserialize:

     $attachments = json_decode($ticket->attachments, true);
     

4. Status Field

   • The status field defaults to open. If you add custom statuses (e.g., escalated), update the ticket_statuses config array and ensure UI templates reflect these changes.

5. Demo Dependency

   • The demo at http://ticketit.kordy.info/tickets may not match your local setup. Clone the repo’s resources/views for reference, but avoid copying vendor files directly.

Debugging Tips

1. Log Observers

   • Enable Laravel’s query logging to debug observer issues:

     DB::enableQueryLog();
     $ticket->update(['status' => 'closed']);
     dd(DB::getQueryLog());
     

2. Check Config

   • Verify config/ticketit.php for misconfigurations, especially:
     • ticket_table (must match your migrations).
     • ticket_statuses (must include all used statuses).

3. Artisan Commands

   • Use php artisan ticketit:clear-cache if templates or assets aren’t updating.

Extension Points

1. Custom Fields

   • Add fields to the tickets table and extend the Ticket model:

     protected $fillable = ['title', 'description', 'priority']; // Add 'priority'
     

   • Update the migration and config accordingly.

2. Custom Views

   • Override vendor views in resources/views/vendor/ticketit/ to customize the UI without modifying the package.

3. API Filters

   • Use Laravel’s API resources or Scout for advanced filtering:

     // Example: Filter tickets by status
     $tickets = Ticket::whereIn('status', ['open', 'pending'])->get();
     

4. Webhooks

   • Trigger external actions (e.g., Zapier) by extending the TicketObserver:

     public function saved(Ticket $ticket) {
         Http::post('https://your-webhook.com', [
             'ticket_id' => $ticket->id,
             'status' => $ticket->status,
         ]);
     }