Merge pull request #7 from codex-team/feature/laravel-before-send

Add `before_send_service` support in Laravel provider

Author: pavelzotikov

README.md

@@ -1,25 +1,47 @@
-**This project is currently in the testing phase and may undergo changes.**
-
 # Hawk Laravel
 
-Laravel errors Catcher for [Hawk.so](https://hawk.so).
+[![Latest Version on Packagist](https://img.shields.io/packagist/v/codex-team/hawk.laravel.svg?style=flat-square)](https://packagist.org/packages/codex-team/hawk.laravel)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
+[![PHP Version](https://img.shields.io/packagist/php-v/codex-team/hawk.laravel?style=flat-square)](https://www.php.net/)
+
+Laravel error catcher for [Hawk.so](https://hawk.so).
 
 ## Setup
 
-1. [Register](https://garage.hawk.so/sign-up) an account, create a Project and get an Integration Token.
+---
 
-2. Install SDK via [composer](https://getcomposer.org) to install the Catcher
+1. [Register](https://garage.hawk.so/sign-up) an account, create a project, and get an **Integration Token**.
+2. Install the SDK via [Composer](https://getcomposer.org):
 
-- Catcher provides support for PHP 7.2 or later
-- Your Laravel version needs to be 11.x or higher
+   ```bash
+   composer require codex-team/hawk.laravel
+   ```
 
-### Install command
+### Requirements
 
-```bash
-$ composer require codex-team/hawk.laravel
-```
+- PHP **7.2+**
+- Laravel **11.x+**
+
+## Features
+
+---
 
-To enable capturing unhandled exceptions for reporting to `Hawk`, modify your `bootstrap/app.php` file as follows:
+- 🦅 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
 <?php
@@ -39,12 +61,13 @@ return Application::configure(basePath: dirname(__DIR__))
     })
     ->withExceptions(function (Exceptions $exceptions) {
         HawkBundle\Integration::handles($exceptions);
-    })->create();
+    })
+    ->create();
 ```
 
 ### Register the Service Provider
 
-To complete the setup, add the `Hawk` service provider to your `config/app.php` or `bootstrap/providers.php` file in the providers array:
+Add the `Hawk` service provider to your `config/app.php` or `bootstrap/providers.php`:
 
 ```php
 'providers' => [
@@ -53,34 +76,143 @@ To complete the setup, add the `Hawk` service provider to your `config/app.php`
 ],
 ```
 
-### Configuration
+### Publish configuration
 
-Set up Hawk using the following command:
+Run:
 
 ```bash
-$ php artisan hawkbundle:publish
+php artisan hawkbundle:publish
 ```
 
-This will create the configuration file (`config/hawk.php`), and you can manually add the `HAWK_TOKEN` in your `.env` file:
+This will create `config/hawk.php`.  
+Then add your token in `.env`:
 
 ```env
-HAWK_TOKEN=<your integration token>
+HAWK_TOKEN=<your_integration_token>
+```
+
+## Usage
+
+---
+
+### Adding User & Context Information
+
+```php
+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`:
+
+```php
+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);
+        }
+    }
+}
 ```
 
-## Issues and improvements
+### Sending Custom Messages
 
-Feel free to ask questions or improve the project.
+```php
+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
+<?php
+
+namespace App\Hawk;
+
+use Hawk\EventPayload;
+use HawkBundle\Services\BeforeSendServiceInterface;
 
-## Links
+class BeforeSendService implements BeforeSendServiceInterface
+{
+    public function __invoke(EventPayload $eventPayload): ?EventPayload
+    {
+        $user = $eventPayload->getUser();
 
-Repository: https://github.com/codex-team/hawk.laravel
+        // Remove sensitive data
+        if (!empty($user['email'])) {
+            unset($user['email']);
+            $eventPayload->setUser($user);
+        }
 
-Report a bug: https://github.com/codex-team/hawk.laravel/issues
+        // Skip sending in specific cases
+        if ($eventPayload->getContext()['skip_sending'] ?? false) {
+            return null;
+        }
 
-Composer Package: https://packagist.org/packages/codex-team/hawk.laravel
+        return $eventPayload;
+    }
+}
+```
+
+Register it in `config/hawk.php`:
+
+```php
+return [
+    'integration_token' => env('HAWK_TOKEN'),
+    'before_send_service' => \App\Hawk\BeforeSendService::class,
+];
+```
+
+## Issues & Contributions
 
-CodeX Team: https://codex.so
+---
+
+- Found a bug? [Open an issue](https://github.com/codex-team/hawk.laravel/issues)
+- Want to improve the package? Pull requests are welcome!
+
+## Useful Links
+
+---
+
+- **Repository:** [github.com/codex-team/hawk.laravel](https://github.com/codex-team/hawk.laravel)
+- **Composer Package:** [packagist.org/packages/codex-team/hawk.laravel](https://packagist.org/packages/codex-team/hawk.laravel)
+- **CodeX Team:** [codex.so](https://codex.so)
 
 ## License
 
-MIT
+---
+
+[MIT](LICENSE)

composer.json

@@ -3,7 +3,7 @@
     "description": "Laravel errors Catcher module for Hawk.so",
     "keywords": ["hawk", "php", "error", "catcher", "monolog", "laravel"],
     "type": "library",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "license": "MIT",
     "require": {
         "php": "^7.2 || ^8.0",

config/hawk.php

@@ -1,5 +1,6 @@
 <?php
 
 return [
-    'integration_token' => env('HAWK_TOKEN', '')
+    'integration_token' => env('HAWK_TOKEN', ''),
+    'before_send_service' => null
 ];

src/ErrorLoggerServiceProvider.php

@@ -6,6 +6,7 @@
 
 use HawkBundle\Console\Commands\PublishHawkConfig;
 use HawkBundle\Handlers\ErrorHandler;
+use HawkBundle\Services\BeforeSendServiceInterface;
 use HawkBundle\Services\BreadcrumbsCollector;
 use HawkBundle\Services\DataFilter;
 use HawkBundle\Services\ErrorLoggerService;
@@ -16,6 +17,7 @@
 use Illuminate\Queue\Events\JobProcessing;
 use Illuminate\Queue\Events\JobFailed;
 use Illuminate\Log\Events\MessageLogged;
+use InvalidArgumentException;
 
 class ErrorLoggerServiceProvider extends ServiceProvider
 {
@@ -49,9 +51,31 @@ public function boot()
         $this->app->singleton(Catcher::class, function ($app) {
             $breadcrumbsCollector = $app->make(BreadcrumbsCollector::class);
 
-            return Catcher::init([
-                'integrationToken' => config('hawk.integration_token') ?: ''
-            ], $breadcrumbsCollector);
+            $options = [
+                'integrationToken' => config('hawk.integration_token') ?: '',
+            ];
+
+            $beforeSendService = config('hawk.before_send_service');
+            if (!empty($beforeSendService)) {
+                if (!class_exists($beforeSendService)) {
+                    throw new InvalidArgumentException(sprintf(
+                        'The before_send_service class "%s" does not exist.',
+                        $beforeSendService
+                    ));
+                }
+
+                if (!is_subclass_of($beforeSendService, BeforeSendServiceInterface::class)) {
+                    throw new InvalidArgumentException(sprintf(
+                        'The service "%s" must implement "%s".',
+                        $beforeSendService,
+                        BeforeSendServiceInterface::class
+                    ));
+                }
+
+                $options['before_send'] = $app->make($beforeSendService);
+            }
+
+            return Catcher::init($options, $breadcrumbsCollector);
         });
 
         $this->app->singleton('Illuminate\Contracts\Debug\ExceptionHandler', function ($app) {

src/Services/BeforeSendServiceInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HawkBundle\Services;
+
+use Hawk\EventPayload;
+
+interface BeforeSendServiceInterface
+{
+    public function __invoke(EventPayload $eventPayload): ?EventPayload;
+}