Search by

adachsoft / site-settings-bundle

Arkadiusz Adach

Symfony bundle for schema-driven public, private, and secret site settings.

Package info

gitlab.com/a.adach/site-settings-bundle

Issues

pkg:composer/adachsoft/site-settings-bundle

Statistics

Installs: 5

Dependents: 0

Suggesters: 0

Stars: 0

v0.1.0 2026-11-22 10:01 UTC

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/public returns public settings.
  • GET /api/v1/admin/settings returns the administrative view, with secret values replaced by safe metadata.
  • PATCH /api/v1/admin/settings updates non-secret settings.
  • PATCH /api/v1/admin/settings/secrets updates 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.