The Tickets facade

Everything goes through one facade, RoundlyConsulting\Tickets\Facades\Tickets (global alias Tickets), sugar over the TicketsManager singleton. A ticket from filing to resolution:

use Illuminate\Support\Facades\Gate;
use RoundlyConsulting\Tickets\Facades\Tickets;

// Who is an agent is your call: is_support stands for your own agent flag. An undefined ability denies.
Gate::define('tickets.agent', fn ($user) => $user->is_support);

// A category, once: its defaults apply to every ticket filed under it.
$hardware = Tickets::categories()->make(['en' => 'Hardware', 'sk' => 'Hardvér'])
    ->defaults(priority: 'high', dueIn: 'P1D')
    ->create();

// The customer opens a ticket — numbered TCK-1, high priority, due in a day.
$ticket = Tickets::make()
    ->subject('Printer on floor 3 is jammed')
    ->description('Paper jam error E-102 since this morning.')
    ->requester($customer)
    ->category($hardware)
    ->create();

// An agent takes it, answers the customer and leaves a note only agents see.
Tickets::for($ticket)->by($agent)->claim()->start();
Tickets::for($ticket)->by($agent)->reply('A technician is on the way.', transition: 'wait');
Tickets::for($ticket)->by($agent)->note('Roller worn out, order a spare.');

// The customer's reply puts it back in the queue; the agent resolves it.
Tickets::for($ticket)->by($customer)->reply('Works again, thanks!');
Tickets::for('TCK-1')->by($agent)->resolve('Roller replaced.');

Tickets::for('TCK-1')->status();   // TicketStatus::Resolved
Tickets::for('TCK-1')->thread();   // the two public replies — never the note

Manager methods

perform() is public on the manager too, but internal: it is the single funnel every handle, sub-accessor, builder and model method runs its action through, and the hook the fake records with. Don’t call it from host code.

The for($ticket) handle

Tickets::for($ticket) returns an immutable TicketHandle. Mutators return the handle so you can chain them; creators and queries return their result. The bound Ticket is updated in place, so a chained call sees the previous one’s effect:

Tickets::for('SUP-42')->by($agent)->claim()->prioritize('urgent')->due(now()->addHours(4))->wait();

Sub-accessors

Sub-accessor mutators return the sub-accessor, so they chain within their area: ->tags()->attach(['vip'])->detach(['spam']). Every mutation of a soft-deleted ticket throws TicketTrashedException (lifecycle refuses its transitions with SubjectTrashedException).

Scoping is a security boundary. A handle refuses what is not its ticket’s: another ticket’s comment, a link this ticket is not part of, another owner’s media, a guest link for someone who is neither the guest requester nor a guest watcher. ProjectTickets::for() refuses a ticket of another project.

Tickets::categories()

A string name is the current locale’s; an array is a locale map (['en' => 'Hardware', 'sk' => 'Hardvér']).

Tickets::fields()

Tickets::tags()

Tickets::guests()

Tickets::project($project)

Model traits

The traits delegate to the manager, so everything they do is recorded by the fake too:

Data objects

Every DTO is final readonly:

The PHP API trusts its caller

The facade enforces the domain rules — a requester may not post a note, only an eligible assignee is assigned, a Closed ticket takes no message, merging needs the merge ability, the agent scope decides who is an agent for a ticket — but it never asks TicketPolicy. The policy is the authority of the HTTP API; a host calling the facade decides who may call what.