PHPLIB-1689 Make the Atlas Search exception more specific

src/Exception/SearchNotSupportedException.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace MongoDB\Exception;
+
+use MongoDB\Driver\Exception\ServerException;
+use Throwable;
+
+use function in_array;
+
+final class SearchNotSupportedException extends ServerException
+{
+    public static function create(ServerException $e): self
+    {
+        return new self('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', $e->getCode(), $e);
+    }
+
+    public static function isSearchNotSupportedError(Throwable $e): bool
+    {
+        if (! $e instanceof ServerException) {
+            return false;
+        }
+
+        return in_array($e->getCode(), [
+            59,      // MongoDB 4 to 6, 7-community: no such command: 'createSearchIndexes'
+            40324,   // MongoDB 4 to 6: Unrecognized pipeline stage name: '$listSearchIndexes'
+            115,     // MongoDB 7-ent: Search index commands are only supported with Atlas.
+            6047401, // MongoDB 7: $listSearchIndexes stage is only allowed on MongoDB Atlas
+            31082,   // MongoDB 8: Using Atlas Search Database Commands and the $listSearchIndexes aggregation stage requires additional configuration.
+        ], true);
+    }
+}

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());

tests/Collection/CollectionFunctionalTest.php

@@ -13,6 +13,7 @@
 use MongoDB\Driver\ReadPreference;
 use MongoDB\Driver\WriteConcern;
 use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Exception\SearchNotSupportedException;
 use MongoDB\Exception\UnsupportedException;
 use MongoDB\Operation\Count;
 use MongoDB\Tests\CommandObserver;
@@ -807,6 +808,32 @@ public function testListSearchIndexesInheritTypeMap(): void
         $this->assertIsArray($indexes[0]);
     }
 
+    public function testListSearchIndexesNotSupportedException(): void
+    {
+        if (self::isAtlas()) {
+            self::markTestSkipped('Atlas Search is supported on Atlas');
+        }
+
+        $collection = new Collection($this->manager, $this->getDatabaseName(), $this->getCollectionName());
+
+        $this->expectException(SearchNotSupportedException::class);
+
+        $collection->listSearchIndexes();
+    }
+
+    public function testCreateSearchIndexNotSupportedException(): void
+    {
+        if (self::isAtlas()) {
+            self::markTestSkipped('Atlas Search is supported on Atlas');
+        }
+
+        $collection = new Collection($this->manager, $this->getDatabaseName(), $this->getCollectionName());
+
+        $this->expectException(SearchNotSupportedException::class);
+
+        $collection->createSearchIndex(['mappings' => ['dynamic' => false]], ['name' => 'test-search-index']);
+    }
+
     /**
      * Create data fixtures.
      */