{"id":20499853,"url":"https://github.com/sherlockode/configuration-bundle","last_synced_at":"2025-04-13T18:52:41.863Z","repository":{"id":33164480,"uuid":"153753277","full_name":"sherlockode/configuration-bundle","owner":"sherlockode","description":"Symfony bundle for configuration purposes. Let users define application parameters in your backoffice.","archived":false,"fork":false,"pushed_at":"2023-12-18T20:29:59.000Z","size":145,"stargazers_count":21,"open_issues_count":2,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2023-12-19T15:02:20.263Z","etag":null,"topics":["configuration","php","symfony","symfony-bundle"],"latest_commit_sha":null,"homepage":"","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/sherlockode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2018-10-19T08:46:05.000Z","updated_at":"2024-01-26T11:40:43.642Z","dependencies_parsed_at":"2024-01-24T16:31:23.458Z","dependency_job_id":"9216e19c-54a8-4664-bf91-3125b4a66141","html_url":"https://github.com/sherlockode/configuration-bundle","commit_stats":{"total_commits":78,"total_committers":6,"mean_commits":13.0,"dds":"0.16666666666666663","last_synced_commit":"37b0cde3fc802cf645ab2bfa02866d4462ef4e94"},"previous_names":[],"tags_count":29,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherlockode%2Fconfiguration-bundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherlockode%2Fconfiguration-bundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherlockode%2Fconfiguration-bundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherlockode%2Fconfiguration-bundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sherlockode","download_url":"https://codeload.github.com/sherlockode/configuration-bundle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248766004,"owners_count":21158296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","php","symfony","symfony-bundle"],"created_at":"2024-11-15T18:18:49.387Z","updated_at":"2025-04-13T18:52:41.841Z","avatar_url":"https://github.com/sherlockode.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Sherlockode ConfigurationBundle\n===============================\n\nThis bundle is built to allow users to define configuration options, useful in admin panels.\nGet rid of the business logic variables in your `ENV` or `parameters.yml` file !\n\nAvailable features:\n\n* Define multiple configuration entries available for the users\n* Retrieve configuration values anywhere in your code for business logic\n* Use or create custom parameter types for a better user experience\n\n[![CircleCI](https://circleci.com/gh/sherlockode/configuration-bundle.svg?style=shield)](https://circleci.com/gh/sherlockode/configuration-bundle)\n[![Total Downloads](https://poser.pugx.org/sherlockode/configuration-bundle/downloads)](https://packagist.org/packages/sherlockode/configuration-bundle)\n[![Latest Stable Version](https://poser.pugx.org/sherlockode/configuration-bundle/v/stable)](https://packagist.org/packages/sherlockode/configuration-bundle)\n\n## Installation\n\nThe best way to install this bundle is to rely on [Composer](https://getcomposer.org/):\n\n```bash\n$ composer require sherlockode/configuration-bundle\n```\n\n## Setup\n\nEnable the bundle in the kernel\n\n```php\n\u003c?php\n// config/bundles.php\n\nreturn [\n    // ...\n    Sherlockode\\ConfigurationBundle\\SherlockodeConfigurationBundle::class =\u003e ['all' =\u003e true],\n];\n```\n\nYou will need a `Parameter` entity in order to store the configuration values in the database.\n\n```php\n\u003c?php\n\nnamespace App\\Entity;\n\nuse Doctrine\\ORM\\Mapping as ORM;\nuse Sherlockode\\ConfigurationBundle\\Model\\Parameter as BaseParameter;\n\n#[ORM\\Entity]\n#[ORM\\Table(name: 'parameter')]\nclass Parameter extends BaseParameter\n{\n    #[ORM\\Id]\n    #[ORM\\Column(name: 'id', type: 'integer')]\n    #[ORM\\GeneratedValue(strategy: 'AUTO')]\n    protected int $id;\n\n    #[ORM\\Column(name: 'path', type: 'string')]\n    protected string $path;\n\n    #[ORM\\Column(name: 'value', type: 'text', nullable: true)]\n    protected ?string $value = null;\n}\n```\n\n## Configuration\n\nThe entity class you just created must be set in the bundle's configuration:\n\n```yaml\n# config/packages/sherlockode_configuration.yaml\nsherlockode_configuration:\n    entity_class:\n        parameter: App\\Entity\\Parameter\n```\n\nNow you are free to define any configuration entry you'd like by using the `parameters` key:\n```yaml\n# config/packages/sherlockode_configuration.yaml\nsherlockode_configuration:\n    entity_class:\n        parameter: App\\Entity\\Parameter\n    parameters:\n        contact_email:\n            label: My customer service contact email\n            type: simple # the \"simple\" type renders by default as a TextType form element\n        max_user_login_attempts:\n            label: Max login attemps before account blocking\n            type: simple\n            options:\n                # it is possible to customize the form type to use for a \"simple\" parameter type\n                subtype: Symfony\\Component\\Form\\Extension\\Core\\Type\\IntegerType\n        sales_date:\n            label: Sales start date\n            type: datetime\n            options:\n                required: false\n```\n\n### Translations\n\nBy default parameters labels are not translated in the form provided by the bundle.\nIf you want to use translations you can define a `translation_domain` key globally and/or for each parameter\nand use your translation key as the label.\n\n```yaml\n# config/packages/sherlockode_configuration.yaml\nsherlockode_configuration:\n    translation_domain: my_app_domain # default domain is false (no translation)\n    parameters:\n        contact_email:\n            label: customer.contact_email\n            type: simple\n            translation_domain: my_param_domain # overrides the global domain\n        sales_date:\n            # no translation domain, fallback to my_app_domain\n            label: sales.start_date\n            type: datetime\n```\n\n### Options\n\nEach type of field may accept a various range of options that can be defined under the `options` key.\n\nEvery field may have a `required` option to define if the input field will be required (it defaults to true).\nThe other options are up to the field and its needs. For instance, the choice field allow to define\n`multiple` and `choices` options in order to customize the form.\n\n```yaml\n# config/packages/sherlockode_configuration.yaml\nsherlockode_configuration:\n    parameters:\n        guess_access:\n            label: Allow guest access\n            type: choice\n            options:\n                required: true\n                multiple: true\n                choices:\n                    yes: 1\n                    no: 0\n```\n\nEvery field may also have a `constraints` option to define validation constraints.\nYou can use Symfony built-in constraints or add your own:\n\n```yaml\n# config/packages/sherlockode_configuration.yaml\nsherlockode_configuration:\n    parameters:\n        website_title:\n            label: Website title\n            type: simple\n            options:\n                required: true\n                constraints:\n                    - NotBlank: ~\n                    - Length:\n                        min: 8\n                        max: 255\n                        minMessage: 'This field must be at least {{ limit }} characters long'\n                        maxMessage: 'This field must be at least {{ limit }} characters long'\n                    - App\\Validator\\ContainsAlphanumeric:\n                        message: \"The website title can only contains alphanumeric characters\" \n```\n\n## Usage\n\n### Default controller\n\nAll configured parameters can be edited with the provided controller.\nYou may import the routing file in order to access it, the listing will be available at URI `/parameters`.\n\n```yaml\n# config/routing.yaml\nsherlockode_configuration:\n    resource: \"@SherlockodeConfigurationBundle/Resources/config/routing.xml\"\n```\n\nYou can also modify the default template used by this controller with the `templates` configuration entry point:\n\n```yaml\n# config/packages/sherlockode_configuration.yaml\nsherlockode_configuration:\n    templates:\n        edit_form: 'Parameter/my_parameter_list.html.twig'\n```\n\n### Custom code for the Form\n\nIf you have more specific usages, you can build your own form using the `ParametersType`,\na `FormType` dedicated to editing the parameters.\nThe model data for the form is an associative array of the paths and existing values.\nYou can get the existing parameters from the DB using the service `sherlockode_configuration.parameter_manager`:\n\n```php\n\u003c?php\nuse Sherlockode\\ConfigurationBundle\\Form\\Type\\ParametersType;\nuse Sherlockode\\ConfigurationBundle\\Manager\\ParameterManagerInterface;\n\n// $parameterManager has been injected\n/** @var ParameterManagerInterface $parameterManager */\n$data = $parameterManager-\u003egetAll();\n// or using an associative array:\n// $data = ['contact_email' =\u003e 'me@example.com', 'max_user_login_attempts' =\u003e 5];\n\n$form = $this-\u003ecreateForm(ParametersType::class, $data);\n// handle form submission\n$form-\u003ehandleRequest($request);\nif ($form-\u003eisSubmitted() \u0026\u0026 $form-\u003eisValid()) {\n    $params = $form-\u003egetData();\n    foreach ($params as $path =\u003e $value) {\n        $parameterManager-\u003eset($path, $value);\n    }\n    $parameterManager-\u003esave();\n}\n//...\n```\n\n### Access configuration values\n\nYou are now able to retrieve any configuration value by using the `get` method from the parameter manager.\nIt is possible to provide a default value to return if the entry has not been set yet.\n\n```php\n$email = $parameterManager-\u003eget('contact_email');\n$maxAttempts = $parameterManager-\u003eget('max_user_login_attempts', 5);\n```\n\n### Import / export from the browser\n\nYou can export or import parameters in a yaml file. You have two routes for these operations:\n\n* `sherlockode_configuration.export`\n* `sherlockode_configuration.import`\n\nYou also can customize the import form template by defining your own in the configuration:\n\n```yaml\n# config/packages/sherlockode_configuration.yaml\nsherlockode_configuration:\n    templates:\n        import_form: 'Parameter/my_import_form.html.twig'\n```\n\n### Import / export from CLI\n\nYou can export or import your parameters with these two Symfony commands:\n\n* `sherlockode:configuration:export`\n* `sherlockode:configuration:import`\n\nThese commands rely on the [Symfony secrets mechanism](https://symfony.com/doc/current/configuration/secrets.html).\nSo be sure to generate your credentials with the following command:\n\n```shell\n$ php bin/console secrets:generate-keys\n```\n\n### Events\n\nWhen parameters are saved in database, multiple events are dispatched\n\n* `Sherlockode\\ConfigurationBundle\\Event\\PreSaveEvent` is dispatch before saving parameters;\n* `Sherlockode\\ConfigurationBundle\\Event\\SaveEvent` is dispatch just after saving new parameters values\n  in database;\n* `Sherlockode\\ConfigurationBundle\\Event\\PostSaveEvent` is dispatch just after the SaveEvent. It can be \n  useful for customizing redirection or adding flash message for example;\n\n## Field types\n\n### Default types\n\nHere are the field types provided in the bundle, located in the namespace `Sherlockode\\ConfigurationBundle\\FieldType` :\n\n* simple\n* checkbox\n* choice\n* datetime\n* entity\n* image\n* password\n\n### Custom Field types\n\nIn order to add custom field types, you should create a service implementing the `FieldTypeInterface` interface\nand tag it with `sherlockode_configuration.field` (or use autoconfiguration).\n\nThe `getName()` return value is the alias of the field type to use in the configuration (like `simple` or `choice`).\n\n### Using transformers\n\nDue to the format of the Parameter entity in the database (the value is stored as a string, whatever the parameter type),\ncomplex values cannot be stored directly.\nFor instance, we can serialize an array to fit the string type, or we may store the ID of a database entity.\nThe process may vary depending on your needs and the value to store, but the application needs to be aware of the process\nto transform the PHP data into a string and the opposite process. This is done through transformers.\n\nA transformer is an object implementing the `Sherlockode\\ConfigurationBundle\\Transformer\\TransformerInterface`.\nThe interface has two methods `transform` and `reverseTransform`, similarly to the transformers used by Symfony in the Form Component.\n\nThe `transform` method takes the string representation and returns the PHP value,\nwhen the `reverseTransform` takes your PHP value and returns back the corresponding scalar value.\n\nIn order to be used, an instance of the transformer should be returned by the `getModelTransformer`\nmethod of the corresponding field type. If this method returns `null`, the bundle considers that no transformation is needed.\n\nThe bundle also provides a `CallbackTransformer` that can be used for faster implementations.\nFor instance handling an array can be done like this :\n\n```php\npublic function getModelTransformer(ParameterDefinition $definition): ?TransformerInterface\n{\n    return new CallbackTransformer(\n        function ($data) {\n            if (!$data) {\n                return null;\n            }\n            if (false !== ($unserialized = @unserialize($data))) {\n                return $unserialized;\n            }\n            return $data;\n        },\n        function ($data) {\n            if (is_array($data)) {\n                return serialize($data);\n            }\n            return $data;\n        }\n    );\n}\n```\n\n## License\n\nThis bundle is under the MIT license. Check the details in the [dedicated file](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsherlockode%2Fconfiguration-bundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsherlockode%2Fconfiguration-bundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsherlockode%2Fconfiguration-bundle/lists"}