Ticketit Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

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

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

2. Configure Routes Add to routes/web.php:

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

3. First Ticket Creation

   • Log in as a user (or admin/agent).
   • Navigate to /tickets/create to open the ticket form.
   • Fill in subject, description (supports Markdown), and submit.

4. Admin Panel Access /admin/tickets to manage tickets, agents, and departments.

Implementation Patterns

Core Workflows

1. Ticket Lifecycle

   • User: Creates → Updates → Closes (if permitted).
   • Agent: Assigns → Replies → Resolves (via /tickets/{id}/reply).
   • Admin: Bulk actions (e.g., /admin/tickets/mark-as-read).

2. Auto-Assignment Logic

   • Configure departments in config/ticketit.php:

     'departments' => [
         'technical' => ['agents' => ['agent1@example.com']],
         'billing'   => ['agents' => ['agent2@example.com']],
     ],
     

   • Agents with the lowest ticket queue are auto-assigned when a user selects a department.

3. Localization

   • Set locale in config/app.php (e.g., 'locale' => 'fr').
   • Language files are in resources/lang/vendor/ticketit.

4. Permissions

   • Use middleware (auth:agent, auth:admin) to restrict routes:

     Route::middleware(['auth:agent'])->group(function () {
         Route::get('/agent/dashboard', 'AgentController@dashboard');
     });
     

5. Customizing Views

   • Override default Blade templates in resources/views/vendor/ticketit/.
   • Example: Copy resources/views/vendor/ticketit/tickets/create.blade.php to your project.

6. Extending Models

   • Publish migrations (php artisan vendor:publish --tag=ticketit-migrations) to add custom fields to tickets or users tables.
   • Example: Add a priority column to tickets table.

7. Event Listeners

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

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

8. API Integration (Optional)

   • Use Laravel’s API resources to expose ticket data:

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

Gotchas and Tips

Pitfalls

1. Role Conflicts

   • Ensure users are assigned only one role (user/agent/admin) to avoid permission issues.
   • Debug with php artisan ticketit:roles to check assignments.

2. Auto-Assignment Failures

   • If no agent is assigned, verify:
     • Departments are correctly configured in config/ticketit.php.
     • Agents exist in the users table with the agent role.
     • No agent has a ticketit_last_assigned_at timestamp in the future.

3. Localization Caching

   • Clear view cache after adding new language files:

     php artisan view:clear
     

4. File Uploads

   • Ticket descriptions support image uploads via laravel-filemanager. Ensure:
     • The package is installed (composer require unclead/laravel-filemanager).
     • Storage is linked (php artisan storage:link).

5. Middleware Overrides

   • If using custom guards (e.g., Sanctum), update middleware in app/Http/Kernel.php:

     'auth:agent' => \YuraPyzyk\Ticketit\Http\Middleware\AuthenticateAgent::class,
     

6. Database Seeding

   • Avoid running php artisan migrate:fresh if you’ve manually added data (e.g., custom agents). Use --seed carefully:

     php artisan migrate:fresh --seed  # Resets everything!
     

Debugging Tips

1. Log Auto-Assignment Add to config/ticketit.php:

   'debug' => true,  // Logs assignment logic to Laravel logs.
   

2. Check Queue Metrics Run this SQL to verify agent workloads:

   SELECT user_id, COUNT(*) as ticket_count
   FROM tickets
   WHERE assigned_to IS NOT NULL
   GROUP BY user_id;
   

3. Common Errors

   • 403 Forbidden: Missing middleware or role. Verify can() checks in controllers.
   • Missing Translation: Publish language files:

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

Extension Points

1. Custom Fields

   • Add columns to tickets table via migrations, then extend the Ticket model:

     public function getPriorityAttribute()
     {
         return $this->attributes['priority'] ?? 'medium';
     }
     

2. Hooks for Business Logic

   • Override TicketitServiceProvider to bind interfaces:

     $this->app->bind(
         YuraPyzyk\Ticketit\Contracts\TicketAssigner::class,
         App\Services\CustomTicketAssigner::class
     );
     

3. Webhooks

   • Trigger external actions on ticket events (e.g., Slack notifications):

     // In EventServiceProvider
     'YuraPyzyk\Ticketit\Events\TicketUpdated' => [
         'App\Listeners\SlackNotification',
     ],
     

4. Testing

   • Use TicketitTestCase for unit tests:

     use YuraPyzyk\Ticketit\Tests\TestCase;
     class TicketTest extends TestCase {
         public function testCreateTicket() { ... }
     }