Field::setArray() - Code Metrics - Inspection of "Docs review" - symphonycms/symphony-2 - Measure and Improve Code Quality continuously with Scrutinizer

Passed
Pull Request — master (#2835)

unknown
created 2018-05-09 20:36 UTC
Field::setArray() A

↳ Parent: Field
Complexity

Conditions	3
Paths	3
Size

Total Lines	8
Code Lines	4
Duplication

Lines	0
Ratio	0 %
Importance

Changes
Metric	Value
cc	3
eloc	4
c	0
b	0
f	0
nc	3
nop	1
dl	0
loc	8
rs	9.4285
<?php
/**
 * @package toolkit
 */
/**
 * The Field class represents a Symphony Field object. Fields are the building
 * blocks for Sections. All fields instances are unique and can only be used once
 * in a Symphony install. Fields have their own field table which records where
 * instances of this field type have been used in other sections and their settings.
 * They also spinoff other `tbl_entry_data_{id}` tables that actually store data for
 * entries particular to this field.
 *
 * @since Symphony 3.0.0 it implements the ArrayAccess interface.
 */
class Field implements ArrayAccess
{
    /**
     * The desired result when creating a field in the section editor
     * @var integer
     */
    const __OK__ = 100;

    /**
     * If an error occurring when saving a section because of this field,
     * this will be returned
     * @var integer
     */
    const __ERROR__ = 150;

    /**
     * When saving a section, if a value that is required is missing,
     * this will be returned
     * @var integer
     */
    const __MISSING_FIELDS__ = 200;

    /**
     * If a value for a setting is invalid, this will be returned
     * @var integer
     */
    const __INVALID_FIELDS__ = 220;

    /**
     * If there already is an instance of this field in this section and
     * `mustBeUnique()` returns true, this will be returned
     * @var integer
     * @see mustBeUnique()
     */
    const __DUPLICATE__ = 300;

    /**
     * Fields can returned this is an error occurred when saving the
     * field's settings that doesn't fit another `Field` constant
     * @var integer
     */
    const __ERROR_CUSTOM__ = 400;

    /**
     * If the field name is not a valid QName, this error will be returned
     * @var integer
     */
    const __INVALID_QNAME__ = 500;

    /**
     * Used by the `FieldManager` to return fields that can be toggled
     * @var integer
     */
    const __TOGGLEABLE_ONLY__ = 600;

    /**
     * Used by the `FieldManager` to return fields that can't be toggled
     * @var integer
     */
    const __UNTOGGLEABLE_ONLY__ = 700;

    /**
     * Used by the `FieldManager` to return fields that can be filtered
     * @var integer
     */
    const __FILTERABLE_ONLY__ = 800;

    /**
     * Used by the `FieldManager` to return fields that can't be filtered
     * @var integer
     */
    const __UNFILTERABLE_ONLY__ = 900;

    /**
     * Used by the `FieldManager` to just return all fields
     * @var integer
     */
    const __FIELD_ALL__ = 1000;

    /**
     * Used to manage the joins when this field used in a datasource
     * @deprecated @since Symphony 3.0.0
     * @var integer
     */
    protected $_key = 0;

    /**
     * An associative array of the settings for this `Field` instance
     * @var array
     */
    protected $_settings = array();

    /**
     * Whether this field is required inherently, defaults to false.
     * @var boolean
     */
    protected $_required = false;

    /**
     * Whether this field can be viewed on the entries table. Note
     * that this is not the same variable as the one set when saving
     * a field in the section editor, rather just the if the field has
     * the ability to be shown. Defaults to true.
     * @var boolean
     */
    protected $_showcolumn = true;

    /**
     * Whether this field has an association that should be shown on
     * the Publish Index. This does not mean that it will be, but just
     * that this field has the ability too. Defaults to false.
     * @var boolean
     */
    protected $_showassociation = false;

    /**
     * The entry query field adapter object, responsible for filter and sort.
     * The default class does not set a default EntryQueryFieldAdapter object
     * to allow the compatibility layer to work. In later versions, this can change.
     * @since Symphony 3.0.0
     * @var EntryQueryFieldAdapter
     */
    protected $entryQueryFieldAdapter = null;

    /**
     * Construct a new instance of this field.
     */
    public function __construct()
    {
        $this->_handle = (strtolower(get_class($this)) == 'field' ? 'field' : strtolower(substr(get_class($this), 5)));

    }

    /**
     * Adjust the newly cloned field in order to fix circular references.
     *
     * @return void
     */
    public function __clone()
    {
        if ($this->entryQueryFieldAdapter) {
            $eqfaClass = get_class($this->entryQueryFieldAdapter);
            $this->entryQueryFieldAdapter = new $eqfaClass($this);
        }
    }

    /**
     * Test whether this field can show the table column.
     *
     * @return boolean
     *  true if this can, false otherwise.
     */
    public function canShowTableColumn()
    {
        return $this->_showcolumn;
    }

    /**
     * Test whether this field can show the association column in
     * the Publish Index.
     *
     * @since Symphony 2.6.0
     * @return boolean
     *  true if this can, false otherwise.
     */
    public function canShowAssociationColumn()
    {
        return $this->_showassociation;
    }

    /**
     * Test whether this field can be toggled using the With Selected menu
     * on the Publish Index.
     *
     * @return boolean
     *  true if it can be toggled, false otherwise.
     */
    public function canToggle()
    {
        return false;
    }

    /**
     * Accessor to the toggle states. This default implementation returns
     * an empty array.
     *
     * @return array
     *  the array of toggle states.
     */
    public function getToggleStates()
    {
        return array();
    }

    /**
     * Toggle the field data. This default implementation always returns
     * the input data.
     *
     * @param array $data
     *   the data to toggle.
     * @param string $newState
     *   the new value to set
     * @param integer $entry_id (optional)
     *   an optional entry ID for more intelligent processing. defaults to null
     * @return array
     *   the toggled data.
     */
    public function toggleFieldData(array $data, $newState, $entry_id = null)
    public function toggleFieldData(array $data, /** @scrutinizer ignore-unused */ $newState, $entry_id = null)
    {
        return $data;
    }

    /**
     * Test whether this field can be filtered. This default implementation
     * prohibits filtering. Filtering allows the XML output results to be limited
     * according to an input parameter. Subclasses should override this if
     * filtering is supported.
     *
     * @return boolean
     *  true if this can be filtered, false otherwise.
     */
    public function canFilter()
    {
        return false;
    }

    /**
     * Test whether this field can be filtered in the publish index. This default
     * implementation prohibts filtering. Publish Filtering allows the index view
     * to filter results. Subclasses should override this if
     * filtering is supported.
     *
     * @return boolean
     *  true if this can be publish-filtered, false otherwise.
     */
    public function canPublishFilter()
    {
        return $this->canFilter();
    }

    /**
     * Test whether this field can be prepopulated with data. This default
     * implementation does not support pre-population and, thus, returns false.
     *
     * @return boolean
     *  true if this can be pre-populated, false otherwise.
     */
    public function canPrePopulate()
    {
        return false;
    }

    /**
     * Test whether this field can be sorted. This default implementation
     * returns false.
     *
     * @return boolean
     *  true if this field is sortable, false otherwise.
     */
    public function isSortable()
    {
        return false;
    }

    /**
     * Test whether this field must be unique in a section, that is, only one of
     * this field's type is allowed per section. This default implementation
     * always returns false.
     *
     * @return boolean
     *  true if the content of this field must be unique, false otherwise.
     */
    public function mustBeUnique()
    {
        return false;
    }

    /**
     * Test whether this field supports data source output grouping. This
     * default implementation prohibits grouping. Data-source grouping allows
     * clients of this field to group the XML output according to this field.
     * Subclasses should override this if grouping is supported.
     *
     * @return boolean
     *  true if this field does support data source grouping, false otherwise.
     */
    public function allowDatasourceOutputGrouping()
    {
        return false;
    }

    /**
     * Test whether this field requires grouping. If this function returns true
     * SQL statements generated in the `EntryManager` will include the `DISTINCT` keyword
     * to only return a single row for an entry regardless of how many 'matches' it
     * might have. This default implementation returns false.
     *
     * @return boolean
     *  true if this field requires grouping, false otherwise.
     */
    public function requiresSQLGrouping()
    {
        return false;
    }

    /**
     * Test whether this field supports data source parameter output. This
     * default implementation prohibits parameter output. Data-source
     * parameter output allows this field to be provided as a parameter
     * to other data sources or XSLT. Subclasses should override this if
     * parameter output is supported.
     *
     * @return boolean
     *  true if this supports data source parameter output, false otherwise.
     */
    public function allowDatasourceParamOutput()
    {
        return false;
    }

    /**
     * Accessor to the handle of this field object. The Symphony convention is
     * for field subclass names to be prefixed with field. Handle removes this prefix
     * so that the class handle can be used as the field type.
     *
     * @return string
     *  The field classname minus the field prefix.
     */
    public function handle()
    {
        return $this->_handle;
    }

    /**
     * Accessor to the name of this field object. The name may contain characters
     * that normally would be stripped in the handle while also allowing the field
     * name to be localized. If a name is not set, it will return the handle of the
     * the field
     *
     * @return string
     *  The field name
     */
    public function name()
    {
        return ($this->_name ? $this->_name : $this->_handle);
    }

    /**
     * Clean the input value using html entity encode.
     *
     * @param mixed $value
     *  the value to clean.
     * @return string
     *  the cleaned value.
     */
    public function cleanValue($value)
    {
        return html_entity_decode($value);
    }

    /**
     * Fields have settings that define how that field will act in a section, including
     * if it's required, any validators, if it can be shown on the entries table etc. This
     * function will set a setting to a value.  This function will set a setting to a value
     * overwriting any existing value for this setting
     *
     * @param string $setting
     *  the setting key.
     * @param mixed $value
     *  the value of the setting.
     */
    public function set($setting, $value)
    {
        $this->_settings[$setting] = $value;
    }

    /**
     * Add or overwrite the settings of this field by providing an associative array
     * of the settings. This will do nothing if the input array is empty. If a setting is
     * omitted from the input array, it will not be unset by this function
     *
     * @param array $array
     *  the associative array of settings for this field
     */
    public function setArray(array $array = array())
    {
        if (empty($array)) {
            return;
        }

        foreach ($array as $setting => $value) {
            $this->set($setting, $value);
        }
    }

    /**
     * Fill the input data array with default values for known keys provided
     * these settings are not already set. The input array is then used to set
     * the values of the corresponding settings for this field. This function
     * is called when a section is saved.
     *
     * @param array $settings
     *  the data array to initialize if necessary.
     */
    public function setFromPOST(array $settings = array())
    {
        $settings['location'] = (isset($settings['location']) ? $settings['location'] : 'main');
        $settings['required'] = (isset($settings['required']) && $settings['required'] === 'yes' ? 'yes' : 'no');
        $settings['show_column'] = (isset($settings['show_column']) && $settings['show_column'] === 'yes' ? 'yes' : 'no');

        $this->setArray($settings);
    }

    /**
     * Accessor to the a setting by name. If no setting is provided all the
     * settings of this `Field` instance are returned.
     *
     * @param string $setting (optional)
     *  the name of the setting to access the value for. This is optional and
     *  defaults to null in which case all settings are returned.
     * @return null|mixed|array
     *  the value of the setting if there is one, all settings if the input setting
     *  was omitted or null if the setting was supplied but there is no value
     *  for that setting.
     */
    public function get($setting = null)
    {
        if (is_null($setting)) {
            return $this->_settings;
        }

        if (!isset($this->_settings[$setting])) {
            return null;
        }

        return $this->_settings[$setting];
    }

    /**
     * Unset the value of a setting by the key
     *
     * @param string $setting
     *  the key of the setting to unset.
     */
    public function remove($setting)
    {
        unset($this->_settings[$setting]);
    }


    /**
     * Implementation of ArrayAccess::offsetExists()
     *
     * @param mixed $offset
     * @return bool
     */
    public function offsetExists($offset)
    {
        return isset($this->_settings[$offset]);
    }

    /**
     * Implementation of ArrayAccess::offsetGet()
     *
     * @param mixed $offset
     * @return mixed
     */
    public function offsetGet($offset)
    {
        return $this->_settings[$offset];
    }

    /**
     * Implementation of ArrayAccess::offsetSet()
     *
     * @param mixed $offset
     * @param mixed $value
     * @return void
     */
    public function offsetSet($offset, $value)
    {
        $this->_settings[$offset] = $value;
    }

    /**
     * Implementation of ArrayAccess::offsetUnset()
     *
     * @param mixed $offset
     * @return void
     */
    public function offsetUnset($offset)
    {
        unset($this->_settings[$offset]);
    }

    /**
     * Getter for this field's EntryQuery operations object.
     *
     * @since Symphony 3.0.0
     * @return EntryQueryFieldAdapter
     */
    public function getEntryQueryFieldAdapter()
    {
        return $this->entryQueryFieldAdapter;
    }

    /**
     * Just prior to the field being deleted, this function allows
     * Fields to cleanup any additional things before it is removed
     * from the section. This may be useful to remove data from any
     * custom field tables or the configuration.
     *
     * @since Symphony 2.2.1
     * @return boolean
     */
    public function tearDown()
    {
        return true;
    }

    /**
     * Allows a field to set default settings.
     *
     * @param array $settings
     *  the array of settings to populate with their defaults.
     */
    public function findDefaults(array &$settings)
    {
    }

    /**
     * Display the default settings panel, calls the `buildSummaryBlock`
     * function after basic field settings are added to the wrapper.
     *
     * @see buildSummaryBlock()
     * @param XMLElement $wrapper
     *    the input XMLElement to which the display of this will be appended.
     * @param mixed $errors
     *  the input error collection. this defaults to null.
     * @throws InvalidArgumentException
     */
    public function displaySettingsPanel(XMLElement &$wrapper, $errors = null)
    {
        // Create header
        $location = ($this->get('location') ? $this->get('location') : 'main');
        $header = new XMLElement('header', null, array(
            'class' => 'frame-header ' . $location,
            'data-name' => $this->name(),
            'title' => $this->get('id'),
        ));
        $label = (($this->get('label')) ? $this->get('label') : __('New Field'));
        $header->appendChild(new XMLElement('h4', '<strong>' . $label . '</strong> <span class="type">' . $this->name() . '</span>'));
        $wrapper->appendChild($header);

        // Create content
        $wrapper->appendChild(Widget::Input('fields['.$this->get('sortorder').'][type]', $this->handle(), 'hidden'));
        $wrapper->appendChild(Widget::Input('fields['./** @scrutinizer ignore-type */ $this->get('sortorder').'][type]', $this->handle(), 'hidden'));

        if ($this->get('id')) {
            $wrapper->appendChild(Widget::Input('fields['.$this->get('sortorder').'][id]', $this->get('id'), 'hidden'));
            $wrapper->appendChild(Widget::Input('fields['.$this->get('sortorder').'][id]', /** @scrutinizer ignore-type */ $this->get('id'), 'hidden'));
        }

        $wrapper->appendChild($this->buildSummaryBlock($errors));
    }

    /**
     * Construct the html block to display a summary of this field, which is the field
     * Label and it's location within the section. Any error messages generated are
     * appended to the optional input error array. This function calls
     * `buildLocationSelect` once it is completed
     *
     * @see buildLocationSelect()
     * @param array $errors (optional)
     *    an array to append html formatted error messages to. this defaults to null.
     * @throws InvalidArgumentException
     * @return XMLElement
     *    the root XML element of the html display of this.
     */
    public function buildSummaryBlock($errors = null)
    {
        $div = new XMLElement('div');

        // Publish label
        $label = Widget::Label(__('Label'));
        $label->appendChild(
            Widget::Input('fields['.$this->get('sortorder').'][label]', $this->get('label'))
            Widget::Input('fields['.$this->get('sortorder').'][label]', /** @scrutinizer ignore-type */ $this->get('label'))
        );
        if (isset($errors['label'])) {
            $div->appendChild(Widget::Error($label, $errors['label']));
        } else {
            $div->appendChild($label);
        }

        // Handle + placement
        $group = new XMLElement('div');
        $group->setAttribute('class', 'two columns');

        $label = Widget::Label(__('Handle'));
        $label->setAttribute('class', 'column');

        $label->appendChild(Widget::Input('fields['.$this->get('sortorder').'][element_name]', $this->get('element_name')));

        if (isset($errors['element_name'])) {
            $group->appendChild(Widget::Error($label, $errors['element_name']));
        } else {
            $group->appendChild($label);
        }

        // Location
        $group->appendChild($this->buildLocationSelect($this->get('location'), 'fields['.$this->get('sortorder').'][location]'));
        $group->appendChild($this->buildLocationSelect(/** @scrutinizer ignore-type */ $this->get('location'), 'fields['.$this->get('sortorder').'][location]'));

        $div->appendChild($group);

        return $div;
    }

    /**
     * Build the location select widget. This widget allows users to select
     * whether this field will appear in the main content column or in the sidebar
     * when creating a new entry.
     *
     * @param string|null $selected (optional)
     *    the currently selected location, if there is one. this defaults to null.
     * @param string $name (optional)
     *    the name of this field. this is optional and defaults to `fields[location]`.
     * @param string $label_value (optional)
     *    any predefined label for this widget. this is an optional argument that defaults
     *    to null.
     * @throws InvalidArgumentException
     * @return XMLElement
     *    An XMLElement representing a `<select>` field containing the options.
     */
    public function buildLocationSelect($selected = null, $name = 'fields[location]', $label_value = null)
    {
        if (!$label_value) {
            $label_value = __('Placement');
        }

        $label = Widget::Label($label_value);
        $label->setAttribute('class', 'column');

        $options = array(
            array('main', $selected == 'main', __('Main content')),
            array('sidebar', $selected == 'sidebar', __('Sidebar'))
        );
        $label->appendChild(Widget::Select($name, $options));

        return $label;
    }

    /**
     * Construct the html widget for selecting a text formatter for this field.
     *
     * @param string $selected (optional)
     *    the currently selected text formatter name if there is one. this defaults
     *    to null.
     * @param string $name (optional)
     *    the name of this field in the form. this is optional and defaults to
     *    "fields[format]".
     * @param string $label_value
     *    the default label for the widget to construct. if null is passed in then
     *    this defaults to the localization of "Formatting".
     * @throws InvalidArgumentException
     * @return XMLElement
     *    An XMLElement representing a `<select>` field containing the options.
     */
    public function buildFormatterSelect($selected = null, $name = 'fields[format]', $label_value)
    {
        $formatters = TextformatterManager::listAll();

        if (!$label_value) {
            $label_value = __('Formatting');
        }

        $label = Widget::Label($label_value);
        $label->setAttribute('class', 'column');

        $options = array();

        $options[] = array('none', false, __('None'));

        if (!empty($formatters) && is_array($formatters)) {
            foreach ($formatters as $handle => $about) {
                $options[] = array($handle, ($selected == $handle), $about['name']);
            }
        }

        $label->appendChild(Widget::Select($name, $options));

        return $label;
    }

    /**
     * Append a validator selector to a given `XMLElement`. Note that this
     * function differs from the other two similarly named build functions in
     * that it takes an `XMLElement` to append the Validator to as a parameter,
     * and does not return anything.
     *
     * @param XMLElement $wrapper
     *    the parent element to append the XMLElement of the Validation select to,
     *  passed by reference.
     * @param string $selected (optional)
     *    the current validator selection if there is one. defaults to null if there
     *    isn't.
     * @param string $name (optional)
     *    the form element name of this field. this defaults to "fields[validator]".
     * @param string $type (optional)
     *    the type of input for the validation to apply to. this defaults to 'input'
     *    but also accepts 'upload'.
     * @param array $errors (optional)
     *    an associative array of errors
     * @throws InvalidArgumentException
     */
    public function buildValidationSelect(XMLElement &$wrapper, $selected = null, $name = 'fields[validator]', $type = 'input', array $errors = null)
    {
        include TOOLKIT . '/util.validators.php';


        $rules = ($type == 'upload' ? $upload : $validators);


        $label = Widget::Label(__('Validation Rule'));
        $label->setAttribute('class', 'column');
        $label->appendChild(new XMLElement('i', __('Optional')));
        $label->appendChild(Widget::Input($name, $selected));

        $ul = new XMLElement('ul', null, array('class' => 'tags singular', 'data-interactive' => 'data-interactive'));
        foreach ($rules as $name => $rule) {
            $ul->appendChild(new XMLElement('li', $name, array('class' => $rule)));
        }

        if (isset($errors['validator'])) {
            $div = new XMLElement('div');
            $div->appendChild($label);
            $div->appendChild($ul);

            $wrapper->appendChild(Widget::Error($div, $errors['validator']));
        } else {
            $wrapper->appendChild($label);
            $wrapper->appendChild($ul);
        }
    }

    /**
     * Append the html widget for selecting an association interface and editor
     * for this field.
     *
     * @param XMLElement $wrapper
     *    the parent XML element to append the association interface selection to,
     *    if either interfaces or editors are provided to the system.
     * @since Symphony 2.5.0
     */
    public function appendAssociationInterfaceSelect(XMLElement &$wrapper)
    {
        $wrapper->setAttribute('data-condition', 'associative');

        $interfaces = Symphony::ExtensionManager()->getProvidersOf(iProvider::ASSOCIATION_UI);
        $editors = Symphony::ExtensionManager()->getProvidersOf(iProvider::ASSOCIATION_EDITOR);

        if (!empty($interfaces) || !empty($editors)) {
            $association_context = $this->getAssociationContext();

            $group = new XMLElement('div');
            if (!empty($interfaces) && !empty($editors)) {
                $group->setAttribute('class', 'two columns');
            }

            // Create interface select
            if (!empty($interfaces)) {
                $label = Widget::Label(__('Association Interface'), null, 'column');
                $label->appendChild(new XMLElement('i', __('Optional')));

                $options = array(
                    array(null, false, __('None'))
                );
                foreach ($interfaces as $id => $name) {
                    $options[] = array($id, ($association_context['interface'] === $id), $name);
                }

                $select = Widget::Select('fields[' . $this->get('sortorder') . '][association_ui]', $options);
                $select = Widget::Select('fields[' . /** @scrutinizer ignore-type */ $this->get('sortorder') . '][association_ui]', $options);
                $label->appendChild($select);
                $group->appendChild($label);
            }

            // Create editor select
            if (!empty($editors)) {
                $label = Widget::Label(__('Association Editor'), null, 'column');
                $label->appendChild(new XMLElement('i', __('Optional')));

                $options = array(
                    array(null, false, __('None'))
                );
                foreach ($editors as $id => $name) {
                    $options[] = array($id, ($association_context['editor'] === $id), $name);
                }

                $select = Widget::Select('fields[' . $this->get('sortorder') . '][association_editor]', $options);
                $label->appendChild($select);
                $group->appendChild($label);
            }

            $wrapper->appendChild($group);
        }
    }

    /**
     * Get association data of the current field from the page context.
     *
     * @since Symphony 2.5.0
     * @return array
     */
    public function getAssociationContext()
    {
        $context = Symphony::Engine()->Page->getContext();
        $context = Symphony::Engine()->Page->getContext();
        $associations = $context['associations']['parent'];
        $field_association = array();
        $count = 0;

        if (!empty($associations)) {
            $associationsCount = count($associations);
            for ($i = 0; $i < $associationsCount; $i++) {
                if ($associations[$i]['child_section_field_id'] == $this->get('id')) {
                    if ($count === 0) {
                        $field_association = $associations[$i];
                        $count++;
                    } else {
                        $field_association['parent_section_id'] .= '|' . $associations[$i]['parent_section_id'];
                        $field_association['parent_section_field_id'] .= '|' . $associations[$i]['parent_section_field_id'];
                    }
                }
            }
        }

        return $field_association;
    }

    /**
     * Set association data for the current field.
     *
     * @since Symphony 2.5.0
     * @param XMLElement $wrapper
     */
    public function setAssociationContext(XMLElement &$wrapper)
    {
        $association_context = $this->getAssociationContext();

        if (!empty($association_context)) {
            $wrapper->setAttributeArray(array(
                'data-parent-section-id' => $association_context['parent_section_id'],
                'data-parent-section-field-id' => $association_context['parent_section_field_id'],
                'data-child-section-id' => $association_context['child_section_id'],
                'data-child-section-field-id' => $association_context['child_section_field_id'],
                'data-interface' => $association_context['interface'],
                'data-editor' => $association_context['editor']
            ));
        }
    }

    /**
     * Append and set a labeled html checkbox to the input XML element if this
     * field is set as a required field.
     *
     * @param XMLElement $wrapper
     *    the parent XML element to append the constructed html checkbox to if
     *    necessary.
     * @throws InvalidArgumentException
     */
    public function appendRequiredCheckbox(XMLElement &$wrapper)
    {
        if (!$this->_required) {
            return;
        }

        $this->createCheckboxSetting($wrapper, 'required', __('Make this a required field'));
    }

    /**
     * Append the show column html widget to the input parent XML element. This
     * displays a column in the entries table or not.
     *
     * @param XMLElement $wrapper
     *    the parent XML element to append the checkbox to.
     * @throws InvalidArgumentException
     */
    public function appendShowColumnCheckbox(XMLElement &$wrapper)
    {
        if (!$this->_showcolumn) {
            return;
        }

        $this->createCheckboxSetting($wrapper, 'show_column', __('Display in entries table'));
    }

    /**
     * Append the show association html widget to the input parent XML element. This
     * widget allows fields that provide linking to hide or show the column in the linked
     * section, similar to how the Show Column functionality works, but for the linked
     * section.
     *
     * @param XMLElement $wrapper
     *    the parent XML element to append the checkbox to.
     * @param string $help (optional)
     *    a help message to show below the checkbox.
     * @throws InvalidArgumentException
     */
    public function appendShowAssociationCheckbox(XMLElement &$wrapper, $help = null)
    {
        if (!$this->_showassociation) {
            return;
        }

        $label = $this->createCheckboxSetting($wrapper, 'show_association', __('Display associations in entries table'), $help);
        $label->setAttribute('data-condition', 'associative');
    }

    /**
     * Given the setting name and the label, this helper method will add
     * the required markup for a checkbox to the given `$wrapper`.
     *
     * @since Symphony 2.5.2
     * @param XMLElement $wrapper
     *  Passed by reference, this will have the resulting markup appended to it
     * @param string $setting
     *  This will be used with $this->get() to get the existing value
     * @param string $label_description
     *  This will be localisable and displayed after the checkbox when
     *  generated.
     * @param string $help (optional)
     *    A help message to show below the checkbox.
     * @return XMLElement
     *  The Label and Checkbox that was just added to the `$wrapper`.
     */
    public function createCheckboxSetting(XMLElement &$wrapper, $setting, $label_description, $help = null)
    {
        $order = $this->get('sortorder');
        $name = "fields[$order][$setting]";

        $label = Widget::Checkbox($name, $this->get($setting), $label_description, $wrapper, $help);
        $label = Widget::Checkbox($name, /** @scrutinizer ignore-type */ $this->get($setting), $label_description, $wrapper, $help);
        $label->addClass('column');

        return $label;
    }

    /**
     * Append the default status footer to the field settings panel.
     * Displays the required and show column checkboxes.
     *
     * @param XMLElement $wrapper
     *    the parent XML element to append the checkbox to.
     * @throws InvalidArgumentException
     */
    public function appendStatusFooter(XMLElement &$wrapper)
    {
        $fieldset = new XMLElement('fieldset');
        $div = new XMLElement('div', null, array('class' => 'two columns'));

        $this->appendRequiredCheckbox($div);
        $this->appendShowColumnCheckbox($div);

        $fieldset->appendChild($div);
        $wrapper->appendChild($fieldset);
    }

    /**
     * Check the field's settings to ensure they are valid on the section
     * editor
     *
     * @param array $errors
     *  the array to populate with the errors found.
     * @param boolean $checkForDuplicates (optional)
     *  if set to true, duplicate Field name's in the same section will be flagged
     *  as errors. Defaults to true.
     * @return integer
     *  returns the status of the checking. if errors has been populated with
     *  any errors `self::__ERROR__`, `self::__OK__` otherwise.
     */
    public function checkFields(array &$errors, $checkForDuplicates = true)
    {
        $parent_section = $this->get('parent_section');
        $label = $this->get('label');
        $element_name = $this->get('element_name');

        if (Lang::isUnicodeCompiled()) {
            $valid_name = preg_match('/^[\p{L}]([0-9\p{L}\.\-\_]+)?$/u', $element_name);
            $valid_name = preg_match('/^[\p{L}]([0-9\p{L}\.\-\_]+)?$/u', /** @scrutinizer ignore-type */ $element_name);
        } else {
            $valid_name = preg_match('/^[A-z]([\w\d-_\.]+)?$/i', $element_name);
        }

        if ($label === '') {
            $errors['label'] = __('This is a required field.');
        } elseif (strtolower($label) === 'id') {
        } elseif (strtolower(/** @scrutinizer ignore-type */ $label) === 'id') {
            $errors['label'] = __('%s is a reserved name used by the system and is not allowed for a field handle. Try using %s instead.', array('<code>ID</code>', '<code>UID</code>'));
        }

        if ($element_name === '') {
            $errors['element_name'] = __('This is a required field.');
        } elseif ($element_name === 'id') {
            $errors['element_name'] = __('%s is a reserved name used by the system and is not allowed for a field handle. Try using %s instead.', array('<code>id</code>', '<code>uid</code>'));
        } elseif (!$valid_name) {
            $errors['element_name'] = __('Invalid element name. Must be valid %s.', array('<code>QName</code>'));
        } elseif ($checkForDuplicates) {
            if (FieldManager::fetchFieldIDFromElementName($element_name, $parent_section) !== $this->get('id')) {
            if (FieldManager::fetchFieldIDFromElementName($element_name, /** @scrutinizer ignore-type */ $parent_section) !== $this->get('id')) {
                $errors['element_name'] = __('A field with that element name already exists. Please choose another.');
            }
        }

        // Check that if the validator is provided that it's a valid regular expression
        if (!is_null($this->get('validator')) && $this->get('validator') !== '') {
            if (@preg_match($this->get('validator'), 'teststring') === false) {
            if (@preg_match(/** @scrutinizer ignore-type */ $this->get('validator'), 'teststring') === false) {
                $errors['validator'] = __('Validation rule is not a valid regular expression');
            }
        }

        return (!empty($errors) ? self::__ERROR__ : self::__OK__);
    }

    /**
     * Format this field value for display in the publish index tables.
     *
     * Since Symphony 2.5.0, this function will call `Field::prepareReadableValue`
     * in order to get the field's human readable value.
     *
     * @param array $data
     *  an associative array of data for this string. At minimum this requires a
     *  key of 'value'.
     * @param XMLElement $link (optional)
     *  an XML link structure to append the content of this to provided it is not
     *  null. it defaults to null.
     * @param integer $entry_id (optional)
     *  An option entry ID for more intelligent processing. defaults to null
     * @return string
     *  the formatted string summary of the values of this field instance.
     */
    public function prepareTableValue($data, XMLElement $link = null, $entry_id = null)
    {
        $value = $this->prepareReadableValue($data, $entry_id, true, __('None'));

        if ($link) {
            $link->setValue($value);

            return $link->generate();
        }

        return $value;
    }

    /**
     * Format this field value for display as readable  text value. By default, it
     * will call `Field::prepareTextValue` to get the raw text value of this field.
     *
     * If $truncate is set to true, Symphony will truncate the value to the
     * configuration setting `cell_truncation_length`.
     *
     * @since Symphony 2.5.0
     * @param array $data
     *  an associative array of data for this string. At minimum this requires a
     *  key of 'value'.
     * @param integer $entry_id (optional)
     *  An option entry ID for more intelligent processing. Defaults to null.
     * @param string $defaultValue (optional)
     *  The value to use when no plain text representation of the field's data
     *  can be made. Defaults to null.
     * @return string
     *  the readable text summary of the values of this field instance.
     */
    public function prepareReadableValue($data, $entry_id = null, $truncate = false, $defaultValue = null)
    {
        $value = $this->prepareTextValue($data, $entry_id);

        if ($truncate) {
            $max_length = Symphony::Configuration()->get('cell_truncation_length', 'symphony');
            $max_length = ($max_length ? $max_length : 75);

            $value = (General::strlen($value) <= $max_length ? $value : General::substr($value, 0, $max_length) . '…');
        }

        if (General::strlen($value) == 0 && $defaultValue != null) {

            $value = $defaultValue;
        }

        return $value;
    }

    /**
     * Format this field value for complete display as text (string). By default,
     * it looks for the 'value' key in the $data array and strip tags from it.
     *
     * @since Symphony 2.5.0
     * @param array $data
     *  an associative array of data for this string. At minimum this requires a
     *  key of 'value'.
     * @param integer $entry_id (optional)
     *  An option entry ID for more intelligent processing. defaults to null
     * @return string
     *  the complete text representation of the values of this field instance.
     */
    public function prepareTextValue($data, $entry_id = null)
    {
        return strip_tags($data['value']);
    }

    /**
     * This is general purpose factory method that makes it easier to create the
     * markup needed in order to create an Associations Drawer XMLElement.
     *
     * @since Symphony 2.5.0
     *
     * @param string $value
     *   The value to display in the link
     * @param Entry $e
     *   The associated entry
     * @param array $parent_association
     *   An array containing information about the association
     * @param string $prepopulate
     *   A string containing prepopulate parameter to append to the association url
     *
     * @return XMLElement
     *   The XMLElement must be a li node, since it will be added an ul node.
     */
    public static function createAssociationsDrawerXMLElement($value, Entry $e, array $parent_association, $prepopulate = '')
    {
        $li = new XMLElement('li');
        $a = new XMLElement('a', $value);
        $a->setAttribute('href', SYMPHONY_URL . '/publish/' . $parent_association['handle'] . '/edit/' . $e->get('id') . '/' . $prepopulate);
        $a->setAttribute('href', SYMPHONY_URL . '/publish/' . $parent_association['handle'] . '/edit/' . /** @scrutinizer ignore-type */ $e->get('id') . '/' . $prepopulate);
        $li->appendChild($a);
        return $li;
    }

    /**
     * Format this field value for display in the Associations Drawer publish index.
     * By default, Symphony will use the return value of the `prepareReadableValue` function.
     *
     * @since Symphony 2.4
     * @since Symphony 2.5.0 The prepopulate parameter was added.
     *
     * @param Entry $e
     *   The associated entry
     * @param array $parent_association
     *   An array containing information about the association
     * @param string $prepopulate
     *   A string containing prepopulate parameter to append to the association url
     *
     * @return XMLElement
     *   The XMLElement must be a li node, since it will be added an ul node.
     */
    public function prepareAssociationsDrawerXMLElement(Entry $e, array $parent_association, $prepopulate = '')
    {
        $value = $this->prepareReadableValue($e->getData($this->get('id')), $e->get('id'));
        $value = $this->prepareReadableValue(/** @scrutinizer ignore-type */ $e->getData($this->get('id')), $e->get('id'));

        // fallback for compatibility since the default
        // `preparePlainTextValue` is not compatible with all fields
        // this should be removed in Symphony 3.0
        if (empty($value)) {
            $value = strip_tags($this->prepareTableValue($e->getData($this->get('id')), null, $e->get('id')));
            $value = strip_tags($this->prepareTableValue($e->getData($this->get('id')), null, /** @scrutinizer ignore-type */ $e->get('id')));
        }

        // use our factory method to create the html
        $li = self::createAssociationsDrawerXMLElement($value, $e, $parent_association, $prepopulate);

        $li->setAttribute('class', 'field-' . $this->get('type'));
        $li->setAttribute('class', 'field-' . /** @scrutinizer ignore-type */ $this->get('type'));

        return $li;
    }

    /**
     * Display the publish panel for this field. The display panel is the
     * interface shown to Authors that allow them to input data into this
     * field for an `Entry`.
     *
     * @param XMLElement $wrapper
     *  the XML element to append the html defined user interface to this
     *  field.
     * @param array $data (optional)
     *  any existing data that has been supplied for this field instance.
     *  this is encoded as an array of columns, each column maps to an
     *  array of row indexes to the contents of that column. this defaults
     *  to null.
     * @param mixed $flagWithError (optional)
     *  flag with error defaults to null.
     * @param string $fieldnamePrefix (optional)
     *  the string to be prepended to the display of the name of this field.
     *  this defaults to null.
     * @param string $fieldnamePostfix (optional)
     *  the string to be appended to the display of the name of this field.
     *  this defaults to null.
     * @param integer $entry_id (optional)
     *  the entry id of this field. this defaults to null.
     */
    public function displayPublishPanel(XMLElement &$wrapper, $data = null, $flagWithError = null, $fieldnamePrefix = null, $fieldnamePostfix = null, $entry_id = null)
    public function displayPublishPanel(XMLElement &$wrapper, $data = null, /** @scrutinizer ignore-unused */ $flagWithError = null, $fieldnamePrefix = null, $fieldnamePostfix = null, $entry_id = null)
    {
    }

    /**
     * Check the field data that has been posted from a form. This will set the
     * input message to the error message or to null if there is none. Any existing
     * message value will be overwritten.
     *
     * @param array $data
     *  the input data to check.
     * @param string $message
     *  the place to set any generated error message. any previous value for
     *  this variable will be overwritten.
     * @param integer $entry_id (optional)
     *  the optional id of this field entry instance. this defaults to null.
     * @return integer
     *  `self::__MISSING_FIELDS__` if there are any missing required fields,
     *  `self::__OK__` otherwise.
     */
    public function checkPostFieldData($data, &$message, $entry_id = null)
    {
        $message = null;

        $has_no_value = is_array($data) ? empty($data) : strlen(trim($data)) == 0;


        if ($this->get('required') === 'yes' && $has_no_value) {
            $message = __('‘%s’ is a required field.', array($this->get('label')));

            return self::__MISSING_FIELDS__;
        }

        return self::__OK__;
    }

    /**
     * Process the raw field data.
     *
     * @param mixed $data
     *  post data from the entry form
     * @param integer $status
     *  the status code resultant from processing the data.
     * @param string $message
     *  the place to set any generated error message. any previous value for
     *  this variable will be overwritten.
     * @param boolean $simulate (optional)
     *  true if this will tell the CF's to simulate data creation, false
     *  otherwise. this defaults to false. this is important if clients
     *  will be deleting or adding data outside of the main entry object
     *  commit function.
     * @param mixed $entry_id (optional)
     *  the current entry. defaults to null.
     * @return array
     *  the processed field data.
     */
    public function processRawFieldData($data, &$status, &$message = null, $simulate = false, $entry_id = null)
    public function processRawFieldData($data, &$status, &$message = null, /** @scrutinizer ignore-unused */ $simulate = false, $entry_id = null)
    {
        $status = self::__OK__;

        return array(
            'value' => $data,
        );
    }

    /**
     * Returns the keywords that this field supports for filtering. Note
     * that no filter will do a simple 'straight' match on the value.
     *
     * @since Symphony 2.6.0
     * @return array
     */
    public function fetchFilterableOperators()
    {
        return array(
            array(
                'title' => 'is',
                'filter' => ' ',
                'help' => __('Find values that are an exact match for the given string.')
            ),
            array(
                'filter' => 'sql: NOT NULL',
                'title' => 'is not empty',
                'help' => __('Find entries with a non-empty value.')
            ),
            array(
                'filter' => 'sql: NULL',
                'title' => 'is empty',
                'help' => __('Find entries with an empty value.')
            ),
            array(
                'title' => 'contains',
                'filter' => 'regexp: ',
                'help' => __('Find values that match the given <a href="%s">MySQL regular expressions</a>.', array(
                    'https://dev.mysql.com/doc/mysql/en/regexp.html'
                ))
            ),
            array(
                'title' => 'does not contain',
                'filter' => 'not-regexp: ',
                'help' => __('Find values that do not match the given <a href="%s">MySQL regular expressions</a>.', array(
                    'https://dev.mysql.com/doc/mysql/en/regexp.html'
                ))
            ),
        );
    }

    /**
     * Returns the types of filter suggestion this field supports. 
     * The array may contain the following values:
     *
     * - `entry` for searching entries in the current section
     * - `association` for searching entries in associated sections
     * - `static` for searching static values
     * - `date` for searching in a calendar
     * - `parameters` for searching in parameters
     *
     * If the date type is set, only the calendar will be shown in the suggestion dropdown.
     *
     * @since Symphony 2.6.0
     * @return array
     */
    public function fetchSuggestionTypes()
    {
        return array('entry');
    }

    /**
     * Display the default data source filter panel.
     *
     * @param XMLElement $wrapper
     *    the input XMLElement to which the display of this will be appended.
     * @param mixed $data (optional)
     *    the input data. this defaults to null.

     * @param null $errors
     *  the input error collection. this defaults to null.
     * @param string $fieldnamePrefix
     *  the prefix to apply to the display of this.
     * @param string $fieldnamePostfix
     *  the suffix to apply to the display of this.
     * @throws InvalidArgumentException
     */
    public function displayDatasourceFilterPanel(XMLElement &$wrapper, $data = null, $errors = null, $fieldnamePrefix = null, $fieldnamePostfix = null)
    public function displayDatasourceFilterPanel(XMLElement &$wrapper, $data = null, /** @scrutinizer ignore-unused */ $errors = null, $fieldnamePrefix = null, $fieldnamePostfix = null)
    {
        $wrapper->appendChild(new XMLElement('header', '<h4>' . $this->get('label') . '</h4> <span>' . $this->name() . '</span>', array(
        $wrapper->appendChild(new XMLElement('header', '<h4>' . /** @scrutinizer ignore-type */ $this->get('label') . '</h4> <span>' . $this->name() . '</span>', array(
            'data-name' => $this->get('label') . ' (' . $this->name() . ')'
        )));

        $label = Widget::Label(__('Value'));
        $input = Widget::Input('fields[filter]'.($fieldnamePrefix ? '['.$fieldnamePrefix.']' : '').'['.$this->get('id').']'.($fieldnamePostfix ? '['.$fieldnamePostfix.']' : ''), ($data ? General::sanitize($data) : null));
        $input = Widget::Input('fields[filter]'.($fieldnamePrefix ? '['.$fieldnamePrefix.']' : '').'['./** @scrutinizer ignore-type */ $this->get('id').']'.($fieldnamePostfix ? '['.$fieldnamePostfix.']' : ''), ($data ? General::sanitize($data) : null));
        $input->setAttribute('autocomplete', 'off');
        $input->setAttribute('data-search-types', 'parameters');
        $input->setAttribute('data-trigger', '{$');
        $label->appendChild($input);
        $wrapper->appendChild($label);

        $this->displayFilteringOptions($wrapper);
    }

    /**
     * Inserts tags at the bottom of the filter panel
     *
     * @since Symphony 2.6.0
     * @param XMLElement $wrapper
     */
    public function displayFilteringOptions(XMLElement &$wrapper)
    {
        // Add filter tags
        $filterTags = new XMLElement('ul');
        $filterTags->setAttribute('class', 'tags singular');
        $filterTags->setAttribute('data-interactive', 'data-interactive');

        $filters = $this->fetchFilterableOperators();
        foreach ($filters as $value) {
            $item = new XMLElement('li', $value['title']);
            $item->setAttribute('data-value', $value['filter']);

            if (isset($value['help'])) {
                $item->setAttribute('data-help', General::sanitize($value['help']));
            }

            $filterTags->appendChild($item);
        }
        $wrapper->appendChild($filterTags);

        $help = new XMLElement('p');
        $help->setAttribute('class', 'help');
        $first = array_shift($filters);
        $help->setValue($first['help']);
        $wrapper->appendChild($help);
    }

    /**
     * Default accessor for the includable elements of this field. This array
     * will populate the `Datasource` included elements. Fields that have
     * different modes will override this and add new items to the array.
     * The Symphony convention is element_name : mode. Modes allow Fields to
     * output different XML in datasources.
     *
     * @return array
     *  the array of includable elements from this field.
     */
    public function fetchIncludableElements()
    {
        return array($this->get('element_name'));
    }

    /**
     * Test whether the input string is a regular expression, by searching
     * for the prefix of `regexp:` or `not-regexp:` in the given `$string`.
     *
     * @deprecated @since Symphony 3.0.0
     *  Use EntryQueryFieldAdapter::isFilterRegex() instead
     * @param string $string
     *  The string to test.
     * @return boolean
     *  true if the string is prefixed with `regexp:` or `not-regexp:`, false otherwise.
     */
    protected static function isFilterRegex($string)
    {
        if (Symphony::Log()) {
            Symphony::Log()->pushDeprecateWarningToLog(
                get_called_class() . '::isFilterRegex()',
                'EntryQueryFieldAdapter::isFilterRegex()'
            );
        }
        if (preg_match('/^regexp:/i', $string) || preg_match('/^not-?regexp:/i', $string)) {
            return true;
        }
    }

    /**
     * Builds a basic REGEXP statement given a `$filter`. This function supports
     * `regexp:` or `not-regexp:`. Users should keep in mind this function
     * uses MySQL patterns, not the usual PHP patterns, the syntax between these
     * flavours differs at times.
     *
     * @since Symphony 2.3
     * @deprecated @since Symphony 3.0.0
     *  Use EntryQueryFieldAdapter::createFilterRegexp() instead
     * @link https://dev.mysql.com/doc/refman/en/regexp.html
     * @param string $filter
     *  The full filter, eg. `regexp: ^[a-d]`
     * @param array $columns
     *  The array of columns that need the given `$filter` applied to. The conditions
     *  will be added using `OR` when using `regexp:` but they will be added using `AND`
     *  when using `not-regexp:`
     * @param string $joins
     *  A string containing any table joins for the current SQL fragment. By default
     *  Datasources will always join to the `tbl_entries` table, which has an alias of
     *  `e`. This parameter is passed by reference.
     * @param string $where
     *  A string containing the WHERE conditions for the current SQL fragment. This
     *  is passed by reference and is expected to be used to add additional conditions
     *  specific to this field
     */
    public function buildRegexSQL($filter, array $columns, &$joins, &$where)
    {
        if (Symphony::Log()) {
            Symphony::Log()->pushDeprecateWarningToLog(
                get_called_class() . '::buildRegexSQL()',
                'EntryQueryFieldAdapter::createFilterRegexp()'
            );
        }
        $this->_key++;
        /** @scrutinizer ignore-deprecated */ $this->_key++;
        $field_id = $this->get('id');
        $filter = $this->cleanValue($filter);
        $op = '';

        if (preg_match('/^regexp:\s*/i', $filter)) {
            $pattern = preg_replace('/^regexp:\s*/i', null, $filter);
            $regex = 'REGEXP';
            $op = 'OR';
        } elseif (preg_match('/^not-?regexp:\s*/i', $filter)) {
            $pattern = preg_replace('/^not-?regexp:\s*/i', null, $filter);
            $regex = 'NOT REGEXP';
            $op = 'AND';
        } else {
            throw new Exception("Filter `$filter` is not a Regexp filter");
        }

        if (strlen($pattern) == 0) {
            return;
        }

        $joins .= "
            LEFT JOIN
                `tbl_entries_data_{$field_id}` AS t{$field_id}_{$this->_key}
                `tbl_entries_data_{$field_id}` AS t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}
                ON (e.id = t{$field_id}_{$this->_key}.entry_id)
                ON (e.id = t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}.entry_id)
        ";

        $where .= "AND ( ";

        foreach ($columns as $key => $col) {
            $modifier = ($key === 0) ? '' : $op;

            $where .= "
                {$modifier} t{$field_id}_{$this->_key}.{$col} {$regex} '{$pattern}'
                {$modifier} t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}.{$col} {$regex} '{$pattern}'
            ";
        }
        $where .= ")";
    }

    /**
     * Test whether the input string is a NULL/NOT NULL SQL clause, by searching
     * for the prefix of `sql:` in the given `$string`, followed by `(NOT )? NULL`
     *
     * @since Symphony 2.7.0
     * @deprecated @since Symphony 3.0.0
     *  Use EntryQueryFieldAdapter::isFilterSQL() instead
     * @param string $string
     *  The string to test.
     * @return boolean
     *  true if the string is prefixed with `sql:`, false otherwise.
     */
    protected static function isFilterSQL($string)
    {
        if (Symphony::Log()) {
            Symphony::Log()->pushDeprecateWarningToLog(
                get_called_class() . '::isFilterSQL()',
                'EntryQueryFieldAdapter::isFilterSQL()'
            );
        }
        if (preg_match('/^sql:\s*(NOT )?NULL$/i', $string)) {
            return true;
        }
    }

    /**
     * Builds a basic NULL/NOT NULL SQL statement given a `$filter`.
     *  This function supports `sql: NULL` or `sql: NOT NULL`.
     *
     * @since Symphony 2.7.0
     * @deprecated @since Symphony 3.0.0
     *  Use EntryQueryFieldAdapter::createFilterSQL() instead
     * @link https://dev.mysql.com/doc/refman/en/regexp.html
     * @param string $filter
     *  The full filter, eg. `sql: NULL`
     * @param array $columns
     *  The array of columns that need the given `$filter` applied to. The conditions
     *  will be added using `OR`.
     * @param string $joins
     *  A string containing any table joins for the current SQL fragment. By default
     *  Datasources will always join to the `tbl_entries` table, which has an alias of
     *  `e`. This parameter is passed by reference.
     * @param string $where
     *  A string containing the WHERE conditions for the current SQL fragment. This
     *  is passed by reference and is expected to be used to add additional conditions
     *  specific to this field
     */
    public function buildFilterSQL($filter, array $columns, &$joins, &$where)
    {
        if (Symphony::Log()) {
            Symphony::Log()->pushDeprecateWarningToLog(
                get_called_class() . '::buildFilterSQL()',
                'EntryQueryFieldAdapter::createFilterSQL()'
            );
        }
        $this->_key++;
        /** @scrutinizer ignore-deprecated */ $this->_key++;
        $field_id = $this->get('id');
        $filter = $this->cleanValue($filter);
        $pattern = '';

        if (preg_match('/^sql:\s*NOT NULL$/i', $filter)) {
            $pattern = 'NOT NULL';
        } elseif (preg_match('/^sql:\s*NULL$/i', $filter)) {
            $pattern = 'NULL';
        } else {
            // No match, return
            return;
        }

        $joins .= "
            LEFT JOIN
                `tbl_entries_data_{$field_id}` AS t{$field_id}_{$this->_key}
                `tbl_entries_data_{$field_id}` AS t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}
                ON (e.id = t{$field_id}_{$this->_key}.entry_id)
                ON (e.id = t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}.entry_id)
        ";

        $where .= "AND ( ";

        foreach ($columns as $key => $col) {
            $modifier = ($key === 0) ? '' : 'OR';

            $where .= "
                {$modifier} t{$field_id}_{$this->_key}.{$col} IS {$pattern}
                {$modifier} t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}.{$col} IS {$pattern}
            ";
        }
        $where .= ")";
    }

    /**
     * Construct the SQL statement fragments to use to retrieve the data of this
     * field when utilized as a data source.
     *
     * @deprecated @since Symphony 3.0.0
     *  Use EntryQueryFieldAdapter::filter() instead
     * @param array $data
     *  An array of the data that contains the values for the filter as specified
     *  in the datasource editor. The value that is entered in the datasource editor
     *  is made into an array by using + or , to separate the filter.
     * @param string $joins
     *  A string containing any table joins for the current SQL fragment. By default
     *  Datasources will always join to the `tbl_entries` table, which has an alias of
     *  `e`. This parameter is passed by reference.
     * @param string $where
     *  A string containing the WHERE conditions for the current SQL fragment. This
     *  is passed by reference and is expected to be used to add additional conditions
     *  specific to this field
     * @param boolean $andOperation (optional)
     *  This parameter defines whether the `$data` provided should be treated as
     *  AND or OR conditions. This parameter will be set to true if $data used a
     *  + to separate the values, otherwise it will be false. It is false by default.
     * @return boolean
     *  true if the construction of the SQL was successful, false otherwise.
     */
    public function buildDSRetrievalSQL($data, &$joins, &$where, $andOperation = false)
    {
        if (Symphony::Log()) {
            Symphony::Log()->pushDeprecateWarningToLog(
                get_called_class() . '::buildDSRetrievalSQL()',
                'EntryQueryFieldAdapter::filter()'
            );
        }
        $field_id = $this->get('id');

        // REGEX filtering is a special case, and will only work on the first item
        // in the array. You cannot specify multiple filters when REGEX is involved.
        if (self::isFilterRegex($data[0])) {
        if (/** @scrutinizer ignore-deprecated */ self::isFilterRegex($data[0])) {
            $this->buildRegexSQL($data[0], array('value'), $joins, $where);
            /** @scrutinizer ignore-deprecated */ $this->buildRegexSQL($data[0], array('value'), $joins, $where);

            // SQL filtering: allows for NULL/NOT NULL statements
        } elseif (self::isFilterSQL($data[0])) {
        } elseif (/** @scrutinizer ignore-deprecated */ self::isFilterSQL($data[0])) {
            $this->buildFilterSQL($data[0], array('value'), $joins, $where);
            /** @scrutinizer ignore-deprecated */ $this->buildFilterSQL($data[0], array('value'), $joins, $where);

            // AND operation, iterates over `$data` and uses a new JOIN for
            // every item.
        } elseif ($andOperation) {
            foreach ($data as $value) {
                $this->_key++;
                /** @scrutinizer ignore-deprecated */ $this->_key++;
                $value = $this->cleanValue($value);
                $joins .= "
                    LEFT JOIN
                        `tbl_entries_data_{$field_id}` AS t{$field_id}_{$this->_key}
                        `tbl_entries_data_{$field_id}` AS t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}
                        ON (e.id = t{$field_id}_{$this->_key}.entry_id)
                        ON (e.id = t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}.entry_id)
                ";
                $where .= "
                    AND t{$field_id}_{$this->_key}.value = '{$value}'
                    AND t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}.value = '{$value}'
                ";
            }

            // Default logic, this will use a single JOIN statement and collapse
            // `$data` into a string to be used in conjunction with IN
        } else {
            foreach ($data as &$value) {
                $value = $this->cleanValue($value);
            }

            $this->_key++;
            /** @scrutinizer ignore-deprecated */ $this->_key++;
            $data = implode("', '", $data);
            $joins .= "
                LEFT JOIN
                    `tbl_entries_data_{$field_id}` AS t{$field_id}_{$this->_key}
                    `tbl_entries_data_{$field_id}` AS t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}
                    ON (e.id = t{$field_id}_{$this->_key}.entry_id)
                    ON (e.id = t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}.entry_id)
            ";
            $where .= "
                AND t{$field_id}_{$this->_key}.value IN ('{$data}')
                AND t{$field_id}_{/** @scrutinizer ignore-deprecated */ $this->_key}.value IN ('{$data}')
            ";
        }

        return true;
    }

    /**
     * Determine if the requested $order is random or not.
     *
     * @since Symphony 2.7.0
     * @deprecated @since Symphony 3.0.0
     *  Use EntryQueryFieldAdapter::isRandomOrder() instead
     * @param string $order
     *  the sorting direction.
     * @return boolean
     *  true if the $order is either 'rand' or 'random'
     */
    protected function isRandomOrder($order)
    {
        if (Symphony::Log()) {
            Symphony::Log()->pushDeprecateWarningToLog(
                get_called_class() . '::isRandomOrder()',
                'EntryQueryFieldAdapter::isRandomOrder()'
            );
        }
        return in_array(strtolower($order), array('random', 'rand'));
    }

    /**
     * Build the SQL command to append to the default query to enable
     * sorting of this field. By default this will sort the results by
     * the entry id in ascending order.
     *
     * Extension developers should always implement both `buildSortingSQL()`
     * and `buildSortingSelectSQL()`.
     *
     * @deprecated @since Symphony 3.0.0
     *  Use EntryQueryFieldAdapter::sort() instead
     * @uses Field::isRandomOrder()
     * @see Field::buildSortingSelectSQL()
     * @param string $joins
     *  the join element of the query to append the custom join sql to.
     * @param string $where
     *  the where condition of the query to append to the existing where clause.
     * @param string $sort
     *  the existing sort component of the sql query to append the custom
     *  sort sql code to.
     * @param string $order (optional)
     *  an optional sorting direction. this defaults to ascending. if this
     *  is declared either 'random' or 'rand' then a random sort is applied.
     */
    public function buildSortingSQL(&$joins, &$where, &$sort, $order = 'ASC')
    {
        if (Symphony::Log()) {
            Symphony::Log()->pushDeprecateWarningToLog(
                get_called_class() . '::buildSortingSQL()',
                'EntryQueryFieldAdapter::sort()'
            );
        }
        if ($this->isRandomOrder($order)) {
        if (/** @scrutinizer ignore-deprecated */ $this->isRandomOrder($order)) {
            $sort = 'ORDER BY RAND()';
        } else {
            $joins .= "LEFT OUTER JOIN `tbl_entries_data_".$this->get('id')."` AS `ed` ON (`e`.`id` = `ed`.`entry_id`) ";
            $joins .= "LEFT OUTER JOIN `tbl_entries_data_"./** @scrutinizer ignore-type */ $this->get('id')."` AS `ed` ON (`e`.`id` = `ed`.`entry_id`) ";
            $sort = sprintf('ORDER BY `ed`.`value` %s', $order);
        }
    }

    /**
     * Build the needed SQL clause command to make `buildSortingSQL()` work on
     * MySQL 5.7 in strict mode, which requires all columns in the ORDER BY
     * clause to be included in the SELECT's projection.
     *
     * If no new projection is needed (like if the order is made via a sub-query),
     * simply return null.
     *
     * For backward compatibility, this method checks if the sort expression
     * contains `ed`.`value`. This check will be removed in Symphony 3.0.0.
     *
     * Extension developers should make their Fields implement
     * `buildSortingSelectSQL()` when overriding `buildSortingSQL()`.
     *
     * @deprecated @since Symphony 3.0.0
     *  Use EntryQueryFieldAdapter::sort() instead
     * @since Symphony 2.7.0
     * @uses Field::isRandomOrder()
     * @see Field::buildSortingSQL()
     * @param string $sort
     *  the existing sort component of the sql query, after it has been passed
     *  to `buildSortingSQL()`
     * @param string $order (optional)
     *  an optional sorting direction. this defaults to ascending. Should be the
     *  same value that was passed to `buildSortingSQL()`
     * @return string
     *  an optional select clause to append to the generated SQL query.
     *  This is needed when sorting on a column that is not part of the projection.
     */
    public function buildSortingSelectSQL($sort, $order = 'ASC')
    {
        if (Symphony::Log()) {
            Symphony::Log()->pushDeprecateWarningToLog(
                get_called_class() . '::buildSortingSelectSQL()',
                'EntryQueryFieldAdapter::sort()'
            );
        }
        if ($this->isRandomOrder($order)) {
        if (/** @scrutinizer ignore-deprecated */ $this->isRandomOrder($order)) {
            return null;
        }
        // @deprecated This check should be removed in Symphony 3.0.0
        if (strpos($sort, '`ed`.`value`') === false) {
            return null;
        }
        return '`ed`.`value`';
    }

    /**
     * Default implementation of record grouping. This default implementation
     * will throw an `Exception`. Thus, clients must overload this method
     * for grouping to be successful.
     *
     * @throws Exception
     * @param array $records
     *  the records to group.
     */
    public function groupRecords($records)
    public function groupRecords(/** @scrutinizer ignore-unused */ $records)
    {
        throw new Exception(
            __('Data source output grouping is not supported by the %s field', array('<code>' . $this->get('label') . '</code>'))
            __('Data source output grouping is not supported by the %s field', array('<code>' . /** @scrutinizer ignore-type */ $this->get('label') . '</code>'))
        );
    }

    /**
     * Function to format this field if it chosen in a data source to be
     * output as a parameter in the XML.
     *
     * Since Symphony 2.5.0, it will defaults to `prepareReadableValue` return value.
     *
     * @param array $data
     *  The data for this field from it's `tbl_entry_data_{id}` table
     * @param integer $entry_id
     *  The optional id of this field entry instance
     * @return string|array
     *  The formatted value to be used as the parameter. Note that this can be
     *  an array or a string. When returning multiple values use array, otherwise
     *  use string.
     */
    public function getParameterPoolValue(array $data, $entry_id = null)
    {
        return $this->prepareReadableValue($data, $entry_id);
    }

    /**
     * Append the formatted XML output of this field as utilized as a data source.
     *
     * Since Symphony 2.5.0, it will defaults to `prepareReadableValue` return value.
     *
     * @param XMLElement $wrapper
     *  the XML element to append the XML representation of this to.
     * @param array $data
     *  the current set of values for this field. the values are structured as
     *  for displayPublishPanel.
     * @param boolean $encode (optional)
     *  flag as to whether this should be html encoded prior to output. this
     *  defaults to false.
     * @param string $mode
     *   A field can provide ways to output this field's data. For instance a mode
     *  could be 'items' or 'full' and then the function would display the data
     *  in a different way depending on what was selected in the datasource
     *  included elements.
     * @param integer $entry_id (optional)
     *  the identifier of this field entry instance. defaults to null.
     */
    public function appendFormattedElement(XMLElement &$wrapper, $data, $encode = false, $mode = null, $entry_id = null)
    public function appendFormattedElement(XMLElement &$wrapper, $data, $encode = false, /** @scrutinizer ignore-unused */ $mode = null, $entry_id = null)
    {
        $wrapper->appendChild(new XMLElement($this->get('element_name'), ($encode ?
        $wrapper->appendChild(new XMLElement(/** @scrutinizer ignore-type */ $this->get('element_name'), ($encode ?
                              General::sanitize($this->prepareReadableValue($data, $entry_id)) :
                              $this->prepareReadableValue($data, $entry_id))));
    }

    /**
     * The default method for constructing the example form markup containing this
     * field when utilized as part of an event. This displays in the event documentation
     * and serves as a basic guide for how markup should be constructed on the
     * `Frontend` to save this field
     *
     * @throws InvalidArgumentException
     * @return XMLElement
     *  a label widget containing the formatted field element name of this.
     */
    public function getExampleFormMarkup()
    {
        $label = Widget::Label($this->get('label'));
        $label = Widget::Label(/** @scrutinizer ignore-type */ $this->get('label'));
        $label->appendChild(Widget::Input('fields['.$this->get('element_name').']'));
        $label->appendChild(Widget::Input('fields['./** @scrutinizer ignore-type */ $this->get('element_name').']'));

        return $label;
    }

    /**
     * Commit the settings of this field from the section editor to
     * create an instance of this field in a section.
     *
     * @return boolean
     *  true if the commit was successful, false otherwise.
     */
    public function commit()
    {
        $fields = array();

        $fields['label'] = General::sanitize($this->get('label'));
        $fields['label'] = General::sanitize(/** @scrutinizer ignore-type */ $this->get('label'));
        $fields['element_name'] = ($this->get('element_name') ? $this->get('element_name') : Lang::createHandle($this->get('label')));
        $fields['element_name'] = ($this->get('element_name') ? $this->get('element_name') : Lang::createHandle(/** @scrutinizer ignore-type */ $this->get('label')));
        $fields['parent_section'] = $this->get('parent_section');
        $fields['location'] = $this->get('location');
        $fields['required'] = $this->get('required');
        $fields['type'] = $this->_handle;
        $fields['show_column'] = $this->get('show_column');
        $fields['sortorder'] = (string)$this->get('sortorder');

        if ($id = $this->get('id')) {
            return FieldManager::edit($id, $fields);
            return FieldManager::edit(/** @scrutinizer ignore-type */ $id, $fields);
        } elseif ($id = FieldManager::add($fields)) {
            $this->set('id', $id);
            if ($this->requiresTable()) {
                return $this->createTable();
            }
            return true;
        }

        return false;
    }

    /**
     * The default field table construction method. This constructs the bare
     * minimum set of columns for a valid field table. Subclasses are expected
     * to overload this method to create a table structure that contains
     * additional columns to store the specific data created by the field.
     *
     * @throws DatabaseException
     * @see Field::requiresTable()
     * @return boolean
     */
    public function createTable()
    {
        return Symphony::Database()
            ->create('tbl_entries_data_' . General::intval($this->get('id')))
            ->ifNotExists()
            ->fields([
                'id' => [
                    'type' => 'int(11)',
                    'auto' => true,
                ],
                'entry_id' => 'int(11)',
                'value' => [
                    'type' => 'varchar(255)',
                    'null' => true,
                ],
            ])
            ->keys([
                'id' => 'primary',
                'entry_id' => 'key',
                'value' => 'key',
            ])
            ->execute()
            ->success();
    }

    /**
     * Tells Symphony that this field needs a table in order to store
     * data for each of its entries. Used when adding/deleting this field in a section
     * or entries are edited/added, data as a performance optimization.
     * It defaults to true, which force table creation.
     *
     * Developers are encouraged to update their null create table implementation
     * with this method.
     *
     * @since Symphony 2.7.0
     * @see Field::createTable()
     * @return boolean
     *  true if Symphony should call `createTable()`
     */
    public function requiresTable()
    {
        return true;
    }

    /**
     * Checks that we are working with a valid field handle and
     * that the setting table exists.
     *
     * @since Symphony 2.7.0
     * @return boolean
     *   true if the table exists, false otherwise
     */
    public function tableExists()
    {
        if (!$this->_handle) {
            return false;
        }
        return Symphony::Database()->tableExists('tbl_fields_' . $this->_handle);
    }

    /**
     * Checks that we are working with a valid field handle and field id, and
     * checks that the field record exists in the settings table.
     *
     * @since Symphony 2.7.1 It does check if the settings table only contains
     *   default columns and assume those fields do not require a record in the settings table.
     *   When this situation is detected the field is considered as valid even if no records were
     *   found in the settings table.
     *
     * @since Symphony 2.7.0
     * @see Field::tableExists()
     * @return boolean
     *   true if the field id exists in the table, false otherwise
     */
    public function exists()
    {
        if (!$this->get('id') || !$this->_handle) {
            return false;
        }
        $row = Symphony::Database()
            ->select(['id'])
            ->from('tbl_fields_' . $this->_handle)
            ->where(['field_id' => $this->get('id')])
            ->execute()
            ->rows();

        if (empty($row)) {
            // Some fields do not create any records in their settings table because they do not
            // implement a proper `Field::commit()` method.
            // The base implementation of the commit function only deals with the "core"
            // `tbl_fields` table.
            // The problem with this approach is that it can lead to data corruption when
            // saving a field that got deleted by another user.
            // The only way a field can live without a commit method is if it does not store any
            // settings at all.
            // But current version of Symphony assume that the `tbl_fields_$handle` table exists
            // with at least a `id` and `field_id` column, so field are required to at least create
            // the table to make their field work without SQL errors from the core.
            $columns = Symphony::Database()
                ->describe('tbl_fields_' . $this->_handle)
                ->execute()
                ->column('Field');

            // The table only has the two required columns, tolerate the missing record
            $isDefault = count($columns) === 2 &&
                in_array('id', $columns) &&
                in_array('field_id', $columns);
            if ($isDefault) {
                Symphony::Log()->pushDeprecateWarningToLog($this->_handle, get_class($this), array(
                    'message-format' => __('The field `%1$s` does not create settings records in the `tbl_fields_%1$s`.'),
                    'alternative-format' => __('Please implement the commit function in class `%s`.'),
                    'removal-format' => __('The compatibility check will will be removed in Symphony %s.'),
                    'removal-version' => '4.0.0',
                ));
            }
            return $isDefault;
        }
        return true;
    }

    /**
     * Remove the entry data of this field from the database.
     *
     * @param integer|array $entry_id
     *    the ID of the entry, or an array of entry ID's to delete.
     * @param array $data (optional)
     *    The entry data provided for fields to do additional cleanup
     *  This is an optional argument and defaults to null.
     * @throws DatabaseException
     * @return boolean
     *    Returns true after the cleanup has been completed
     */
    public function entryDataCleanup($entry_id, $data = null)
    {
        if (!is_array($entry_id)) {
            $entry_id = [$entry_id];
        }
        return Symphony::Database()
        return /** @scrutinizer ignore-deprecated */ Symphony::Database()
            ->delete('tbl_entries_data_' . $this->get('id'))
            ->delete('tbl_entries_data_' . /** @scrutinizer ignore-type */ $this->get('id'))
            ->where(['entry_id' => ['in' => $entry_id]])
            ->execute()
            ->success();
    }

    /**
     * Accessor to the associated entry search value for this field
     * instance. This default implementation simply returns `$data`
     *
     * @param array $data
     *  the data from which to construct the associated search entry value, this is usually
     *  Entry with the `$parent_entry_id` value's data.
     * @param integer $field_id (optional)
     *  the ID of the field that is the parent in the relationship
     * @param integer $parent_entry_id (optional)
     *  the ID of the entry from the parent section in the relationship
     * @return array|string
     *  Defaults to returning `$data`, but overriding implementation should return
     *  a string
     */
    public function fetchAssociatedEntrySearchValue($data, $field_id = null, $parent_entry_id = null)
    public function fetchAssociatedEntrySearchValue($data, /** @scrutinizer ignore-unused */ $field_id = null, $parent_entry_id = null)
    {
        return $data;
    }

    /**
     * Fetch the count of the associated entries given a `$value`.
     *
     * @see toolkit.Field#fetchAssociatedEntrySearchValue()
     * @param mixed $value
     *  the value to find the associated entry count for, this usually comes from
     *  the `fetchAssociatedEntrySearchValue` function.
     * @return void|integer
     *  this default implementation returns void. overriding implementations should
     *  return an integer.
     */
    public function fetchAssociatedEntryCount($value)
    {
    }

    /**
     * Find related entries from a linking field's data table. Default implementation uses
     * column names `entry_id` and `relation_id` as with the Select Box Link
     *
     * @since Symphony 2.5.0
     *
     * @param  integer $entry_id
     * @param  integer $parent_field_id
     * @return array
     */
    public function findRelatedEntries($entry_id, $parent_field_id)
    public function findRelatedEntries($entry_id, /** @scrutinizer ignore-unused */ $parent_field_id)
    {
        try {
            $ids = Symphony::Database()
                ->select(['entry_id'])
                ->from('tbl_entries_data_' . $this->get('id'))
                ->from('tbl_entries_data_' . /** @scrutinizer ignore-type */ $this->get('id'))
                ->where(['relation_id' => General::intval($entry_id)])
                ->where(['entry_id' => ['!=' => null]])
                ->execute()
                ->column('entry_id');
        } catch (Exception $e) {
            return [];
        }

        return $ids;
    }

    /**
     * Find related entries for the current field. Default implementation uses
     * column names `entry_id` and `relation_id` as with the Select Box Link
     *
     * @since Symphony 2.5.0
     *
     * @param  integer $parent_field_id
     * @param  integer $entry_id
     * @return array
     */
    public function findParentRelatedEntries($parent_field_id, $entry_id)
    public function findParentRelatedEntries(/** @scrutinizer ignore-unused */ $parent_field_id, $entry_id)
    {
        try {
            $ids = Symphony::Database()
                ->select(['relation_id'])
                ->from('tbl_entries_data_' . $this->get('id'))
                ->from('tbl_entries_data_' . /** @scrutinizer ignore-type */ $this->get('id'))
                ->where(['entry_id' => General::intval($entry_id)])
                ->where(['relation_id' => ['!=' => null]])
                ->execute()
                ->column('relation_id');
        } catch (Exception $e) {
            return [];
        }

        return $ids;
    }
}

symphonycms / symphony-2

GitHub Access Token became invalid

Pull Request — master (#2835)

Field::setArray() A

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like
