README

Framework-agnostic settings management engine with hierarchical resolution across user, tenant, and application layers.

Overview

Nexus\Setting is a pure PHP package that provides a flexible, secure, and performant settings management system. It implements a three-tier hierarchical resolution system (User → Tenant → Application) with caching, encryption support, and comprehensive validation.

Key Features

Hierarchical Resolution: Settings cascade through User → Tenant → Application layers
Framework-Agnostic: Pure PHP with no framework dependencies
Type-Safe Getters: Dedicated methods for string, int, bool, float, and array types
Caching Support: Interface-driven caching with automatic invalidation
Encryption: Support for encrypting sensitive settings at rest
Schema Registry: Define and validate setting schemas programmatically
Bulk Operations: Transaction-safe bulk updates and exports
Read-Only Protection: Mark settings as immutable or protected
Audit Trail: Track all setting changes with history
Tenant Isolation: Automatic scoping for multi-tenant applications

Architecture

This package follows the Nexus monorepo architectural principles:

Logic in Packages: All business logic lives here (framework-agnostic)
Implementation in Applications: Database, models, and Laravel-specific code in apps/Atomy

Package Structure

packages/Setting/
├── composer.json              # Package definition (PHP ^8.2 only)
├── LICENSE                    # MIT License
├── README.md                  # This file
└── src/
    ├── Contracts/             # Interfaces for dependency injection
    │   ├── SettingRepositoryInterface.php
    │   ├── SettingsCacheInterface.php
    │   └── SettingsAuthorizerInterface.php
    ├── Exceptions/            # Domain-specific exceptions
    │   ├── SettingNotFoundException.php
    │   ├── ReadOnlySettingException.php
    │   └── ProtectedSettingException.php
    ├── Services/              # Business logic layer
    │   ├── SettingsManager.php
    │   ├── SettingsCacheManager.php
    │   ├── SettingsValidationService.php
    │   └── SettingsSchemaRegistry.php
    └── ValueObjects/          # Immutable value objects
        ├── SettingScope.php
        ├── SettingLayer.php
        └── EncryptedSetting.php

Installation

This package is designed for use within the Nexus monorepo. Add it to your application's composer.json:

{
    "require": {
        "azaharizaman/nexus-setting": "*@dev"
    },
    "repositories": [
        {
            "type": "path",
            "url": "../../packages/Setting"
        }
    ]
}

Then run:

composer require azaharizaman/nexus-setting:"*@dev"

Usage

Basic Usage

use Nexus\Setting\Services\SettingsManager;
use Nexus\Setting\Contracts\SettingRepositoryInterface;
use Nexus\Setting\Contracts\SettingsCacheInterface;

// Inject dependencies (bound by application layer)
$manager = new SettingsManager(
    $userRepo,      // SettingRepositoryInterface implementation
    $tenantRepo,    // SettingRepositoryInterface implementation
    $appRepo,       // SettingRepositoryInterface implementation
    $cache          // SettingsCacheInterface implementation
);

// Get setting with hierarchical resolution
$timezone = $manager->getString('timezone', 'UTC');

// Set user-specific setting
$manager->setUserSetting('user-123', 'theme', 'dark');

// Set tenant-specific setting
$manager->setTenantSetting('tenant-456', 'currency', 'MYR');

// Check if setting exists
if ($manager->has('mail.smtp.host')) {
    $host = $manager->getString('mail.smtp.host');
}

// Get setting origin (which layer it came from)
$origin = $manager->getOrigin('timezone'); // 'user', 'tenant', or 'application'

Type-Safe Getters

// String
$theme = $manager->getString('theme', 'light');

// Integer
$timeout = $manager->getInt('api.timeout', 30);

// Boolean
$enabled = $manager->getBool('feature.analytics', false);

// Float
$taxRate = $manager->getFloat('tax.rate', 0.06);

// Array
$permissions = $manager->getArray('user.permissions', []);

Bulk Operations

// Bulk update multiple settings in a transaction
$settings = [
    'timezone' => 'Asia/Kuala_Lumpur',
    'currency' => 'MYR',
    'date_format' => 'DD/MM/YYYY'
];
$manager->bulkSet($settings, 'tenant', 'tenant-456');

// Export all tenant settings
$exported = $manager->export('tenant-456');

// Import settings (restore/migration)
$manager->import($exported, 'tenant-789');

Caching

use Nexus\Setting\Services\SettingsCacheManager;

$cacheManager = new SettingsCacheManager($cacheInterface);

// Cache with TTL
$value = $cacheManager->remember('setting.key', fn() => $expensive_operation());

// Invalidate specific key
$cacheManager->forget('setting.key');

// Invalidate all settings for a scope
$cacheManager->forgetScope('tenant', 'tenant-456');

// Flush entire cache
$cacheManager->flush();

Schema Registry & Validation

use Nexus\Setting\Services\SettingsSchemaRegistry;
use Nexus\Setting\Services\SettingsValidationService;

$registry = new SettingsSchemaRegistry();

// Register a setting schema
$registry->register('api.timeout', [
    'type' => 'integer',
    'min' => 1,
    'max' => 300,
    'description' => 'API timeout in seconds'
]);

$validator = new SettingsValidationService($registry);

// Validate before setting
if ($validator->validate('api.timeout', 30)) {
    $manager->setTenantSetting('tenant-456', 'api.timeout', 30);
}

Hierarchical Resolution

Settings are resolved in the following order:

User Layer: User-specific settings (highest priority)
Tenant Layer: Tenant-specific settings
Application Layer: Application/environment defaults (lowest priority, read-only)

// Example: Getting 'timezone' setting
// 1. Check user settings for current user
// 2. If not found, check tenant settings
// 3. If not found, check application config
// 4. If not found, return default value

$timezone = $manager->getString('timezone', 'UTC');

Contracts (Interfaces)

SettingRepositoryInterface

Defines the persistence contract for settings at each layer.

interface SettingRepositoryInterface
{
    public function get(string $key, mixed $default = null): mixed;
    public function set(string $key, mixed $value): void;
    public function delete(string $key): void;
    public function has(string $key): bool;
    public function getAll(): array;
    public function getByPrefix(string $prefix): array;
    public function getMetadata(string $key): ?array;
}

SettingsCacheInterface

Defines the caching contract for settings.

interface SettingsCacheInterface
{
    public function get(string $key, mixed $default = null): mixed;
    public function set(string $key, mixed $value, ?int $ttl = null): void;
    public function forget(string $key): void;
    public function flush(): void;
    public function has(string $key): bool;
}

SettingsAuthorizerInterface

Defines the authorization contract for settings access control.

interface SettingsAuthorizerInterface
{
    public function canView(string $userId, string $key): bool;
    public function canEdit(string $userId, string $key): bool;
}

Integration with Atomy

In apps/Atomy, you'll implement:

Migrations: Database schema for settings, setting_history tables
Models: Eloquent models implementing package interfaces
Repositories: Concrete implementations of repository interfaces
Service Provider: Binding contracts to implementations
API Routes: RESTful endpoints for settings CRUD

See apps/Atomy/app/Providers/SettingsServiceProvider.php for binding examples.

Requirements Fulfilled

This package fulfills the following requirements from REQUIREMENTS.csv:

Architectural Requirements: ARC-SET-1289 to ARC-SET-1299 (Framework-agnostic design)
Business Requirements: BUS-SET-1300 to BUS-SET-1314 (Hierarchical resolution, caching, encryption)
Functional Requirements: FUN-SET-1315 to FUN-SET-1345 (31 functional requirements)
Performance Requirements: PER-SET-1346 to PER-SET-1350 (Caching, bulk operations)
Security Requirements: SEC-SET-1351 to SEC-SET-1357 (Audit logging, tenant isolation, encryption)

Testing

Package tests should be unit tests with mocked repository implementations (no database dependencies).

// Example test
$mockUserRepo = $this->createMock(SettingRepositoryInterface::class);
$mockTenantRepo = $this->createMock(SettingRepositoryInterface::class);
$mockAppRepo = $this->createMock(SettingRepositoryInterface::class);
$mockCache = $this->createMock(SettingsCacheInterface::class);

$manager = new SettingsManager($mockUserRepo, $mockTenantRepo, $mockAppRepo, $mockCache);

// Test hierarchical resolution
$mockUserRepo->expects($this->once())
    ->method('get')
    ->with('timezone', null)
    ->willReturn('Asia/Kuala_Lumpur');

$result = $manager->getString('timezone', 'UTC');
$this->assertEquals('Asia/Kuala_Lumpur', $result);

📖 Documentation

Package Documentation

Getting Started Guide
Runtime Settings Management - Multi-tenancy aware key resolution and usage patterns
API Reference
Integration Guide
Examples

Additional Resources

IMPLEMENTATION_SUMMARY.md - Implementation progress
REQUIREMENTS.md - Requirements
TEST_SUITE_SUMMARY.md - Tests
VALUATION_MATRIX.md - Valuation

License

MIT License. See LICENSE for details.

Contributing

This package is part of the Nexus monorepo. Follow the architectural guidelines in ARCHITECTURE.md.

Key Principle: Logic in Packages, Implementation in Applications.

azaharizaman / nexus-setting

Maintainers

Package info

Statistics

Security