feat(scopes): introduce typed scopes

mago.toml

@@ -10,3 +10,8 @@ excludes = [
 
 [analyzer]
 baseline = "analysis-baseline.toml"
+ignore = [
+    { code = "no-value", pattern = "DebugType::getDebugType" },
+    "impossible-condition",
+    "redundant-logical-operation",
+]

src/Client.php

@@ -10,6 +10,7 @@
 use Sentry\Integration\IntegrationRegistry;
 use Sentry\Serializer\RepresentationSerializer;
 use Sentry\Serializer\RepresentationSerializerInterface;
+use Sentry\State\MergedScope;
 use Sentry\State\Scope;
 use Sentry\Transport\Result;
 use Sentry\Transport\TransportInterface;
@@ -140,7 +141,7 @@ public function getCspReportUrl(): ?string
     /**
      * {@inheritdoc}
      */
-    public function captureMessage(string $message, ?Severity $level = null, ?Scope $scope = null, ?EventHint $hint = null): ?EventId
+    public function captureMessage(string $message, ?Severity $level = null, ?MergedScope $scope = null, ?EventHint $hint = null): ?EventId
     {
         $event = Event::createEvent();
         $event->setMessage($message);
@@ -152,7 +153,7 @@ public function captureMessage(string $message, ?Severity $level = null, ?Scope
     /**
      * {@inheritdoc}
      */
-    public function captureException(\Throwable $exception, ?Scope $scope = null, ?EventHint $hint = null): ?EventId
+    public function captureException(\Throwable $exception, ?MergedScope $scope = null, ?EventHint $hint = null): ?EventId
     {
         $className = \get_class($exception);
         if ($this->shouldIgnoreException($className)) {
@@ -176,7 +177,7 @@ public function captureException(\Throwable $exception, ?Scope $scope = null, ?E
     /**
      * {@inheritdoc}
      */
-    public function captureEvent(Event $event, ?EventHint $hint = null, ?Scope $scope = null): ?EventId
+    public function captureEvent(Event $event, ?EventHint $hint = null, ?MergedScope $scope = null): ?EventId
     {
         // Client reports don't need to be augmented in the prepareEvent pipeline.
         if ($event->getType() !== EventType::clientReport()) {
@@ -208,7 +209,7 @@ public function captureEvent(Event $event, ?EventHint $hint = null, ?Scope $scop
     /**
      * {@inheritdoc}
      */
-    public function captureLastError(?Scope $scope = null, ?EventHint $hint = null): ?EventId
+    public function captureLastError(?MergedScope $scope = null, ?EventHint $hint = null): ?EventId
     {
         $error = error_get_last();
 
@@ -277,13 +278,13 @@ public function getSdkVersion(): string
     /**
      * Assembles an event and prepares it to be sent of to Sentry.
      *
-     * @param Event          $event The payload that will be converted to an Event
-     * @param EventHint|null $hint  May contain additional information about the event
-     * @param Scope|null     $scope Optional scope which enriches the Event
+     * @param Event            $event The payload that will be converted to an Event
+     * @param EventHint|null   $hint  May contain additional information about the event
+     * @param MergedScope|null $scope Optional scope which enriches the Event
      *
      * @return Event|null The prepared event object or null if it must be discarded
      */
-    private function prepareEvent(Event $event, ?EventHint $hint = null, ?Scope $scope = null): ?Event
+    private function prepareEvent(Event $event, ?EventHint $hint = null, ?MergedScope $scope = null): ?Event
     {
         if ($hint !== null) {
             if ($hint->exception !== null && empty($event->getExceptions())) {

src/ClientInterface.php

@@ -5,6 +5,7 @@
 namespace Sentry;
 
 use Sentry\Integration\IntegrationInterface;
+use Sentry\State\MergedScope;
 use Sentry\State\Scope;
 use Sentry\Transport\Result;
 
@@ -23,38 +24,38 @@ public function getCspReportUrl(): ?string;
     /**
      * Logs a message.
      *
-     * @param string         $message The message (primary description) for the event
-     * @param Severity|null  $level   The level of the message to be sent
-     * @param Scope|null     $scope   An optional scope keeping the state
-     * @param EventHint|null $hint    Object that can contain additional information about the event
+     * @param string           $message The message (primary description) for the event
+     * @param Severity|null    $level   The level of the message to be sent
+     * @param MergedScope|null $scope   An optional scope keeping the state
+     * @param EventHint|null   $hint    Object that can contain additional information about the event
      */
-    public function captureMessage(string $message, ?Severity $level = null, ?Scope $scope = null, ?EventHint $hint = null): ?EventId;
+    public function captureMessage(string $message, ?Severity $level = null, ?MergedScope $scope = null, ?EventHint $hint = null): ?EventId;
 
     /**
      * Logs an exception.
      *
-     * @param \Throwable     $exception The exception object
-     * @param Scope|null     $scope     An optional scope keeping the state
-     * @param EventHint|null $hint      Object that can contain additional information about the event
+     * @param \Throwable       $exception The exception object
+     * @param MergedScope|null $scope     An optional scope keeping the state
+     * @param EventHint|null   $hint      Object that can contain additional information about the event
      */
-    public function captureException(\Throwable $exception, ?Scope $scope = null, ?EventHint $hint = null): ?EventId;
+    public function captureException(\Throwable $exception, ?MergedScope $scope = null, ?EventHint $hint = null): ?EventId;
 
     /**
      * Logs the most recent error (obtained with {@link error_get_last}).
      *
-     * @param Scope|null     $scope An optional scope keeping the state
-     * @param EventHint|null $hint  Object that can contain additional information about the event
+     * @param MergedScope|null $scope An optional scope keeping the state
+     * @param EventHint|null   $hint  Object that can contain additional information about the event
      */
-    public function captureLastError(?Scope $scope = null, ?EventHint $hint = null): ?EventId;
+    public function captureLastError(?MergedScope $scope = null, ?EventHint $hint = null): ?EventId;
 
     /**
      * Captures a new event using the provided data.
      *
-     * @param Event          $event The event being captured
-     * @param EventHint|null $hint  May contain additional information about the event
-     * @param Scope|null     $scope An optional scope keeping the state
+     * @param Event            $event The event being captured
+     * @param EventHint|null   $hint  May contain additional information about the event
+     * @param MergedScope|null $scope An optional scope keeping the state
      */
-    public function captureEvent(Event $event, ?EventHint $hint = null, ?Scope $scope = null): ?EventId;
+    public function captureEvent(Event $event, ?EventHint $hint = null, ?MergedScope $scope = null): ?EventId;
 
     /**
      * Returns the integration instance if it is installed on the client.

src/Integration/AbstractErrorListenerIntegration.php

@@ -5,9 +5,10 @@
 namespace Sentry\Integration;
 
 use Sentry\Event;
+use Sentry\EventHint;
 use Sentry\ExceptionMechanism;
 use Sentry\State\EventCapturer;
-use Sentry\State\Scope;
+use Sentry\State\IsolationScope;
 
 use function Sentry\withIsolationScope;
 
@@ -18,8 +19,10 @@ abstract class AbstractErrorListenerIntegration implements IntegrationInterface
      */
     protected function captureException(\Throwable $exception): void
     {
-        withIsolationScope(function (Scope $scope) use ($exception): void {
-            $scope->addEventProcessor(\Closure::fromCallable([$this, 'addExceptionMechanismToEvent']));
+        withIsolationScope(function (IsolationScope $scope) use ($exception): void {
+            $scope->addEventProcessor(function (Event $event, EventHint $hint): Event {
+                return $this->addExceptionMechanismToEvent($event);
+            });
 
             EventCapturer::captureException($exception);
         });

src/Logs/LogsAggregator.php

@@ -10,6 +10,8 @@
 use Sentry\Event;
 use Sentry\EventId;
 use Sentry\SentrySdk;
+use Sentry\State\IsolationScope;
+use Sentry\State\MergedScope;
 use Sentry\State\Scope;
 use Sentry\Util\Arr;
 use Sentry\Util\Str;
@@ -42,7 +44,7 @@ public function add(
 
         $isolationScope = SentrySdk::getIsolationScope();
         $client = SentrySdk::getClient($isolationScope);
-        $scope = Scope::mergeScopes(SentrySdk::getGlobalScope(), $isolationScope);
+        $scope = SentrySdk::getGlobalScope()->merge($isolationScope);
 
         $options = $client->getOptions();
         $sdkLogger = $options->getLogger();
@@ -162,7 +164,7 @@ public function add(
         }
     }
 
-    public function flush(?ClientInterface $client = null, ?Scope $isolationScope = null): ?EventId
+    public function flush(?ClientInterface $client = null, ?IsolationScope $isolationScope = null): ?EventId
     {
         $logs = $this->logs;
 
@@ -174,7 +176,7 @@ public function flush(?ClientInterface $client = null, ?Scope $isolationScope =
         $client = $client ?? SentrySdk::getClient($isolationScope);
         $event = Event::createLogs()->setLogs($logs->drain());
 
-        return $client->captureEvent($event, null, Scope::mergeScopes(SentrySdk::getGlobalScope(), $isolationScope));
+        return $client->captureEvent($event, null, SentrySdk::getGlobalScope()->merge($isolationScope));
     }
 
     /**
@@ -188,7 +190,7 @@ public function all(): array
     /**
      * @return array{trace_id: string, parent_span_id: string|null}
      */
-    private function getTraceData(Scope $scope): array
+    private function getTraceData(MergedScope $scope): array
     {
         $span = $scope->getSpan();
 

src/Metrics/MetricsAggregator.php

@@ -13,7 +13,8 @@
 use Sentry\Metrics\Types\GaugeMetric;
 use Sentry\Metrics\Types\Metric;
 use Sentry\SentrySdk;
-use Sentry\State\Scope;
+use Sentry\State\IsolationScope;
+use Sentry\State\MergedScope;
 use Sentry\Tracing\SpanId;
 use Sentry\Tracing\TraceId;
 use Sentry\Unit;
@@ -53,7 +54,7 @@ public function add(
     ): void {
         $isolationScope = SentrySdk::getIsolationScope();
         $client = SentrySdk::getClient($isolationScope);
-        $scope = Scope::mergeScopes(SentrySdk::getGlobalScope(), $isolationScope);
+        $scope = SentrySdk::getGlobalScope()->merge($isolationScope);
         $options = $client->getOptions();
         $metricFlushThreshold = $options->getMetricFlushThreshold();
 
@@ -119,7 +120,7 @@ public function add(
         }
     }
 
-    public function flush(?ClientInterface $client = null, ?Scope $isolationScope = null): ?EventId
+    public function flush(?ClientInterface $client = null, ?IsolationScope $isolationScope = null): ?EventId
     {
         $metrics = $this->metrics;
 
@@ -131,13 +132,13 @@ public function flush(?ClientInterface $client = null, ?Scope $isolationScope =
         $client = $client ?? SentrySdk::getClient($isolationScope);
         $event = Event::createMetrics()->setMetrics($metrics->drain());
 
-        return $client->captureEvent($event, null, Scope::mergeScopes(SentrySdk::getGlobalScope(), $isolationScope));
+        return $client->captureEvent($event, null, SentrySdk::getGlobalScope()->merge($isolationScope));
     }
 
     /**
      * @return array{trace_id: string, span_id: string}
      */
-    private function getTraceContext(Scope $scope): array
+    private function getTraceContext(MergedScope $scope): array
     {
         $traceContext = $scope->getTraceContext();
 

src/Monolog/BreadcrumbHandler.php

@@ -13,10 +13,10 @@
 use Sentry\Event;
 use Sentry\SentrySdk;
 use Sentry\State\BreadcrumbRecorder;
-use Sentry\State\Scope;
+use Sentry\State\IsolationScope;
 
 /**
- * This Monolog handler logs every message as a {@see Breadcrumb} into the current {@see Scope},
+ * This Monolog handler logs every message as a {@see Breadcrumb} into the current {@see IsolationScope},
  * to enrich any event sent to Sentry.
  */
 final class BreadcrumbHandler extends AbstractProcessingHandler

src/Monolog/ExceptionToSentryIssueHandler.php

@@ -10,7 +10,7 @@
 use Monolog\LogRecord;
 use Psr\Log\LogLevel;
 use Sentry\State\EventCapturer;
-use Sentry\State\Scope;
+use Sentry\State\IsolationScope;
 
 use function Sentry\withIsolationScope;
 
@@ -39,7 +39,7 @@ public function handle($record): bool
             return false;
         }
 
-        withIsolationScope(function (Scope $scope) use ($record, $exception): void {
+        withIsolationScope(function (IsolationScope $scope) use ($record, $exception): void {
             $scope->setExtra('monolog.channel', $record['channel']);
             $scope->setExtra('monolog.level', $record['level_name']);
             $scope->setExtra('monolog.message', $record['message']);

src/Monolog/LogToSentryIssueHandler.php

@@ -12,7 +12,7 @@
 use Sentry\Event;
 use Sentry\EventHint;
 use Sentry\State\EventCapturer;
-use Sentry\State\Scope;
+use Sentry\State\IsolationScope;
 
 use function Sentry\withIsolationScope;
 
@@ -66,7 +66,7 @@ protected function doWrite($record): void
 
         $hint = new EventHint();
 
-        withIsolationScope(function (Scope $scope) use ($record, $event, $hint): void {
+        withIsolationScope(function (IsolationScope $scope) use ($record, $event, $hint): void {
             $scope->setExtra('monolog.channel', $record['channel']);
             $scope->setExtra('monolog.level', $record['level_name']);
 

src/NoOpClient.php

@@ -6,7 +6,7 @@
 
 use Sentry\Integration\IntegrationInterface;
 use Sentry\Serializer\RepresentationSerializer;
-use Sentry\State\Scope;
+use Sentry\State\MergedScope;
 use Sentry\Transport\Result;
 use Sentry\Transport\ResultStatus;
 
@@ -54,22 +54,22 @@ public function getCspReportUrl(): ?string
         return null;
     }
 
-    public function captureMessage(string $message, ?Severity $level = null, ?Scope $scope = null, ?EventHint $hint = null): ?EventId
+    public function captureMessage(string $message, ?Severity $level = null, ?MergedScope $scope = null, ?EventHint $hint = null): ?EventId
     {
         return null;
     }
 
-    public function captureException(\Throwable $exception, ?Scope $scope = null, ?EventHint $hint = null): ?EventId
+    public function captureException(\Throwable $exception, ?MergedScope $scope = null, ?EventHint $hint = null): ?EventId
     {
         return null;
     }
 
-    public function captureLastError(?Scope $scope = null, ?EventHint $hint = null): ?EventId
+    public function captureLastError(?MergedScope $scope = null, ?EventHint $hint = null): ?EventId
     {
         return null;
     }
 
-    public function captureEvent(Event $event, ?EventHint $hint = null, ?Scope $scope = null): ?EventId
+    public function captureEvent(Event $event, ?EventHint $hint = null, ?MergedScope $scope = null): ?EventId
     {
         return null;
     }

src/SentrySdk.php

@@ -6,9 +6,10 @@
 
 use Sentry\Logs\Logs;
 use Sentry\Metrics\TraceMetrics;
+use Sentry\State\GlobalScope;
+use Sentry\State\IsolationScope;
 use Sentry\State\RuntimeContext;
 use Sentry\State\RuntimeContextManager;
-use Sentry\State\Scope;
 
 /**
  * This class is the main entry point for all the most common SDK features.
@@ -18,7 +19,7 @@
 final class SentrySdk
 {
     /**
-     * @var Scope|null The process-global scope
+     * @var GlobalScope|null The process-global scope
      */
     private static $globalScope;
 
@@ -46,21 +47,21 @@ public static function init(?ClientInterface $client = null): void
         self::$runtimeContextManager = new RuntimeContextManager();
     }
 
-    public static function getGlobalScope(): Scope
+    public static function getGlobalScope(): GlobalScope
     {
         if (self::$globalScope === null) {
-            self::$globalScope = new Scope();
+            self::$globalScope = new GlobalScope();
         }
 
         return self::$globalScope;
     }
 
-    public static function getIsolationScope(): Scope
+    public static function getIsolationScope(): IsolationScope
     {
         return self::getCurrentRuntimeContext()->getIsolationScope();
     }
 
-    public static function getClient(?Scope $isolationScope = null): ClientInterface
+    public static function getClient(?IsolationScope $isolationScope = null): ClientInterface
     {
         $client = ($isolationScope ?? self::getIsolationScope())->getClient();
 

src/State/BreadcrumbRecorder.php

@@ -20,7 +20,7 @@ private function __construct()
     /**
      * Records the breadcrumb on the given scope if the client configuration allows it.
      */
-    public static function record(ClientInterface $client, Scope $scope, Breadcrumb $breadcrumb): bool
+    public static function record(ClientInterface $client, IsolationScope $scope, Breadcrumb $breadcrumb): bool
     {
         if ($client instanceof NoOpClient) {
             return false;