Download the PHP package escalated-dev/escalated-laravel without Composer

العربية • Deutsch • English • Español • Français • Italiano • 日本語 • 한국어 • Nederlands • Polski • Português (BR) • Русский • Türkçe • 简体中文

Escalated for Laravel

A full-featured, embeddable support ticket system for Laravel. Drop it into any app — get a complete helpdesk with SLA tracking, escalation rules, agent workflows, and a customer portal. No external services required.

escalated.dev — Learn more, view demos, and compare Cloud vs Self-Hosted options.

Three hosting modes. Run entirely self-hosted, sync to a central cloud for multi-app visibility, or proxy everything to the cloud. Switch modes with a single config change.

Features

• Ticket lifecycle — Create, assign, reply, resolve, close, reopen with configurable status transitions
• SLA engine — Per-priority response and resolution targets, business hours calculation, automatic breach detection
• Escalation rules — Condition-based rules that auto-escalate, reprioritize, reassign, or notify
• Agent dashboard — Ticket queue with filters, bulk actions, internal notes, canned responses
• Customer portal — Self-service ticket creation, replies, and status tracking
• Admin panel — Manage departments, SLA policies, escalation rules, tags, and view reports
• File attachments — Drag-and-drop uploads with configurable storage and size limits
• Activity timeline — Full audit log of every action on every ticket
• Email notifications — Configurable per-event notifications with webhook support
• Department routing — Organize agents into departments with auto-assignment (round-robin)
• Tagging system — Categorize tickets with colored tags
• Guest tickets — Anonymous ticket submission with magic-link access via guest token
• Inbound email — Create and reply to tickets via email (Mailgun, Postmark, AWS SES, IMAP)
• Inertia.js + Vue 3 UI — Shared frontend via @escalated-dev/escalated
• Ticket splitting — Split a reply into a new standalone ticket while preserving the original context
• Ticket snooze — Snooze tickets with presets (1h, 4h, tomorrow, next week); escalated:wake-snoozed-tickets Artisan command auto-wakes them on schedule
• Saved views / custom queues — Save, name, and share filter presets as reusable ticket views
• Embeddable support widget — Lightweight <script> widget served via /support/widget/* routes with KB search, ticket form, and status check
• Email threading — Outbound emails include proper In-Reply-To and References headers for correct threading in mail clients
• Branded email templates — Configurable logo, primary color, and footer text for all outbound emails
• Real-time broadcasting — Opt-in broadcasting via Pusher, Reverb, or Soketi with automatic polling fallback
• Knowledge base toggle — Enable or disable the public knowledge base from admin settings
• CI: Laravel Pint — Automated code style enforcement on every pull request

Requirements

• PHP 8.2+
• Laravel 11.x, 12.x, or 13.x
• Node.js 18+ (for frontend assets)

Quick Start

The install command will offer to automatically configure your User model with the Ticketable interface and HasTickets trait. If you prefer to do this manually, or if you use a custom user model, add the following:

Define authorization gates in App\Providers\AppServiceProvider::boot() for Laravel 12+, or App\Providers\AuthServiceProvider::boot() for Laravel 11 and earlier:

Visit /support — you're live.

UUID / string user keys

Escalated supports both integer and string (UUID/ULID) host-app user keys out of the box — no code or migration edits required:

• Every user-id parameter is typed int|string, and incoming user ids are never cast to int (so UUIDs aren't corrupted).
• The user-referencing columns Escalated creates (ticket_followers.user_id, agent_profiles.user_id, tickets.assigned_to/requester_id, the polymorphic requester/author/causer columns, the role and skill pivots, etc.) are typed to match your user model's key type automatically. At migration time Escalated reflects the configured user_model: an auto-incrementing integer key yields unsignedBigInteger columns; a HasUuids/HasUlids/string key yields string-compatible columns.

Override the detection with the user_key_type config ('auto' by default; 'bigint', 'uuid', 'ulid', or 'string'):

Existing installs: the column type is chosen when a migration runs. Apps already migrated (e.g. as bigint) keep their columns; switching your user key type after installing requires a manual migration.

Ticket subjects

A ticket has a requester (the person who raised it) and a subject line (free text). Sometimes a ticket is also about one or more host-app entities — a Project, a Customer, an asset — that aren't people. Attach them as ticket subjects so agents see what the ticket concerns and can jump straight to it in your app.

Make any model attachable by implementing the TicketSubject contract. The PresentsAsTicketSubject trait gives sane defaults — override only what you need:

Attach, detach, or sync subjects on a ticket — a ticket can reference several:

Each attached subject is serialized onto the ticket as { type, id, role, title, subtitle, url, color, icon } for the frontend to render (clickable when url is set). subject_id is stored as a string, so integer, UUID, or string-keyed host models all work.

To allow attaching subjects via the agent API (and protect against arbitrary class resolution from request input), list the permitted models in config:

Programmatic attachSubject() works for any model when the allowlist is empty; the agent API only accepts allowlisted types.

Frontend Integration

Escalated ships a Vue component library and default pages via the @escalated-dev/escalated npm package.

1. Tailwind Content

For Tailwind CSS v3 and earlier, add the Escalated package to your Tailwind content config so its classes aren't purged:

For Tailwind CSS v4+, add Escalated as a source in your app CSS file instead:

Adjust the relative path if your CSS file lives somewhere else.

2. Page Resolver

If your app already has Inertia and Vue configured, add the Escalated page resolver to your existing app.ts:

3. Theming (Optional)

Register the EscalatedPlugin to render Escalated pages inside your app's layout — no page duplication needed:

Your layout component must accept a #header slot and a default slot. Escalated will render its sub-navigation in the header and page content in the default slot.

Without the plugin, Escalated uses its own standalone layout with a simple nav bar.

CSS Custom Properties

Pass a theme option to customize colors and radii:

Available Components

Shared Inertia Props

Escalated automatically shares data to all Inertia pages via page.props.escalated:

Use these to conditionally show nav links or restrict UI elements.

Hosting Modes

Self-Hosted (default)

Everything stays in your database. No external calls. Full autonomy.

Synced

Local database + automatic sync to cloud.escalated.dev for unified inbox across multiple apps. If the cloud is unreachable, your app keeps working — events queue and retry.

Cloud

All ticket data proxied to the cloud API. Your app handles auth and renders UI, but storage lives in the cloud. Supports multiple domains per API key.

All three modes share the same controllers, UI, and business logic. The driver pattern handles the rest.

Publishing Assets

Translations

Translation strings for the escalated namespace are sourced from the shared escalated-dev/locale Composer package, which is consumed by every Escalated host plugin (Laravel, Rails, NestJS, Django, …) so wording stays consistent across backends.

The EscalatedServiceProvider wires three layers, lowest to highest precedence:

1. Central package — vendor/escalated-dev/locale/locales/{locale}/... The canonical source.
2. Plugin-shipped overrides — lang/vendor/escalated/{locale}/... in this repository, for Laravel-specific divergences.
3. Host-app overrides — {app}/lang/vendor/escalated/{locale}/..., populated via php artisan vendor:publish --tag=escalated-lang. Apps edit those files to brand or relocalize Escalated.

Each layer is merged on top of the previous one with array_replace_recursive (PHP groups) and array_merge (JSON), so a layer only needs to define the keys it changes. See lang/README.md for details.

Scheduling

Add these to your scheduler for SLA and escalation automation:

Configuration

All config lives in config/escalated.php. Key options:

See the full configuration reference.

Events

Every ticket action dispatches an event you can listen to:

Full events documentation →

Inbound Email

Escalated can create and reply to tickets from incoming emails. Supports Mailgun, Postmark, AWS SES webhooks, and IMAP polling as a fallback.

How It Works

1. An external email service receives an email at your support address (e.g., [email protected])
2. The service forwards the email to your application via webhook (or IMAP polling fetches it)
3. Escalated normalizes the payload into an InboundMessage DTO via the adapter
4. The InboundEmailService processes the message:
   • Thread matching: checks the subject for a ticket reference (e.g., [ESC-00001]), then checks In-Reply-To / References headers against stored message IDs
   • Match found: adds a reply to the existing ticket; reopens the ticket if it was resolved or closed
   • No match: creates a new ticket — if the sender is a registered user they become the requester, otherwise a guest ticket is created
5. Every inbound email is logged to escalated_inbound_emails for audit

Enable Inbound Email

Adapter Setup

Mailgun

Configure a Mailgun Route to forward inbound emails to:

The signing key is in your Mailgun dashboard under Settings > API Keys > HTTP Webhook Signing Key. Requests are verified via HMAC-SHA256 signature.

Postmark

Configure an Inbound Webhook in your Postmark server settings pointing to:

The token is sent in the X-Postmark-Token header and verified on each request.

AWS SES

1. Configure SES to receive emails and publish to an SNS topic

2. Create an HTTPS subscription on the SNS topic pointing to:

3. Escalated auto-confirms the SNS subscription and verifies message signatures using Amazon's certificate

IMAP (Fallback)

For providers without webhook support, poll via IMAP:

Schedule the poll command:

Webhook URL

Where {prefix} is your configured route prefix (default: support) and {adapter} is mailgun, postmark, or ses. These routes use the api middleware (no CSRF, no auth).

Processing Features

• Thread detection via subject reference pattern ([ESC-00001]) and In-Reply-To / References headers
• Guest tickets for unknown senders — display name derived from email (e.g., [email protected] → John Doe)
• Subject sanitization — strips RE:, FW:, FWD: prefixes (including stacked)
• HTML fallback — uses stripped HTML body when plain text is empty
• Duplicate detection — skips messages with duplicate Message-ID headers
• Attachment handling — stores attachments respecting max_attachment_size_kb and max_attachments_per_reply
• Auto-reopen — reopens resolved/closed tickets when a reply arrives via email
• Audit logging — every inbound email recorded in escalated_inbound_emails with status tracking

Custom Adapter

Implement the InboundAdapter interface:

Inbound Email Environment Variables

Routes

All routes use the configurable prefix (default: support). Inbound webhook routes use the api middleware (no auth, no CSRF).

Plugin SDK

Escalated supports framework-agnostic plugins built with the Plugin SDK. Plugins are written once in TypeScript and work across all Escalated backends.

Installing Plugins

The plugin bridge is built into escalated-laravel — no additional PHP package required. Install plugins and the runtime via npm:

Enabling SDK Plugins

How It Works

SDK plugins run as a Node.js subprocess managed by @escalated-dev/plugin-runtime, communicating with Laravel over JSON-RPC 2.0 via stdio. The escalated_do_action() and escalated_apply_filters() helpers dual-dispatch to both legacy PHP plugins and new SDK plugins simultaneously — no changes to existing hook call sites.

Building Your Own Plugin

Resources

• Plugin SDK — TypeScript SDK for building plugins
• Plugin Runtime — Runtime host for plugins
• Plugin Development Guide — Full documentation

See the detailed Plugin Bridge section below for the full architecture, auto-generated routes, dual dispatch, and store documentation.

Plugin Bridge (SDK Plugins)

Escalated supports a second generation of plugins written in TypeScript using the @escalated-dev/plugin-sdk. These plugins run as a Node.js subprocess managed by @escalated-dev/plugin-runtime and communicate with Laravel over JSON-RPC 2.0 via stdio.

How It Works

The bridge spawns the runtime lazily on the first hook dispatch and keeps the process alive across requests (one long-lived subprocess per PHP-FPM worker). If the process crashes it is automatically restarted with exponential backoff.

Requirements

• Node.js 18+
• @escalated-dev/plugin-runtime installed in your project:

Install any SDK plugins the same way:

Startup Sequence

1. EscalatedServiceProvider::boot() calls $bridge->boot()
2. Bridge spawns node node_modules/@escalated-dev/plugin-runtime/dist/index.js
3. Protocol handshake confirms version compatibility
4. Bridge fetches the plugin manifest (pages, hooks, endpoints, webhooks)
5. Routes are registered in Laravel for plugin pages, API endpoints, and webhooks
6. Runtime is ready to receive hook dispatches

Auto-generated Routes

For each installed SDK plugin the bridge automatically registers:

Dual Dispatch (Backward Compatibility)

The existing escalated_do_action() and escalated_apply_filters() helper functions dispatch hooks to both old PHP plugins and new SDK plugins simultaneously. No changes are required to existing hook call sites.

Plugin Store

SDK plugins can persist data using ctx.store. This is backed by the escalated_plugin_store table:

Configuration

Writing SDK Plugins

See the @escalated-dev/plugin-sdk package for the full TypeScript authoring API. A minimal plugin looks like:

Documentation

• Installation
• Configuration
• Customization
• Events
• SLA Policies
• Escalation Rules
• Hosting Modes

Newsletters (optional, disabled by default)

An admin-only broadcast feature for sending Markdown emails to contacts. Disabled by default — when off, no newsletter routes, controllers, or scheduler hooks register.

Add a Laravel scheduler entry in app/Console/Kernel.php:

Then re-seed permissions to attach newsletters.manage and newsletters.send to the Admin role:

Custom themes live in resources/views/vendor/escalated/newsletters/themes/<slug>.blade.php.

ESP webhook endpoints for outbound events:

• POST /escalated/webhooks/newsletter/postmark
• POST /escalated/webhooks/newsletter/mailgun
• POST /escalated/webhooks/newsletter/ses
• POST /escalated/webhooks/newsletter/sendgrid

Testing

Also Available For

• Escalated for Laravel — Laravel Composer package (you are here)
• Escalated for Rails — Ruby on Rails engine
• Escalated for Django — Django reusable app
• Escalated for AdonisJS — AdonisJS v6 package
• Escalated for Filament — Filament v3 admin panel plugin
• Shared Frontend — Vue 3 + Inertia.js UI components

Same architecture, same Vue UI, same three hosting modes — for every major backend framework.

License

MIT