Skip to content

[WCM] Added documentation for the new OptionsResolver flags #3731

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

Closed
wants to merge 1 commit into from
Closed

[WCM] Added documentation for the new OptionsResolver flags #3731

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
112 changes: 97 additions & 15 deletions components/options_resolver.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,9 @@ knows which options should be resolved.

To check if an option exists, you can use the
:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::isKnown`
function.
function. You can also `suppress the exception`_ by passing one of the
flags ``IGNORE_UNKNOWN`` or ``REMOVE_UNKNOWN`` to
:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::resolve`.

A best practice is to put the configuration in a method (e.g.
``configureOptions``). You call this method in the constructor to configure
Expand Down Expand Up @@ -162,7 +164,9 @@ will be thrown.

To determine if an option is required, you can use the
:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::isRequired`
method.
method. You can also `suppress the exception`_ by passing the flag
``IGNORE_MISSING`` to
:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::resolve`.

Optional Options
~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -304,11 +308,11 @@ again. When using a closure as the new value it is passed 2 arguments:

Existing option keys that you do not mention when overwriting are preserved.

Configure allowed Values
~~~~~~~~~~~~~~~~~~~~~~~~
Setting Allowed Values
~~~~~~~~~~~~~~~~~~~~~~

Not all values are valid values for options. Suppose the ``Mailer`` class has
a ``transport`` option, it can only be one of ``sendmail``, ``mail`` or
a ``transport`` option, which can only be one of ``sendmail``, ``mail`` or
``smtp``. You can configure these allowed values by calling
:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setAllowedValues`::

Expand All @@ -324,8 +328,8 @@ a ``transport`` option, it can only be one of ``sendmail``, ``mail`` or

There is also an
:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::addAllowedValues`
method, which you can use if you want to add an allowed value to the previously
configured allowed values.
method. Use that method if you want to add another allowed value to the ones
you configured previously.

.. versionadded:: 2.5
The callback support for allowed values was introduced in Symfony 2.5.
Expand All @@ -349,11 +353,12 @@ as an allowed value::

Note that using this together with ``addAllowedValues`` will not work.

Configure Allowed Types
~~~~~~~~~~~~~~~~~~~~~~~
Setting Allowed Types
~~~~~~~~~~~~~~~~~~~~~

You can also specify allowed types. For instance, the ``port`` option can
be anything, but it must be an integer. You can configure these types by calling
You can also specify allowed types. For instance, the ``port`` option can carry
any value, as llong as it is an integer. You can configure the allowed type by
calling
:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setAllowedTypes`::

// ...
Expand All @@ -370,12 +375,12 @@ Possible types are the ones associated with the ``is_*`` PHP functions or a
class name. You can also pass an array of types as the value. For instance,
``array('null', 'string')`` allows ``port`` to be ``null`` or a ``string``.

There is also an
Like for the allowed values, there is also an
:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::addAllowedTypes`
method, which you can use to add an allowed type to the previous allowed types.
method, which adds an allowed type to the previously configured ones.

Normalize the Options
~~~~~~~~~~~~~~~~~~~~~
Option Normalization
~~~~~~~~~~~~~~~~~~~~

Some values need to be normalized before you can use them. For instance,
pretend that the ``host`` should always start with ``http://``. To do that,
Expand Down Expand Up @@ -423,4 +428,81 @@ need to use the other options for normalizing::
));
}

.. _suppress the exception:

Dealing With Errors
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dealing with Errors (with is a closed class word)

~~~~~~~~~~~~~~~~~~~

By default, if you pass a non-existing option to
:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::resolve`, an
:class:`Symfony\\Component\\OptionsResolver\\Exception\\InvalidOptionsException`
will be thrown. In some cases, that's not what you want. You can change this
behavior by passing one of the following flags:

* ``FORBID_UNKNOWN`` (the default)
* ``IGNORE_UNKNOWN``
* ``REMOVE_UNKNOWN``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't we use OptionsResolverInterface::REMOVE_UNKNOWN here rather than REMOVE_UNKNOWN, to make it clear that these are constants on the interface ?


For example, if you pass ``REMOVE_UNKNOWN``, non-existing options will be
removed from the resolved options array instead of throwing an exception::

$resolver->setDefaults(array(
'transport' => 'http',
));

$options = $resolver->resolve(array(
'transport' => 'https',
'encryption' => 'tls',
), OptionsResolverInterface::REMOVE_UNKNOWN);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There should be a use statement for this at the top of the block, followed by // ...


print_r($options);
// => Array(
// [transport] => https
// )

If you pass ``IGNORE_UNKNOWN`` instead, the unknown option will be left in the
final options array unchanged::

$options = $resolver->resolve(array(
'transport' => 'https',
'encryption' => 'tls',
), OptionsResolverInterface::IGNORE_UNKNOWN);

print_r($options);
// => Array(
// [transport] => https
// [encryption] => tls
// )

Likewise, you can configure how to deal with missing required options. By
default, a
:class:`Symfony\\Component\\OptionsResolver\\Exception\\MissingOptionsException`
is thrown. The following flag values are available:

* ``FORBID_MISSING`` (the default)
* ``IGNORE_MISSING``

If you pass ``IGNORE_MISSING``, missing required options will silently be
ignored::

$resolver->setRequired(array(
'transport',
'port',
));

$options = $resolver->resolve(array(
'port' => 587,
), OptionsResolverInterface::IGNORE_MISSING);

print_r($options);
// => Array(
// [port] => 587
// )

You can combine multiple flags using the bitwise OR ("|") operator::
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

quotes should be backticks


$options = $resolver->resolve(array(
'port' => 587,
), OptionsResolverInterface::REMOVE_UNKNOWN | OptionsResolverInterface::IGNORE_MISSING);

.. _Packagist: https://packagist.org/packages/symfony/options-resolver