adachsoft / site-settings
Framework-independent core for validated public, private, and encrypted secret site settings.
Requires
- php: ^8.3
- ext-json: *
- ext-sodium: *
Requires (Dev)
- adachsoft/php-code-style: ^0.7.3
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^12.5
- rector/rector: ^2.8
- symplify/phpstan-rules: ^14.19
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A framework-independent PHP library for defining and managing validated site settings. It supports public, private, and encrypted secret values, with schema-driven validation and change auditing. Storage is supplied by the host application through repository interfaces; no framework or storage adapter is required.
Features
- Typed setting definitions with defaults and validation constraints.
- Separate public and administrative views that do not reveal secret values.
- Atomic validation of updates before values are persisted, with change-log entries.
- Sodium-based secret encryption and key rotation.
- Repository and secret-provider contracts for application-specific integration.
Requirements
- PHP 8.3 or newer
ext-jsonext-sodium
Installation
composer require adachsoft/site-settings
Define a schema
use AdachSoft\SiteSettings\Enum\SettingTypeEnum;
use AdachSoft\SiteSettings\Enum\SettingVisibilityEnum;
use AdachSoft\SiteSettings\Model\SettingDefinition;
use AdachSoft\SiteSettings\Model\SettingsSchema;
$schema = new SettingsSchema([
new SettingDefinition(
key: 'site.title',
type: SettingTypeEnum::String,
defaultValue: 'Example site',
visibility: SettingVisibilityEnum::Public,
description: 'The public site title.',
minLength: 1,
maxLength: 120,
),
new SettingDefinition(
key: 'mail.password',
type: SettingTypeEnum::Secret,
description: 'SMTP password.',
),
]);
Usage
Construct SiteSettingsService with the schema, implementations of SettingRepositoryInterface and SettingChangeLogRepositoryInterface, and a SecretCipherInterface. The package deliberately leaves persistence to the host application.
getPublic() returns public settings and configured defaults. getAdminView() returns setting DTOs; secret DTOs contain only whether a value is set, its last four characters, and its update time. update() validates all changes before writing, treats null as a reset to the default (or deletion for secrets), and appends audit entries. Secret audit entries contain last-four-character metadata only.
Backend code that needs a secret can depend on SecretProviderInterface and call get($key). Use SodiumSecretCipher with a 32-byte key and a key identifier supplied by the host application. The package does not read secrets from the environment. rotateKey() re-encrypts configured secrets using the supplied old and new ciphers.
See the schema example for a focused usage example.
Tests
Run the test suite from the repository root:
vendor/bin/phpunit --configuration phpunit.xml