Appbajarticket Laravel Package

Getting Started

Minimal Setup Steps

1. Installation

   composer require mhshohel/appbajarticket
   

   Note: Verify the package is compatible with Laravel 5.1 (original ticketit was built for this version).

2. Publish Configuration & Migrations

   php artisan vendor:publish --provider="AppBajarTicket\Providers\AppBajarTicketServiceProvider"
   php artisan migrate
   

3. Add Middleware & Routes In app/Http/Kernel.php, add:

   'ticket' => \AppBajarTicket\Http\Middleware\TicketMiddleware::class,
   

   Include routes in routes/web.php:

   Route::group(['middleware' => 'web', 'prefix' => 'ticket'], function () {
       require __DIR__ . '/ticket-routes.php';
   });
   

4. First Use Case

   • User Flow: Register a user (Laravel default auth) → Log in → Navigate to /ticket → Create a ticket.
   • Agent Flow: Assign an agent role → Log in → View /ticket/agent → Accept/respond to tickets.
   • Admin Flow: Assign admin role → Log in → Access /ticket/admin → Manage departments, roles, or stats.

Implementation Patterns

Core Workflows

1. Ticket Creation

   // User creates a ticket (via form submission)
   $ticket = \AppBajarTicket\Models\Ticket::create([
       'user_id' => auth()->id(),
       'subject' => $request->subject,
       'message' => $request->message,
       'department_id' => $request->department_id,
   ]);
   

   • Auto-assignment: Configure config/ticketit.php:

     'auto_assign' => true,
     'assign_to_least_busy' => true,
     

2. Agent Assignment & Notifications

   • Use the assignToAgent() method:

     $ticket->assignToAgent($agentId);
     

   • Trigger email notifications via Laravel’s events (extend AppBajarTicket\Events\TicketAssigned).

3. Role-Based Permissions

   • Extend Laravel’s gates/policies:

     Gate::define('close-ticket', function ($user, $ticket) {
         return $user->isAgent() && $ticket->agent_id === $user->id;
     });
     

4. Department Integration

   • Link tickets to departments (e.g., Billing, Technical):

     $ticket->department()->attach($departmentId);
     

   • Filter tickets by department in agent dashboard:

     $tickets = Ticket::whereHas('department', function($q) {
         $q->where('name', 'Technical');
     })->get();
     

5. Localization

   • Switch languages via middleware or config:

     // config/app.php
     'locale' => 'hu', // Hungarian
     

   • Override translations in resources/lang/vendor/ticketit/.

Integration Tips

• Laravel Notifications: Replace default emails with via() channels:

  use AppBajarTicket\Notifications\TicketAssignedNotification;
  
  TicketAssignedNotification::create($ticket)
      ->route('mail', $agent->email)
      ->send();
  

• API Endpoints: Use Laravel’s API resources:

  Route::apiResource('tickets', 'TicketController')->middleware('auth:api');
  

• Custom Fields: Extend the Ticket model:

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

Gotchas and Tips

Pitfalls

1. Laravel 5.1 Dependency

   • Issue: Package assumes Laravel 5.1 (e.g., Route::controller() syntax, Auth::user()).
   • Fix: Use compatibility layers or fork the package if upgrading Laravel.
   • Tip: Check composer.json for laravel/framework version constraints.

2. Migration Conflicts

   • Issue: Custom users table structure (e.g., role column) may clash with migrations.
   • Fix: Dump migrations before running:

     php artisan migrate --pretend
     

   • Tip: Override migrations in database/migrations/ if needed.

3. Auto-Assignment Logic

   • Issue: assign_to_least_busy may not work as expected with custom agent workloads.
   • Fix: Extend the Agent model:

     public function getQueueLengthAttribute()
     {
         return $this->tickets()->where('status', 'open')->count();
     }
     

   • Tip: Cache queue lengths with Laravel’s cache:

     Cache::remember("agent_{$this->id}_queue", 60, function() {
         return $this->queue_length;
     });
     

4. Permission Overrides

   • Issue: Default role permissions (e.g., users closing tickets) may not fit your workflow.
   • Fix: Override gates in AuthServiceProvider:

     Gate::before(function ($user) {
         if ($user->isAdmin()) {
             return true; // Bypass all gates
         }
     });
     

5. Email Configuration

   • Issue: Default email templates may not match your brand.
   • Fix: Override views in resources/views/vendor/ticketit/emails/.

Debugging

• Ticket Not Auto-Assigned:
  • Check config/ticketit.php for auto_assign and assign_to_least_busy.
  • Log agent queue lengths:

    \Log::debug('Agent queues:', [
        'agents' => \AppBajarTicket\Models\Agent::withCount('tickets as open_tickets')
            ->whereHas('tickets', function($q) {
                $q->where('status', 'open');
            })
            ->get()
    ]);
    

• Permission Denied:
  • Verify roles in users table (role column) and middleware:

    Route::middleware(['auth', 'role:agent'])->group(function () {
        // Agent-only routes
    });
    

Extension Points

1. Custom Ticket Statuses

   • Extend the status field in migrations and add logic to Ticket model:

     const STATUS_PENDING = 'pending';
     const STATUS_REVIEW = 'review';
     

   • Update the status dropdown in views (resources/views/ticketit/partials/status.blade.php).

2. Webhooks for External Systems

   • Listen to ticket.created events:

     Event::listen('ticket.created', function ($ticket) {
         // Send webhook to Slack/Teams
         Http::post('https://hooks.slack.com/...', [
             'text' => "New ticket #{$ticket->id} created"
         ]);
     });
     

3. Sentry/Error Tracking

   • Log ticket-related errors:

     try {
         $ticket->assignToAgent($agentId);
     } catch (\Exception $e) {
         \Sentry\captureException($e, [
             'ticket_id' => $ticket->id,
             'agent_id' => $agentId,
         ]);
     }
     

4. Testing

   • Use Laravel’s testing helpers:

     $this->actingAs($user)
          ->post('/ticket', [
              'subject' => 'Test',
              'message' => 'Hello',
          ])
          ->assertRedirect('/ticket');
     

   • Mock auto-assignment:

     $agent = create('AppBajarTicket\Models\Agent');
     \AppBajarTicket\Services\TicketAssigner::shouldReceive('assign')
         ->once()
         ->andReturn($agent);