codex-team/hawk.laravel

Laravel errors Catcher module for Hawk.so

0.1.2 2025-09-25 11:33 UTC

Requires

• php: ^7.2 || ^8.0
• codex-team/hawk.php: ^2.2.9
• guzzlehttp/guzzle: ^6.0 || ^7.0
• guzzlehttp/psr7: ^2.1.1
• illuminate/support: ^6.0 | ^7.0 | ^8.0 | ^9.0 | ^10.0 | ^11.0 | ^12.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.19||^3.40

MIT

• php
• monolog
• error
• laravel
• hawk
• catcher

README

Laravel error catcher for Hawk.so.

Setup

1. Register an account, create a project, and get an Integration Token.

2. Install the SDK via Composer:

   composer require codex-team/hawk.laravel

Requirements

• PHP 7.2+
• Laravel 11.x+

Features

• 🦅 Automatic error catching
• 💎 Manual exception and message sending
• 🙂 Attaching user information
• 📦 Attaching additional context
• 🛡️ Sensitive data filtering
• 🌟 BeforeSend hook for event preprocessing
• 🗂️ Breadcrumbs collection (routes, queries, jobs, logs)
• ⚡ Laravel 11+ support

Configuration

Enable exception capturing

Update your bootstrap/app.php:

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        //
    })
    ->withExceptions(function (Exceptions $exceptions) {
        HawkBundle\Integration::handles($exceptions);
    })
    ->create();

Register the Service Provider

Add the Hawk service provider to your config/app.php or bootstrap/providers.php:

'providers' => [
    // Other service providers...
    HawkBundle\ErrorLoggerServiceProvider::class,
],

Publish configuration

Run:

php artisan hawkbundle:publish

This will create config/hawk.php.
Then add your token in .env:

HAWK_TOKEN=<your_integration_token>

Usage

Adding User & Context Information

app(\HawkBundle\Catcher::class)->setUser([
    'name' => 'John Doe',
    'photo' => 'https://example.com/avatar.png',
]);

app(\HawkBundle\Catcher::class)->setContext([
    'page' => 'checkout',
    'cart_id' => 123,
]);

Sending Exceptions Manually

Inject \HawkBundle\Catcher and call sendException:

use HawkBundle\Catcher;

class TestController extends Controller
{
    private Catcher $catcher;

    public function __construct(Catcher $catcher)
    {
        $this->catcher = $catcher;
    }

    public function test()
    {
        try {
            // Code that may fail
        } catch (\Exception $e) {
            $this->catcher->sendException($e);
        }
    }
}

Sending Custom Messages

app(\HawkBundle\Catcher::class)->sendMessage(
    'Checkout started',
    [
        'cart_id' => 123,
        'step' => 'payment',
    ]
);

BeforeSend Hook

If you want to modify or filter errors before they are sent to Hawk,
implement the BeforeSendServiceInterface.

Example:

<?php

namespace App\Hawk;

use Hawk\EventPayload;
use HawkBundle\Services\BeforeSendServiceInterface;

class BeforeSendService implements BeforeSendServiceInterface
{
    public function __invoke(EventPayload $eventPayload): ?EventPayload
    {
        $user = $eventPayload->getUser();

        // Remove sensitive data
        if (!empty($user['email'])) {
            unset($user['email']);
            $eventPayload->setUser($user);
        }

        // Skip sending in specific cases
        if ($eventPayload->getContext()['skip_sending'] ?? false) {
            return null;
        }

        return $eventPayload;
    }
}

Register it in config/hawk.php:

return [
    'integration_token' => env('HAWK_TOKEN'),
    'before_send_service' => \App\Hawk\BeforeSendService::class,
];

Issues & Contributions

• Found a bug? Open an issue
• Want to improve the package? Pull requests are welcome!

Useful Links

• Repository: github.com/codex-team/hawk.laravel
• Composer Package: packagist.org/packages/codex-team/hawk.laravel
• CodeX Team: codex.so

License

MIT