README

v1.0 — stable contract. The public contract is frozen as of v1.0.0 (see docs/ADR-004-v1.0-contract.md).

Core (stable): open · assign · reassign · converse · close · departments

routing · priority · attachments · statuses.

Optional-stable (ON by default): level escalation.

Optional-experimental (@experimental, OFF by default): evaluations, agent rating, risk assessment — outside the semver promise.

A comprehensive, UUID-first support ticket management system for Laravel with 4-level escalation, risk assessment, evaluations, and full RESTful API. General-purpose for any UUID-first Laravel application.

Features

4-Level Escalation System: Automatic and manual escalation between support levels (I, II, III, IV)
Department Management: Organize tickets by departments (Technical, Administrative, Commercial)
Risk Assessment: Level III/IV agents can assess ticket risk with automatic critical escalation
Ticket Evaluations: Global ticket scoring and individual agent ratings
File Attachments: Upload/download/delete files attached to tickets. Configurable disk (local/S3/…), mime/size restrictions, role-based authorization via contract. See ADR-002.
RESTful API: Full versioned API (v1) with Laravel Sanctum authentication
Flexible Authorization: Contract-based authorization system, easily adaptable to any permission package
UUID-first: Requires users.id UUID v7 char(36). See setup-uuid.md (shared with larabill) for consumer setup. See ADR-001 for rationale.
Event System: 11 events for complete extensibility
SLA Management: Configurable SLA hours per level with auto-escalation on breach
Comprehensive Testing: 25+ tests with 80+ assertions

Requirements

PHP 8.4+
Laravel 12.x

Installation

Install via Composer:

composer require aichadigital/laratickets

Run the installation command:

php artisan laratickets:install --seed

This will:

Publish configuration file
Run migrations (10 tables)
Seed default levels (I-IV) and departments

Migrations are package-managed. Laratickets owns its database schema and loads it from the package via loadMigrationsFrom(). The install command does not copy migrations into your application, and applications should not publish or edit the package migrations. User foreign keys require UUID-compatible (char(36) UUID v7) user IDs. If you need custom schema ownership, fork or request an extension point. See ADR-005.

Configuration

The configuration file is published to config/laratickets.php:

return [
    // User model configuration (UUID-first; users.id MUST be char(36) UUID v7)
    'user' => [
        'model' => env('LARATICKETS_USER_MODEL', config('auth.providers.users.model')),
        'id_column' => env('LARATICKETS_USER_ID_COLUMN', 'id'),
    ],

    // Authorization handlers
    'authorization' => [
        'handler' => \AichaDigital\Laratickets\Implementations\BasicTicketAuthorization::class,
        'capability_handler' => \AichaDigital\Laratickets\Implementations\BasicUserCapabilityHandler::class,
    ],

    // Features
    'evaluation' => ['enabled' => true],
    'risk_assessment' => ['enabled' => true, 'auto_escalate_on_critical' => true],
    'sla' => ['enabled' => true, 'auto_escalation_on_breach' => true],
    // ... more configuration options
];

Basic Usage

Creating a Ticket

use AichaDigital\Laratickets\Services\TicketService;
use AichaDigital\Laratickets\Enums\Priority;

$ticketService = app(TicketService::class);

$ticket = $ticketService->createTicket([
    'subject' => 'Database connection issue',
    'description' => 'Cannot connect to production database',
    'priority' => Priority::HIGH,
    'department_id' => 1,
], $user);

Requesting Escalation

use AichaDigital\Laratickets\Services\EscalationService;

$escalationService = app(EscalationService::class);

$escalation = $escalationService->requestEscalation(
    $ticket,
    $targetLevel, // TicketLevel model
    'Issue requires senior expertise',
    $requester
);

Assessing Risk

use AichaDigital\Laratickets\Services\RiskAssessmentService;
use AichaDigital\Laratickets\Enums\RiskLevel;

$riskService = app(RiskAssessmentService::class);

$assessment = $riskService->assessRisk(
    $ticket,
    $assessor, // Must be Level III or IV
    RiskLevel::CRITICAL,
    'Affects production systems for 10k+ users'
);
// Auto-escalates if risk is CRITICAL

Evaluating a Ticket

use AichaDigital\Laratickets\Services\EvaluationService;

$evaluationService = app(EvaluationService::class);

$evaluation = $evaluationService->evaluateTicket(
    $ticket,
    $evaluator,
    4.5, // Score 1.0-5.0
    'Excellent support, quick resolution'
);

API Usage

All API endpoints require Laravel Sanctum authentication.

Base URL: /api/v1/laratickets

Examples

Create Ticket:

curl -X POST /api/v1/laratickets/tickets \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Login issue",
    "description": "Cannot log in to dashboard",
    "priority": "high",
    "department_id": 1
  }'

List Tickets:

curl /api/v1/laratickets/tickets?status=open&level=1 \
  -H "Authorization: Bearer {token}"

Request Escalation:

curl -X POST /api/v1/laratickets/tickets/1/escalations \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "target_level_id": 2,
    "justification": "Requires advanced database knowledge"
  }'

See API Documentation for complete endpoint reference.

Authorization

Laratickets uses a contract-based authorization system. The default implementation provides basic authorization, but you can easily integrate with any permission package (Bouncer, Spatie Permission, etc.).

Custom Authorization Handler

namespace App\Laratickets\Authorization;

use AichaDigital\Laratickets\Contracts\TicketAuthorizationContract;
use Silber\Bouncer\BouncerFacade as Bouncer;

class MyTicketAuthorization implements TicketAuthorizationContract
{
    public function canViewTicket($user, Ticket $ticket): bool
    {
        return Bouncer::can('view-tickets')
            || $user->id === $ticket->created_by;
    }

    // Implement other methods...
}

Update config:

'authorization' => [
    'handler' => \App\Laratickets\Authorization\MyTicketAuthorization::class,
],

Events

Laratickets dispatches 11 events that you can listen to:

TicketCreated
TicketAssigned
TicketStatusChanged
TicketClosed
EscalationRequested
EscalationApproved
EscalationRejected
TicketEvaluated
AgentRated
RiskAssessed
SLABreached

Example Listener

use AichaDigital\Laratickets\Events\TicketCreated;

class SendTicketCreatedNotification
{
    public function handle(TicketCreated $event): void
    {
        $ticket = $event->ticket;

        // Send notification to level I agents
        Notification::send(
            $this->getLevelIAgents($ticket->department_id),
            new NewTicketNotification($ticket)
        );
    }
}

Testing

composer test

Code Style

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

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later). See LICENSE.md for details.

Contributor License Agreement

Contributors must agree to our Contributor License Agreement (CLA) before their contributions can be accepted. This helps ensure the project remains free and open source.

aichadigital / laratickets

Maintainers

Package info

Fund package maintenance!

Statistics

Security