#Laravel Service Desk

A complete, headless Service Desk package for Laravel featuring ticket management, SLA tracking, knowledge base, service catalog with approval workflows, and multi-channel email integration.

#Features

• Ticket Management - Full lifecycle with status transitions, priorities, assignments, watchers, and auto-generated reference numbers
• SLA Management - Policies with business hours, breach detection, near-breach warnings, pause/resume, and escalation rules
• Knowledge Base - Articles with versioning, publishing workflow, full-text search, feedback collection, and SEO fields
• Service Catalog - Dynamic form builder, multi-step approval workflows, and automatic ticket creation
• Email Integration - Inbound email processing via IMAP, Mailgun, SendGrid, Resend, and Postmark
• Event-Driven - 24 domain events for extensibility
• Notifications - 10 built-in notification classes with queue support
• Translations - English and Brazilian Portuguese included
• Headless - No built-in UI; integrate with Filament, Livewire, Inertia, or any frontend

#Requirements

• PHP 8.2+
• Laravel 11.x, 12.x or 13.x

#Installation

Install the package via Composer:

composer require jeffersongoncalves/laravel-service-desk

Publish the configuration and migrations:

php artisan vendor:publish --tag="service-desk-config"
php artisan vendor:publish --tag="service-desk-migrations"

Run the migrations:

php artisan migrate

Optionally publish the translation files:

php artisan vendor:publish --tag="service-desk-translations"

#Configuration

The configuration file config/service-desk.php allows you to customize:

#Models

'models' => [
    'user' => \App\Models\User::class,     // Who creates tickets
    'operator' => \App\Models\User::class,  // Who handles tickets
],

#Ticket Settings

'ticket' => [
    'reference_prefix' => 'SD',            // Ticket references: SD-00001
    'default_status' => 'open',
    'default_priority' => 'medium',
    'allowed_extensions' => ['jpg', 'png', 'pdf', 'doc', 'xlsx', ...],
    'max_file_size' => 10240,              // KB
    'max_attachments_per_comment' => 5,
    'attachment_disk' => 'local',          // Any Laravel filesystem disk
    'auto_close_days' => null,             // null = disabled
    'allow_reopen' => true,
],

#SLA Settings

'sla' => [
    'enabled' => true,
    'auto_apply' => true,                  // Auto-apply policies on ticket creation
    'near_breach_minutes' => 30,
    'pause_on_statuses' => ['on_hold'],
    'default_business_hours_schedule' => null,
],

#Knowledge Base

'knowledge_base' => [
    'enabled' => true,
    'versioning_enabled' => true,
    'feedback_enabled' => true,
    'track_views' => true,
    'search_engine' => 'database',         // Or custom implementation
],

#Service Catalog

'service_catalog' => [
    'enabled' => true,
    'auto_create_ticket' => true,          // Auto-create ticket from requests
    'approval_enabled' => true,
],

#Email Integration

'email' => [
    'enabled' => true,
    'subject_prefix' => '[Service Desk #:reference]',
    'threading_enabled' => true,

    'inbound' => [
        'driver' => env('SERVICE_DESK_INBOUND_DRIVER'), // imap|mailgun|sendgrid|resend|postmark
        // Driver-specific settings...
    ],
],

#Notifications

'notifications' => [
    'channels' => ['mail'],
    'queue' => env('SERVICE_DESK_NOTIFICATION_QUEUE', 'default'),

    'notify_on' => [
        'ticket_created' => true,
        'ticket_assigned' => true,
        'ticket_status_changed' => true,
        'comment_added' => true,
        'sla_breached' => true,
        // ...
    ],
],

#Setup

#Preparing Your User Model

Add the HasTickets and IsOperator traits to your User model:

use JeffersonGoncalves\ServiceDesk\Concerns\HasTickets;
use JeffersonGoncalves\ServiceDesk\Concerns\IsOperator;

class User extends Authenticatable
{
    use HasTickets, IsOperator;
}

#Usage

#Using the Facade

The ServiceDesk facade provides a clean API for all operations:

use JeffersonGoncalves\ServiceDesk\Facades\ServiceDesk;

#Ticket Management

// Create a ticket
$ticket = ServiceDesk::createTicket([
    'title' => 'Cannot login to the system',
    'description' => 'I get an error when trying to login...',
    'priority' => 'high',
    'department_id' => 1,
    'category_id' => 2,
], $user);

// Update a ticket
ServiceDesk::updateTicket($ticket, [
    'title' => 'Updated title',
    'priority' => 'urgent',
], $performer);

// Change status
use JeffersonGoncalves\ServiceDesk\Enums\TicketStatus;

ServiceDesk::changeStatus($ticket, TicketStatus::InProgress, $operator);

// Assign to operator
ServiceDesk::assignTicket($ticket, $operator, $assignedBy);

// Close / Reopen
ServiceDesk::closeTicket($ticket, $performer);
ServiceDesk::reopenTicket($ticket, $performer);

// Find tickets
$ticket = ServiceDesk::findTicketByUuid('550e8400-e29b-41d4-a716-446655440000');
$ticket = ServiceDesk::findTicketByReference('SD-00001');

// Watchers
ServiceDesk::addWatcher($ticket, $user);
ServiceDesk::removeWatcher($ticket, $user);

#Comments

// Add a public reply
ServiceDesk::addComment($ticket, $author, 'Thanks for reporting this!', [
    'attachments' => $uploadedFiles,  // Optional
]);

// Add an internal note (not visible to the user)
ServiceDesk::addNote($ticket, $operator, 'Escalating to tier 2 support.');

#Departments

// Create a department
$department = ServiceDesk::createDepartment([
    'name' => 'IT Support',
    'description' => 'Handles IT-related tickets',
    'is_active' => true,
]);

// Manage operators
ServiceDesk::addOperator($department, $operator, 'manager');
ServiceDesk::removeOperator($department, $operator);

#Accessing Services Directly

For advanced operations, access the underlying services:

$ticketService = ServiceDesk::tickets();
$commentService = ServiceDesk::comments();
$departmentService = ServiceDesk::departments();
$attachmentService = ServiceDesk::attachments();

#Working with Enums

All enums support translated labels via the label() method:

use JeffersonGoncalves\ServiceDesk\Enums\TicketStatus;
use JeffersonGoncalves\ServiceDesk\Enums\TicketPriority;
use JeffersonGoncalves\ServiceDesk\Enums\CommentType;

TicketStatus::Open->label();      // "Open" (en) / "Aberto" (pt_BR)
TicketPriority::High->label();    // "High" (en) / "Alta" (pt_BR)
CommentType::Reply->label();      // "Reply" (en) / "Resposta" (pt_BR)

// Status transitions
TicketStatus::Open->allowedTransitions();     // [Pending, InProgress, OnHold, ...]
TicketStatus::Open->canTransitionTo(TicketStatus::InProgress); // true
TicketStatus::Closed->canTransitionTo(TicketStatus::InProgress); // false

// Priority numeric value (useful for sorting)
TicketPriority::Low->numericValue();    // 1
TicketPriority::Urgent->numericValue(); // 4

#Available Enums

#Events

The package dispatches domain events that you can listen to:

#Listening to Events

// In your EventServiceProvider or listener
use JeffersonGoncalves\ServiceDesk\Events\TicketCreated;

class NotifySlackOnTicketCreation
{
    public function handle(TicketCreated $event): void
    {
        $ticket = $event->ticket;
        // Send Slack notification...
    }
}

#Artisan Commands

#Scheduling Commands

Add these to your routes/console.php or scheduler:

use Illuminate\Support\Facades\Schedule;

Schedule::command('service-desk:check-sla-breaches')->everyFiveMinutes();
Schedule::command('service-desk:process-escalations')->everyFiveMinutes();
Schedule::command('service-desk:poll-imap-mailbox')->everyFiveMinutes();
Schedule::command('service-desk:close-stale-tickets')->daily();
Schedule::command('service-desk:clean-inbound-emails')->daily();

#Email Integration

#IMAP Polling

Requires the optional webklex/php-imap package:

composer require webklex/php-imap

Configure in .env:

SERVICE_DESK_INBOUND_DRIVER=imap
SERVICE_DESK_IMAP_HOST=imap.example.com
SERVICE_DESK_IMAP_PORT=993
SERVICE_DESK_IMAP_ENCRYPTION=ssl
SERVICE_DESK_IMAP_USERNAME=support@example.com
SERVICE_DESK_IMAP_PASSWORD=your-password
SERVICE_DESK_IMAP_FOLDER=INBOX

#Webhook Drivers (Mailgun, SendGrid, Resend, Postmark)

Configure the webhook driver and point your email provider's webhook URL to:

https://your-app.com/service-desk/webhooks/{driver}

Where {driver} is mailgun, sendgrid, resend, or postmark.

Each driver includes signature verification middleware for security.

#Translations

The package ships with English and Brazilian Portuguese translations. To customize or add new languages, publish the translation files:

php artisan vendor:publish --tag="service-desk-translations"

Translation files will be published to lang/vendor/service-desk/.

#Testing

composer test

#Static Analysis

composer analyse

#Code Formatting

composer format

#Changelog

Please see CHANGELOG for more information on what has changed recently.

#Contributing

Please see CONTRIBUTING for details.

#Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

#Credits

• Jefferson Goncalves
• All Contributors

#License

The MIT License (MIT). Please see License File for more information.