Ticketit Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

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

   • Run php artisan ticketit:install to seed default roles (users, agents, admins) and departments.

2. Configure Routes Add to routes/web.php:

   Route::middleware(['auth'])->group(function () {
       Route::prefix('ticketit')->group(function () {
           require __DIR__.'/ticketit.php';
       });
   });
   

3. First Ticket Creation

   • Log in as a user (or admin/agent).
   • Navigate to /ticketit/tickets/create.
   • Fill in the form (title, description, department) and submit.

4. Key Files to Review

   • config/ticketit.php (core settings like roles, permissions, and auto-assignment logic).
   • resources/views/vendor/ticketit/ (customize blades if needed).
   • app/Providers/TicketitServiceProvider.php (service binding overrides).

Implementation Patterns

Core Workflows

1. Ticket Lifecycle

   • Creation: Users submit tickets via TicketController@create (form + Ticket model).
   • Assignment: Auto-assigned to agents via TicketObserver (lowest queue logic in TicketitService::assignTicket()).
   • Updates: Agents/users add comments via CommentController (rich text + attachments via TicketitService::uploadImage()).
   • Resolution: Admins/agents close tickets via TicketController@close (triggers TicketClosed event).

2. Role-Based Permissions

   • Use can() gates (e.g., auth()->user()->can('close_ticket')) to restrict actions.
   • Extend via TicketitServiceProvider::boot():

     Gate::define('close_ticket', function ($user) {
         return $user->isAdmin() || $user->isAgent();
     });
     

3. Auto-Assignment Logic

   • Customize department-agent mapping in config/ticketit.php:

     'departments' => [
         'technical' => ['agents' => [1, 3]], // Agent IDs
     ],
     

   • Override assignment logic by extending Saadzer\Ticketit\Services\TicketitService.

4. Localization

   • Load language packs via config/app.php:

     'locale' => 'fr', // e.g., for French
     

   • Add custom translations in resources/lang/{locale}/ticketit.php.

5. Dashboard Integration

   • Fetch stats via TicketitService::getDashboardStats():

     $stats = app(Saadzer\Ticketit\Services\TicketitService::class)->getDashboardStats();
     

   • Display in a blade view:

     @foreach($stats['ticketCounts'] as $status => $count)
         <div>{{ $status }}: {{ $count }}</div>
     @endforeach
     

6. Rich Text Editor

   • Use the built-in CKEditor (configured in config/ticketit.php):

     'editor' => [
         'enabled' => true,
         'config' => [
             'filebrowserUploadUrl' => route('ticketit.upload'),
         ],
     ],
     

   • Handle uploads via UploadController@upload.

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If using Laravel 8+, run php artisan vendor:publish --tag=ticketit-migrations to update migrations.
   • Fix: Manually resolve column conflicts (e.g., updated_at timestamps) in database/migrations/.

2. Auto-Assignment Failures

   • If no agent is assigned, check:
     • config/ticketit.php for valid departments and agents.
     • Agent status (ensure agents have is_active = 1 in users table).
   • Debug: Override TicketitService::assignTicket() to log unassigned tickets.

3. Permission Denied Errors

   • Default gates may block actions. Verify:
     • User roles (isAdmin(), isAgent()) in User model.
     • Middleware in routes/web.php (e.g., auth + role:admin).
   • Tip: Use php artisan ticketit:permissions to regenerate gates.

4. Editor Uploads Not Working

   • Ensure storage/app/public is writable and symlinked:

     php artisan storage:link
     

   • Verify filebrowserUploadUrl in config/ticketit.php matches your UploadController route.

5. Localization Issues

   • Missing translations? Check:
     • Language files exist in vendor/saadzer/ticketit/resources/lang/{locale}.
     • config/app.php has the correct locale.
   • Fix: Publish language files:

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

Debugging Tips

1. Log Auto-Assignment Add to TicketitService.php:

   Log::debug('Available agents for dept X:', [$agents]);
   

2. Check Queue Logic Override getAgentWithLowestQueue() to log queue counts:

   public function getAgentWithLowestQueue($department) {
       $queues = $this->getAgentQueues($department);
       Log::debug('Agent queues:', $queues);
       return array_reduce($queues, fn($carry, $item) => $item['count'] < $carry['count'] ? $item : $carry);
   }
   

3. Test Permissions Use Tinker to verify gates:

   php artisan tinker
   >>> auth()->user()->can('close_ticket')
   

Extension Points

1. Custom Ticket Fields

   • Extend the Ticket model:

     class Ticket extends \Saadzer\Ticketit\Models\Ticket {
         protected $casts = [
             'priority' => 'integer',
         ];
     }
     

   • Add fields to the migration and form (override resources/views/vendor/ticketit/tickets/form.blade.php).

2. Custom Assignment Logic

   • Override TicketitService:

     class CustomTicketitService extends \Saadzer\Ticketit\Services\TicketitService {
         public function assignTicket($ticket) {
             // Custom logic (e.g., round-robin)
             $agent = $this->getNextAgentInRoundRobin($ticket->department);
             $ticket->agent_id = $agent->id;
             $ticket->save();
         }
     }
     

   • Bind in TicketitServiceProvider:

     $this->app->bind(
         \Saadzer\Ticketit\Services\TicketitService::class,
         CustomTicketitService::class
     );
     

3. Webhooks for External Systems

   • Listen to TicketClosed events in EventServiceProvider:

     protected $listen = [
         \Saadzer\Ticketit\Events\TicketClosed::class => [
             \App\Listeners\SendSlackNotification::class,
         ],
     ];
     

4. API Endpoints

   • Expose ticket data via TicketController:

     Route::middleware('auth:api')->get('/ticketit/tickets', [TicketController::class, 'apiIndex']);
     

   • Return JSON responses:

     public function apiIndex() {
         return Ticket::with('comments', 'agent')->get();
     }