Ticketit Laravel Package

Getting Started

Minimal Setup Steps

1. Install via Composer

   composer require umark1142/ticketit
   

   (Note: Despite being archived, the package remains functional for Laravel 5.1–8.x.)

2. Publish Assets & Config

   php artisan vendor:publish --provider="Ticketit\TicketitServiceProvider"
   

   • Publishes migrations, views, and config to config/ticketit.php and resources/views/vendor/ticketit/.

3. Run Migrations

   php artisan migrate
   

   • Creates tables for tickets, agents, departments, and roles.

4. Register Routes Add to routes/web.php:

   Route::prefix('ticketit')->group(function () {
       require __DIR__.'/vendor/ticketit/routes.php';
   });
   

5. Assign Roles Use the Ticketit\Ticketit facade to assign roles to users:

   use Ticketit\Facades\Ticketit;
   
   // Assign 'agent' role to a user
   Ticketit::assignRoleToUser($userId, 'agent');
   

6. First Ticket Test

   • Log in as a user (default role: user).
   • Navigate to /ticketit/tickets/create to submit a test ticket.

Where to Look First

• Config File: config/ticketit.php – Adjust department settings, auto-assignment rules, and permissions.
• Blade Views: resources/views/vendor/ticketit/ – Customize UI (e.g., tickets/index.blade.php).
• Facade Methods: Ticketit:: – Core functionality (e.g., Ticketit::createTicket(), Ticketit::assignAgent()).
• Middleware: Ticketit\Middleware\CheckRole – Restrict routes by role (e.g., agents only).

First Use Case: Auto-Assigning Agents

1. Configure Departments:

   // config/ticketit.php
   'departments' => [
       'technical' => ['agents' => [1, 2]], // User IDs
       'billing'   => ['agents' => [3]],
   ],
   

2. Trigger Auto-Assignment:

   $ticket = Ticketit::createTicket($userId, [
       'title' => 'Issue with login',
       'department' => 'technical',
   ]);
   // Auto-assigns agent with lowest queue in 'technical' department.
   

Implementation Patterns

Core Workflows

1. Ticket Creation & Lifecycle

• User Flow:

  // Create ticket via facade
  $ticket = Ticketit::createTicket($userId, [
      'title' => 'API Error',
      'description' => '404 on /endpoint',
      'department' => 'technical',
  ]);
  

  • Attach files via Ticketit::attachFileToTicket($ticketId, $filePath).
• Agent Flow:

  // Reply to ticket
  Ticketit::addComment($ticketId, $agentId, 'Debugging...');
  // Close ticket
  Ticketit::closeTicket($ticketId, $agentId);
  

2. Role-Based Permissions

• Middleware Integration:

  Route::get('/admin/dashboard', function () {
      // ...
  })->middleware(['auth', 'ticketit.role:admin']);
  

• Dynamic Role Assignment:

  // Bulk assign roles
  Ticketit::assignRoleToUsers([1, 2, 3], 'agent');
  

3. Auto-Assignment Logic

• Customize Assignment Rules:

  // Override default assignment in config/ticketit.php
  'auto_assign' => [
      'strategy' => 'least_busy', // or 'round_robin'
      'fallback_agent' => 1,       // ID if no agent available
  ],
  

• Manual Override:

  Ticketit::assignAgent($ticketId, $agentId);
  

4. Localization

• Switch Language:

  app()->setLocale('fr'); // French
  

• Add Custom Translations: Publish lang files:

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

  Then extend resources/lang/vendor/ticketit/.

Integration Tips

Laravel Ecosystem

• Notifications: Extend Ticketit\Events\TicketCreated to trigger Slack/email alerts:

  Event::listen(TicketitEvents::TICKET_CREATED, function ($event) {
      Notification::route('mail', $event->ticket->agent->email)
                  ->notify(new TicketAssigned($event->ticket));
  });
  

• Queues: Offload ticket processing:

  dispatch(new AssignAgentToTicket($ticketId));
  

• APIs: Expose endpoints for frontend apps:

  Route::get('/api/tickets/{id}', 'TicketController@show')->middleware('auth:api');
  

UI Customization

• Override Blade Components:

  // resources/views/vendor/ticketit/partials/ticket-comment.blade.php
  @extends('vendor.ticketit.partials.ticket-comment')
  @section('comment-body')
      <div class="custom-style">
          {{ $comment->body }}
      </div>
  @endsection
  

• Asset Overrides: Publish CSS/JS:

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

  Then extend public/vendor/ticketit/css/ticketit.css.

Data Migration

• Seed Departments/Agents:

  // database/seeds/TicketitTableSeeder.php
  $departments = [
      ['name' => 'Technical', 'description' => 'Tech support'],
      ['name' => 'Billing', 'description' => 'Invoices'],
  ];
  DB::table('ticketit_departments')->insert($departments);
  

Gotchas and Tips

Pitfalls

1. Archived Package Risks:

   • No updates for Laravel 9+/10+. Test thoroughly if upgrading.
   • Missing PHP 8.x type hints (may require manual fixes).

2. Role Assignment Quirks:

   • Default roles (user, agent, admin) must exist in ticketit_roles table.
   • Fix: Run php artisan ticketit:install if roles are missing (if command exists).

3. Auto-Assignment Failures:

   • If no agents are assigned to a department, tickets may hang.
   • Solution: Set fallback_agent in config or validate departments before creation:

     $department = Ticketit::getDepartment('technical');
     if (!$department || empty($department->agents)) {
         throw new \Exception("No agents in department.");
     }
     

4. File Uploads:

   • Default storage is public/ticketit_uploads. Ensure symlink exists:

     php artisan storage:link
     

   • Custom Path: Override in config:

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

5. Localization Gaps:

   • Some strings may not be translated. Extend lang files or use fallbacks:

     __('ticketit::default', ['key' => 'ticket.created']);
     

Debugging Tips

1. Log Auto-Assignment: Enable debug mode in config:

   'debug' => true,
   

   Logs assignment logic to storage/logs/laravel.log.

2. Middleware Issues:

   • Clear compiled views if roles aren’t applying:

     php artisan view:clear
     

3. Database Conflicts:

   • Reset migrations if stuck:

     php artisan migrate:fresh --env=local
     

4. Queue Stuck Jobs:

   • Monitor failed_jobs table for Ticketit\Jobs\AssignAgentToTicket.

Extension Points

1. Custom Ticket Fields:

   • Extend the ticketit_tickets table via migrations, then override the Ticket model:

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

2. Event Hooks:

   • Listen for core events:

     Event::listen(TicketitEvents::TICKET_COMMENT_ADDED, function ($event) {
         // Send webhook to third-party system
     });
     

3. API Endpoints:

   • Wrap facade methods in controllers:

     class TicketController extends Controller {
         public function update(TicketUpdateRequest $request, $id) {
             $ticket = Ticketit::updateTicket($id, $request->