feat: Add FQDN class support to IndexLocator and IndexLocatorAwareTrait

This reflects newly added FQDN support in TableLocator (CakePHP 5.2.9)

Author: josbeir

src/Datasource/IndexLocator.php

@@ -81,17 +81,22 @@ public function allowFallbackClass(bool $allow = true)
      */
     protected function createInstance(string $alias, array $options): RepositoryInterface
     {
-        [, $classAlias] = pluginSplit($alias);
-        $options += [
-            'name' => Inflector::underscore($classAlias),
-            'className' => Inflector::camelize($alias),
-        ];
-        $className = App::className($options['className'], 'Model/Index', 'Index');
+        if (!str_contains($alias, '\\')) {
+            [, $classAlias] = pluginSplit($alias);
+            $options += [
+                'name' => Inflector::underscore($classAlias),
+                'className' => Inflector::camelize($alias),
+            ];
+        } elseif (!isset($options['name'])) {
+            $options['className'] = $alias;
+        }
+
+        $className = App::className($options['className'] ?? $alias, 'Model/Index', 'Index');
         if ($className) {
             $options['className'] = $className;
         } elseif ($this->allowFallbackClass) {
-            if (!isset($options['name']) && strpos($options['className'], '\\') === false) {
-                [, $name] = pluginSplit($options['className']);
+            if (!isset($options['name']) && strpos($options['className'] ?? $alias, '\\') === false) {
+                [, $name] = pluginSplit($options['className'] ?? $alias);
                 $options['name'] = Inflector::underscore($name);
             }
 

src/Datasource/IndexLocatorAwareTrait.php

@@ -70,10 +70,12 @@ public function getIndexLocator(): LocatorInterface
     /**
      * Convenience method to get an index instance.
      *
-     * @param string|null $alias The alias name you want to get. Should be in CamelCase format.
+     * @template T of \Cake\ElasticSearch\Index
+     * @param class-string<T>|string|null $alias The alias name you want to get. Should be in CamelCase format.
      *  If `null` then the value of $defaultIndex property is used.
      * @param array<string, mixed> $options The options you want to build the index with.
      *   If an index has already been loaded the registry options will be ignored.
+     * @return ($alias is class-string<T> ? T : \Cake\ElasticSearch\Index)
      * @throws \UnexpectedValueException If `$alias` argument and `$defaultIndex` property both are `null`.
      * @see \Cake\ElasticSearch\Datasource\IndexLocator::get()
      */
@@ -86,9 +88,8 @@ public function fetchIndex(?string $alias = null, array $options = []): Index
             );
         }
 
-        $index = $this->getIndexLocator()->get($alias, $options);
-        assert($index instanceof Index);
-
-        return $index;
+        // phpcs:ignore
+        /** @var T */
+        return $this->getIndexLocator()->get($alias, $options);
     }
 }

tests/TestCase/Datasource/IndexLocatorAwareTraitTest.php

@@ -295,4 +295,25 @@ public function testDefaultIndexProperty(): void
         $this->subject->setDefaultIndex(null);
         $this->assertNull($this->subject->getDefaultIndex());
     }
+
+    /**
+     * Test fetchIndex passes FQDN class names through to locator
+     */
+    public function testFetchIndexWithFqdnClassName(): void
+    {
+        $mockIndex = $this->createMock(Index::class);
+        $fqdnClass = Index::class;
+
+        $this->mockLocator
+            ->expects($this->once())
+            ->method('get')
+            ->with($fqdnClass, [])
+            ->willReturn($mockIndex);
+
+        $this->subject->setIndexLocator($this->mockLocator);
+
+        $result = $this->subject->fetchIndex($fqdnClass);
+
+        $this->assertSame($mockIndex, $result);
+    }
 }

tests/TestCase/Datasource/IndexLocatorTest.php

@@ -373,6 +373,40 @@ public function testCreateInstanceWithFullNamespaceClassName(): void
         $this->assertSame('custom_name', $result->getName());
     }
 
+    /**
+     * Test get() with FQDN class name
+     */
+    public function testGetWithFqdnClassName(): void
+    {
+        // Using FQDN should work directly
+        $result = $this->locator->get(UsersIndex::class);
+
+        $this->assertInstanceOf(UsersIndex::class, $result);
+        $this->assertSame('users', $result->getName());
+
+        // Should be cached under FQDN alias
+        $this->assertTrue($this->locator->exists(UsersIndex::class));
+
+        // Getting again should return same instance
+        $result2 = $this->locator->get(UsersIndex::class);
+        $this->assertSame($result, $result2);
+    }
+
+    /**
+     * Test get() with FQDN class name and custom options
+     */
+    public function testGetWithFqdnClassNameAndOptions(): void
+    {
+        // Using FQDN with custom name option
+        // Use Index::class which respects the name option
+        $result = $this->locator->get(Index::class, [
+            'name' => 'custom_users_index',
+        ]);
+
+        $this->assertInstanceOf(Index::class, $result);
+        $this->assertSame('custom_users_index', $result->getName());
+    }
+
     /**
      * Test createInstance with fallback disabled and missing className
      */