PHPLIB-1689 Make the Atlas Search exception more specific

src/Exception/SearchNotSupportedException.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace MongoDB\Exception;
+
+use MongoDB\Driver\Exception\ServerException;
+use Throwable;
+
+final class SearchNotSupportedException extends ServerException
+{
+    /** @internal */
+    public static function create(ServerException $e): self
+    {
+        $message = $e->getCode() === 31082
+            ? $e->getMessage()
+            : 'Using Atlas Search Database Commands and the $listSearchIndexes aggregation stage requires additional configuration. '
+                . 'Please connect to Atlas or an AtlasCLI local deployment to enable. '
+                . 'For more information on how to connect, see https://dochub.mongodb.org/core/atlas-cli-deploy-local-reqs';
+
+        return new self($message, $e->getCode(), $e);
+    }
+
+    /** @internal */
+    public static function isSearchNotSupportedError(Throwable $exception): bool
+    {
+        if (! $exception instanceof ServerException) {
+            return false;
+        }
+
+        return match ($exception->getCode()) {
+            // MongoDB 8: Using Atlas Search Database Commands and the $listSearchIndexes aggregation stage requires additional configuration.
+            31082 => true,
+            // MongoDB 7: $listSearchIndexes stage is only allowed on MongoDB Atlas
+            6047401 => true,
+            // MongoDB 7-ent: Search index commands are only supported with Atlas.
+            115 => true,
+            // MongoDB 4 to 6, 7-community
+            59 => match ($exception->getMessage()) {
+                'no such command: \'createSearchIndexes\'' => true,
+                'no such command: \'updateSearchIndex\'' => true,
+                'no such command: \'dropSearchIndex\'' => true,
+                default => false,
+            },
+            // MongoDB 4 to 6
+            40324 => match ($exception->getMessage()) {
+                'Unrecognized pipeline stage name: \'$listSearchIndexes\'' => true,
+                'Unrecognized pipeline stage name: \'$search\'' => true,
+                'Unrecognized pipeline stage name: \'$searchMeta\'' => true,
+                'Unrecognized pipeline stage name: \'$vectorSearch\'' => true,
+                default => false,
+            },
+            // Not a Search error
+            default => false,
+        };
+    }
+}

src/Operation/Aggregate.php

@@ -21,12 +21,14 @@
 use MongoDB\Driver\Command;
 use MongoDB\Driver\CursorInterface;
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
+use MongoDB\Driver\Exception\ServerException;
 use MongoDB\Driver\ReadConcern;
 use MongoDB\Driver\ReadPreference;
 use MongoDB\Driver\Server;
 use MongoDB\Driver\Session;
 use MongoDB\Driver\WriteConcern;
 use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Exception\SearchNotSupportedException;
 use MongoDB\Exception\UnexpectedValueException;
 use MongoDB\Exception\UnsupportedException;
 use MongoDB\Model\CodecCursor;
@@ -233,7 +235,15 @@ public function execute(Server $server): CursorInterface
             $this->createCommandOptions(),
         );
 
-        $cursor = $this->executeCommand($server, $command);
+        try {
+            $cursor = $this->executeCommand($server, $command);
+        } catch (ServerException $exception) {
+            if (SearchNotSupportedException::isSearchNotSupportedError($exception)) {
+                throw SearchNotSupportedException::create($exception);
+            }
+
+            throw $exception;
+        }
 
         if (isset($this->options['codec'])) {
             return CodecCursor::fromCursor($cursor, $this->options['codec']);

src/Operation/CreateSearchIndexes.php

@@ -19,8 +19,10 @@
 
 use MongoDB\Driver\Command;
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
+use MongoDB\Driver\Exception\ServerException;
 use MongoDB\Driver\Server;
 use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Exception\SearchNotSupportedException;
 use MongoDB\Exception\UnsupportedException;
 use MongoDB\Model\SearchIndexInput;
 
@@ -83,7 +85,15 @@ public function execute(Server $server): array
             $cmd['comment'] = $this->options['comment'];
         }
 
-        $cursor = $server->executeCommand($this->databaseName, new Command($cmd));
+        try {
+            $cursor = $server->executeCommand($this->databaseName, new Command($cmd));
+        } catch (ServerException $exception) {
+            if (SearchNotSupportedException::isSearchNotSupportedError($exception)) {
+                throw SearchNotSupportedException::create($exception);
+            }
+
+            throw $exception;
+        }
 
         /** @var object{indexesCreated: list<object{name: string}>} $result */
         $result = current($cursor->toArray());

src/Operation/DropSearchIndex.php

@@ -22,6 +22,7 @@
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
 use MongoDB\Driver\Server;
 use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Exception\SearchNotSupportedException;
 use MongoDB\Exception\UnsupportedException;
 
 /**
@@ -72,6 +73,10 @@ public function execute(Server $server): void
         } catch (CommandException $e) {
             // Drop operations are idempotent. The server may return an error if the collection does not exist.
             if ($e->getCode() !== self::ERROR_CODE_NAMESPACE_NOT_FOUND) {
+                if (SearchNotSupportedException::isSearchNotSupportedError($e)) {
+                    throw SearchNotSupportedException::create($e);
+                }
+
                 throw $e;
             }
         }

src/Operation/UpdateSearchIndex.php

@@ -19,8 +19,10 @@
 
 use MongoDB\Driver\Command;
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
+use MongoDB\Driver\Exception\ServerException;
 use MongoDB\Driver\Server;
 use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Exception\SearchNotSupportedException;
 use MongoDB\Exception\UnsupportedException;
 
 use function MongoDB\is_document;
@@ -76,6 +78,14 @@ public function execute(Server $server): void
             $cmd['comment'] = $this->options['comment'];
         }
 
-        $server->executeCommand($this->databaseName, new Command($cmd));
+        try {
+            $server->executeCommand($this->databaseName, new Command($cmd));
+        } catch (ServerException $e) {
+            if (SearchNotSupportedException::isSearchNotSupportedError($e)) {
+                throw SearchNotSupportedException::create($e);
+            }
+
+            throw $e;
+        }
     }
 }

tests/Collection/CollectionFunctionalTest.php

@@ -783,7 +783,7 @@ public function testMethodInTransactionWithReadConcernOption($method): void
 
     public function testListSearchIndexesInheritTypeMap(): void
     {
-        $this->skipIfAtlasSearchIndexIsNotSupported();
+        $this->skipIfSearchIndexIsNotSupported();
 
         $collection = new Collection($this->manager, $this->getDatabaseName(), $this->getCollectionName(), ['typeMap' => ['root' => 'array']]);
 

tests/ExamplesTest.php

@@ -8,7 +8,6 @@
 use PHPUnit\Framework\Attributes\RunTestsInSeparateProcesses;
 
 use function bin2hex;
-use function getenv;
 use function putenv;
 use function random_bytes;
 use function sprintf;
@@ -230,10 +229,7 @@ public static function provideExamples(): Generator
     #[Group('atlas')]
     public function testAtlasSearch(): void
     {
-        $uri = getenv('MONGODB_URI') ?? '';
-        if (! self::isAtlas($uri)) {
-            $this->markTestSkipped('Atlas Search examples are only supported on MongoDB Atlas');
-        }
+        $this->skipIfSearchIndexIsNotSupported();
 
         $this->skipIfServerVersion('<', '7.0', 'Atlas Search examples require MongoDB 7.0 or later');
 

tests/Exception/SearchNotSupportedExceptionTest.php

@@ -0,0 +1,102 @@
+<?php
+
+namespace MongoDB\Tests\Exception;
+
+use MongoDB\Driver\Command;
+use MongoDB\Driver\Exception\ServerException;
+use MongoDB\Exception\SearchNotSupportedException;
+use MongoDB\Tests\Collection\FunctionalTestCase;
+use PHPUnit\Framework\Attributes\DoesNotPerformAssertions;
+
+class SearchNotSupportedExceptionTest extends FunctionalTestCase
+{
+    #[DoesNotPerformAssertions]
+    public function testListSearchIndexesNotSupportedException(): void
+    {
+        $collection = $this->createCollection($this->getDatabaseName(), $this->getCollectionName());
+
+        try {
+            $collection->listSearchIndexes();
+        } catch (SearchNotSupportedException) {
+            // If an exception is thrown because Atlas Search is not supported,
+            // then the test is successful because it has the correct exception class.
+        }
+    }
+
+    #[DoesNotPerformAssertions]
+    public function testSearchStageNotSupportedException(): void
+    {
+        // The server returns an empty result if the search index does not exist.
+        // We don't need to create a search index for this test.
+        $collection = $this->createCollection($this->getDatabaseName(), $this->getCollectionName());
+
+        try {
+            $collection->aggregate([
+                ['$search' => ['index' => 'default', 'text' => ['query' => 'test', 'path' => 'field']]],
+            ]);
+        } catch (SearchNotSupportedException) {
+            // If an exception is thrown because Atlas Search is not supported,
+            // then the test is successful because it has the correct exception class.
+        }
+
+        try {
+            $collection->aggregate([
+                ['$vectorSearch' => ['index' => 'default', 'queryVector' => [0.1, 0.2, 0.3], 'path' => 'embedding', 'numCandidates' => 5, 'limit' => 5]],
+            ]);
+        } catch (SearchNotSupportedException) {
+            // If an exception is thrown because Atlas Search is not supported,
+            // then the test is successful because it has the correct exception class.
+        }
+    }
+
+    #[DoesNotPerformAssertions]
+    public function testSearchIndexManagementNotSupportedException(): void
+    {
+        $collection = $this->createCollection($this->getDatabaseName(), $this->getCollectionName());
+
+        try {
+            $collection->createSearchIndex(['mappings' => ['dynamic' => false]], ['name' => 'test-search-index']);
+        } catch (SearchNotSupportedException) {
+            // If an exception is thrown because Atlas Search is not supported,
+            // then the test is successful because it has the correct exception class.
+        }
+
+        try {
+            $collection->updateSearchIndex('test-search-index', ['mappings' => ['dynamic' => true]]);
+        } catch (SearchNotSupportedException) {
+            // If an exception is thrown because Atlas Search is not supported,
+            // then the test is successful because it has the correct exception class.
+        }
+
+        try {
+            $collection->dropSearchIndex('test-search-index');
+        } catch (SearchNotSupportedException) {
+            // If an exception is thrown because Atlas Search is not supported,
+            // then the test is successful because it has the correct exception class.
+        }
+    }
+
+    public function testOtherStageNotFound(): void
+    {
+        $collection = $this->createCollection($this->getDatabaseName(), $this->getCollectionName());
+
+        try {
+            $collection->aggregate([
+                ['$searchStageNotExisting' => ['text' => ['query' => 'test', 'path' => 'field']]],
+            ]);
+            self::fail('Expected ServerException was not thrown');
+        } catch (ServerException $exception) {
+            self::assertNotInstanceOf(SearchNotSupportedException::class, $exception, $exception);
+        }
+    }
+
+    public function testOtherCommandNotFound(): void
+    {
+        try {
+            $this->manager->executeCommand($this->getDatabaseName(), new Command(['nonExistingCommand' => 1]));
+            self::fail('Expected ServerException was not thrown');
+        } catch (ServerException $exception) {
+            self::assertFalse(SearchNotSupportedException::isSearchNotSupportedError($exception));
+        }
+    }
+}

tests/FunctionalTestCase.php

@@ -8,6 +8,7 @@
 use MongoDB\Collection;
 use MongoDB\Driver\Command;
 use MongoDB\Driver\Exception\CommandException;
+use MongoDB\Driver\Exception\ServerException;
 use MongoDB\Driver\Manager;
 use MongoDB\Driver\ReadPreference;
 use MongoDB\Driver\Server;
@@ -50,8 +51,6 @@
 
 abstract class FunctionalTestCase extends TestCase
 {
-    private const ATLAS_TLD = '/\.(mongodb\.net|mongodb-dev\.net)/';
-
     protected Manager $manager;
 
     private array $configuredFailPoints = [];
@@ -434,13 +433,22 @@ protected function skipIfServerVersion(string $operator, string $version, ?strin
         }
     }
 
-    protected function skipIfAtlasSearchIndexIsNotSupported(): void
+    protected function skipIfSearchIndexIsNotSupported(): void
     {
-        if (! self::isAtlas()) {
-            self::markTestSkipped('Search Indexes are only supported on MongoDB Atlas 7.0+');
-        }
+        try {
+            $this->createCollection($this->getDatabaseName(), __METHOD__);
+            $this->manager->executeWriteCommand($this->getDatabaseName(), new Command([
+                'dropSearchIndex' => __METHOD__,
+                'name' => 'nonexistent-index',
+            ]));
+        } catch (ServerException $exception) {
+            // Code 27 = Search index does not exist, which indicates that the feature is supported
+            if ($exception->getCode() === 27) {
+                return;
+            }
 
-        $this->skipIfServerVersion('<', '7.0', 'Search Indexes are only supported on MongoDB Atlas 7.0+');
+            self::markTestSkipped($exception->getMessage());
+        }
     }
 
     protected function skipIfChangeStreamIsNotSupported(): void
@@ -516,11 +524,6 @@ protected function isEnterprise(): bool
         throw new UnexpectedValueException('Could not determine server modules');
     }
 
-    public static function isAtlas(?string $uri = null): bool
-    {
-        return preg_match(self::ATLAS_TLD, $uri ?? static::getUri());
-    }
-
     /** @see https://www.mongodb.com/docs/manual/core/queryable-encryption/reference/shared-library/ */
     public static function isCryptSharedLibAvailable(): bool
     {

tests/SpecTests/SearchIndexSpecTest.php

@@ -31,7 +31,7 @@ public function setUp(): void
     {
         parent::setUp();
 
-        $this->skipIfAtlasSearchIndexIsNotSupported();
+        $this->skipIfSearchIndexIsNotSupported();
     }
 
     /**

tests/UnifiedSpecTests/UnifiedSpecTest.php

@@ -373,9 +373,7 @@ public static function provideFailingTests(): Generator
     #[DataProvider('provideIndexManagementTests')]
     public function testIndexManagement(UnifiedTestCase $test): void
     {
-        if (self::isAtlas()) {
-            self::markTestSkipped('Search Indexes tests must run on a non-Atlas cluster');
-        }
+        $this->skipIfSearchIndexIsNotSupported();
 
         if (! self::isEnterprise()) {
             self::markTestSkipped('Specific Atlas error messages are only available on Enterprise server');

tests/UnifiedSpecTests/UnifiedTestRunner.php

@@ -32,6 +32,7 @@
 use function PHPUnit\Framework\assertIsString;
 use function PHPUnit\Framework\assertNotEmpty;
 use function PHPUnit\Framework\assertNotFalse;
+use function preg_match;
 use function preg_replace;
 use function sprintf;
 use function str_starts_with;
@@ -89,7 +90,7 @@ public function __construct(private string $internalClientUri)
          *
          * Atlas Data Lake also does not support killAllSessions.
          */
-        if (FunctionalTestCase::isAtlas($internalClientUri) || $this->isAtlasDataLake()) {
+        if ($this->isAtlas($internalClientUri) || $this->isAtlasDataLake()) {
             $this->allowKillAllSessions = false;
         }
 
@@ -307,6 +308,11 @@ private function getTopology(): string
         };
     }
 
+    private function isAtlas(string $internalClientUri): bool
+    {
+        return preg_match('/\.(mongodb\.net|mongodb-dev\.net)/', $internalClientUri);
+    }
+
     private function isAtlasDataLake(): bool
     {
         $database = $this->internalClient->selectDatabase('admin');