PHPackages                             azaharizaman/nexus-setting - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. azaharizaman/nexus-setting

ActiveLibrary[Utility & Helpers](/categories/utility)

azaharizaman/nexus-setting
==========================

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

v0.1.0-alpha1(2mo ago)023MITPHP ^8.3

Since May 5Compare

[ Source](https://github.com/azaharizaman/nexus-setting)[ Packagist](https://packagist.org/packages/azaharizaman/nexus-setting)[ RSS](/packages/azaharizaman-nexus-setting/feed)WikiDiscussions Synced 3w ago

READMEChangelogDependenciesVersions (2)Used By (3)

Nexus\\Setting
==============

[](#nexussetting)

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

Overview
--------

[](#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
------------

[](#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
------------

[](#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

[](#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
------------

[](#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
-----

[](#usage)

### Basic 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

[](#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-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

[](#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

[](#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
-----------------------

[](#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)
----------------------

[](#contracts-interfaces)

### SettingRepositoryInterface

[](#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

[](#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

[](#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
----------------------

[](#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
----------------------

[](#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
-------

[](#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
---------------

[](#-documentation)

### Package Documentation

[](#package-documentation)

- [Getting Started Guide](docs/getting-started.md)
- [Runtime Settings Management](docs/runtime-settings-management.md) - Multi-tenancy aware key resolution and usage patterns
- [API Reference](docs/api-reference.md)
- [Integration Guide](docs/integration-guide.md)
- [Examples](docs/examples/)

### Additional Resources

[](#additional-resources)

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

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

Contributing
------------

[](#contributing)

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

**Key Principle**: Logic in Packages, Implementation in Applications.

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance84

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

81d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/117408?v=4)[Azahari Zaman](/maintainers/azaharizaman)[@azaharizaman](https://github.com/azaharizaman)

---

Tags

phpconfigurationSettingsmulti-tenanthierarchicalnexus

### Embed Badge

![Health badge](/badges/azaharizaman-nexus-setting/health.svg)

```
[![Health](https://phpackages.com/badges/azaharizaman-nexus-setting/health.svg)](https://phpackages.com/packages/azaharizaman-nexus-setting)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)