README

A Symfony bundle for managing application parameters stored in a database, with a built-in admin UI.

Requirements

PHP 8.4+
Symfony 7.0 or 8.0
Doctrine ORM 3.0+

Installation

composer require ardent/parameter-bundle

Configuration

Define parameters using PHP attributes on plain classes. Types are inferred from native PHP types.

use Ardent\ParameterBundle\Attribute\AsParameterGroup;
use Ardent\ParameterBundle\Attribute\AsParameter;

#[AsParameterGroup('emails', label: 'Email Settings', description: 'Configure outgoing email', priority: 10)]
class EmailParameters
{
    #[AsParameter(label: 'Default Sender', help: 'Used as the From address')]
    public string $sender = 'noreply@example.com';

    #[AsParameter(label: 'Max Retries')]
    public int $maxRetries = 3;

    #[AsParameter(label: 'Send Welcome Email')]
    public bool $welcomeEmail = true;

    #[AsParameter(label: 'Template', choices: ['default', 'minimal', 'fancy'])]
    public string $template = 'default';
}

The class must be in a directory covered by Symfony's service autoconfiguration (typically src/).

Type Mapping

PHP Type	Form Field
`string`	TextType
`int`	NumberType
`bool`	CheckboxType
`BackedEnum`	ChoiceType (auto)
`choices` array	ChoiceType

Property default values are used as fallbacks when no value exists in the database.

Group Metadata

Groups support labels, descriptions, icons, and priority ordering:

#[AsParameterGroup(
    'notifications',
    label: 'Notification Settings',
    description: 'Configure how notifications are sent',
    icon: 'fa-bell',
    priority: 5,
)]

Parameters also support label, help, and priority for display ordering within a group.

Usage

Service

Inject ParameterService to read and write parameters:

use Ardent\ParameterBundle\Service\ParameterService;

class MyService
{
    public function __construct(private ParameterService $params) {}

    public function example(): void
    {
        $sender = $this->params->get('emails_sender');
        $this->params->set('emails_maxRetries', 5);
    }
}

Parameter names follow the format {group}_{property}.

Twig

Parameters are available directly in templates:

{{ parameter('emails_sender') }}

Parameter References

Values can reference other parameters or Symfony container parameters using %name% syntax:

Hello %emails_sender%

Admin UI

Mount the bundle's routes in your routing config:

# config/routes/parameter_bundle.yaml
ardent_parameter:
    resource: '@ArdentParameterBundle/src/Controller/'
    type: attribute
    prefix: /admin/parameters

This provides:

/{prefix}/ — category listing with labels, descriptions, and icons
/{prefix}/{category} — edit parameters in a group

The bundle ships framework-agnostic HTML templates. Override them in your app at templates/bundles/ArdentParameterBundle/ to apply your CSS framework's styling.

Enum Support

BackedEnum properties are automatically detected. Choices are generated from the enum cases, the backing value is stored in the database, and get() returns the enum instance.

enum DeleteMode: string
{
    case Keep = 'keep';
    case Delayed = 'delayed';
    case Immediate = 'immediate';
}

#[AsParameter]
public DeleteMode $deleteMode = DeleteMode::Keep;

$mode = $params->get('group_deleteMode'); // returns DeleteMode::Keep

No choices array needed — they are derived from the enum cases.

Dynamic Choice Providers

For choices that need to be resolved at runtime, implement ChoiceProviderInterface:

use Ardent\ParameterBundle\Contract\ChoiceProviderInterface;

class UserEmailProvider implements ChoiceProviderInterface
{
    public function __construct(private UserRepository $users) {}

    public function getChoices(): array
    {
        $choices = [];
        foreach ($this->users->findAll() as $user) {
            $choices[$user->getName()] = $user->getEmail();
        }
        return $choices;
    }
}

Then reference it in the attribute:

#[AsParameter(choiceProvider: UserEmailProvider::class)]
public string $defaultSender = '';

Custom Parameter Types

For form types beyond the built-in ones, implement ParameterTypeInterface:

use Ardent\ParameterBundle\Contract\ParameterTypeInterface;
use Symfony\Component\Form\Extension\Core\Type\ColorType;

class ColorParameterType implements ParameterTypeInterface
{
    public static function getName(): string
    {
        return 'color';
    }

    public function getFormType(): string
    {
        return ColorType::class;
    }

    public function getFormOptions(): array
    {
        return [];
    }

    public function parseValue(string $raw): mixed
    {
        return $raw;
    }
}

#[AsParameter(type: ColorParameterType::class)]
public string $brandColor = '#ff0000';

Validation

Add Symfony validation constraints to parameters:

use Symfony\Component\Validator\Constraints as Assert;

#[AsParameter(
    label: 'Admin Email',
    constraints: [new Assert\NotBlank(), new Assert\Email()],
)]
public string $adminEmail = '';

Events

The bundle dispatches events when parameters change:

ParameterPreUpdateEvent — dispatched before saving. Modify $event->value to transform, or call $event->stopPropagation() to veto.
ParameterPostUpdateEvent — dispatched after saving. Use for side effects (cache clearing, notifications).

use Ardent\ParameterBundle\Event\ParameterPostUpdateEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener]
class ParameterChangeListener
{
    public function __invoke(ParameterPostUpdateEvent $event): void
    {
        // React to parameter change
    }
}

Caching

Parameters are cached using Symfony's CacheInterface. Cache is automatically invalidated when a parameter is updated via set(). Only parsed values (get($name, true)) are cached — raw values used for form population are always fetched fresh.

Migrating from YAML Config

If you're upgrading from the YAML-based configuration, run:

php bin/console parameter:migrate-config

This generates PHP attribute classes from your existing YAML config. Options:

php bin/console parameter:migrate-config 'App\Parameter' src/Parameter

First argument: namespace (default: App\Parameter)
Second argument: output directory (default: src/Parameter)

After verifying the generated classes, remove the ardent_parameter.parameters section from your YAML config.

License

GPL-3.0-only

ardent / parameter-bundle

Maintainers

Package info

Statistics

Security