adachsoft / site-settings-bundle
Symfony bundle for schema-driven public, private, and secret site settings.
Requires
- php: ^8.3
- adachsoft/site-settings: ^0.1.0
- adachsoft/site-settings-json: ^0.1.0
- symfony/framework-bundle: ^7.2
- zircote/swagger-php: ^4.10
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
This package is auto-updated.
Last update: 2026-11-22 09:03:48 UTC
README
A Symfony bundle that exposes schema-driven site settings over HTTP. It integrates the adachsoft/site-settings service with JSON-file persistence and provides separate public, administrative, and secret-setting endpoints.
Features
- Declare setting keys, types, visibility, defaults, descriptions, and numeric constraints in Symfony configuration.
- Serve public settings with shared-cache headers.
- Read and update administrative settings with schema validation.
- Keep secret updates on a separately permissioned endpoint and encrypt secrets with Sodium when a cipher key is configured.
- Persist settings and change history using the JSON repositories from
adachsoft/site-settings-json.
Installation
composer require adachsoft/site-settings-bundle
Register AdachSoft\SiteSettingsBundle\SiteSettingsBundle in the Symfony application bundle configuration and import the bundle routes (for example, from config/routes.yaml):
site_settings:
resource: '@SiteSettingsBundle/Resources/config/routes.yaml'
Configure a writable storage directory and the setting definitions:
site_settings:
storage_dir: '%kernel.project_dir%/var/site-settings'
cipher_key: '%env(default::SITE_SETTINGS_CIPHER_KEY)%'
definitions:
- key: site_name
type: string
visibility: public
default: Example site
- key: support_email
type: email
visibility: private
- key: external_api_token
type: secret
visibility: secret
Generate a base64-encoded 32-byte Sodium secretbox key for SITE_SETTINGS_CIPHER_KEY when secret-setting writes are required. Without a key, non-secret settings remain available, while secret writes are rejected safely.
Requirements
- PHP 8.3 or later.
- Symfony FrameworkBundle 7.2 or later.
- A writable directory for JSON settings and change-history files.
- A base64-encoded Sodium secretbox key when secret-setting updates are needed.
Usage
Import the bundle routes, configure the setting schema, and call the HTTP endpoints described below. The usage examples include bundle registration, configuration, and request samples.
HTTP endpoints
GET /api/v1/settings/publicreturns public settings.GET /api/v1/admin/settingsreturns the administrative view, with secret values replaced by safe metadata.PATCH /api/v1/admin/settingsupdates non-secret settings.PATCH /api/v1/admin/settings/secretsupdates secret settings.
Administrative routes include _permission metadata (settings.read, settings.write, and settings.secret.write). Configure the application's security layer to enforce these permissions. See usage examples for sample requests and responses.