Skip to content

[OptionsResolver] Documenting new setPrototype() method #15325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 10, 2021
Merged

[OptionsResolver] Documenting new setPrototype() method #15325

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions components/options_resolver.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -717,6 +717,55 @@ In same way, parent options can access to the nested options as normal arrays::
The fact that an option is defined as nested means that you must pass
an array of values to resolve it at runtime.

Prototype Options
~~~~~~~~~~~~~~~~~

There are situations where you will have to resolve and validate a set of
options that may repeat many times within another option. Let's imagine a
``connections`` option that will accept an array of database connections
with ``host``, ``database``, ``user`` and ``password`` each.

To achieve it, you can establish the nested definition of this ``connections``
option as prototype::

$resolver->setDefault('connections', function (OptionsResolver $connResolver) {
$connResolver
->setPrototype(true)
->setRequired(['host', 'database'])
->setDefaults(['user' => 'root', 'password' => null]);
});

According to the prototype definition in the example above, it is possible
to have multiple connection arrays like following::

$resolver->resolve([
'connections' => [
'default' => [
'host' => '127.0.0.1',
'database' => 'symfony',
],
'test' => [
'host' => '127.0.0.1',
'database' => 'symfony_test',
'user' => 'test',
'password' => 'test',
],
// ...
],
]);

The array keys (``default``, ``test``, etc.) of this prototype option are
validation-free and can be any valid key you want to differentiate the connections.

.. note::

A prototype option can only be defined inside a nested option and
during its resolution it will expect an array of array.

.. versionadded:: 5.3

The ``setPrototype()`` method was introduced in Symfony 5.3.

Deprecating the Option
~~~~~~~~~~~~~~~~~~~~~~

Expand Down