README

⚠️ ALPHA VERSION - IN ACTIVE DEVELOPMENT

This package is currently in alpha stage and under active development. The API and features may change significantly before the first stable release. Not recommended for production use yet.

• Current Status: Pre-release (v0.x)
• Expected Stable Release: TBD
• Contributions and feedback welcome!

A comprehensive support ticket management system for Laravel with 4-level escalation, risk assessment, evaluations, and full RESTful API.

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 (8 tables)
• Seed default levels (I-IV) and departments

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.