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\Form;

    13 

    14 /**

    15  * Transforms a value between different representations.

    16  *

    17  * @author     Bernhard Schussek <bernhard.schussek@symfony.com>

    18  */

    19 interface DataTransformerInterface

    20 {

    21     /**

    22      * Transforms a value from the original representation to a transformed representation.

    23      *

    24      * This method is called on two occasions inside a form field:

    25      *

    26      * 1. When the form field is initialized with the data attached from the datasource (object or array).

    27      * 2. When data from a request is bound using {@link Field::bind()} to transform the new input data

    28      *    back into the renderable format. For example if you have a date field and bind '2009-10-10' onto

    29      *    it you might accept this value because its easily parsed, but the transformer still writes back

    30      *    "2009/10/10" onto the form field (for further displaying or other purposes).

    31      *

    32      * This method must be able to deal with empty values. Usually this will

    33      * be NULL, but depending on your implementation other empty values are

    34      * possible as well (such as empty strings). The reasoning behind this is

    35      * that value transformers must be chainable. If the transform() method

    36      * of the first value transformer outputs NULL, the second value transformer

    37      * must be able to process that value.

    38      *

    39      * By convention, transform() should return an empty string if NULL is

    40      * passed.

    41      *

    42      * @param  mixed $value              The value in the original representation

    43      *

    44      * @return mixed                     The value in the transformed representation

    45      *

    46      * @throws UnexpectedTypeException   when the argument is not a string

    47      * @throws TransformationFailedException  when the transformation fails

    48      */

    49     function transform($value);

    50 

    51     /**

    52      * Transforms a value from the transformed representation to its original

    53      * representation.

    54      *

    55      * This method is called when {@link Field::bind()} is called to transform the requests tainted data

    56      * into an acceptable format for your data processing/model layer.

    57      *

    58      * This method must be able to deal with empty values. Usually this will

    59      * be an empty string, but depending on your implementation other empty

    60      * values are possible as well (such as empty strings). The reasoning behind

    61      * this is that value transformers must be chainable. If the

    62      * reverseTransform() method of the first value transformer outputs an

    63      * empty string, the second value transformer must be able to process that

    64      * value.

    65      *

    66      * By convention, reverseTransform() should return NULL if an empty string

    67      * is passed.

    68      *

    69      * @param  mixed $value              The value in the transformed representation

    70      *

    71      * @return mixed                     The value in the original representation

    72      *

    73      * @throws UnexpectedTypeException   when the argument is not of the expected type

    74      * @throws TransformationFailedException  when the transformation fails

    75      */

    76     function reverseTransform($value);

    77 }