Ticketit Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require ctos-app/ticketit
   php artisan vendor:publish --provider="Ticketit\TicketitServiceProvider"
   php artisan migrate
   

2. Configuration

   • Publish the config file (config/ticketit.php) and adjust settings like:
     • ticket_statuses (customize default states like "Open", "Closed")
     • ticket_priorities (e.g., "Low", "Medium", "High")
     • default_assignee (set a default user ID for new tickets)
   • Verify config/auth.php includes Ticketit\TicketitUserProvider in providers.

3. First Use Case

   • Create a Ticket via Trait Add the Ticketit\HasTickets trait to a model (e.g., User):

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

     Then create a ticket in a controller:

     $ticket = auth()->user()->tickets()->create([
         'title' => 'API Issue',
         'description' => 'Endpoint /api/v1/users returns 500',
         'priority' => 'high',
     ]);
     

   • View Tickets Use the provided Blade directives in resources/views:

     @ticketList(auth()->user()->tickets)
     @ticketView($ticket)
     

Implementation Patterns

Core Workflows

1. Ticket Management

   • CRUD via Eloquent:

     // Fetch open tickets
     $openTickets = auth()->user()->tickets()->whereStatus('open')->get();
     
     // Update status
     $ticket->update(['status' => 'closed', 'closed_at' => now()]);
     

   • Bulk Actions: Use the Ticketit\Ticket facade for batch operations:

     use Ticketit\Facades\Ticket;
     Ticket::updateStatus(['open'], 'closed', auth()->id());
     

2. Integration with Auth

   • Assign Tickets:

     $ticket->assignTo(User::find(2)); // Assign to another user
     

   • Role-Based Access: Extend the Ticketit\Policies\TicketPolicy to restrict actions by role:

     public function update(User $user, Ticket $ticket) {
         return $user->can('manage_tickets');
     }
     

3. Notifications

   • Event Listeners: Listen to TicketCreated, TicketUpdated, etc., in EventServiceProvider:

     protected $listen = [
         'Ticketit\Events\TicketCreated' => [
             'App\Listeners\SendTicketNotification',
         ],
     ];
     

   • Custom Notifications: Extend Ticketit\Notifications\TicketNotification to override templates or channels.

4. API Endpoints

   • Resource Controller: Generate a controller via:

     php artisan make:controller TicketController --resource --model=Ticket
     

     Use Ticketit\Http\Requests\StoreTicketRequest for validation.

Advanced Patterns

1. Custom Fields

   • Add a morphTo relationship to a TicketCustomField table:

     class Ticket extends Model {
         public function customFields() {
             return $this->morphMany(TicketCustomField::class, 'fieldable');
         }
     }
     

   • Use the Ticketit\Concerns\HasCustomFields trait for dynamic field handling.

2. Search & Filtering

   • Scope Tickets:

     class TicketScope {
         public function byPriority($query, $priority) {
             return $query->where('priority', $priority);
         }
     }
     

     Register in TicketitServiceProvider:

     Ticket::addGlobalScope(new \App\Scopes\TicketScope);
     

3. Webhooks

   • Dispatch events to external services:

     event(new \Ticketit\Events\TicketUpdated($ticket));
     

     Use laravel-webhooks to trigger HTTP calls on events.

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If using Laravel 8+, manually adjust the 2017_01_01_000000_create_tickets_table.php migration for schema changes (e.g., timestamps vs. created_at/updated_at).
   • Fix: Override the migration in database/migrations or use Schema::defaultStringLength(191).

2. Auth Integration

   • Issue: Ticketit assumes User model is App\User. If using a custom model (e.g., App\Models\User), update:

     config(['ticketit.user_model' => App\Models\User::class]);
     

   • Tip: Extend Ticketit\TicketitUserProvider to support custom user models.

3. Permission Gaps

   • Gotcha: Default policies may not cover all use cases (e.g., "delete tickets").
   • Fix: Publish and extend the policy file:

     php artisan vendor:publish --tag=ticketit-policies
     

4. Blade Directives

   • Issue: @ticketList or @ticketView may fail if the Ticketit\TicketitBlade service provider isn’t registered.
   • Fix: Add to config/app.php under providers:

     Ticketit\TicketitBladeServiceProvider::class,
     

Debugging Tips

1. Log Events

   • Enable event logging in config/ticketit.php:

     'log_events' => true,
     

   • Check storage/logs/laravel.log for event payloads.

2. SQL Queries

   • Use Laravel Debugbar to inspect ticket queries. Common slow queries involve:
     • tickets table joins with users and statuses.
     • Optimization: Add indexes:

       Schema::table('tickets', function (Blueprint $table) {
           $table->index(['status', 'priority']);
       });
       

3. Testing

   • Factories: Use the TicketitTicketFactory:

     $ticket = TicketitTicket::new()->create();
     

   • Assertions: Extend Ticketit\Tests\TestCase for helper methods like assertTicketStatus().

Extension Points

1. Custom Statuses/Priorities

   • Override the ticket_statuses and ticket_priorities arrays in config/ticketit.php:

     'ticket_statuses' => [
         'backlog' => 'Backlog',
         'in_progress' => 'In Progress',
     ],
     

   • Dynamic Loading: Use a Status model with polymorphic relationships.

2. Attachment Handling

   • Extend the Ticket model to support attachments via spatie/laravel-medialibrary:

     use Spatie\MediaLibrary\HasMedia;
     use Spatie\MediaLibrary\InteractsWithMedia;
     
     class Ticket extends Model implements HasMedia {
         use InteractsWithMedia;
     }
     

3. API Resources

   • Customize the default TicketResource:

     php artisan make:resource CustomTicketResource --from=Ticket
     

     Override fields in toArray():

     public function toArray($request) {
         return [
             'id' => $this->id,
             'title_truncated' => Str::limit($this->title, 50),
             // ...
         ];
     }
     

4. Localization

   • Publish language files:

     php artisan vendor:publish --tag=ticketit-lang
     

   • Override translations in resources/lang/en/ticketit.php:

     return [
         'ticket_status_open' => 'Open Ticket',
     ];