interface.importablefield.php

<?php

/**
 * @package interface
 */

/**
 * The `ImportableField` interface defines the functions required to implement
 * the field import API.
 *
 * @since Symphony 2.3.1
 * @link https://github.com/symphonycms/symphony-2/issues/1394
 */
interface ImportableField
{
    /**
     * Prepare a string for a field, oriented towards the human readable.
     *
     * @since Symphony 2.3.2
     * @var integer
     */
    const STRING_VALUE = 1100;

    /**
     * Select raw values from a field, usually as an associative array
     * that `processRawFieldData` would generate.
     *
     * @since Symphony 2.3.2
     * @var integer
     */
    const ARRAY_VALUE = 1101;

    /**
     * Return a list of supported import modes for use with `prepareImportValue`.
     *
     * @return array
     */
    public function getImportModes();

    /**
     * Give the field some data and ask it to return a value.
     *
     * @since Symphony 2.3.2 the method signature changed to add `$mode`
     *  as the second parameter. The default signature restores functionality
     *  present prior to Symphony 2.3.1
     *
     * @param mixed $data
     *  The data to sanitise/prepare so that it can be added to Symphony.
     * @param integer $mode
     *  The `$mode` dictates how this function should return it's value. Prior
     *  to Symphony 2.3.1, the pseudo implementation of this function returned
     *  strings, whereas in Symphony 2.3.1 the function returned arrays. `$mode`
     *  toggles between these two return types (for now)
     * @param integer $entry_id
     *  If there is an existing entry that this value is being imported into,
     *  the `$entry_id` can allow the field to do additional processing/checking
     * @return array|string
     *  Dependent on the `$mode`
     */
    public function prepareImportValue($data, $mode, $entry_id = null);
}