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

• Abdelkarim Mateos Sanchez
• All Contributors

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.