Hawk Laravel

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 8.2+ for Laravel 11 and 12
• PHP 8.3+ for Laravel 13
• Laravel 11.x, 12.x, 13.x for the documented setup below

Composer constraints for legacy Illuminate 6.x-10.x are preserved for existing installations with their own framework PHP requirements.

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, 12, and 13 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

For Laravel 11-13, add the Hawk service provider to bootstrap/providers.php:

<?php

return [
    App\Providers\AppServiceProvider::class,
    HawkBundle\ErrorLoggerServiceProvider::class,
];

For older Laravel applications using config/app.php, add the provider to the providers list:

'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

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for the full text.