4 * This file is part of the Symfony package.
6 * (c) Fabien Potencier <fabien@symfony.com>
8 * For the full copyright and license information, please view the LICENSE
9 * file that was distributed with this source code.
12 namespace Symfony\Component\OptionsResolver
;
14 use Symfony\Component\OptionsResolver\Exception\OptionDefinitionException
;
17 * Container for resolving inter-dependent options.
19 * @author Bernhard Schussek <bschussek@gmail.com>
21 class Options
implements \ArrayAccess
, \Iterator
, \Countable
24 * A list of option values.
27 private $options = array();
30 * A list of normalizer closures.
33 private $normalizers = array();
36 * A list of closures for evaluating lazy options.
39 private $lazy = array();
42 * A list containing the currently locked options.
45 private $lock = array();
48 * Whether at least one option has already been read.
50 * Once read, the options cannot be changed anymore. This is
51 * necessary in order to avoid inconsistencies during the resolving
52 * process. If any option is changed after being read, all evaluated
53 * lazy options that depend on this option would become invalid.
57 private $reading = false;
60 * Sets the value of a given option.
62 * You can set lazy options by passing a closure with the following
66 * function (Options $options)
69 * This closure will be evaluated once the option is read using
70 * {@link get()}. The closure has access to the resolved values of
71 * other options through the passed {@link Options} instance.
73 * @param string $option The name of the option.
74 * @param mixed $value The value of the option.
76 * @throws OptionDefinitionException If options have already been read.
77 * Once options are read, the container
80 public function set($option, $value)
82 // Setting is not possible once an option is read, because then lazy
83 // options could manipulate the state of the object, leading to
84 // inconsistent results.
86 throw new OptionDefinitionException('Options cannot be set anymore once options have been read.');
89 // Setting is equivalent to overloading while discarding the previous
91 unset($this->options
[$option]);
92 unset($this->lazy
[$option]);
94 $this->overload($option, $value);
98 * Sets the normalizer for a given option.
100 * Normalizers should be closures with the following signature:
103 * function (Options $options, $value)
106 * This closure will be evaluated once the option is read using
107 * {@link get()}. The closure has access to the resolved values of
108 * other options through the passed {@link Options} instance.
110 * @param string $option The name of the option.
111 * @param \Closure $normalizer The normalizer.
113 * @throws OptionDefinitionException If options have already been read.
114 * Once options are read, the container
117 public function setNormalizer($option, \Closure
$normalizer)
119 if ($this->reading
) {
120 throw new OptionDefinitionException('Normalizers cannot be added anymore once options have been read.');
123 $this->normalizers
[$option] = $normalizer;
127 * Replaces the contents of the container with the given options.
129 * This method is a shortcut for {@link clear()} with subsequent
130 * calls to {@link set()}.
132 * @param array $options The options to set.
134 * @throws OptionDefinitionException If options have already been read.
135 * Once options are read, the container
138 public function replace(array $options)
140 if ($this->reading
) {
141 throw new OptionDefinitionException('Options cannot be replaced anymore once options have been read.');
144 $this->options
= array();
145 $this->lazy
= array();
146 $this->normalizers
= array();
148 foreach ($options as $option => $value) {
149 $this->overload($option, $value);
154 * Overloads the value of a given option.
156 * Contrary to {@link set()}, this method keeps the previous default
157 * value of the option so that you can access it if you pass a closure.
158 * Passed closures should have the following signature:
161 * function (Options $options, $value)
164 * The second parameter passed to the closure is the current default
165 * value of the option.
167 * @param string $option The option name.
168 * @param mixed $value The option value.
170 * @throws OptionDefinitionException If options have already been read.
171 * Once options are read, the container
174 public function overload($option, $value)
176 if ($this->reading
) {
177 throw new OptionDefinitionException('Options cannot be overloaded anymore once options have been read.');
180 // If an option is a closure that should be evaluated lazily, store it
181 // in the "lazy" property.
182 if ($value instanceof \Closure
) {
183 $reflClosure = new \
ReflectionFunction($value);
184 $params = $reflClosure->getParameters();
186 if (isset($params[0]) && null !== ($class = $params[0]->getClass()) && __CLASS__
=== $class->name
) {
187 // Initialize the option if no previous value exists
188 if (!isset($this->options
[$option])) {
189 $this->options
[$option] = null;
192 // Ignore previous lazy options if the closure has no second parameter
193 if (!isset($this->lazy
[$option]) || !isset($params[1])) {
194 $this->lazy
[$option] = array();
197 // Store closure for later evaluation
198 $this->lazy
[$option][] = $value;
204 // Remove lazy options by default
205 unset($this->lazy
[$option]);
207 $this->options
[$option] = $value;
211 * Returns the value of the given option.
213 * If the option was a lazy option, it is evaluated now.
215 * @param string $option The option name.
217 * @return mixed The option value.
219 * @throws \OutOfBoundsException If the option does not exist.
220 * @throws OptionDefinitionException If a cyclic dependency is detected
221 * between two lazy options.
223 public function get($option)
225 $this->reading
= true;
227 if (!array_key_exists($option, $this->options
)) {
228 throw new \
OutOfBoundsException(sprintf('The option "%s" does not exist.', $option));
231 if (isset($this->lazy
[$option])) {
232 $this->resolve($option);
235 if (isset($this->normalizers
[$option])) {
236 $this->normalize($option);
239 return $this->options
[$option];
243 * Returns whether the given option exists.
245 * @param string $option The option name.
247 * @return Boolean Whether the option exists.
249 public function has($option)
251 return array_key_exists($option, $this->options
);
255 * Removes the option with the given name.
257 * @param string $option The option name.
259 * @throws OptionDefinitionException If options have already been read.
260 * Once options are read, the container
263 public function remove($option)
265 if ($this->reading
) {
266 throw new OptionDefinitionException('Options cannot be removed anymore once options have been read.');
269 unset($this->options
[$option]);
270 unset($this->lazy
[$option]);
271 unset($this->normalizers
[$option]);
275 * Removes all options.
277 * @throws OptionDefinitionException If options have already been read.
278 * Once options are read, the container
281 public function clear()
283 if ($this->reading
) {
284 throw new OptionDefinitionException('Options cannot be cleared anymore once options have been read.');
287 $this->options
= array();
288 $this->lazy
= array();
289 $this->normalizers
= array();
293 * Returns the values of all options.
295 * Lazy options are evaluated at this point.
297 * @return array The option values.
299 public function all()
301 $this->reading
= true;
303 // Performance-wise this is slightly better than
304 // while (null !== $option = key($this->lazy))
305 foreach ($this->lazy
as $option => $closures) {
306 // Double check, in case the option has already been resolved
307 // by cascade in the previous cycles
308 if (isset($this->lazy
[$option])) {
309 $this->resolve($option);
313 foreach ($this->normalizers
as $option => $normalizer) {
314 if (isset($this->normalizers
[$option])) {
315 $this->normalize($option);
319 return $this->options
;
323 * Equivalent to {@link has()}.
325 * @param string $option The option name.
327 * @return Boolean Whether the option exists.
329 * @see \ArrayAccess::offsetExists()
331 public function offsetExists($option)
333 return $this->has($option);
337 * Equivalent to {@link get()}.
339 * @param string $option The option name.
341 * @return mixed The option value.
343 * @throws \OutOfBoundsException If the option does not exist.
344 * @throws OptionDefinitionException If a cyclic dependency is detected
345 * between two lazy options.
347 * @see \ArrayAccess::offsetGet()
349 public function offsetGet($option)
351 return $this->get($option);
355 * Equivalent to {@link set()}.
357 * @param string $option The name of the option.
358 * @param mixed $value The value of the option. May be a closure with a
359 * signature as defined in DefaultOptions::add().
361 * @throws OptionDefinitionException If options have already been read.
362 * Once options are read, the container
365 * @see \ArrayAccess::offsetSet()
367 public function offsetSet($option, $value)
369 $this->set($option, $value);
373 * Equivalent to {@link remove()}.
375 * @param string $option The option name.
377 * @throws OptionDefinitionException If options have already been read.
378 * Once options are read, the container
381 * @see \ArrayAccess::offsetUnset()
383 public function offsetUnset($option)
385 $this->remove($option);
391 public function current()
393 return $this->get($this->key());
399 public function next()
401 next($this->options
);
407 public function key()
409 return key($this->options
);
415 public function valid()
417 return null !== $this->key();
423 public function rewind()
425 reset($this->options
);
431 public function count()
433 return count($this->options
);
437 * Evaluates the given lazy option.
439 * The evaluated value is written into the options array. The closure for
440 * evaluating the option is discarded afterwards.
442 * @param string $option The option to evaluate.
444 * @throws OptionDefinitionException If the option has a cyclic dependency
447 private function resolve($option)
449 // The code duplication with normalize() exists for performance
450 // reasons, in order to save a method call.
451 // Remember that this method is potentially called a couple of thousand
452 // times and needs to be as efficient as possible.
453 if (isset($this->lock
[$option])) {
454 $conflicts = array();
456 foreach ($this->lock
as $option => $locked) {
458 $conflicts[] = $option;
462 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', implode('", "', $conflicts)));
465 $this->lock
[$option] = true;
466 foreach ($this->lazy
[$option] as $closure) {
467 $this->options
[$option] = $closure($this, $this->options
[$option]);
469 unset($this->lock
[$option]);
471 // The option now isn't lazy anymore
472 unset($this->lazy
[$option]);
476 * Normalizes the given option.
478 * The evaluated value is written into the options array.
480 * @param string $option The option to normalizer.
482 * @throws OptionDefinitionException If the option has a cyclic dependency
485 private function normalize($option)
487 // The code duplication with resolve() exists for performance
488 // reasons, in order to save a method call.
489 // Remember that this method is potentially called a couple of thousand
490 // times and needs to be as efficient as possible.
491 if (isset($this->lock
[$option])) {
492 $conflicts = array();
494 foreach ($this->lock
as $option => $locked) {
496 $conflicts[] = $option;
500 throw new OptionDefinitionException(sprintf('The options "%s" have a cyclic dependency.', implode('", "', $conflicts)));
503 /** @var \Closure $normalizer */
504 $normalizer = $this->normalizers
[$option];
506 $this->lock
[$option] = true;
507 $this->options
[$option] = $normalizer($this, array_key_exists($option, $this->options
) ? $this->options
[$option] : null);
508 unset($this->lock
[$option]);
510 // The option is now normalized
511 unset($this->normalizers
[$option]);