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,7 +10,7 @@
 use Sentry\Integration\IntegrationRegistry;
 use Sentry\Serializer\RepresentationSerializer;
 use Sentry\Serializer\RepresentationSerializerInterface;
-use Sentry\State\Scope;
+use Sentry\State\IsolationScope;
 use Sentry\Transport\Result;
 use Sentry\Transport\TransportInterface;
 
@@ -140,7 +140,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, ?IsolationScope $scope = null, ?EventHint $hint = null): ?EventId
     {
         $event = Event::createEvent();
         $event->setMessage($message);
@@ -152,7 +152,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, ?IsolationScope $scope = null, ?EventHint $hint = null): ?EventId
     {
         $className = \get_class($exception);
         if ($this->shouldIgnoreException($className)) {
@@ -176,7 +176,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, ?IsolationScope $scope = null): ?EventId
     {
         // Client reports don't need to be augmented in the prepareEvent pipeline.
         if ($event->getType() !== EventType::clientReport()) {
@@ -208,7 +208,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(?IsolationScope $scope = null, ?EventHint $hint = null): ?EventId
     {
         $error = error_get_last();
 
@@ -277,13 +277,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 IsolationScope|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, ?IsolationScope $scope = null): ?Event
     {
         if ($hint !== null) {
             if ($hint->exception !== null && empty($event->getExceptions())) {
@@ -339,7 +339,8 @@ private function prepareEvent(Event $event, ?EventHint $hint = null, ?Scope $sco
 
         if ($scope !== null) {
             $beforeEventProcessors = $event;
-            $event = $scope->applyToEvent($event, $hint, $this->options);
+            $globalScope = SentrySdk::getGlobalScope();
+            $event = $globalScope->merge($scope)->applyToEvent($event, $hint, $this->options);
 
             if ($event === null) {
                 $this->logger->info(

src/ClientInterface.php

@@ -5,7 +5,7 @@
 namespace Sentry;
 
 use Sentry\Integration\IntegrationInterface;
-use Sentry\State\Scope;
+use Sentry\State\IsolationScope;
 use Sentry\Transport\Result;
 
 interface ClientInterface
@@ -23,38 +23,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 IsolationScope|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, ?IsolationScope $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 IsolationScope|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, ?IsolationScope $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 IsolationScope|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(?IsolationScope $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 IsolationScope|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, ?IsolationScope $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,7 @@
 use Sentry\Event;
 use Sentry\EventId;
 use Sentry\SentrySdk;
+use Sentry\State\IsolationScope;
 use Sentry\State\Scope;
 use Sentry\Util\Arr;
 use Sentry\Util\Str;
@@ -42,7 +43,8 @@ public function add(
 
         $isolationScope = SentrySdk::getIsolationScope();
         $client = SentrySdk::getClient($isolationScope);
-        $scope = Scope::mergeScopes(SentrySdk::getGlobalScope(), $isolationScope);
+        $globalScope = SentrySdk::getGlobalScope();
+        $scope = $globalScope->merge($isolationScope);
 
         $options = $client->getOptions();
         $sdkLogger = $options->getLogger();
@@ -71,7 +73,7 @@ public function add(
             $formattedMessage = $message;
         }
 
-        $traceData = $this->getTraceData($scope);
+        $traceData = $this->getTraceData($isolationScope);
         $traceId = $traceData['trace_id'];
         $parentSpanId = $traceData['parent_span_id'];
 
@@ -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, $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(IsolationScope $scope): array
     {
         $span = $scope->getSpan();
 

src/Metrics/MetricsAggregator.php

@@ -13,7 +13,7 @@
 use Sentry\Metrics\Types\GaugeMetric;
 use Sentry\Metrics\Types\Metric;
 use Sentry\SentrySdk;
-use Sentry\State\Scope;
+use Sentry\State\IsolationScope;
 use Sentry\Tracing\SpanId;
 use Sentry\Tracing\TraceId;
 use Sentry\Unit;
@@ -53,7 +53,8 @@ public function add(
     ): void {
         $isolationScope = SentrySdk::getIsolationScope();
         $client = SentrySdk::getClient($isolationScope);
-        $scope = Scope::mergeScopes(SentrySdk::getGlobalScope(), $isolationScope);
+        $globalScope = SentrySdk::getGlobalScope();
+        $scope = $globalScope->merge($isolationScope);
         $options = $client->getOptions();
         $metricFlushThreshold = $options->getMetricFlushThreshold();
 
@@ -97,7 +98,7 @@ public function add(
 
         $attributes += $defaultAttributes;
 
-        $traceContext = $this->getTraceContext($scope);
+        $traceContext = $this->getTraceContext($isolationScope);
         $traceId = new TraceId($traceContext['trace_id']);
         $spanId = new SpanId($traceContext['span_id']);
 
@@ -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, $isolationScope);
     }
 
     /**
      * @return array{trace_id: string, span_id: string}
      */
-    private function getTraceContext(Scope $scope): array
+    private function getTraceContext(IsolationScope $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\IsolationScope;
 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, ?IsolationScope $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, ?IsolationScope $scope = null, ?EventHint $hint = null): ?EventId
     {
         return null;
     }
 
-    public function captureLastError(?Scope $scope = null, ?EventHint $hint = null): ?EventId
+    public function captureLastError(?IsolationScope $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, ?IsolationScope $scope = null): ?EventId
     {
         return null;
     }