From abe24c846c390e6f95de3af8622c3aad817559bc Mon Sep 17 00:00:00 2001 From: Martin Linzmayer Date: Mon, 2 Mar 2026 16:47:47 +0100 Subject: [PATCH] ref: laravel closures and config caching --- .../laravel/configuration/laravel-options.mdx | 68 ++++++------------- .../before-send-check-in/php.laravel.mdx | 30 ++++---- .../before-send-fingerprint/php.laravel.mdx | 24 ++++--- .../before-send-hint/php.laravel.mdx | 26 +++---- .../before-send-transaction/php.laravel.mdx | 20 +++--- .../configuration/before-send/php.laravel.mdx | 20 +++--- .../before-breadcrumb/php.laravel.mdx | 18 ++--- .../logs/options/php.laravel.mdx | 23 +++---- .../metrics/options/php.laravel.mdx | 29 ++++---- .../php.laravel.mdx | 27 ++++---- .../configure-sample-rate/php.laravel.mdx | 21 +++--- .../traces-sampler-as-filter/php.laravel.mdx | 39 ++++++----- 12 files changed, 170 insertions(+), 175 deletions(-) diff --git a/docs/platforms/php/guides/laravel/configuration/laravel-options.mdx b/docs/platforms/php/guides/laravel/configuration/laravel-options.mdx index ef932cea9ca8b..15a1e405e78ec 100644 --- a/docs/platforms/php/guides/laravel/configuration/laravel-options.mdx +++ b/docs/platforms/php/guides/laravel/configuration/laravel-options.mdx @@ -54,31 +54,33 @@ SENTRY_TRACES_SAMPLE_RATE=1.0 ### Advanced Sample Rate -If you want more control over which requests are monitored, you can use the [`traces_sampler`](/platforms/php/guides/laravel/configuration/options/#traces-sampler) option: +If you want more control over which requests are monitored, use the [`traces_sampler`](/platforms/php/guides/laravel/configuration/options/#traces-sampler) option as a callable: ```php {filename:config/sentry.php} -'traces_sampler' => function (\Sentry\Tracing\SamplingContext $context): float { - // We always sample if the front-end indicates it was sampled to have full traces front to back - if ($context->getParentSampled()) { - return 1.0; - } +'traces_sampler' => [App\Exceptions\Sentry::class, 'tracesSampler'], +``` - if (some_condition()) { - // Drop this transaction, by setting its sample rate to 0 - return 0.0; +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + public static function tracesSampler(\Sentry\Tracing\SamplingContext $context): float + { + // Keep front-end and back-end traces connected. + if ($context->getParentSampled()) { + return 1.0; + } + + if (some_condition()) { + // Drop this transaction. + return 0.0; + } + + // Default sample rate for all other transactions. + return 0.25; } - - // Default sample rate for all other transactions - return 0.25; -}, +} ``` - - -Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). - - - ### More Configuration You can also configure which parts of your application are traced automatically. @@ -136,31 +138,3 @@ These settings have no effect if `SENTRY_TRACES_SAMPLE_RATE` is set to `0.0` or 'default_integrations' => env('SENTRY_TRACE_DEFAULT_INTEGRATIONS_ENABLED', true), ], ``` - -## Closures and Config Caching - -Sometimes the SDK requires a closure as an option value. However, this causes problems when using `php artisan config:cache`, resulting in the `Your configuration files are not serializable` error. - -We can work around that by providing a callable instead of a closure. In this example we are using the `traces_sampler` option, but this can be used for any other option that accepts a closure: - -```php {filename:config/sentry.php} -'traces_sampler' => [App\Exceptions\Sentry::class, 'tracesSampler'], -``` - -This callable points to the `App\Exceptions\Sentry` class and the `tracesSampler` method: - -```php {filename:app/Exceptions/Sentry.php} - function (\Sentry\Event $event): ?\Sentry\Event { - $checkIn = $event->getCheckIn(); - $checkInEnvironment = $checkIn->getEnvironment(); - - if ($checkInEnvironment !== 'production') { - return null; - } - - return $event; -}, +'before_send_check_in' => [App\Exceptions\Sentry::class, 'beforeSendCheckIn'], ``` - +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + public static function beforeSendCheckIn(\Sentry\Event $event): ?\Sentry\Event + { + $checkIn = $event->getCheckIn(); + $checkInEnvironment = $checkIn->getEnvironment(); -Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). + if ($checkInEnvironment !== 'production') { + return null; + } - + return $event; + } +} +``` diff --git a/platform-includes/configuration/before-send-fingerprint/php.laravel.mdx b/platform-includes/configuration/before-send-fingerprint/php.laravel.mdx index 2d11066de09ee..2e5bd3f9ea788 100644 --- a/platform-includes/configuration/before-send-fingerprint/php.laravel.mdx +++ b/platform-includes/configuration/before-send-fingerprint/php.laravel.mdx @@ -1,15 +1,17 @@ ```php {filename:config/sentry.php} -'before_send' => function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event { - if ($hint !== null && $hint->exception !== null && str_contains($hint->exception->getMessage(), 'database unavailable')) { - $event->setFingerprint(['database-unavailable']); - } - - return $event; -}, +'before_send' => [App\Exceptions\Sentry::class, 'beforeSend'], ``` - - -Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + public static function beforeSend(\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event + { + if ($hint !== null && $hint->exception !== null && str_contains($hint->exception->getMessage(), 'database unavailable')) { + $event->setFingerprint(['database-unavailable']); + } - + return $event; + } +} +``` diff --git a/platform-includes/configuration/before-send-hint/php.laravel.mdx b/platform-includes/configuration/before-send-hint/php.laravel.mdx index 23a54cd982504..b6498b2526028 100644 --- a/platform-includes/configuration/before-send-hint/php.laravel.mdx +++ b/platform-includes/configuration/before-send-hint/php.laravel.mdx @@ -1,16 +1,18 @@ ```php {filename:config/sentry.php} -'before_send' => function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event { - // Ignore the event if the original exception is an instance of MyException - if ($hint !== null && $hint->exception instanceof MyException) { - return null; - } - - return $event; -}, +'before_send' => [App\Exceptions\Sentry::class, 'beforeSend'], ``` - - -Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + public static function beforeSend(\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event + { + // Ignore the event if the original exception is an instance of MyException. + if ($hint !== null && $hint->exception instanceof MyException) { + return null; + } - + return $event; + } +} +``` diff --git a/platform-includes/configuration/before-send-transaction/php.laravel.mdx b/platform-includes/configuration/before-send-transaction/php.laravel.mdx index de3f1969a1840..fd110b9a7e8e2 100644 --- a/platform-includes/configuration/before-send-transaction/php.laravel.mdx +++ b/platform-includes/configuration/before-send-transaction/php.laravel.mdx @@ -1,13 +1,15 @@ -In the Laravel config, a closure can be used to modify the event or return a completely new one. If you return `null`, the event will be discarded. +In Laravel, use a callable to modify the transaction event or return a completely new one. If you return `null`, the event will be discarded. ```php {filename:config/sentry.php} -'before_send_transaction' => function (\Sentry\Event $transaction): ?\Sentry\Event { - return $transaction; -}, +'before_send_transaction' => [App\Exceptions\Sentry::class, 'beforeSendTransaction'], ``` - - -Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). - - +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + public static function beforeSendTransaction(\Sentry\Event $transaction): ?\Sentry\Event + { + return $transaction; + } +} +``` diff --git a/platform-includes/configuration/before-send/php.laravel.mdx b/platform-includes/configuration/before-send/php.laravel.mdx index a27193a54b11a..e72b8df056e0f 100644 --- a/platform-includes/configuration/before-send/php.laravel.mdx +++ b/platform-includes/configuration/before-send/php.laravel.mdx @@ -1,13 +1,15 @@ -In the Laravel config, a closure can be used to modify the event or return a completely new one. If you return `null`, the event will be discarded. +In Laravel, use a callable to modify the event or return a completely new one. If you return `null`, the event will be discarded. ```php {filename:config/sentry.php} -'before_send' => function (\Sentry\Event $event): ?\Sentry\Event { - return $event; -}, +'before_send' => [App\Exceptions\Sentry::class, 'beforeSend'], ``` - - -Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). - - +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + public static function beforeSend(\Sentry\Event $event): ?\Sentry\Event + { + return $event; + } +} +``` diff --git a/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/php.laravel.mdx b/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/php.laravel.mdx index 999c42170ff86..8f7d36fa2b5ce 100644 --- a/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/php.laravel.mdx +++ b/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/php.laravel.mdx @@ -1,11 +1,13 @@ ```php {filename:config/sentry.php} -'before_breadcrumb' => function (\Sentry\Breadcrumb $breadcrumb): ?\Sentry\Breadcrumb { - return $breadcrumb; -}, +'before_breadcrumb' => [App\Exceptions\Sentry::class, 'beforeBreadcrumb'], ``` - - -Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). - - +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + public static function beforeBreadcrumb(\Sentry\Breadcrumb $breadcrumb): ?\Sentry\Breadcrumb + { + return $breadcrumb; + } +} +``` diff --git a/platform-includes/logs/options/php.laravel.mdx b/platform-includes/logs/options/php.laravel.mdx index 7f6fca24b9806..18d9ac29e5c2f 100644 --- a/platform-includes/logs/options/php.laravel.mdx +++ b/platform-includes/logs/options/php.laravel.mdx @@ -3,23 +3,22 @@ To filter logs, or update them before they are sent to Sentry, you can use the `before_send_log` option. ```php {filename:config/sentry.php} - // ... - 'before_send_log' => function (\Sentry\Logs\Log $log): ?\Sentry\Logs\Log { +'before_send_log' => [App\Exceptions\Sentry::class, 'beforeSendLog'], +``` + +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + public static function beforeSendLog(\Sentry\Logs\Log $log): ?\Sentry\Logs\Log + { if ($log->getLevel() === \Sentry\Logs\LogLevel::info()) { - // Filter out all info logs + // Filter out all info logs. return null; } return $log; - }, - // ... -]); + } +} ``` - - -Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). - - - The `before_send_log` function receives a log object, and should return the log object if you want it to be sent to Sentry, or `null` if you want to discard it. diff --git a/platform-includes/metrics/options/php.laravel.mdx b/platform-includes/metrics/options/php.laravel.mdx index 425121fc0e770..90108c60150a9 100644 --- a/platform-includes/metrics/options/php.laravel.mdx +++ b/platform-includes/metrics/options/php.laravel.mdx @@ -2,21 +2,22 @@ To filter metrics, or update them before they are sent to Sentry, you can use the `before_send_metric` option. If the callback returns `null`, the metric is not emitted. Attributes can also be updated in the callback function. -```php -// ... -'before_send_metric' => static function (\Sentry\Metrics\Types\Metric $metric): ?\Sentry\Metrics\Types\Metric { - if ($metric->getName() === 'removed-metric') { - return null; - } - return $metric; -}, -// ... +```php {filename:config/sentry.php} +'before_send_metric' => [App\Exceptions\Sentry::class, 'beforeSendMetric'], ``` -The `before_send_metric` function receives a metric object, and should return the metric object if you want it to be sent to Sentry, or `null` if you want to discard it. - - +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + public static function beforeSendMetric(\Sentry\Metrics\Types\Metric $metric): ?\Sentry\Metrics\Types\Metric + { + if ($metric->getName() === 'removed-metric') { + return null; + } - Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). + return $metric; + } +} +``` - +The `before_send_metric` function receives a metric object, and should return the metric object if you want it to be sent to Sentry, or `null` if you want to discard it. diff --git a/platform-includes/performance/always-inherit-sampling-decision/php.laravel.mdx b/platform-includes/performance/always-inherit-sampling-decision/php.laravel.mdx index 30474994d651b..6d10f3be7dc51 100644 --- a/platform-includes/performance/always-inherit-sampling-decision/php.laravel.mdx +++ b/platform-includes/performance/always-inherit-sampling-decision/php.laravel.mdx @@ -1,16 +1,19 @@ ```php {filename:config/sentry.php} -'traces_sampler' => function (\Sentry\Tracing\SamplingContext $context): float { - // always inherit - if ($context->getParentSampled()) { - return 1.0; - } - - // the rest of sampling logic -}, +'traces_sampler' => [App\Exceptions\Sentry::class, 'tracesSampler'], ``` - - -Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + public static function tracesSampler(\Sentry\Tracing\SamplingContext $context): float + { + // Always inherit the parent sampling decision. + if ($context->getParentSampled()) { + return 1.0; + } - + // The rest of your sampling logic. + return 0.25; + } +} +``` diff --git a/platform-includes/performance/configure-sample-rate/php.laravel.mdx b/platform-includes/performance/configure-sample-rate/php.laravel.mdx index 1e439f40db5ef..e0039d3ffc486 100644 --- a/platform-includes/performance/configure-sample-rate/php.laravel.mdx +++ b/platform-includes/performance/configure-sample-rate/php.laravel.mdx @@ -1,14 +1,17 @@ ```php {filename:config/sentry.php} // Specify a fixed sample rate: 'traces_sample_rate' => 0.2, -// Or provide a custom sampler: -'traces_sampler' => function (\Sentry\Tracing\SamplingContext $context): float { - // return a number between 0 and 1 -}, +// Or provide a custom sampler as a callable: +'traces_sampler' => [App\Exceptions\Sentry::class, 'tracesSampler'], ``` - - -Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). - - +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + public static function tracesSampler(\Sentry\Tracing\SamplingContext $context): float + { + // Return a value between 0 and 1. + return $context->getParentSampled() ? 1.0 : 0.2; + } +} +``` diff --git a/platform-includes/performance/traces-sampler-as-filter/php.laravel.mdx b/platform-includes/performance/traces-sampler-as-filter/php.laravel.mdx index f097bbc9665aa..c6ceb52daef0b 100644 --- a/platform-includes/performance/traces-sampler-as-filter/php.laravel.mdx +++ b/platform-includes/performance/traces-sampler-as-filter/php.laravel.mdx @@ -1,23 +1,26 @@ ```php {filename:config/sentry.php} -'traces_sampler' => function (\Sentry\Tracing\SamplingContext $context): float { - if ($context->getParentSampled()) { - // If the parent transaction (for example a JavaScript front-end) - // is sampled, also sample the current transaction - return 1.0; - } - - if (some_condition()) { - // Drop this transaction, by setting its sample rate to 0 - return 0; - } - - // Default sample rate for all other transactions (replaces `traces_sample_rate`) - return 0.25; -}, +'traces_sampler' => [App\Exceptions\Sentry::class, 'tracesSampler'], ``` - +```php {filename:app/Exceptions/Sentry.php} +class Sentry +{ + // `traces_sampler` replaces `traces_sample_rate` when both are configured. + public static function tracesSampler(\Sentry\Tracing\SamplingContext $context): float + { + if ($context->getParentSampled()) { + // If the parent transaction (for example a JavaScript front-end) + // is sampled, also sample the current transaction. + return 1.0; + } -Learn more in [Closures and Config Caching](/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching). + if (some_condition()) { + // Drop this transaction by setting its sample rate to 0. + return 0.0; + } - + // Default sample rate for all other transactions. + return 0.25; + } +} +```