PHPackages                             mzshovon/laravel-trycatcher - 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. [Logging & Monitoring](/categories/logging)
4. /
5. mzshovon/laravel-trycatcher

ActiveLibrary[Logging & Monitoring](/categories/logging)

mzshovon/laravel-trycatcher
===========================

A lightweight exception guard for Laravel to simplify try-catch handling with logging and policies.

v1.0.4(6mo ago)010MITPHPPHP >=8.0

Since Oct 2Pushed 6mo agoCompare

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

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

Laravel TryCatcher
------------------

[](#laravel-trycatcher)

A lightweight exception guard for Laravel to simplify try/catch handling with consistent logging, safe responses, and attribute-driven policies.

### Why this package?

[](#why-this-package)

- **Eliminate boilerplate**: Replace repetitive try/catch blocks with concise guards
- **Consistent behavior**: Centralized policies for logging and responses
- **Flexible usage**: Use a Facade, helper, or trait with PHP 8 attributes
- **Production-safe**: Return safe messages in production without leaking traces
- **Persistent logs**: Store errors in `error_logs` table and Laravel logs

---

### Requirements

[](#requirements)

- PHP >= 8.0
- Laravel 9+ (auto-discovery enabled)

---

### Installation

[](#installation)

```
composer require mzshovon/laravel-trycatcher

```

The package supports Laravel package discovery. No manual provider registration is required.

Publish configuration and migrations:

```
php artisan vendor:publish --provider="Mzshovon\LaravelTryCatcher\ExceptionGuardServiceProvider" --tag=config
php artisan vendor:publish --provider="Mzshovon\LaravelTryCatcher\ExceptionGuardServiceProvider" --tag=migrations
php artisan migrate

```

---

### Configuration

[](#configuration)

Published to `config/exception-guard.php`:

```
return [
    'default_policy' => \Mzshovon\LaravelTryCatcher\Policies\ExceptionPolicy::THROW,
    'prod_policy' => \Mzshovon\LaravelTryCatcher\Policies\ExceptionPolicy::PROD_SAFE,
    'log_channel' => env('EXCEPTION_GUARD_LOG_CHANNEL', 'stack'),
    'integrations' => [
        'sentry' => env('SENTRY_DSN') ? true : false,
        'slack' => env('EXCEPTION_GUARD_SLACK_WEBHOOK') ? true : false,
    ],
    'safe_prod_guard' => 1,
];

```

- **default\_policy**: Used when no explicit policy/attribute is found
- **prod\_policy**: Recommended production-safe policy
- **safe\_prod\_guard**: When enabled and `app.env=production`, responses avoid traces regardless of requested policy

---

### Policies

[](#policies)

Available values in `\Mzshovon\LaravelTryCatcher\Policies\ExceptionPolicy`:

- `THROW`: Rethrow to Laravel’s handler
- `LOG`: Persist to DB and Laravel log (no stack trace in DB)
- `LOG_WITH_TRACE`: Persist to DB and Laravel log with stack trace
- `EXCEPTION_ONLY`: Return structured error payload (includes trace only when `app.debug=true`)
- `PROD_SAFE`: Log minimally and return a safe generic message
- `LOG_AND_THROW`: Log then rethrow

Note: When `safe_prod_guard` is enabled and the app is in production, responses are converted to a safe generic payload even if a policy would otherwise include details.

---

### Usage

[](#usage)

#### 1) Trait + Attribute

[](#1-trait--attribute)

Annotate methods with a policy and call them normally; exceptions will be intercepted and handled.

```
use Mzshovon\LaravelTryCatcher\Traits\Guardable;
use Mzshovon\LaravelTryCatcher\Attributes\ExceptionPolicyAttr;
use Mzshovon\LaravelTryCatcher\Policies\ExceptionPolicy;

class PaymentService
{
    use Guardable;

    #[ExceptionPolicyAttr(ExceptionPolicy::LOG_AND_THROW, options: ['context' => ['service' => 'payment']])]
    protected function charge(array $payload)
    {
        // ... risky operation ...
        return 'ok';
    }

    public function runCharge(array $payload)
    {
        // Will honor the attribute policy
        return $this->runGuardedMethod('charge', [$payload]);
    }
}

```

##### Protected and parent methods

[](#protected-and-parent-methods)

`runGuardedMethod` supports calling protected/private methods (including those declared on a parent class). The trait uses reflection and will set accessibility when required.

```
use Mzshovon\LaravelTryCatcher\Traits\Guardable;
use Mzshovon\LaravelTryCatcher\Policies\ExceptionPolicy;

abstract class BaseService
{
    use Guardable;

    // Declared in parent, not public
    #[\Mzshovon\LaravelTryCatcher\Attributes\ExceptionPolicyAttr(ExceptionPolicy::LOG)]
    protected function persist(array $data)
    {
        // ... risky work ...
        return 'saved';
    }
}

class UserService extends BaseService
{
    public function save(array $data)
    {
        // Calls protected parent method with args; attribute is honored
        return $this->runGuardedMethod('persist', [$data]);
    }
}

```

#### 2) Facade

[](#2-facade)

```
use Guard; // alias of \Mzshovon\LaravelTryCatcher\Facades\Guard
use Mzshovon\LaravelTryCatcher\Policies\ExceptionPolicy;

$result = Guard::run(function () {
    // risky work
    return doSomething();
}, ExceptionPolicy::LOG_WITH_TRACE, [
    'context' => ['user_id' => auth()->id()],
    'status' => 500,
]);

```

#### 3) Helper

[](#3-helper)

```
use Mzshovon\LaravelTryCatcher\Policies\ExceptionPolicy;

$response = guarded(function () {
    return doAnotherThing();
}, ExceptionPolicy::PROD_SAFE, [
    'message' => 'Please try again later',
    'status' => 422,
]);

```

You can also pass method callables. If no policy is provided, the helper attempts to discover an `ExceptionPolicyAttr` attribute on that method and falls back to `default_policy` otherwise.

Alternatively, when calling methods directly on an object using `Guardable`, the magic `__call` will intercept and apply the attribute policy automatically.

##### Passing arguments and runtime objects

[](#passing-arguments-and-runtime-objects)

- Attributes in PHP cannot accept runtime objects; they only allow constant expressions. If you need to work with runtime object references (e.g., a repository or DTO), pass them as method arguments and invoke via `runGuardedMethod`:

```
use Mzshovon\LaravelTryCatcher\Policies\ExceptionPolicy;

class ReportService
{
    use \Mzshovon\LaravelTryCatcher\Traits\Guardable;

    // No attribute here; we want dynamic control
    protected function generate($reportGenerator, array $params)
    {
        return $reportGenerator->build($params);
    }

    public function safeGenerate($reportGenerator, array $params)
    {
        return $this->runGuardedMethod(
            'generate',
            [$reportGenerator, $params],
            ExceptionPolicy::PROD_SAFE,
            [
                'context' => ['type' => 'report'],
                'message' => 'Report generation failed. Please try again later.',
                'status' => 503,
            ]
        );
    }
}

```

- Alternatively, wrap your logic in a closure and use the `guarded()` helper or the `Guard` facade when you need full control over captured variables.

---

### Options

[](#options)

Pass via the third parameter to guards/handlers or via the attribute’s `options`:

- `context` (array): Extra data included in logs
- `level` (string): Log level persisted to DB (default `error`)
- `status` (int): HTTP status for JSON responses
- `message` (string): Safe message for production responses

---

### Database Logging

[](#database-logging)

Errors are persisted in `error_logs` with the following schema:

```
$table->id();
$table->string('level')->nullable();
$table->string('message');
$table->text('trace')->nullable();
$table->json('context')->nullable();
$table->timestamps();

```

Model: `\Mzshovon\LaravelTryCatcher\Models\ErrorLog` (casts `context` to array).

On any failure to persist, the package falls back to Laravel file logging to avoid losing error details.

---

### JSON Response Shape

[](#json-response-shape)

Non-throwing policies return a JSON response similar to:

```
{
  "error": true,
  "message": "Something went wrong.",
  "trace": [] // included only when applicable and app.debug=true
}

```

In production with `safe_prod_guard` enabled, responses omit traces and use the provided `message` option or a generic message.

---

### Testing

[](#testing)

- Use policies like `EXCEPTION_ONLY` to assert structured error payloads
- Seed a failure and assert a row exists in `error_logs`
- In production-like tests, enable `safe_prod_guard` and assert generic responses

---

### License

[](#license)

Licensed under the MIT License. See `LICENSE`.

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance66

Regular maintenance activity

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

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

Every ~4 days

Total

6

Last Release

201d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/befb2fb4fd7118fc67269f07b7f0c69f03db769df209d1ba58dacf7f1bb33d5e?d=identicon)[mohammad moniruzzaman](/maintainers/mohammad%20moniruzzaman)

---

Top Contributors

[![mzshovon](https://avatars.githubusercontent.com/u/46594039?v=4)](https://github.com/mzshovon "mzshovon (12 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mzshovon-laravel-trycatcher/health.svg)

```
[![Health](https://phpackages.com/badges/mzshovon-laravel-trycatcher/health.svg)](https://phpackages.com/packages/mzshovon-laravel-trycatcher)
```

###  Alternatives

[psr/log

Common interface for logging libraries

10.4k1.2B9.2k](/packages/psr-log)[itsgoingd/clockwork

php dev tools in your browser

5.9k27.6M94](/packages/itsgoingd-clockwork)[graylog2/gelf-php

A php implementation to send log-messages to a GELF compatible backend like Graylog2.

41838.2M138](/packages/graylog2-gelf-php)[bugsnag/bugsnag-psr-logger

Official Bugsnag PHP PSR Logger.

32132.5M2](/packages/bugsnag-bugsnag-psr-logger)[consolidation/log

Improved Psr-3 / Psr\\Log logger based on Symfony Console components.

15462.2M7](/packages/consolidation-log)[datadog/php-datadogstatsd

An extremely simple PHP datadogstatsd client

19124.6M15](/packages/datadog-php-datadogstatsd)

PHPackages © 2026

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