Ticketit Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require kordy/ticketit
   php artisan vendor:publish --provider="Kordy\Ticketit\TicketitServiceProvider"
   php artisan migrate
   php artisan ticketit:install
   

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

2. First Use Case: Creating a Ticket

   • Publish the package views:

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

   • Add the ticket creation route in routes/web.php:

     Route::get('/create-ticket', 'TicketitController@create')->name('ticketit.create');
     Route::post('/create-ticket', 'TicketitController@store')->name('ticketit.store');
     

   • Use the provided Blade directives in your views:

     @ticketit
     

Implementation Patterns

Core Workflows

1. Ticket Creation & Management

   • User Flow: Users create tickets via a form (published views include create.blade.php and show.blade.php).
   • Agent Flow: Agents access tickets via Route::get('/agent/tickets', 'AgentController@index').
   • Admin Flow: Admins manage roles, departments, and statistics via Route::get('/admin/ticketit', 'AdminController@index').

2. Auto-Assignment Logic

   • Configure departments and agent assignments in config/ticketit.php:

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

   • Use the assignToLeastBusyAgent() method in custom logic:

     $ticket->assignToLeastBusyAgent('technical');
     

3. Localization

   • Load language packs via config/app.php:

     'locale' => 'en', // or 'ar', 'pt_BR', etc.
     

   • Translate strings in Blade:

     {{ __('ticketit::messages.ticket_created') }}
     

4. Dashboard Integration

   • Extend the admin dashboard with custom widgets:

     // In a service provider
     Event::listen('ticketit.admin.dashboard', function ($dashboard) {
         $dashboard->addWidget(new \Kordy\Ticketit\Widgets\CustomWidget());
     });
     

5. Text Editor & Attachments

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

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

   • Handle file uploads via the UploadController (published routes include /upload).

Gotchas and Tips

Pitfalls

1. Archived Package Risks

   • No active maintenance; avoid for production-critical systems. Consider forks like laravel-ticketit or alternatives (e.g., Laravel Helpdesk, SupportPal).
   • Mitigation: Override core logic in a service provider to future-proof customizations.

2. Role/Department Mismatches

   • Auto-assignment fails if agents lack department access. Verify config/ticketit.php mappings:

     'departments' => [
         'tech' => ['agents' => [1, 2]], // Ensure agent IDs exist in `users` table.
     ],
     

   • Debug with:

     dd(\Kordy\Ticketit\Models\Department::with('agents')->get());
     

3. Migration Conflicts

   • Package migrations may clash with existing users or roles tables. Run:

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

     Then manually merge changes (e.g., ticketit_users pivot table).

4. CKEditor Uploads

   • Uploads require a symlink to storage/app/public:

     php artisan storage:link
     

   • Ensure config/filesystems.php has:

     'disks' => [
         'public' => [
             'url' => env('APP_URL').'/storage',
             'visibility' => 'public',
         ],
     ],
     

5. Localization Caching

   • Clear views after language changes:

     php artisan view:clear
     php artisan cache:clear
     

Debugging Tips

1. Log Auto-Assignment Add to app/Providers/AppServiceProvider.php:

   public function boot()
   {
       \Kordy\Ticketit\Events\TicketAssigned::listen(function ($event) {
           \Log::info('Ticket assigned', ['ticket' => $event->ticket, 'agent' => $event->agent]);
       });
   }
   

2. Override Assignment Logic Extend the AssignToLeastBusyAgent trait:

   namespace App\Extensions;
   
   use Kordy\Ticketit\Traits\AssignToLeastBusyAgent as BaseTrait;
   
   trait CustomAssignToLeastBusyAgent
   {
       use BaseTrait;
   
       protected function getLeastBusyAgent($department)
       {
           // Custom logic here
           return parent::getLeastBusyAgent($department);
       }
   }
   

3. Test Routes Use php artisan route:list | grep ticketit to verify published routes. Common missing routes:

   • /agent/tickets
   • /admin/ticketit

Extension Points

1. Custom Fields Extend the Ticket model:

   namespace App;
   
   use Kordy\Ticketit\Models\Ticket as BaseTicket;
   
   class Ticket extends BaseTicket
   {
       protected $casts = [
           'priority' => 'integer', // Example custom field
       ];
   }
   

2. Webhooks Listen for ticket events:

   \Kordy\Ticketit\Events\TicketCreated::listen(function ($event) {
       // Send Slack/email notification
   });
   

3. API Endpoints Use Laravel’s API resources to expose tickets:

   Route::apiResource('tickets', 'TicketApiController');
   

   namespace App\Http\Controllers;
   
   use Kordy\Ticketit\Models\Ticket;
   use App\Http\Resources\TicketResource;
   
   class TicketApiController extends Controller
   {
       public function index()
       {
           return TicketResource::collection(Ticket::all());
       }
   }