Use SENTRY_SPOTLIGHT as default value for Spotlight options

phpstan-baseline.neon

@@ -260,11 +260,6 @@ parameters:
 			count: 1
 			path: src/Options.php
 
-		-
-			message: "#^Method Sentry\\\\Options\\:\\:isSpotlightEnabled\\(\\) should return bool but returns mixed\\.$#"
-			count: 1
-			path: src/Options.php
-
 		-
 			message: "#^Method Sentry\\\\Options\\:\\:shouldAttachMetricCodeLocations\\(\\) should return bool but returns mixed\\.$#"
 			count: 1

src/Options.php

@@ -368,10 +368,13 @@ public function setLogger(LoggerInterface $logger): self
 
     public function isSpotlightEnabled(): bool
     {
-        return $this->options['spotlight'];
+        return \is_string($this->options['spotlight']) || $this->options['spotlight'];
     }
 
-    public function enableSpotlight(bool $enable): self
+    /**
+     * @param bool|string $enable can be passed a boolean or the Spotlight URL (which will also enable Spotlight)
+     */
+    public function enableSpotlight($enable): self
     {
         $options = array_merge($this->options, ['spotlight' => $enable]);
 
@@ -382,9 +385,18 @@ public function enableSpotlight(bool $enable): self
 
     public function getSpotlightUrl(): string
     {
+        if (\is_string($this->options['spotlight'])) {
+            return $this->options['spotlight'];
+        }
+
         return $this->options['spotlight_url'];
     }
 
+    /**
+     * @return $this
+     *
+     * @deprecated Use `enableSpotlight` instead. Will be removed in 5.x.
+     */
     public function setSpotlightUrl(string $url): self
     {
         $options = array_merge($this->options, ['spotlight_url' => $url]);
@@ -1076,7 +1088,7 @@ public function setClassSerializers(array $serializers): self
     /**
      * Gets a callback that will be invoked when we sample a Transaction.
      *
-     * @psalm-return null|callable(\Sentry\Tracing\SamplingContext): float
+     * @psalm-return null|callable(Tracing\SamplingContext): float
      */
     public function getTracesSampler(): ?callable
     {
@@ -1089,7 +1101,7 @@ public function getTracesSampler(): ?callable
      *
      * @param ?callable $sampler The sampler
      *
-     * @psalm-param null|callable(\Sentry\Tracing\SamplingContext): float $sampler
+     * @psalm-param null|callable(Tracing\SamplingContext): float $sampler
      */
     public function setTracesSampler(?callable $sampler): self
     {
@@ -1127,7 +1139,10 @@ private function configureOptions(OptionsResolver $resolver): void
             'context_lines' => 5,
             'environment' => $_SERVER['SENTRY_ENVIRONMENT'] ?? null,
             'logger' => null,
-            'spotlight' => false,
+            'spotlight' => $_SERVER['SENTRY_SPOTLIGHT'] ?? null,
+            /**
+             * @deprecated Use `spotlight` instead. Will be removed in 5.x.
+             */
             'spotlight_url' => 'http://localhost:8969',
             'release' => $_SERVER['SENTRY_RELEASE'] ?? $_SERVER['AWS_LAMBDA_FUNCTION_VERSION'] ?? null,
             'dsn' => $_SERVER['SENTRY_DSN'] ?? null,
@@ -1187,7 +1202,7 @@ private function configureOptions(OptionsResolver $resolver): void
         $resolver->setAllowedTypes('in_app_exclude', 'string[]');
         $resolver->setAllowedTypes('in_app_include', 'string[]');
         $resolver->setAllowedTypes('logger', ['null', LoggerInterface::class]);
-        $resolver->setAllowedTypes('spotlight', 'bool');
+        $resolver->setAllowedTypes('spotlight', ['bool', 'string', 'null']);
         $resolver->setAllowedTypes('spotlight_url', 'string');
         $resolver->setAllowedTypes('release', ['null', 'string']);
         $resolver->setAllowedTypes('dsn', ['null', 'string', 'bool', Dsn::class]);
@@ -1229,6 +1244,8 @@ private function configureOptions(OptionsResolver $resolver): void
             return array_map([$this, 'normalizeAbsolutePath'], $value);
         });
 
+        $resolver->setNormalizer('spotlight', \Closure::fromCallable([$this, 'normalizeBooleanOrUrl']));
+
         $resolver->setNormalizer('in_app_exclude', function (SymfonyOptions $options, array $value) {
             return array_map([$this, 'normalizeAbsolutePath'], $value);
         });
@@ -1254,6 +1271,22 @@ private function normalizeAbsolutePath(string $value): string
         return $path;
     }
 
+    /**
+     * @return bool|string
+     */
+    private function normalizeBooleanOrUrl(SymfonyOptions $options, ?string $booleanOrUrl)
+    {
+        if (empty($booleanOrUrl)) {
+            return false;
+        }
+
+        if (filter_var($booleanOrUrl, \FILTER_VALIDATE_URL)) {
+            return $booleanOrUrl;
+        }
+
+        return filter_var($booleanOrUrl, \FILTER_VALIDATE_BOOLEAN);
+    }
+
     /**
      * Normalizes the DSN option by parsing the host, public and secret keys and
      * an optional path.

tests/OptionsTest.php

@@ -177,7 +177,7 @@ static function (): void {},
             'spotlight',
             true,
             'isSpotlightEnabled',
-            'EnableSpotlight',
+            'enableSpotlight',
         ];
 
         yield [
@@ -653,6 +653,37 @@ public function testReleaseOptionDefaultValueIsPreferredFromSentryEnvironmentVar
         $this->assertSame('0.0.4', (new Options())->getRelease());
     }
 
+    /**
+     * @backupGlobals enabled
+     *
+     * @dataProvider spotlightEnvironmentValueDataProvider
+     */
+    public function testSpotlightOptionDefaultValueIsControlledFromEnvironmentVariable(string $environmentVariableValue, bool $expectedSpotlightEnabled, string $expectedSpotlightUrl): void
+    {
+        $_SERVER['SENTRY_SPOTLIGHT'] = $environmentVariableValue;
+
+        $options = new Options();
+
+        $this->assertEquals($expectedSpotlightEnabled, $options->isSpotlightEnabled());
+        $this->assertEquals($expectedSpotlightUrl, $options->getSpotlightUrl());
+    }
+
+    public static function spotlightEnvironmentValueDataProvider(): array
+    {
+        $defaultSpotlightUrl = 'http://localhost:8969';
+
+        return [
+            ['', false, $defaultSpotlightUrl],
+            ['true', true, $defaultSpotlightUrl],
+            ['1', true, $defaultSpotlightUrl],
+            ['false', false, $defaultSpotlightUrl],
+            ['0', false, $defaultSpotlightUrl],
+            ['null', false, $defaultSpotlightUrl],
+            ['http://localhost:1234', true, 'http://localhost:1234'],
+            ['some invalid looking value', false, $defaultSpotlightUrl],
+        ];
+    }
+
     public function testErrorTypesOptionIsNotDynamiclyReadFromErrorReportingLevelWhenSet(): void
     {
         $errorReportingBeforeTest = error_reporting(\E_ERROR);