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\Form
;
14 use Symfony\Component\Form\Exception\TransformationFailedException
;
17 * Transforms a value between different representations.
19 * @author Bernhard Schussek <bschussek@gmail.com>
21 interface DataTransformerInterface
24 * Transforms a value from the original representation to a transformed representation.
26 * This method is called on two occasions inside a form field:
28 * 1. When the form field is initialized with the data attached from the datasource (object or array).
29 * 2. When data from a request is submitted using {@link Form::submit()} to transform the new input data
30 * back into the renderable format. For example if you have a date field and submit '2009-10-10'
31 * you might accept this value because its easily parsed, but the transformer still writes back
32 * "2009/10/10" onto the form field (for further displaying or other purposes).
34 * This method must be able to deal with empty values. Usually this will
35 * be NULL, but depending on your implementation other empty values are
36 * possible as well (such as empty strings). The reasoning behind this is
37 * that value transformers must be chainable. If the transform() method
38 * of the first value transformer outputs NULL, the second value transformer
39 * must be able to process that value.
41 * By convention, transform() should return an empty string if NULL is
44 * @param mixed $value The value in the original representation
46 * @return mixed The value in the transformed representation
48 * @throws TransformationFailedException When the transformation fails.
50 public function transform($value);
53 * Transforms a value from the transformed representation to its original
56 * This method is called when {@link Form::submit()} is called to transform the requests tainted data
57 * into an acceptable format for your data processing/model layer.
59 * This method must be able to deal with empty values. Usually this will
60 * be an empty string, but depending on your implementation other empty
61 * values are possible as well (such as empty strings). The reasoning behind
62 * this is that value transformers must be chainable. If the
63 * reverseTransform() method of the first value transformer outputs an
64 * empty string, the second value transformer must be able to process that
67 * By convention, reverseTransform() should return NULL if an empty string
70 * @param mixed $value The value in the transformed representation
72 * @return mixed The value in the original representation
74 * @throws TransformationFailedException When the transformation fails.
76 public function reverseTransform($value);