Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sherlockode/configuration-bundle
Symfony bundle for configuration purposes. Let users define application parameters in your backoffice.
https://github.com/sherlockode/configuration-bundle
configuration php symfony symfony-bundle
Last synced: about 1 month ago
JSON representation
Symfony bundle for configuration purposes. Let users define application parameters in your backoffice.
- Host: GitHub
- URL: https://github.com/sherlockode/configuration-bundle
- Owner: sherlockode
- License: mit
- Created: 2018-10-19T08:46:05.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-12-18T20:29:59.000Z (about 1 year ago)
- Last Synced: 2023-12-19T15:02:20.263Z (about 1 year ago)
- Topics: configuration, php, symfony, symfony-bundle
- Language: PHP
- Homepage:
- Size: 142 KB
- Stars: 21
- Watchers: 6
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Sherlockode ConfigurationBundle
===============================
This bundle is built to allow users to define configuration options, useful in admin panels.
Get rid of the business logic variables in your `ENV` or `parameters.yml` file !
Available features:
* Define multiple configuration entries available for the users
* Retrieve configuration values anywhere in your code for business logic
* Use or create custom parameter types for a better user experience
[](https://circleci.com/gh/sherlockode/configuration-bundle)
[](https://packagist.org/packages/sherlockode/configuration-bundle)
[](https://packagist.org/packages/sherlockode/configuration-bundle)
## Installation
The best way to install this bundle is to rely on [Composer](https://getcomposer.org/):
```bash
$ composer require sherlockode/configuration-bundle
```
## Setup
Enable the bundle in the kernel
```php
['all' => true],
];
```
You will need a `Parameter` entity in order to store the configuration values in the database.
```php
getAll();
// or using an associative array:
// $data = ['contact_email' => '[email protected]', 'max_user_login_attempts' => 5];
$form = $this->createForm(ParametersType::class, $data);
// handle form submission
$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
$params = $form->getData();
foreach ($params as $path => $value) {
$parameterManager->set($path, $value);
}
$parameterManager->save();
}
//...
```
### Access configuration values
You are now able to retrieve any configuration value by using the `get` method from the parameter manager.
It is possible to provide a default value to return if the entry has not been set yet.
```php
$email = $parameterManager->get('contact_email');
$maxAttempts = $parameterManager->get('max_user_login_attempts', 5);
```
### Import / export from the browser
You can export or import parameters in a yaml file. You have two routes for these operations:
* `sherlockode_configuration.export`
* `sherlockode_configuration.import`
You also can customize the import form template by defining your own in the configuration:
```yaml
# config/packages/sherlockode_configuration.yaml
sherlockode_configuration:
templates:
import_form: 'Parameter/my_import_form.html.twig'
```
### Import / export from CLI
You can export or import your parameters with these two Symfony commands:
* `sherlockode:configuration:export`
* `sherlockode:configuration:import`
These commands rely on the [Symfony secrets mechanism](https://symfony.com/doc/current/configuration/secrets.html).
So be sure to generate your credentials with the following command:
```shell
$ php bin/console secrets:generate-keys
```
### Events
When parameters are saved in database, multiple events are dispatched
* `Sherlockode\ConfigurationBundle\Event\PreSaveEvent` is dispatch before saving parameters;
* `Sherlockode\ConfigurationBundle\Event\SaveEvent` is dispatch just after saving new parameters values
in database;
* `Sherlockode\ConfigurationBundle\Event\PostSaveEvent` is dispatch just after the SaveEvent. It can be
useful for customizing redirection or adding flash message for example;
## Field types
### Default types
Here are the field types provided in the bundle, located in the namespace `Sherlockode\ConfigurationBundle\FieldType` :
* simple
* checkbox
* choice
* datetime
* entity
* image
* password
### Custom Field types
In order to add custom field types, you should create a service implementing the `FieldTypeInterface` interface
and tag it with `sherlockode_configuration.field` (or use autoconfiguration).
The `getName()` return value is the alias of the field type to use in the configuration (like `simple` or `choice`).
### Using transformers
Due to the format of the Parameter entity in the database (the value is stored as a string, whatever the parameter type),
complex values cannot be stored directly.
For instance, we can serialize an array to fit the string type, or we may store the ID of a database entity.
The process may vary depending on your needs and the value to store, but the application needs to be aware of the process
to transform the PHP data into a string and the opposite process. This is done through transformers.
A transformer is an object implementing the `Sherlockode\ConfigurationBundle\Transformer\TransformerInterface`.
The interface has two methods `transform` and `reverseTransform`, similarly to the transformers used by Symfony in the Form Component.
The `transform` method takes the string representation and returns the PHP value,
when the `reverseTransform` takes your PHP value and returns back the corresponding scalar value.
In order to be used, an instance of the transformer should be returned by the `getModelTransformer`
method of the corresponding field type. If this method returns `null`, the bundle considers that no transformation is needed.
The bundle also provides a `CallbackTransformer` that can be used for faster implementations.
For instance handling an array can be done like this :
```php
public function getModelTransformer(ParameterDefinition $definition): ?TransformerInterface
{
return new CallbackTransformer(
function ($data) {
if (!$data) {
return null;
}
if (false !== ($unserialized = @unserialize($data))) {
return $unserialized;
}
return $data;
},
function ($data) {
if (is_array($data)) {
return serialize($data);
}
return $data;
}
);
}
```
## License
This bundle is under the MIT license. Check the details in the [dedicated file](LICENSE)