|
| 1 | +# CakePHP Sentry Plugin |
| 2 | +CakePHP integration for Sentry. |
| 3 | + |
| 4 | +ℹ️ This is a refactored version of https://github.com/Connehito/cake-sentry to remove deprecation warnings introduced in CakePHP 4.4 ℹ️ |
| 5 | + |
| 6 | +## Requirements |
| 7 | +- PHP 7.4+ / PHP 8.0+ |
| 8 | +- CakePHP 4.4+ |
| 9 | +- and a [Sentry](https://sentry.io) account |
| 10 | + |
| 11 | +## Installation |
| 12 | +### With composer install. |
| 13 | +``` |
| 14 | +composer require lordsimal/cakephp-sentry |
| 15 | +``` |
| 16 | + |
| 17 | +## Usage |
| 18 | + |
| 19 | +### Set config files. |
| 20 | +```php |
| 21 | +// in `config/app.php` |
| 22 | +return [ |
| 23 | + 'Sentry' => [ |
| 24 | + 'dsn' => '<sentry-dsn-url>' |
| 25 | + ] |
| 26 | +]; |
| 27 | +``` |
| 28 | + |
| 29 | +### Loading plugin. |
| 30 | +In Application.php |
| 31 | +```php |
| 32 | +public function bootstrap() |
| 33 | +{ |
| 34 | + parent::bootstrap(); |
| 35 | + |
| 36 | + $this->addPlugin(\CakeSentry\Plugin::class); |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +Or use the cake CLI. |
| 41 | +``` |
| 42 | +bin/cake plugin load LordSimal/CakeSentry |
| 43 | +``` |
| 44 | + |
| 45 | +That's all! 🎉 |
| 46 | + |
| 47 | +⚠️️ If events (error/exception) are not captured in Sentry try changing the order in which the plugins are loaded. |
| 48 | + |
| 49 | +### Advanced Usage |
| 50 | + |
| 51 | +#### Ignore specific exceptions |
| 52 | +You can filter out noisy exceptions which should not be debugged further. |
| 53 | + |
| 54 | +```php |
| 55 | +// in `config/app.php` |
| 56 | +'Error' => [ |
| 57 | + 'skipLog' => [ |
| 58 | + NotFoundException::class, |
| 59 | + MissingRouteException::class, |
| 60 | + MissingControllerException::class, |
| 61 | + ], |
| 62 | +] |
| 63 | +``` |
| 64 | + |
| 65 | +Also see [CakePHP Cookbook](https://book.cakephp.org/4/en/development/errors.html#error-exception-configuration) |
| 66 | + |
| 67 | +### Set Options |
| 68 | +Everything inside the `'Sentry'` configuration key will be passed to `\Sentry\init()`. |
| 69 | +Please check Sentry's official documentation on [about configuration](https://docs.sentry.io/error-reporting/configuration/?platform=php) and [about php-sdk's configuraion](https://docs.sentry.io/platforms/php/#php-specific-options). |
| 70 | + |
| 71 | +CakeSentry also provides custom event hooks to set dynamic values. |
| 72 | + |
| 73 | +| Event Name | Description | |
| 74 | +|-----------------------------------|------------------------------------------------------| |
| 75 | +| `CakeSentry.Client.afterSetup` | General config for e.g. a release info | |
| 76 | +| `CakeSentry.Client.beforeCapture` | Before an error or exception is being sent to sentry | |
| 77 | +| `CakeSentry.Client.afterCapture` | After an error or exception has been sent to sentry | |
| 78 | + |
| 79 | +### Example for `CakeSentry.Client.afterSetup` |
| 80 | + |
| 81 | +```php |
| 82 | +use Cake\Event\Event; |
| 83 | +use Cake\Event\EventListenerInterface; |
| 84 | + |
| 85 | +class SentryOptionsContext implements EventListenerInterface |
| 86 | +{ |
| 87 | + public function implementedEvents(): array |
| 88 | + { |
| 89 | + return [ |
| 90 | + 'CakeSentry.Client.afterSetup' => 'setServerContext', |
| 91 | + ]; |
| 92 | + } |
| 93 | + |
| 94 | + public function setServerContext(Event $event): void |
| 95 | + { |
| 96 | + /** @var Client $subject */ |
| 97 | + $subject = $event->getSubject(); |
| 98 | + $options = $subject->getHub()->getClient()->getOptions(); |
| 99 | + |
| 100 | + $options->setEnvironment('test_app'); |
| 101 | + $options->setRelease('3.0.0@dev'); |
| 102 | + } |
| 103 | +} |
| 104 | +``` |
| 105 | + |
| 106 | +And in `config/bootstrap.php` |
| 107 | +```php |
| 108 | +\Cake\Event\EventManager::instance()->on(new SentryOptionsContext()); |
| 109 | +``` |
| 110 | + |
| 111 | +### Example for `CakeSentry.Client.beforeCapture` |
| 112 | + |
| 113 | +```php |
| 114 | +use Cake\Event\Event; |
| 115 | +use Cake\Event\EventListenerInterface; |
| 116 | +use Cake\Http\ServerRequest; |
| 117 | +use Cake\Http\ServerRequestFactory; |
| 118 | +use Sentry\State\Scope; |
| 119 | + |
| 120 | +use function Sentry\configureScope as sentryConfigureScope; |
| 121 | + |
| 122 | +class SentryErrorContext implements EventListenerInterface |
| 123 | +{ |
| 124 | + public function implementedEvents(): array |
| 125 | + { |
| 126 | + return [ |
| 127 | + 'CakeSentry.Client.beforeCapture' => 'setContext', |
| 128 | + ]; |
| 129 | + } |
| 130 | + |
| 131 | + public function setContext(Event $event): void |
| 132 | + { |
| 133 | + if (PHP_SAPI !== 'cli') { |
| 134 | + /** @var ServerRequest $request */ |
| 135 | + $request = $event->getData('request') ?? ServerRequestFactory::fromGlobals(); |
| 136 | + $request->trustProxy = true; |
| 137 | + |
| 138 | + sentryConfigureScope(function (Scope $scope) use ($request, $event) { |
| 139 | + $scope->setTag('app_version', $request->getHeaderLine('App-Version') ?: 1.0); |
| 140 | + $exception = $event->getData('exception'); |
| 141 | + if ($exception) { |
| 142 | + assert($exception instanceof \Exception); |
| 143 | + $scope->setTag('status', $exception->getCode()); |
| 144 | + } |
| 145 | + $scope->setUser(['ip_address' => $request->clientIp()]); |
| 146 | + $scope->setExtras([ |
| 147 | + 'foo' => 'bar', |
| 148 | + 'request attributes' => $request->getAttributes(), |
| 149 | + ]); |
| 150 | + }); |
| 151 | + } |
| 152 | + } |
| 153 | +} |
| 154 | +``` |
| 155 | + |
| 156 | +And in `config/bootstrap.php` |
| 157 | +```php |
| 158 | +\Cake\Event\EventManager::instance()->on(new SentryErrorContext()); |
| 159 | +``` |
| 160 | + |
| 161 | +### Example for `CakeSentry.Client.afterCapture` |
| 162 | + |
| 163 | +```php |
| 164 | +class SentryErrorContext implements EventListenerInterface |
| 165 | +{ |
| 166 | + public function implementedEvents(): array |
| 167 | + { |
| 168 | + return [ |
| 169 | + 'CakeSentry.Client.afterCapture' => 'callbackAfterCapture', |
| 170 | + ]; |
| 171 | + } |
| 172 | + |
| 173 | + public function callbackAfterCapture(Event $event): void |
| 174 | + { |
| 175 | + $lastEventId = $event->getData('lastEventId'); |
| 176 | + } |
| 177 | +} |
| 178 | +``` |
| 179 | + |
| 180 | +## License |
| 181 | +The plugin is available as open source under the terms of the [MIT License](https://github.com/lordsimal/cakephp-sentry/blob/master/LICENSE). |
0 commit comments