Ticketit Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation via Composer

   composer require roboticsexpert/ticketit
   

   Run migrations:

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

2. Publish Assets & Config

   php artisan vendor:publish --provider="Ticketit\TicketitServiceProvider" --tag=config
   php artisan vendor:publish --provider="Ticketit\TicketitServiceProvider" --tag=public
   php artisan vendor:publish --provider="Ticketit\TicketitServiceProvider" --tag=views
   

3. Add Routes Include Ticketit routes in routes/web.php:

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

4. First Use Case

   • User: Log in as a user → Navigate to /tickets → Create a ticket with a subject, description, and optional attachments.
   • Agent: Log in as an agent → View assigned tickets in /tickets → Reply to tickets or update status.

Implementation Patterns

Core Workflows

1. Ticket Creation & Management

   • Users create tickets via a form with fields like subject, description, and priority.
   • Use Ticketit\Ticket facade or inject Ticketit\Repositories\TicketRepository for programmatic access:

     use Ticketit\Facades\Ticket;
     $ticket = Ticket::create(['subject' => 'Issue', 'user_id' => auth()->id()]);
     

2. Auto-Assignment Logic

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

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

   • Agents are auto-assigned based on lowest ticket queue (configurable via queue_weight in config).

3. Role-Based Permissions

   • Extend default roles (user, agent, admin) via middleware or policy bindings:

     // app/Providers/AuthServiceProvider.php
     Gate::define('close-ticket', function ($user) {
         return $user->role === 'admin' || $user->role === 'agent';
     });
     

4. Localization & UI

   • Switch languages via config/ticketit.php:

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

   • Customize views in resources/views/vendor/ticketit/.

5. Admin Dashboard

   • Access at /admin/tickets. Use the built-in stats graphs or extend with custom queries:

     $recentTickets = Ticket::with('user', 'agent')->latest()->take(10)->get();
     

6. Attachments & Rich Text

   • Upload images via the WYSIWYG editor (TinyMCE). Handle uploads in storage/app/public/ticketit/attachments.

Gotchas and Tips

Pitfalls & Debugging

1. Migration Conflicts

   • If users table lacks role column, add it manually or extend the users table migration:

     Schema::table('users', function (Blueprint $table) {
         $table->string('role')->default('user');
     });
     

2. Auto-Assignment Failures

   • Ensure departments and agents are properly configured in config/ticketit.php. Verify agent IDs exist in the users table.
   • Debug with:

     \Log::info('Departments config:', config('ticketit.departments'));
     

3. Permission Denied Errors

   • Check middleware in app/Http/Kernel.php for auth and role checks. Example:

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

4. Localization Issues

   • Publish language files first:

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

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

5. Attachment Paths

   • Ensure storage/app/public/ticketit/attachments is writable:

     mkdir -p storage/app/public/ticketit/attachments
     chmod -R 775 storage/app/public/ticketit
     

   • Symlink the directory:

     php artisan storage:link
     

Extension Points

1. Custom Ticket Fields

   • Extend the tickets table via a migration, then update the Ticket model:

     protected $fillable = ['subject', 'description', 'user_id', 'custom_field'];
     

2. Event Listeners

   • Listen to ticket events (e.g., TicketCreated) in EventServiceProvider:

     protected $listen = [
         'Ticketit\Events\TicketCreated' => [
             'App\Listeners\SendTicketNotification',
         ],
     ];
     

3. API Integration

   • Use Laravel’s API resources to expose tickets:

     Route::middleware('auth:api')->get('/tickets', 'TicketController@index');
     

   • Example controller:

     public function index() {
         return TicketResource::collection(Ticket::where('user_id', auth()->id())->get());
     }
     

4. Customizing Views

   • Override default views by copying from vendor/roboticsexpert/ticketit/resources/views to resources/views/vendor/ticketit.

5. Testing

   • Use Laravel’s testing helpers to assert ticket states:

     $ticket = factory(Ticketit\Ticket::class)->create(['user_id' => $user->id]);
     $this->assertEquals('open', $ticket->status);
     

Config Quirks

• Queue Weight: Adjust queue_weight in config/ticketit.php to balance agent workloads (lower = higher priority).
• Default Roles: Ensure role column in users table matches config/ticketit.roles (e.g., ['user', 'agent', 'admin']).
• Email Notifications: Configure ticketit.notifications in config/ticketit.php to enable/disable emails for ticket events.