Release version 1.0.0-RC17

Author: ddebowczyk

docs-build/mint.json

@@ -244,6 +244,7 @@
             "group": "Release Notes",
             "pages": [
                 "release-notes/versions",
+                "release-notes/v1.0.0-RC17",
                 "release-notes/v1.0.0-RC16",
                 "release-notes/v1.0.0-RC15",
                 "release-notes/v1.0.0-RC14",

docs-build/release-notes/v1.0.0-RC17.mdx

@@ -0,0 +1 @@
+- (utils) New, simplified Settings class with bugs fixed.

docs/release-notes/v1.0.0-RC17.mdx

@@ -0,0 +1 @@
+- (utils) New, simplified Settings class with bugs fixed.

packages/addons/release_notes/v1.0.0-RC17.md

@@ -0,0 +1 @@
+- (utils) New, simplified Settings class with bugs fixed.

packages/auxiliary/release_notes/v1.0.0-RC17.md

@@ -0,0 +1 @@
+- (utils) New, simplified Settings class with bugs fixed.

packages/config/release_notes/v1.0.0-RC17.md

@@ -0,0 +1 @@
+- (utils) New, simplified Settings class with bugs fixed.

packages/config/src/Settings.php

@@ -1,258 +1,128 @@
-<?php
+<?php declare(strict_types=1);
+
 namespace Cognesy\Config;
 
+use Adbar\Dot;
 use Cognesy\Config\Exceptions\MissingSettingException;
 use Cognesy\Config\Exceptions\NoSettingsFileException;
-use Exception;
-use InvalidArgumentException;
-use RuntimeException;
 
-class Settings
+/**
+ * Lightweight, read-only config loader.
+ *
+ * Search order (first match wins):
+ *   1. Path set via Settings::setPath('/dir')         ← highest priority
+ *   2. INSTRUCTOR_CONFIG_PATHS or INSTRUCTOR_CONFIG_PATH (comma-separated)
+ *   3. Internal defaults listed in DEFAULT_PATHS
+ *
+ * Usage:
+ *   Settings::setPath(__DIR__.'/config');       // optional override
+ *   $dsn = Settings::get('database', 'dsn');    // dot-notation supported
+ *
+ * Implementation notes:
+ *   • All data is cached per-group in static $cache (Dot objects).
+ *   • Settings::flush() clears both cache _and_ custom override.
+ *   • locate() walks the final path list once per group; O(N) worst-case.
+ *   • Throws:
+ *       – NoSettingsFileException   when group file missing
+ *       – MissingSettingException   when key absent and no default given
+ */
+final class Settings
 {
-    /**
-     * @var ?string The path to the configuration files.
-     */
-    static private ?string $path = null;
-
-    /**
-     * @var array<string> The default path to the configuration files.
-     */
-    static private array $defaultPaths = [
+    private const DEFAULT_PATHS = [
         'config/',
         'vendor/cognesy/instructor-php/config/',
+        'vendor/cognesy/instructor-struct/config/',
+        'vendor/cognesy/instructor-polyglot/config/',
+        'vendor/cognesy/instructor-config/config/',
     ];
 
-    /**
-     * @var array The loaded settings.
-     */
-    static private array $settings = [];
-
-    // STATIC ////////////////////////////////////////////////////////////////////
+    private static array $customPaths = [];
+    private static array $cache = [];   // group => Dot
 
-    /**
-     * Sets the path to the configuration files and clears the loaded settings.
-     *
-     * @param string $path The new path to the configuration files.
-     */
-    public static function setPath(string $path) : void {
-        self::$path = self::resolvePath($path);
-        self::$settings = [];
+    /** Highest-priority override */
+    public static function setPath(string $dir): void {
+        self::$customPaths = [self::dir($dir)];
+        self::$cache = [];
     }
 
-    /**
-     * Gets the current path to the configuration files.
-     *
-     * @return string The current path to the configuration files.
-     */
-    public static function getPath(?string $group = null): string {
-        return self::$path
-            ?? self::getFirstValidPath(
-                paths: $_ENV['INSTRUCTOR_CONFIG_PATHS']
-                    ?? $_ENV['INSTRUCTOR_CONFIG_PATH']
-                    ?? self::$defaultPaths,
-                group: $group,
-            );
+    /** Drop all cached groups (tests, hot-reload) */
+    public static function flush(): void {
+        self::$cache = [];
+        self::$customPaths = [];
     }
 
-    /**
-     * Gets the default path to the configuration files.
-     * @return array<string> The default paths to the configuration files.
-     * @throws Exception
-     */
-    public static function getDefaultPaths(): array {
-        return self::$defaultPaths;
-    }
-
-    /**
-     * Gets a setting value by group and key.
-     *
-     * @param string $group The settings group.
-     * @param string $key The settings key.
-     * @param mixed $default The default value if the key is not found.
-     * @return mixed The setting value.
-     * @throws Exception If the group is not provided or the key is not found and no default value is provided.
-     */
-    public static function get(string $group, string $key, mixed $default = null) : mixed {
-        if (empty($group)) {
-            throw new InvalidArgumentException("Settings group not provided");
+    public static function has(string $group, ?string $key = null): bool {
+        if ($key === null) {
+            return self::locate($group) !== null;
         }
 
-        if (!self::isGroupLoaded($group)) {
-            self::$settings[$group] = dot(self::loadGroup($group));
-        }
-
-        if ($default === null && !self::has($group, $key)) {
-            throw new MissingSettingException("Settings key not found: $key in group: $group and no default value provided");
-        }
-        return self::$settings[$group]->get($key, $default);
+        $dot = self::load($group, false);
+        return $dot?->has($key) ?? false;
     }
 
-    /**
-     * Checks if a setting exists by group and key.
-     * If key is not provided, it checks if the group exists.
-     *
-     * @param string $group The settings group.
-     * @param ?string $key The settings key.
-     * @return bool True if the setting exists, false otherwise.
-     * @throws Exception If the group is not provided.
-     */
-    public static function has(string $group, ?string $key = null) : bool {
-        if (empty($group)) {
-            throw new RuntimeException("Settings group not provided");
-        }
-
-        if (empty($key)) {
-            return self::hasGroup($group);
-        }
-
-        if (!self::isGroupLoaded($group)) {
-            self::$settings[$group] = dot(self::loadGroup($group));
-        }
-
-        return self::$settings[$group]->has($key);
-    }
-
-    /**
-     * Checks if a settings group exists.
-     *
-     * @param string $group The settings group.
-     * @return bool True if the group exists, false otherwise.
-     * @throws Exception If the group is not provided.
-     */
-    public static function hasGroup(string $group) : bool {
-        if (empty($group)) {
-            throw new RuntimeException("Settings group not provided");
-        }
-
-        if (!self::isGroupLoaded($group)) {
-            self::$settings[$group] = dot(self::loadGroup($group));
+    public static function get(string $group, string $key, mixed $default = null): mixed {
+        $dot = self::load($group);
+        if (!$dot->has($key)) {
+            if (func_num_args() === 3) {
+                return $default;
+            }
+            throw new MissingSettingException("Key '$key' missing in '$group'");
         }
-
-        return !empty(self::$settings[$group]);
+        return $dot->get($key);
     }
 
-    /**
-     * Gets a settings group.
-     *
-     * @param string $group The settings group.
-     * @return mixed The settings group.
-     * @throws Exception If the group is not provided or the settings file is not found.
-     */
-    public static function getGroup(string $group) : mixed {
-        if (empty($group)) {
-            throw new RuntimeException("Settings group not provided");
-        }
+    // ----------------------------------------------------------------
 
-        if (!self::isGroupLoaded($group)) {
-            self::$settings[$group] = dot(self::loadGroup($group));
+    private static function load(string $group, bool $throw = true): ?Dot {
+        if (isset(self::$cache[$group])) {
+            return self::$cache[$group];
         }
-
-        return self::$settings[$group];
-    }
-
-    /**
-     * Sets a setting value by group and key.
-     *
-     * @param string $group The settings group.
-     * @param string $key The settings key.
-     * @param mixed $value The value to set.
-     */
-    public static function set(string $group, string $key, mixed $value) : void {
-        if (!self::isGroupLoaded($group)) {
-            self::$settings[$group] = dot(self::loadGroup($group));
+        $file = self::locate($group);
+        if ($file === null) {
+            if ($throw) {
+                throw new NoSettingsFileException("Config '$group' not found in any search path");
+            }
+            return null;
         }
-
-        self::$settings[$group] = self::$settings[$group]->set($key, $value);
+        /** @var array $data */
+        $data = require $file;
+        return self::$cache[$group] = new Dot($data);
     }
 
-    /**
-     * Unsets a settings group.
-     *
-     * @param string $group The settings group.
-     */
-    public static function unset(string $group) : void {
-        if (self::isGroupLoaded($group)) {
-            self::$settings[$group] = [];
+    /** Return full path to file or null */
+    private static function locate(string $group): ?string {
+        foreach (self::paths() as $dir) {
+            $file = $dir . $group . '.php';
+            if (is_file($file)) {
+                return $file;
+            }
         }
+        return null;
     }
 
-    // INTERNAL //////////////////////////////////////////////////////////////////
-
-    /**
-     * Checks if a settings group is loaded.
-     *
-     * @param string $group The settings group.
-     * @return bool True if the group is loaded, false otherwise.
-     */
-    private static function isGroupLoaded(string $group) : bool {
-        return isset(self::$settings[$group]) && (self::$settings[$group] !== null);
-    }
-
-    /**
-     * Loads a settings group from a file.
-     *
-     * @param string $group The settings group.
-     * @return array The loaded settings group.
-     * @throws Exception If the settings file is not found.
-     */
-    private static function loadGroup(string $group) : array {
-        $rootPath = self::getPath($group);
-
-        // Ensure the rootPath ends with a directory separator
-        $rootPath = rtrim($rootPath, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR;
-
-        $path = $rootPath . $group . '.php';
-
-        if (!file_exists($path)) {
-            throw new NoSettingsFileException("Settings file not found: $path");
+    /** Final search path list, in order */
+    private static function paths(): array {
+        if (self::$customPaths) {
+            return self::$customPaths;
         }
-
-        return require $path;
-    }
-
-    /**
-     * Resolves a given path to an absolute path.
-     *
-     * @param string $path The path to resolve.
-     * @return string The resolved absolute path.
-     */
-    private static function resolvePath(string $path): string {
-        $path = self::isAbsolutePath($path) ? $path : BasePath::get($path);
-        // if path does not end with DIRECTORY_SEPARATOR, add it
-        return rtrim($path, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR;
+        $env = getenv('INSTRUCTOR_CONFIG_PATHS')
+            ?: ($_ENV['INSTRUCTOR_CONFIG_PATHS'] ?? '')
+            ?: getenv('INSTRUCTOR_CONFIG_PATH')
+            ?: ($_ENV['INSTRUCTOR_CONFIG_PATH'] ?? '');
+        $envPaths = array_filter(array_map(fn($p) => self::dir($p), explode(',', $env)));
+        return array_unique([...$envPaths, ...array_map(fn($p) => self::dir($p), self::DEFAULT_PATHS)]);
     }
 
-    private static function getFirstValidPath(string|array $paths, ?string $group = null): string {
-        $paths = is_array($paths) ? $paths : explode(',', $paths);
-        if (empty($paths)) {
-            throw new InvalidArgumentException("No settings paths provided");
+    /** Normalise dir string, always with trailing slash */
+    private static function dir(string $dir): string {
+        $dir = rtrim($dir);
+        if ($dir === '') {
+            return '';
         }
-
-        foreach ($paths as $path) {
-            $resolvedPath = self::resolvePath($path);
-            if (is_dir($resolvedPath)) {
-                // if $group is not provided, return the resolved path
-                if (empty($group)) {
-                    return $resolvedPath;
-                }
-                // check if group file exists
-                $groupPath = $resolvedPath . $group . '.php';
-                if (file_exists($groupPath)) {
-                    return $resolvedPath;
-                }
-            }
+        // relative → project base
+        if (!str_starts_with($dir, '/') && !preg_match('/^[A-Z]:\\\\/i', $dir)) {
+            $dir = BasePath::get($dir);
         }
-
-        throw new NoSettingsFileException("No valid settings path found in: " . implode(', ', $paths));
-    }
-
-    /**
-     * Checks if a given path is absolute.
-     *
-     * @param string $path The path to check.
-     * @return bool True if the path is absolute, false otherwise.
-     */
-    private static function isAbsolutePath(string $path): bool {
-        return str_starts_with($path, '/') || preg_match('/^[a-zA-Z]:\\\\/', $path) === 1;
+        return rtrim($dir, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR;
     }
 }