Download the PHP package linkrobins/support without Composer

Link Robins Support

A private support-desk extension for Flarum 2. Lets registered users open support tickets with staff, with an emphasis on workflows that keep forum-wide moderation actions (suspensions, bans) honest.

Features

• Private tickets. Tickets are NOT Flarum discussions. A user's ticket is visible only to that user and to staff. Other users never see it, even if they know the URL.
• Categories. Admin-configurable, each with name, slug, color, icon, position, and an is_appeal flag.
• Appeal flow. Categories marked as appeals follow stricter rate limits and are filable by suspended users so they can plead their case. General categories are blocked for suspended users so a ban isn't trivially worked around.
• Internal notes. Staff can add replies marked as internal. These are filtered out at the database level for non-staff users -- the ticket owner doesn't see them in their list, can't fetch them directly, and the replyCount on the ticket reflects only what they can see. Visually, internal notes get a subtle background tint on the reply card for staff.
• Reply moderation. Staff can edit, soft-delete, restore, and permanently delete any reply via a ⋯ menu in the reply header. Edits stamp edited_at and edited_by_user_id so other staff can see the audit info; permanent deletion requires the reply to be soft-deleted first (no accidental single-click destruction).
• Ticket moderation. Staff can soft-delete tickets via a ⋯ menu in the ticket title row. Soft-deleted tickets are hidden from the index for both the owner and staff but remain reachable via direct URL for staff to restore. Permanent deletion is admin-only and cascades to all replies.
• Rate limits. Per-user, configurable. Defaults:
  • 3 appeals per 30 days
  • 1 concurrent open appeal at a time
  • 10 general tickets per 24 hours
• Permanent appeal-ban. A per-user flag (support_appeal_banned) that blocks appeals while leaving general tickets available. Toggled from the admin's "Appeal bans" tab.
• Status workflow. open → in_progress → awaiting_user → resolved → closed. Auto-advances based on who replies (staff to open ⇒ in_progress; user to awaiting_user ⇒ in_progress). Closed tickets reject replies.
• Assignment. Staff can claim or unassign tickets. The assigned staff member shows in the staff control bar.
• Notifications. In-app and email. The ticket owner is notified when staff replies; staff are notified when a new ticket is opened or when the owner replies. Internal notes never produce notifications. Users can toggle these per driver in their notification preferences.
• Decisions on appeals. Resolved appeal tickets record a decision field (approved / rejected / null).
• File attachments. Optional integration with fof/upload. When installed, the compose and reply forms surface an "Attach files" button that uploads through fof/upload's normal pipeline. No configuration here; the button respects whatever fof/upload permissions you've set.

Requirements

• Flarum 2.0.0+
• PHP 8.2+

Installation

Then enable the extension in admin → Extensions.

Permissions

The extension adds one permission:

• linkrobins-support.handle_tickets (default: moderate group) -- grants the ability to see all tickets, reply on any ticket, post internal notes, change ticket status, set decisions, and claim tickets.

Anyone in the admin group bypasses this check.

Filing tickets requires being authenticated; the policy doesn't add a separate permission for it.

Admin UI

Settings live at admin → Extensions → Link Robins Support, with three tabs:

• Categories. CRUD for ticket categories.
• Rate limits. Configurable values for the appeal and general limits described above.
• Appeal bans. Search users and toggle their permanent appeal-ban flag.

Forum UI

Users see:

• /support -- their tickets list, with filter chips for status.
• /support/new -- compose form. Banned-from-appeals users see only general categories; suspended users see only appeal categories.
• /support/:id -- the ticket page, with reply form and reply thread.

Staff additionally see:

• The "All" filter on the index, with status chips for cross-cutting views (open, in_progress, awaiting_user, resolved, closed).
• The staff control bar on each ticket: set status, claim/unassign, post internal notes via the reply form's "Internal note" toggle.

Data model

Three tables:

• linkrobins_support_categories -- name, slug, description, color, icon, position, is_appeal.
• linkrobins_support_tickets -- category_id, user_id, assigned_staff_id, subject, status, decision, last_reply_at, deleted_at.
• linkrobins_support_replies -- ticket_id, user_id, content (parsed-source XML), is_internal_note, deleted_at, edited_at, edited_by_user_id.

One column added to the existing users table:

• support_appeal_banned (boolean, default 0).

Replies use Flarum's content formatter via the HasFormattedContent trait. The rendered HTML is computed at serialize time via formatContent(), NOT cached in a content_html column -- this means formatter extensions like mentions and emoji apply to older replies the moment they're installed.

File attachments (fof/upload integration)

If fof/upload is installed and enabled, the compose form and reply form get an "Attach files" button. Uploaded files are stored, validated, and rendered by fof/upload; this extension only inserts the resulting BBCode marker into the message body. No additional configuration is needed -- if the user has permission to upload via fof/upload, the button appears.

Privacy caveat

fof/upload's download URLs act as capabilities: anyone who has the URL to a file can download it. CSRF protection limits direct hot-linking, but if a staff member copies a file URL out of a ticket and shares it elsewhere, that link works for anyone who clicks it.

This is identical to how fof/upload behaves on regular discussions, so it isn't unique to this extension. If you need a hard guarantee that ticket attachments can be read only by ticket-eligible users, fof/upload would need to be patched to gate downloads against per-resource policies. That's out of scope for v1.

In practice, for the support-desk use case, the risk is small: attachments tend to be screenshots and logs from the ticket-opener themselves, who is also the only non-staff party with the URL.

Security notes

• The creating() hooks on both tickets and replies overwrite user_id with the authenticated actor's id. Even if the client sends relationships.user, JSON:API rejects it because the field isn't declared writable, AND the hook would overwrite it anyway.
• Visibility is enforced in two places that must stay in sync: the resource's scope() (for single-resource Show endpoints) and the Searcher's getQuery() (for list Index endpoints). Both use the same rules.
• Internal notes are filtered at the database level (a WHERE clause on is_internal_note), not at render time. A non-staff user hitting the API directly cannot bypass the filter.
• The "Update" endpoint is gated by ->can('update'), which routes to SupportTicketPolicy::update. Field setters add a second layer of defense: even if the gate ever loosened, status / decision / assignment changes wouldn't take effect for a non-staff actor.
• Soft-deleted rows are hidden from non-staff at the DB query level (Eloquent's default SoftDeletes scope). Staff see them via withTrashed() in the resource scope, but Index/Searcher queries deliberately stay on the active set so the staff index isn't cluttered. Force-delete on a live (non-trashed) row is rejected by the deleting() hook -- a soft-delete must come first.

API summary

Moderation patterns:

• PATCH a ticket or reply with { attributes: { content: "..." } } to edit (replies only). Stamps edited_at + edited_by_user_id.
• PATCH with { attributes: { isDeleted: true } } to soft-delete. PATCH with { isDeleted: false } to restore.
• DELETE permanently removes -- but only if the row is already soft-deleted; otherwise returns 400.

Supported filters (use filter[name]=value shape; Flarum 2 rejects unrecognized top-level params):

• On tickets: filter[mine]=1, filter[status]=open, filter[categoryId]=N
• On replies: filter[ticketId]=N

License

MIT.