PHPackages                             tishmalo/escalation-matrix - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. tishmalo/escalation-matrix

ActiveLibrary

tishmalo/escalation-matrix
==========================

Escalation Matrix Package for Laravel

v1.0.0(3mo ago)07MITPHPPHP ^8.1|^8.2|^8.3

Since Feb 6Pushed 3mo agoCompare

[ Source](https://github.com/tishmalo/escalation-matrix)[ Packagist](https://packagist.org/packages/tishmalo/escalation-matrix)[ RSS](/packages/tishmalo-escalation-matrix/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (3)Versions (2)Used By (0)

Escalation Matrix Package
=========================

[](#escalation-matrix-package)

A robust error handling and escalation system for Laravel applications. This package captures exceptions, prioritizes them, and sends notifications via Email and SMS (optional). It also features a standalone support ticket system via a Driver pattern.

Features
--------

[](#features)

- 🚨 **Prioritized Error Handling:** Automatically categorizes errors as Critical, High, Medium, or Low.
- 📧 **Email Notifications:** sends detailed error reports to configured contacts.
- 📱 **SMS Alerts:** Optional integration with Africa's Talking for critical mobile alerts.
- 🎫 **Support Ticket Driver:** Plug-and-play interface to connect with any support ticket system.
- 🖥️ **Standalone UI:** Built-in interface at `/tickets` to view and manage internal tickets.
- ⚙️ **Configurable:** Rate limiting, ignored exceptions, and custom escalation matrices.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require tishmalo/escalation-matrix
```

Setup
-----

[](#setup)

1. **Publish Configuration:**

    ```
    php artisan vendor:publish --tag=escalation-config
    ```
2. **Run Migrations:**The package uses a local database ticket system by default. Run migrations to create the required table:

    ```
    php artisan migrate
    ```
3. **Configure Escalation Matrix:**Edit `config/escalation.php` to set up your notification contacts, priorities, and channels.
4. **Setup Ticket Authentication (Important!):**The `/tickets` interface is protected and requires authentication. Choose one of the methods below:

### Ticket Authentication Setup

[](#ticket-authentication-setup)

#### Option 1: For Apps WITH Laravel Authentication (Recommended)

[](#option-1-for-apps-with-laravel-authentication-recommended)

If your application has user authentication (Breeze, Jetstream, Sanctum, etc.), configure allowed users:

```
ESCALATION_AUTH_ENABLED=true
ESCALATION_ALLOWED_EMAILS=admin@company.com,dev@company.com,support@company.com
```

Or use roles (works with Spatie Permission, Laravel's built-in roles, etc.):

```
ESCALATION_AUTH_ENABLED=true
ESCALATION_ALLOWED_ROLES=admin,developer,support
```

**How it works:**

- Users must log in to your application first
- Package checks if the logged-in user's email is in allowed list OR has an allowed role
- No additional login required - uses your app's existing authentication

#### Option 2: For Apps WITHOUT Authentication (Password-Based)

[](#option-2-for-apps-without-authentication-password-based)

If your application doesn't have authentication, set up a password:

```
php artisan escalation:set-password
```

This command will:

1. Prompt you to enter a password (min 8 characters)
2. Generate a bcrypt hash
3. Show you what to add to your `.env` file

Add the generated hash to `.env`:

```
ESCALATION_AUTH_ENABLED=true
ESCALATION_PASSWORD_HASH="$2y$10$abc...xyz"
```

**How it works:**

- Users visit `/tickets` and see a login form
- They enter the password you set
- Session-based authentication (login once per browser session)
- To change password, run `php artisan escalation:set-password` again

#### Disable Authentication (Not Recommended for Production)

[](#disable-authentication-not-recommended-for-production)

To disable authentication (only for local development):

```
ESCALATION_AUTH_ENABLED=false
```

**⚠️ Warning:** This exposes sensitive error data (stack traces, user info, IPs) to anyone who can access your application.

### Custom Support Ticket Driver (Optional)

[](#custom-support-ticket-driver-optional)

By default, the package uses `LocalTicketDriver` which stores tickets in your database. To integrate with an external ticketing system:

1. **Implement the Driver Interface:**

    ```
    // app/Services/MyTicketDriver.php
    use Tishmalo\EscalationMatrix\Contracts\SupportTicketDriver;

    class MyTicketDriver implements SupportTicketDriver {
        public function createTicket($subject, $description, $priority, $errorData): ?string {
            // Your integration logic (e.g., Zendesk, Jira, etc.)
            return 'TICKET-123';
        }

        public function getSystemUser(): ?object {
             return null;
        }
    }
    ```
2. **Bind Your Custom Driver:**In your `AppServiceProvider`:

    ```
    $this->app->bind(
        \Tishmalo\EscalationMatrix\Contracts\SupportTicketDriver::class,
        \App\Services\MyTicketDriver::class
    );
    ```

Usage
-----

[](#usage)

### ✨ Automatic Exception Capture (Zero Configuration Required)

[](#-automatic-exception-capture-zero-configuration-required)

**The package works automatically!** Once installed and configured, it will capture and process ALL exceptions without any code changes.

The package automatically registers with Laravel's exception handler using the `reportable()` method and processes exceptions based on your `config/escalation.php` settings.

**To disable automatic reporting:**

```
# In your .env file
ERROR_AUTO_REPORT=false
```

Or in `config/escalation.php`:

```
'auto_report' => false,
```

### Manual Integration (Optional)

[](#manual-integration-optional)

If you prefer manual control or disabled auto-reporting, you can manually trigger the escalation:

**Using Facade:**

```
use Tishmalo\EscalationMatrix\Facades\Escalation;

try {
    // ... your code
} catch (\Throwable $e) {
    Escalation::handle($e);
    throw $e; // Re-throw if needed
}
```

**Using Service Container:**

```
app(\Tishmalo\EscalationMatrix\Services\EscalationService::class)->handle($exception);
```

### Viewing and Managing Tickets

[](#viewing-and-managing-tickets)

Access the ticket management interface at `/tickets` to:

- View all tickets with their priorities and statuses
- Click on individual tickets to see full details
- Change ticket status via dropdown (Open, In Progress, Resolved, Closed)

### Updating the Package

[](#updating-the-package)

When updating the package, if you have previously published the views, republish them to get the latest updates:

```
php artisan vendor:publish --tag=escalation-views --force
```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance82

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

94d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/465590acf8fe2885c365a6712288d7142a4d5af2a906d51be49c6b45b225d56e?d=identicon)[tishmalo](/maintainers/tishmalo)

---

Top Contributors

[![tishmalo](https://avatars.githubusercontent.com/u/62063245?v=4)](https://github.com/tishmalo "tishmalo (11 commits)")

---

Tags

laravelnotificationserror-monitoringerror handlingexception handlersupport-ticketsescalationsms-alerts

### Embed Badge

![Health badge](/badges/tishmalo-escalation-matrix/health.svg)

```
[![Health](https://phpackages.com/badges/tishmalo-escalation-matrix/health.svg)](https://phpackages.com/packages/tishmalo-escalation-matrix)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[masterro/laravel-mail-viewer

Easily view in browser outgoing emails.

6392.1k](/packages/masterro-laravel-mail-viewer)[illuminated/console-logger

Logging and Notifications for Laravel Console Commands.

8674.9k](/packages/illuminated-console-logger)[api-platform/laravel

API Platform support for Laravel

59126.4k6](/packages/api-platform-laravel)[shaffe/laravel-mail-log-channel

A package to support logging via email in Laravel

1286.2k](/packages/shaffe-laravel-mail-log-channel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)