vendor/symfony/options-resolver/Symfony/Component/OptionsResolver/OptionsResolverInterface.php

   1 <?php
   2
   3 /*
   4  * This file is part of the Symfony package.
   5  *
   6  * (c) Fabien Potencier <fabien@symfony.com>
   7  *
   8  * For the full copyright and license information, please view the LICENSE
   9  * file that was distributed with this source code.
  10  */
  11
  12 namespace Symfony\Component\OptionsResolver;
  13
  14 /**
  15  * @author Bernhard Schussek <bschussek@gmail.com>
  16  */
  17 interface OptionsResolverInterface
  18 {
  19     /**
  20      * Sets default option values.
  21      *
  22      * The options can either be values of any types or closures that
  23      * evaluate the option value lazily. These closures must have one
  24      * of the following signatures:
  25      *
  26      * <code>
  27      * function (Options $options)
  28      * function (Options $options, $value)
  29      * </code>
  30      *
  31      * The second parameter passed to the closure is the previously
  32      * set default value, in case you are overwriting an existing
  33      * default value.
  34      *
  35      * The closures should return the lazily created option value.
  36      *
  37      * @param array $defaultValues A list of option names as keys and default
  38      *                             values or closures as values.
  39      *
  40      * @return OptionsResolverInterface The resolver instance.
  41      */
  42     public function setDefaults(array $defaultValues);
  43
  44     /**
  45      * Replaces default option values.
  46      *
  47      * Old defaults are erased, which means that closures passed here cannot
  48      * access the previous default value. This may be useful to improve
  49      * performance if the previous default value is calculated by an expensive
  50      * closure.
  51      *
  52      * @param array $defaultValues A list of option names as keys and default
  53      *                             values or closures as values.
  54      *
  55      * @return OptionsResolverInterface The resolver instance.
  56      */
  57     public function replaceDefaults(array $defaultValues);
  58
  59     /**
  60      * Sets optional options.
  61      *
  62      * This method declares valid option names without setting default values for them.
  63      * If these options are not passed to {@link resolve()} and no default has been set
  64      * for them, they will be missing in the final options array. This can be helpful
  65      * if you want to determine whether an option has been set or not because otherwise
  66      * {@link resolve()} would trigger an exception for unknown options.
  67      *
  68      * @param array $optionNames A list of option names.
  69      *
  70      * @return OptionsResolverInterface The resolver instance.
  71      *
  72      * @throws Exception\OptionDefinitionException When trying to pass default values.
  73      */
  74     public function setOptional(array $optionNames);
  75
  76     /**
  77      * Sets required options.
  78      *
  79      * If these options are not passed to {@link resolve()} and no default has been set for
  80      * them, an exception will be thrown.
  81      *
  82      * @param array $optionNames A list of option names.
  83      *
  84      * @return OptionsResolverInterface The resolver instance.
  85      *
  86      * @throws Exception\OptionDefinitionException When trying to pass default values.
  87      */
  88     public function setRequired(array $optionNames);
  89
  90     /**
  91      * Sets allowed values for a list of options.
  92      *
  93      * @param array $allowedValues A list of option names as keys and arrays
  94      *                             with values acceptable for that option as
  95      *                             values.
  96      *
  97      * @return OptionsResolverInterface The resolver instance.
  98      *
  99      * @throws Exception\InvalidOptionsException If an option has not been defined
 100      *                                 (see {@link isKnown()}) for which
 101      *                                 an allowed value is set.
 102      */
 103     public function setAllowedValues(array $allowedValues);
 104
 105     /**
 106      * Adds allowed values for a list of options.
 107      *
 108      * The values are merged with the allowed values defined previously.
 109      *
 110      * @param array $allowedValues A list of option names as keys and arrays
 111      *                             with values acceptable for that option as
 112      *                             values.
 113      *
 114      * @return OptionsResolverInterface The resolver instance.
 115      *
 116      * @throws Exception\InvalidOptionsException If an option has not been defined
 117      *                                 (see {@link isKnown()}) for which
 118      *                                 an allowed value is set.
 119      */
 120     public function addAllowedValues(array $allowedValues);
 121
 122     /**
 123      * Sets allowed types for a list of options.
 124      *
 125      * @param array $allowedTypes A list of option names as keys and type
 126      *                            names passed as string or array as values.
 127      *
 128      * @return OptionsResolverInterface The resolver instance.
 129      *
 130      * @throws Exception\InvalidOptionsException If an option has not been defined for
 131      *                                           which an allowed type is set.
 132      */
 133     public function setAllowedTypes(array $allowedTypes);
 134
 135     /**
 136      * Adds allowed types for a list of options.
 137      *
 138      * The types are merged with the allowed types defined previously.
 139      *
 140      * @param array $allowedTypes A list of option names as keys and type
 141      *                            names passed as string or array as values.
 142      *
 143      * @return OptionsResolverInterface The resolver instance.
 144      *
 145      * @throws Exception\InvalidOptionsException If an option has not been defined for
 146      *                                           which an allowed type is set.
 147      */
 148     public function addAllowedTypes(array $allowedTypes);
 149
 150     /**
 151      * Sets normalizers that are applied on resolved options.
 152      *
 153      * The normalizers should be closures with the following signature:
 154      *
 155      * <code>
 156      * function (Options $options, $value)
 157      * </code>
 158      *
 159      * The second parameter passed to the closure is the value of
 160      * the option.
 161      *
 162      * The closure should return the normalized value.
 163      *
 164      * @param array $normalizers An array of closures.
 165      *
 166      * @return OptionsResolverInterface The resolver instance.
 167      */
 168     public function setNormalizers(array $normalizers);
 169
 170     /**
 171      * Returns whether an option is known.
 172      *
 173      * An option is known if it has been passed to either {@link setDefaults()},
 174      * {@link setRequired()} or {@link setOptional()} before.
 175      *
 176      * @param string $option The name of the option.
 177      *
 178      * @return Boolean Whether the option is known.
 179      */
 180     public function isKnown($option);
 181
 182     /**
 183      * Returns whether an option is required.
 184      *
 185      * An option is required if it has been passed to {@link setRequired()},
 186      * but not to {@link setDefaults()}. That is, the option has been declared
 187      * as required and no default value has been set.
 188      *
 189      * @param string $option The name of the option.
 190      *
 191      * @return Boolean Whether the option is required.
 192      */
 193     public function isRequired($option);
 194
 195     /**
 196      * Returns the combination of the default and the passed options.
 197      *
 198      * @param array $options The custom option values.
 199      *
 200      * @return array A list of options and their values.
 201      *
 202      * @throws Exception\InvalidOptionsException   If any of the passed options has not
 203      *                                             been defined or does not contain an
 204      *                                             allowed value.
 205      * @throws Exception\MissingOptionsException   If a required option is missing.
 206      * @throws Exception\OptionDefinitionException If a cyclic dependency is detected
 207      *                                             between two lazy options.
 208      */
 209     public function resolve(array $options = array());
 210 }