Search by

adachsoft / site-settings

Arkadiusz Adach

Framework-independent core for validated public, private, and encrypted secret site settings.

Package info

gitlab.com/a.adach/site-settings

Issues

pkg:composer/adachsoft/site-settings

Statistics

Installs: 16

Dependents: 2

Suggesters: 0

Stars: 0

v0.1.0 2026-11-22 07:53 UTC

This package is auto-updated.

Last update: 2026-11-22 06:54:14 UTC


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-json
  • ext-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