codex-team/hawk.php

PHP errors Catcher module for Hawk.so

2.3.0 2026-08-13 15:10 UTC

Requires

• php: ^7.2 || ^8.0
• ext-json: *
• jean85/pretty-package-versions: ^1.5 || ^2.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.15
• phpunit/phpunit: ^8.2
• symfony/var-dumper: ^5.2

Suggests

• ext-curl: Required to use the default CurlTransport. Not needed when providing a custom transport.

MIT

• php
• error
• hawk
• catcher

Published on Packagist.org on 2026-08-13 15:10 UTC

README

PHP errors Catcher for Hawk.so.

Setup

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

2. Install SDK via composer to install the Catcher

Catcher provides support for PHP 7.2 or later

$ composer require codex-team/hawk.php

Configuration

\Hawk\Catcher::init([
    'integrationToken' => 'your integration token'
]);

Passing custom Transport

The default transport requires the ext-curl PHP extension. If ext-curl is unavailable, provide a custom transport via the transport option.

You can also provide your own transport by implementing TransportInterface. Custom transports own their endpoint and timeout configuration, so the url and timeout options are used only by the default transport.

For example, install a PHP-version-compatible Guzzle release in your application and wrap it with a custom transport:

use Hawk\Event;
use Hawk\Options;
use Hawk\Transport\TransportInterface;

class CustomGuzzleTransport implements TransportInterface
{
    private $url;
    private $client;

    public function __construct(string $url = Options::DEFAULT_URL)
    {
        $this->url = $url;
        $this->client = new \GuzzleHttp\Client();
    }

    public function getUrl(): string
    {
        return $this->url;
    }

    public function send(Event $event)
    {
        $this->client->request('POST', $this->url, [
            'headers' => [
                'Content-Type' => 'application/json',
            ],
            'body' => json_encode($event, JSON_UNESCAPED_UNICODE),
        ]);
    }
}

\Hawk\Catcher::init([
    'integrationToken' => 'your integration token',
    'transport' => new CustomGuzzleTransport(),
]);

Passing User and Context

After initialization you can set user or context for any event that will be send to Hawk

\Hawk\Catcher::get()
    ->setUser([
        'name' => 'user name',
        'photo' => 'user photo',
    ])
    ->setContext([
        ...
    ]);

Send events and exceptions manually

Use sendException method to send any caught exception

try {
    throw new Exception("Error Processing Request", 1);
} catch (Exception $e) {
    \Hawk\Catcher::get()->sendException($e);
}

Use sendEvent method to send any data (logs, notices or something else)

\Hawk\Catcher::get()->sendMessage('your message', [
    ... // Context
]);

Filtering sensitive information

Use the beforeSend hook to filter any data you don't want to send to Hawk. Use setters to clear any property.

\Hawk\Catcher::init([
    // ...
    'beforeSend' => function (\Hawk\EventPayload $eventPayload) {
        $user = $eventPayload->getUser();
        
        if (!empty($user['email'])){
            unset($user['email']);
        
            $eventPayload->setUser($user);
        }

        return $eventPayload;
    }
]);

Issues and improvements

Feel free to ask questions or improve the project.

Links

Repository: https://github.com/codex-team/hawk.php

Report a bug: https://github.com/codex-team/hawk.php/issues

Composer Package: https://packagist.org/packages/codex-team/hawk.php

CodeX Team: https://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.