Merge branch 'config'

Author: lkrms

.gitattributes

@@ -8,6 +8,7 @@
 /phpstan* export-ignore
 /phpunit* export-ignore
 /scripts export-ignore
+/src/Toolkit/Core/Facade/Config.php linguist-generated
 /src/Util/Cli/CliOptionBuilder.php linguist-generated
 /src/Util/Curler/CurlerBuilder.php linguist-generated
 /src/Util/Curler/Support/CurlerPageBuilder.php linguist-generated

lk-util/Command/Generate/GenerateFacade.php

@@ -9,7 +9,7 @@
 use Lkrms\Support\PhpDoc\PhpDoc;
 use Lkrms\Utility\Arr;
 use Lkrms\Utility\Reflect;
-use Salient\Core\Facade;
+use Salient\Core\AbstractFacade;
 use ReflectionMethod;
 use ReflectionParameter;
 
@@ -24,6 +24,10 @@ final class GenerateFacade extends GenerateCommand
     private const SKIP_METHODS = [
         'getReadableProperties',
         'getWritableProperties',
+        'offsetExists',
+        'offsetGet',
+        'offsetSet',
+        'offsetUnset',
         'withFacade',
         'withoutFacade',
         // These are displaced by Facade
@@ -123,7 +127,7 @@ protected function run(string ...$args)
         $classPrefix = $this->getClassPrefix();
 
         $service = $this->getFqcnAlias($classFqcn, $classClass);
-        $extends = $this->getFqcnAlias(Facade::class);
+        $extends = $this->getFqcnAlias(AbstractFacade::class);
 
         $alias = [];
         foreach ($aliasFqcn as $aliasFqcn) {

scripts/generate.php

@@ -57,12 +57,15 @@
 use Lkrms\Utility\Json;
 use Lkrms\Utility\Package;
 use Lkrms\Utility\Pcre;
+use Salient\Core\Facade\Config;
+use Salient\Core\ConfigurationManager;
 
-$loader = require dirname(__DIR__) . '/vendor/autoload.php';
+require dirname(__DIR__) . '/vendor/autoload.php';
 
 $facades = [
     App::class => [ContainerInterface::class, [Container::class], '--desc', 'A facade for the global service container', '--api'],
     Cache::class => CacheStore::class,
+    Config::class => [ConfigurationManager::class, '--api'],
     Console::class => [ConsoleWriter::class, '--api'],
     Err::class => [ErrorHandler::class, '--skip', 'handleShutdown,handleError,handleException'],
     Event::class => EventDispatcher::class,

src/Toolkit/Core/Facade.php renamed to src/Toolkit/Core/AbstractFacade.php

@@ -24,7 +24,7 @@
  *
  * @implements FacadeInterface<TService>
  */
-abstract class Facade implements FacadeInterface
+abstract class AbstractFacade implements FacadeInterface
 {
     /** @use ResolvesServiceLists<TService> */
     use ResolvesServiceLists;

src/Toolkit/Core/ConfigurationManager.php

@@ -0,0 +1,163 @@
+<?php declare(strict_types=1);
+
+namespace Salient\Core;
+
+use Lkrms\Utility\Arr;
+use Lkrms\Utility\File;
+use Lkrms\Utility\Pcre;
+use Salient\Core\Exception\InvalidConfigurationException;
+use ArrayAccess;
+use LogicException;
+use OutOfRangeException;
+use ReturnTypeWillChange;
+
+/**
+ * Provides access to values in configuration files
+ *
+ * @implements ArrayAccess<string,mixed>
+ */
+final class ConfigurationManager implements ArrayAccess
+{
+    /**
+     * @var array<string,mixed[]>
+     */
+    private array $Items = [];
+
+    /**
+     * @param array<string,mixed[]> $items
+     */
+    public function __construct(array $items = [])
+    {
+        $this->Items = $items;
+    }
+
+    /**
+     * Load values from files in a directory
+     *
+     * @return $this
+     */
+    public function loadDirectory(string $directory): self
+    {
+        $items = [];
+        foreach (File::find()->in($directory)->include('/\.php$/')->doNotRecurse() as $file) {
+            $basename = $file->getBasename('.php');
+            $file = (string) $file;
+            if (Pcre::match('/[\s.]|^[0-9]+$/', $basename)) {
+                throw new InvalidConfigurationException(sprintf(
+                    'Invalid configuration file name: %s',
+                    $file,
+                ));
+            }
+            $values = require $file;
+            if (!is_array($values)) {
+                throw new InvalidConfigurationException(sprintf(
+                    'Invalid configuration file: %s',
+                    $file,
+                ));
+            }
+            $items[$basename] = $values;
+        }
+        ksort($items, \SORT_NATURAL);
+        $this->Items = $items;
+        return $this;
+    }
+
+    /**
+     * Check if a configuration value exists
+     */
+    public function has(string $key): bool
+    {
+        return Arr::has($key, $this->Items);
+    }
+
+    /**
+     * Get a configuration value
+     *
+     * @param mixed $default
+     * @return mixed
+     * @throws OutOfRangeException if `$key` is not configured and no `$default`
+     * is given.
+     */
+    public function get(string $key, $default = null)
+    {
+        if (func_num_args() > 1) {
+            return Arr::get($key, $this->Items, $default);
+        }
+        return Arr::get($key, $this->Items);
+    }
+
+    /**
+     * Get multiple configuration values
+     *
+     * @param array<string|int,mixed|string> $keys An array that optionally maps
+     * keys to default values.
+     * @return array<string,mixed>
+     * @throws OutOfRangeException if a key is not configured and no default
+     * value is given.
+     */
+    public function getMany(array $keys): array
+    {
+        foreach ($keys as $key => $default) {
+            if (is_int($key)) {
+                $key = $default;
+                $values[$key] = Arr::get($key, $this->Items);
+                continue;
+            }
+            $values[$key] = Arr::get($key, $this->Items, $default);
+        }
+        return $values ?? [];
+    }
+
+    /**
+     * Get all configuration values
+     *
+     * @return array<string,mixed[]>
+     */
+    public function all(): array
+    {
+        return $this->Items;
+    }
+
+    /**
+     * @internal
+     *
+     * @param string $offset
+     */
+    public function offsetExists($offset): bool
+    {
+        return Arr::get($offset, $this->Items, null) !== null;
+    }
+
+    /**
+     * @internal
+     *
+     * @param string $offset
+     * @return mixed
+     */
+    #[ReturnTypeWillChange]
+    public function offsetGet($offset)
+    {
+        return Arr::get($offset, $this->Items);
+    }
+
+    /**
+     * @internal
+     *
+     * @param string $offset
+     * @param mixed $value
+     */
+    public function offsetSet($offset, $value): void
+    {
+        throw new LogicException('Configuration values are read-only');
+    }
+
+    /**
+     * @internal
+     *
+     * @param string $offset
+     */
+    public function offsetUnset($offset): void
+    {
+        throw new LogicException('Configuration values are read-only');
+    }
+}

src/Toolkit/Core/Exception/InvalidConfigurationException.php

@@ -0,0 +1,10 @@
+<?php declare(strict_types=1);
+
+namespace Salient\Core\Exception;
+
+use Lkrms\Exception\Exception;
+
+/**
+ * @api
+ */
+class InvalidConfigurationException extends Exception {}

src/Toolkit/Core/Facade/Config.php

@@ -26,6 +26,7 @@
 use Lkrms\Utility\Pcre;
 use Lkrms\Utility\Sys;
 use Lkrms\Utility\Test;
+use Salient\Core\Facade\Config;
 use LogicException;
 use Phar;
 
@@ -264,15 +265,21 @@ final public function getTempPath(bool $create = true): string
      * is used after removing common PHP file extensions and recognised version
      * numbers.
      *
+     * If `$configDir` exists and is a directory, it is passed to
+     * {@see Config::loadDirectory()} after `.env` files are loaded and applied.
+     *
      * @api
      *
      * @param int-mask-of<EnvFlag::*> $envFlags Values to apply from the
      * environment to the running script.
+     * @param string|null $configDir A path relative to the application's base
+     * path, or `null` if configuration files should not be loaded.
      */
     public function __construct(
         ?string $basePath = null,
         ?string $appName = null,
-        int $envFlags = EnvFlag::ALL
+        int $envFlags = EnvFlag::ALL,
+        ?string $configDir = 'config'
     ) {
         if (!isset(self::$StartTime)) {
             self::$StartTime = hrtime(true);
@@ -345,6 +352,15 @@ public function __construct(
         if ($adodb !== null) {
             Err::silencePath($adodb);
         }
+
+        if ((string) $configDir !== '') {
+            if (!File::isAbsolute($configDir)) {
+                $configDir = "{$this->BasePath}/{$configDir}";
+            }
+            if (is_dir($configDir)) {
+                Config::loadDirectory($configDir);
+            }
+        }
     }
 
     /**

src/Util/Container/Application.php

@@ -50,7 +50,8 @@ public function getBasePath(): string;
     public function getCachePath(): string;
 
     /**
-     * Get a writable directory for the application's configuration files
+     * Get a writable directory for configuration files created by the
+     * application
      */
     public function getConfigPath(): string;