feat: add getMany() settings API (#163)

* feat(settings): add getMany API

* docs: clarify getMany return keys

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>

---------

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>

Author: memleakd

docs/basic-usage.md

@@ -15,6 +15,17 @@ To retrieve a config value use the `settings` service.
 $siteName = service('settings')->get('App.siteName');
 ```
 
+You can retrieve multiple values with `getMany()`. This behaves like calling `get()` for each key.
+
+```php
+$settings = service('settings')->getMany([
+    'App.siteName',
+    'App.siteEmail',
+]);
+```
+
+Unlike `get()`, which returns a single value, `getMany()` returns an array keyed by the exact setting names you requested.
+
 In this case we used the short class name, `App`, which the `config()` method automatically locates within the
 `app/Config` directory. If it was from a module, it would be found there. Either way, the fully qualified name
 is automatically detected by the Settings class to keep values separated from config files that may share the
@@ -119,6 +130,10 @@ setting('App.siteName', 'My Great Site');
 
 // Using the service through the helper
 $name = setting()->get('App.siteName');
+$settings = setting()->getMany([
+    'App.siteName',
+    'App.siteEmail',
+]);
 setting()->set('App.siteName', 'My Great Site');
 setting()->setMany([
     'App.siteName'  => 'My Great Site',

src/Settings.php

@@ -72,6 +72,24 @@ public function get(string $key, ?string $context = null)
         return $config->{$property} ?? null;
     }
 
+    /**
+     * Retrieve multiple values using the same behavior as get().
+     *
+     * @param list<string> $keys
+     *
+     * @return array<string, mixed>
+     */
+    public function getMany(array $keys, ?string $context = null): array
+    {
+        $settings = [];
+
+        foreach ($keys as $key) {
+            $settings[$key] = $this->get($key, $context);
+        }
+
+        return $settings;
+    }
+
     /**
      * Save a value to the writable handler for later retrieval.
      *

tests/SettingsTest.php

@@ -57,6 +57,70 @@ public function testGetWithContext(): void
         $this->assertSame('YesContext', $this->settings->get('Example.siteName', 'testing:true'));
     }
 
+    public function testGetManyReturnsMultipleValues(): void
+    {
+        $this->settings->setMany([
+            'Example.siteName'  => 'BatchName',
+            'Example.siteEmail' => 'batch@example.com',
+        ]);
+
+        $this->assertSame([
+            'Example.siteName'  => 'BatchName',
+            'Example.siteEmail' => 'batch@example.com',
+        ], $this->settings->getMany([
+            'Example.siteName',
+            'Example.siteEmail',
+        ]));
+    }
+
+    public function testGetManyFallsBackToConfigValues(): void
+    {
+        $this->assertSame([
+            'Example.siteName'  => 'Settings Test',
+            'Example.siteEmail' => null,
+        ], $this->settings->getMany([
+            'Example.siteName',
+            'Example.siteEmail',
+        ]));
+    }
+
+    public function testGetManyWithContext(): void
+    {
+        $this->settings->setMany([
+            'Example.siteName'  => 'NoContext',
+            'Example.siteEmail' => 'general@example.com',
+        ]);
+        $this->settings->setMany([
+            'Example.siteName' => 'YesContext',
+        ], 'testing:true');
+
+        $this->assertSame([
+            'Example.siteName'  => 'YesContext',
+            'Example.siteEmail' => 'general@example.com',
+        ], $this->settings->getMany([
+            'Example.siteName',
+            'Example.siteEmail',
+        ], 'testing:true'));
+    }
+
+    public function testGetManyPreservesRequestedKeys(): void
+    {
+        $this->settings->set('Example.siteName', 'BatchName');
+
+        $this->assertSame([
+            Example::class . '.siteName' => 'BatchName',
+            'Nada.siteName'              => null,
+        ], $this->settings->getMany([
+            Example::class . '.siteName',
+            'Nada.siteName',
+        ]));
+    }
+
+    public function testGetManyAcceptsEmptyArray(): void
+    {
+        $this->assertSame([], $this->settings->getMany([]));
+    }
+
     public function testSetManyStoresMultipleValues(): void
     {
         $this->settings->setMany([