{"id":14983874,"url":"https://github.com/jbtronics/settings-bundle","last_synced_at":"2026-02-28T18:04:37.680Z","repository":{"id":216196901,"uuid":"735997007","full_name":"jbtronics/settings-bundle","owner":"jbtronics","description":"A bundle to easily create typesafe, user-configurable settings for symfony applications","archived":false,"fork":false,"pushed_at":"2025-11-30T22:25:33.000Z","size":569,"stargazers_count":92,"open_issues_count":2,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-12-03T07:32:38.983Z","etag":null,"topics":["configuration","configuration-management","settings","settings-management","symfony","symfony-bundle","symfony6","symfony7","web"],"latest_commit_sha":null,"homepage":"https://jbtronics.github.io/settings-bundle/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jbtronics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"jbtronics","custom":["https://www.paypal.me/do9jhb"]}},"created_at":"2023-12-26T17:24:45.000Z","updated_at":"2025-11-30T22:22:55.000Z","dependencies_parsed_at":"2024-01-29T23:45:09.120Z","dependency_job_id":"504a1bb7-a778-4978-8f88-3a73308b862c","html_url":"https://github.com/jbtronics/settings-bundle","commit_stats":{"total_commits":273,"total_committers":5,"mean_commits":54.6,"dds":0.01831501831501836,"last_synced_commit":"deb51a945cc6c7a2004584e2ac0c92e3841b22f6"},"previous_names":["jbtronics/settings-bundle"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/jbtronics/settings-bundle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbtronics%2Fsettings-bundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbtronics%2Fsettings-bundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbtronics%2Fsettings-bundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbtronics%2Fsettings-bundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jbtronics","download_url":"https://codeload.github.com/jbtronics/settings-bundle/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbtronics%2Fsettings-bundle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29946464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T17:57:52.716Z","status":"ssl_error","status_checked_at":"2026-02-28T17:57:31.974Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration","configuration-management","settings","settings-management","symfony","symfony-bundle","symfony6","symfony7","web"],"created_at":"2024-09-24T14:08:06.329Z","updated_at":"2026-02-28T18:04:37.656Z","avatar_url":"https://github.com/jbtronics.png","language":"PHP","readme":"**[Documentation](https://jbtronics.github.io/settings-bundle/)**\n\n[![codecov](https://codecov.io/github/jbtronics/settings-bundle/graph/badge.svg?token=2IGGK9MGOW)](https://codecov.io/github/jbtronics/settings-bundle)\n\n# Settings bundle\n\nSettings-bundle is a symfony bundle that let you easily create and manage user-configurable settings, which are changeable via a web frontend.\nIt allows for easy creation of type-safe settings objects, which can be easily managed and changed via a web frontend in your symfony application.\n\n## Introduction\nBy default, symfony is mostly configured by parameters in configuration files, where a recompilation of the container is required, or via environment variables, which can not be easily changed by the application itself. \n\nHowever, you often want administrators and users of your application let change settings and configuration of your application. This bundle provides a simple way to do this. Unlike other bundles with a similar goal, this bundle tries to be as modular as possible and to be as type-safe as possible. Therefore you define your Settings as a class, and access objects of this class in your application, instead of doing simple key-value lookups with mixed return types.\n\nAll relevant definitions of settings are done directly in the settings class via metadata attributes. This makes it easy to understand and maintain the settings. The bundle also provides a simple way to generate forms to change the settings, which can be easily integrated into your application.\n\n## Features\n* Class based settings, which get easily managed by the bundle\n* Type-safe access to settings\n* Easy to use API\n* Retrieve settings via dependency injection in service constructors\n* Almost zero configuration required in many cases, as the bundle tries to derive as much information as possible from code metadata like property types, etc.\n* Various storage backends, like database, json files, PHP files, etc. (custom backends can be easily implemented)\n* Use symfony/validator to easily restrict possible values of settings parameters\n* Automatically generate forms to change settings\n* Easy possibility to version settings and automatically migrate old stored data to the current format\n* Possibility to lazy load settings, so that only the settings, which are really needed, are loaded\n* Profiler integration for easy debugging\n* Ability to use environment variables for easy configuration on automated deployments\n\n## Requirements\n* PHP 8.1 or higher\n* Symfony 6.4 or higher (compatible with Symfony 7.0)\n* Symfony/forms and Symfony/validator required if forms should be generated or validation should be used\n* twig required if you want to use the twig extension to access settings in your templates\n* doctrine/orm and doctrine-bundle required if you want to use the doctrine storage adapter\n\n## Installation\n\nAdd the bundle to your symfony project via composer:\n```bash\ncomposer require jbtronics/settings-bundle\n```\n\nIf you are using symfony flex, the bundle should be automatically enabled. Otherwise you have to add the bundle to your `config/bundles.php` file:\n\n```php\nreturn [\n    // ...\n    Jbtronics\\SettingsBundle\\JbtronicsSettingsBundle::class =\u003e ['all' =\u003e true],\n];\n```\n\n## Usage\n\n*The following section is just a quick overview. See [documentation](https://jbtronics.github.io/settings-bundle/) for full info.*\n\nSettings classes are simple PHP classes, which are annotated with the `#[Settings]` attribute. They must live in the path configured to store settings classes (normally `src/Settings`), in your symfony project. The bundle will automatically find and register all settings classes in this directory.\n\nThe properties of the classes are used for storing the different data. Similar to the `#[ORM\\Column]` attribute of doctrine, you can use the `#[SettingsParameter]` attribute to make a class property to a managed parameter. The properties can be public, protected or private (as SettingsBundle accesses them via reflection), but you have some kind of possibility to access the properties to get/set the configuration parameters in your software.\nYou have to configure, which type mapper should be used to map the normalized data from the storage backend to the type of property. The bundle comes with a few default type mappers, but you can also implement your own type mappers.\n\n```php\n\u003c?php\n// src/Settings/TestSettings.php\n\nnamespace App\\Settings;\n\nuse Jbtronics\\SettingsBundle\\Settings\\Settings;\nuse Jbtronics\\SettingsBundle\\Settings\\SettingsParameter;\nuse Jbtronics\\SettingsBundle\\ParameterTypes\\StringType;\nuse Jbtronics\\SettingsBundle\\ParameterTypes\\IntType;\nuse Jbtronics\\SettingsBundle\\Storage\\JSONFileStorageAdapter;\nuse Jbtronics\\SettingsBundle\\Settings\\SettingsTrait;\nuse Symfony\\Component\\Validator\\Constraints as Assert;\n\n\n// The settings attribute makes a simple class to settings\n// You can configure the storage backend (here JSON files) to use either here or globally in the bundle configuration\n#[Settings(storageAdapter: JSONFileStorageAdapter::class)]\nclass TestSettings {\n    use SettingsTrait; // Disable constructor and __clone methods\n\n     //The properties are public here for simplicity, but it can also be protected or private\n\n    //In many cases this attribute with zero config is enough, the type mapper is then derived from the declared type of the property\n    #[SettingsParameter()]\n    public string $myString = 'default value'; // The default value can be set right here in most cases\n\n    //Or you can explicitly set the type mapper and some options\n    #[SettingsParameter(type: IntType::class, label: 'My Integer', description: 'This value is shown as help in forms.')] \n    #[Assert\\Range(min: 5, max: 10,)] // You can use symfony/validator to restrict possible values\n    public ?int $myInt = null;\n}\n```\n\nThe main way to work with settings is to use the `SettingsManagerInterface` service. It offers a `get()` method, which allows to retrieve the current settings for a given settings class. If not loaded yet, the manager will load the desired settings from the storage backend (or initialize a fresh instance with default values). The instances are cached, so that the manager will always return the same instance for a given settings class. The manager also offers a `save()` method, which allows to save the current settings to the storage backend and persist the changes.\n\n```php\n\nuse Jbtronics\\SettingsBundle\\Settings\\SettingsManagerInterface;\n\nclass ExampleService {\n    public function __construct(private SettingsManagerInterface $settingsManager) {}\n\n    public function accessAndSaveSettings(): void\n    {\n        /** @var TestSettings $settings This is an instance of our previously defined setting class, containing the stored settings */\n        $settings = $this-\u003esettingsManager-\u003eget(TestSettings::class);\n\n        //To read the current settings value, just access the property\n        dump('My string is: ' . $settings-\u003emyString);\n\n        //To change the settings, just change the property (or call the setter)\n        $settings-\u003emyString = 'new value';\n\n        //And save the settings to the storage backend\n        $this-\u003esettingsManager-\u003esave($settings);\n\n\n        //You can also access the settings via a given name (which is the part before the \"Settings\" suffix of the class name in lowercase, by default)\n        $settings = $this-\u003esettingsManager-\u003eget('test');\n\n        //You can set an invalid value to the parameters\n        $settings-\u003emyInt = 42;\n\n        //But the bundle will throw an exception, when you try to save the settings\n        $this-\u003esettingsManager-\u003esave($settings); // Throws an excpetion\n    }\n}\n\n```\n\nAlternatively if you have a service, which depends on the settings, you can inject the current settings instance directly via dependency injection. \nThe bundle registers a service for each settings class, which can be injected into your services like any other service. \nInternally the settings manager `get()` method is called to retrieve a lazy loaded settings instance:\n\n```php\nclass ExampleService {\n    public function __construct(private TestSettings $settings) {\n        //This is equivalent to calling $settings = $settingsManager-\u003eget(TestSettings::class, lazy: true)\n        //The settings are lazy, meaning that they are only loaded from storage, when you access a property\n        if ($this-\u003esettings-\u003emyString === 'some value') {\n            //Do something\n        }\n    }\n}\n```\n\nThe instance injected via dependency injection is the same as the one you would get via the settings manager.\nThis means, that all changes to the settings instance are updated automatically in all parts of your application.\n\n### Forms\n\nThe bundle can automatically generate forms to change settings classes. This is done via the `SettingsFormFactoryInterface`, which creates a form builder containing fields to edit one or more settings classes. You can also render just a subset of the settings. Validation attributes are checked and mapped to form errors. This way you can easily create a controller, to let users change the settings:\n\n```php\n\u003c?php\n\nclass SettingsFormController {\n\n    public function __construct(\n        private SettingsManagerInterface $settingsManager,\n        private SettingsFormFactoryInterface $settingsFormFactory,\n        ) {}\n\n    #[Route('/settings', name: 'settings')]\n    public function settingsForm(Request $request): Response\n    {\n        //Create a temporary copy of the settings object, which we can modify in the form without breaking anything with invalid data\n        $settings = $this-\u003esettingsManager-\u003ecreateTemporaryCopy(TestSettings::class);\n\n        //Create a builder for the settings form\n        $builder = $this-\u003esettingsFormFactory-\u003ecreateSettingsFormBuilder($settings);\n\n        //Add a submit button, so we can save the form\n        $builder-\u003eadd('submit', SubmitType::class);\n\n        //Create the form\n        $form = $builder-\u003egetForm();\n\n        //Handle the form submission\n        $form-\u003ehandleRequest($request);\n\n        //If the form was submitted and the data is valid, then it\n        if ($form-\u003eisSubmitted() \u0026\u0026 $form-\u003eisValid()) {\n            //Merge the valid data back into the managed instance\n            $this-\u003esettingsManager-\u003emergeTemporaryCopy($settings);\n\n            //Save the settings to storage\n            $this-\u003esettingsManager-\u003esave();\n        }\n\n        //Render the form\n        return $this-\u003erender('settings.html.twig', [\n            'form' =\u003e $form-\u003ecreateView(),\n        ]);\n    }\n}\n```\n\nForm rendering can be customized via the Parameter attributes. See [documentation](https://jbtronics.github.io/settings-bundle/) for full info.\n\n### Twig templates\n\nIn twig templates you can access the settings via the `settings_instance()` function, which behaves like the `SettingsManagerInterface::get()` function and returns the current settings instance:\n\n```twig\n{# @var settings \\App\\Settings\\TestSettings #}\n{% set settings = settings_instance('test') %}\n{{ dump(settings) }}\n\n{# or directly #}\n{{ settings_instance('test').myString }}\n```\n\n## License\n\nSettingsBundle is licensed under the MIT License.\nThis mostly means that you can use this bundle for whatever you want (even use it commercially)\nas long as you retain the copyright/license information.\n\nSee [LICENSE](https://github.com/jbtronics/settings-bundle/blob/master/LICENSE) for more information.\n","funding_links":["https://github.com/sponsors/jbtronics","https://www.paypal.me/do9jhb"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbtronics%2Fsettings-bundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbtronics%2Fsettings-bundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbtronics%2Fsettings-bundle/lists"}