[github/wallabag/wallabag.git] / vendor / symfony / options-resolver / Symfony / Component / OptionsResolver / OptionsResolverInterface.php

<?php

/*
 * This file is part of the Symfony package.
 *
 * (c) Fabien Potencier <fabien@symfony.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace Symfony\Component\OptionsResolver;

/**
 * @author Bernhard Schussek <bschussek@gmail.com>
 */
interface OptionsResolverInterface
{
    /**
     * Sets default option values.
     *
     * The options can either be values of any types or closures that
     * evaluate the option value lazily. These closures must have one
     * of the following signatures:
     *
     * <code>
     * function (Options $options)
     * function (Options $options, $value)
     * </code>
     *
     * The second parameter passed to the closure is the previously
     * set default value, in case you are overwriting an existing
     * default value.
     *
     * The closures should return the lazily created option value.
     *
     * @param array $defaultValues A list of option names as keys and default
     *                             values or closures as values.
     *
     * @return OptionsResolverInterface The resolver instance.
     */
    public function setDefaults(array $defaultValues);

    /**
     * Replaces default option values.
     *
     * Old defaults are erased, which means that closures passed here cannot
     * access the previous default value. This may be useful to improve
     * performance if the previous default value is calculated by an expensive
     * closure.
     *
     * @param array $defaultValues A list of option names as keys and default
     *                             values or closures as values.
     *
     * @return OptionsResolverInterface The resolver instance.
     */
    public function replaceDefaults(array $defaultValues);

    /**
     * Sets optional options.
     *
     * This method declares valid option names without setting default values for them.
     * If these options are not passed to {@link resolve()} and no default has been set
     * for them, they will be missing in the final options array. This can be helpful
     * if you want to determine whether an option has been set or not because otherwise
     * {@link resolve()} would trigger an exception for unknown options.
     *
     * @param array $optionNames A list of option names.
     *
     * @return OptionsResolverInterface The resolver instance.
     *
     * @throws Exception\OptionDefinitionException When trying to pass default values.
     */
    public function setOptional(array $optionNames);

    /**
     * Sets required options.
     *
     * If these options are not passed to {@link resolve()} and no default has been set for
     * them, an exception will be thrown.
     *
     * @param array $optionNames A list of option names.
     *
     * @return OptionsResolverInterface The resolver instance.
     *
     * @throws Exception\OptionDefinitionException When trying to pass default values.
     */
    public function setRequired(array $optionNames);

    /**
     * Sets allowed values for a list of options.
     *
     * @param array $allowedValues A list of option names as keys and arrays
     *                             with values acceptable for that option as
     *                             values.
     *
     * @return OptionsResolverInterface The resolver instance.
     *
     * @throws Exception\InvalidOptionsException If an option has not been defined
     *                                 (see {@link isKnown()}) for which
     *                                 an allowed value is set.
     */
    public function setAllowedValues(array $allowedValues);

    /**
     * Adds allowed values for a list of options.
     *
     * The values are merged with the allowed values defined previously.
     *
     * @param array $allowedValues A list of option names as keys and arrays
     *                             with values acceptable for that option as
     *                             values.
     *
     * @return OptionsResolverInterface The resolver instance.
     *
     * @throws Exception\InvalidOptionsException If an option has not been defined
     *                                 (see {@link isKnown()}) for which
     *                                 an allowed value is set.
     */
    public function addAllowedValues(array $allowedValues);

    /**
     * Sets allowed types for a list of options.
     *
     * @param array $allowedTypes A list of option names as keys and type
     *                            names passed as string or array as values.
     *
     * @return OptionsResolverInterface The resolver instance.
     *
     * @throws Exception\InvalidOptionsException If an option has not been defined for
     *                                           which an allowed type is set.
     */
    public function setAllowedTypes(array $allowedTypes);

    /**
     * Adds allowed types for a list of options.
     *
     * The types are merged with the allowed types defined previously.
     *
     * @param array $allowedTypes A list of option names as keys and type
     *                            names passed as string or array as values.
     *
     * @return OptionsResolverInterface The resolver instance.
     *
     * @throws Exception\InvalidOptionsException If an option has not been defined for
     *                                           which an allowed type is set.
     */
    public function addAllowedTypes(array $allowedTypes);

    /**
     * Sets normalizers that are applied on resolved options.
     *
     * The normalizers should be closures with the following signature:
     *
     * <code>
     * function (Options $options, $value)
     * </code>
     *
     * The second parameter passed to the closure is the value of
     * the option.
     *
     * The closure should return the normalized value.
     *
     * @param array $normalizers An array of closures.
     *
     * @return OptionsResolverInterface The resolver instance.
     */
    public function setNormalizers(array $normalizers);

    /**
     * Returns whether an option is known.
     *
     * An option is known if it has been passed to either {@link setDefaults()},
     * {@link setRequired()} or {@link setOptional()} before.
     *
     * @param string $option The name of the option.
     *
     * @return Boolean Whether the option is known.
     */
    public function isKnown($option);

    /**
     * Returns whether an option is required.
     *
     * An option is required if it has been passed to {@link setRequired()},
     * but not to {@link setDefaults()}. That is, the option has been declared
     * as required and no default value has been set.
     *
     * @param string $option The name of the option.
     *
     * @return Boolean Whether the option is required.
     */
    public function isRequired($option);

    /**
     * Returns the combination of the default and the passed options.
     *
     * @param array $options The custom option values.
     *
     * @return array A list of options and their values.
     *
     * @throws Exception\InvalidOptionsException   If any of the passed options has not
     *                                             been defined or does not contain an
     *                                             allowed value.
     * @throws Exception\MissingOptionsException   If a required option is missing.
     * @throws Exception\OptionDefinitionException If a cyclic dependency is detected
     *                                             between two lazy options.
     */
    public function resolve(array $options = array());
}
Commit	Line	Data
4f5b44bd NL	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	}