class-gv-field.php

Go to the documentation of this file.

<?php
namespace GV;

/** If this file is called directly, abort. */
if ( ! defined( 'GRAVITYVIEW_DIR' ) ) {
    die();
}

/**
 * The default GravityView Field class.
 *
 * Houses all base Field functionality.
 */
class Field {

    /**
     * @var array The custom View configuration for this field.
     *
     * Everything else is in the properties.
     */
    private $configuration = array();

    /**
     * @var string The field position in the view.
     * @api
     * @since 2.0
     */
    public $position = '';

    /**
     * @var string UID for this field.
     *
     * A unique relation identifier between this field and a view.
     *
     * @api
     * @since 2.0
     */
    public $UID = '';

    /**
     * @var string The form field ID for this field.
     * @api
     * @since 2.0
     */
    public $ID = '';

    /**
     * @var string The form label for this field.
     * @api
     * @since 2.0
     */
    public $label = '';

    /**
     * @var string The custom label for this field.
     * @api
     * @since 2.0
     */
    public $custom_label = '';

    /**
     * @var bool Whether to show the label or not for this field.
     * @api
     * @since 2.0
     */
    public $show_label = true;

    /**
     * @var string The custom class for this field.
     * @api
     * @since 2.0
     */
    public $custom_class = '';

    /**
     * @var string The capability required to view this field.
     *
     * If empty, anyone can view it, including non-logged in users.
     *
     * @api
     * @since 2.0
     */
    public $cap = '';

    /**
     * @var bool Show as a link to entry.
     *
     * @api
     * @since 2.0
     */
    public $show_as_link = false;

    /**
     * @var bool Filter this field from searching.
     *
     * @api
     * @since 2.0
     */
    public $search_filter = false;

    /**
     * Return an array of the old format as used by callers of `GVCommon:get_directory_fields()` for example.
     *
     *          'id' => string '9' (length=1)
     *          'label' => string 'Screenshots' (length=11)
     *          'show_label' => string '1' (length=1)
     *          'custom_label' => string '' (length=0)
     *          'custom_class' => string 'gv-gallery' (length=10)
     *          'only_loggedin' => string '0' (length=1)
     *          'only_loggedin_cap' => string 'read' (length=4)
     *          'search_filter' => string '0'
     *          'show_as_link' => string '0'
     *
     *          + whatever else specific field types may have
     *
     * @internal
     * @since 2.0
     *
     * @return array
     */
    public function as_configuration() {
        return array_merge( array(
            'id' => $this->ID,
            'label' => $this->label,
            'show_label' => $this->show_label ? '1' : '0',
            'custom_label' => $this->custom_label,
            'custom_class' => $this->custom_class,
            'only_loggedin' => $this->cap ? '1' : '0',
            'only_loggedin_cap' => $this->cap,
            'search_filter' => $this->search_filter ? '1' : '0',
            'show_as_link' => $this->show_as_link ? '1' : '0',
        ), $this->configuration );
    }

    /**
     * An alias for \GV\Source::get_field()
     *
     * @see \GV\Source::get_field()
     * @param string $source A \GV\Source class as string this field is tied to.
     * @param array $args The arguments required for the backend to fetch the field (usually just the ID).
     *
     * @return \GV\Field|null A \GV\Field instance or null if not found.
     */
    final public static function get( $source, $args ) {
        if ( ! is_string( $source ) || ! class_exists( $source ) ) {
            gravityview()->log->error( '{source} class not found', array( 'source' => $source ) );
            return null;
        }

        if ( ! method_exists( $source, 'get_field' ) ) {
            gravityview()->log->error( '{source} does not appear to be a valid \GV\Source subclass (get_field method missing)', array( 'source' => $source ) );
            return null;
        }

        return call_user_func_array( array( $source, 'get_field' ), is_array( $args ) ? $args : array( $args ) );
    }

    /**
     * Create self from a configuration array.
     *
     * @param array $configuration The configuration array.
     * @see \GV\Field::as_configuration()
     * @internal
     * @since 2.0
     *
     * @return \GV\Field The field implementation from configuration (\GV\GF_Field, \GV\Internal_Field).
     */
    public static function from_configuration( $configuration ) {
        if ( empty( $configuration['id'] ) ) {
            $field = new self();
            gravityview()->log->error( 'Trying to get field from configuration without a field ID.', array( 'data' => $configuration ) );
            $field->update_configuration( $configuration );
            return $field;
        }

        /** Prevent infinte loops here from unimplemented children. */
        if ( version_compare( phpversion(), '5.4', '>=' ) ) {
            $trace = debug_backtrace( DEBUG_BACKTRACE_IGNORE_ARGS, 2 );
        } else {
            $trace = debug_backtrace( DEBUG_BACKTRACE_IGNORE_ARGS );
        }
        $trace = $trace[1];
        if ( $trace['function'] == 'from_configuration' && $trace['class'] == __CLASS__ ) {
            $field = new self();
            gravityview()->log->error( 'Infinite loop protection tripped. Returning default class here.' );
            $field->update_configuration( $configuration );
            return $field;
        }

        /** @type \GV\GF_Field|\GV\Internal_Field $field_class Determine the field implementation to use, and try to use. */
        $field_class = is_numeric( $configuration['id'] ) ? '\GV\GF_Field' : '\GV\Internal_Field';

        /**
         * @filter `gravityview/field/class` Filter the field class about to be created from the configuration.
         * @param string $field_class The field class about to be used.
         * @param array $configuration The configuration as per \GV\Field::as_configuration()
         */
        $field_class = apply_filters( 'gravityview/field/class', $field_class, $configuration );

        if ( ! class_exists( $field_class ) || ! method_exists( $field_class, 'from_configuration' ) ) {
            $field = new self();
            gravityview()->log->error( 'Class {field_class}::from_configuration does not exist.', array( 'field_class' => $field_class, 'data' => $configuration ) );
            $field->update_configuration( $configuration );
            return $field;
        }

        /** @type \GV\GF_Field|\GV\Internal_Field $field */
        $field = $field_class::from_configuration( $configuration );

        if ( ! $field ) {
            $field = new self();
            gravityview()->log->error( 'Could not configure {field_class} with given configuration.', array( 'field_class' => __CLASS__, 'data' => $configuration ) );
            $field->update_configuration( $configuration );
        }

        return $field;
    }

    /**
     * Update configuration.
     *
     * @param array $configuration The configuration array.
     * @see \GV\Field::as_configuration()
     * @since 2.0
     *
     * @return void
     */
    public function update_configuration( $configuration ) {
        $configuration = wp_parse_args( $configuration, $this->as_configuration() );

        if ( $this->ID != $configuration['id'] ) {
            /** Smelling trouble here... */
            gravityview()->log->warning( 'ID is being changed for {field_class} instance, but implementation is not. Use ::from_configuration instead', array( 'field_class', __CLASS__ ) );
        }

        $this->ID = $configuration['id'];
        $this->label = $configuration['label'];
        $this->show_label = $configuration['show_label'] == '1';
        $this->custom_label = $configuration['custom_label'];
        $this->custom_class = $configuration['custom_class'];
        $this->cap = $configuration['only_loggedin'] == '1' ? $configuration['only_loggedin_cap'] : '';
        $this->search_filter = $configuration['search_filter'] == '1';
        $this->show_as_link = $configuration['show_as_link'] == '1';

        /** Shared among all field types (sort of). */
        $shared_configuration_keys = array(
            'id', 'label', 'show_label', 'custom_label', 'custom_class',
            'only_loggedin' ,'only_loggedin_cap', 'search_filter', 'show_as_link',
        );

        /** Everything else goes into the properties for now. @todo subclasses! */
        foreach ( $configuration as $key => $value ) {
            if ( ! in_array( $key, $shared_configuration_keys ) ) {
                $this->configuration[ $key ] = $value;
            }
        }
    }

    /**
     * Retrieve the label for this field.
     *
     * @param \GV\View $view The view for this context if applicable.
     * @param \GV\Source $source The source (form) for this context if applicable.
     * @param \GV\Entry $entry The entry for this context if applicable.
     * @param \GV\Request $request The request for this context if applicable.
     *
     * @return string The label for this field. Nothing here.
     */
    public function get_label( View $view = null, Source $source = null, Entry $entry = null, Request $request = null ) {

        if ( ! $this->show_label ) {
            return '';
        }

        /** A custom label is available. */
        if ( ! empty( $this->custom_label ) ) {
            return \GravityView_API::replace_variables( $this->custom_label, $source ? $source->form ? : null : null, $entry ? $entry->as_entry() : null );
        }

        return '';
    }

    /**
     * Retrieve the value for this field.
     *
     * Returns null in this implementation (or, rather, lack thereof).
     *
     * @param \GV\View $view The view for this context if applicable.
     * @param \GV\Source $source The source (form) for this context if applicable.
     * @param \GV\Entry $entry The entry for this context if applicable.
     * @param \GV\Request $request The request for this context if applicable.
     *
     * @return mixed The value for this field.
     */
    public function get_value( View $view = null, Source $source = null, Entry $entry = null, Request $request = null ) {
        return $this->get_value_filters( null, $view, $source, $entry, $request );
    }

    /**
     * Apply all the required filters after get_value() was called.
     *
     * @param mixed $value The value that will be filtered.
     * @param \GV\View $view The view for this context if applicable.
     * @param \GV\Source $source The source (form) for this context if applicable.
     * @param \GV\Entry $entry The entry for this context if applicable.
     * @param \GV\Request $request The request for this context if applicable.
     *
     * This is in its own function since \GV\Field subclasses have to call it.
     */
    protected function get_value_filters( $value, View $view = null, Source $source = null, Entry $entry = null, Request $request = null ) {
        if ( $this->type ) {
            /**
             * @filter `gravityview/field/$type/value` Override the displayed value here.
             * @param string $value The value.
             * @param \GV\Field The field we're doing this for.
             * @param \GV\View $view The view for this context if applicable.
             * @param \GV\Source $source The source (form) for this context if applicable.
             * @param \GV\Entry $entry The entry for this context if applicable.
             * @param \GV\Request $request The request for this context if applicable.
             */
            $value = apply_filters( "gravityview/field/{$this->type}/value", $value, $this, $view, $source, $entry, $request );
        }

        /**
         * @filter `gravityview/field/value` Override the displayed value here.
         * @param string $value The value.
         * @param \GV\Field The field we're doing this for.
         * @param \GV\View $view The view for this context if applicable.
         * @param \GV\Source $source The source (form) for this context if applicable.
         * @param \GV\Entry $entry The entry for this context if applicable.
         * @param \GV\Request $request The request for this context if applicable.
         */
        return apply_filters( 'gravityview/field/value', $value, $this, $view, $source, $entry, $request );
    }

    /**
     * Whether or not this field is visible.
     *
     * @param \GV\View|null Is visible where exactly?
     * @since develop
     *
     * @return bool
     */
    public function is_visible( $view = null ) {
        /**
         * @filter `gravityview/field/is_visible` Should this field be visible?
         *
         * @param boolean $visible Visible or not, defaults to the set field capability requirement if defined.
         * @param \GV\Field $field The field we're looking at.
         * @param \GV\View|null A context view. Since @develop
         */
        return apply_filters( 'gravityview/field/is_visible', ( ! $this->cap || \GVCommon::has_cap( $this->cap ) ), $this, $view );
    }

    /**
     * Get one of the extra configuration keys via property accessors.
     *
     * @param string $key The key to get.
     *
     * @return mixed|null The value for the given configuration key, null if doesn't exist.
     */
    public function __get( $key ) {
        switch( $key ) {
            default:
                if ( isset( $this->configuration[ $key ] ) ) {
                    return $this->configuration[ $key ];
                }
        }

        return null;
    }

    /**
     * Is this set?
     *
     * @param string $key The key to get.
     *
     * @return boolean Whether this $key is set or not.
     */
    public function __isset( $key ) {
        switch( $key ) {
            default:
                return isset( $this->configuration[ $key ] );
        }
    }
}