Replace hubs with scopes

.github/workflows/ci.yml

@@ -81,7 +81,7 @@ jobs:
 
       - name: Remove OpenTelemetry dependencies on unsupported PHP versions
         if: ${{ matrix.php.version == '7.2' || matrix.php.version == '7.3' || matrix.php.version == '7.4' || matrix.php.version == '8.0' }}
-        run: composer remove open-telemetry/api open-telemetry/exporter-otlp open-telemetry/sdk --dev --no-interaction --no-update
+        run: composer remove open-telemetry/api open-telemetry/exporter-otlp open-telemetry/sem-conv open-telemetry/sdk --dev --no-interaction --no-update
 
       - name: Set phpunit/phpunit version constraint
         run: composer require phpunit/phpunit:'${{ matrix.php.phpunit }}' --dev --no-interaction --no-update

UPGRADE-5.0.md

@@ -21,6 +21,39 @@ $logger->pushHandler(new \Sentry\Monolog\LogsHandler());
 
 To continue sending Monolog records to Sentry issues instead, use `Sentry\Monolog\LogToSentryIssueHandler` for log messages or `Sentry\Monolog\ExceptionToSentryIssueHandler` for exceptions.
 
+### Hub APIs Removed
+
+The Hub API has been removed. This includes:
+
+- **Removed classes and interfaces:**
+  - `Sentry\State\Hub`
+  - `Sentry\State\HubAdapter`
+  - `Sentry\State\HubInterface`
+
+- **Removed methods:**
+  - `SentrySdk::getCurrentHub()`
+  - `SentrySdk::setCurrentHub()`
+
+The SDK now exposes runtime state directly through `SentrySdk`, global helpers, and `Scope`:
+
+```php
+// Before (4.x)
+\Sentry\SentrySdk::getCurrentHub()->configureScope(static function (\Sentry\State\Scope $scope): void {
+    $scope->setTag('feature', 'checkout');
+});
+
+// After (5.0)
+\Sentry\configureScope(static function (\Sentry\State\Scope $scope): void {
+    $scope->setTag('feature', 'checkout');
+});
+```
+
+Use `SentrySdk::getClient()` for the active client, `SentrySdk::getGlobalScope()` for process-global data, and `SentrySdk::getIsolationScope()` for the current runtime isolation scope. Use the capture helpers such as `captureMessage()`, `captureException()`, and `captureEvent()` to send events.
+
+Use `configureScope()` to mutate the current isolation scope, `withIsolationScope()` to run code with a temporary forked scope, and `startTransaction()` to start manual tracing instrumentation.
+
+`SentrySdk::init()` no longer returns a Hub instance. It now returns `void`.
+
 ### Metrics API Removed
 
 The entire Metrics API has been removed as it is no longer supported. This includes:

analysis-baseline.toml

@@ -1368,18 +1368,6 @@ code = "possibly-invalid-argument"
 message = '''Possible argument type mismatch for argument #1 of `Sentry\StacktraceBuilder::buildFromBacktrace`: expected `list<array{'args'?: array<array-key, mixed>, 'class'?: class-string, 'file'?: string, 'function'?: string, 'line'?: int, 'type'?: string}>`, but possibly received `array<array-key, mixed>`.'''
 count = 1
 
-[[issues]]
-file = "src/State/Hub.php"
-code = "mixed-operand"
-message = "Right operand in `<` comparison has `mixed` type."
-count = 1
-
-[[issues]]
-file = "src/State/Hub.php"
-code = "possibly-null-operand"
-message = "Left operand in `<` comparison might be `null` (type `float|null`)."
-count = 1
-
 [[issues]]
 file = "src/State/Scope.php"
 code = "impossible-condition"

composer.json

@@ -37,6 +37,7 @@
         "nyholm/psr7": "^1.8",
         "open-telemetry/api": "^1.0",
         "open-telemetry/exporter-otlp": "^1.0",
+        "open-telemetry/sem-conv": "^1.27",
         "open-telemetry/sdk": "^1.0",
         "phpstan/phpstan": "^1.3",
         "phpunit/phpunit": "^8.5.52|^9.6.34",

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/ClientReport/ClientReportAggregator.php

@@ -5,7 +5,7 @@
 namespace Sentry\ClientReport;
 
 use Sentry\Event;
-use Sentry\State\HubAdapter;
+use Sentry\SentrySdk;
 use Sentry\Transport\DataCategory;
 
 class ClientReportAggregator
@@ -35,15 +35,13 @@ public function add(DataCategory $category, Reason $reason, int $quantity): void
         $category = $category->getValue();
         $reason = $reason->getValue();
         if ($quantity <= 0) {
-            $client = HubAdapter::getInstance()->getClient();
-            if ($client !== null) {
-                $logger = $client->getOptions()->getLoggerOrNullLogger();
-                $logger->debug('Dropping Client report with category={category} and reason={reason} because quantity is zero or negative ({quantity})', [
-                    'category' => $category,
-                    'reason' => $reason,
-                    'quantity' => $quantity,
-                ]);
-            }
+            $client = SentrySdk::getClient();
+            $logger = $client->getOptions()->getLoggerOrNullLogger();
+            $logger->debug('Dropping Client report with category={category} and reason={reason} because quantity is zero or negative ({quantity})', [
+                'category' => $category,
+                'reason' => $reason,
+                'quantity' => $quantity,
+            ]);
 
             return;
         }
@@ -64,11 +62,11 @@ public function flush(): void
         $event = Event::createClientReport();
         $event->setClientReports($reports);
 
-        $client = HubAdapter::getInstance()->getClient();
+        $client = SentrySdk::getClient();
 
         // Reset the client reports only if we successfully sent an event. If it fails it
         // can be sent on the next flush, or it gets discarded anyway.
-        if ($client !== null && $client->captureEvent($event) !== null) {
+        if ($client->captureEvent($event) !== null) {
             $this->reports = [];
         }
     }

src/Integration/AbstractErrorListenerIntegration.php

@@ -5,24 +5,26 @@
 namespace Sentry\Integration;
 
 use Sentry\Event;
+use Sentry\EventHint;
 use Sentry\ExceptionMechanism;
-use Sentry\State\HubInterface;
-use Sentry\State\Scope;
+use Sentry\State\EventRecorder;
+use Sentry\State\IsolationScope;
+
+use function Sentry\withIsolationScope;
 
 abstract class AbstractErrorListenerIntegration implements IntegrationInterface
 {
     /**
-     * Captures the exception using the given hub instance.
-     *
-     * @param HubInterface $hub       The hub instance
-     * @param \Throwable   $exception The exception instance
+     * @param \Throwable $exception The exception instance
      */
-    protected function captureException(HubInterface $hub, \Throwable $exception): void
+    protected function captureException(\Throwable $exception): void
     {
-        $hub->withScope(function (Scope $scope) use ($hub, $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);
+            });
 
-            $hub->captureException($exception);
+            EventRecorder::captureException($exception, null, $scope);
         });
     }
 

src/Integration/EnvironmentIntegration.php

@@ -24,7 +24,7 @@ final class EnvironmentIntegration implements IntegrationInterface
     public function setupOnce(): void
     {
         Scope::addGlobalEventProcessor(static function (Event $event): Event {
-            $integration = SentrySdk::getCurrentHub()->getIntegration(self::class);
+            $integration = SentrySdk::getClient()->getIntegration(self::class);
 
             if ($integration !== null) {
                 $event->setRuntimeContext($integration->updateRuntimeContext($event->getRuntimeContext()));

src/Integration/ErrorListenerIntegration.php

@@ -33,24 +33,22 @@ public function setupOnce(): void
         ErrorHandler::registerOnceErrorHandler($this->options)
                     ->addErrorHandlerListener(
                         static function (\ErrorException $exception): void {
-                            $currentHub = SentrySdk::getCurrentHub();
-                            $integration = $currentHub->getIntegration(self::class);
+                            $client = SentrySdk::getClient();
+                            $integration = $client->getIntegration(self::class);
 
                             if ($integration === null) {
                                 return;
                             }
 
-                            $client = $currentHub->getClient();
-
                             if ($exception instanceof SilencedErrorException && !$client->getOptions()->shouldCaptureSilencedErrors()) {
                                 return;
                             }
 
-                            if (!$exception instanceof SilencedErrorException && !($client->getOptions()->getErrorTypes() & $exception->getSeverity())) {
+                            if (!$exception instanceof SilencedErrorException && ($client->getOptions()->getErrorTypes() & $exception->getSeverity()) === 0) {
                                 return;
                             }
 
-                            $integration->captureException($currentHub, $exception);
+                            $integration->captureException($exception);
                         }
                     );
     }

src/Integration/ExceptionListenerIntegration.php

@@ -20,16 +20,14 @@ public function setupOnce(): void
     {
         $errorHandler = ErrorHandler::registerOnceExceptionHandler();
         $errorHandler->addExceptionHandlerListener(static function (\Throwable $exception): void {
-            $currentHub = SentrySdk::getCurrentHub();
-            $integration = $currentHub->getIntegration(self::class);
+            $client = SentrySdk::getClient();
+            $integration = $client->getIntegration(self::class);
 
-            // The client bound to the current hub, if any, could not have this
-            // integration enabled. If this is the case, bail out
             if ($integration === null) {
                 return;
             }
 
-            $integration->captureException($currentHub, $exception);
+            $integration->captureException($exception);
         });
     }
 }

src/Integration/FatalErrorListenerIntegration.php

@@ -22,20 +22,18 @@ public function setupOnce(): void
     {
         $errorHandler = ErrorHandler::registerOnceFatalErrorHandler();
         $errorHandler->addFatalErrorHandlerListener(static function (FatalErrorException $exception): void {
-            $currentHub = SentrySdk::getCurrentHub();
-            $integration = $currentHub->getIntegration(self::class);
+            $client = SentrySdk::getClient();
+            $integration = $client->getIntegration(self::class);
 
             if ($integration === null) {
                 return;
             }
 
-            $client = $currentHub->getClient();
-
-            if (!($client->getOptions()->getErrorTypes() & $exception->getSeverity())) {
+            if (($client->getOptions()->getErrorTypes() & $exception->getSeverity()) === 0) {
                 return;
             }
 
-            $integration->captureException($currentHub, $exception);
+            $integration->captureException($exception);
         });
     }
 }

src/Integration/FrameContextifierIntegration.php

@@ -41,7 +41,7 @@ public function __construct(?LoggerInterface $logger = null)
     public function setupOnce(): void
     {
         Scope::addGlobalEventProcessor(static function (Event $event): Event {
-            $client = SentrySdk::getCurrentHub()->getClient();
+            $client = SentrySdk::getClient();
 
             $maxContextLines = $client->getOptions()->getContextLines();
             $integration = $client->getIntegration(self::class);