README

key-value-form-bundle

Symfony form type to manage associative array data.

Installation

composer require alexandrefernandez/key-value-form-bundle

Verify that the bundle is enabled in config/bundles.php :

return [
	// ...
    AlexandreFernandez\KeyValueFormBundle\KeyValueFormBundle::class => ['all' => true],
];

KeyValueType Field

This field type is used to render an associative array (key-value pairs) as a form. It allows you to manage a collection of key-value pairs where each key is a string and each value can be of any type (specified via options). This is useful when you need to allow users to dynamically add and edit key-value pairs within your application.

When rendered, existing key-value pairs are displayed with individual input fields for the key and the value. The keys are used to index the pairs within the submitted data.

The full list of options defined and inherited by this form type is available running this command in your app:

php bin/console debug:form KeyValueType

Basic usage

Suppose you are building a simple phone book application. You have a phoneNumbers field that corresponds to an associative array where the full name of a person is the key and their phone number is the value. In the form, you want to expose each name and phone number as a pair of input text boxes:

$builder->add('phoneNumbers', KeyValueType::class, [
    'label' => 'Phone Numbers',
    'key_options' => [ // options passed to each "key" field
        'attr' => ['class' => 'full-name'],
        'help' => 'Enter the full contact name.',
    ],
    'value_type' => TextType::class, // form type for the "value" part of each key-value pair
    'value_options' => [ // options passed to each "value" field
        'attr' => ['class' => 'phone-number'],
        'help' => 'Enter the phone number.',
    ],
]);

Field options

allow_add

type: boolean default: false

If set to true, new key-value pairs can be added dynamically to the form. This requires the prototype option to be enabled so a template can be used to add new pairs using JavaScript.

allow_delete

type: boolean default: false

If set to true, existing key-value pairs can be removed from the form. This is usually implemented with a "delete" button next to each key-value pair that removes the corresponding form element from the DOM.

container_options

type: array default: []

An array of options that are passed to the underlying FormType instance that wraps each key-value pair. This allows you to customize the container for each pair.

container_prototype_options

type: array default: []

Similar to container_options, but applies only to the prototype form used for adding new key-value pairs when allow_add is true. This allows you to define specific options for the prototype form.

delete_empty

type: boolean default: false

If set to true, key-value pairs where the key or the value field is empty will be automatically removed when the form is submitted.

Alternatively, you can provide a callable (a PHP function or closure) to define custom logic for determining if a key-value pair should be considered empty. The callable will receive the value and the key as arguments, and should return true if the pair should be deleted.

$builder->add('settings', KeyValueType::class, [
    'delete_empty' => function (mixed $value = null, ?string $key = null): bool {
        return empty($key) || (empty($value) && $key !== 'some_required_key');
    },
]);

key_options

type: array default: []

An array of options that are passed to the TextType instance used for rendering the "key" field in each key-value pair. This allows you to customize the key input.

key_prototype_options

type: array default: []

Similar to key_options, but applies only to the prototype key field used for adding new key-value pairs when allow_add is true.

prototype

type: boolean default: true

If set to true, a prototype is generated for adding new key-value pairs when the allow_add option is also set to true. The prototype is a hidden form that you can use with JavaScript to dynamically create new key-value pair fields. The prototype variable is accessible in your Twig template: form.your_field_name.vars.prototype.

prototype_name

type: string default: __name__

The name used as a placeholder in the prototype for the key-value pair fields. This placeholder will be replaced with a unique identifier when adding a new key-value pair using JavaScript.

value_type

type: string default: Symfony\Component\Form\Extension\Core\Type\TextType

The fully-qualified class name of the form type used for the "value" field in each key-value pair. This can be any valid Symfony form type, such as TextType, EmailType, ChoiceType, or even a custom form type.

value_options

type: array default: []

An array of options that are passed to the form type specified in the value_type option. This lets you configure options specific to the value field.

value_prototype_options

type: array default: []

Similar to value_options, but applies only to the prototype value field used for adding new key-value pairs when allow_add is true.

uksort

type: null or callabe default: null

If provided the callable will be used as a comparison function to sort the key-value pairs order using the uksort function.