Laravel Service Desk

https://github.com/jeffersongoncalves/laravel-service-desk
Admin
Laravel Service Desk is a headless service desk package for Laravel providing ticket management, SLA...
Tokens:8,505
Snippets:82
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Install the package via Composer.

```bash
composer require jeffersongoncalves/laravel-service-desk
```

--------------------------------

### Install webklex/php-imap package

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Install the optional webklex/php-imap package required for IMAP polling.

```bash
composer require webklex/php-imap
```

--------------------------------

### Listen to TicketCreated event with a listener class

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Example listener for the TicketCreated event. Register this class in your EventServiceProvider or as a listener to handle ticket creation. The event provides a $ticket property for accessing the created ticket.

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

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

```

--------------------------------

### Testing Patterns: Create ticket and fake events

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/resources/boost/skills/service-desk-development/SKILL.md

Feature tests use Orchestra Testbench with SQLite in-memory; the TestCase loads package migrations via runPackageMigrations(). The first block creates a ticket and asserts it is a Ticket instance with a reference number starting with 'SD-'. The second block shows using Event::fake() with specific event classes to avoid blocking Eloquent model events (uuid/reference generation).

```php
use JeffersonGoncalves\ServiceDesk\Tests\Fixtures\User;

it('can create a ticket', function () {
    $user = User::create(['name' => 'Test', 'email' => 'test@example.com', 'password' => 'secret']);
    $department = Department::create(['name' => 'IT', 'slug' => 'it']);

    $ticket = app(TicketService::class)->create([
        'department_id' => $department->id,
        'title' => 'Test Ticket',
        'description' => 'Description',
    ], $user);

    expect($ticket)->toBeInstanceOf(Ticket::class)
        ->and($ticket->reference_number)->toStartWith('SD-');
});
```

```php
Event::fake([TicketCreated::class, TicketStatusChanged::class]);
```

--------------------------------

### Change ticket status with TicketStatus::allowedTransitions()

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/resources/boost/skills/service-desk-development/SKILL.md

Use this snippet to change a ticket's status. The TicketStatus enum enforces allowed transitions; the example shows moving a ticket to InProgress. Note that OnHold pauses SLA, Resolved can be reopened, and Closed can be reopened only if the config allow_reopen is true.

```php
use JeffersonGoncalves\ServiceDesk\Enums\TicketStatus;

// Valid transitions are enforced by TicketStatus::allowedTransitions()
// Open -> Pending, InProgress, OnHold, Resolved, Closed
// Pending -> Open, InProgress, OnHold, Resolved, Closed
// InProgress -> Pending, OnHold, Resolved, Closed
// OnHold -> Open, Pending, InProgress (pauses SLA)
// Resolved -> Open (reopen), Closed
// Closed -> Open (if config allow_reopen is true)

$ticketService->changeStatus($ticket, TicketStatus::InProgress, $operator);
```

--------------------------------

### Publish Configuration and Migrations

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Publish the configuration and migration files.

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

--------------------------------

### Run Migrations

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Run the database migrations.

```bash
php artisan migrate
```

--------------------------------

### Set up SLA workflow with SlaService, BusinessHoursSchedule, SlaPolicy, and SlaTarget

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/resources/boost/skills/service-desk-development/SKILL.md

Use this snippet to set up an SLA workflow. It creates a business hours schedule, adds a time slot, creates an SLA policy with priority targets, and defines response/resolution times. SLA is auto-applied on ticket creation if sla.auto_apply is true, and the scheduler runs service-desk:check-sla every minute to detect breaches.

```php
use JeffersonGoncalves\ServiceDesk\Services\SlaService;

$slaService = app(SlaService::class);

// 1. Create business hours schedule
$schedule = BusinessHoursSchedule::create([
    'name' => 'Standard Business Hours',
    'timezone' => 'America/Sao_Paulo',
    'is_default' => true,
]);

// 2. Add time slots
BusinessHoursTimeSlot::create([
    'schedule_id' => $schedule->id,
    'day_of_week' => 1, // Monday
    'start_time' => '09:00',
    'end_time' => '18:00',
]);

// 3. Create SLA policy with priority targets
$policy = SlaPolicy::create([
    'name' => 'Standard SLA',
    'business_hours_schedule_id' => $schedule->id,
    'conditions' => ['priorities' => ['high', 'urgent']],
]);

SlaTarget::create([
    'sla_policy_id' => $policy->id,
    'priority' => 'urgent',
    'first_response_time' => 30,   // 30 business minutes
    'resolution_time' => 240,       // 4 business hours
]);

// 4. SLA is auto-applied when ticket is created (if sla.auto_apply is true)
// 5. Scheduler runs service-desk:check-sla every minute to detect breaches
```

--------------------------------

### Manage departments and operators

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Create a department and manage its operators with roles.

```php
// 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);
```

--------------------------------

### Create a new ticket using TicketService

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/resources/boost/skills/service-desk-development/SKILL.md

Demonstrates how to instantiate the TicketService and create a ticket with required fields. Note that events like TicketCreated are dispatched automatically, and fields like uuid and reference_number are generated by the system.

```php
use JeffersonGoncalves\ServiceDesk\Services\TicketService;

$ticketService = app(TicketService::class);

$ticket = $ticketService->create([
    'department_id' => 1,
    'title' => 'Server is down',
    'description' => 'Production server not responding.',
    'priority' => 'urgent',
    'source' => 'web',
], $user);

// Events dispatched: TicketCreated
// Auto-generated: uuid, reference_number (e.g., SD-000001)
// If SLA auto_apply is enabled, SLA policy is automatically matched and applied
```

--------------------------------

### Import ServiceDesk facade

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Import the ServiceDesk facade to access the clean API for all operations.

```php
use JeffersonGoncalves\ServiceDesk\Facades\ServiceDesk;
```

--------------------------------

### Configure SLA Settings

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Configure SLA settings including auto-apply, near-breach warnings, and pause statuses.

```php
'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,
],
```

--------------------------------

### Run static analysis with composer analyse

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Runs static analysis on the codebase.

```bash
composer analyse
```

--------------------------------

### Work with enums: labels, transitions, and numeric values

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Use enum methods for translated labels, status transitions, and numeric priority values.

```php
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
```

--------------------------------

### Configure Notifications

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Configure notification channels, queue, and which events trigger notifications.

```php
'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,
        // ...
    ],
],
```

--------------------------------

### Configure Knowledge Base

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Configure knowledge base features such as versioning, feedback, view tracking, and search engine.

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

--------------------------------

### Configure Ticket Settings

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Configure ticket settings such as reference prefix, default status, priority, attachments, and auto-close behavior.

```php
'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,
],
```

--------------------------------

### Manage tickets with ServiceDesk facade

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Shows the main ticket management operations: create, update, change status, assign, close/reopen, find by UUID or reference, and manage watchers.

```php
// 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);
```

--------------------------------

### Publish Translations

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Optionally publish the translation files.

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

--------------------------------

### Format code with composer format

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Formats the codebase according to the project's code style.

```bash
composer format
```

--------------------------------

### Run tests with composer test

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Runs the package's test suite.

```bash
composer test
```

--------------------------------

### Configure Service Catalog

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Configure service catalog settings including auto ticket creation and approval workflows.

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

--------------------------------

### Run local checks with composer test, analyse, and format

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/CONTRIBUTING.md

Run these commands locally before submitting a pull request to ensure the test suite, static analysis, and code style checks pass.

```bash
composer test     # Run the Pest test suite
composer analyse  # Run PHPStan static analysis
composer format   # Apply Laravel Pint code style fixes
```

--------------------------------

### Configure Models

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Configure the user and operator model classes used by the package.

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

--------------------------------

### Configure IMAP polling in .env

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Environment configuration for IMAP polling. Set the inbound driver to imap and provide the IMAP server details, credentials, and folder.

```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
```

--------------------------------

### Configure Email Integration

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Configure email integration settings including subject prefix, threading, and inbound driver.

```php
'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...
    ],
],
```

--------------------------------

### Schedule service-desk artisan commands

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Schedule the service desk artisan commands in routes/console.php or the scheduler. Runs SLA checks and escalations every five minutes, polls the IMAP mailbox every five minutes, and closes stale tickets and cleans inbound emails daily.

```php
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();
```

--------------------------------

### Access underlying services via ServiceDesk

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Access the underlying services directly for advanced operations.

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

--------------------------------

### Add HasTickets and IsOperator traits to User model

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Add the HasTickets and IsOperator traits to your User model to enable ticket-related functionality.

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

class User extends Authenticatable
{
    use HasTickets, IsOperator;
}
```

--------------------------------

### Webhook URL for email providers

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Webhook URL to configure in your email provider (Mailgun, SendGrid, Resend, or Postmark). Replace {driver} with the provider name. Each driver includes signature verification middleware.

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

--------------------------------

### Add comments and internal notes

Source: https://github.com/jeffersongoncalves/laravel-service-desk/blob/main/README.md

Add public replies with optional attachments and internal notes that are not visible to the user.

```php
// 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.');
```
Tokens:
Raw