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:

1. User Layer: User-specific settings (highest priority)
2. Tenant Layer: Tenant-specific settings
3. 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:

1. Migrations: Database schema for settings, setting_history tables
2. Models: Eloquent models implementing package interfaces
3. Repositories: Concrete implementations of repository interfaces
4. Service Provider: Binding contracts to implementations
5. 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.