Ticketit Laravel Package

Getting Started

Minimal Steps to First Use

1. Install via Composer

   composer require juanrube/ticketit
   

   Run migrations and publish assets:

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

2. Configure Routes Add Ticketit routes in routes/web.php:

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

3. Set Up Middleware Ensure auth middleware is applied to Ticketit routes (default in published config).

4. First Ticket Creation

   • Log in as a user (default role).
   • Navigate to /tickets/create.
   • Fill in subject, description, and select a department.
   • Submit to generate a ticket.

Where to Look First

• Admin Panel: /tickets/admin – Overview of tickets, agents, and stats.
• User Dashboard: /tickets – View, comment, and manage personal tickets.
• Agent Workflow: /tickets/agent – Assign, resolve, and reply to tickets.
• Config File: config/ticketit.php – Adjust roles, permissions, and auto-assignment rules.

First Use Case: User Submits a Ticket

1. User logs in via Laravel’s default auth.
2. Clicks "New Ticket" in the Ticketit sidebar.
3. Selects a department (e.g., "Technical Support").
4. Writes a description (supports Markdown and image uploads).
5. Submits → Ticket is auto-assigned to the least busy agent in the department.
6. User receives a confirmation email (configurable template).

Implementation Patterns

Core Workflows

1. Role-Based Access

• Users: Create/manage their own tickets.

  // Check if current user is a user (not agent/admin)
  if (auth()->user()->hasRole('user')) {
      $tickets = \JuanRube\Ticketit\Models\Ticket::where('user_id', auth()->id())->get();
  }
  

• Agents: Assign, reply, and resolve tickets.

  // Assign ticket to self
  $ticket->assignTo(auth()->id());
  

• Admins: Override assignments, manage departments/agents, and view stats.

  // Force-reassign a ticket
  $ticket->forceAssignTo($agentId);
  

2. Auto-Assignment Logic

• Configure in config/ticketit.php:

  'auto_assign' => [
      'enabled' => true,
      'department_field' => 'department_id',
      'agent_selection' => 'least_busy', // or 'random'
  ],
  

• Extend logic via service provider:

  // Override agent selection
  Ticketit::extend(function ($ticket) {
      return \JuanRube\Ticketit\Models\Agent::where('department_id', $ticket->department_id)
          ->orderBy('last_assigned_at', 'asc')
          ->first();
  });
  

3. Ticket Lifecycle

• States: open, pending, resolved, closed.
• Transition states with methods:

  $ticket->resolve(); // Marks as resolved
  $ticket->close();  // Finalizes ticket
  

• Listen for state changes:

  \JuanRube\Ticketit\Models\Ticket::resolved(function ($ticket) {
      // Send notification
  });
  

4. Localization

• Switch languages via middleware or config:

  // In AppServiceProvider
  \JuanRube\Ticketit\Facades\Ticketit::setLocale('es');
  

• Add custom translations:

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

  Edit resources/lang/vendor/ticketit/.

Integration Tips

Laravel Notifications

• Extend Ticketit’s email notifications:

  // Override notification template
  \JuanRube\Ticketit\Mail\TicketCreated::createUrlUsing(function ($ticket) {
      return route('tickets.show', $ticket->id);
  });
  

API Endpoints

• Expose Ticketit via API (e.g., for mobile apps):

  Route::middleware('auth:sanctum')->group(function () {
      Route::apiResource('tickets', \JuanRube\Ticketit\Http\Controllers\Api\TicketController::class);
  });
  

Custom Fields

• Add metadata to tickets via ticket_metadata table:

  $ticket->metadata()->create([
      'key' => 'priority',
      'value' => 'high',
  ]);
  

Department-Specific Rules

• Dynamically assign departments based on user attributes:

  // In TicketitServiceProvider
  Ticketit::macro('getUserDepartment', function ($user) {
      return $user->company->support_department_id;
  });
  

Gotchas and Tips

Pitfalls

1. Role Conflicts

   • Ensure can() checks align with hasRole():

     // ❌ Avoid hardcoding roles
     if (auth()->user()->role === 'admin') { ... }
     
     // ✅ Use Ticketit’s permission system
     if (auth()->user()->can('manage_tickets')) { ... }
     

   • Fix: Re-run php artisan ticketit:permissions if roles are misconfigured.

2. Auto-Assignment Failures

   • If no agent is assigned, check:
     • config/ticketit.php → 'auto_assign' => ['enabled' => true].
     • Department has active agents:

       SELECT * FROM agents WHERE department_id = ? AND active = 1;
       

   • Fix: Manually assign or adjust agent_selection logic.

3. Email Configuration

   • Ticketit uses Laravel’s default mail driver. Verify .env:

     MAIL_MAILER=smtp
     MAIL_FROM_ADDRESS="support@yourdomain.com"
     

   • Tip: Test emails with php artisan ticketit:test-email.

4. Asset Publishing

   • Forgetting to publish assets causes JS/CSS 404s:

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

   • Fix: Clear cached views:

     php artisan view:clear
     

Debugging

1. Log Auto-Assignment

   • Enable debug mode in config/ticketit.php:

     'debug' => [
         'log_auto_assign' => true,
     ],
     

   • Check logs in storage/logs/laravel.log.

2. Ticket State Transitions

   • Use dd($ticket->fresh()) to inspect state after actions like resolve().
   • Common Issue: Stuck in pending state due to validation errors in comments.

3. Middleware Conflicts

   • If routes return 403, verify:
     • auth middleware is applied.
     • User has the correct role (check users table role column).

Extension Points

1. Custom Ticket Actions

   • Add buttons to tickets via view composers:

     // In AppServiceProvider
     View::composer('ticketit::ticket.show', function ($view) {
         $view->with('customActions', [
             'escalate' => route('tickets.escalate', $ticket->id),
         ]);
     });
     

2. Override Views

   • Publish and modify templates:

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

   • Edit files in resources/views/vendor/ticketit/.

3. Hooks for Business Logic

   • Use events:

     // In EventServiceProvider
     public function boot() {
         \JuanRube\Ticketit\Models\Ticket::created(function ($ticket) {
             // Trigger Slack notification
         });
     }
     

   • Available events:
     • TicketCreated
     • TicketAssigned
     • TicketResolved
     • TicketClosed

4. Custom Departments

   • Extend the departments table or use a many-to-many relationship:

     // Add to User model
     public function departments() {
         return $this->belongsToMany(Department::class, 'user_departments');
     }
     

Configuration Quirks

1. Default Role Assignment

   • New users default to 'user' role. Override in AppServiceProvider:

     use JuanRube\Ticketit\Models\User;
     
     User::created(function ($user) {
         $user->role = 'agent'; // Force role
         $user->save();
     });
     

2. File Uploads

   • Ensure public/uploads/ticketit is writable: