eventespresso / event-espresso-core

modules/add_new_state/EED_Add_New_State.module.php

Indentation +814 added lines, -814 removed lines

@@ -17,818 +17,818 @@
 {
 
 
-    /**
-     * @return EED_Module|EED_Add_New_State
-     */
-    public static function instance()
-    {
-        return parent::get_instance(__CLASS__);
-    }
-
-
-    /**
-     * set_hooks - for hooking into EE Core, other modules, etc
-     *
-     * @return void
-     */
-    public static function set_hooks()
-    {
-        add_action('wp_loaded', array('EED_Add_New_State', 'set_definitions'), 2);
-        add_action('wp_enqueue_scripts', array('EED_Add_New_State', 'translate_js_strings'), 0);
-        add_action('wp_enqueue_scripts', array('EED_Add_New_State', 'wp_enqueue_scripts'), 10);
-        add_filter(
-            'FHEE__EE_SPCO_Reg_Step_Attendee_Information___question_group_reg_form__question_group_reg_form',
-            array('EED_Add_New_State', 'display_add_new_state_micro_form'),
-            1,
-            1
-        );
-        add_filter(
-            'FHEE__EE_SPCO_Reg_Step_Payment_Options___get_billing_form_for_payment_method__billing_form',
-            array('EED_Add_New_State', 'display_add_new_state_micro_form'),
-            1,
-            1
-        );
-        add_filter(
-            'FHEE__EE_Single_Page_Checkout__process_attendee_information__valid_data_line_item',
-            array('EED_Add_New_State', 'unset_new_state_request_params'),
-            10,
-            1
-        );
-        add_filter(
-            'FHEE__EE_SPCO_Reg_Step_Attendee_Information___generate_question_input__state_options',
-            array('EED_Add_New_State', 'inject_new_reg_state_into_options'),
-            10,
-            5
-        );
-        add_filter(
-            'FHEE__EE_SPCO_Reg_Step_Attendee_Information___generate_question_input__country_options',
-            array('EED_Add_New_State', 'inject_new_reg_country_into_options'),
-            10,
-            5
-        );
-        add_filter(
-            'FHEE__EE_State_Select_Input____construct__state_options',
-            array('EED_Add_New_State', 'state_options'),
-            10,
-            1
-        );
-        add_filter(
-            'FHEE__EE_Country_Select_Input____construct__country_options',
-            array('EED_Add_New_State', 'country_options'),
-            10,
-            1
-        );
-    }
-
-
-    /**
-     * set_hooks_admin - for hooking into EE Admin Core, other modules, etc
-     *
-     * @return void
-     */
-    public static function set_hooks_admin()
-    {
-        add_action('wp_loaded', array('EED_Add_New_State', 'set_definitions'), 2);
-        add_filter(
-            'FHEE__EE_SPCO_Reg_Step_Attendee_Information___question_group_reg_form__question_group_reg_form',
-            array('EED_Add_New_State', 'display_add_new_state_micro_form'),
-            1,
-            1
-        );
-        add_filter(
-            'FHEE__EE_SPCO_Reg_Step_Payment_Options___get_billing_form_for_payment_method__billing_form',
-            array('EED_Add_New_State', 'display_add_new_state_micro_form'),
-            1,
-            1
-        );
-        add_action('wp_ajax_espresso_add_new_state', array('EED_Add_New_State', 'add_new_state'));
-        add_action('wp_ajax_nopriv_espresso_add_new_state', array('EED_Add_New_State', 'add_new_state'));
-        add_filter(
-            'FHEE__EE_Single_Page_Checkout__process_attendee_information__valid_data_line_item',
-            array('EED_Add_New_State', 'unset_new_state_request_params'),
-            10,
-            1
-        );
-        add_action(
-            'AHEE__General_Settings_Admin_Page__update_country_settings__state_saved',
-            array('EED_Add_New_State', 'update_country_settings'),
-            10,
-            3
-        );
-        add_action(
-            'AHEE__General_Settings_Admin_Page__delete_state__state_deleted',
-            array('EED_Add_New_State', 'update_country_settings'),
-            10,
-            3
-        );
-        add_filter(
-            'FHEE__EE_State_Select_Input____construct__state_options',
-            array('EED_Add_New_State', 'state_options'),
-            10,
-            1
-        );
-        add_filter(
-            'FHEE__EE_Country_Select_Input____construct__country_options',
-            array('EED_Add_New_State', 'country_options'),
-            10,
-            1
-        );
-        add_filter(
-            'FHEE__EE_Form_Section_Proper__receive_form_submission__request_data',
-            array('EED_Add_New_State', 'filter_checkout_request_params'),
-            10,
-            1
-        );
-        add_filter(
-            'FHEE__EE_SPCO_Reg_Step_Attendee_Information___generate_question_input__state_options',
-            array('EED_Add_New_State', 'inject_new_reg_state_into_options'),
-            10,
-            5
-        );
-        add_filter(
-            'FHEE__EE_SPCO_Reg_Step_Attendee_Information___generate_question_input__country_options',
-            array('EED_Add_New_State', 'inject_new_reg_country_into_options'),
-            10,
-            5
-        );
-    }
-
-
-    /**
-     * @return void
-     */
-    public static function set_definitions()
-    {
-        define('ANS_ASSETS_URL', plugin_dir_url(__FILE__) . 'assets' . DS);
-        define(
-            'ANS_TEMPLATES_PATH',
-            str_replace(
-                '\\',
-                DS,
-                plugin_dir_path(__FILE__)
-            ) . 'templates' . DS
-        );
-    }
-
-
-    /**
-     * @param WP $WP
-     * @return void
-     */
-    public function run($WP)
-    {
-    }
-
-
-    /**
-     * @return void
-     */
-    public static function translate_js_strings()
-    {
-        EE_Registry::$i18n_js_strings['ans_no_country'] = esc_html__(
-            'In order to proceed, you need to select the Country that your State/Province belongs to.',
-            'event_espresso'
-        );
-        EE_Registry::$i18n_js_strings['ans_no_name'] = esc_html__(
-            'In order to proceed, you need to enter the name of your State/Province.',
-            'event_espresso'
-        );
-        EE_Registry::$i18n_js_strings['ans_no_abbreviation'] = esc_html__(
-            'In order to proceed, you need to enter an abbreviation for the name of your State/Province.',
-            'event_espresso'
-        );
-        EE_Registry::$i18n_js_strings['ans_save_success'] = esc_html__(
-            'The new state was successfully saved to the database.',
-            'event_espresso'
-        );
-        EE_Registry::$i18n_js_strings['ans_server_save_error'] = esc_html__(
-            'An unknown error has occurred on the server while saving the new state to the database.',
-            'event_espresso'
-        );
-    }
-
-
-    /**
-     * @return void
-     */
-    public static function wp_enqueue_scripts()
-    {
-        if (apply_filters('EED_Single_Page_Checkout__SPCO_active', false)) {
-            wp_register_script(
-                'add_new_state',
-                ANS_ASSETS_URL . 'add_new_state.js',
-                array('espresso_core', 'single_page_checkout'),
-                EVENT_ESPRESSO_VERSION,
-                true
-            );
-            wp_enqueue_script('add_new_state');
-        }
-    }
-
-
-
-    /**
-     * display_add_new_state_micro_form
-     *
-     * @param EE_Form_Section_Proper $question_group_reg_form
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public static function display_add_new_state_micro_form(EE_Form_Section_Proper $question_group_reg_form)
-    {
-        // only add the 'new_state_micro_form' when displaying reg forms,
-        // not during processing since we process the 'new_state_micro_form' in it's own AJAX request
-        $action = EE_Registry::instance()->REQ->get('action', '');
-        // is the "state" question in this form section?
-        $input = $question_group_reg_form->get_subsection('state');
-        if ($action === 'process_reg_step' || $action === 'update_reg_step') {
-            // ok then all we need to do is make sure the input's HTML name is consistent
-            // by forcing it to set it now, like it did while getting the form for display
-            if ($input instanceof EE_State_Select_Input) {
-                $input->html_name();
-            }
-            return $question_group_reg_form;
-        }
-        // we're only doing this for state select inputs
-        if ($input instanceof EE_State_Select_Input
-            && ! $input->get_display_strategy() instanceof EE_Hidden_Display_Strategy
-        ) {
-            // grab any set values from the request
-            $country_name = str_replace('state', 'nsmf_new_state_country', $input->html_name());
-            $state_name = str_replace('state', 'nsmf_new_state_name', $input->html_name());
-            $abbrv_name = str_replace('state', 'nsmf_new_state_abbrv', $input->html_name());
-            $new_state_submit_id = str_replace('state', 'new_state', $input->html_id());
-            $country_options = array();
-            $countries = EEM_Country::instance()->get_all_countries();
-            if (! empty($countries)) {
-                foreach ($countries as $country) {
-                    if ($country instanceof EE_Country) {
-                        $country_options[ $country->ID() ] = $country->name();
-                    }
-                }
-            }
-            $new_state_micro_form = new EE_Form_Section_Proper(
-                array(
-                    'name'            => 'new_state_micro_form',
-                    'html_id'         => 'new_state_micro_form',
-                    'layout_strategy' => new EE_Div_Per_Section_Layout(),
-                    'subsections'     => array(
-                        // add hidden input to indicate that a new state is being added
-                        'add_new_state'               => new EE_Hidden_Input(
-                            array(
-                                'html_name' => str_replace(
-                                    'state',
-                                    'nsmf_add_new_state',
-                                    $input->html_name()
-                                ),
-                                'html_id'   => str_replace(
-                                    'state',
-                                    'nsmf_add_new_state',
-                                    $input->html_id()
-                                ),
-                                'default'   => 0,
-                            )
-                        ),
-                        // add link for displaying hidden container
-                        'click_here_link'             => new EE_Form_Section_HTML(
-                            apply_filters(
-                                'FHEE__EED_Add_New_State__display_add_new_state_micro_form__click_here_link',
-                                EEH_HTML::link(
-                                    '',
-                                    esc_html__('click here to add a new state/province', 'event_espresso'),
-                                    '',
-                                    'display-' . $input->html_id(),
-                                    'ee-form-add-new-state-lnk display-the-hidden smaller-text hide-if-no-js',
-                                    '',
-                                    'data-target="' . $input->html_id() . '"'
-                                )
-                            )
-                        ),
-                        // add initial html for hidden container
-                        'add_new_state_micro_form'    => new EE_Form_Section_HTML(
-                            apply_filters(
-                                'FHEE__EED_Add_New_State__display_add_new_state_micro_form__add_new_state_micro_form',
-                                EEH_HTML::div(
-                                    '',
-                                    $input->html_id() . '-dv',
-                                    'ee-form-add-new-state-dv',
-                                    'display: none;'
-                                ) .
-                                EEH_HTML::h6(
-                                    esc_html__(
-                                        'Is your state/province missing from the dropdown menu above? You can add it by completing the following steps:',
-                                        'event_espresso'
-                                    )
-                                ) .
-                                EEH_HTML::ul() .
-                                EEH_HTML::li(
-                                    esc_html__(
-                                        'first select the Country that your State/Province belongs to',
-                                        'event_espresso'
-                                    )
-                                ) .
-                                EEH_HTML::li(
-                                    esc_html__('enter the name of your State/Province', 'event_espresso')
-                                ) .
-                                EEH_HTML::li(
-                                    esc_html__(
-                                        'enter a two to six letter abbreviation for the name of your State/Province',
-                                        'event_espresso'
-                                    )
-                                ) .
-                                EEH_HTML::li(esc_html__('click the ADD button', 'event_espresso')) .
-                                EEH_HTML::ulx()
-                            )
-                        ),
-                        // NEW STATE COUNTRY
-                        'new_state_country'           => new EE_Country_Select_Input(
-                            $country_options,
-                            array(
-                                'html_name'       => $country_name,
-                                'html_id'         => str_replace(
-                                    'state',
-                                    'nsmf_new_state_country',
-                                    $input->html_id()
-                                ),
-                                'html_class'      => $input->html_class() . ' new-state-country',
-                                'html_label_text' => esc_html__('New State/Province Country', 'event_espresso'),
-                                'default'         => EE_Registry::instance()->REQ->get($country_name, ''),
-                                'required'        => false,
-                            )
-                        ),
-                        // NEW STATE NAME
-                        'new_state_name'              => new EE_Text_Input(
-                            array(
-                                'html_name'       => $state_name,
-                                'html_id'         => str_replace(
-                                    'state',
-                                    'nsmf_new_state_name',
-                                    $input->html_id()
-                                ),
-                                'html_class'      => $input->html_class() . ' new-state-state',
-                                'html_label_text' => esc_html__(
-                                    'New State/Province Name',
-                                    'event_espresso'
-                                ),
-                                'default'         => EE_Registry::instance()->REQ->get($state_name, ''),
-                                'required'        => false,
-                            )
-                        ),
-                        'spacer'                      => new EE_Form_Section_HTML(EEH_HTML::br()),
-                        // NEW STATE NAME
-                        'new_state_abbrv'             => new EE_Text_Input(
-                            array(
-                                'html_name'             => $abbrv_name,
-                                'html_id'               => str_replace(
-                                    'state',
-                                    'nsmf_new_state_abbrv',
-                                    $input->html_id()
-                                ),
-                                'html_class'            => $input->html_class() . ' new-state-abbrv',
-                                'html_label_text'       => esc_html__(
-                                    'New State/Province Abbreviation',
-                                    'event_espresso'
-                                ) . ' *',
-                                'html_other_attributes' => 'size="24"',
-                                'default'               => EE_Registry::instance()->REQ->get($abbrv_name, ''),
-                                'required'              => false,
-                            )
-                        ),
-                        // "submit" button
-                        'add_new_state_submit_button' => new EE_Form_Section_HTML(
-                            apply_filters(
-                                'FHEE__EED_Add_New_State__display_add_new_state_micro_form__add_new_state_submit_button',
-                                EEH_HTML::nbsp(3) .
-                                EEH_HTML::link(
-                                    '',
-                                    esc_html__('ADD', 'event_espresso'),
-                                    '',
-                                    'submit-' . $new_state_submit_id,
-                                    'ee-form-add-new-state-submit button button-secondary',
-                                    '',
-                                    'data-target="' . $new_state_submit_id . '" data-value-field-name="' . $input->valueFieldName(). '"'
-                                )
-                            )
-                        ),
-                        // extra info
-                        'add_new_state_extra'         => new EE_Form_Section_HTML(
-                            apply_filters(
-                                'FHEE__EED_Add_New_State__display_add_new_state_micro_form__add_new_state_extra',
-                                EEH_HTML::br(2)
-                                .
-                                EEH_HTML::div('', '', 'small-text')
-                                .
-                                EEH_HTML::strong(
-                                    '* ' .
-                                    esc_html__(
-                                        'Don\'t know your State/Province Abbreviation?',
-                                        'event_espresso'
-                                    )
-                                )
-                                .
-                                EEH_HTML::br()
-                                .
-                                sprintf(
-                                    esc_html__(
-                                        'You can look here: %s, for a list of Countries and links to their State/Province Abbreviations ("Subdivisions assigned codes" column).',
-                                        'event_espresso'
-                                    ),
-                                    EEH_HTML::link(
-                                        'http://en.wikipedia.org/wiki/ISO_3166-2',
-                                        'http://en.wikipedia.org/wiki/ISO_3166-2',
-                                        '',
-                                        '',
-                                        'ee-form-add-new-state-wiki-lnk',
-                                        '',
-                                        'target="_blank"'
-                                    )
-                                )
-                                .
-                                EEH_HTML::divx()
-                                .
-                                EEH_HTML::br()
-                                .
-                                EEH_HTML::link(
-                                    '',
-                                    esc_html__('cancel new State/Province', 'event_espresso'),
-                                    '',
-                                    'hide-' . $input->html_id(),
-                                    'ee-form-cancel-new-state-lnk smaller-text',
-                                    '',
-                                    'data-target="' . $input->html_id() . '"'
-                                )
-                                .
-                                EEH_HTML::divx()
-                                .
-                                EEH_HTML::br()
-                            )
-                        ),
-                    ),
-                )
-            );
-            $question_group_reg_form->add_subsections(
-                array('new_state_micro_form' => $new_state_micro_form),
-                'state',
-                false
-            );
-        }
-        return $question_group_reg_form;
-    }
-
-
-    /**
-     * set_new_state_input_width
-     *
-     * @return int|string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function add_new_state()
-    {
-        $REQ = EE_Registry::instance()->load_core('Request_Handler');
-        if (absint($REQ->get('nsmf_add_new_state')) === 1) {
-            EE_Registry::instance()->load_model('State');
-            // grab country ISO code, new state name, and new state abbreviation
-            $state_country = $REQ->is_set('nsmf_new_state_country')
-                ? sanitize_text_field($REQ->get('nsmf_new_state_country'))
-                : false;
-            $state_name = $REQ->is_set('nsmf_new_state_name')
-                ? sanitize_text_field($REQ->get('nsmf_new_state_name'))
-                : false;
-            $state_abbr = $REQ->is_set('nsmf_new_state_abbrv')
-                ? sanitize_text_field($REQ->get('nsmf_new_state_abbrv'))
-                : false;
-            if ($state_country && $state_name && $state_abbr) {
-                $new_state = EED_Add_New_State::save_new_state_to_db(
-                    array(
-                        'CNT_ISO'    => strtoupper($state_country),
-                        'STA_abbrev' => strtoupper($state_abbr),
-                        'STA_name'   => ucwords($state_name),
-                        'STA_active' => false,
-                    )
-                );
-                if ($new_state instanceof EE_State) {
-                    // clean house
-                    EE_Registry::instance()->REQ->un_set('nsmf_add_new_state');
-                    EE_Registry::instance()->REQ->un_set('nsmf_new_state_country');
-                    EE_Registry::instance()->REQ->un_set('nsmf_new_state_name');
-                    EE_Registry::instance()->REQ->un_set('nsmf_new_state_abbrv');
-                    // get any existing new states
-                    $new_states = EE_Registry::instance()->SSN->get_session_data(
-                        'nsmf_new_states'
-                    );
-                    $new_states[ $new_state->ID() ] = $new_state;
-                    EE_Registry::instance()->SSN->set_session_data(
-                        array('nsmf_new_states' => $new_states)
-                    );
-                    if (EE_Registry::instance()->REQ->ajax) {
-                        echo wp_json_encode(
-                            array(
-                                'success'      => true,
-                                'id'           => $new_state->ID(),
-                                'name'         => $new_state->name(),
-                                'abbrev'       => $new_state->abbrev(),
-                                'country_iso'  => $new_state->country_iso(),
-                                'country_name' => $new_state->country()->name(),
-                            )
-                        );
-                        exit();
-                    }
-                    return $new_state->ID();
-                }
-            } else {
-                $error = esc_html__(
-                    'A new State/Province could not be added because invalid or missing data was received.',
-                    'event_espresso'
-                );
-                if (EE_Registry::instance()->REQ->ajax) {
-                    echo wp_json_encode(array('error' => $error));
-                    exit();
-                }
-                EE_Error::add_error($error, __FILE__, __FUNCTION__, __LINE__);
-            }
-        }
-        return false;
-    }
-
-
-    /**
-     * recursively drills down through request params to remove any that were added by this module
-     *
-     * @param array $request_params
-     * @return array
-     */
-    public static function filter_checkout_request_params($request_params)
-    {
-        foreach ($request_params as $form_section) {
-            if (is_array($form_section)) {
-                EED_Add_New_State::unset_new_state_request_params($form_section);
-                EED_Add_New_State::filter_checkout_request_params($form_section);
-            }
-        }
-        return $request_params;
-    }
-
-
-    /**
-     * @param array $request_params
-     * @return array
-     */
-    public static function unset_new_state_request_params($request_params)
-    {
-        unset(
-            $request_params['new_state_micro_form'],
-            $request_params['new_state_micro_add_new_state'],
-            $request_params['new_state_micro_new_state_country'],
-            $request_params['new_state_micro_new_state_name'],
-            $request_params['new_state_micro_new_state_abbrv']
-        );
-        return $request_params;
-    }
-
-
-    /**
-     * @param array $props_n_values
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public static function save_new_state_to_db($props_n_values = array())
-    {
-        $existing_state = EEM_State::instance()->get_all(array($props_n_values, 'limit' => 1));
-        if (! empty($existing_state)) {
-            return array_pop($existing_state);
-        }
-        $new_state = EE_State::new_instance($props_n_values);
-        if ($new_state instanceof EE_State) {
-            $country_settings_url = add_query_arg(
-                array(
-                    'page'    => 'espresso_general_settings',
-                    'action'  => 'country_settings',
-                    'country' => $new_state->country_iso(),
-                ),
-                admin_url('admin.php')
-            );
-            // if not non-ajax admin
-            new PersistentAdminNotice(
-                'new-state-added-' . $new_state->country_iso() . '-' . $new_state->abbrev(),
-                sprintf(
-                    esc_html__(
-                        'A new State named "%1$s (%2$s)" was dynamically added from an Event Espresso form for the Country of "%3$s".%5$sTo verify, edit, and/or delete this new State, please go to the %4$s and update the States / Provinces section.%5$sCheck "Yes" to have this new State added to dropdown select lists in forms.',
-                        'event_espresso'
-                    ),
-                    '<b>' . $new_state->name() . '</b>',
-                    '<b>' . $new_state->abbrev() . '</b>',
-                    '<b>' . $new_state->country()->name() . '</b>',
-                    '<a href="'
-                    . $country_settings_url
-                    . '">'
-                    . esc_html__(
-                        'Event Espresso - General Settings > Countries Tab',
-                        'event_espresso'
-                    )
-                    . '</a>',
-                    '<br />'
-                )
-            );
-            $new_state->save();
-            EEM_State::instance()->reset_cached_states();
-            return $new_state;
-        }
-        return false;
-    }
-
-
-    /**
-     * @param string $CNT_ISO
-     * @param string $STA_ID
-     * @param array  $cols_n_values
-     * @return void
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public static function update_country_settings($CNT_ISO = '', $STA_ID = '', $cols_n_values = array())
-    {
-        if (! $CNT_ISO) {
-            EE_Error::add_error(
-                esc_html__('An invalid or missing Country ISO Code was received.', 'event_espresso'),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-        }
-        $STA_abbrev = is_array($cols_n_values) && isset($cols_n_values['STA_abbrev']) ? $cols_n_values['STA_abbrev']
-            : false;
-        if (! $STA_abbrev && ! empty($STA_ID)) {
-            $state = EEM_State::instance()->get_one_by_ID($STA_ID);
-            if ($state instanceof EE_State) {
-                $STA_abbrev = $state->abbrev();
-            }
-        }
-        if (! $STA_abbrev) {
-            EE_Error::add_error(
-                esc_html__('An invalid or missing State Abbreviation was received.', 'event_espresso'),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-        }
-        /** @var PersistentAdminNoticeManager $persistent_admin_notice_manager */
-        $persistent_admin_notice_manager = LoaderFactory::getLoader()->getShared(
-            'EventEspresso\core\services\notifications\PersistentAdminNoticeManager'
-        );
-        $persistent_admin_notice_manager->dismissNotice($CNT_ISO . '-' . $STA_abbrev, true, true);
-    }
-
-
-    /**
-     * @param EE_State[]                            $state_options
-     * @param EE_SPCO_Reg_Step_Attendee_Information $reg_step
-     * @param EE_Registration                       $registration
-     * @param EE_Question                           $question
-     * @param                                       $answer
-     * @return array
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public static function inject_new_reg_state_into_options(
-        $state_options = array(),
-        EE_SPCO_Reg_Step_Attendee_Information $reg_step,
-        EE_Registration $registration,
-        EE_Question $question,
-        $answer
-    ) {
-        if ($answer instanceof EE_Answer && $question instanceof EE_Question
-            && $question->type() === EEM_Question::QST_type_state
-        ) {
-            $STA_ID = $answer->value();
-            if (! empty($STA_ID)) {
-                $state = EEM_State::instance()->get_one_by_ID($STA_ID);
-                if ($state instanceof EE_State) {
-                    $country = $state->country();
-                    if ($country instanceof EE_Country) {
-                        if (! isset($state_options[ $country->name() ])) {
-                            $state_options[ $country->name() ] = array();
-                        }
-                        if (! isset($state_options[ $country->name() ][ $STA_ID ])) {
-                            $state_options[ $country->name() ][ $STA_ID ] = $state->name();
-                        }
-                    }
-                }
-            }
-        }
-        return $state_options;
-    }
-
-
-    /**
-     * @param EE_Country[]                          $country_options
-     * @param EE_SPCO_Reg_Step_Attendee_Information $reg_step
-     * @param EE_Registration                       $registration
-     * @param EE_Question                           $question
-     * @param                                       $answer
-     * @return array
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public static function inject_new_reg_country_into_options(
-        $country_options = array(),
-        EE_SPCO_Reg_Step_Attendee_Information $reg_step,
-        EE_Registration $registration,
-        EE_Question $question,
-        $answer
-    ) {
-        if ($answer instanceof EE_Answer && $question instanceof EE_Question
-            && $question->type()
-               === EEM_Question::QST_type_country
-        ) {
-            $CNT_ISO = $answer->value();
-            if (! empty($CNT_ISO)) {
-                $country = EEM_Country::instance()->get_one_by_ID($CNT_ISO);
-                if ($country instanceof EE_Country) {
-                    if (! isset($country_options[ $CNT_ISO ])) {
-                        $country_options[ $CNT_ISO ] = $country->name();
-                    }
-                }
-            }
-        }
-        return $country_options;
-    }
-
-
-    /**
-     * @param EE_State[] $state_options
-     * @return array
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public static function state_options($state_options = array())
-    {
-        $new_states = EED_Add_New_State::_get_new_states();
-        foreach ($new_states as $new_state) {
-            if ($new_state instanceof EE_State
-                && $new_state->country() instanceof EE_Country
-            ) {
-                $state_options[ $new_state->country()->name() ][ $new_state->ID() ] = $new_state->name();
-            }
-        }
-        return $state_options;
-    }
-
-
-    /**
-     * @return array
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    protected static function _get_new_states()
-    {
-        $new_states = array();
-        if (EE_Registry::instance()->SSN instanceof EE_Session) {
-            $new_states = EE_Registry::instance()->SSN->get_session_data(
-                'nsmf_new_states'
-            );
-        }
-        return is_array($new_states) ? $new_states : array();
-    }
-
-
-    /**
-     * @param EE_Country[] $country_options
-     * @return array
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public static function country_options($country_options = array())
-    {
-        $new_states = EED_Add_New_State::_get_new_states();
-        foreach ($new_states as $new_state) {
-            if ($new_state instanceof EE_State
-                && $new_state->country() instanceof EE_Country
-            ) {
-                $country_options[ $new_state->country()->ID() ] = $new_state->country()->name();
-            }
-        }
-        return $country_options;
-    }
+	/**
+	 * @return EED_Module|EED_Add_New_State
+	 */
+	public static function instance()
+	{
+		return parent::get_instance(__CLASS__);
+	}
+
+
+	/**
+	 * set_hooks - for hooking into EE Core, other modules, etc
+	 *
+	 * @return void
+	 */
+	public static function set_hooks()
+	{
+		add_action('wp_loaded', array('EED_Add_New_State', 'set_definitions'), 2);
+		add_action('wp_enqueue_scripts', array('EED_Add_New_State', 'translate_js_strings'), 0);
+		add_action('wp_enqueue_scripts', array('EED_Add_New_State', 'wp_enqueue_scripts'), 10);
+		add_filter(
+			'FHEE__EE_SPCO_Reg_Step_Attendee_Information___question_group_reg_form__question_group_reg_form',
+			array('EED_Add_New_State', 'display_add_new_state_micro_form'),
+			1,
+			1
+		);
+		add_filter(
+			'FHEE__EE_SPCO_Reg_Step_Payment_Options___get_billing_form_for_payment_method__billing_form',
+			array('EED_Add_New_State', 'display_add_new_state_micro_form'),
+			1,
+			1
+		);
+		add_filter(
+			'FHEE__EE_Single_Page_Checkout__process_attendee_information__valid_data_line_item',
+			array('EED_Add_New_State', 'unset_new_state_request_params'),
+			10,
+			1
+		);
+		add_filter(
+			'FHEE__EE_SPCO_Reg_Step_Attendee_Information___generate_question_input__state_options',
+			array('EED_Add_New_State', 'inject_new_reg_state_into_options'),
+			10,
+			5
+		);
+		add_filter(
+			'FHEE__EE_SPCO_Reg_Step_Attendee_Information___generate_question_input__country_options',
+			array('EED_Add_New_State', 'inject_new_reg_country_into_options'),
+			10,
+			5
+		);
+		add_filter(
+			'FHEE__EE_State_Select_Input____construct__state_options',
+			array('EED_Add_New_State', 'state_options'),
+			10,
+			1
+		);
+		add_filter(
+			'FHEE__EE_Country_Select_Input____construct__country_options',
+			array('EED_Add_New_State', 'country_options'),
+			10,
+			1
+		);
+	}
+
+
+	/**
+	 * set_hooks_admin - for hooking into EE Admin Core, other modules, etc
+	 *
+	 * @return void
+	 */
+	public static function set_hooks_admin()
+	{
+		add_action('wp_loaded', array('EED_Add_New_State', 'set_definitions'), 2);
+		add_filter(
+			'FHEE__EE_SPCO_Reg_Step_Attendee_Information___question_group_reg_form__question_group_reg_form',
+			array('EED_Add_New_State', 'display_add_new_state_micro_form'),
+			1,
+			1
+		);
+		add_filter(
+			'FHEE__EE_SPCO_Reg_Step_Payment_Options___get_billing_form_for_payment_method__billing_form',
+			array('EED_Add_New_State', 'display_add_new_state_micro_form'),
+			1,
+			1
+		);
+		add_action('wp_ajax_espresso_add_new_state', array('EED_Add_New_State', 'add_new_state'));
+		add_action('wp_ajax_nopriv_espresso_add_new_state', array('EED_Add_New_State', 'add_new_state'));
+		add_filter(
+			'FHEE__EE_Single_Page_Checkout__process_attendee_information__valid_data_line_item',
+			array('EED_Add_New_State', 'unset_new_state_request_params'),
+			10,
+			1
+		);
+		add_action(
+			'AHEE__General_Settings_Admin_Page__update_country_settings__state_saved',
+			array('EED_Add_New_State', 'update_country_settings'),
+			10,
+			3
+		);
+		add_action(
+			'AHEE__General_Settings_Admin_Page__delete_state__state_deleted',
+			array('EED_Add_New_State', 'update_country_settings'),
+			10,
+			3
+		);
+		add_filter(
+			'FHEE__EE_State_Select_Input____construct__state_options',
+			array('EED_Add_New_State', 'state_options'),
+			10,
+			1
+		);
+		add_filter(
+			'FHEE__EE_Country_Select_Input____construct__country_options',
+			array('EED_Add_New_State', 'country_options'),
+			10,
+			1
+		);
+		add_filter(
+			'FHEE__EE_Form_Section_Proper__receive_form_submission__request_data',
+			array('EED_Add_New_State', 'filter_checkout_request_params'),
+			10,
+			1
+		);
+		add_filter(
+			'FHEE__EE_SPCO_Reg_Step_Attendee_Information___generate_question_input__state_options',
+			array('EED_Add_New_State', 'inject_new_reg_state_into_options'),
+			10,
+			5
+		);
+		add_filter(
+			'FHEE__EE_SPCO_Reg_Step_Attendee_Information___generate_question_input__country_options',
+			array('EED_Add_New_State', 'inject_new_reg_country_into_options'),
+			10,
+			5
+		);
+	}
+
+
+	/**
+	 * @return void
+	 */
+	public static function set_definitions()
+	{
+		define('ANS_ASSETS_URL', plugin_dir_url(__FILE__) . 'assets' . DS);
+		define(
+			'ANS_TEMPLATES_PATH',
+			str_replace(
+				'\\',
+				DS,
+				plugin_dir_path(__FILE__)
+			) . 'templates' . DS
+		);
+	}
+
+
+	/**
+	 * @param WP $WP
+	 * @return void
+	 */
+	public function run($WP)
+	{
+	}
+
+
+	/**
+	 * @return void
+	 */
+	public static function translate_js_strings()
+	{
+		EE_Registry::$i18n_js_strings['ans_no_country'] = esc_html__(
+			'In order to proceed, you need to select the Country that your State/Province belongs to.',
+			'event_espresso'
+		);
+		EE_Registry::$i18n_js_strings['ans_no_name'] = esc_html__(
+			'In order to proceed, you need to enter the name of your State/Province.',
+			'event_espresso'
+		);
+		EE_Registry::$i18n_js_strings['ans_no_abbreviation'] = esc_html__(
+			'In order to proceed, you need to enter an abbreviation for the name of your State/Province.',
+			'event_espresso'
+		);
+		EE_Registry::$i18n_js_strings['ans_save_success'] = esc_html__(
+			'The new state was successfully saved to the database.',
+			'event_espresso'
+		);
+		EE_Registry::$i18n_js_strings['ans_server_save_error'] = esc_html__(
+			'An unknown error has occurred on the server while saving the new state to the database.',
+			'event_espresso'
+		);
+	}
+
+
+	/**
+	 * @return void
+	 */
+	public static function wp_enqueue_scripts()
+	{
+		if (apply_filters('EED_Single_Page_Checkout__SPCO_active', false)) {
+			wp_register_script(
+				'add_new_state',
+				ANS_ASSETS_URL . 'add_new_state.js',
+				array('espresso_core', 'single_page_checkout'),
+				EVENT_ESPRESSO_VERSION,
+				true
+			);
+			wp_enqueue_script('add_new_state');
+		}
+	}
+
+
+
+	/**
+	 * display_add_new_state_micro_form
+	 *
+	 * @param EE_Form_Section_Proper $question_group_reg_form
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public static function display_add_new_state_micro_form(EE_Form_Section_Proper $question_group_reg_form)
+	{
+		// only add the 'new_state_micro_form' when displaying reg forms,
+		// not during processing since we process the 'new_state_micro_form' in it's own AJAX request
+		$action = EE_Registry::instance()->REQ->get('action', '');
+		// is the "state" question in this form section?
+		$input = $question_group_reg_form->get_subsection('state');
+		if ($action === 'process_reg_step' || $action === 'update_reg_step') {
+			// ok then all we need to do is make sure the input's HTML name is consistent
+			// by forcing it to set it now, like it did while getting the form for display
+			if ($input instanceof EE_State_Select_Input) {
+				$input->html_name();
+			}
+			return $question_group_reg_form;
+		}
+		// we're only doing this for state select inputs
+		if ($input instanceof EE_State_Select_Input
+			&& ! $input->get_display_strategy() instanceof EE_Hidden_Display_Strategy
+		) {
+			// grab any set values from the request
+			$country_name = str_replace('state', 'nsmf_new_state_country', $input->html_name());
+			$state_name = str_replace('state', 'nsmf_new_state_name', $input->html_name());
+			$abbrv_name = str_replace('state', 'nsmf_new_state_abbrv', $input->html_name());
+			$new_state_submit_id = str_replace('state', 'new_state', $input->html_id());
+			$country_options = array();
+			$countries = EEM_Country::instance()->get_all_countries();
+			if (! empty($countries)) {
+				foreach ($countries as $country) {
+					if ($country instanceof EE_Country) {
+						$country_options[ $country->ID() ] = $country->name();
+					}
+				}
+			}
+			$new_state_micro_form = new EE_Form_Section_Proper(
+				array(
+					'name'            => 'new_state_micro_form',
+					'html_id'         => 'new_state_micro_form',
+					'layout_strategy' => new EE_Div_Per_Section_Layout(),
+					'subsections'     => array(
+						// add hidden input to indicate that a new state is being added
+						'add_new_state'               => new EE_Hidden_Input(
+							array(
+								'html_name' => str_replace(
+									'state',
+									'nsmf_add_new_state',
+									$input->html_name()
+								),
+								'html_id'   => str_replace(
+									'state',
+									'nsmf_add_new_state',
+									$input->html_id()
+								),
+								'default'   => 0,
+							)
+						),
+						// add link for displaying hidden container
+						'click_here_link'             => new EE_Form_Section_HTML(
+							apply_filters(
+								'FHEE__EED_Add_New_State__display_add_new_state_micro_form__click_here_link',
+								EEH_HTML::link(
+									'',
+									esc_html__('click here to add a new state/province', 'event_espresso'),
+									'',
+									'display-' . $input->html_id(),
+									'ee-form-add-new-state-lnk display-the-hidden smaller-text hide-if-no-js',
+									'',
+									'data-target="' . $input->html_id() . '"'
+								)
+							)
+						),
+						// add initial html for hidden container
+						'add_new_state_micro_form'    => new EE_Form_Section_HTML(
+							apply_filters(
+								'FHEE__EED_Add_New_State__display_add_new_state_micro_form__add_new_state_micro_form',
+								EEH_HTML::div(
+									'',
+									$input->html_id() . '-dv',
+									'ee-form-add-new-state-dv',
+									'display: none;'
+								) .
+								EEH_HTML::h6(
+									esc_html__(
+										'Is your state/province missing from the dropdown menu above? You can add it by completing the following steps:',
+										'event_espresso'
+									)
+								) .
+								EEH_HTML::ul() .
+								EEH_HTML::li(
+									esc_html__(
+										'first select the Country that your State/Province belongs to',
+										'event_espresso'
+									)
+								) .
+								EEH_HTML::li(
+									esc_html__('enter the name of your State/Province', 'event_espresso')
+								) .
+								EEH_HTML::li(
+									esc_html__(
+										'enter a two to six letter abbreviation for the name of your State/Province',
+										'event_espresso'
+									)
+								) .
+								EEH_HTML::li(esc_html__('click the ADD button', 'event_espresso')) .
+								EEH_HTML::ulx()
+							)
+						),
+						// NEW STATE COUNTRY
+						'new_state_country'           => new EE_Country_Select_Input(
+							$country_options,
+							array(
+								'html_name'       => $country_name,
+								'html_id'         => str_replace(
+									'state',
+									'nsmf_new_state_country',
+									$input->html_id()
+								),
+								'html_class'      => $input->html_class() . ' new-state-country',
+								'html_label_text' => esc_html__('New State/Province Country', 'event_espresso'),
+								'default'         => EE_Registry::instance()->REQ->get($country_name, ''),
+								'required'        => false,
+							)
+						),
+						// NEW STATE NAME
+						'new_state_name'              => new EE_Text_Input(
+							array(
+								'html_name'       => $state_name,
+								'html_id'         => str_replace(
+									'state',
+									'nsmf_new_state_name',
+									$input->html_id()
+								),
+								'html_class'      => $input->html_class() . ' new-state-state',
+								'html_label_text' => esc_html__(
+									'New State/Province Name',
+									'event_espresso'
+								),
+								'default'         => EE_Registry::instance()->REQ->get($state_name, ''),
+								'required'        => false,
+							)
+						),
+						'spacer'                      => new EE_Form_Section_HTML(EEH_HTML::br()),
+						// NEW STATE NAME
+						'new_state_abbrv'             => new EE_Text_Input(
+							array(
+								'html_name'             => $abbrv_name,
+								'html_id'               => str_replace(
+									'state',
+									'nsmf_new_state_abbrv',
+									$input->html_id()
+								),
+								'html_class'            => $input->html_class() . ' new-state-abbrv',
+								'html_label_text'       => esc_html__(
+									'New State/Province Abbreviation',
+									'event_espresso'
+								) . ' *',
+								'html_other_attributes' => 'size="24"',
+								'default'               => EE_Registry::instance()->REQ->get($abbrv_name, ''),
+								'required'              => false,
+							)
+						),
+						// "submit" button
+						'add_new_state_submit_button' => new EE_Form_Section_HTML(
+							apply_filters(
+								'FHEE__EED_Add_New_State__display_add_new_state_micro_form__add_new_state_submit_button',
+								EEH_HTML::nbsp(3) .
+								EEH_HTML::link(
+									'',
+									esc_html__('ADD', 'event_espresso'),
+									'',
+									'submit-' . $new_state_submit_id,
+									'ee-form-add-new-state-submit button button-secondary',
+									'',
+									'data-target="' . $new_state_submit_id . '" data-value-field-name="' . $input->valueFieldName(). '"'
+								)
+							)
+						),
+						// extra info
+						'add_new_state_extra'         => new EE_Form_Section_HTML(
+							apply_filters(
+								'FHEE__EED_Add_New_State__display_add_new_state_micro_form__add_new_state_extra',
+								EEH_HTML::br(2)
+								.
+								EEH_HTML::div('', '', 'small-text')
+								.
+								EEH_HTML::strong(
+									'* ' .
+									esc_html__(
+										'Don\'t know your State/Province Abbreviation?',
+										'event_espresso'
+									)
+								)
+								.
+								EEH_HTML::br()
+								.
+								sprintf(
+									esc_html__(
+										'You can look here: %s, for a list of Countries and links to their State/Province Abbreviations ("Subdivisions assigned codes" column).',
+										'event_espresso'
+									),
+									EEH_HTML::link(
+										'http://en.wikipedia.org/wiki/ISO_3166-2',
+										'http://en.wikipedia.org/wiki/ISO_3166-2',
+										'',
+										'',
+										'ee-form-add-new-state-wiki-lnk',
+										'',
+										'target="_blank"'
+									)
+								)
+								.
+								EEH_HTML::divx()
+								.
+								EEH_HTML::br()
+								.
+								EEH_HTML::link(
+									'',
+									esc_html__('cancel new State/Province', 'event_espresso'),
+									'',
+									'hide-' . $input->html_id(),
+									'ee-form-cancel-new-state-lnk smaller-text',
+									'',
+									'data-target="' . $input->html_id() . '"'
+								)
+								.
+								EEH_HTML::divx()
+								.
+								EEH_HTML::br()
+							)
+						),
+					),
+				)
+			);
+			$question_group_reg_form->add_subsections(
+				array('new_state_micro_form' => $new_state_micro_form),
+				'state',
+				false
+			);
+		}
+		return $question_group_reg_form;
+	}
+
+
+	/**
+	 * set_new_state_input_width
+	 *
+	 * @return int|string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function add_new_state()
+	{
+		$REQ = EE_Registry::instance()->load_core('Request_Handler');
+		if (absint($REQ->get('nsmf_add_new_state')) === 1) {
+			EE_Registry::instance()->load_model('State');
+			// grab country ISO code, new state name, and new state abbreviation
+			$state_country = $REQ->is_set('nsmf_new_state_country')
+				? sanitize_text_field($REQ->get('nsmf_new_state_country'))
+				: false;
+			$state_name = $REQ->is_set('nsmf_new_state_name')
+				? sanitize_text_field($REQ->get('nsmf_new_state_name'))
+				: false;
+			$state_abbr = $REQ->is_set('nsmf_new_state_abbrv')
+				? sanitize_text_field($REQ->get('nsmf_new_state_abbrv'))
+				: false;
+			if ($state_country && $state_name && $state_abbr) {
+				$new_state = EED_Add_New_State::save_new_state_to_db(
+					array(
+						'CNT_ISO'    => strtoupper($state_country),
+						'STA_abbrev' => strtoupper($state_abbr),
+						'STA_name'   => ucwords($state_name),
+						'STA_active' => false,
+					)
+				);
+				if ($new_state instanceof EE_State) {
+					// clean house
+					EE_Registry::instance()->REQ->un_set('nsmf_add_new_state');
+					EE_Registry::instance()->REQ->un_set('nsmf_new_state_country');
+					EE_Registry::instance()->REQ->un_set('nsmf_new_state_name');
+					EE_Registry::instance()->REQ->un_set('nsmf_new_state_abbrv');
+					// get any existing new states
+					$new_states = EE_Registry::instance()->SSN->get_session_data(
+						'nsmf_new_states'
+					);
+					$new_states[ $new_state->ID() ] = $new_state;
+					EE_Registry::instance()->SSN->set_session_data(
+						array('nsmf_new_states' => $new_states)
+					);
+					if (EE_Registry::instance()->REQ->ajax) {
+						echo wp_json_encode(
+							array(
+								'success'      => true,
+								'id'           => $new_state->ID(),
+								'name'         => $new_state->name(),
+								'abbrev'       => $new_state->abbrev(),
+								'country_iso'  => $new_state->country_iso(),
+								'country_name' => $new_state->country()->name(),
+							)
+						);
+						exit();
+					}
+					return $new_state->ID();
+				}
+			} else {
+				$error = esc_html__(
+					'A new State/Province could not be added because invalid or missing data was received.',
+					'event_espresso'
+				);
+				if (EE_Registry::instance()->REQ->ajax) {
+					echo wp_json_encode(array('error' => $error));
+					exit();
+				}
+				EE_Error::add_error($error, __FILE__, __FUNCTION__, __LINE__);
+			}
+		}
+		return false;
+	}
+
+
+	/**
+	 * recursively drills down through request params to remove any that were added by this module
+	 *
+	 * @param array $request_params
+	 * @return array
+	 */
+	public static function filter_checkout_request_params($request_params)
+	{
+		foreach ($request_params as $form_section) {
+			if (is_array($form_section)) {
+				EED_Add_New_State::unset_new_state_request_params($form_section);
+				EED_Add_New_State::filter_checkout_request_params($form_section);
+			}
+		}
+		return $request_params;
+	}
+
+
+	/**
+	 * @param array $request_params
+	 * @return array
+	 */
+	public static function unset_new_state_request_params($request_params)
+	{
+		unset(
+			$request_params['new_state_micro_form'],
+			$request_params['new_state_micro_add_new_state'],
+			$request_params['new_state_micro_new_state_country'],
+			$request_params['new_state_micro_new_state_name'],
+			$request_params['new_state_micro_new_state_abbrv']
+		);
+		return $request_params;
+	}
+
+
+	/**
+	 * @param array $props_n_values
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public static function save_new_state_to_db($props_n_values = array())
+	{
+		$existing_state = EEM_State::instance()->get_all(array($props_n_values, 'limit' => 1));
+		if (! empty($existing_state)) {
+			return array_pop($existing_state);
+		}
+		$new_state = EE_State::new_instance($props_n_values);
+		if ($new_state instanceof EE_State) {
+			$country_settings_url = add_query_arg(
+				array(
+					'page'    => 'espresso_general_settings',
+					'action'  => 'country_settings',
+					'country' => $new_state->country_iso(),
+				),
+				admin_url('admin.php')
+			);
+			// if not non-ajax admin
+			new PersistentAdminNotice(
+				'new-state-added-' . $new_state->country_iso() . '-' . $new_state->abbrev(),
+				sprintf(
+					esc_html__(
+						'A new State named "%1$s (%2$s)" was dynamically added from an Event Espresso form for the Country of "%3$s".%5$sTo verify, edit, and/or delete this new State, please go to the %4$s and update the States / Provinces section.%5$sCheck "Yes" to have this new State added to dropdown select lists in forms.',
+						'event_espresso'
+					),
+					'<b>' . $new_state->name() . '</b>',
+					'<b>' . $new_state->abbrev() . '</b>',
+					'<b>' . $new_state->country()->name() . '</b>',
+					'<a href="'
+					. $country_settings_url
+					. '">'
+					. esc_html__(
+						'Event Espresso - General Settings > Countries Tab',
+						'event_espresso'
+					)
+					. '</a>',
+					'<br />'
+				)
+			);
+			$new_state->save();
+			EEM_State::instance()->reset_cached_states();
+			return $new_state;
+		}
+		return false;
+	}
+
+
+	/**
+	 * @param string $CNT_ISO
+	 * @param string $STA_ID
+	 * @param array  $cols_n_values
+	 * @return void
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public static function update_country_settings($CNT_ISO = '', $STA_ID = '', $cols_n_values = array())
+	{
+		if (! $CNT_ISO) {
+			EE_Error::add_error(
+				esc_html__('An invalid or missing Country ISO Code was received.', 'event_espresso'),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+		}
+		$STA_abbrev = is_array($cols_n_values) && isset($cols_n_values['STA_abbrev']) ? $cols_n_values['STA_abbrev']
+			: false;
+		if (! $STA_abbrev && ! empty($STA_ID)) {
+			$state = EEM_State::instance()->get_one_by_ID($STA_ID);
+			if ($state instanceof EE_State) {
+				$STA_abbrev = $state->abbrev();
+			}
+		}
+		if (! $STA_abbrev) {
+			EE_Error::add_error(
+				esc_html__('An invalid or missing State Abbreviation was received.', 'event_espresso'),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+		}
+		/** @var PersistentAdminNoticeManager $persistent_admin_notice_manager */
+		$persistent_admin_notice_manager = LoaderFactory::getLoader()->getShared(
+			'EventEspresso\core\services\notifications\PersistentAdminNoticeManager'
+		);
+		$persistent_admin_notice_manager->dismissNotice($CNT_ISO . '-' . $STA_abbrev, true, true);
+	}
+
+
+	/**
+	 * @param EE_State[]                            $state_options
+	 * @param EE_SPCO_Reg_Step_Attendee_Information $reg_step
+	 * @param EE_Registration                       $registration
+	 * @param EE_Question                           $question
+	 * @param                                       $answer
+	 * @return array
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public static function inject_new_reg_state_into_options(
+		$state_options = array(),
+		EE_SPCO_Reg_Step_Attendee_Information $reg_step,
+		EE_Registration $registration,
+		EE_Question $question,
+		$answer
+	) {
+		if ($answer instanceof EE_Answer && $question instanceof EE_Question
+			&& $question->type() === EEM_Question::QST_type_state
+		) {
+			$STA_ID = $answer->value();
+			if (! empty($STA_ID)) {
+				$state = EEM_State::instance()->get_one_by_ID($STA_ID);
+				if ($state instanceof EE_State) {
+					$country = $state->country();
+					if ($country instanceof EE_Country) {
+						if (! isset($state_options[ $country->name() ])) {
+							$state_options[ $country->name() ] = array();
+						}
+						if (! isset($state_options[ $country->name() ][ $STA_ID ])) {
+							$state_options[ $country->name() ][ $STA_ID ] = $state->name();
+						}
+					}
+				}
+			}
+		}
+		return $state_options;
+	}
+
+
+	/**
+	 * @param EE_Country[]                          $country_options
+	 * @param EE_SPCO_Reg_Step_Attendee_Information $reg_step
+	 * @param EE_Registration                       $registration
+	 * @param EE_Question                           $question
+	 * @param                                       $answer
+	 * @return array
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public static function inject_new_reg_country_into_options(
+		$country_options = array(),
+		EE_SPCO_Reg_Step_Attendee_Information $reg_step,
+		EE_Registration $registration,
+		EE_Question $question,
+		$answer
+	) {
+		if ($answer instanceof EE_Answer && $question instanceof EE_Question
+			&& $question->type()
+			   === EEM_Question::QST_type_country
+		) {
+			$CNT_ISO = $answer->value();
+			if (! empty($CNT_ISO)) {
+				$country = EEM_Country::instance()->get_one_by_ID($CNT_ISO);
+				if ($country instanceof EE_Country) {
+					if (! isset($country_options[ $CNT_ISO ])) {
+						$country_options[ $CNT_ISO ] = $country->name();
+					}
+				}
+			}
+		}
+		return $country_options;
+	}
+
+
+	/**
+	 * @param EE_State[] $state_options
+	 * @return array
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public static function state_options($state_options = array())
+	{
+		$new_states = EED_Add_New_State::_get_new_states();
+		foreach ($new_states as $new_state) {
+			if ($new_state instanceof EE_State
+				&& $new_state->country() instanceof EE_Country
+			) {
+				$state_options[ $new_state->country()->name() ][ $new_state->ID() ] = $new_state->name();
+			}
+		}
+		return $state_options;
+	}
+
+
+	/**
+	 * @return array
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	protected static function _get_new_states()
+	{
+		$new_states = array();
+		if (EE_Registry::instance()->SSN instanceof EE_Session) {
+			$new_states = EE_Registry::instance()->SSN->get_session_data(
+				'nsmf_new_states'
+			);
+		}
+		return is_array($new_states) ? $new_states : array();
+	}
+
+
+	/**
+	 * @param EE_Country[] $country_options
+	 * @return array
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public static function country_options($country_options = array())
+	{
+		$new_states = EED_Add_New_State::_get_new_states();
+		foreach ($new_states as $new_state) {
+			if ($new_state instanceof EE_State
+				&& $new_state->country() instanceof EE_Country
+			) {
+				$country_options[ $new_state->country()->ID() ] = $new_state->country()->name();
+			}
+		}
+		return $country_options;
+	}
 }

Spacing +45 added lines, -45 removed lines

@@ -159,14 +159,14 @@ 
      */
     public static function set_definitions()
     {
-        define('ANS_ASSETS_URL', plugin_dir_url(__FILE__) . 'assets' . DS);
+        define('ANS_ASSETS_URL', plugin_dir_url(__FILE__).'assets'.DS);
         define(
             'ANS_TEMPLATES_PATH',
             str_replace(
                 '\\',
                 DS,
                 plugin_dir_path(__FILE__)
-            ) . 'templates' . DS
+            ).'templates'.DS
         );
     }
 
@@ -216,7 +216,7 @@ 
         if (apply_filters('EED_Single_Page_Checkout__SPCO_active', false)) {
             wp_register_script(
                 'add_new_state',
-                ANS_ASSETS_URL . 'add_new_state.js',
+                ANS_ASSETS_URL.'add_new_state.js',
                 array('espresso_core', 'single_page_checkout'),
                 EVENT_ESPRESSO_VERSION,
                 true
@@ -263,10 +263,10 @@ 
             $new_state_submit_id = str_replace('state', 'new_state', $input->html_id());
             $country_options = array();
             $countries = EEM_Country::instance()->get_all_countries();
-            if (! empty($countries)) {
+            if ( ! empty($countries)) {
                 foreach ($countries as $country) {
                     if ($country instanceof EE_Country) {
-                        $country_options[ $country->ID() ] = $country->name();
+                        $country_options[$country->ID()] = $country->name();
                     }
                 }
             }
@@ -300,10 +300,10 @@ 
                                     '',
                                     esc_html__('click here to add a new state/province', 'event_espresso'),
                                     '',
-                                    'display-' . $input->html_id(),
+                                    'display-'.$input->html_id(),
                                     'ee-form-add-new-state-lnk display-the-hidden smaller-text hide-if-no-js',
                                     '',
-                                    'data-target="' . $input->html_id() . '"'
+                                    'data-target="'.$input->html_id().'"'
                                 )
                             )
                         ),
@@ -313,33 +313,33 @@ 
                                 'FHEE__EED_Add_New_State__display_add_new_state_micro_form__add_new_state_micro_form',
                                 EEH_HTML::div(
                                     '',
-                                    $input->html_id() . '-dv',
+                                    $input->html_id().'-dv',
                                     'ee-form-add-new-state-dv',
                                     'display: none;'
-                                ) .
+                                ).
                                 EEH_HTML::h6(
                                     esc_html__(
                                         'Is your state/province missing from the dropdown menu above? You can add it by completing the following steps:',
                                         'event_espresso'
                                     )
-                                ) .
-                                EEH_HTML::ul() .
+                                ).
+                                EEH_HTML::ul().
                                 EEH_HTML::li(
                                     esc_html__(
                                         'first select the Country that your State/Province belongs to',
                                         'event_espresso'
                                     )
-                                ) .
+                                ).
                                 EEH_HTML::li(
                                     esc_html__('enter the name of your State/Province', 'event_espresso')
-                                ) .
+                                ).
                                 EEH_HTML::li(
                                     esc_html__(
                                         'enter a two to six letter abbreviation for the name of your State/Province',
                                         'event_espresso'
                                     )
-                                ) .
-                                EEH_HTML::li(esc_html__('click the ADD button', 'event_espresso')) .
+                                ).
+                                EEH_HTML::li(esc_html__('click the ADD button', 'event_espresso')).
                                 EEH_HTML::ulx()
                             )
                         ),
@@ -353,7 +353,7 @@ 
                                     'nsmf_new_state_country',
                                     $input->html_id()
                                 ),
-                                'html_class'      => $input->html_class() . ' new-state-country',
+                                'html_class'      => $input->html_class().' new-state-country',
                                 'html_label_text' => esc_html__('New State/Province Country', 'event_espresso'),
                                 'default'         => EE_Registry::instance()->REQ->get($country_name, ''),
                                 'required'        => false,
@@ -368,7 +368,7 @@ 
                                     'nsmf_new_state_name',
                                     $input->html_id()
                                 ),
-                                'html_class'      => $input->html_class() . ' new-state-state',
+                                'html_class'      => $input->html_class().' new-state-state',
                                 'html_label_text' => esc_html__(
                                     'New State/Province Name',
                                     'event_espresso'
@@ -387,11 +387,11 @@ 
                                     'nsmf_new_state_abbrv',
                                     $input->html_id()
                                 ),
-                                'html_class'            => $input->html_class() . ' new-state-abbrv',
+                                'html_class'            => $input->html_class().' new-state-abbrv',
                                 'html_label_text'       => esc_html__(
                                     'New State/Province Abbreviation',
                                     'event_espresso'
-                                ) . ' *',
+                                ).' *',
                                 'html_other_attributes' => 'size="24"',
                                 'default'               => EE_Registry::instance()->REQ->get($abbrv_name, ''),
                                 'required'              => false,
@@ -401,15 +401,15 @@ 
                         'add_new_state_submit_button' => new EE_Form_Section_HTML(
                             apply_filters(
                                 'FHEE__EED_Add_New_State__display_add_new_state_micro_form__add_new_state_submit_button',
-                                EEH_HTML::nbsp(3) .
+                                EEH_HTML::nbsp(3).
                                 EEH_HTML::link(
                                     '',
                                     esc_html__('ADD', 'event_espresso'),
                                     '',
-                                    'submit-' . $new_state_submit_id,
+                                    'submit-'.$new_state_submit_id,
                                     'ee-form-add-new-state-submit button button-secondary',
                                     '',
-                                    'data-target="' . $new_state_submit_id . '" data-value-field-name="' . $input->valueFieldName(). '"'
+                                    'data-target="'.$new_state_submit_id.'" data-value-field-name="'.$input->valueFieldName().'"'
                                 )
                             )
                         ),
@@ -422,7 +422,7 @@ 
                                 EEH_HTML::div('', '', 'small-text')
                                 .
                                 EEH_HTML::strong(
-                                    '* ' .
+                                    '* '.
                                     esc_html__(
                                         'Don\'t know your State/Province Abbreviation?',
                                         'event_espresso'
@@ -455,10 +455,10 @@ 
                                     '',
                                     esc_html__('cancel new State/Province', 'event_espresso'),
                                     '',
-                                    'hide-' . $input->html_id(),
+                                    'hide-'.$input->html_id(),
                                     'ee-form-cancel-new-state-lnk smaller-text',
                                     '',
-                                    'data-target="' . $input->html_id() . '"'
+                                    'data-target="'.$input->html_id().'"'
                                 )
                                 .
                                 EEH_HTML::divx()
@@ -523,7 +523,7 @@ 
                     $new_states = EE_Registry::instance()->SSN->get_session_data(
                         'nsmf_new_states'
                     );
-                    $new_states[ $new_state->ID() ] = $new_state;
+                    $new_states[$new_state->ID()] = $new_state;
                     EE_Registry::instance()->SSN->set_session_data(
                         array('nsmf_new_states' => $new_states)
                     );
@@ -604,7 +604,7 @@ 
     public static function save_new_state_to_db($props_n_values = array())
     {
         $existing_state = EEM_State::instance()->get_all(array($props_n_values, 'limit' => 1));
-        if (! empty($existing_state)) {
+        if ( ! empty($existing_state)) {
             return array_pop($existing_state);
         }
         $new_state = EE_State::new_instance($props_n_values);
@@ -619,15 +619,15 @@ 
             );
             // if not non-ajax admin
             new PersistentAdminNotice(
-                'new-state-added-' . $new_state->country_iso() . '-' . $new_state->abbrev(),
+                'new-state-added-'.$new_state->country_iso().'-'.$new_state->abbrev(),
                 sprintf(
                     esc_html__(
                         'A new State named "%1$s (%2$s)" was dynamically added from an Event Espresso form for the Country of "%3$s".%5$sTo verify, edit, and/or delete this new State, please go to the %4$s and update the States / Provinces section.%5$sCheck "Yes" to have this new State added to dropdown select lists in forms.',
                         'event_espresso'
                     ),
-                    '<b>' . $new_state->name() . '</b>',
-                    '<b>' . $new_state->abbrev() . '</b>',
-                    '<b>' . $new_state->country()->name() . '</b>',
+                    '<b>'.$new_state->name().'</b>',
+                    '<b>'.$new_state->abbrev().'</b>',
+                    '<b>'.$new_state->country()->name().'</b>',
                     '<a href="'
                     . $country_settings_url
                     . '">'
@@ -660,7 +660,7 @@ 
      */
     public static function update_country_settings($CNT_ISO = '', $STA_ID = '', $cols_n_values = array())
     {
-        if (! $CNT_ISO) {
+        if ( ! $CNT_ISO) {
             EE_Error::add_error(
                 esc_html__('An invalid or missing Country ISO Code was received.', 'event_espresso'),
                 __FILE__,
@@ -670,13 +670,13 @@ 
         }
         $STA_abbrev = is_array($cols_n_values) && isset($cols_n_values['STA_abbrev']) ? $cols_n_values['STA_abbrev']
             : false;
-        if (! $STA_abbrev && ! empty($STA_ID)) {
+        if ( ! $STA_abbrev && ! empty($STA_ID)) {
             $state = EEM_State::instance()->get_one_by_ID($STA_ID);
             if ($state instanceof EE_State) {
                 $STA_abbrev = $state->abbrev();
             }
         }
-        if (! $STA_abbrev) {
+        if ( ! $STA_abbrev) {
             EE_Error::add_error(
                 esc_html__('An invalid or missing State Abbreviation was received.', 'event_espresso'),
                 __FILE__,
@@ -688,7 +688,7 @@ 
         $persistent_admin_notice_manager = LoaderFactory::getLoader()->getShared(
             'EventEspresso\core\services\notifications\PersistentAdminNoticeManager'
         );
-        $persistent_admin_notice_manager->dismissNotice($CNT_ISO . '-' . $STA_abbrev, true, true);
+        $persistent_admin_notice_manager->dismissNotice($CNT_ISO.'-'.$STA_abbrev, true, true);
     }
 
 
@@ -715,16 +715,16 @@ 
             && $question->type() === EEM_Question::QST_type_state
         ) {
             $STA_ID = $answer->value();
-            if (! empty($STA_ID)) {
+            if ( ! empty($STA_ID)) {
                 $state = EEM_State::instance()->get_one_by_ID($STA_ID);
                 if ($state instanceof EE_State) {
                     $country = $state->country();
                     if ($country instanceof EE_Country) {
-                        if (! isset($state_options[ $country->name() ])) {
-                            $state_options[ $country->name() ] = array();
+                        if ( ! isset($state_options[$country->name()])) {
+                            $state_options[$country->name()] = array();
                         }
-                        if (! isset($state_options[ $country->name() ][ $STA_ID ])) {
-                            $state_options[ $country->name() ][ $STA_ID ] = $state->name();
+                        if ( ! isset($state_options[$country->name()][$STA_ID])) {
+                            $state_options[$country->name()][$STA_ID] = $state->name();
                         }
                     }
                 }
@@ -758,11 +758,11 @@ 
                === EEM_Question::QST_type_country
         ) {
             $CNT_ISO = $answer->value();
-            if (! empty($CNT_ISO)) {
+            if ( ! empty($CNT_ISO)) {
                 $country = EEM_Country::instance()->get_one_by_ID($CNT_ISO);
                 if ($country instanceof EE_Country) {
-                    if (! isset($country_options[ $CNT_ISO ])) {
-                        $country_options[ $CNT_ISO ] = $country->name();
+                    if ( ! isset($country_options[$CNT_ISO])) {
+                        $country_options[$CNT_ISO] = $country->name();
                     }
                 }
             }
@@ -786,7 +786,7 @@ 
             if ($new_state instanceof EE_State
                 && $new_state->country() instanceof EE_Country
             ) {
-                $state_options[ $new_state->country()->name() ][ $new_state->ID() ] = $new_state->name();
+                $state_options[$new_state->country()->name()][$new_state->ID()] = $new_state->name();
             }
         }
         return $state_options;
@@ -826,7 +826,7 @@ 
             if ($new_state instanceof EE_State
                 && $new_state->country() instanceof EE_Country
             ) {
-                $country_options[ $new_state->country()->ID() ] = $new_state->country()->name();
+                $country_options[$new_state->country()->ID()] = $new_state->country()->name();
             }
         }
         return $country_options;

core/libraries/form_sections/inputs/EE_State_Select_Input.php

Spacing +5 added lines, -5 removed lines

@@ -36,7 +36,7 @@ 
     {
         if (isset($input_settings['value_field_name'])) {
             $this->valueFieldName = $input_settings['value_field_name'];
-            if (! EEM_State::instance()->has_field((string) $this->valueFieldName())) {
+            if ( ! EEM_State::instance()->has_field((string) $this->valueFieldName())) {
                 throw new InvalidArgumentException(
                     sprintf(
                         esc_html__('An invalid state field "%1$s" was specified for the state input\'s option values.', 'event_espresso'),
@@ -53,7 +53,7 @@ 
             $this
         );
         $input_settings['html_class'] = isset($input_settings['html_class'])
-            ? $input_settings['html_class'] . ' ee-state-select-js'
+            ? $input_settings['html_class'].' ee-state-select-js'
             : 'ee-state-select-js';
         parent::__construct($state_options, $input_settings);
     }
@@ -83,7 +83,7 @@ 
     public function get_state_answer_options($state_options = null)
     {
         // if passed something that is NOT an array
-        if (! is_array($state_options) || empty($state_options)) {
+        if ( ! is_array($state_options) || empty($state_options)) {
             // get possibly cached list of states
             $states = EEM_State::instance()->get_all_active_states();
         }
@@ -91,12 +91,12 @@ 
             $states = $state_options;
             $state_options = array();
         }
-        if (! empty($states)) {
+        if ( ! empty($states)) {
             // set the default
             $state_options[''][''] = '';
             foreach ($states as $state) {
                 if ($state instanceof EE_State) {
-                    $state_options[ $state->country()->name() ][ $state->get($this->valueFieldName()) ] = $state->name();
+                    $state_options[$state->country()->name()][$state->get($this->valueFieldName())] = $state->name();
                 }
             }
         }

Indentation +86 added lines, -86 removed lines

@@ -12,94 +12,94 @@
  */
 class EE_State_Select_Input extends EE_Select_Input
 {
-    /**
-     * @var string the name of the EE_State field to use for option values in the HTML form input.
-     */
-    protected $valueFieldName;
+	/**
+	 * @var string the name of the EE_State field to use for option values in the HTML form input.
+	 */
+	protected $valueFieldName;
 
-    /**
-     * @param EE_State[]|array|null $state_options. If a flat array of string is provided,
-     * $input_settings['value_field_name'] is ignored. If an array of states is passed, that field will be used for
-     * the keys (which will become the option values). If null or empty is passed, all active states will be used,
-     * and $input_settings['value_field_name'] will again be used.     *
-     * @param array $input_settings same as parent, but also {
-     *   @type string $value_field_name the name of the field to use
-     *   for the HTML option values, ie, `STA_ID`, `STA_abbrev`, or `STA_name`.
-     * }
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function __construct($state_options, $input_settings = array())
-    {
-        if (isset($input_settings['value_field_name'])) {
-            $this->valueFieldName = $input_settings['value_field_name'];
-            if (! EEM_State::instance()->has_field((string) $this->valueFieldName())) {
-                throw new InvalidArgumentException(
-                    sprintf(
-                        esc_html__('An invalid state field "%1$s" was specified for the state input\'s option values.', 'event_espresso'),
-                        $this->valueFieldName()
-                    )
-                );
-            }
-        } else {
-            $this->valueFieldName = 'STA_ID';
-        }
-        $state_options = apply_filters(
-            'FHEE__EE_State_Select_Input____construct__state_options',
-            $this->get_state_answer_options($state_options),
-            $this
-        );
-        $input_settings['html_class'] = isset($input_settings['html_class'])
-            ? $input_settings['html_class'] . ' ee-state-select-js'
-            : 'ee-state-select-js';
-        parent::__construct($state_options, $input_settings);
-    }
+	/**
+	 * @param EE_State[]|array|null $state_options. If a flat array of string is provided,
+	 * $input_settings['value_field_name'] is ignored. If an array of states is passed, that field will be used for
+	 * the keys (which will become the option values). If null or empty is passed, all active states will be used,
+	 * and $input_settings['value_field_name'] will again be used.     *
+	 * @param array $input_settings same as parent, but also {
+	 *   @type string $value_field_name the name of the field to use
+	 *   for the HTML option values, ie, `STA_ID`, `STA_abbrev`, or `STA_name`.
+	 * }
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function __construct($state_options, $input_settings = array())
+	{
+		if (isset($input_settings['value_field_name'])) {
+			$this->valueFieldName = $input_settings['value_field_name'];
+			if (! EEM_State::instance()->has_field((string) $this->valueFieldName())) {
+				throw new InvalidArgumentException(
+					sprintf(
+						esc_html__('An invalid state field "%1$s" was specified for the state input\'s option values.', 'event_espresso'),
+						$this->valueFieldName()
+					)
+				);
+			}
+		} else {
+			$this->valueFieldName = 'STA_ID';
+		}
+		$state_options = apply_filters(
+			'FHEE__EE_State_Select_Input____construct__state_options',
+			$this->get_state_answer_options($state_options),
+			$this
+		);
+		$input_settings['html_class'] = isset($input_settings['html_class'])
+			? $input_settings['html_class'] . ' ee-state-select-js'
+			: 'ee-state-select-js';
+		parent::__construct($state_options, $input_settings);
+	}
 
-    /**
-     * Returns the name of the state field used for the HTML option values.
-     * @since $VID:$
-     * @return string
-     */
-    public function valueFieldName()
-    {
-        return $this->valueFieldName;
-    }
+	/**
+	 * Returns the name of the state field used for the HTML option values.
+	 * @since $VID:$
+	 * @return string
+	 */
+	public function valueFieldName()
+	{
+		return $this->valueFieldName;
+	}
 
 
-    /**
-     * get_state_answer_options
-     *
-     * @param array $state_options
-     * @return array
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public function get_state_answer_options($state_options = null)
-    {
-        // if passed something that is NOT an array
-        if (! is_array($state_options) || empty($state_options)) {
-            // get possibly cached list of states
-            $states = EEM_State::instance()->get_all_active_states();
-        }
-        if (is_array($state_options) && reset($state_options) instanceof EE_State) {
-            $states = $state_options;
-            $state_options = array();
-        }
-        if (! empty($states)) {
-            // set the default
-            $state_options[''][''] = '';
-            foreach ($states as $state) {
-                if ($state instanceof EE_State) {
-                    $state_options[ $state->country()->name() ][ $state->get($this->valueFieldName()) ] = $state->name();
-                }
-            }
-        }
-        return $state_options;
-    }
+	/**
+	 * get_state_answer_options
+	 *
+	 * @param array $state_options
+	 * @return array
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public function get_state_answer_options($state_options = null)
+	{
+		// if passed something that is NOT an array
+		if (! is_array($state_options) || empty($state_options)) {
+			// get possibly cached list of states
+			$states = EEM_State::instance()->get_all_active_states();
+		}
+		if (is_array($state_options) && reset($state_options) instanceof EE_State) {
+			$states = $state_options;
+			$state_options = array();
+		}
+		if (! empty($states)) {
+			// set the default
+			$state_options[''][''] = '';
+			foreach ($states as $state) {
+				if ($state instanceof EE_State) {
+					$state_options[ $state->country()->name() ][ $state->get($this->valueFieldName()) ] = $state->name();
+				}
+			}
+		}
+		return $state_options;
+	}
 }

public/template_tags.php

Spacing +291 added lines, -291 removed lines

@@ -14,12 +14,12 @@ 
  * @param int | \EE_Event $event
  * @return bool
  */
-function is_espresso_event( $event = NULL ) {
-	if ( can_use_espresso_conditionals( __FUNCTION__ )) {
+function is_espresso_event($event = NULL) {
+	if (can_use_espresso_conditionals(__FUNCTION__)) {
 		// extract EE_Event object from passed param regardless of what it is (within reason of course)
-		$event = EEH_Event_View::get_event( $event );
+		$event = EEH_Event_View::get_event($event);
 		// do we have a valid event ?
-		return $event instanceof EE_Event  ? TRUE : FALSE;
+		return $event instanceof EE_Event ? TRUE : FALSE;
 	}
 	return FALSE;
 }
@@ -31,7 +31,7 @@ 
  * @return bool
  */
 function is_espresso_event_single() {
-	if ( can_use_espresso_conditionals( __FUNCTION__ )) {
+	if (can_use_espresso_conditionals(__FUNCTION__)) {
 		global $wp_query;
 		// return conditionals set by CPTs
 		return $wp_query instanceof WP_Query ? $wp_query->is_espresso_event_single : FALSE;
@@ -46,7 +46,7 @@ 
  * @return bool
  */
 function is_espresso_event_archive() {
-	if ( can_use_espresso_conditionals( __FUNCTION__ )) {
+	if (can_use_espresso_conditionals(__FUNCTION__)) {
 		global $wp_query;
 		return $wp_query instanceof WP_Query ? $wp_query->is_espresso_event_archive : FALSE;
 	}
@@ -60,7 +60,7 @@ 
  * @return bool
  */
 function is_espresso_event_taxonomy() {
-	if ( can_use_espresso_conditionals( __FUNCTION__ )) {
+	if (can_use_espresso_conditionals(__FUNCTION__)) {
 		global $wp_query;
 		return $wp_query instanceof WP_Query ? $wp_query->is_espresso_event_taxonomy : FALSE;
 	}
@@ -74,10 +74,10 @@ 
  * @param int | \EE_Venue $venue
  * @return bool
  */
-function is_espresso_venue( $venue = NULL ) {
-	if ( can_use_espresso_conditionals( __FUNCTION__ )) {
+function is_espresso_venue($venue = NULL) {
+	if (can_use_espresso_conditionals(__FUNCTION__)) {
 		// extract EE_Venue object from passed param regardless of what it is (within reason of course)
-		$venue = EEH_Venue_View::get_venue( $venue, FALSE );
+		$venue = EEH_Venue_View::get_venue($venue, FALSE);
 		// do we have a valid event ?
 		return $venue instanceof EE_Venue ? TRUE : FALSE;
 	}
@@ -91,7 +91,7 @@ 
  * @return bool
  */
 function is_espresso_venue_single() {
-	if ( can_use_espresso_conditionals( __FUNCTION__ )) {
+	if (can_use_espresso_conditionals(__FUNCTION__)) {
 		global $wp_query;
 		return $wp_query instanceof WP_Query ? $wp_query->is_espresso_venue_single : FALSE;
 	}
@@ -105,7 +105,7 @@ 
  * @return bool
  */
 function is_espresso_venue_archive() {
-	if ( can_use_espresso_conditionals( __FUNCTION__ )) {
+	if (can_use_espresso_conditionals(__FUNCTION__)) {
 		global $wp_query;
 		return $wp_query instanceof WP_Query ? $wp_query->is_espresso_venue_archive : FALSE;
 	}
@@ -119,7 +119,7 @@ 
  * @return bool
  */
 function is_espresso_venue_taxonomy() {
-	if ( can_use_espresso_conditionals( __FUNCTION__ )) {
+	if (can_use_espresso_conditionals(__FUNCTION__)) {
 		global $wp_query;
 		return $wp_query instanceof WP_Query ? $wp_query->is_espresso_venue_taxonomy : FALSE;
 	}
@@ -133,12 +133,12 @@ 
  * @param $conditional_tag
  * @return bool
  */
-function can_use_espresso_conditionals( $conditional_tag ) {
-	if ( ! did_action( 'AHEE__EE_System__initialize' )) {
+function can_use_espresso_conditionals($conditional_tag) {
+	if ( ! did_action('AHEE__EE_System__initialize')) {
 		EE_Error::doing_it_wrong(
 			__FUNCTION__,
 			sprintf(
-				esc_html__( 'The "%s" conditional tag can not be used until after the "init" hook has run, but works best when used within a theme\'s template files.','event_espresso'),
+				esc_html__('The "%s" conditional tag can not be used until after the "init" hook has run, but works best when used within a theme\'s template files.', 'event_espresso'),
 				$conditional_tag
 			),
 			'4.4.0'
@@ -153,13 +153,13 @@ 
 
 /*************************** Event Queries ***************************/
 
-if ( ! function_exists( 'espresso_get_events' )) {
+if ( ! function_exists('espresso_get_events')) {
 	/**
 	 * 	espresso_get_events
 	 * @param array $params
 	 * @return array
 	 */
-	function espresso_get_events( $params = array() ) {
+	function espresso_get_events($params = array()) {
 		//set default params
 		$default_espresso_events_params = array(
 			'limit' => 10,
@@ -170,18 +170,18 @@ 
 			'sort' => 'ASC'
 		);
 		// allow the defaults to be filtered
-		$default_espresso_events_params = apply_filters( 'espresso_get_events__default_espresso_events_params', $default_espresso_events_params );
+		$default_espresso_events_params = apply_filters('espresso_get_events__default_espresso_events_params', $default_espresso_events_params);
 		// grab params and merge with defaults, then extract
-		$params = array_merge( $default_espresso_events_params, $params );
+		$params = array_merge($default_espresso_events_params, $params);
 		// run the query
-		$events_query = new EventEspresso\core\domain\services\wp_queries\EventListQuery( $params );
+		$events_query = new EventEspresso\core\domain\services\wp_queries\EventListQuery($params);
 		// assign results to a variable so we can return it
 		$events = $events_query->have_posts() ? $events_query->posts : array();
 		// but first reset the query and postdata
 		wp_reset_query();
 		wp_reset_postdata();
 		EED_Events_Archive::remove_all_events_archive_filters();
-		unset( $events_query );
+		unset($events_query);
 		return $events;
 	}
 }
@@ -195,33 +195,33 @@ 
  * espresso_load_ticket_selector
  */
 function espresso_load_ticket_selector() {
-	EE_Registry::instance()->load_file( EE_MODULES . 'ticket_selector', 'EED_Ticket_Selector', 'module' );
+	EE_Registry::instance()->load_file(EE_MODULES.'ticket_selector', 'EED_Ticket_Selector', 'module');
 }
 
-if ( ! function_exists( 'espresso_ticket_selector' )) {
+if ( ! function_exists('espresso_ticket_selector')) {
 	/**
 	 * espresso_ticket_selector
 	 * @param null $event
 	 */
-	function espresso_ticket_selector( $event = NULL ) {
-		if (  ! apply_filters( 'FHEE_disable_espresso_ticket_selector', FALSE ) ) {
+	function espresso_ticket_selector($event = NULL) {
+		if ( ! apply_filters('FHEE_disable_espresso_ticket_selector', FALSE)) {
 			espresso_load_ticket_selector();
             \EED_Ticket_Selector::set_definitions();
-			echo EED_Ticket_Selector::display_ticket_selector( $event );
+			echo EED_Ticket_Selector::display_ticket_selector($event);
 		}
 	}
 }
 
 
-	if ( ! function_exists( 'espresso_view_details_btn' )) {
+	if ( ! function_exists('espresso_view_details_btn')) {
 	/**
 	 * espresso_view_details_btn
 	 * @param null $event
 	 */
-	function espresso_view_details_btn( $event = NULL ) {
-		if (  ! apply_filters( 'FHEE_disable_espresso_view_details_btn', FALSE ) ) {
+	function espresso_view_details_btn($event = NULL) {
+		if ( ! apply_filters('FHEE_disable_espresso_view_details_btn', FALSE)) {
 			espresso_load_ticket_selector();
-			echo EED_Ticket_Selector::display_ticket_selector( $event, TRUE );
+			echo EED_Ticket_Selector::display_ticket_selector($event, TRUE);
 		}
 	}
 }
@@ -231,7 +231,7 @@ 
 
 /*************************** EEH_Event_View ***************************/
 
-if ( ! function_exists( 'espresso_load_event_list_assets' )) {
+if ( ! function_exists('espresso_load_event_list_assets')) {
 	/**
 	 * espresso_load_event_list_assets
 	 * ensures that event list styles and scripts are loaded
@@ -240,13 +240,13 @@ 
 	 */
 	function espresso_load_event_list_assets() {
 		$event_list = EED_Events_Archive::instance();
-		add_action( 'AHEE__EE_System__initialize_last', array( $event_list, 'load_event_list_assets' ), 10 );
-		add_filter( 'FHEE_enable_default_espresso_css', '__return_true' );
+		add_action('AHEE__EE_System__initialize_last', array($event_list, 'load_event_list_assets'), 10);
+		add_filter('FHEE_enable_default_espresso_css', '__return_true');
 	}
 }
 
 
-if ( ! function_exists( 'espresso_event_reg_button' )) {
+if ( ! function_exists('espresso_event_reg_button')) {
 	/**
 	 * espresso_event_reg_button
 	 * returns the "Register Now" button if event is active,
@@ -258,13 +258,13 @@ 
 	 * @param bool $EVT_ID
 	 * @return string
 	 */
-	function espresso_event_reg_button( $btn_text_if_active = NULL, $btn_text_if_inactive = FALSE, $EVT_ID = FALSE ) {
-		$event = EEH_Event_View::get_event( $EVT_ID );
-		if ( ! $event instanceof EE_Event ) {
+	function espresso_event_reg_button($btn_text_if_active = NULL, $btn_text_if_inactive = FALSE, $EVT_ID = FALSE) {
+		$event = EEH_Event_View::get_event($EVT_ID);
+		if ( ! $event instanceof EE_Event) {
 			return;
 		}
 		$event_status = $event->get_active_status();
-		switch ( $event_status ) {
+		switch ($event_status) {
 			case EE_Datetime::sold_out :
 				$btn_text = esc_html__('Sold Out', 'event_espresso');
 				$class = 'ee-pink';
@@ -284,15 +284,15 @@ 
 			case EE_Datetime::upcoming :
 			case EE_Datetime::active :
 			default :
-				$btn_text =! empty( $btn_text_if_active ) ? $btn_text_if_active : esc_html__( 'Register Now', 'event_espresso' );
+				$btn_text = ! empty($btn_text_if_active) ? $btn_text_if_active : esc_html__('Register Now', 'event_espresso');
 				$class = 'ee-green';
 		}
-		if ( $event_status < 1 && ! empty( $btn_text_if_inactive )) {
+		if ($event_status < 1 && ! empty($btn_text_if_inactive)) {
 			$btn_text = $btn_text_if_inactive;
 			$class = 'ee-grey';
 		}
 		?>
-		<a class="ee-button ee-register-button <?php echo $class; ?>" href="<?php espresso_event_link_url( $EVT_ID ); ?>"<?php echo \EED_Events_Archive::link_target(); ?>>
+		<a class="ee-button ee-register-button <?php echo $class; ?>" href="<?php espresso_event_link_url($EVT_ID); ?>"<?php echo \EED_Events_Archive::link_target(); ?>>
 			<?php echo $btn_text; ?>
 		</a>
 	<?php
@@ -301,7 +301,7 @@ 
 
 
 
-if ( ! function_exists( 'espresso_display_ticket_selector' )) {
+if ( ! function_exists('espresso_display_ticket_selector')) {
 	/**
 	 * espresso_display_ticket_selector
 	 * whether or not to display the Ticket Selector for an event
@@ -309,14 +309,14 @@ 
 	 * @param bool $EVT_ID
 	 * @return boolean
 	 */
-	function espresso_display_ticket_selector( $EVT_ID = FALSE ) {
-		return EEH_Event_View::display_ticket_selector( $EVT_ID );
+	function espresso_display_ticket_selector($EVT_ID = FALSE) {
+		return EEH_Event_View::display_ticket_selector($EVT_ID);
 	}
 }
 
 
 
-if ( ! function_exists( 'espresso_event_status_banner' )) {
+if ( ! function_exists('espresso_event_status_banner')) {
 	/**
 	 * espresso_event_status
 	 * returns a banner showing the event status if it is sold out, expired, or inactive
@@ -324,13 +324,13 @@ 
 	 * @param bool $EVT_ID
 	 * @return string
 	 */
-	function espresso_event_status_banner( $EVT_ID = FALSE ) {
-		return EEH_Event_View::event_status( $EVT_ID );
+	function espresso_event_status_banner($EVT_ID = FALSE) {
+		return EEH_Event_View::event_status($EVT_ID);
 	}
 }
 
 
-if ( ! function_exists( 'espresso_event_status' )) {
+if ( ! function_exists('espresso_event_status')) {
 	/**
 	 * espresso_event_status
 	 * returns the event status if it is sold out, expired, or inactive
@@ -339,13 +339,13 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_event_status( $EVT_ID = 0, $echo = TRUE ) {
-		return EEH_Event_View::event_active_status( $EVT_ID, $echo );
+	function espresso_event_status($EVT_ID = 0, $echo = TRUE) {
+		return EEH_Event_View::event_active_status($EVT_ID, $echo);
 	}
 }
 
 
-if ( ! function_exists( 'espresso_event_categories' )) {
+if ( ! function_exists('espresso_event_categories')) {
 	/**
 	 * espresso_event_categories
 	 * returns the terms associated with an event
@@ -355,17 +355,17 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_event_categories( $EVT_ID = 0, $hide_uncategorized = TRUE, $echo = TRUE ) {
-		if ( $echo ) {
-			echo EEH_Event_View::event_categories( $EVT_ID, $hide_uncategorized );
+	function espresso_event_categories($EVT_ID = 0, $hide_uncategorized = TRUE, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Event_View::event_categories($EVT_ID, $hide_uncategorized);
 			return '';
 		}
-		return EEH_Event_View::event_categories( $EVT_ID, $hide_uncategorized );
+		return EEH_Event_View::event_categories($EVT_ID, $hide_uncategorized);
 	}
 }
 
 
-if ( ! function_exists( 'espresso_event_tickets_available' )) {
+if ( ! function_exists('espresso_event_tickets_available')) {
 	/**
 	 * espresso_event_tickets_available
 	 * returns the ticket types available for purchase for an event
@@ -375,26 +375,26 @@ 
 	 * @param bool $format
 	 * @return string
 	 */
-	function espresso_event_tickets_available( $EVT_ID = 0, $echo = TRUE, $format = TRUE ) {
-		$tickets = EEH_Event_View::event_tickets_available( $EVT_ID );
-		if ( is_array( $tickets ) && ! empty( $tickets )) {
+	function espresso_event_tickets_available($EVT_ID = 0, $echo = TRUE, $format = TRUE) {
+		$tickets = EEH_Event_View::event_tickets_available($EVT_ID);
+		if (is_array($tickets) && ! empty($tickets)) {
 			// if formatting then $html will be a string, else it will be an array of ticket objects
-			$html = $format ? '<ul id="ee-event-tickets-ul-' . $EVT_ID . '" class="ee-event-tickets-ul">' : array();
-			foreach ( $tickets as $ticket ) {
-				if ( $ticket instanceof EE_Ticket ) {
-					if ( $format ) {
-						$html .= '<li id="ee-event-tickets-li-' . $ticket->ID() . '" class="ee-event-tickets-li">';
-						$html .= $ticket->name() . ' ' . EEH_Template::format_currency( $ticket->get_ticket_total_with_taxes() );
+			$html = $format ? '<ul id="ee-event-tickets-ul-'.$EVT_ID.'" class="ee-event-tickets-ul">' : array();
+			foreach ($tickets as $ticket) {
+				if ($ticket instanceof EE_Ticket) {
+					if ($format) {
+						$html .= '<li id="ee-event-tickets-li-'.$ticket->ID().'" class="ee-event-tickets-li">';
+						$html .= $ticket->name().' '.EEH_Template::format_currency($ticket->get_ticket_total_with_taxes());
 						$html .= '</li>';
 					} else {
 						$html[] = $ticket;
 					}
 				}
 			}
-			if ( $format ) {
+			if ($format) {
 				$html .= '</ul>';
 			}
-			if ( $echo && $format ) {
+			if ($echo && $format) {
 				echo $html;
 				return '';
 			}
@@ -404,7 +404,7 @@ 
 	}
 }
 
-if ( ! function_exists( 'espresso_event_date_obj' )) {
+if ( ! function_exists('espresso_event_date_obj')) {
 	/**
 	 * espresso_event_date_obj
 	 * returns the primary date object for an event
@@ -412,13 +412,13 @@ 
 	 * @param bool $EVT_ID
 	 * @return object
 	 */
-	function espresso_event_date_obj( $EVT_ID = FALSE ) {
-		return EEH_Event_View::get_primary_date_obj( $EVT_ID );
+	function espresso_event_date_obj($EVT_ID = FALSE) {
+		return EEH_Event_View::get_primary_date_obj($EVT_ID);
 	}
 }
 
 
-if ( ! function_exists( 'espresso_event_date' )) {
+if ( ! function_exists('espresso_event_date')) {
 	/**
 	 * espresso_event_date
 	 * returns the primary date for an event
@@ -429,22 +429,22 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_event_date( $date_format = '', $time_format = '', $EVT_ID = FALSE, $echo = TRUE ) {
-		$date_format = ! empty( $date_format ) ? $date_format : get_option( 'date_format' );
-		$time_format = ! empty( $time_format ) ? $time_format : get_option( 'time_format' );
-		$date_format = apply_filters( 'FHEE__espresso_event_date__date_format', $date_format );
-		$time_format = apply_filters( 'FHEE__espresso_event_date__time_format', $time_format );
-		if($echo){
-			echo EEH_Event_View::the_event_date( $date_format, $time_format, $EVT_ID );
+	function espresso_event_date($date_format = '', $time_format = '', $EVT_ID = FALSE, $echo = TRUE) {
+		$date_format = ! empty($date_format) ? $date_format : get_option('date_format');
+		$time_format = ! empty($time_format) ? $time_format : get_option('time_format');
+		$date_format = apply_filters('FHEE__espresso_event_date__date_format', $date_format);
+		$time_format = apply_filters('FHEE__espresso_event_date__time_format', $time_format);
+		if ($echo) {
+			echo EEH_Event_View::the_event_date($date_format, $time_format, $EVT_ID);
 			return '';
 		}
-		return EEH_Event_View::the_event_date( $date_format, $time_format, $EVT_ID );
+		return EEH_Event_View::the_event_date($date_format, $time_format, $EVT_ID);
 
 	}
 }
 
 
-if ( ! function_exists( 'espresso_list_of_event_dates' )) {
+if ( ! function_exists('espresso_list_of_event_dates')) {
 	/**
 	 * espresso_list_of_event_dates
 	 * returns a unordered list of dates for an event
@@ -459,40 +459,40 @@ 
 	 * @param null   $limit
 	 * @return string
 	 */
-	function espresso_list_of_event_dates( $EVT_ID = 0, $date_format = '', $time_format = '', $echo = TRUE, $show_expired = NULL, $format = TRUE, $add_breaks = TRUE, $limit = NULL ) {
-		$date_format = ! empty( $date_format ) ? $date_format : get_option( 'date_format' );
-		$time_format = ! empty( $time_format ) ? $time_format : get_option( 'time_format' );
-		$date_format = apply_filters( 'FHEE__espresso_list_of_event_dates__date_format', $date_format );
-		$time_format = apply_filters( 'FHEE__espresso_list_of_event_dates__time_format', $time_format );
-		$datetimes = EEH_Event_View::get_all_date_obj( $EVT_ID, $show_expired, FALSE, $limit );
-		if ( ! $format ) {
-			return apply_filters( 'FHEE__espresso_list_of_event_dates__datetimes', $datetimes );
+	function espresso_list_of_event_dates($EVT_ID = 0, $date_format = '', $time_format = '', $echo = TRUE, $show_expired = NULL, $format = TRUE, $add_breaks = TRUE, $limit = NULL) {
+		$date_format = ! empty($date_format) ? $date_format : get_option('date_format');
+		$time_format = ! empty($time_format) ? $time_format : get_option('time_format');
+		$date_format = apply_filters('FHEE__espresso_list_of_event_dates__date_format', $date_format);
+		$time_format = apply_filters('FHEE__espresso_list_of_event_dates__time_format', $time_format);
+		$datetimes = EEH_Event_View::get_all_date_obj($EVT_ID, $show_expired, FALSE, $limit);
+		if ( ! $format) {
+			return apply_filters('FHEE__espresso_list_of_event_dates__datetimes', $datetimes);
 		}
 		//d( $datetimes );
-		if ( is_array( $datetimes ) && ! empty( $datetimes )) {
+		if (is_array($datetimes) && ! empty($datetimes)) {
 			global $post;
-			$html = $format ? '<ul id="ee-event-datetimes-ul-' . $post->ID . '" class="ee-event-datetimes-ul ee-clearfix">' : '';
-			foreach ( $datetimes as $datetime ) {
-				if ( $datetime instanceof EE_Datetime ) {
-					$html .= '<li id="ee-event-datetimes-li-' . $datetime->ID();
-					$html .= '" class="ee-event-datetimes-li ee-event-datetimes-li-' . $datetime->get_active_status() . '">';
+			$html = $format ? '<ul id="ee-event-datetimes-ul-'.$post->ID.'" class="ee-event-datetimes-ul ee-clearfix">' : '';
+			foreach ($datetimes as $datetime) {
+				if ($datetime instanceof EE_Datetime) {
+					$html .= '<li id="ee-event-datetimes-li-'.$datetime->ID();
+					$html .= '" class="ee-event-datetimes-li ee-event-datetimes-li-'.$datetime->get_active_status().'">';
 					$datetime_name = $datetime->name();
-					$html .= ! empty( $datetime_name ) ? '<strong>' . $datetime_name . '</strong>' : '';
-					$html .= ! empty( $datetime_name )  && $add_breaks ? '<br />' : '';
-					$html .= '<span class="dashicons dashicons-calendar"></span><span class="ee-event-datetimes-li-daterange">' . $datetime->date_range( $date_format ) . '</span><br/>';
-					$html .= '<span class="dashicons dashicons-clock"></span><span class="ee-event-datetimes-li-timerange">' . $datetime->time_range( $time_format ) . '</span>';
+					$html .= ! empty($datetime_name) ? '<strong>'.$datetime_name.'</strong>' : '';
+					$html .= ! empty($datetime_name) && $add_breaks ? '<br />' : '';
+					$html .= '<span class="dashicons dashicons-calendar"></span><span class="ee-event-datetimes-li-daterange">'.$datetime->date_range($date_format).'</span><br/>';
+					$html .= '<span class="dashicons dashicons-clock"></span><span class="ee-event-datetimes-li-timerange">'.$datetime->time_range($time_format).'</span>';
 					$datetime_description = $datetime->description();
-					$html .= ! empty( $datetime_description )  && $add_breaks ? '<br />' : '';
-					$html .= ! empty( $datetime_description ) ? ' - ' . $datetime_description : '';
-					$html = apply_filters( 'FHEE__espresso_list_of_event_dates__datetime_html', $html, $datetime );
+					$html .= ! empty($datetime_description) && $add_breaks ? '<br />' : '';
+					$html .= ! empty($datetime_description) ? ' - '.$datetime_description : '';
+					$html = apply_filters('FHEE__espresso_list_of_event_dates__datetime_html', $html, $datetime);
 					$html .= '</li>';
 				}
 			}
 			$html .= $format ? '</ul>' : '';
 		} else {
-			$html = $format ?  '<p><span class="dashicons dashicons-marker pink-text"></span>' . esc_html__( 'There are no upcoming dates for this event.', 'event_espresso' ) . '</p><br/>' : '';
+			$html = $format ? '<p><span class="dashicons dashicons-marker pink-text"></span>'.esc_html__('There are no upcoming dates for this event.', 'event_espresso').'</p><br/>' : '';
 		}
-		if ( $echo ) {
+		if ($echo) {
 			echo $html;
 			return '';
 		}
@@ -501,7 +501,7 @@ 
 }
 
 
-if ( ! function_exists( 'espresso_event_end_date' )) {
+if ( ! function_exists('espresso_event_end_date')) {
 	/**
 	 * espresso_event_end_date
 	 * returns the last date for an event
@@ -512,20 +512,20 @@ 
 	 * @param bool   $echo
 	 * @return string
 	 */
-	function espresso_event_end_date( $date_format = '', $time_format = '', $EVT_ID = FALSE, $echo = TRUE ) {
-		$date_format = ! empty( $date_format ) ? $date_format : get_option( 'date_format' );
-		$time_format = ! empty( $time_format ) ? $time_format : get_option( 'time_format' );
-		$date_format = apply_filters( 'FHEE__espresso_event_end_date__date_format', $date_format );
-		$time_format = apply_filters( 'FHEE__espresso_event_end_date__time_format', $time_format );
-		if($echo){
-			echo EEH_Event_View::the_event_end_date( $date_format, $time_format, $EVT_ID );
+	function espresso_event_end_date($date_format = '', $time_format = '', $EVT_ID = FALSE, $echo = TRUE) {
+		$date_format = ! empty($date_format) ? $date_format : get_option('date_format');
+		$time_format = ! empty($time_format) ? $time_format : get_option('time_format');
+		$date_format = apply_filters('FHEE__espresso_event_end_date__date_format', $date_format);
+		$time_format = apply_filters('FHEE__espresso_event_end_date__time_format', $time_format);
+		if ($echo) {
+			echo EEH_Event_View::the_event_end_date($date_format, $time_format, $EVT_ID);
 			return '';
 		}
-		return EEH_Event_View::the_event_end_date( $date_format, $time_format, $EVT_ID );
+		return EEH_Event_View::the_event_end_date($date_format, $time_format, $EVT_ID);
 	}
 }
 
-if ( ! function_exists( 'espresso_event_date_range' )) {
+if ( ! function_exists('espresso_event_date_range')) {
 	/**
 	 * espresso_event_date_range
 	 * returns the first and last chronologically ordered dates for an event (if different)
@@ -538,32 +538,32 @@ 
 	 * @param bool   $echo
 	 * @return string
 	 */
-	function espresso_event_date_range( $date_format = '', $time_format = '', $single_date_format = '', $single_time_format = '', $EVT_ID = FALSE, $echo = TRUE ) {
+	function espresso_event_date_range($date_format = '', $time_format = '', $single_date_format = '', $single_time_format = '', $EVT_ID = FALSE, $echo = TRUE) {
 		// set and filter date and time formats when a range is returned
-		$date_format = ! empty( $date_format ) ? $date_format : get_option( 'date_format' );
-		$date_format = apply_filters( 'FHEE__espresso_event_date_range__date_format', $date_format );
+		$date_format = ! empty($date_format) ? $date_format : get_option('date_format');
+		$date_format = apply_filters('FHEE__espresso_event_date_range__date_format', $date_format);
 		// get the start and end date with NO time portion
-		$the_event_date = EEH_Event_View::the_earliest_event_date( $date_format, '', $EVT_ID );
-		$the_event_end_date = EEH_Event_View::the_latest_event_date( $date_format, '', $EVT_ID );
+		$the_event_date = EEH_Event_View::the_earliest_event_date($date_format, '', $EVT_ID);
+		$the_event_end_date = EEH_Event_View::the_latest_event_date($date_format, '', $EVT_ID);
 		// now we can determine if date range spans more than one day
-		if ( $the_event_date != $the_event_end_date ) {
-			$time_format = ! empty( $time_format ) ? $time_format : get_option( 'time_format' );
-			$time_format = apply_filters( 'FHEE__espresso_event_date_range__time_format', $time_format );
+		if ($the_event_date != $the_event_end_date) {
+			$time_format = ! empty($time_format) ? $time_format : get_option('time_format');
+			$time_format = apply_filters('FHEE__espresso_event_date_range__time_format', $time_format);
 			$html = sprintf(
 				/* translators: 1: first event date, 2: last event date */
-				esc_html__( '%1$s - %2$s', 'event_espresso' ),
-				EEH_Event_View::the_earliest_event_date( $date_format, $time_format, $EVT_ID ),
-				EEH_Event_View::the_latest_event_date( $date_format, $time_format, $EVT_ID )
+				esc_html__('%1$s - %2$s', 'event_espresso'),
+				EEH_Event_View::the_earliest_event_date($date_format, $time_format, $EVT_ID),
+				EEH_Event_View::the_latest_event_date($date_format, $time_format, $EVT_ID)
 			);
 		} else {
 			// set and filter date and time formats when only a single datetime is returned
-			$single_date_format = ! empty( $single_date_format ) ? $single_date_format : get_option( 'date_format' );
-			$single_time_format = ! empty( $single_time_format ) ? $single_time_format : get_option( 'time_format' );
-			$single_date_format = apply_filters( 'FHEE__espresso_event_date_range__single_date_format', $single_date_format );
-			$single_time_format = apply_filters( 'FHEE__espresso_event_date_range__single_time_format', $single_time_format );
-			$html = EEH_Event_View::the_earliest_event_date( $single_date_format, $single_time_format, $EVT_ID );
+			$single_date_format = ! empty($single_date_format) ? $single_date_format : get_option('date_format');
+			$single_time_format = ! empty($single_time_format) ? $single_time_format : get_option('time_format');
+			$single_date_format = apply_filters('FHEE__espresso_event_date_range__single_date_format', $single_date_format);
+			$single_time_format = apply_filters('FHEE__espresso_event_date_range__single_time_format', $single_time_format);
+			$html = EEH_Event_View::the_earliest_event_date($single_date_format, $single_time_format, $EVT_ID);
 		}
-		if ( $echo ) {
+		if ($echo) {
 			echo $html;
 			return '';
 		}
@@ -571,7 +571,7 @@ 
 	}
 }
 
-if ( ! function_exists( 'espresso_next_upcoming_datetime_obj' )) {
+if ( ! function_exists('espresso_next_upcoming_datetime_obj')) {
 	/**
 	 * espresso_next_upcoming_datetime_obj
 	 * returns the next upcoming datetime object for an event
@@ -579,12 +579,12 @@ 
 	 * @param int $EVT_ID
 	 * @return EE_Datetime|null
 	 */
-	function espresso_next_upcoming_datetime_obj( $EVT_ID = 0 ) {
-		return EEH_Event_View::get_next_upcoming_date_obj( $EVT_ID );
+	function espresso_next_upcoming_datetime_obj($EVT_ID = 0) {
+		return EEH_Event_View::get_next_upcoming_date_obj($EVT_ID);
 	}
 }
 
-if ( ! function_exists( 'espresso_next_upcoming_datetime' ) ) {
+if ( ! function_exists('espresso_next_upcoming_datetime')) {
 	/**
 	 * espresso_next_upcoming_datetime
 	 * returns the start date and time for the next upcoming event.
@@ -595,30 +595,30 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_next_upcoming_datetime( $date_format = '', $time_format = '', $EVT_ID = 0, $echo = true ) {
+	function espresso_next_upcoming_datetime($date_format = '', $time_format = '', $EVT_ID = 0, $echo = true) {
 
-		$date_format = ! empty( $date_format ) ? $date_format : get_option( 'date_format' );
-		$date_format = apply_filters( 'FHEE__espresso_next_upcoming_datetime__date_format', $date_format );
+		$date_format = ! empty($date_format) ? $date_format : get_option('date_format');
+		$date_format = apply_filters('FHEE__espresso_next_upcoming_datetime__date_format', $date_format);
 
-		$time_format = ! empty( $time_format ) ? $time_format : get_option( 'time_format' );
-		$time_format = apply_filters( 'FHEE__espresso_next_upcoming_datetime__time_format', $time_format );
+		$time_format = ! empty($time_format) ? $time_format : get_option('time_format');
+		$time_format = apply_filters('FHEE__espresso_next_upcoming_datetime__time_format', $time_format);
 
-		$datetime_format = trim( $date_format . ' ' . $time_format);
+		$datetime_format = trim($date_format.' '.$time_format);
 
-		$datetime = espresso_next_upcoming_datetime_obj( $EVT_ID );
+		$datetime = espresso_next_upcoming_datetime_obj($EVT_ID);
 
-		if( ! $datetime instanceof EE_Datetime ) {
+		if ( ! $datetime instanceof EE_Datetime) {
 			return '';
 		}
-		if ( $echo ){
-			echo $datetime->get_i18n_datetime( 'DTT_EVT_start', $datetime_format );
+		if ($echo) {
+			echo $datetime->get_i18n_datetime('DTT_EVT_start', $datetime_format);
 			return '';
 		}
-		return $datetime->get_i18n_datetime( 'DTT_EVT_start', $datetime_format );
+		return $datetime->get_i18n_datetime('DTT_EVT_start', $datetime_format);
 	}
 }
 
-if ( ! function_exists( 'espresso_event_date_as_calendar_page' )) {
+if ( ! function_exists('espresso_event_date_as_calendar_page')) {
 	/**
 	 * espresso_event_date_as_calendar_page
 	 * returns the primary date for an event, stylized to appear as the page of a calendar
@@ -626,15 +626,15 @@ 
 	 * @param bool $EVT_ID
 	 * @return string
 	 */
-	function espresso_event_date_as_calendar_page( $EVT_ID = FALSE ) {
-		EEH_Event_View::event_date_as_calendar_page( $EVT_ID );
+	function espresso_event_date_as_calendar_page($EVT_ID = FALSE) {
+		EEH_Event_View::event_date_as_calendar_page($EVT_ID);
 	}
 }
 
 
 
 
-if ( ! function_exists( 'espresso_event_link_url' )) {
+if ( ! function_exists('espresso_event_link_url')) {
 	/**
 	 * espresso_event_link_url
 	 *
@@ -642,18 +642,18 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_event_link_url( $EVT_ID = 0, $echo = TRUE ) {
-		if ( $echo ) {
-			echo EEH_Event_View::event_link_url( $EVT_ID );
+	function espresso_event_link_url($EVT_ID = 0, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Event_View::event_link_url($EVT_ID);
 			return '';
 		}
-		return EEH_Event_View::event_link_url( $EVT_ID );
+		return EEH_Event_View::event_link_url($EVT_ID);
 	}
 }
 
 
 
-if ( ! function_exists( 'espresso_event_has_content_or_excerpt' )) {
+if ( ! function_exists('espresso_event_has_content_or_excerpt')) {
 	/**
 	 *    espresso_event_has_content_or_excerpt
 	 *
@@ -661,15 +661,15 @@ 
 	 * @param bool $EVT_ID
 	 * @return    boolean
 	 */
-	function espresso_event_has_content_or_excerpt( $EVT_ID = FALSE ) {
-		return EEH_Event_View::event_has_content_or_excerpt( $EVT_ID );
+	function espresso_event_has_content_or_excerpt($EVT_ID = FALSE) {
+		return EEH_Event_View::event_has_content_or_excerpt($EVT_ID);
 	}
 }
 
 
 
 
-if ( ! function_exists( 'espresso_event_content_or_excerpt' )) {
+if ( ! function_exists('espresso_event_content_or_excerpt')) {
 	/**
 	 * espresso_event_content_or_excerpt
 	 *
@@ -678,18 +678,18 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_event_content_or_excerpt( $num_words = 55, $more = NULL, $echo = TRUE ) {
-		if ( $echo ) {
-			echo EEH_Event_View::event_content_or_excerpt( $num_words, $more );
+	function espresso_event_content_or_excerpt($num_words = 55, $more = NULL, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Event_View::event_content_or_excerpt($num_words, $more);
 			return '';
 		}
-		return EEH_Event_View::event_content_or_excerpt( $num_words, $more );
+		return EEH_Event_View::event_content_or_excerpt($num_words, $more);
 	}
 }
 
 
 
-if ( ! function_exists( 'espresso_event_phone' )) {
+if ( ! function_exists('espresso_event_phone')) {
 	/**
 	 * espresso_event_phone
 	 *
@@ -697,18 +697,18 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_event_phone( $EVT_ID = 0, $echo = TRUE ) {
-		if ( $echo ) {
-			echo EEH_Event_View::event_phone( $EVT_ID );
+	function espresso_event_phone($EVT_ID = 0, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Event_View::event_phone($EVT_ID);
 			return '';
 		}
-		return EEH_Event_View::event_phone( $EVT_ID );
+		return EEH_Event_View::event_phone($EVT_ID);
 	}
 }
 
 
 
-if ( ! function_exists( 'espresso_edit_event_link' )) {
+if ( ! function_exists('espresso_edit_event_link')) {
 	/**
 	 * espresso_edit_event_link
 	 * returns a link to edit an event
@@ -717,39 +717,39 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_edit_event_link( $EVT_ID = 0, $echo = TRUE ) {
-		if ( $echo ) {
-			echo EEH_Event_View::edit_event_link( $EVT_ID );
+	function espresso_edit_event_link($EVT_ID = 0, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Event_View::edit_event_link($EVT_ID);
 			return '';
 		}
-		return EEH_Event_View::edit_event_link( $EVT_ID );
+		return EEH_Event_View::edit_event_link($EVT_ID);
 	}
 }
 
 
-if ( ! function_exists( 'espresso_organization_name' )) {
+if ( ! function_exists('espresso_organization_name')) {
 	/**
 	 * espresso_organization_name
 	 * @param bool $echo
 	 * @return string
 	 */
 	function espresso_organization_name($echo = TRUE) {
-		if($echo){
-			echo EE_Registry::instance()->CFG->organization->get_pretty( 'name' );
+		if ($echo) {
+			echo EE_Registry::instance()->CFG->organization->get_pretty('name');
 			return '';
 		}
-		return EE_Registry::instance()->CFG->organization->get_pretty( 'name' );
+		return EE_Registry::instance()->CFG->organization->get_pretty('name');
 	}
 }
 
-if ( ! function_exists( 'espresso_organization_address' )) {
+if ( ! function_exists('espresso_organization_address')) {
 	/**
 	 * espresso_organization_address
 	 * @param string $type
 	 * @return string
 	 */
-	function espresso_organization_address( $type = 'inline' ) {
-		if ( EE_Registry::instance()->CFG->organization instanceof EE_Organization_Config ) {
+	function espresso_organization_address($type = 'inline') {
+		if (EE_Registry::instance()->CFG->organization instanceof EE_Organization_Config) {
 			$address = new EventEspresso\core\domain\entities\GenericAddress(
 				EE_Registry::instance()->CFG->organization->address_1,
 				EE_Registry::instance()->CFG->organization->address_2,
@@ -758,129 +758,129 @@ 
 				EE_Registry::instance()->CFG->organization->zip,
 				EE_Registry::instance()->CFG->organization->CNT_ISO
 			);
-			return EEH_Address::format( $address, $type );
+			return EEH_Address::format($address, $type);
 		}
 		return '';
 	}
 }
 
-if ( ! function_exists( 'espresso_organization_email' )) {
+if ( ! function_exists('espresso_organization_email')) {
 	/**
 	 * espresso_organization_email
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_organization_email( $echo = TRUE ) {
-		if($echo){
-			echo EE_Registry::instance()->CFG->organization->get_pretty( 'email' );
+	function espresso_organization_email($echo = TRUE) {
+		if ($echo) {
+			echo EE_Registry::instance()->CFG->organization->get_pretty('email');
 			return '';
 		}
-		return EE_Registry::instance()->CFG->organization->get_pretty( 'email' );
+		return EE_Registry::instance()->CFG->organization->get_pretty('email');
 	}
 }
 
-if ( ! function_exists( 'espresso_organization_logo_url' )) {
+if ( ! function_exists('espresso_organization_logo_url')) {
 	/**
 	 * espresso_organization_logo_url
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_organization_logo_url( $echo = TRUE ) {
-		if($echo){
-			echo EE_Registry::instance()->CFG->organization->get_pretty( 'logo_url' );
+	function espresso_organization_logo_url($echo = TRUE) {
+		if ($echo) {
+			echo EE_Registry::instance()->CFG->organization->get_pretty('logo_url');
 			return '';
 		}
-		return EE_Registry::instance()->CFG->organization->get_pretty( 'logo_url' );
+		return EE_Registry::instance()->CFG->organization->get_pretty('logo_url');
 	}
 }
 
-if ( ! function_exists( 'espresso_organization_facebook' )) {
+if ( ! function_exists('espresso_organization_facebook')) {
 	/**
 	 * espresso_organization_facebook
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_organization_facebook( $echo = TRUE ) {
-		if($echo){
-			echo EE_Registry::instance()->CFG->organization->get_pretty( 'facebook' );
+	function espresso_organization_facebook($echo = TRUE) {
+		if ($echo) {
+			echo EE_Registry::instance()->CFG->organization->get_pretty('facebook');
 			return '';
 		}
-		return EE_Registry::instance()->CFG->organization->get_pretty( 'facebook' );
+		return EE_Registry::instance()->CFG->organization->get_pretty('facebook');
 	}
 }
 
-if ( ! function_exists( 'espresso_organization_twitter' )) {
+if ( ! function_exists('espresso_organization_twitter')) {
 	/**
 	 * espresso_organization_twitter
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_organization_twitter( $echo = TRUE ) {
-		if($echo){
-			echo EE_Registry::instance()->CFG->organization->get_pretty( 'twitter' );
+	function espresso_organization_twitter($echo = TRUE) {
+		if ($echo) {
+			echo EE_Registry::instance()->CFG->organization->get_pretty('twitter');
 			return '';
 		}
-		return EE_Registry::instance()->CFG->organization->get_pretty( 'twitter' );
+		return EE_Registry::instance()->CFG->organization->get_pretty('twitter');
 	}
 }
 
-if ( ! function_exists( 'espresso_organization_linkedin' )) {
+if ( ! function_exists('espresso_organization_linkedin')) {
 	/**
 	 * espresso_organization_linkedin
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_organization_linkedin( $echo = TRUE ) {
-		if($echo){
-			echo EE_Registry::instance()->CFG->organization->get_pretty( 'linkedin' );
+	function espresso_organization_linkedin($echo = TRUE) {
+		if ($echo) {
+			echo EE_Registry::instance()->CFG->organization->get_pretty('linkedin');
 			return '';
 		}
-		return EE_Registry::instance()->CFG->organization->get_pretty( 'linkedin' );
+		return EE_Registry::instance()->CFG->organization->get_pretty('linkedin');
 	}
 }
 
-if ( ! function_exists( 'espresso_organization_pinterest' )) {
+if ( ! function_exists('espresso_organization_pinterest')) {
 	/**
 	 * espresso_organization_pinterest
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_organization_pinterest( $echo = TRUE ) {
-		if($echo){
-			echo EE_Registry::instance()->CFG->organization->get_pretty( 'pinterest' );
+	function espresso_organization_pinterest($echo = TRUE) {
+		if ($echo) {
+			echo EE_Registry::instance()->CFG->organization->get_pretty('pinterest');
 			return '';
 		}
-		return EE_Registry::instance()->CFG->organization->get_pretty( 'pinterest' );
+		return EE_Registry::instance()->CFG->organization->get_pretty('pinterest');
 	}
 }
 
-if ( ! function_exists( 'espresso_organization_google' )) {
+if ( ! function_exists('espresso_organization_google')) {
 	/**
 	 * espresso_organization_google
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_organization_google( $echo = TRUE ) {
-		if($echo){
-			echo EE_Registry::instance()->CFG->organization->get_pretty( 'google' );
+	function espresso_organization_google($echo = TRUE) {
+		if ($echo) {
+			echo EE_Registry::instance()->CFG->organization->get_pretty('google');
 			return '';
 		}
-		return EE_Registry::instance()->CFG->organization->get_pretty( 'google' );
+		return EE_Registry::instance()->CFG->organization->get_pretty('google');
 	}
 }
 
-if ( ! function_exists( 'espresso_organization_instagram' )) {
+if ( ! function_exists('espresso_organization_instagram')) {
 	/**
 	 * espresso_organization_instagram
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_organization_instagram( $echo = TRUE ) {
-		if($echo){
-			echo EE_Registry::instance()->CFG->organization->get_pretty( 'instagram' );
+	function espresso_organization_instagram($echo = TRUE) {
+		if ($echo) {
+			echo EE_Registry::instance()->CFG->organization->get_pretty('instagram');
 			return '';
 		}
-		return EE_Registry::instance()->CFG->organization->get_pretty( 'instagram' );
+		return EE_Registry::instance()->CFG->organization->get_pretty('instagram');
 	}
 }
 
@@ -890,7 +890,7 @@ 
 
 
 
-if ( ! function_exists( 'espresso_event_venues' )) {
+if ( ! function_exists('espresso_event_venues')) {
 	/**
 	 * espresso_event_venues
 	 *
@@ -904,7 +904,7 @@ 
 
 
 
-if ( ! function_exists( 'espresso_venue_id' )) {
+if ( ! function_exists('espresso_venue_id')) {
 	/**
 	 *    espresso_venue_name
 	 *
@@ -912,15 +912,15 @@ 
 	 * @param     int $EVT_ID
 	 * @return    string
 	 */
-	function espresso_venue_id( $EVT_ID = 0 ) {
-		$venue = EEH_Venue_View::get_venue( $EVT_ID );
+	function espresso_venue_id($EVT_ID = 0) {
+		$venue = EEH_Venue_View::get_venue($EVT_ID);
 		return $venue instanceof EE_Venue ? $venue->ID() : 0;
 	}
 }
 
 
 
-if ( ! function_exists( 'espresso_is_venue_private' ) ) {
+if ( ! function_exists('espresso_is_venue_private')) {
 	/**
 	 * Return whether a venue is private or not.
 	 * @see EEH_Venue_View::get_venue() for more info on expected return results.
@@ -929,45 +929,45 @@ 
 	 *
 	 * @return bool | null
 	 */
-	function espresso_is_venue_private( $VNU_ID = 0 ) {
-		return EEH_Venue_View::is_venue_private( $VNU_ID );
+	function espresso_is_venue_private($VNU_ID = 0) {
+		return EEH_Venue_View::is_venue_private($VNU_ID);
 	}
 }
 
 
 
-if ( ! function_exists( 'espresso_venue_is_password_protected' ) ) {
+if ( ! function_exists('espresso_venue_is_password_protected')) {
 	/**
 	 * returns true or false if a venue is password protected or not
 	 *
 	 * @param int     $VNU_ID optional, the venue id to check.
 	 * @return string
 	 */
-	function espresso_venue_is_password_protected( $VNU_ID = 0 ) {
-		EE_Registry::instance()->load_helper( 'Venue_View' );
-		return EEH_Venue_View::is_venue_password_protected( $VNU_ID );
+	function espresso_venue_is_password_protected($VNU_ID = 0) {
+		EE_Registry::instance()->load_helper('Venue_View');
+		return EEH_Venue_View::is_venue_password_protected($VNU_ID);
 	}
 }
 
 
 
-if ( ! function_exists( 'espresso_password_protected_venue_form' ) ) {
+if ( ! function_exists('espresso_password_protected_venue_form')) {
 	/**
 	 * Returns a password form if venue is password protected.
 	 *
 	 * @param int     $VNU_ID optional, the venue id to check.
 	 * @return string
 	 */
-	function espresso_password_protected_venue_form( $VNU_ID = 0 ) {
-		EE_Registry::instance()->load_helper( 'Venue_View' );
-		return EEH_Venue_View::password_protected_venue_form( $VNU_ID );
+	function espresso_password_protected_venue_form($VNU_ID = 0) {
+		EE_Registry::instance()->load_helper('Venue_View');
+		return EEH_Venue_View::password_protected_venue_form($VNU_ID);
 	}
 }
 
 
 
 
-if ( ! function_exists( 'espresso_venue_name' )) {
+if ( ! function_exists('espresso_venue_name')) {
 	/**
 	 *    espresso_venue_name
 	 *
@@ -977,19 +977,19 @@ 
 	 * @param bool   $echo
 	 * @return    string
 	 */
-	function espresso_venue_name( $VNU_ID = 0, $link_to = 'details', $echo = TRUE ) {
-		if($echo){
-			echo EEH_Venue_View::venue_name( $link_to, $VNU_ID );
+	function espresso_venue_name($VNU_ID = 0, $link_to = 'details', $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Venue_View::venue_name($link_to, $VNU_ID);
 			return '';
 		}
-		return EEH_Venue_View::venue_name( $link_to, $VNU_ID );
+		return EEH_Venue_View::venue_name($link_to, $VNU_ID);
 	}
 }
 
 
 
 
-if ( ! function_exists( 'espresso_venue_link' )) {
+if ( ! function_exists('espresso_venue_link')) {
 	/**
 	 * 	espresso_venue_link
 	 *
@@ -998,14 +998,14 @@ 
 	 *  @param 	string 	$text
 	 *  @return 	string
 	 */
-	function espresso_venue_link( $VNU_ID = 0, $text = '' ) {
-		return EEH_Venue_View::venue_details_link( $VNU_ID, $text );
+	function espresso_venue_link($VNU_ID = 0, $text = '') {
+		return EEH_Venue_View::venue_details_link($VNU_ID, $text);
 	}
 }
 
 
 
-if ( ! function_exists( 'espresso_venue_description' )) {
+if ( ! function_exists('espresso_venue_description')) {
 	/**
 	 *    espresso_venue_description
 	 *
@@ -1014,17 +1014,17 @@ 
 	 * @param bool $echo
 	 * @return    string
 	 */
-	function espresso_venue_description( $VNU_ID = FALSE, $echo = TRUE ) {
-		if($echo){
-			echo EEH_Venue_View::venue_description( $VNU_ID );
+	function espresso_venue_description($VNU_ID = FALSE, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Venue_View::venue_description($VNU_ID);
 			return '';
 		}
-		return EEH_Venue_View::venue_description( $VNU_ID );
+		return EEH_Venue_View::venue_description($VNU_ID);
 	}
 }
 
 
-if ( ! function_exists( 'espresso_venue_excerpt' )) {
+if ( ! function_exists('espresso_venue_excerpt')) {
 	/**
 	 *    espresso_venue_excerpt
 	 *
@@ -1033,18 +1033,18 @@ 
 	 * @param bool $echo
 	 * @return    string
 	 */
-	function espresso_venue_excerpt( $VNU_ID = 0,  $echo = TRUE ) {
-		if ( $echo ) {
-			echo EEH_Venue_View::venue_excerpt( $VNU_ID );
+	function espresso_venue_excerpt($VNU_ID = 0, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Venue_View::venue_excerpt($VNU_ID);
 			return '';
 		}
-		return EEH_Venue_View::venue_excerpt( $VNU_ID );
+		return EEH_Venue_View::venue_excerpt($VNU_ID);
 	}
 }
 
 
 
-if ( ! function_exists( 'espresso_venue_categories' )) {
+if ( ! function_exists('espresso_venue_categories')) {
 	/**
 	 * espresso_venue_categories
 	 * returns the terms associated with a venue
@@ -1054,17 +1054,17 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_venue_categories( $VNU_ID = 0, $hide_uncategorized = TRUE,  $echo = TRUE ) {
-		if ( $echo ) {
-			echo EEH_Venue_View::venue_categories( $VNU_ID, $hide_uncategorized );
+	function espresso_venue_categories($VNU_ID = 0, $hide_uncategorized = TRUE, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Venue_View::venue_categories($VNU_ID, $hide_uncategorized);
 			return '';
 		}
-		return EEH_Venue_View::venue_categories( $VNU_ID, $hide_uncategorized );
+		return EEH_Venue_View::venue_categories($VNU_ID, $hide_uncategorized);
 	}
 }
 
 
-if ( ! function_exists( 'espresso_venue_address' )) {
+if ( ! function_exists('espresso_venue_address')) {
 	/**
 	 * espresso_venue_address
 	 * returns a formatted block of html  for displaying a venue's address
@@ -1074,17 +1074,17 @@ 
 	 * @param bool   $echo
 	 * @return string
 	 */
-	function espresso_venue_address( $type = 'multiline', $VNU_ID = 0, $echo = TRUE ) {
-		if ( $echo ) {
-			echo EEH_Venue_View::venue_address( $type, $VNU_ID );
+	function espresso_venue_address($type = 'multiline', $VNU_ID = 0, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Venue_View::venue_address($type, $VNU_ID);
 			return '';
 		}
-		return EEH_Venue_View::venue_address( $type, $VNU_ID );
+		return EEH_Venue_View::venue_address($type, $VNU_ID);
 	}
 }
 
 
-if ( ! function_exists( 'espresso_venue_raw_address' )) {
+if ( ! function_exists('espresso_venue_raw_address')) {
 	/**
 	 * espresso_venue_address
 	 * returns an UN-formatted string containing a venue's address
@@ -1094,17 +1094,17 @@ 
 	 * @param bool     $echo
 	 * @return string
 	 */
-	function espresso_venue_raw_address( $type = 'multiline', $VNU_ID = 0, $echo = TRUE ) {
-		if ( $echo ) {
-			echo EEH_Venue_View::venue_address( $type, $VNU_ID, FALSE, FALSE );
+	function espresso_venue_raw_address($type = 'multiline', $VNU_ID = 0, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Venue_View::venue_address($type, $VNU_ID, FALSE, FALSE);
 			return '';
 		}
-		return EEH_Venue_View::venue_address( $type, $VNU_ID, FALSE, FALSE );
+		return EEH_Venue_View::venue_address($type, $VNU_ID, FALSE, FALSE);
 	}
 }
 
 
-if ( ! function_exists( 'espresso_venue_has_address' )) {
+if ( ! function_exists('espresso_venue_has_address')) {
 	/**
 	 * espresso_venue_has_address
 	 * returns TRUE or FALSE if a Venue has address information
@@ -1112,13 +1112,13 @@ 
 	 * @param int $VNU_ID
 	 * @return bool
 	 */
-	function espresso_venue_has_address( $VNU_ID = 0 ) {
-		return EEH_Venue_View::venue_has_address( $VNU_ID );
+	function espresso_venue_has_address($VNU_ID = 0) {
+		return EEH_Venue_View::venue_has_address($VNU_ID);
 	}
 }
 
 
-if ( ! function_exists( 'espresso_venue_gmap' )) {
+if ( ! function_exists('espresso_venue_gmap')) {
 	/**
 	 * espresso_venue_gmap
 	 * returns a google map for the venue address
@@ -1129,17 +1129,17 @@ 
 	 * @param bool     $echo
 	 * @return string
 	 */
-	function espresso_venue_gmap( $VNU_ID = 0, $map_ID = FALSE, $gmap = array(), $echo = TRUE  ) {
-		if ( $echo ) {
-			echo EEH_Venue_View::venue_gmap( $VNU_ID, $map_ID, $gmap );
+	function espresso_venue_gmap($VNU_ID = 0, $map_ID = FALSE, $gmap = array(), $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Venue_View::venue_gmap($VNU_ID, $map_ID, $gmap);
 			return '';
 		}
-		return EEH_Venue_View::venue_gmap( $VNU_ID, $map_ID, $gmap );
+		return EEH_Venue_View::venue_gmap($VNU_ID, $map_ID, $gmap);
 	}
 }
 
 
-if ( ! function_exists( 'espresso_venue_phone' )) {
+if ( ! function_exists('espresso_venue_phone')) {
 	/**
 	 * espresso_venue_phone
 	 *
@@ -1147,18 +1147,18 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_venue_phone( $VNU_ID = 0, $echo = TRUE ) {
-		if ( $echo ) {
-			echo EEH_Venue_View::venue_phone( $VNU_ID );
+	function espresso_venue_phone($VNU_ID = 0, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Venue_View::venue_phone($VNU_ID);
 			return '';
 		}
-		return EEH_Venue_View::venue_phone( $VNU_ID );
+		return EEH_Venue_View::venue_phone($VNU_ID);
 	}
 }
 
 
 
-if ( ! function_exists( 'espresso_venue_website' )) {
+if ( ! function_exists('espresso_venue_website')) {
 	/**
 	 * espresso_venue_website
 	 *
@@ -1166,18 +1166,18 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_venue_website( $VNU_ID = 0, $echo = TRUE ) {
-		if ( $echo ) {
-			echo EEH_Venue_View::venue_website_link( $VNU_ID );
+	function espresso_venue_website($VNU_ID = 0, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Venue_View::venue_website_link($VNU_ID);
 			return '';
 		}
-		return EEH_Venue_View::venue_website_link( $VNU_ID );
+		return EEH_Venue_View::venue_website_link($VNU_ID);
 	}
 }
 
 
 
-if ( ! function_exists( 'espresso_edit_venue_link' )) {
+if ( ! function_exists('espresso_edit_venue_link')) {
 	/**
 	 * espresso_edit_venue_link
 	 *
@@ -1185,12 +1185,12 @@ 
 	 * @param bool $echo
 	 * @return string
 	 */
-	function espresso_edit_venue_link( $VNU_ID = 0, $echo = TRUE ) {
-		if($echo){
-			echo EEH_Venue_View::edit_venue_link( $VNU_ID );
+	function espresso_edit_venue_link($VNU_ID = 0, $echo = TRUE) {
+		if ($echo) {
+			echo EEH_Venue_View::edit_venue_link($VNU_ID);
 			return '';
 		}
-		return EEH_Venue_View::edit_venue_link( $VNU_ID );
+		return EEH_Venue_View::edit_venue_link($VNU_ID);
 	}
 }
 

core/db_classes/EE_Base_Class.class.php

Indentation +3333 added lines, -3333 removed lines

@@ -13,3348 +13,3348 @@
 abstract class EE_Base_Class
 {
 
-    /**
-     * This is an array of the original properties and values provided during construction
-     * of this model object. (keys are model field names, values are their values).
-     * This list is important to remember so that when we are merging data from the db, we know
-     * which values to override and which to not override.
-     *
-     * @var array
-     */
-    protected $_props_n_values_provided_in_constructor;
-
-    /**
-     * Timezone
-     * This gets set by the "set_timezone()" method so that we know what timezone incoming strings|timestamps are in.
-     * This can also be used before a get to set what timezone you want strings coming out of the object to be in.  NOT
-     * all EE_Base_Class child classes use this property but any that use a EE_Datetime_Field data type will have
-     * access to it.
-     *
-     * @var string
-     */
-    protected $_timezone;
-
-    /**
-     * date format
-     * pattern or format for displaying dates
-     *
-     * @var string $_dt_frmt
-     */
-    protected $_dt_frmt;
-
-    /**
-     * time format
-     * pattern or format for displaying time
-     *
-     * @var string $_tm_frmt
-     */
-    protected $_tm_frmt;
-
-    /**
-     * This property is for holding a cached array of object properties indexed by property name as the key.
-     * The purpose of this is for setting a cache on properties that may have calculated values after a
-     * prepare_for_get.  That way the cache can be checked first and the calculated property returned instead of having
-     * to recalculate. Used by _set_cached_property() and _get_cached_property() methods.
-     *
-     * @var array
-     */
-    protected $_cached_properties = array();
-
-    /**
-     * An array containing keys of the related model, and values are either an array of related mode objects or a
-     * single
-     * related model object. see the model's _model_relations. The keys should match those specified. And if the
-     * relation is of type EE_Belongs_To (or one of its children), then there should only be ONE related model object,
-     * all others have an array)
-     *
-     * @var array
-     */
-    protected $_model_relations = array();
-
-    /**
-     * Array where keys are field names (see the model's _fields property) and values are their values. To see what
-     * their types should be, look at what that field object returns on its prepare_for_get and prepare_for_set methods)
-     *
-     * @var array
-     */
-    protected $_fields = array();
-
-    /**
-     * @var boolean indicating whether or not this model object is intended to ever be saved
-     * For example, we might create model objects intended to only be used for the duration
-     * of this request and to be thrown away, and if they were accidentally saved
-     * it would be a bug.
-     */
-    protected $_allow_persist = true;
-
-    /**
-     * @var boolean indicating whether or not this model object's properties have changed since construction
-     */
-    protected $_has_changes = false;
-
-    /**
-     * @var EEM_Base
-     */
-    protected $_model;
-
-    /**
-     * This is a cache of results from custom selections done on a query that constructs this entity. The only purpose
-     * for these values is for retrieval of the results, they are not further queryable and they are not persisted to
-     * the db.  They also do not automatically update if there are any changes to the data that produced their results.
-     * The format is a simple array of field_alias => field_value.  So for instance if a custom select was something
-     * like,  "Select COUNT(Registration.REG_ID) as Registration_Count ...", then the resulting value will be in this
-     * array as:
-     * array(
-     *  'Registration_Count' => 24
-     * );
-     * Note: if the custom select configuration for the query included a data type, the value will be in the data type
-     * provided for the query (@see EventEspresso\core\domain\values\model\CustomSelects::__construct phpdocs for more
-     * info)
-     *
-     * @var array
-     */
-    protected $custom_selection_results = array();
-
-
-    /**
-     * basic constructor for Event Espresso classes, performs any necessary initialization, and verifies it's children
-     * play nice
-     *
-     * @param array   $fieldValues                             where each key is a field (ie, array key in the 2nd
-     *                                                         layer of the model's _fields array, (eg, EVT_ID,
-     *                                                         TXN_amount, QST_name, etc) and values are their values
-     * @param boolean $bydb                                    a flag for setting if the class is instantiated by the
-     *                                                         corresponding db model or not.
-     * @param string  $timezone                                indicate what timezone you want any datetime fields to
-     *                                                         be in when instantiating a EE_Base_Class object.
-     * @param array   $date_formats                            An array of date formats to set on construct where first
-     *                                                         value is the date_format and second value is the time
-     *                                                         format.
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    protected function __construct($fieldValues = array(), $bydb = false, $timezone = '', $date_formats = array())
-    {
-        $className = get_class($this);
-        do_action("AHEE__{$className}__construct", $this, $fieldValues);
-        $model = $this->get_model();
-        $model_fields = $model->field_settings(false);
-        // ensure $fieldValues is an array
-        $fieldValues = is_array($fieldValues) ? $fieldValues : array($fieldValues);
-        // verify client code has not passed any invalid field names
-        foreach ($fieldValues as $field_name => $field_value) {
-            if (! isset($model_fields[ $field_name ])) {
-                throw new EE_Error(
-                    sprintf(
-                        esc_html__(
-                            'Invalid field (%s) passed to constructor of %s. Allowed fields are :%s',
-                            'event_espresso'
-                        ),
-                        $field_name,
-                        get_class($this),
-                        implode(', ', array_keys($model_fields))
-                    )
-                );
-            }
-        }
-        $this->_timezone = EEH_DTT_Helper::get_valid_timezone_string($timezone);
-        if (! empty($date_formats) && is_array($date_formats)) {
-            list($this->_dt_frmt, $this->_tm_frmt) = $date_formats;
-        } else {
-            // set default formats for date and time
-            $this->_dt_frmt = (string) get_option('date_format', 'Y-m-d');
-            $this->_tm_frmt = (string) get_option('time_format', 'g:i a');
-        }
-        // if db model is instantiating
-        if ($bydb) {
-            // client code has indicated these field values are from the database
-            foreach ($model_fields as $fieldName => $field) {
-                $this->set_from_db(
-                    $fieldName,
-                    isset($fieldValues[ $fieldName ]) ? $fieldValues[ $fieldName ] : null
-                );
-            }
-        } else {
-            // we're constructing a brand
-            // new instance of the model object. Generally, this means we'll need to do more field validation
-            foreach ($model_fields as $fieldName => $field) {
-                $this->set(
-                    $fieldName,
-                    isset($fieldValues[ $fieldName ]) ? $fieldValues[ $fieldName ] : null,
-                    true
-                );
-            }
-        }
-        // remember what values were passed to this constructor
-        $this->_props_n_values_provided_in_constructor = $fieldValues;
-        // remember in entity mapper
-        if (! $bydb && $model->has_primary_key_field() && $this->ID()) {
-            $model->add_to_entity_map($this);
-        }
-        // setup all the relations
-        foreach ($model->relation_settings() as $relation_name => $relation_obj) {
-            if ($relation_obj instanceof EE_Belongs_To_Relation) {
-                $this->_model_relations[ $relation_name ] = null;
-            } else {
-                $this->_model_relations[ $relation_name ] = array();
-            }
-        }
-        /**
-         * Action done at the end of each model object construction
-         *
-         * @param EE_Base_Class $this the model object just created
-         */
-        do_action('AHEE__EE_Base_Class__construct__finished', $this);
-    }
-
-
-    /**
-     * Gets whether or not this model object is allowed to persist/be saved to the database.
-     *
-     * @return boolean
-     */
-    public function allow_persist()
-    {
-        return $this->_allow_persist;
-    }
-
-
-    /**
-     * Sets whether or not this model object should be allowed to be saved to the DB.
-     * Normally once this is set to FALSE you wouldn't set it back to TRUE, unless
-     * you got new information that somehow made you change your mind.
-     *
-     * @param boolean $allow_persist
-     * @return boolean
-     */
-    public function set_allow_persist($allow_persist)
-    {
-        return $this->_allow_persist = $allow_persist;
-    }
-
-
-    /**
-     * Gets the field's original value when this object was constructed during this request.
-     * This can be helpful when determining if a model object has changed or not
-     *
-     * @param string $field_name
-     * @return mixed|null
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get_original($field_name)
-    {
-        if (isset($this->_props_n_values_provided_in_constructor[ $field_name ])
-            && $field_settings = $this->get_model()->field_settings_for($field_name)
-        ) {
-            return $field_settings->prepare_for_get($this->_props_n_values_provided_in_constructor[ $field_name ]);
-        }
-        return null;
-    }
-
-
-    /**
-     * @param EE_Base_Class $obj
-     * @return string
-     */
-    public function get_class($obj)
-    {
-        return get_class($obj);
-    }
-
-
-    /**
-     * Overrides parent because parent expects old models.
-     * This also doesn't do any validation, and won't work for serialized arrays
-     *
-     * @param    string $field_name
-     * @param    mixed  $field_value
-     * @param bool      $use_default
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @throws ReflectionException
-     * @throws ReflectionException
-     */
-    public function set($field_name, $field_value, $use_default = false)
-    {
-        // if not using default and nothing has changed, and object has already been setup (has ID),
-        // then don't do anything
-        if (! $use_default
-            && $this->_fields[ $field_name ] === $field_value
-            && $this->ID()
-        ) {
-            return;
-        }
-        $model = $this->get_model();
-        $this->_has_changes = true;
-        $field_obj = $model->field_settings_for($field_name);
-        if ($field_obj instanceof EE_Model_Field_Base) {
-            // if ( method_exists( $field_obj, 'set_timezone' )) {
-            if ($field_obj instanceof EE_Datetime_Field) {
-                $field_obj->set_timezone($this->_timezone);
-                $field_obj->set_date_format($this->_dt_frmt);
-                $field_obj->set_time_format($this->_tm_frmt);
-            }
-            $holder_of_value = $field_obj->prepare_for_set($field_value);
-            // should the value be null?
-            if (($field_value === null || $holder_of_value === null || $holder_of_value === '') && $use_default) {
-                $this->_fields[ $field_name ] = $field_obj->get_default_value();
-                /**
-                 * To save having to refactor all the models, if a default value is used for a
-                 * EE_Datetime_Field, and that value is not null nor is it a DateTime
-                 * object.  Then let's do a set again to ensure that it becomes a DateTime
-                 * object.
-                 *
-                 * @since 4.6.10+
-                 */
-                if ($field_obj instanceof EE_Datetime_Field
-                    && $this->_fields[ $field_name ] !== null
-                    && ! $this->_fields[ $field_name ] instanceof DateTime
-                ) {
-                    empty($this->_fields[ $field_name ])
-                        ? $this->set($field_name, time())
-                        : $this->set($field_name, $this->_fields[ $field_name ]);
-                }
-            } else {
-                $this->_fields[ $field_name ] = $holder_of_value;
-            }
-            // if we're not in the constructor...
-            // now check if what we set was a primary key
-            if (// note: props_n_values_provided_in_constructor is only set at the END of the constructor
-                $this->_props_n_values_provided_in_constructor
-                && $field_value
-                && $field_name === $model->primary_key_name()
-            ) {
-                // if so, we want all this object's fields to be filled either with
-                // what we've explicitly set on this model
-                // or what we have in the db
-                // echo "setting primary key!";
-                $fields_on_model = self::_get_model(get_class($this))->field_settings();
-                $obj_in_db = self::_get_model(get_class($this))->get_one_by_ID($field_value);
-                foreach ($fields_on_model as $field_obj) {
-                    if (! array_key_exists($field_obj->get_name(), $this->_props_n_values_provided_in_constructor)
-                        && $field_obj->get_name() !== $field_name
-                    ) {
-                        $this->set($field_obj->get_name(), $obj_in_db->get($field_obj->get_name()));
-                    }
-                }
-                // oh this model object has an ID? well make sure its in the entity mapper
-                $model->add_to_entity_map($this);
-            }
-            // let's unset any cache for this field_name from the $_cached_properties property.
-            $this->_clear_cached_property($field_name);
-        } else {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'A valid EE_Model_Field_Base could not be found for the given field name: %s',
-                        'event_espresso'
-                    ),
-                    $field_name
-                )
-            );
-        }
-    }
-
-
-    /**
-     * Set custom select values for model.
-     *
-     * @param array $custom_select_values
-     */
-    public function setCustomSelectsValues(array $custom_select_values)
-    {
-        $this->custom_selection_results = $custom_select_values;
-    }
-
-
-    /**
-     * Returns the custom select value for the provided alias if its set.
-     * If not set, returns null.
-     *
-     * @param string $alias
-     * @return string|int|float|null
-     */
-    public function getCustomSelect($alias)
-    {
-        return isset($this->custom_selection_results[ $alias ])
-            ? $this->custom_selection_results[ $alias ]
-            : null;
-    }
-
-
-    /**
-     * This sets the field value on the db column if it exists for the given $column_name or
-     * saves it to EE_Extra_Meta if the given $column_name does not match a db column.
-     *
-     * @see EE_message::get_column_value for related documentation on the necessity of this method.
-     * @param string $field_name  Must be the exact column name.
-     * @param mixed  $field_value The value to set.
-     * @return int|bool @see EE_Base_Class::update_extra_meta() for return docs.
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_field_or_extra_meta($field_name, $field_value)
-    {
-        if ($this->get_model()->has_field($field_name)) {
-            $this->set($field_name, $field_value);
-            return true;
-        }
-        // ensure this object is saved first so that extra meta can be properly related.
-        $this->save();
-        return $this->update_extra_meta($field_name, $field_value);
-    }
-
-
-    /**
-     * This retrieves the value of the db column set on this class or if that's not present
-     * it will attempt to retrieve from extra_meta if found.
-     * Example Usage:
-     * Via EE_Message child class:
-     * Due to the dynamic nature of the EE_messages system, EE_messengers will always have a "to",
-     * "from", "subject", and "content" field (as represented in the EE_Message schema), however they may
-     * also have additional main fields specific to the messenger.  The system accommodates those extra
-     * fields through the EE_Extra_Meta table.  This method allows for EE_messengers to retrieve the
-     * value for those extra fields dynamically via the EE_message object.
-     *
-     * @param  string $field_name expecting the fully qualified field name.
-     * @return mixed|null  value for the field if found.  null if not found.
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get_field_or_extra_meta($field_name)
-    {
-        if ($this->get_model()->has_field($field_name)) {
-            $column_value = $this->get($field_name);
-        } else {
-            // This isn't a column in the main table, let's see if it is in the extra meta.
-            $column_value = $this->get_extra_meta($field_name, true, null);
-        }
-        return $column_value;
-    }
-
-
-    /**
-     * See $_timezone property for description of what the timezone property is for.  This SETS the timezone internally
-     * for being able to reference what timezone we are running conversions on when converting TO the internal timezone
-     * (UTC Unix Timestamp) for the object OR when converting FROM the internal timezone (UTC Unix Timestamp). This is
-     * available to all child classes that may be using the EE_Datetime_Field for a field data type.
-     *
-     * @access public
-     * @param string $timezone A valid timezone string as described by @link http://www.php.net/manual/en/timezones.php
-     * @return void
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_timezone($timezone = '')
-    {
-        $this->_timezone = EEH_DTT_Helper::get_valid_timezone_string($timezone);
-        // make sure we clear all cached properties because they won't be relevant now
-        $this->_clear_cached_properties();
-        // make sure we update field settings and the date for all EE_Datetime_Fields
-        $model_fields = $this->get_model()->field_settings(false);
-        foreach ($model_fields as $field_name => $field_obj) {
-            if ($field_obj instanceof EE_Datetime_Field) {
-                $field_obj->set_timezone($this->_timezone);
-                if (isset($this->_fields[ $field_name ]) && $this->_fields[ $field_name ] instanceof DateTime) {
-                    EEH_DTT_Helper::setTimezone($this->_fields[ $field_name ], new DateTimeZone($this->_timezone));
-                }
-            }
-        }
-    }
-
-
-    /**
-     * This just returns whatever is set for the current timezone.
-     *
-     * @access public
-     * @return string timezone string
-     */
-    public function get_timezone()
-    {
-        return $this->_timezone;
-    }
-
-
-    /**
-     * This sets the internal date format to what is sent in to be used as the new default for the class
-     * internally instead of wp set date format options
-     *
-     * @since 4.6
-     * @param string $format should be a format recognizable by PHP date() functions.
-     */
-    public function set_date_format($format)
-    {
-        $this->_dt_frmt = $format;
-        // clear cached_properties because they won't be relevant now.
-        $this->_clear_cached_properties();
-    }
-
-
-    /**
-     * This sets the internal time format string to what is sent in to be used as the new default for the
-     * class internally instead of wp set time format options.
-     *
-     * @since 4.6
-     * @param string $format should be a format recognizable by PHP date() functions.
-     */
-    public function set_time_format($format)
-    {
-        $this->_tm_frmt = $format;
-        // clear cached_properties because they won't be relevant now.
-        $this->_clear_cached_properties();
-    }
-
-
-    /**
-     * This returns the current internal set format for the date and time formats.
-     *
-     * @param bool $full           if true (default), then return the full format.  Otherwise will return an array
-     *                             where the first value is the date format and the second value is the time format.
-     * @return mixed string|array
-     */
-    public function get_format($full = true)
-    {
-        return $full ? $this->_dt_frmt . ' ' . $this->_tm_frmt : array($this->_dt_frmt, $this->_tm_frmt);
-    }
-
-
-    /**
-     * cache
-     * stores the passed model object on the current model object.
-     * In certain circumstances, we can use this cached model object instead of querying for another one entirely.
-     *
-     * @param string        $relationName    one of the keys in the _model_relations array on the model. Eg
-     *                                       'Registration' associated with this model object
-     * @param EE_Base_Class $object_to_cache that has a relation to this model object. (Eg, if this is a Transaction,
-     *                                       that could be a payment or a registration)
-     * @param null          $cache_id        a string or number that will be used as the key for any Belongs_To_Many
-     *                                       items which will be stored in an array on this object
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @return mixed    index into cache, or just TRUE if the relation is of type Belongs_To (because there's only one
-     *                                       related thing, no array)
-     */
-    public function cache($relationName = '', $object_to_cache = null, $cache_id = null)
-    {
-        // its entirely possible that there IS no related object yet in which case there is nothing to cache.
-        if (! $object_to_cache instanceof EE_Base_Class) {
-            return false;
-        }
-        // also get "how" the object is related, or throw an error
-        if (! $relationship_to_model = $this->get_model()->related_settings_for($relationName)) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__('There is no relationship to %s on a %s. Cannot cache it', 'event_espresso'),
-                    $relationName,
-                    get_class($this)
-                )
-            );
-        }
-        // how many things are related ?
-        if ($relationship_to_model instanceof EE_Belongs_To_Relation) {
-            // if it's a "belongs to" relationship, then there's only one related model object
-            // eg, if this is a registration, there's only 1 attendee for it
-            // so for these model objects just set it to be cached
-            $this->_model_relations[ $relationName ] = $object_to_cache;
-            $return = true;
-        } else {
-            // otherwise, this is the "many" side of a one to many relationship,
-            // so we'll add the object to the array of related objects for that type.
-            // eg: if this is an event, there are many registrations for that event,
-            // so we cache the registrations in an array
-            if (! is_array($this->_model_relations[ $relationName ])) {
-                // if for some reason, the cached item is a model object,
-                // then stick that in the array, otherwise start with an empty array
-                $this->_model_relations[ $relationName ] = $this->_model_relations[ $relationName ]
-                                                           instanceof
-                                                           EE_Base_Class
-                    ? array($this->_model_relations[ $relationName ]) : array();
-            }
-            // first check for a cache_id which is normally empty
-            if (! empty($cache_id)) {
-                // if the cache_id exists, then it means we are purposely trying to cache this
-                // with a known key that can then be used to retrieve the object later on
-                $this->_model_relations[ $relationName ][ $cache_id ] = $object_to_cache;
-                $return = $cache_id;
-            } elseif ($object_to_cache->ID()) {
-                // OR the cached object originally came from the db, so let's just use it's PK for an ID
-                $this->_model_relations[ $relationName ][ $object_to_cache->ID() ] = $object_to_cache;
-                $return = $object_to_cache->ID();
-            } else {
-                // OR it's a new object with no ID, so just throw it in the array with an auto-incremented ID
-                $this->_model_relations[ $relationName ][] = $object_to_cache;
-                // move the internal pointer to the end of the array
-                end($this->_model_relations[ $relationName ]);
-                // and grab the key so that we can return it
-                $return = key($this->_model_relations[ $relationName ]);
-            }
-        }
-        return $return;
-    }
-
-
-    /**
-     * For adding an item to the cached_properties property.
-     *
-     * @access protected
-     * @param string      $fieldname the property item the corresponding value is for.
-     * @param mixed       $value     The value we are caching.
-     * @param string|null $cache_type
-     * @return void
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected function _set_cached_property($fieldname, $value, $cache_type = null)
-    {
-        // first make sure this property exists
-        $this->get_model()->field_settings_for($fieldname);
-        $cache_type = empty($cache_type) ? 'standard' : $cache_type;
-        $this->_cached_properties[ $fieldname ][ $cache_type ] = $value;
-    }
-
-
-    /**
-     * This returns the value cached property if it exists OR the actual property value if the cache doesn't exist.
-     * This also SETS the cache if we return the actual property!
-     *
-     * @param string $fieldname        the name of the property we're trying to retrieve
-     * @param bool   $pretty
-     * @param string $extra_cache_ref  This allows the user to specify an extra cache ref for the given property
-     *                                 (in cases where the same property may be used for different outputs
-     *                                 - i.e. datetime, money etc.)
-     *                                 It can also accept certain pre-defined "schema" strings
-     *                                 to define how to output the property.
-     *                                 see the field's prepare_for_pretty_echoing for what strings can be used
-     * @return mixed                   whatever the value for the property is we're retrieving
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected function _get_cached_property($fieldname, $pretty = false, $extra_cache_ref = null)
-    {
-        // verify the field exists
-        $model = $this->get_model();
-        $model->field_settings_for($fieldname);
-        $cache_type = $pretty ? 'pretty' : 'standard';
-        $cache_type .= ! empty($extra_cache_ref) ? '_' . $extra_cache_ref : '';
-        if (isset($this->_cached_properties[ $fieldname ][ $cache_type ])) {
-            return $this->_cached_properties[ $fieldname ][ $cache_type ];
-        }
-        $value = $this->_get_fresh_property($fieldname, $pretty, $extra_cache_ref);
-        $this->_set_cached_property($fieldname, $value, $cache_type);
-        return $value;
-    }
-
-
-    /**
-     * If the cache didn't fetch the needed item, this fetches it.
-     *
-     * @param string $fieldname
-     * @param bool   $pretty
-     * @param string $extra_cache_ref
-     * @return mixed
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    protected function _get_fresh_property($fieldname, $pretty = false, $extra_cache_ref = null)
-    {
-        $field_obj = $this->get_model()->field_settings_for($fieldname);
-        // If this is an EE_Datetime_Field we need to make sure timezone, formats, and output are correct
-        if ($field_obj instanceof EE_Datetime_Field) {
-            $this->_prepare_datetime_field($field_obj, $pretty, $extra_cache_ref);
-        }
-        if (! isset($this->_fields[ $fieldname ])) {
-            $this->_fields[ $fieldname ] = null;
-        }
-        $value = $pretty
-            ? $field_obj->prepare_for_pretty_echoing($this->_fields[ $fieldname ], $extra_cache_ref)
-            : $field_obj->prepare_for_get($this->_fields[ $fieldname ]);
-        return $value;
-    }
-
-
-    /**
-     * set timezone, formats, and output for EE_Datetime_Field objects
-     *
-     * @param \EE_Datetime_Field $datetime_field
-     * @param bool               $pretty
-     * @param null               $date_or_time
-     * @return void
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected function _prepare_datetime_field(
-        EE_Datetime_Field $datetime_field,
-        $pretty = false,
-        $date_or_time = null
-    ) {
-        $datetime_field->set_timezone($this->_timezone);
-        $datetime_field->set_date_format($this->_dt_frmt, $pretty);
-        $datetime_field->set_time_format($this->_tm_frmt, $pretty);
-        // set the output returned
-        switch ($date_or_time) {
-            case 'D':
-                $datetime_field->set_date_time_output('date');
-                break;
-            case 'T':
-                $datetime_field->set_date_time_output('time');
-                break;
-            default:
-                $datetime_field->set_date_time_output();
-        }
-    }
-
-
-    /**
-     * This just takes care of clearing out the cached_properties
-     *
-     * @return void
-     */
-    protected function _clear_cached_properties()
-    {
-        $this->_cached_properties = array();
-    }
-
-
-    /**
-     * This just clears out ONE property if it exists in the cache
-     *
-     * @param  string $property_name the property to remove if it exists (from the _cached_properties array)
-     * @return void
-     */
-    protected function _clear_cached_property($property_name)
-    {
-        if (isset($this->_cached_properties[ $property_name ])) {
-            unset($this->_cached_properties[ $property_name ]);
-        }
-    }
-
-
-    /**
-     * Ensures that this related thing is a model object.
-     *
-     * @param mixed  $object_or_id EE_base_Class/int/string either a related model object, or its ID
-     * @param string $model_name   name of the related thing, eg 'Attendee',
-     * @return EE_Base_Class
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected function ensure_related_thing_is_model_obj($object_or_id, $model_name)
-    {
-        $other_model_instance = self::_get_model_instance_with_name(
-            self::_get_model_classname($model_name),
-            $this->_timezone
-        );
-        return $other_model_instance->ensure_is_obj($object_or_id);
-    }
-
-
-    /**
-     * Forgets the cached model of the given relation Name. So the next time we request it,
-     * we will fetch it again from the database. (Handy if you know it's changed somehow).
-     * If a specific object is supplied, and the relationship to it is either a HasMany or HABTM,
-     * then only remove that one object from our cached array. Otherwise, clear the entire list
-     *
-     * @param string $relationName                         one of the keys in the _model_relations array on the model.
-     *                                                     Eg 'Registration'
-     * @param mixed  $object_to_remove_or_index_into_array or an index into the array of cached things, or NULL
-     *                                                     if you intend to use $clear_all = TRUE, or the relation only
-     *                                                     has 1 object anyways (ie, it's a BelongsToRelation)
-     * @param bool   $clear_all                            This flags clearing the entire cache relation property if
-     *                                                     this is HasMany or HABTM.
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @return EE_Base_Class | boolean from which was cleared from the cache, or true if we requested to remove a
-     *                                                     relation from all
-     */
-    public function clear_cache($relationName, $object_to_remove_or_index_into_array = null, $clear_all = false)
-    {
-        $relationship_to_model = $this->get_model()->related_settings_for($relationName);
-        $index_in_cache = '';
-        if (! $relationship_to_model) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__('There is no relationship to %s on a %s. Cannot clear that cache', 'event_espresso'),
-                    $relationName,
-                    get_class($this)
-                )
-            );
-        }
-        if ($clear_all) {
-            $obj_removed = true;
-            $this->_model_relations[ $relationName ] = null;
-        } elseif ($relationship_to_model instanceof EE_Belongs_To_Relation) {
-            $obj_removed = $this->_model_relations[ $relationName ];
-            $this->_model_relations[ $relationName ] = null;
-        } else {
-            if ($object_to_remove_or_index_into_array instanceof EE_Base_Class
-                && $object_to_remove_or_index_into_array->ID()
-            ) {
-                $index_in_cache = $object_to_remove_or_index_into_array->ID();
-                if (is_array($this->_model_relations[ $relationName ])
-                    && ! isset($this->_model_relations[ $relationName ][ $index_in_cache ])
-                ) {
-                    $index_found_at = null;
-                    // find this object in the array even though it has a different key
-                    foreach ($this->_model_relations[ $relationName ] as $index => $obj) {
-                        /** @noinspection TypeUnsafeComparisonInspection */
-                        if ($obj instanceof EE_Base_Class
-                            && (
-                                $obj == $object_to_remove_or_index_into_array
-                                || $obj->ID() === $object_to_remove_or_index_into_array->ID()
-                            )
-                        ) {
-                            $index_found_at = $index;
-                            break;
-                        }
-                    }
-                    if ($index_found_at) {
-                        $index_in_cache = $index_found_at;
-                    } else {
-                        // it wasn't found. huh. well obviously it doesn't need to be removed from teh cache
-                        // if it wasn't in it to begin with. So we're done
-                        return $object_to_remove_or_index_into_array;
-                    }
-                }
-            } elseif ($object_to_remove_or_index_into_array instanceof EE_Base_Class) {
-                // so they provided a model object, but it's not yet saved to the DB... so let's go hunting for it!
-                foreach ($this->get_all_from_cache($relationName) as $index => $potentially_obj_we_want) {
-                    /** @noinspection TypeUnsafeComparisonInspection */
-                    if ($potentially_obj_we_want == $object_to_remove_or_index_into_array) {
-                        $index_in_cache = $index;
-                    }
-                }
-            } else {
-                $index_in_cache = $object_to_remove_or_index_into_array;
-            }
-            // supposedly we've found it. But it could just be that the client code
-            // provided a bad index/object
-            if (isset($this->_model_relations[ $relationName ][ $index_in_cache ])) {
-                $obj_removed = $this->_model_relations[ $relationName ][ $index_in_cache ];
-                unset($this->_model_relations[ $relationName ][ $index_in_cache ]);
-            } else {
-                // that thing was never cached anyways.
-                $obj_removed = null;
-            }
-        }
-        return $obj_removed;
-    }
-
-
-    /**
-     * update_cache_after_object_save
-     * Allows a cached item to have it's cache ID (within the array of cached items) reset using the new ID it has
-     * obtained after being saved to the db
-     *
-     * @param string        $relationName       - the type of object that is cached
-     * @param EE_Base_Class $newly_saved_object - the newly saved object to be re-cached
-     * @param string        $current_cache_id   - the ID that was used when originally caching the object
-     * @return boolean TRUE on success, FALSE on fail
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function update_cache_after_object_save(
-        $relationName,
-        EE_Base_Class $newly_saved_object,
-        $current_cache_id = ''
-    ) {
-        // verify that incoming object is of the correct type
-        $obj_class = 'EE_' . $relationName;
-        if ($newly_saved_object instanceof $obj_class) {
-            /* @type EE_Base_Class $newly_saved_object */
-            // now get the type of relation
-            $relationship_to_model = $this->get_model()->related_settings_for($relationName);
-            // if this is a 1:1 relationship
-            if ($relationship_to_model instanceof EE_Belongs_To_Relation) {
-                // then just replace the cached object with the newly saved object
-                $this->_model_relations[ $relationName ] = $newly_saved_object;
-                return true;
-                // or if it's some kind of sordid feral polyamorous relationship...
-            }
-            if (is_array($this->_model_relations[ $relationName ])
-                && isset($this->_model_relations[ $relationName ][ $current_cache_id ])
-            ) {
-                // then remove the current cached item
-                unset($this->_model_relations[ $relationName ][ $current_cache_id ]);
-                // and cache the newly saved object using it's new ID
-                $this->_model_relations[ $relationName ][ $newly_saved_object->ID() ] = $newly_saved_object;
-                return true;
-            }
-        }
-        return false;
-    }
-
-
-    /**
-     * Fetches a single EE_Base_Class on that relation. (If the relation is of type
-     * BelongsTo, it will only ever have 1 object. However, other relations could have an array of objects)
-     *
-     * @param string $relationName
-     * @return EE_Base_Class
-     */
-    public function get_one_from_cache($relationName)
-    {
-        $cached_array_or_object = isset($this->_model_relations[ $relationName ])
-            ? $this->_model_relations[ $relationName ]
-            : null;
-        if (is_array($cached_array_or_object)) {
-            return array_shift($cached_array_or_object);
-        }
-        return $cached_array_or_object;
-    }
-
-
-    /**
-     * Fetches a single EE_Base_Class on that relation. (If the relation is of type
-     * BelongsTo, it will only ever have 1 object. However, other relations could have an array of objects)
-     *
-     * @param string $relationName
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @return EE_Base_Class[] NOT necessarily indexed by primary keys
-     */
-    public function get_all_from_cache($relationName)
-    {
-        $objects = isset($this->_model_relations[ $relationName ]) ? $this->_model_relations[ $relationName ] : array();
-        // if the result is not an array, but exists, make it an array
-        $objects = is_array($objects) ? $objects : array($objects);
-        // bugfix for https://events.codebasehq.com/projects/event-espresso/tickets/7143
-        // basically, if this model object was stored in the session, and these cached model objects
-        // already have IDs, let's make sure they're in their model's entity mapper
-        // otherwise we will have duplicates next time we call
-        // EE_Registry::instance()->load_model( $relationName )->get_one_by_ID( $result->ID() );
-        $model = EE_Registry::instance()->load_model($relationName);
-        foreach ($objects as $model_object) {
-            if ($model instanceof EEM_Base && $model_object instanceof EE_Base_Class) {
-                // ensure its in the map if it has an ID; otherwise it will be added to the map when its saved
-                if ($model_object->ID()) {
-                    $model->add_to_entity_map($model_object);
-                }
-            } else {
-                throw new EE_Error(
-                    sprintf(
-                        esc_html__(
-                            'Error retrieving related model objects. Either $1%s is not a model or $2%s is not a model object',
-                            'event_espresso'
-                        ),
-                        $relationName,
-                        gettype($model_object)
-                    )
-                );
-            }
-        }
-        return $objects;
-    }
-
-
-    /**
-     * Returns the next x number of EE_Base_Class objects in sequence from this object as found in the database
-     * matching the given query conditions.
-     *
-     * @param null  $field_to_order_by  What field is being used as the reference point.
-     * @param int   $limit              How many objects to return.
-     * @param array $query_params       Any additional conditions on the query.
-     * @param null  $columns_to_select  If left null, then an array of EE_Base_Class objects is returned, otherwise
-     *                                  you can indicate just the columns you want returned
-     * @return array|EE_Base_Class[]
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function next_x($field_to_order_by = null, $limit = 1, $query_params = array(), $columns_to_select = null)
-    {
-        $model = $this->get_model();
-        $field = empty($field_to_order_by) && $model->has_primary_key_field()
-            ? $model->get_primary_key_field()->get_name()
-            : $field_to_order_by;
-        $current_value = ! empty($field) ? $this->get($field) : null;
-        if (empty($field) || empty($current_value)) {
-            return array();
-        }
-        return $model->next_x($current_value, $field, $limit, $query_params, $columns_to_select);
-    }
-
-
-    /**
-     * Returns the previous x number of EE_Base_Class objects in sequence from this object as found in the database
-     * matching the given query conditions.
-     *
-     * @param null  $field_to_order_by  What field is being used as the reference point.
-     * @param int   $limit              How many objects to return.
-     * @param array $query_params       Any additional conditions on the query.
-     * @param null  $columns_to_select  If left null, then an array of EE_Base_Class objects is returned, otherwise
-     *                                  you can indicate just the columns you want returned
-     * @return array|EE_Base_Class[]
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function previous_x(
-        $field_to_order_by = null,
-        $limit = 1,
-        $query_params = array(),
-        $columns_to_select = null
-    ) {
-        $model = $this->get_model();
-        $field = empty($field_to_order_by) && $model->has_primary_key_field()
-            ? $model->get_primary_key_field()->get_name()
-            : $field_to_order_by;
-        $current_value = ! empty($field) ? $this->get($field) : null;
-        if (empty($field) || empty($current_value)) {
-            return array();
-        }
-        return $model->previous_x($current_value, $field, $limit, $query_params, $columns_to_select);
-    }
-
-
-    /**
-     * Returns the next EE_Base_Class object in sequence from this object as found in the database
-     * matching the given query conditions.
-     *
-     * @param null  $field_to_order_by  What field is being used as the reference point.
-     * @param array $query_params       Any additional conditions on the query.
-     * @param null  $columns_to_select  If left null, then an array of EE_Base_Class objects is returned, otherwise
-     *                                  you can indicate just the columns you want returned
-     * @return array|EE_Base_Class
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function next($field_to_order_by = null, $query_params = array(), $columns_to_select = null)
-    {
-        $model = $this->get_model();
-        $field = empty($field_to_order_by) && $model->has_primary_key_field()
-            ? $model->get_primary_key_field()->get_name()
-            : $field_to_order_by;
-        $current_value = ! empty($field) ? $this->get($field) : null;
-        if (empty($field) || empty($current_value)) {
-            return array();
-        }
-        return $model->next($current_value, $field, $query_params, $columns_to_select);
-    }
-
-
-    /**
-     * Returns the previous EE_Base_Class object in sequence from this object as found in the database
-     * matching the given query conditions.
-     *
-     * @param null  $field_to_order_by  What field is being used as the reference point.
-     * @param array $query_params       Any additional conditions on the query.
-     * @param null  $columns_to_select  If left null, then an EE_Base_Class object is returned, otherwise
-     *                                  you can indicate just the column you want returned
-     * @return array|EE_Base_Class
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function previous($field_to_order_by = null, $query_params = array(), $columns_to_select = null)
-    {
-        $model = $this->get_model();
-        $field = empty($field_to_order_by) && $model->has_primary_key_field()
-            ? $model->get_primary_key_field()->get_name()
-            : $field_to_order_by;
-        $current_value = ! empty($field) ? $this->get($field) : null;
-        if (empty($field) || empty($current_value)) {
-            return array();
-        }
-        return $model->previous($current_value, $field, $query_params, $columns_to_select);
-    }
-
-
-    /**
-     * Overrides parent because parent expects old models.
-     * This also doesn't do any validation, and won't work for serialized arrays
-     *
-     * @param string $field_name
-     * @param mixed  $field_value_from_db
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function set_from_db($field_name, $field_value_from_db)
-    {
-        $field_obj = $this->get_model()->field_settings_for($field_name);
-        if ($field_obj instanceof EE_Model_Field_Base) {
-            // you would think the DB has no NULLs for non-null label fields right? wrong!
-            // eg, a CPT model object could have an entry in the posts table, but no
-            // entry in the meta table. Meaning that all its columns in the meta table
-            // are null! yikes! so when we find one like that, use defaults for its meta columns
-            if ($field_value_from_db === null) {
-                if ($field_obj->is_nullable()) {
-                    // if the field allows nulls, then let it be null
-                    $field_value = null;
-                } else {
-                    $field_value = $field_obj->get_default_value();
-                }
-            } else {
-                $field_value = $field_obj->prepare_for_set_from_db($field_value_from_db);
-            }
-            $this->_fields[ $field_name ] = $field_value;
-            $this->_clear_cached_property($field_name);
-        }
-    }
-
-
-    /**
-     * verifies that the specified field is of the correct type
-     *
-     * @param string $field_name
-     * @param string $extra_cache_ref This allows the user to specify an extra cache ref for the given property
-     *                                (in cases where the same property may be used for different outputs
-     *                                - i.e. datetime, money etc.)
-     * @return mixed
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get($field_name, $extra_cache_ref = null)
-    {
-        return $this->_get_cached_property($field_name, false, $extra_cache_ref);
-    }
-
-
-    /**
-     * This method simply returns the RAW unprocessed value for the given property in this class
-     *
-     * @param  string $field_name A valid fieldname
-     * @return mixed              Whatever the raw value stored on the property is.
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error if fieldSettings is misconfigured or the field doesn't exist.
-     */
-    public function get_raw($field_name)
-    {
-        $field_settings = $this->get_model()->field_settings_for($field_name);
-        return $field_settings instanceof EE_Datetime_Field && $this->_fields[ $field_name ] instanceof DateTime
-            ? $this->_fields[ $field_name ]->format('U')
-            : $this->_fields[ $field_name ];
-    }
-
-
-    /**
-     * This is used to return the internal DateTime object used for a field that is a
-     * EE_Datetime_Field.
-     *
-     * @param string $field_name               The field name retrieving the DateTime object.
-     * @return mixed null | false | DateTime  If the requested field is NOT a EE_Datetime_Field then
-     * @throws EE_Error an error is set and false returned.  If the field IS an
-     *                                         EE_Datetime_Field and but the field value is null, then
-     *                                         just null is returned (because that indicates that likely
-     *                                         this field is nullable).
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function get_DateTime_object($field_name)
-    {
-        $field_settings = $this->get_model()->field_settings_for($field_name);
-        if (! $field_settings instanceof EE_Datetime_Field) {
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'The field %s is not an EE_Datetime_Field field.  There is no DateTime object stored on this field type.',
-                        'event_espresso'
-                    ),
-                    $field_name
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return false;
-        }
-        return isset($this->_fields[ $field_name ]) && $this->_fields[ $field_name ] instanceof DateTime
-            ? clone $this->_fields[ $field_name ]
-            : null;
-    }
-
-
-    /**
-     * To be used in template to immediately echo out the value, and format it for output.
-     * Eg, should call stripslashes and whatnot before echoing
-     *
-     * @param string $field_name      the name of the field as it appears in the DB
-     * @param string $extra_cache_ref This allows the user to specify an extra cache ref for the given property
-     *                                (in cases where the same property may be used for different outputs
-     *                                - i.e. datetime, money etc.)
-     * @return void
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function e($field_name, $extra_cache_ref = null)
-    {
-        echo $this->get_pretty($field_name, $extra_cache_ref);
-    }
-
-
-    /**
-     * Exactly like e(), echoes out the field, but sets its schema to 'form_input', so that it
-     * can be easily used as the value of form input.
-     *
-     * @param string $field_name
-     * @return void
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function f($field_name)
-    {
-        $this->e($field_name, 'form_input');
-    }
-
-
-    /**
-     * Same as `f()` but just returns the value instead of echoing it
-     *
-     * @param string $field_name
-     * @return string
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get_f($field_name)
-    {
-        return (string) $this->get_pretty($field_name, 'form_input');
-    }
-
-
-    /**
-     * Gets a pretty view of the field's value. $extra_cache_ref can specify different formats for this.
-     * The $extra_cache_ref will be passed to the model field's prepare_for_pretty_echoing, so consult the field's class
-     * to see what options are available.
-     *
-     * @param string $field_name
-     * @param string $extra_cache_ref This allows the user to specify an extra cache ref for the given property
-     *                                (in cases where the same property may be used for different outputs
-     *                                - i.e. datetime, money etc.)
-     * @return mixed
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get_pretty($field_name, $extra_cache_ref = null)
-    {
-        return $this->_get_cached_property($field_name, true, $extra_cache_ref);
-    }
-
-
-    /**
-     * This simply returns the datetime for the given field name
-     * Note: this protected function is called by the wrapper get_date or get_time or get_datetime functions
-     * (and the equivalent e_date, e_time, e_datetime).
-     *
-     * @access   protected
-     * @param string   $field_name   Field on the instantiated EE_Base_Class child object
-     * @param string   $dt_frmt      valid datetime format used for date
-     *                               (if '' then we just use the default on the field,
-     *                               if NULL we use the last-used format)
-     * @param string   $tm_frmt      Same as above except this is for time format
-     * @param string   $date_or_time if NULL then both are returned, otherwise "D" = only date and "T" = only time.
-     * @param  boolean $echo         Whether the dtt is echoing using pretty echoing or just returned using vanilla get
-     * @return string|bool|EE_Error string on success, FALSE on fail, or EE_Error Exception is thrown
-     *                               if field is not a valid dtt field, or void if echoing
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected function _get_datetime($field_name, $dt_frmt = '', $tm_frmt = '', $date_or_time = '', $echo = false)
-    {
-        // clear cached property
-        $this->_clear_cached_property($field_name);
-        // reset format properties because they are used in get()
-        $this->_dt_frmt = $dt_frmt !== '' ? $dt_frmt : $this->_dt_frmt;
-        $this->_tm_frmt = $tm_frmt !== '' ? $tm_frmt : $this->_tm_frmt;
-        if ($echo) {
-            $this->e($field_name, $date_or_time);
-            return '';
-        }
-        return $this->get($field_name, $date_or_time);
-    }
-
-
-    /**
-     * below are wrapper functions for the various datetime outputs that can be obtained for JUST returning the date
-     * portion of a datetime value. (note the only difference between get_ and e_ is one returns the value and the
-     * other echoes the pretty value for dtt)
-     *
-     * @param  string $field_name name of model object datetime field holding the value
-     * @param  string $format     format for the date returned (if NULL we use default in dt_frmt property)
-     * @return string            datetime value formatted
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get_date($field_name, $format = '')
-    {
-        return $this->_get_datetime($field_name, $format, null, 'D');
-    }
-
-
-    /**
-     * @param        $field_name
-     * @param string $format
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function e_date($field_name, $format = '')
-    {
-        $this->_get_datetime($field_name, $format, null, 'D', true);
-    }
-
-
-    /**
-     * below are wrapper functions for the various datetime outputs that can be obtained for JUST returning the time
-     * portion of a datetime value. (note the only difference between get_ and e_ is one returns the value and the
-     * other echoes the pretty value for dtt)
-     *
-     * @param  string $field_name name of model object datetime field holding the value
-     * @param  string $format     format for the time returned ( if NULL we use default in tm_frmt property)
-     * @return string             datetime value formatted
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get_time($field_name, $format = '')
-    {
-        return $this->_get_datetime($field_name, null, $format, 'T');
-    }
-
-
-    /**
-     * @param        $field_name
-     * @param string $format
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function e_time($field_name, $format = '')
-    {
-        $this->_get_datetime($field_name, null, $format, 'T', true);
-    }
-
-
-    /**
-     * below are wrapper functions for the various datetime outputs that can be obtained for returning the date AND
-     * time portion of a datetime value. (note the only difference between get_ and e_ is one returns the value and the
-     * other echoes the pretty value for dtt)
-     *
-     * @param  string $field_name name of model object datetime field holding the value
-     * @param  string $dt_frmt    format for the date returned (if NULL we use default in dt_frmt property)
-     * @param  string $tm_frmt    format for the time returned (if NULL we use default in tm_frmt property)
-     * @return string             datetime value formatted
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get_datetime($field_name, $dt_frmt = '', $tm_frmt = '')
-    {
-        return $this->_get_datetime($field_name, $dt_frmt, $tm_frmt);
-    }
-
-
-    /**
-     * @param string $field_name
-     * @param string $dt_frmt
-     * @param string $tm_frmt
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function e_datetime($field_name, $dt_frmt = '', $tm_frmt = '')
-    {
-        $this->_get_datetime($field_name, $dt_frmt, $tm_frmt, null, true);
-    }
-
-
-    /**
-     * Get the i8ln value for a date using the WordPress @see date_i18n function.
-     *
-     * @param string $field_name The EE_Datetime_Field reference for the date being retrieved.
-     * @param string $format     PHP valid date/time string format.  If none is provided then the internal set format
-     *                           on the object will be used.
-     * @return string Date and time string in set locale or false if no field exists for the given
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     *                           field name.
-     */
-    public function get_i18n_datetime($field_name, $format = '')
-    {
-        $format = empty($format) ? $this->_dt_frmt . ' ' . $this->_tm_frmt : $format;
-        return date_i18n(
-            $format,
-            EEH_DTT_Helper::get_timestamp_with_offset(
-                $this->get_raw($field_name),
-                $this->_timezone
-            )
-        );
-    }
-
-
-    /**
-     * This method validates whether the given field name is a valid field on the model object as well as it is of a
-     * type EE_Datetime_Field.  On success there will be returned the field settings.  On fail an EE_Error exception is
-     * thrown.
-     *
-     * @param  string $field_name The field name being checked
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @return EE_Datetime_Field
-     */
-    protected function _get_dtt_field_settings($field_name)
-    {
-        $field = $this->get_model()->field_settings_for($field_name);
-        // check if field is dtt
-        if ($field instanceof EE_Datetime_Field) {
-            return $field;
-        }
-        throw new EE_Error(
-            sprintf(
-                esc_html__(
-                    'The field name "%s" has been requested for the EE_Base_Class datetime functions and it is not a valid EE_Datetime_Field.  Please check the spelling of the field and make sure it has been setup as a EE_Datetime_Field in the %s model constructor',
-                    'event_espresso'
-                ),
-                $field_name,
-                self::_get_model_classname(get_class($this))
-            )
-        );
-    }
-
-
-
-
-    /**
-     * NOTE ABOUT BELOW:
-     * These convenience date and time setters are for setting date and time independently.  In other words you might
-     * want to change the time on a datetime_field but leave the date the same (or vice versa). IF on the other hand
-     * you want to set both date and time at the same time, you can just use the models default set($fieldname,$value)
-     * method and make sure you send the entire datetime value for setting.
-     */
-    /**
-     * sets the time on a datetime property
-     *
-     * @access protected
-     * @param string|Datetime $time      a valid time string for php datetime functions (or DateTime object)
-     * @param string          $fieldname the name of the field the time is being set on (must match a EE_Datetime_Field)
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected function _set_time_for($time, $fieldname)
-    {
-        $this->_set_date_time('T', $time, $fieldname);
-    }
-
-
-    /**
-     * sets the date on a datetime property
-     *
-     * @access protected
-     * @param string|DateTime $date      a valid date string for php datetime functions ( or DateTime object)
-     * @param string          $fieldname the name of the field the date is being set on (must match a EE_Datetime_Field)
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected function _set_date_for($date, $fieldname)
-    {
-        $this->_set_date_time('D', $date, $fieldname);
-    }
-
-
-    /**
-     * This takes care of setting a date or time independently on a given model object property. This method also
-     * verifies that the given fieldname matches a model object property and is for a EE_Datetime_Field field
-     *
-     * @access protected
-     * @param string          $what           "T" for time, 'B' for both, 'D' for Date.
-     * @param string|DateTime $datetime_value A valid Date or Time string (or DateTime object)
-     * @param string          $fieldname      the name of the field the date OR time is being set on (must match a
-     *                                        EE_Datetime_Field property)
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected function _set_date_time($what = 'T', $datetime_value, $fieldname)
-    {
-        $field = $this->_get_dtt_field_settings($fieldname);
-        $field->set_timezone($this->_timezone);
-        $field->set_date_format($this->_dt_frmt);
-        $field->set_time_format($this->_tm_frmt);
-        switch ($what) {
-            case 'T':
-                $this->_fields[ $fieldname ] = $field->prepare_for_set_with_new_time(
-                    $datetime_value,
-                    $this->_fields[ $fieldname ]
-                );
-                $this->_has_changes = true;
-                break;
-            case 'D':
-                $this->_fields[ $fieldname ] = $field->prepare_for_set_with_new_date(
-                    $datetime_value,
-                    $this->_fields[ $fieldname ]
-                );
-                $this->_has_changes = true;
-                break;
-            case 'B':
-                $this->_fields[ $fieldname ] = $field->prepare_for_set($datetime_value);
-                $this->_has_changes = true;
-                break;
-        }
-        $this->_clear_cached_property($fieldname);
-    }
-
-
-    /**
-     * This will return a timestamp for the website timezone but ONLY when the current website timezone is different
-     * than the timezone set for the website. NOTE, this currently only works well with methods that return values.  If
-     * you use it with methods that echo values the $_timestamp property may not get reset to its original value and
-     * that could lead to some unexpected results!
-     *
-     * @access public
-     * @param string $field_name               This is the name of the field on the object that contains the date/time
-     *                                         value being returned.
-     * @param string $callback                 must match a valid method in this class (defaults to get_datetime)
-     * @param mixed (array|string) $args       This is the arguments that will be passed to the callback.
-     * @param string $prepend                  You can include something to prepend on the timestamp
-     * @param string $append                   You can include something to append on the timestamp
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @return string timestamp
-     */
-    public function display_in_my_timezone(
-        $field_name,
-        $callback = 'get_datetime',
-        $args = null,
-        $prepend = '',
-        $append = ''
-    ) {
-        $timezone = EEH_DTT_Helper::get_timezone();
-        if ($timezone === $this->_timezone) {
-            return '';
-        }
-        $original_timezone = $this->_timezone;
-        $this->set_timezone($timezone);
-        $fn = (array) $field_name;
-        $args = array_merge($fn, (array) $args);
-        if (! method_exists($this, $callback)) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'The method named "%s" given as the callback param in "display_in_my_timezone" does not exist.  Please check your spelling',
-                        'event_espresso'
-                    ),
-                    $callback
-                )
-            );
-        }
-        $args = (array) $args;
-        $return = $prepend . call_user_func_array(array($this, $callback), $args) . $append;
-        $this->set_timezone($original_timezone);
-        return $return;
-    }
-
-
-    /**
-     * Deletes this model object.
-     * This calls the `EE_Base_Class::_delete` method.  Child classes wishing to change default behaviour should
-     * override
-     * `EE_Base_Class::_delete` NOT this class.
-     *
-     * @return boolean | int
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function delete()
-    {
-        /**
-         * Called just before the `EE_Base_Class::_delete` method call.
-         * Note:
-         * `EE_Base_Class::_delete` might be overridden by child classes so any client code hooking into these actions
-         * should be aware that `_delete` may not always result in a permanent delete.
-         * For example, `EE_Soft_Delete_Base_Class::_delete`
-         * soft deletes (trash) the object and does not permanently delete it.
-         *
-         * @param EE_Base_Class $model_object about to be 'deleted'
-         */
-        do_action('AHEE__EE_Base_Class__delete__before', $this);
-        $result = $this->_delete();
-        /**
-         * Called just after the `EE_Base_Class::_delete` method call.
-         * Note:
-         * `EE_Base_Class::_delete` might be overridden by child classes so any client code hooking into these actions
-         * should be aware that `_delete` may not always result in a permanent delete.
-         * For example `EE_Soft_Base_Class::_delete`
-         * soft deletes (trash) the object and does not permanently delete it.
-         *
-         * @param EE_Base_Class $model_object that was just 'deleted'
-         * @param boolean       $result
-         */
-        do_action('AHEE__EE_Base_Class__delete__end', $this, $result);
-        return $result;
-    }
-
-
-    /**
-     * Calls the specific delete method for the instantiated class.
-     * This method is called by the public `EE_Base_Class::delete` method.  Any child classes desiring to override
-     * default functionality for "delete" (which is to call `permanently_delete`) should override this method NOT
-     * `EE_Base_Class::delete`
-     *
-     * @return bool|int
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected function _delete()
-    {
-        return $this->delete_permanently();
-    }
-
-
-    /**
-     * Deletes this model object permanently from db
-     * (but keep in mind related models may block the delete and return an error)
-     *
-     * @return bool | int
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function delete_permanently()
-    {
-        /**
-         * Called just before HARD deleting a model object
-         *
-         * @param EE_Base_Class $model_object about to be 'deleted'
-         */
-        do_action('AHEE__EE_Base_Class__delete_permanently__before', $this);
-        $model = $this->get_model();
-        $result = $model->delete_permanently_by_ID($this->ID());
-        $this->refresh_cache_of_related_objects();
-        /**
-         * Called just after HARD deleting a model object
-         *
-         * @param EE_Base_Class $model_object that was just 'deleted'
-         * @param boolean       $result
-         */
-        do_action('AHEE__EE_Base_Class__delete_permanently__end', $this, $result);
-        return $result;
-    }
-
-
-    /**
-     * When this model object is deleted, it may still be cached on related model objects. This clears the cache of
-     * related model objects
-     *
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function refresh_cache_of_related_objects()
-    {
-        $model = $this->get_model();
-        foreach ($model->relation_settings() as $relation_name => $relation_obj) {
-            if (! empty($this->_model_relations[ $relation_name ])) {
-                $related_objects = $this->_model_relations[ $relation_name ];
-                if ($relation_obj instanceof EE_Belongs_To_Relation) {
-                    // this relation only stores a single model object, not an array
-                    // but let's make it consistent
-                    $related_objects = array($related_objects);
-                }
-                foreach ($related_objects as $related_object) {
-                    // only refresh their cache if they're in memory
-                    if ($related_object instanceof EE_Base_Class) {
-                        $related_object->clear_cache(
-                            $model->get_this_model_name(),
-                            $this
-                        );
-                    }
-                }
-            }
-        }
-    }
-
-
-    /**
-     *        Saves this object to the database. An array may be supplied to set some values on this
-     * object just before saving.
-     *
-     * @access public
-     * @param array $set_cols_n_values keys are field names, values are their new values,
-     *                                 if provided during the save() method (often client code will change the fields'
-     *                                 values before calling save)
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @return int , 1 on a successful update, the ID of the new entry on insert; 0 on failure or if the model object
-     *                                 isn't allowed to persist (as determined by EE_Base_Class::allow_persist())
-     * @throws ReflectionException
-     * @throws ReflectionException
-     * @throws ReflectionException
-     */
-    public function save($set_cols_n_values = array())
-    {
-        $model = $this->get_model();
-        /**
-         * Filters the fields we're about to save on the model object
-         *
-         * @param array         $set_cols_n_values
-         * @param EE_Base_Class $model_object
-         */
-        $set_cols_n_values = (array) apply_filters(
-            'FHEE__EE_Base_Class__save__set_cols_n_values',
-            $set_cols_n_values,
-            $this
-        );
-        // set attributes as provided in $set_cols_n_values
-        foreach ($set_cols_n_values as $column => $value) {
-            $this->set($column, $value);
-        }
-        // no changes ? then don't do anything
-        if (! $this->_has_changes && $this->ID() && $model->get_primary_key_field()->is_auto_increment()) {
-            return 0;
-        }
-        /**
-         * Saving a model object.
-         * Before we perform a save, this action is fired.
-         *
-         * @param EE_Base_Class $model_object the model object about to be saved.
-         */
-        do_action('AHEE__EE_Base_Class__save__begin', $this);
-        if (! $this->allow_persist()) {
-            return 0;
-        }
-        // now get current attribute values
-        $save_cols_n_values = $this->_fields;
-        // if the object already has an ID, update it. Otherwise, insert it
-        // also: change the assumption about values passed to the model NOT being prepare dby the model object.
-        // They have been
-        $old_assumption_concerning_value_preparation = $model
-            ->get_assumption_concerning_values_already_prepared_by_model_object();
-        $model->assume_values_already_prepared_by_model_object(true);
-        // does this model have an autoincrement PK?
-        if ($model->has_primary_key_field()) {
-            if ($model->get_primary_key_field()->is_auto_increment()) {
-                // ok check if it's set, if so: update; if not, insert
-                if (! empty($save_cols_n_values[ $model->primary_key_name() ])) {
-                    $results = $model->update_by_ID($save_cols_n_values, $this->ID());
-                } else {
-                    unset($save_cols_n_values[ $model->primary_key_name() ]);
-                    $results = $model->insert($save_cols_n_values);
-                    if ($results) {
-                        // if successful, set the primary key
-                        // but don't use the normal SET method, because it will check if
-                        // an item with the same ID exists in the mapper & db, then
-                        // will find it in the db (because we just added it) and THAT object
-                        // will get added to the mapper before we can add this one!
-                        // but if we just avoid using the SET method, all that headache can be avoided
-                        $pk_field_name = $model->primary_key_name();
-                        $this->_fields[ $pk_field_name ] = $results;
-                        $this->_clear_cached_property($pk_field_name);
-                        $model->add_to_entity_map($this);
-                        $this->_update_cached_related_model_objs_fks();
-                    }
-                }
-            } else {// PK is NOT auto-increment
-                // so check if one like it already exists in the db
-                if ($model->exists_by_ID($this->ID())) {
-                    if (WP_DEBUG && ! $this->in_entity_map()) {
-                        throw new EE_Error(
-                            sprintf(
-                                esc_html__(
-                                    'Using a model object %1$s that is NOT in the entity map, can lead to unexpected errors. You should either: %4$s 1. Put it in the entity mapper by calling %2$s %4$s 2. Discard this model object and use what is in the entity mapper %4$s 3. Fetch from the database using %3$s',
-                                    'event_espresso'
-                                ),
-                                get_class($this),
-                                get_class($model) . '::instance()->add_to_entity_map()',
-                                get_class($model) . '::instance()->get_one_by_ID()',
-                                '<br />'
-                            )
-                        );
-                    }
-                    $results = $model->update_by_ID($save_cols_n_values, $this->ID());
-                } else {
-                    $results = $model->insert($save_cols_n_values);
-                    $this->_update_cached_related_model_objs_fks();
-                }
-            }
-        } else {// there is NO primary key
-            $already_in_db = false;
-            foreach ($model->unique_indexes() as $index) {
-                $uniqueness_where_params = array_intersect_key($save_cols_n_values, $index->fields());
-                if ($model->exists(array($uniqueness_where_params))) {
-                    $already_in_db = true;
-                }
-            }
-            if ($already_in_db) {
-                $combined_pk_fields_n_values = array_intersect_key(
-                    $save_cols_n_values,
-                    $model->get_combined_primary_key_fields()
-                );
-                $results = $model->update(
-                    $save_cols_n_values,
-                    $combined_pk_fields_n_values
-                );
-            } else {
-                $results = $model->insert($save_cols_n_values);
-            }
-        }
-        // restore the old assumption about values being prepared by the model object
-        $model->assume_values_already_prepared_by_model_object(
-            $old_assumption_concerning_value_preparation
-        );
-        /**
-         * After saving the model object this action is called
-         *
-         * @param EE_Base_Class $model_object which was just saved
-         * @param boolean|int   $results      if it were updated, TRUE or FALSE; if it were newly inserted
-         *                                    the new ID (or 0 if an error occurred and it wasn't updated)
-         */
-        do_action('AHEE__EE_Base_Class__save__end', $this, $results);
-        $this->_has_changes = false;
-        return $results;
-    }
-
-
-    /**
-     * Updates the foreign key on related models objects pointing to this to have this model object's ID
-     * as their foreign key.  If the cached related model objects already exist in the db, saves them (so that the DB
-     * is consistent) Especially useful in case we JUST added this model object ot the database and we want to let its
-     * cached relations with foreign keys to it know about that change. Eg: we've created a transaction but haven't
-     * saved it to the db. We also create a registration and don't save it to the DB, but we DO cache it on the
-     * transaction. Now, when we save the transaction, the registration's TXN_ID will be automatically updated, whether
-     * or not they exist in the DB (if they do, their DB records will be automatically updated)
-     *
-     * @return void
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected function _update_cached_related_model_objs_fks()
-    {
-        $model = $this->get_model();
-        foreach ($model->relation_settings() as $relation_name => $relation_obj) {
-            if ($relation_obj instanceof EE_Has_Many_Relation) {
-                foreach ($this->get_all_from_cache($relation_name) as $related_model_obj_in_cache) {
-                    $fk_to_this = $related_model_obj_in_cache->get_model()->get_foreign_key_to(
-                        $model->get_this_model_name()
-                    );
-                    $related_model_obj_in_cache->set($fk_to_this->get_name(), $this->ID());
-                    if ($related_model_obj_in_cache->ID()) {
-                        $related_model_obj_in_cache->save();
-                    }
-                }
-            }
-        }
-    }
-
-
-    /**
-     * Saves this model object and its NEW cached relations to the database.
-     * (Meaning, for now, IT DOES NOT WORK if the cached items already exist in the DB.
-     * In order for that to work, we would need to mark model objects as dirty/clean...
-     * because otherwise, there's a potential for infinite looping of saving
-     * Saves the cached related model objects, and ensures the relation between them
-     * and this object and properly setup
-     *
-     * @return int ID of new model object on save; 0 on failure+
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function save_new_cached_related_model_objs()
-    {
-        // make sure this has been saved
-        if (! $this->ID()) {
-            $id = $this->save();
-        } else {
-            $id = $this->ID();
-        }
-        // now save all the NEW cached model objects  (ie they don't exist in the DB)
-        foreach ($this->get_model()->relation_settings() as $relationName => $relationObj) {
-            if ($this->_model_relations[ $relationName ]) {
-                // is this a relation where we should expect just ONE related object (ie, EE_Belongs_To_relation)
-                // or MANY related objects (ie, EE_HABTM_Relation or EE_Has_Many_Relation)?
-                /* @var $related_model_obj EE_Base_Class */
-                if ($relationObj instanceof EE_Belongs_To_Relation) {
-                    // add a relation to that relation type (which saves the appropriate thing in the process)
-                    // but ONLY if it DOES NOT exist in the DB
-                    $related_model_obj = $this->_model_relations[ $relationName ];
-                    // if( ! $related_model_obj->ID()){
-                    $this->_add_relation_to($related_model_obj, $relationName);
-                    $related_model_obj->save_new_cached_related_model_objs();
-                    // }
-                } else {
-                    foreach ($this->_model_relations[ $relationName ] as $related_model_obj) {
-                        // add a relation to that relation type (which saves the appropriate thing in the process)
-                        // but ONLY if it DOES NOT exist in the DB
-                        // if( ! $related_model_obj->ID()){
-                        $this->_add_relation_to($related_model_obj, $relationName);
-                        $related_model_obj->save_new_cached_related_model_objs();
-                        // }
-                    }
-                }
-            }
-        }
-        return $id;
-    }
-
-
-    /**
-     * for getting a model while instantiated.
-     *
-     * @return EEM_Base | EEM_CPT_Base
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get_model()
-    {
-        if (! $this->_model) {
-            $modelName = self::_get_model_classname(get_class($this));
-            $this->_model = self::_get_model_instance_with_name($modelName, $this->_timezone);
-        } else {
-            $this->_model->set_timezone($this->_timezone);
-        }
-        return $this->_model;
-    }
-
-
-    /**
-     * @param $props_n_values
-     * @param $classname
-     * @return mixed bool|EE_Base_Class|EEM_CPT_Base
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected static function _get_object_from_entity_mapper($props_n_values, $classname)
-    {
-        // TODO: will not work for Term_Relationships because they have no PK!
-        $primary_id_ref = self::_get_primary_key_name($classname);
-        if (array_key_exists($primary_id_ref, $props_n_values)
-            && ! empty($props_n_values[ $primary_id_ref ])
-        ) {
-            $id = $props_n_values[ $primary_id_ref ];
-            return self::_get_model($classname)->get_from_entity_map($id);
-        }
-        return false;
-    }
-
-
-    /**
-     * This is called by child static "new_instance" method and we'll check to see if there is an existing db entry for
-     * the primary key (if present in incoming values). If there is a key in the incoming array that matches the
-     * primary key for the model AND it is not null, then we check the db. If there's a an object we return it.  If not
-     * we return false.
-     *
-     * @param  array  $props_n_values   incoming array of properties and their values
-     * @param  string $classname        the classname of the child class
-     * @param null    $timezone
-     * @param array   $date_formats     incoming date_formats in an array where the first value is the
-     *                                  date_format and the second value is the time format
-     * @return mixed (EE_Base_Class|bool)
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @throws ReflectionException
-     * @throws ReflectionException
-     */
-    protected static function _check_for_object($props_n_values, $classname, $timezone = null, $date_formats = array())
-    {
-        $existing = null;
-        $model = self::_get_model($classname, $timezone);
-        if ($model->has_primary_key_field()) {
-            $primary_id_ref = self::_get_primary_key_name($classname);
-            if (array_key_exists($primary_id_ref, $props_n_values)
-                && ! empty($props_n_values[ $primary_id_ref ])
-            ) {
-                $existing = $model->get_one_by_ID(
-                    $props_n_values[ $primary_id_ref ]
-                );
-            }
-        } elseif ($model->has_all_combined_primary_key_fields($props_n_values)) {
-            // no primary key on this model, but there's still a matching item in the DB
-            $existing = self::_get_model($classname, $timezone)->get_one_by_ID(
-                self::_get_model($classname, $timezone)
-                    ->get_index_primary_key_string($props_n_values)
-            );
-        }
-        if ($existing) {
-            // set date formats if present before setting values
-            if (! empty($date_formats) && is_array($date_formats)) {
-                $existing->set_date_format($date_formats[0]);
-                $existing->set_time_format($date_formats[1]);
-            } else {
-                // set default formats for date and time
-                $existing->set_date_format(get_option('date_format'));
-                $existing->set_time_format(get_option('time_format'));
-            }
-            foreach ($props_n_values as $property => $field_value) {
-                $existing->set($property, $field_value);
-            }
-            return $existing;
-        }
-        return false;
-    }
-
-
-    /**
-     * Gets the EEM_*_Model for this class
-     *
-     * @access public now, as this is more convenient
-     * @param      $classname
-     * @param null $timezone
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @return EEM_Base
-     */
-    protected static function _get_model($classname, $timezone = null)
-    {
-        // find model for this class
-        if (! $classname) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'What were you thinking calling _get_model(%s)?? You need to specify the class name',
-                        'event_espresso'
-                    ),
-                    $classname
-                )
-            );
-        }
-        $modelName = self::_get_model_classname($classname);
-        return self::_get_model_instance_with_name($modelName, $timezone);
-    }
-
-
-    /**
-     * Gets the model instance (eg instance of EEM_Attendee) given its classname (eg EE_Attendee)
-     *
-     * @param string $model_classname
-     * @param null   $timezone
-     * @return EEM_Base
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    protected static function _get_model_instance_with_name($model_classname, $timezone = null)
-    {
-        $model_classname = str_replace('EEM_', '', $model_classname);
-        $model = EE_Registry::instance()->load_model($model_classname);
-        $model->set_timezone($timezone);
-        return $model;
-    }
-
-
-    /**
-     * If a model name is provided (eg Registration), gets the model classname for that model.
-     * Also works if a model class's classname is provided (eg EE_Registration).
-     *
-     * @param null $model_name
-     * @return string like EEM_Attendee
-     */
-    private static function _get_model_classname($model_name = null)
-    {
-        if (strpos($model_name, 'EE_') === 0) {
-            $model_classname = str_replace('EE_', 'EEM_', $model_name);
-        } else {
-            $model_classname = 'EEM_' . $model_name;
-        }
-        return $model_classname;
-    }
-
-
-    /**
-     * returns the name of the primary key attribute
-     *
-     * @param null $classname
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @return string
-     */
-    protected static function _get_primary_key_name($classname = null)
-    {
-        if (! $classname) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__('What were you thinking calling _get_primary_key_name(%s)', 'event_espresso'),
-                    $classname
-                )
-            );
-        }
-        return self::_get_model($classname)->get_primary_key_field()->get_name();
-    }
-
-
-    /**
-     * Gets the value of the primary key.
-     * If the object hasn't yet been saved, it should be whatever the model field's default was
-     * (eg, if this were the EE_Event class, look at the primary key field on EEM_Event and see what its default value
-     * is. Usually defaults for integer primary keys are 0; string primary keys are usually NULL).
-     *
-     * @return mixed, if the primary key is of type INT it'll be an int. Otherwise it could be a string
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function ID()
-    {
-        $model = $this->get_model();
-        // now that we know the name of the variable, use a variable variable to get its value and return its
-        if ($model->has_primary_key_field()) {
-            return $this->_fields[ $model->primary_key_name() ];
-        }
-        return $model->get_index_primary_key_string($this->_fields);
-    }
-
-
-    /**
-     * Adds a relationship to the specified EE_Base_Class object, given the relationship's name. Eg, if the current
-     * model is related to a group of events, the $relationName should be 'Event', and should be a key in the EE
-     * Model's $_model_relations array. If this model object doesn't exist in the DB, just caches the related thing
-     *
-     * @param mixed  $otherObjectModelObjectOrID       EE_Base_Class or the ID of the other object
-     * @param string $relationName                     eg 'Events','Question',etc.
-     *                                                 an attendee to a group, you also want to specify which role they
-     *                                                 will have in that group. So you would use this parameter to
-     *                                                 specify array('role-column-name'=>'role-id')
-     * @param array  $extra_join_model_fields_n_values You can optionally include an array of key=>value pairs that
-     *                                                 allow you to further constrict the relation to being added.
-     *                                                 However, keep in mind that the columns (keys) given must match a
-     *                                                 column on the JOIN table and currently only the HABTM models
-     *                                                 accept these additional conditions.  Also remember that if an
-     *                                                 exact match isn't found for these extra cols/val pairs, then a
-     *                                                 NEW row is created in the join table.
-     * @param null   $cache_id
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @return EE_Base_Class the object the relation was added to
-     */
-    public function _add_relation_to(
-        $otherObjectModelObjectOrID,
-        $relationName,
-        $extra_join_model_fields_n_values = array(),
-        $cache_id = null
-    ) {
-        $model = $this->get_model();
-        // if this thing exists in the DB, save the relation to the DB
-        if ($this->ID()) {
-            $otherObject = $model->add_relationship_to(
-                $this,
-                $otherObjectModelObjectOrID,
-                $relationName,
-                $extra_join_model_fields_n_values
-            );
-            // clear cache so future get_many_related and get_first_related() return new results.
-            $this->clear_cache($relationName, $otherObject, true);
-            if ($otherObject instanceof EE_Base_Class) {
-                $otherObject->clear_cache($model->get_this_model_name(), $this);
-            }
-        } else {
-            // this thing doesn't exist in the DB,  so just cache it
-            if (! $otherObjectModelObjectOrID instanceof EE_Base_Class) {
-                throw new EE_Error(
-                    sprintf(
-                        esc_html__(
-                            'Before a model object is saved to the database, calls to _add_relation_to must be passed an actual object, not just an ID. You provided %s as the model object to a %s',
-                            'event_espresso'
-                        ),
-                        $otherObjectModelObjectOrID,
-                        get_class($this)
-                    )
-                );
-            }
-            $otherObject = $otherObjectModelObjectOrID;
-            $this->cache($relationName, $otherObjectModelObjectOrID, $cache_id);
-        }
-        if ($otherObject instanceof EE_Base_Class) {
-            // fix the reciprocal relation too
-            if ($otherObject->ID()) {
-                // its saved so assumed relations exist in the DB, so we can just
-                // clear the cache so future queries use the updated info in the DB
-                $otherObject->clear_cache(
-                    $model->get_this_model_name(),
-                    null,
-                    true
-                );
-            } else {
-                // it's not saved, so it caches relations like this
-                $otherObject->cache($model->get_this_model_name(), $this);
-            }
-        }
-        return $otherObject;
-    }
-
-
-    /**
-     * Removes a relationship to the specified EE_Base_Class object, given the relationships' name. Eg, if the current
-     * model is related to a group of events, the $relationName should be 'Events', and should be a key in the EE
-     * Model's $_model_relations array. If this model object doesn't exist in the DB, just removes the related thing
-     * from the cache
-     *
-     * @param mixed  $otherObjectModelObjectOrID
-     *                EE_Base_Class or the ID of the other object, OR an array key into the cache if this isn't saved
-     *                to the DB yet
-     * @param string $relationName
-     * @param array  $where_query
-     *                You can optionally include an array of key=>value pairs that allow you to further constrict the
-     *                relation to being added. However, keep in mind that the columns (keys) given must match a column
-     *                on the JOIN table and currently only the HABTM models accept these additional conditions. Also
-     *                remember that if an exact match isn't found for these extra cols/val pairs, then no row is
-     *                deleted.
-     * @return EE_Base_Class the relation was removed from
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function _remove_relation_to($otherObjectModelObjectOrID, $relationName, $where_query = array())
-    {
-        if ($this->ID()) {
-            // if this exists in the DB, save the relation change to the DB too
-            $otherObject = $this->get_model()->remove_relationship_to(
-                $this,
-                $otherObjectModelObjectOrID,
-                $relationName,
-                $where_query
-            );
-            $this->clear_cache(
-                $relationName,
-                $otherObject
-            );
-        } else {
-            // this doesn't exist in the DB, just remove it from the cache
-            $otherObject = $this->clear_cache(
-                $relationName,
-                $otherObjectModelObjectOrID
-            );
-        }
-        if ($otherObject instanceof EE_Base_Class) {
-            $otherObject->clear_cache(
-                $this->get_model()->get_this_model_name(),
-                $this
-            );
-        }
-        return $otherObject;
-    }
-
-
-    /**
-     * Removes ALL the related things for the $relationName.
-     *
-     * @param string $relationName
-     * @param array  $where_query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions
-     * @return EE_Base_Class
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function _remove_relations($relationName, $where_query_params = array())
-    {
-        if ($this->ID()) {
-            // if this exists in the DB, save the relation change to the DB too
-            $otherObjects = $this->get_model()->remove_relations(
-                $this,
-                $relationName,
-                $where_query_params
-            );
-            $this->clear_cache(
-                $relationName,
-                null,
-                true
-            );
-        } else {
-            // this doesn't exist in the DB, just remove it from the cache
-            $otherObjects = $this->clear_cache(
-                $relationName,
-                null,
-                true
-            );
-        }
-        if (is_array($otherObjects)) {
-            foreach ($otherObjects as $otherObject) {
-                $otherObject->clear_cache(
-                    $this->get_model()->get_this_model_name(),
-                    $this
-                );
-            }
-        }
-        return $otherObjects;
-    }
-
-
-    /**
-     * Gets all the related model objects of the specified type. Eg, if the current class if
-     * EE_Event, you could call $this->get_many_related('Registration') to get an array of all the
-     * EE_Registration objects which related to this event. Note: by default, we remove the "default query params"
-     * because we want to get even deleted items etc.
-     *
-     * @param string $relationName key in the model's _model_relations array
-     * @param array  $query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions
-     * @return EE_Base_Class[]     Results not necessarily indexed by IDs, because some results might not have primary
-     *                             keys or might not be saved yet. Consider using EEM_Base::get_IDs() on these
-     *                             results if you want IDs
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get_many_related($relationName, $query_params = array())
-    {
-        if ($this->ID()) {
-            // this exists in the DB, so get the related things from either the cache or the DB
-            // if there are query parameters, forget about caching the related model objects.
-            if ($query_params) {
-                $related_model_objects = $this->get_model()->get_all_related(
-                    $this,
-                    $relationName,
-                    $query_params
-                );
-            } else {
-                // did we already cache the result of this query?
-                $cached_results = $this->get_all_from_cache($relationName);
-                if (! $cached_results) {
-                    $related_model_objects = $this->get_model()->get_all_related(
-                        $this,
-                        $relationName,
-                        $query_params
-                    );
-                    // if no query parameters were passed, then we got all the related model objects
-                    // for that relation. We can cache them then.
-                    foreach ($related_model_objects as $related_model_object) {
-                        $this->cache($relationName, $related_model_object);
-                    }
-                } else {
-                    $related_model_objects = $cached_results;
-                }
-            }
-        } else {
-            // this doesn't exist in the DB, so just get the related things from the cache
-            $related_model_objects = $this->get_all_from_cache($relationName);
-        }
-        return $related_model_objects;
-    }
-
-
-    /**
-     * Instead of getting the related model objects, simply counts them. Ignores default_where_conditions by default,
-     * unless otherwise specified in the $query_params
-     *
-     * @param string $relation_name  model_name like 'Event', or 'Registration'
-     * @param array  $query_params   @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
-     * @param string $field_to_count name of field to count by. By default, uses primary key
-     * @param bool   $distinct       if we want to only count the distinct values for the column then you can trigger
-     *                               that by the setting $distinct to TRUE;
-     * @return int
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function count_related($relation_name, $query_params = array(), $field_to_count = null, $distinct = false)
-    {
-        return $this->get_model()->count_related(
-            $this,
-            $relation_name,
-            $query_params,
-            $field_to_count,
-            $distinct
-        );
-    }
-
-
-    /**
-     * Instead of getting the related model objects, simply sums up the values of the specified field.
-     * Note: ignores default_where_conditions by default, unless otherwise specified in the $query_params
-     *
-     * @param string $relation_name model_name like 'Event', or 'Registration'
-     * @param array  $query_params  @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
-     * @param string $field_to_sum  name of field to count by.
-     *                              By default, uses primary key
-     *                              (which doesn't make much sense, so you should probably change it)
-     * @return int
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function sum_related($relation_name, $query_params = array(), $field_to_sum = null)
-    {
-        return $this->get_model()->sum_related(
-            $this,
-            $relation_name,
-            $query_params,
-            $field_to_sum
-        );
-    }
-
-
-    /**
-     * Gets the first (ie, one) related model object of the specified type.
-     *
-     * @param string $relationName key in the model's _model_relations array
-     * @param array  $query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
-     * @return EE_Base_Class (not an array, a single object)
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get_first_related($relationName, $query_params = array())
-    {
-        $model = $this->get_model();
-        if ($this->ID()) {// this exists in the DB, get from the cache OR the DB
-            // if they've provided some query parameters, don't bother trying to cache the result
-            // also make sure we're not caching the result of get_first_related
-            // on a relation which should have an array of objects (because the cache might have an array of objects)
-            if ($query_params
-                || ! $model->related_settings_for($relationName)
-                     instanceof
-                     EE_Belongs_To_Relation
-            ) {
-                $related_model_object = $model->get_first_related(
-                    $this,
-                    $relationName,
-                    $query_params
-                );
-            } else {
-                // first, check if we've already cached the result of this query
-                $cached_result = $this->get_one_from_cache($relationName);
-                if (! $cached_result) {
-                    $related_model_object = $model->get_first_related(
-                        $this,
-                        $relationName,
-                        $query_params
-                    );
-                    $this->cache($relationName, $related_model_object);
-                } else {
-                    $related_model_object = $cached_result;
-                }
-            }
-        } else {
-            $related_model_object = null;
-            // this doesn't exist in the Db,
-            // but maybe the relation is of type belongs to, and so the related thing might
-            if ($model->related_settings_for($relationName) instanceof EE_Belongs_To_Relation) {
-                $related_model_object = $model->get_first_related(
-                    $this,
-                    $relationName,
-                    $query_params
-                );
-            }
-            // this doesn't exist in the DB and apparently the thing it belongs to doesn't either,
-            // just get what's cached on this object
-            if (! $related_model_object) {
-                $related_model_object = $this->get_one_from_cache($relationName);
-            }
-        }
-        return $related_model_object;
-    }
-
-
-    /**
-     * Does a delete on all related objects of type $relationName and removes
-     * the current model object's relation to them. If they can't be deleted (because
-     * of blocking related model objects) does nothing. If the related model objects are
-     * soft-deletable, they will be soft-deleted regardless of related blocking model objects.
-     * If this model object doesn't exist yet in the DB, just removes its related things
-     *
-     * @param string $relationName
-     * @param array  $query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
-     * @return int how many deleted
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function delete_related($relationName, $query_params = array())
-    {
-        if ($this->ID()) {
-            $count = $this->get_model()->delete_related(
-                $this,
-                $relationName,
-                $query_params
-            );
-        } else {
-            $count = count($this->get_all_from_cache($relationName));
-            $this->clear_cache($relationName, null, true);
-        }
-        return $count;
-    }
-
-
-    /**
-     * Does a hard delete (ie, removes the DB row) on all related objects of type $relationName and removes
-     * the current model object's relation to them. If they can't be deleted (because
-     * of blocking related model objects) just does a soft delete on it instead, if possible.
-     * If the related thing isn't a soft-deletable model object, this function is identical
-     * to delete_related(). If this model object doesn't exist in the DB, just remove its related things
-     *
-     * @param string $relationName
-     * @param array  $query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
-     * @return int how many deleted (including those soft deleted)
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function delete_related_permanently($relationName, $query_params = array())
-    {
-        if ($this->ID()) {
-            $count = $this->get_model()->delete_related_permanently(
-                $this,
-                $relationName,
-                $query_params
-            );
-        } else {
-            $count = count($this->get_all_from_cache($relationName));
-        }
-        $this->clear_cache($relationName, null, true);
-        return $count;
-    }
-
-
-    /**
-     * is_set
-     * Just a simple utility function children can use for checking if property exists
-     *
-     * @access  public
-     * @param  string $field_name property to check
-     * @return bool                              TRUE if existing,FALSE if not.
-     */
-    public function is_set($field_name)
-    {
-        return isset($this->_fields[ $field_name ]);
-    }
-
-
-    /**
-     * Just a simple utility function children can use for checking if property (or properties) exists and throwing an
-     * EE_Error exception if they don't
-     *
-     * @param  mixed (string|array) $properties properties to check
-     * @throws EE_Error
-     * @return bool                              TRUE if existing, throw EE_Error if not.
-     */
-    protected function _property_exists($properties)
-    {
-        foreach ((array) $properties as $property_name) {
-            // first make sure this property exists
-            if (! $this->_fields[ $property_name ]) {
-                throw new EE_Error(
-                    sprintf(
-                        esc_html__(
-                            'Trying to retrieve a non-existent property (%s).  Double check the spelling please',
-                            'event_espresso'
-                        ),
-                        $property_name
-                    )
-                );
-            }
-        }
-        return true;
-    }
-
-
-    /**
-     * This simply returns an array of model fields for this object
-     *
-     * @return array
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function model_field_array()
-    {
-        $fields = $this->get_model()->field_settings(false);
-        $properties = array();
-        // remove prepended underscore
-        foreach ($fields as $field_name => $settings) {
-            $properties[ $field_name ] = $this->get($field_name);
-        }
-        return $properties;
-    }
-
-
-    /**
-     * Very handy general function to allow for plugins to extend any child of EE_Base_Class.
-     * If a method is called on a child of EE_Base_Class that doesn't exist, this function is called
-     * (http://www.garfieldtech.com/blog/php-magic-call) and passed the method's name and arguments.
-     * Instead of requiring a plugin to extend the EE_Base_Class
-     * (which works fine is there's only 1 plugin, but when will that happen?)
-     * they can add a hook onto 'filters_hook_espresso__{className}__{methodName}'
-     * (eg, filters_hook_espresso__EE_Answer__my_great_function)
-     * and accepts 2 arguments: the object on which the function was called,
-     * and an array of the original arguments passed to the function.
-     * Whatever their callback function returns will be returned by this function.
-     * Example: in functions.php (or in a plugin):
-     *      add_filter('FHEE__EE_Answer__my_callback','my_callback',10,3);
-     *      function my_callback($previousReturnValue,EE_Base_Class $object,$argsArray){
-     *          $returnString= "you called my_callback! and passed args:".implode(",",$argsArray);
-     *          return $previousReturnValue.$returnString;
-     *      }
-     * require('EE_Answer.class.php');
-     * $answer= EE_Answer::new_instance(array('REG_ID' => 2,'QST_ID' => 3,'ANS_value' => The answer is 42'));
-     * echo $answer->my_callback('monkeys',100);
-     * //will output "you called my_callback! and passed args:monkeys,100"
-     *
-     * @param string $methodName name of method which was called on a child of EE_Base_Class, but which
-     * @param array  $args       array of original arguments passed to the function
-     * @throws EE_Error
-     * @return mixed whatever the plugin which calls add_filter decides
-     */
-    public function __call($methodName, $args)
-    {
-        $className = get_class($this);
-        $tagName = "FHEE__{$className}__{$methodName}";
-        if (! has_filter($tagName)) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        "Method %s on class %s does not exist! You can create one with the following code in functions.php or in a plugin: add_filter('%s','my_callback',10,3);function my_callback(\$previousReturnValue,EE_Base_Class \$object, \$argsArray){/*function body*/return \$whatever;}",
-                        'event_espresso'
-                    ),
-                    $methodName,
-                    $className,
-                    $tagName
-                )
-            );
-        }
-        return apply_filters($tagName, null, $this, $args);
-    }
-
-
-    /**
-     * Similar to insert_post_meta, adds a record in the Extra_Meta model's table with the given key and value.
-     * A $previous_value can be specified in case there are many meta rows with the same key
-     *
-     * @param string $meta_key
-     * @param mixed  $meta_value
-     * @param mixed  $previous_value
-     * @return bool|int # of records updated (or BOOLEAN if we actually ended up inserting the extra meta row)
-     *                  NOTE: if the values haven't changed, returns 0
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function update_extra_meta($meta_key, $meta_value, $previous_value = null)
-    {
-        $query_params = array(
-            array(
-                'EXM_key'  => $meta_key,
-                'OBJ_ID'   => $this->ID(),
-                'EXM_type' => $this->get_model()->get_this_model_name(),
-            ),
-        );
-        if ($previous_value !== null) {
-            $query_params[0]['EXM_value'] = $meta_value;
-        }
-        $existing_rows_like_that = EEM_Extra_Meta::instance()->get_all($query_params);
-        if (! $existing_rows_like_that) {
-            return $this->add_extra_meta($meta_key, $meta_value);
-        }
-        foreach ($existing_rows_like_that as $existing_row) {
-            $existing_row->save(array('EXM_value' => $meta_value));
-        }
-        return count($existing_rows_like_that);
-    }
-
-
-    /**
-     * Adds a new extra meta record. If $unique is set to TRUE, we'll first double-check
-     * no other extra meta for this model object have the same key. Returns TRUE if the
-     * extra meta row was entered, false if not
-     *
-     * @param string  $meta_key
-     * @param mixed   $meta_value
-     * @param boolean $unique
-     * @return boolean
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @throws ReflectionException
-     */
-    public function add_extra_meta($meta_key, $meta_value, $unique = false)
-    {
-        if ($unique) {
-            $existing_extra_meta = EEM_Extra_Meta::instance()->get_one(
-                array(
-                    array(
-                        'EXM_key'  => $meta_key,
-                        'OBJ_ID'   => $this->ID(),
-                        'EXM_type' => $this->get_model()->get_this_model_name(),
-                    ),
-                )
-            );
-            if ($existing_extra_meta) {
-                return false;
-            }
-        }
-        $new_extra_meta = EE_Extra_Meta::new_instance(
-            array(
-                'EXM_key'   => $meta_key,
-                'EXM_value' => $meta_value,
-                'OBJ_ID'    => $this->ID(),
-                'EXM_type'  => $this->get_model()->get_this_model_name(),
-            )
-        );
-        $new_extra_meta->save();
-        return true;
-    }
-
-
-    /**
-     * Deletes all the extra meta rows for this record as specified by key. If $meta_value
-     * is specified, only deletes extra meta records with that value.
-     *
-     * @param string $meta_key
-     * @param mixed  $meta_value
-     * @return int number of extra meta rows deleted
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function delete_extra_meta($meta_key, $meta_value = null)
-    {
-        $query_params = array(
-            array(
-                'EXM_key'  => $meta_key,
-                'OBJ_ID'   => $this->ID(),
-                'EXM_type' => $this->get_model()->get_this_model_name(),
-            ),
-        );
-        if ($meta_value !== null) {
-            $query_params[0]['EXM_value'] = $meta_value;
-        }
-        return EEM_Extra_Meta::instance()->delete($query_params);
-    }
-
-
-    /**
-     * Gets the extra meta with the given meta key. If you specify "single" we just return 1, otherwise
-     * an array of everything found. Requires that this model actually have a relation of type EE_Has_Many_Any_Relation.
-     * You can specify $default is case you haven't found the extra meta
-     *
-     * @param string  $meta_key
-     * @param boolean $single
-     * @param mixed   $default if we don't find anything, what should we return?
-     * @return mixed single value if $single; array if ! $single
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function get_extra_meta($meta_key, $single = false, $default = null)
-    {
-        if ($single) {
-            $result = $this->get_first_related(
-                'Extra_Meta',
-                array(array('EXM_key' => $meta_key))
-            );
-            if ($result instanceof EE_Extra_Meta) {
-                return $result->value();
-            }
-        } else {
-            $results = $this->get_many_related(
-                'Extra_Meta',
-                array(array('EXM_key' => $meta_key))
-            );
-            if ($results) {
-                $values = array();
-                foreach ($results as $result) {
-                    if ($result instanceof EE_Extra_Meta) {
-                        $values[ $result->ID() ] = $result->value();
-                    }
-                }
-                return $values;
-            }
-        }
-        // if nothing discovered yet return default.
-        return apply_filters(
-            'FHEE__EE_Base_Class__get_extra_meta__default_value',
-            $default,
-            $meta_key,
-            $single,
-            $this
-        );
-    }
-
-
-    /**
-     * Returns a simple array of all the extra meta associated with this model object.
-     * If $one_of_each_key is true (Default), it will be an array of simple key-value pairs, keys being the
-     * extra meta's key, and teh value being its value. However, if there are duplicate extra meta rows with
-     * the same key, only one will be used. (eg array('foo'=>'bar','monkey'=>123))
-     * If $one_of_each_key is false, it will return an array with the top-level keys being
-     * the extra meta keys, but their values are also arrays, which have the extra-meta's ID as their sub-key, and
-     * finally the extra meta's value as each sub-value. (eg
-     * array('foo'=>array(1=>'bar',2=>'bill'),'monkey'=>array(3=>123)))
-     *
-     * @param boolean $one_of_each_key
-     * @return array
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function all_extra_meta_array($one_of_each_key = true)
-    {
-        $return_array = array();
-        if ($one_of_each_key) {
-            $extra_meta_objs = $this->get_many_related(
-                'Extra_Meta',
-                array('group_by' => 'EXM_key')
-            );
-            foreach ($extra_meta_objs as $extra_meta_obj) {
-                if ($extra_meta_obj instanceof EE_Extra_Meta) {
-                    $return_array[ $extra_meta_obj->key() ] = $extra_meta_obj->value();
-                }
-            }
-        } else {
-            $extra_meta_objs = $this->get_many_related('Extra_Meta');
-            foreach ($extra_meta_objs as $extra_meta_obj) {
-                if ($extra_meta_obj instanceof EE_Extra_Meta) {
-                    if (! isset($return_array[ $extra_meta_obj->key() ])) {
-                        $return_array[ $extra_meta_obj->key() ] = array();
-                    }
-                    $return_array[ $extra_meta_obj->key() ][ $extra_meta_obj->ID() ] = $extra_meta_obj->value();
-                }
-            }
-        }
-        return $return_array;
-    }
-
-
-    /**
-     * Gets a pretty nice displayable nice for this model object. Often overridden
-     *
-     * @return string
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function name()
-    {
-        // find a field that's not a text field
-        $field_we_can_use = $this->get_model()->get_a_field_of_type('EE_Text_Field_Base');
-        if ($field_we_can_use) {
-            return $this->get($field_we_can_use->get_name());
-        }
-        $first_few_properties = $this->model_field_array();
-        $first_few_properties = array_slice($first_few_properties, 0, 3);
-        $name_parts = array();
-        foreach ($first_few_properties as $name => $value) {
-            $name_parts[] = "$name:$value";
-        }
-        return implode(',', $name_parts);
-    }
-
-
-    /**
-     * in_entity_map
-     * Checks if this model object has been proven to already be in the entity map
-     *
-     * @return boolean
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function in_entity_map()
-    {
-        // well, if we looked, did we find it in the entity map?
-        return $this->ID() && $this->get_model()->get_from_entity_map($this->ID()) === $this;
-    }
-
-
-    /**
-     * refresh_from_db
-     * Makes sure the fields and values on this model object are in-sync with what's in the database.
-     *
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error if this model object isn't in the entity mapper (because then you should
-     * just use what's in the entity mapper and refresh it) and WP_DEBUG is TRUE
-     */
-    public function refresh_from_db()
-    {
-        if ($this->ID() && $this->in_entity_map()) {
-            $this->get_model()->refresh_entity_map_from_db($this->ID());
-        } else {
-            // if it doesn't have ID, you shouldn't be asking to refresh it from teh database (because its not in the database)
-            // if it has an ID but it's not in the map, and you're asking me to refresh it
-            // that's kinda dangerous. You should just use what's in the entity map, or add this to the entity map if there's
-            // absolutely nothing in it for this ID
-            if (WP_DEBUG) {
-                throw new EE_Error(
-                    sprintf(
-                        esc_html__(
-                            'Trying to refresh a model object with ID "%1$s" that\'s not in the entity map? First off: you should put it in the entity map by calling %2$s. Second off, if you want what\'s in the database right now, you should just call %3$s yourself and discard this model object.',
-                            'event_espresso'
-                        ),
-                        $this->ID(),
-                        get_class($this->get_model()) . '::instance()->add_to_entity_map()',
-                        get_class($this->get_model()) . '::instance()->refresh_entity_map()'
-                    )
-                );
-            }
-        }
-    }
-
-
-    /**
-     * Change $fields' values to $new_value_sql (which is a string of raw SQL)
-     *
-     * @since 4.9.80.p
-     * @param EE_Model_Field_Base[] $fields
-     * @param string $new_value_sql
-     *      example: 'column_name=123',
-     *      or 'column_name=column_name+1',
-     *      or 'column_name= CASE
-     *          WHEN (`column_name` + `other_column` + 5) <= `yet_another_column`
-     *          THEN `column_name` + 5
-     *          ELSE `column_name`
-     *      END'
-     *      Also updates $field on this model object with the latest value from the database.
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    protected function updateFieldsInDB($fields, $new_value_sql)
-    {
-        // First make sure this model object actually exists in the DB. It would be silly to try to update it in the DB
-        // if it wasn't even there to start off.
-        if (! $this->ID()) {
-            $this->save();
-        }
-        global $wpdb;
-        if (empty($fields)) {
-            throw new InvalidArgumentException(
-                esc_html__(
-                    'EE_Base_Class::updateFieldsInDB was passed an empty array of fields.',
-                    'event_espresso'
-                )
-            );
-        }
-        $first_field = reset($fields);
-        $table_alias = $first_field->get_table_alias();
-        foreach ($fields as $field) {
-            if ($table_alias !== $field->get_table_alias()) {
-                throw new InvalidArgumentException(
-                    sprintf(
-                        esc_html__(
-                            // @codingStandardsIgnoreStart
-                            'EE_Base_Class::updateFieldsInDB was passed fields for different tables ("%1$s" and "%2$s"), which is not supported. Instead, please call the method multiple times.',
-                            // @codingStandardsIgnoreEnd
-                            'event_espresso'
-                        ),
-                        $table_alias,
-                        $field->get_table_alias()
-                    )
-                );
-            }
-        }
-        // Ok the fields are now known to all be for the same table. Proceed with creating the SQL to update it.
-        $table_obj = $this->get_model()->get_table_obj_by_alias($table_alias);
-        $table_pk_value = $this->ID();
-        $table_name = $table_obj->get_table_name();
-        if ($table_obj instanceof EE_Secondary_Table) {
-            $table_pk_field_name = $table_obj->get_fk_on_table();
-        } else {
-            $table_pk_field_name = $table_obj->get_pk_column();
-        }
-
-        $query =
-            "UPDATE `{$table_name}`
+	/**
+	 * This is an array of the original properties and values provided during construction
+	 * of this model object. (keys are model field names, values are their values).
+	 * This list is important to remember so that when we are merging data from the db, we know
+	 * which values to override and which to not override.
+	 *
+	 * @var array
+	 */
+	protected $_props_n_values_provided_in_constructor;
+
+	/**
+	 * Timezone
+	 * This gets set by the "set_timezone()" method so that we know what timezone incoming strings|timestamps are in.
+	 * This can also be used before a get to set what timezone you want strings coming out of the object to be in.  NOT
+	 * all EE_Base_Class child classes use this property but any that use a EE_Datetime_Field data type will have
+	 * access to it.
+	 *
+	 * @var string
+	 */
+	protected $_timezone;
+
+	/**
+	 * date format
+	 * pattern or format for displaying dates
+	 *
+	 * @var string $_dt_frmt
+	 */
+	protected $_dt_frmt;
+
+	/**
+	 * time format
+	 * pattern or format for displaying time
+	 *
+	 * @var string $_tm_frmt
+	 */
+	protected $_tm_frmt;
+
+	/**
+	 * This property is for holding a cached array of object properties indexed by property name as the key.
+	 * The purpose of this is for setting a cache on properties that may have calculated values after a
+	 * prepare_for_get.  That way the cache can be checked first and the calculated property returned instead of having
+	 * to recalculate. Used by _set_cached_property() and _get_cached_property() methods.
+	 *
+	 * @var array
+	 */
+	protected $_cached_properties = array();
+
+	/**
+	 * An array containing keys of the related model, and values are either an array of related mode objects or a
+	 * single
+	 * related model object. see the model's _model_relations. The keys should match those specified. And if the
+	 * relation is of type EE_Belongs_To (or one of its children), then there should only be ONE related model object,
+	 * all others have an array)
+	 *
+	 * @var array
+	 */
+	protected $_model_relations = array();
+
+	/**
+	 * Array where keys are field names (see the model's _fields property) and values are their values. To see what
+	 * their types should be, look at what that field object returns on its prepare_for_get and prepare_for_set methods)
+	 *
+	 * @var array
+	 */
+	protected $_fields = array();
+
+	/**
+	 * @var boolean indicating whether or not this model object is intended to ever be saved
+	 * For example, we might create model objects intended to only be used for the duration
+	 * of this request and to be thrown away, and if they were accidentally saved
+	 * it would be a bug.
+	 */
+	protected $_allow_persist = true;
+
+	/**
+	 * @var boolean indicating whether or not this model object's properties have changed since construction
+	 */
+	protected $_has_changes = false;
+
+	/**
+	 * @var EEM_Base
+	 */
+	protected $_model;
+
+	/**
+	 * This is a cache of results from custom selections done on a query that constructs this entity. The only purpose
+	 * for these values is for retrieval of the results, they are not further queryable and they are not persisted to
+	 * the db.  They also do not automatically update if there are any changes to the data that produced their results.
+	 * The format is a simple array of field_alias => field_value.  So for instance if a custom select was something
+	 * like,  "Select COUNT(Registration.REG_ID) as Registration_Count ...", then the resulting value will be in this
+	 * array as:
+	 * array(
+	 *  'Registration_Count' => 24
+	 * );
+	 * Note: if the custom select configuration for the query included a data type, the value will be in the data type
+	 * provided for the query (@see EventEspresso\core\domain\values\model\CustomSelects::__construct phpdocs for more
+	 * info)
+	 *
+	 * @var array
+	 */
+	protected $custom_selection_results = array();
+
+
+	/**
+	 * basic constructor for Event Espresso classes, performs any necessary initialization, and verifies it's children
+	 * play nice
+	 *
+	 * @param array   $fieldValues                             where each key is a field (ie, array key in the 2nd
+	 *                                                         layer of the model's _fields array, (eg, EVT_ID,
+	 *                                                         TXN_amount, QST_name, etc) and values are their values
+	 * @param boolean $bydb                                    a flag for setting if the class is instantiated by the
+	 *                                                         corresponding db model or not.
+	 * @param string  $timezone                                indicate what timezone you want any datetime fields to
+	 *                                                         be in when instantiating a EE_Base_Class object.
+	 * @param array   $date_formats                            An array of date formats to set on construct where first
+	 *                                                         value is the date_format and second value is the time
+	 *                                                         format.
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	protected function __construct($fieldValues = array(), $bydb = false, $timezone = '', $date_formats = array())
+	{
+		$className = get_class($this);
+		do_action("AHEE__{$className}__construct", $this, $fieldValues);
+		$model = $this->get_model();
+		$model_fields = $model->field_settings(false);
+		// ensure $fieldValues is an array
+		$fieldValues = is_array($fieldValues) ? $fieldValues : array($fieldValues);
+		// verify client code has not passed any invalid field names
+		foreach ($fieldValues as $field_name => $field_value) {
+			if (! isset($model_fields[ $field_name ])) {
+				throw new EE_Error(
+					sprintf(
+						esc_html__(
+							'Invalid field (%s) passed to constructor of %s. Allowed fields are :%s',
+							'event_espresso'
+						),
+						$field_name,
+						get_class($this),
+						implode(', ', array_keys($model_fields))
+					)
+				);
+			}
+		}
+		$this->_timezone = EEH_DTT_Helper::get_valid_timezone_string($timezone);
+		if (! empty($date_formats) && is_array($date_formats)) {
+			list($this->_dt_frmt, $this->_tm_frmt) = $date_formats;
+		} else {
+			// set default formats for date and time
+			$this->_dt_frmt = (string) get_option('date_format', 'Y-m-d');
+			$this->_tm_frmt = (string) get_option('time_format', 'g:i a');
+		}
+		// if db model is instantiating
+		if ($bydb) {
+			// client code has indicated these field values are from the database
+			foreach ($model_fields as $fieldName => $field) {
+				$this->set_from_db(
+					$fieldName,
+					isset($fieldValues[ $fieldName ]) ? $fieldValues[ $fieldName ] : null
+				);
+			}
+		} else {
+			// we're constructing a brand
+			// new instance of the model object. Generally, this means we'll need to do more field validation
+			foreach ($model_fields as $fieldName => $field) {
+				$this->set(
+					$fieldName,
+					isset($fieldValues[ $fieldName ]) ? $fieldValues[ $fieldName ] : null,
+					true
+				);
+			}
+		}
+		// remember what values were passed to this constructor
+		$this->_props_n_values_provided_in_constructor = $fieldValues;
+		// remember in entity mapper
+		if (! $bydb && $model->has_primary_key_field() && $this->ID()) {
+			$model->add_to_entity_map($this);
+		}
+		// setup all the relations
+		foreach ($model->relation_settings() as $relation_name => $relation_obj) {
+			if ($relation_obj instanceof EE_Belongs_To_Relation) {
+				$this->_model_relations[ $relation_name ] = null;
+			} else {
+				$this->_model_relations[ $relation_name ] = array();
+			}
+		}
+		/**
+		 * Action done at the end of each model object construction
+		 *
+		 * @param EE_Base_Class $this the model object just created
+		 */
+		do_action('AHEE__EE_Base_Class__construct__finished', $this);
+	}
+
+
+	/**
+	 * Gets whether or not this model object is allowed to persist/be saved to the database.
+	 *
+	 * @return boolean
+	 */
+	public function allow_persist()
+	{
+		return $this->_allow_persist;
+	}
+
+
+	/**
+	 * Sets whether or not this model object should be allowed to be saved to the DB.
+	 * Normally once this is set to FALSE you wouldn't set it back to TRUE, unless
+	 * you got new information that somehow made you change your mind.
+	 *
+	 * @param boolean $allow_persist
+	 * @return boolean
+	 */
+	public function set_allow_persist($allow_persist)
+	{
+		return $this->_allow_persist = $allow_persist;
+	}
+
+
+	/**
+	 * Gets the field's original value when this object was constructed during this request.
+	 * This can be helpful when determining if a model object has changed or not
+	 *
+	 * @param string $field_name
+	 * @return mixed|null
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get_original($field_name)
+	{
+		if (isset($this->_props_n_values_provided_in_constructor[ $field_name ])
+			&& $field_settings = $this->get_model()->field_settings_for($field_name)
+		) {
+			return $field_settings->prepare_for_get($this->_props_n_values_provided_in_constructor[ $field_name ]);
+		}
+		return null;
+	}
+
+
+	/**
+	 * @param EE_Base_Class $obj
+	 * @return string
+	 */
+	public function get_class($obj)
+	{
+		return get_class($obj);
+	}
+
+
+	/**
+	 * Overrides parent because parent expects old models.
+	 * This also doesn't do any validation, and won't work for serialized arrays
+	 *
+	 * @param    string $field_name
+	 * @param    mixed  $field_value
+	 * @param bool      $use_default
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @throws ReflectionException
+	 * @throws ReflectionException
+	 */
+	public function set($field_name, $field_value, $use_default = false)
+	{
+		// if not using default and nothing has changed, and object has already been setup (has ID),
+		// then don't do anything
+		if (! $use_default
+			&& $this->_fields[ $field_name ] === $field_value
+			&& $this->ID()
+		) {
+			return;
+		}
+		$model = $this->get_model();
+		$this->_has_changes = true;
+		$field_obj = $model->field_settings_for($field_name);
+		if ($field_obj instanceof EE_Model_Field_Base) {
+			// if ( method_exists( $field_obj, 'set_timezone' )) {
+			if ($field_obj instanceof EE_Datetime_Field) {
+				$field_obj->set_timezone($this->_timezone);
+				$field_obj->set_date_format($this->_dt_frmt);
+				$field_obj->set_time_format($this->_tm_frmt);
+			}
+			$holder_of_value = $field_obj->prepare_for_set($field_value);
+			// should the value be null?
+			if (($field_value === null || $holder_of_value === null || $holder_of_value === '') && $use_default) {
+				$this->_fields[ $field_name ] = $field_obj->get_default_value();
+				/**
+				 * To save having to refactor all the models, if a default value is used for a
+				 * EE_Datetime_Field, and that value is not null nor is it a DateTime
+				 * object.  Then let's do a set again to ensure that it becomes a DateTime
+				 * object.
+				 *
+				 * @since 4.6.10+
+				 */
+				if ($field_obj instanceof EE_Datetime_Field
+					&& $this->_fields[ $field_name ] !== null
+					&& ! $this->_fields[ $field_name ] instanceof DateTime
+				) {
+					empty($this->_fields[ $field_name ])
+						? $this->set($field_name, time())
+						: $this->set($field_name, $this->_fields[ $field_name ]);
+				}
+			} else {
+				$this->_fields[ $field_name ] = $holder_of_value;
+			}
+			// if we're not in the constructor...
+			// now check if what we set was a primary key
+			if (// note: props_n_values_provided_in_constructor is only set at the END of the constructor
+				$this->_props_n_values_provided_in_constructor
+				&& $field_value
+				&& $field_name === $model->primary_key_name()
+			) {
+				// if so, we want all this object's fields to be filled either with
+				// what we've explicitly set on this model
+				// or what we have in the db
+				// echo "setting primary key!";
+				$fields_on_model = self::_get_model(get_class($this))->field_settings();
+				$obj_in_db = self::_get_model(get_class($this))->get_one_by_ID($field_value);
+				foreach ($fields_on_model as $field_obj) {
+					if (! array_key_exists($field_obj->get_name(), $this->_props_n_values_provided_in_constructor)
+						&& $field_obj->get_name() !== $field_name
+					) {
+						$this->set($field_obj->get_name(), $obj_in_db->get($field_obj->get_name()));
+					}
+				}
+				// oh this model object has an ID? well make sure its in the entity mapper
+				$model->add_to_entity_map($this);
+			}
+			// let's unset any cache for this field_name from the $_cached_properties property.
+			$this->_clear_cached_property($field_name);
+		} else {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'A valid EE_Model_Field_Base could not be found for the given field name: %s',
+						'event_espresso'
+					),
+					$field_name
+				)
+			);
+		}
+	}
+
+
+	/**
+	 * Set custom select values for model.
+	 *
+	 * @param array $custom_select_values
+	 */
+	public function setCustomSelectsValues(array $custom_select_values)
+	{
+		$this->custom_selection_results = $custom_select_values;
+	}
+
+
+	/**
+	 * Returns the custom select value for the provided alias if its set.
+	 * If not set, returns null.
+	 *
+	 * @param string $alias
+	 * @return string|int|float|null
+	 */
+	public function getCustomSelect($alias)
+	{
+		return isset($this->custom_selection_results[ $alias ])
+			? $this->custom_selection_results[ $alias ]
+			: null;
+	}
+
+
+	/**
+	 * This sets the field value on the db column if it exists for the given $column_name or
+	 * saves it to EE_Extra_Meta if the given $column_name does not match a db column.
+	 *
+	 * @see EE_message::get_column_value for related documentation on the necessity of this method.
+	 * @param string $field_name  Must be the exact column name.
+	 * @param mixed  $field_value The value to set.
+	 * @return int|bool @see EE_Base_Class::update_extra_meta() for return docs.
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_field_or_extra_meta($field_name, $field_value)
+	{
+		if ($this->get_model()->has_field($field_name)) {
+			$this->set($field_name, $field_value);
+			return true;
+		}
+		// ensure this object is saved first so that extra meta can be properly related.
+		$this->save();
+		return $this->update_extra_meta($field_name, $field_value);
+	}
+
+
+	/**
+	 * This retrieves the value of the db column set on this class or if that's not present
+	 * it will attempt to retrieve from extra_meta if found.
+	 * Example Usage:
+	 * Via EE_Message child class:
+	 * Due to the dynamic nature of the EE_messages system, EE_messengers will always have a "to",
+	 * "from", "subject", and "content" field (as represented in the EE_Message schema), however they may
+	 * also have additional main fields specific to the messenger.  The system accommodates those extra
+	 * fields through the EE_Extra_Meta table.  This method allows for EE_messengers to retrieve the
+	 * value for those extra fields dynamically via the EE_message object.
+	 *
+	 * @param  string $field_name expecting the fully qualified field name.
+	 * @return mixed|null  value for the field if found.  null if not found.
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get_field_or_extra_meta($field_name)
+	{
+		if ($this->get_model()->has_field($field_name)) {
+			$column_value = $this->get($field_name);
+		} else {
+			// This isn't a column in the main table, let's see if it is in the extra meta.
+			$column_value = $this->get_extra_meta($field_name, true, null);
+		}
+		return $column_value;
+	}
+
+
+	/**
+	 * See $_timezone property for description of what the timezone property is for.  This SETS the timezone internally
+	 * for being able to reference what timezone we are running conversions on when converting TO the internal timezone
+	 * (UTC Unix Timestamp) for the object OR when converting FROM the internal timezone (UTC Unix Timestamp). This is
+	 * available to all child classes that may be using the EE_Datetime_Field for a field data type.
+	 *
+	 * @access public
+	 * @param string $timezone A valid timezone string as described by @link http://www.php.net/manual/en/timezones.php
+	 * @return void
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_timezone($timezone = '')
+	{
+		$this->_timezone = EEH_DTT_Helper::get_valid_timezone_string($timezone);
+		// make sure we clear all cached properties because they won't be relevant now
+		$this->_clear_cached_properties();
+		// make sure we update field settings and the date for all EE_Datetime_Fields
+		$model_fields = $this->get_model()->field_settings(false);
+		foreach ($model_fields as $field_name => $field_obj) {
+			if ($field_obj instanceof EE_Datetime_Field) {
+				$field_obj->set_timezone($this->_timezone);
+				if (isset($this->_fields[ $field_name ]) && $this->_fields[ $field_name ] instanceof DateTime) {
+					EEH_DTT_Helper::setTimezone($this->_fields[ $field_name ], new DateTimeZone($this->_timezone));
+				}
+			}
+		}
+	}
+
+
+	/**
+	 * This just returns whatever is set for the current timezone.
+	 *
+	 * @access public
+	 * @return string timezone string
+	 */
+	public function get_timezone()
+	{
+		return $this->_timezone;
+	}
+
+
+	/**
+	 * This sets the internal date format to what is sent in to be used as the new default for the class
+	 * internally instead of wp set date format options
+	 *
+	 * @since 4.6
+	 * @param string $format should be a format recognizable by PHP date() functions.
+	 */
+	public function set_date_format($format)
+	{
+		$this->_dt_frmt = $format;
+		// clear cached_properties because they won't be relevant now.
+		$this->_clear_cached_properties();
+	}
+
+
+	/**
+	 * This sets the internal time format string to what is sent in to be used as the new default for the
+	 * class internally instead of wp set time format options.
+	 *
+	 * @since 4.6
+	 * @param string $format should be a format recognizable by PHP date() functions.
+	 */
+	public function set_time_format($format)
+	{
+		$this->_tm_frmt = $format;
+		// clear cached_properties because they won't be relevant now.
+		$this->_clear_cached_properties();
+	}
+
+
+	/**
+	 * This returns the current internal set format for the date and time formats.
+	 *
+	 * @param bool $full           if true (default), then return the full format.  Otherwise will return an array
+	 *                             where the first value is the date format and the second value is the time format.
+	 * @return mixed string|array
+	 */
+	public function get_format($full = true)
+	{
+		return $full ? $this->_dt_frmt . ' ' . $this->_tm_frmt : array($this->_dt_frmt, $this->_tm_frmt);
+	}
+
+
+	/**
+	 * cache
+	 * stores the passed model object on the current model object.
+	 * In certain circumstances, we can use this cached model object instead of querying for another one entirely.
+	 *
+	 * @param string        $relationName    one of the keys in the _model_relations array on the model. Eg
+	 *                                       'Registration' associated with this model object
+	 * @param EE_Base_Class $object_to_cache that has a relation to this model object. (Eg, if this is a Transaction,
+	 *                                       that could be a payment or a registration)
+	 * @param null          $cache_id        a string or number that will be used as the key for any Belongs_To_Many
+	 *                                       items which will be stored in an array on this object
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @return mixed    index into cache, or just TRUE if the relation is of type Belongs_To (because there's only one
+	 *                                       related thing, no array)
+	 */
+	public function cache($relationName = '', $object_to_cache = null, $cache_id = null)
+	{
+		// its entirely possible that there IS no related object yet in which case there is nothing to cache.
+		if (! $object_to_cache instanceof EE_Base_Class) {
+			return false;
+		}
+		// also get "how" the object is related, or throw an error
+		if (! $relationship_to_model = $this->get_model()->related_settings_for($relationName)) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__('There is no relationship to %s on a %s. Cannot cache it', 'event_espresso'),
+					$relationName,
+					get_class($this)
+				)
+			);
+		}
+		// how many things are related ?
+		if ($relationship_to_model instanceof EE_Belongs_To_Relation) {
+			// if it's a "belongs to" relationship, then there's only one related model object
+			// eg, if this is a registration, there's only 1 attendee for it
+			// so for these model objects just set it to be cached
+			$this->_model_relations[ $relationName ] = $object_to_cache;
+			$return = true;
+		} else {
+			// otherwise, this is the "many" side of a one to many relationship,
+			// so we'll add the object to the array of related objects for that type.
+			// eg: if this is an event, there are many registrations for that event,
+			// so we cache the registrations in an array
+			if (! is_array($this->_model_relations[ $relationName ])) {
+				// if for some reason, the cached item is a model object,
+				// then stick that in the array, otherwise start with an empty array
+				$this->_model_relations[ $relationName ] = $this->_model_relations[ $relationName ]
+														   instanceof
+														   EE_Base_Class
+					? array($this->_model_relations[ $relationName ]) : array();
+			}
+			// first check for a cache_id which is normally empty
+			if (! empty($cache_id)) {
+				// if the cache_id exists, then it means we are purposely trying to cache this
+				// with a known key that can then be used to retrieve the object later on
+				$this->_model_relations[ $relationName ][ $cache_id ] = $object_to_cache;
+				$return = $cache_id;
+			} elseif ($object_to_cache->ID()) {
+				// OR the cached object originally came from the db, so let's just use it's PK for an ID
+				$this->_model_relations[ $relationName ][ $object_to_cache->ID() ] = $object_to_cache;
+				$return = $object_to_cache->ID();
+			} else {
+				// OR it's a new object with no ID, so just throw it in the array with an auto-incremented ID
+				$this->_model_relations[ $relationName ][] = $object_to_cache;
+				// move the internal pointer to the end of the array
+				end($this->_model_relations[ $relationName ]);
+				// and grab the key so that we can return it
+				$return = key($this->_model_relations[ $relationName ]);
+			}
+		}
+		return $return;
+	}
+
+
+	/**
+	 * For adding an item to the cached_properties property.
+	 *
+	 * @access protected
+	 * @param string      $fieldname the property item the corresponding value is for.
+	 * @param mixed       $value     The value we are caching.
+	 * @param string|null $cache_type
+	 * @return void
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected function _set_cached_property($fieldname, $value, $cache_type = null)
+	{
+		// first make sure this property exists
+		$this->get_model()->field_settings_for($fieldname);
+		$cache_type = empty($cache_type) ? 'standard' : $cache_type;
+		$this->_cached_properties[ $fieldname ][ $cache_type ] = $value;
+	}
+
+
+	/**
+	 * This returns the value cached property if it exists OR the actual property value if the cache doesn't exist.
+	 * This also SETS the cache if we return the actual property!
+	 *
+	 * @param string $fieldname        the name of the property we're trying to retrieve
+	 * @param bool   $pretty
+	 * @param string $extra_cache_ref  This allows the user to specify an extra cache ref for the given property
+	 *                                 (in cases where the same property may be used for different outputs
+	 *                                 - i.e. datetime, money etc.)
+	 *                                 It can also accept certain pre-defined "schema" strings
+	 *                                 to define how to output the property.
+	 *                                 see the field's prepare_for_pretty_echoing for what strings can be used
+	 * @return mixed                   whatever the value for the property is we're retrieving
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected function _get_cached_property($fieldname, $pretty = false, $extra_cache_ref = null)
+	{
+		// verify the field exists
+		$model = $this->get_model();
+		$model->field_settings_for($fieldname);
+		$cache_type = $pretty ? 'pretty' : 'standard';
+		$cache_type .= ! empty($extra_cache_ref) ? '_' . $extra_cache_ref : '';
+		if (isset($this->_cached_properties[ $fieldname ][ $cache_type ])) {
+			return $this->_cached_properties[ $fieldname ][ $cache_type ];
+		}
+		$value = $this->_get_fresh_property($fieldname, $pretty, $extra_cache_ref);
+		$this->_set_cached_property($fieldname, $value, $cache_type);
+		return $value;
+	}
+
+
+	/**
+	 * If the cache didn't fetch the needed item, this fetches it.
+	 *
+	 * @param string $fieldname
+	 * @param bool   $pretty
+	 * @param string $extra_cache_ref
+	 * @return mixed
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	protected function _get_fresh_property($fieldname, $pretty = false, $extra_cache_ref = null)
+	{
+		$field_obj = $this->get_model()->field_settings_for($fieldname);
+		// If this is an EE_Datetime_Field we need to make sure timezone, formats, and output are correct
+		if ($field_obj instanceof EE_Datetime_Field) {
+			$this->_prepare_datetime_field($field_obj, $pretty, $extra_cache_ref);
+		}
+		if (! isset($this->_fields[ $fieldname ])) {
+			$this->_fields[ $fieldname ] = null;
+		}
+		$value = $pretty
+			? $field_obj->prepare_for_pretty_echoing($this->_fields[ $fieldname ], $extra_cache_ref)
+			: $field_obj->prepare_for_get($this->_fields[ $fieldname ]);
+		return $value;
+	}
+
+
+	/**
+	 * set timezone, formats, and output for EE_Datetime_Field objects
+	 *
+	 * @param \EE_Datetime_Field $datetime_field
+	 * @param bool               $pretty
+	 * @param null               $date_or_time
+	 * @return void
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected function _prepare_datetime_field(
+		EE_Datetime_Field $datetime_field,
+		$pretty = false,
+		$date_or_time = null
+	) {
+		$datetime_field->set_timezone($this->_timezone);
+		$datetime_field->set_date_format($this->_dt_frmt, $pretty);
+		$datetime_field->set_time_format($this->_tm_frmt, $pretty);
+		// set the output returned
+		switch ($date_or_time) {
+			case 'D':
+				$datetime_field->set_date_time_output('date');
+				break;
+			case 'T':
+				$datetime_field->set_date_time_output('time');
+				break;
+			default:
+				$datetime_field->set_date_time_output();
+		}
+	}
+
+
+	/**
+	 * This just takes care of clearing out the cached_properties
+	 *
+	 * @return void
+	 */
+	protected function _clear_cached_properties()
+	{
+		$this->_cached_properties = array();
+	}
+
+
+	/**
+	 * This just clears out ONE property if it exists in the cache
+	 *
+	 * @param  string $property_name the property to remove if it exists (from the _cached_properties array)
+	 * @return void
+	 */
+	protected function _clear_cached_property($property_name)
+	{
+		if (isset($this->_cached_properties[ $property_name ])) {
+			unset($this->_cached_properties[ $property_name ]);
+		}
+	}
+
+
+	/**
+	 * Ensures that this related thing is a model object.
+	 *
+	 * @param mixed  $object_or_id EE_base_Class/int/string either a related model object, or its ID
+	 * @param string $model_name   name of the related thing, eg 'Attendee',
+	 * @return EE_Base_Class
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected function ensure_related_thing_is_model_obj($object_or_id, $model_name)
+	{
+		$other_model_instance = self::_get_model_instance_with_name(
+			self::_get_model_classname($model_name),
+			$this->_timezone
+		);
+		return $other_model_instance->ensure_is_obj($object_or_id);
+	}
+
+
+	/**
+	 * Forgets the cached model of the given relation Name. So the next time we request it,
+	 * we will fetch it again from the database. (Handy if you know it's changed somehow).
+	 * If a specific object is supplied, and the relationship to it is either a HasMany or HABTM,
+	 * then only remove that one object from our cached array. Otherwise, clear the entire list
+	 *
+	 * @param string $relationName                         one of the keys in the _model_relations array on the model.
+	 *                                                     Eg 'Registration'
+	 * @param mixed  $object_to_remove_or_index_into_array or an index into the array of cached things, or NULL
+	 *                                                     if you intend to use $clear_all = TRUE, or the relation only
+	 *                                                     has 1 object anyways (ie, it's a BelongsToRelation)
+	 * @param bool   $clear_all                            This flags clearing the entire cache relation property if
+	 *                                                     this is HasMany or HABTM.
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @return EE_Base_Class | boolean from which was cleared from the cache, or true if we requested to remove a
+	 *                                                     relation from all
+	 */
+	public function clear_cache($relationName, $object_to_remove_or_index_into_array = null, $clear_all = false)
+	{
+		$relationship_to_model = $this->get_model()->related_settings_for($relationName);
+		$index_in_cache = '';
+		if (! $relationship_to_model) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__('There is no relationship to %s on a %s. Cannot clear that cache', 'event_espresso'),
+					$relationName,
+					get_class($this)
+				)
+			);
+		}
+		if ($clear_all) {
+			$obj_removed = true;
+			$this->_model_relations[ $relationName ] = null;
+		} elseif ($relationship_to_model instanceof EE_Belongs_To_Relation) {
+			$obj_removed = $this->_model_relations[ $relationName ];
+			$this->_model_relations[ $relationName ] = null;
+		} else {
+			if ($object_to_remove_or_index_into_array instanceof EE_Base_Class
+				&& $object_to_remove_or_index_into_array->ID()
+			) {
+				$index_in_cache = $object_to_remove_or_index_into_array->ID();
+				if (is_array($this->_model_relations[ $relationName ])
+					&& ! isset($this->_model_relations[ $relationName ][ $index_in_cache ])
+				) {
+					$index_found_at = null;
+					// find this object in the array even though it has a different key
+					foreach ($this->_model_relations[ $relationName ] as $index => $obj) {
+						/** @noinspection TypeUnsafeComparisonInspection */
+						if ($obj instanceof EE_Base_Class
+							&& (
+								$obj == $object_to_remove_or_index_into_array
+								|| $obj->ID() === $object_to_remove_or_index_into_array->ID()
+							)
+						) {
+							$index_found_at = $index;
+							break;
+						}
+					}
+					if ($index_found_at) {
+						$index_in_cache = $index_found_at;
+					} else {
+						// it wasn't found. huh. well obviously it doesn't need to be removed from teh cache
+						// if it wasn't in it to begin with. So we're done
+						return $object_to_remove_or_index_into_array;
+					}
+				}
+			} elseif ($object_to_remove_or_index_into_array instanceof EE_Base_Class) {
+				// so they provided a model object, but it's not yet saved to the DB... so let's go hunting for it!
+				foreach ($this->get_all_from_cache($relationName) as $index => $potentially_obj_we_want) {
+					/** @noinspection TypeUnsafeComparisonInspection */
+					if ($potentially_obj_we_want == $object_to_remove_or_index_into_array) {
+						$index_in_cache = $index;
+					}
+				}
+			} else {
+				$index_in_cache = $object_to_remove_or_index_into_array;
+			}
+			// supposedly we've found it. But it could just be that the client code
+			// provided a bad index/object
+			if (isset($this->_model_relations[ $relationName ][ $index_in_cache ])) {
+				$obj_removed = $this->_model_relations[ $relationName ][ $index_in_cache ];
+				unset($this->_model_relations[ $relationName ][ $index_in_cache ]);
+			} else {
+				// that thing was never cached anyways.
+				$obj_removed = null;
+			}
+		}
+		return $obj_removed;
+	}
+
+
+	/**
+	 * update_cache_after_object_save
+	 * Allows a cached item to have it's cache ID (within the array of cached items) reset using the new ID it has
+	 * obtained after being saved to the db
+	 *
+	 * @param string        $relationName       - the type of object that is cached
+	 * @param EE_Base_Class $newly_saved_object - the newly saved object to be re-cached
+	 * @param string        $current_cache_id   - the ID that was used when originally caching the object
+	 * @return boolean TRUE on success, FALSE on fail
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function update_cache_after_object_save(
+		$relationName,
+		EE_Base_Class $newly_saved_object,
+		$current_cache_id = ''
+	) {
+		// verify that incoming object is of the correct type
+		$obj_class = 'EE_' . $relationName;
+		if ($newly_saved_object instanceof $obj_class) {
+			/* @type EE_Base_Class $newly_saved_object */
+			// now get the type of relation
+			$relationship_to_model = $this->get_model()->related_settings_for($relationName);
+			// if this is a 1:1 relationship
+			if ($relationship_to_model instanceof EE_Belongs_To_Relation) {
+				// then just replace the cached object with the newly saved object
+				$this->_model_relations[ $relationName ] = $newly_saved_object;
+				return true;
+				// or if it's some kind of sordid feral polyamorous relationship...
+			}
+			if (is_array($this->_model_relations[ $relationName ])
+				&& isset($this->_model_relations[ $relationName ][ $current_cache_id ])
+			) {
+				// then remove the current cached item
+				unset($this->_model_relations[ $relationName ][ $current_cache_id ]);
+				// and cache the newly saved object using it's new ID
+				$this->_model_relations[ $relationName ][ $newly_saved_object->ID() ] = $newly_saved_object;
+				return true;
+			}
+		}
+		return false;
+	}
+
+
+	/**
+	 * Fetches a single EE_Base_Class on that relation. (If the relation is of type
+	 * BelongsTo, it will only ever have 1 object. However, other relations could have an array of objects)
+	 *
+	 * @param string $relationName
+	 * @return EE_Base_Class
+	 */
+	public function get_one_from_cache($relationName)
+	{
+		$cached_array_or_object = isset($this->_model_relations[ $relationName ])
+			? $this->_model_relations[ $relationName ]
+			: null;
+		if (is_array($cached_array_or_object)) {
+			return array_shift($cached_array_or_object);
+		}
+		return $cached_array_or_object;
+	}
+
+
+	/**
+	 * Fetches a single EE_Base_Class on that relation. (If the relation is of type
+	 * BelongsTo, it will only ever have 1 object. However, other relations could have an array of objects)
+	 *
+	 * @param string $relationName
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @return EE_Base_Class[] NOT necessarily indexed by primary keys
+	 */
+	public function get_all_from_cache($relationName)
+	{
+		$objects = isset($this->_model_relations[ $relationName ]) ? $this->_model_relations[ $relationName ] : array();
+		// if the result is not an array, but exists, make it an array
+		$objects = is_array($objects) ? $objects : array($objects);
+		// bugfix for https://events.codebasehq.com/projects/event-espresso/tickets/7143
+		// basically, if this model object was stored in the session, and these cached model objects
+		// already have IDs, let's make sure they're in their model's entity mapper
+		// otherwise we will have duplicates next time we call
+		// EE_Registry::instance()->load_model( $relationName )->get_one_by_ID( $result->ID() );
+		$model = EE_Registry::instance()->load_model($relationName);
+		foreach ($objects as $model_object) {
+			if ($model instanceof EEM_Base && $model_object instanceof EE_Base_Class) {
+				// ensure its in the map if it has an ID; otherwise it will be added to the map when its saved
+				if ($model_object->ID()) {
+					$model->add_to_entity_map($model_object);
+				}
+			} else {
+				throw new EE_Error(
+					sprintf(
+						esc_html__(
+							'Error retrieving related model objects. Either $1%s is not a model or $2%s is not a model object',
+							'event_espresso'
+						),
+						$relationName,
+						gettype($model_object)
+					)
+				);
+			}
+		}
+		return $objects;
+	}
+
+
+	/**
+	 * Returns the next x number of EE_Base_Class objects in sequence from this object as found in the database
+	 * matching the given query conditions.
+	 *
+	 * @param null  $field_to_order_by  What field is being used as the reference point.
+	 * @param int   $limit              How many objects to return.
+	 * @param array $query_params       Any additional conditions on the query.
+	 * @param null  $columns_to_select  If left null, then an array of EE_Base_Class objects is returned, otherwise
+	 *                                  you can indicate just the columns you want returned
+	 * @return array|EE_Base_Class[]
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function next_x($field_to_order_by = null, $limit = 1, $query_params = array(), $columns_to_select = null)
+	{
+		$model = $this->get_model();
+		$field = empty($field_to_order_by) && $model->has_primary_key_field()
+			? $model->get_primary_key_field()->get_name()
+			: $field_to_order_by;
+		$current_value = ! empty($field) ? $this->get($field) : null;
+		if (empty($field) || empty($current_value)) {
+			return array();
+		}
+		return $model->next_x($current_value, $field, $limit, $query_params, $columns_to_select);
+	}
+
+
+	/**
+	 * Returns the previous x number of EE_Base_Class objects in sequence from this object as found in the database
+	 * matching the given query conditions.
+	 *
+	 * @param null  $field_to_order_by  What field is being used as the reference point.
+	 * @param int   $limit              How many objects to return.
+	 * @param array $query_params       Any additional conditions on the query.
+	 * @param null  $columns_to_select  If left null, then an array of EE_Base_Class objects is returned, otherwise
+	 *                                  you can indicate just the columns you want returned
+	 * @return array|EE_Base_Class[]
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function previous_x(
+		$field_to_order_by = null,
+		$limit = 1,
+		$query_params = array(),
+		$columns_to_select = null
+	) {
+		$model = $this->get_model();
+		$field = empty($field_to_order_by) && $model->has_primary_key_field()
+			? $model->get_primary_key_field()->get_name()
+			: $field_to_order_by;
+		$current_value = ! empty($field) ? $this->get($field) : null;
+		if (empty($field) || empty($current_value)) {
+			return array();
+		}
+		return $model->previous_x($current_value, $field, $limit, $query_params, $columns_to_select);
+	}
+
+
+	/**
+	 * Returns the next EE_Base_Class object in sequence from this object as found in the database
+	 * matching the given query conditions.
+	 *
+	 * @param null  $field_to_order_by  What field is being used as the reference point.
+	 * @param array $query_params       Any additional conditions on the query.
+	 * @param null  $columns_to_select  If left null, then an array of EE_Base_Class objects is returned, otherwise
+	 *                                  you can indicate just the columns you want returned
+	 * @return array|EE_Base_Class
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function next($field_to_order_by = null, $query_params = array(), $columns_to_select = null)
+	{
+		$model = $this->get_model();
+		$field = empty($field_to_order_by) && $model->has_primary_key_field()
+			? $model->get_primary_key_field()->get_name()
+			: $field_to_order_by;
+		$current_value = ! empty($field) ? $this->get($field) : null;
+		if (empty($field) || empty($current_value)) {
+			return array();
+		}
+		return $model->next($current_value, $field, $query_params, $columns_to_select);
+	}
+
+
+	/**
+	 * Returns the previous EE_Base_Class object in sequence from this object as found in the database
+	 * matching the given query conditions.
+	 *
+	 * @param null  $field_to_order_by  What field is being used as the reference point.
+	 * @param array $query_params       Any additional conditions on the query.
+	 * @param null  $columns_to_select  If left null, then an EE_Base_Class object is returned, otherwise
+	 *                                  you can indicate just the column you want returned
+	 * @return array|EE_Base_Class
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function previous($field_to_order_by = null, $query_params = array(), $columns_to_select = null)
+	{
+		$model = $this->get_model();
+		$field = empty($field_to_order_by) && $model->has_primary_key_field()
+			? $model->get_primary_key_field()->get_name()
+			: $field_to_order_by;
+		$current_value = ! empty($field) ? $this->get($field) : null;
+		if (empty($field) || empty($current_value)) {
+			return array();
+		}
+		return $model->previous($current_value, $field, $query_params, $columns_to_select);
+	}
+
+
+	/**
+	 * Overrides parent because parent expects old models.
+	 * This also doesn't do any validation, and won't work for serialized arrays
+	 *
+	 * @param string $field_name
+	 * @param mixed  $field_value_from_db
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function set_from_db($field_name, $field_value_from_db)
+	{
+		$field_obj = $this->get_model()->field_settings_for($field_name);
+		if ($field_obj instanceof EE_Model_Field_Base) {
+			// you would think the DB has no NULLs for non-null label fields right? wrong!
+			// eg, a CPT model object could have an entry in the posts table, but no
+			// entry in the meta table. Meaning that all its columns in the meta table
+			// are null! yikes! so when we find one like that, use defaults for its meta columns
+			if ($field_value_from_db === null) {
+				if ($field_obj->is_nullable()) {
+					// if the field allows nulls, then let it be null
+					$field_value = null;
+				} else {
+					$field_value = $field_obj->get_default_value();
+				}
+			} else {
+				$field_value = $field_obj->prepare_for_set_from_db($field_value_from_db);
+			}
+			$this->_fields[ $field_name ] = $field_value;
+			$this->_clear_cached_property($field_name);
+		}
+	}
+
+
+	/**
+	 * verifies that the specified field is of the correct type
+	 *
+	 * @param string $field_name
+	 * @param string $extra_cache_ref This allows the user to specify an extra cache ref for the given property
+	 *                                (in cases where the same property may be used for different outputs
+	 *                                - i.e. datetime, money etc.)
+	 * @return mixed
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get($field_name, $extra_cache_ref = null)
+	{
+		return $this->_get_cached_property($field_name, false, $extra_cache_ref);
+	}
+
+
+	/**
+	 * This method simply returns the RAW unprocessed value for the given property in this class
+	 *
+	 * @param  string $field_name A valid fieldname
+	 * @return mixed              Whatever the raw value stored on the property is.
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error if fieldSettings is misconfigured or the field doesn't exist.
+	 */
+	public function get_raw($field_name)
+	{
+		$field_settings = $this->get_model()->field_settings_for($field_name);
+		return $field_settings instanceof EE_Datetime_Field && $this->_fields[ $field_name ] instanceof DateTime
+			? $this->_fields[ $field_name ]->format('U')
+			: $this->_fields[ $field_name ];
+	}
+
+
+	/**
+	 * This is used to return the internal DateTime object used for a field that is a
+	 * EE_Datetime_Field.
+	 *
+	 * @param string $field_name               The field name retrieving the DateTime object.
+	 * @return mixed null | false | DateTime  If the requested field is NOT a EE_Datetime_Field then
+	 * @throws EE_Error an error is set and false returned.  If the field IS an
+	 *                                         EE_Datetime_Field and but the field value is null, then
+	 *                                         just null is returned (because that indicates that likely
+	 *                                         this field is nullable).
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function get_DateTime_object($field_name)
+	{
+		$field_settings = $this->get_model()->field_settings_for($field_name);
+		if (! $field_settings instanceof EE_Datetime_Field) {
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'The field %s is not an EE_Datetime_Field field.  There is no DateTime object stored on this field type.',
+						'event_espresso'
+					),
+					$field_name
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return false;
+		}
+		return isset($this->_fields[ $field_name ]) && $this->_fields[ $field_name ] instanceof DateTime
+			? clone $this->_fields[ $field_name ]
+			: null;
+	}
+
+
+	/**
+	 * To be used in template to immediately echo out the value, and format it for output.
+	 * Eg, should call stripslashes and whatnot before echoing
+	 *
+	 * @param string $field_name      the name of the field as it appears in the DB
+	 * @param string $extra_cache_ref This allows the user to specify an extra cache ref for the given property
+	 *                                (in cases where the same property may be used for different outputs
+	 *                                - i.e. datetime, money etc.)
+	 * @return void
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function e($field_name, $extra_cache_ref = null)
+	{
+		echo $this->get_pretty($field_name, $extra_cache_ref);
+	}
+
+
+	/**
+	 * Exactly like e(), echoes out the field, but sets its schema to 'form_input', so that it
+	 * can be easily used as the value of form input.
+	 *
+	 * @param string $field_name
+	 * @return void
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function f($field_name)
+	{
+		$this->e($field_name, 'form_input');
+	}
+
+
+	/**
+	 * Same as `f()` but just returns the value instead of echoing it
+	 *
+	 * @param string $field_name
+	 * @return string
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get_f($field_name)
+	{
+		return (string) $this->get_pretty($field_name, 'form_input');
+	}
+
+
+	/**
+	 * Gets a pretty view of the field's value. $extra_cache_ref can specify different formats for this.
+	 * The $extra_cache_ref will be passed to the model field's prepare_for_pretty_echoing, so consult the field's class
+	 * to see what options are available.
+	 *
+	 * @param string $field_name
+	 * @param string $extra_cache_ref This allows the user to specify an extra cache ref for the given property
+	 *                                (in cases where the same property may be used for different outputs
+	 *                                - i.e. datetime, money etc.)
+	 * @return mixed
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get_pretty($field_name, $extra_cache_ref = null)
+	{
+		return $this->_get_cached_property($field_name, true, $extra_cache_ref);
+	}
+
+
+	/**
+	 * This simply returns the datetime for the given field name
+	 * Note: this protected function is called by the wrapper get_date or get_time or get_datetime functions
+	 * (and the equivalent e_date, e_time, e_datetime).
+	 *
+	 * @access   protected
+	 * @param string   $field_name   Field on the instantiated EE_Base_Class child object
+	 * @param string   $dt_frmt      valid datetime format used for date
+	 *                               (if '' then we just use the default on the field,
+	 *                               if NULL we use the last-used format)
+	 * @param string   $tm_frmt      Same as above except this is for time format
+	 * @param string   $date_or_time if NULL then both are returned, otherwise "D" = only date and "T" = only time.
+	 * @param  boolean $echo         Whether the dtt is echoing using pretty echoing or just returned using vanilla get
+	 * @return string|bool|EE_Error string on success, FALSE on fail, or EE_Error Exception is thrown
+	 *                               if field is not a valid dtt field, or void if echoing
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected function _get_datetime($field_name, $dt_frmt = '', $tm_frmt = '', $date_or_time = '', $echo = false)
+	{
+		// clear cached property
+		$this->_clear_cached_property($field_name);
+		// reset format properties because they are used in get()
+		$this->_dt_frmt = $dt_frmt !== '' ? $dt_frmt : $this->_dt_frmt;
+		$this->_tm_frmt = $tm_frmt !== '' ? $tm_frmt : $this->_tm_frmt;
+		if ($echo) {
+			$this->e($field_name, $date_or_time);
+			return '';
+		}
+		return $this->get($field_name, $date_or_time);
+	}
+
+
+	/**
+	 * below are wrapper functions for the various datetime outputs that can be obtained for JUST returning the date
+	 * portion of a datetime value. (note the only difference between get_ and e_ is one returns the value and the
+	 * other echoes the pretty value for dtt)
+	 *
+	 * @param  string $field_name name of model object datetime field holding the value
+	 * @param  string $format     format for the date returned (if NULL we use default in dt_frmt property)
+	 * @return string            datetime value formatted
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get_date($field_name, $format = '')
+	{
+		return $this->_get_datetime($field_name, $format, null, 'D');
+	}
+
+
+	/**
+	 * @param        $field_name
+	 * @param string $format
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function e_date($field_name, $format = '')
+	{
+		$this->_get_datetime($field_name, $format, null, 'D', true);
+	}
+
+
+	/**
+	 * below are wrapper functions for the various datetime outputs that can be obtained for JUST returning the time
+	 * portion of a datetime value. (note the only difference between get_ and e_ is one returns the value and the
+	 * other echoes the pretty value for dtt)
+	 *
+	 * @param  string $field_name name of model object datetime field holding the value
+	 * @param  string $format     format for the time returned ( if NULL we use default in tm_frmt property)
+	 * @return string             datetime value formatted
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get_time($field_name, $format = '')
+	{
+		return $this->_get_datetime($field_name, null, $format, 'T');
+	}
+
+
+	/**
+	 * @param        $field_name
+	 * @param string $format
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function e_time($field_name, $format = '')
+	{
+		$this->_get_datetime($field_name, null, $format, 'T', true);
+	}
+
+
+	/**
+	 * below are wrapper functions for the various datetime outputs that can be obtained for returning the date AND
+	 * time portion of a datetime value. (note the only difference between get_ and e_ is one returns the value and the
+	 * other echoes the pretty value for dtt)
+	 *
+	 * @param  string $field_name name of model object datetime field holding the value
+	 * @param  string $dt_frmt    format for the date returned (if NULL we use default in dt_frmt property)
+	 * @param  string $tm_frmt    format for the time returned (if NULL we use default in tm_frmt property)
+	 * @return string             datetime value formatted
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get_datetime($field_name, $dt_frmt = '', $tm_frmt = '')
+	{
+		return $this->_get_datetime($field_name, $dt_frmt, $tm_frmt);
+	}
+
+
+	/**
+	 * @param string $field_name
+	 * @param string $dt_frmt
+	 * @param string $tm_frmt
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function e_datetime($field_name, $dt_frmt = '', $tm_frmt = '')
+	{
+		$this->_get_datetime($field_name, $dt_frmt, $tm_frmt, null, true);
+	}
+
+
+	/**
+	 * Get the i8ln value for a date using the WordPress @see date_i18n function.
+	 *
+	 * @param string $field_name The EE_Datetime_Field reference for the date being retrieved.
+	 * @param string $format     PHP valid date/time string format.  If none is provided then the internal set format
+	 *                           on the object will be used.
+	 * @return string Date and time string in set locale or false if no field exists for the given
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 *                           field name.
+	 */
+	public function get_i18n_datetime($field_name, $format = '')
+	{
+		$format = empty($format) ? $this->_dt_frmt . ' ' . $this->_tm_frmt : $format;
+		return date_i18n(
+			$format,
+			EEH_DTT_Helper::get_timestamp_with_offset(
+				$this->get_raw($field_name),
+				$this->_timezone
+			)
+		);
+	}
+
+
+	/**
+	 * This method validates whether the given field name is a valid field on the model object as well as it is of a
+	 * type EE_Datetime_Field.  On success there will be returned the field settings.  On fail an EE_Error exception is
+	 * thrown.
+	 *
+	 * @param  string $field_name The field name being checked
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @return EE_Datetime_Field
+	 */
+	protected function _get_dtt_field_settings($field_name)
+	{
+		$field = $this->get_model()->field_settings_for($field_name);
+		// check if field is dtt
+		if ($field instanceof EE_Datetime_Field) {
+			return $field;
+		}
+		throw new EE_Error(
+			sprintf(
+				esc_html__(
+					'The field name "%s" has been requested for the EE_Base_Class datetime functions and it is not a valid EE_Datetime_Field.  Please check the spelling of the field and make sure it has been setup as a EE_Datetime_Field in the %s model constructor',
+					'event_espresso'
+				),
+				$field_name,
+				self::_get_model_classname(get_class($this))
+			)
+		);
+	}
+
+
+
+
+	/**
+	 * NOTE ABOUT BELOW:
+	 * These convenience date and time setters are for setting date and time independently.  In other words you might
+	 * want to change the time on a datetime_field but leave the date the same (or vice versa). IF on the other hand
+	 * you want to set both date and time at the same time, you can just use the models default set($fieldname,$value)
+	 * method and make sure you send the entire datetime value for setting.
+	 */
+	/**
+	 * sets the time on a datetime property
+	 *
+	 * @access protected
+	 * @param string|Datetime $time      a valid time string for php datetime functions (or DateTime object)
+	 * @param string          $fieldname the name of the field the time is being set on (must match a EE_Datetime_Field)
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected function _set_time_for($time, $fieldname)
+	{
+		$this->_set_date_time('T', $time, $fieldname);
+	}
+
+
+	/**
+	 * sets the date on a datetime property
+	 *
+	 * @access protected
+	 * @param string|DateTime $date      a valid date string for php datetime functions ( or DateTime object)
+	 * @param string          $fieldname the name of the field the date is being set on (must match a EE_Datetime_Field)
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected function _set_date_for($date, $fieldname)
+	{
+		$this->_set_date_time('D', $date, $fieldname);
+	}
+
+
+	/**
+	 * This takes care of setting a date or time independently on a given model object property. This method also
+	 * verifies that the given fieldname matches a model object property and is for a EE_Datetime_Field field
+	 *
+	 * @access protected
+	 * @param string          $what           "T" for time, 'B' for both, 'D' for Date.
+	 * @param string|DateTime $datetime_value A valid Date or Time string (or DateTime object)
+	 * @param string          $fieldname      the name of the field the date OR time is being set on (must match a
+	 *                                        EE_Datetime_Field property)
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected function _set_date_time($what = 'T', $datetime_value, $fieldname)
+	{
+		$field = $this->_get_dtt_field_settings($fieldname);
+		$field->set_timezone($this->_timezone);
+		$field->set_date_format($this->_dt_frmt);
+		$field->set_time_format($this->_tm_frmt);
+		switch ($what) {
+			case 'T':
+				$this->_fields[ $fieldname ] = $field->prepare_for_set_with_new_time(
+					$datetime_value,
+					$this->_fields[ $fieldname ]
+				);
+				$this->_has_changes = true;
+				break;
+			case 'D':
+				$this->_fields[ $fieldname ] = $field->prepare_for_set_with_new_date(
+					$datetime_value,
+					$this->_fields[ $fieldname ]
+				);
+				$this->_has_changes = true;
+				break;
+			case 'B':
+				$this->_fields[ $fieldname ] = $field->prepare_for_set($datetime_value);
+				$this->_has_changes = true;
+				break;
+		}
+		$this->_clear_cached_property($fieldname);
+	}
+
+
+	/**
+	 * This will return a timestamp for the website timezone but ONLY when the current website timezone is different
+	 * than the timezone set for the website. NOTE, this currently only works well with methods that return values.  If
+	 * you use it with methods that echo values the $_timestamp property may not get reset to its original value and
+	 * that could lead to some unexpected results!
+	 *
+	 * @access public
+	 * @param string $field_name               This is the name of the field on the object that contains the date/time
+	 *                                         value being returned.
+	 * @param string $callback                 must match a valid method in this class (defaults to get_datetime)
+	 * @param mixed (array|string) $args       This is the arguments that will be passed to the callback.
+	 * @param string $prepend                  You can include something to prepend on the timestamp
+	 * @param string $append                   You can include something to append on the timestamp
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @return string timestamp
+	 */
+	public function display_in_my_timezone(
+		$field_name,
+		$callback = 'get_datetime',
+		$args = null,
+		$prepend = '',
+		$append = ''
+	) {
+		$timezone = EEH_DTT_Helper::get_timezone();
+		if ($timezone === $this->_timezone) {
+			return '';
+		}
+		$original_timezone = $this->_timezone;
+		$this->set_timezone($timezone);
+		$fn = (array) $field_name;
+		$args = array_merge($fn, (array) $args);
+		if (! method_exists($this, $callback)) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'The method named "%s" given as the callback param in "display_in_my_timezone" does not exist.  Please check your spelling',
+						'event_espresso'
+					),
+					$callback
+				)
+			);
+		}
+		$args = (array) $args;
+		$return = $prepend . call_user_func_array(array($this, $callback), $args) . $append;
+		$this->set_timezone($original_timezone);
+		return $return;
+	}
+
+
+	/**
+	 * Deletes this model object.
+	 * This calls the `EE_Base_Class::_delete` method.  Child classes wishing to change default behaviour should
+	 * override
+	 * `EE_Base_Class::_delete` NOT this class.
+	 *
+	 * @return boolean | int
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function delete()
+	{
+		/**
+		 * Called just before the `EE_Base_Class::_delete` method call.
+		 * Note:
+		 * `EE_Base_Class::_delete` might be overridden by child classes so any client code hooking into these actions
+		 * should be aware that `_delete` may not always result in a permanent delete.
+		 * For example, `EE_Soft_Delete_Base_Class::_delete`
+		 * soft deletes (trash) the object and does not permanently delete it.
+		 *
+		 * @param EE_Base_Class $model_object about to be 'deleted'
+		 */
+		do_action('AHEE__EE_Base_Class__delete__before', $this);
+		$result = $this->_delete();
+		/**
+		 * Called just after the `EE_Base_Class::_delete` method call.
+		 * Note:
+		 * `EE_Base_Class::_delete` might be overridden by child classes so any client code hooking into these actions
+		 * should be aware that `_delete` may not always result in a permanent delete.
+		 * For example `EE_Soft_Base_Class::_delete`
+		 * soft deletes (trash) the object and does not permanently delete it.
+		 *
+		 * @param EE_Base_Class $model_object that was just 'deleted'
+		 * @param boolean       $result
+		 */
+		do_action('AHEE__EE_Base_Class__delete__end', $this, $result);
+		return $result;
+	}
+
+
+	/**
+	 * Calls the specific delete method for the instantiated class.
+	 * This method is called by the public `EE_Base_Class::delete` method.  Any child classes desiring to override
+	 * default functionality for "delete" (which is to call `permanently_delete`) should override this method NOT
+	 * `EE_Base_Class::delete`
+	 *
+	 * @return bool|int
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected function _delete()
+	{
+		return $this->delete_permanently();
+	}
+
+
+	/**
+	 * Deletes this model object permanently from db
+	 * (but keep in mind related models may block the delete and return an error)
+	 *
+	 * @return bool | int
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function delete_permanently()
+	{
+		/**
+		 * Called just before HARD deleting a model object
+		 *
+		 * @param EE_Base_Class $model_object about to be 'deleted'
+		 */
+		do_action('AHEE__EE_Base_Class__delete_permanently__before', $this);
+		$model = $this->get_model();
+		$result = $model->delete_permanently_by_ID($this->ID());
+		$this->refresh_cache_of_related_objects();
+		/**
+		 * Called just after HARD deleting a model object
+		 *
+		 * @param EE_Base_Class $model_object that was just 'deleted'
+		 * @param boolean       $result
+		 */
+		do_action('AHEE__EE_Base_Class__delete_permanently__end', $this, $result);
+		return $result;
+	}
+
+
+	/**
+	 * When this model object is deleted, it may still be cached on related model objects. This clears the cache of
+	 * related model objects
+	 *
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function refresh_cache_of_related_objects()
+	{
+		$model = $this->get_model();
+		foreach ($model->relation_settings() as $relation_name => $relation_obj) {
+			if (! empty($this->_model_relations[ $relation_name ])) {
+				$related_objects = $this->_model_relations[ $relation_name ];
+				if ($relation_obj instanceof EE_Belongs_To_Relation) {
+					// this relation only stores a single model object, not an array
+					// but let's make it consistent
+					$related_objects = array($related_objects);
+				}
+				foreach ($related_objects as $related_object) {
+					// only refresh their cache if they're in memory
+					if ($related_object instanceof EE_Base_Class) {
+						$related_object->clear_cache(
+							$model->get_this_model_name(),
+							$this
+						);
+					}
+				}
+			}
+		}
+	}
+
+
+	/**
+	 *        Saves this object to the database. An array may be supplied to set some values on this
+	 * object just before saving.
+	 *
+	 * @access public
+	 * @param array $set_cols_n_values keys are field names, values are their new values,
+	 *                                 if provided during the save() method (often client code will change the fields'
+	 *                                 values before calling save)
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @return int , 1 on a successful update, the ID of the new entry on insert; 0 on failure or if the model object
+	 *                                 isn't allowed to persist (as determined by EE_Base_Class::allow_persist())
+	 * @throws ReflectionException
+	 * @throws ReflectionException
+	 * @throws ReflectionException
+	 */
+	public function save($set_cols_n_values = array())
+	{
+		$model = $this->get_model();
+		/**
+		 * Filters the fields we're about to save on the model object
+		 *
+		 * @param array         $set_cols_n_values
+		 * @param EE_Base_Class $model_object
+		 */
+		$set_cols_n_values = (array) apply_filters(
+			'FHEE__EE_Base_Class__save__set_cols_n_values',
+			$set_cols_n_values,
+			$this
+		);
+		// set attributes as provided in $set_cols_n_values
+		foreach ($set_cols_n_values as $column => $value) {
+			$this->set($column, $value);
+		}
+		// no changes ? then don't do anything
+		if (! $this->_has_changes && $this->ID() && $model->get_primary_key_field()->is_auto_increment()) {
+			return 0;
+		}
+		/**
+		 * Saving a model object.
+		 * Before we perform a save, this action is fired.
+		 *
+		 * @param EE_Base_Class $model_object the model object about to be saved.
+		 */
+		do_action('AHEE__EE_Base_Class__save__begin', $this);
+		if (! $this->allow_persist()) {
+			return 0;
+		}
+		// now get current attribute values
+		$save_cols_n_values = $this->_fields;
+		// if the object already has an ID, update it. Otherwise, insert it
+		// also: change the assumption about values passed to the model NOT being prepare dby the model object.
+		// They have been
+		$old_assumption_concerning_value_preparation = $model
+			->get_assumption_concerning_values_already_prepared_by_model_object();
+		$model->assume_values_already_prepared_by_model_object(true);
+		// does this model have an autoincrement PK?
+		if ($model->has_primary_key_field()) {
+			if ($model->get_primary_key_field()->is_auto_increment()) {
+				// ok check if it's set, if so: update; if not, insert
+				if (! empty($save_cols_n_values[ $model->primary_key_name() ])) {
+					$results = $model->update_by_ID($save_cols_n_values, $this->ID());
+				} else {
+					unset($save_cols_n_values[ $model->primary_key_name() ]);
+					$results = $model->insert($save_cols_n_values);
+					if ($results) {
+						// if successful, set the primary key
+						// but don't use the normal SET method, because it will check if
+						// an item with the same ID exists in the mapper & db, then
+						// will find it in the db (because we just added it) and THAT object
+						// will get added to the mapper before we can add this one!
+						// but if we just avoid using the SET method, all that headache can be avoided
+						$pk_field_name = $model->primary_key_name();
+						$this->_fields[ $pk_field_name ] = $results;
+						$this->_clear_cached_property($pk_field_name);
+						$model->add_to_entity_map($this);
+						$this->_update_cached_related_model_objs_fks();
+					}
+				}
+			} else {// PK is NOT auto-increment
+				// so check if one like it already exists in the db
+				if ($model->exists_by_ID($this->ID())) {
+					if (WP_DEBUG && ! $this->in_entity_map()) {
+						throw new EE_Error(
+							sprintf(
+								esc_html__(
+									'Using a model object %1$s that is NOT in the entity map, can lead to unexpected errors. You should either: %4$s 1. Put it in the entity mapper by calling %2$s %4$s 2. Discard this model object and use what is in the entity mapper %4$s 3. Fetch from the database using %3$s',
+									'event_espresso'
+								),
+								get_class($this),
+								get_class($model) . '::instance()->add_to_entity_map()',
+								get_class($model) . '::instance()->get_one_by_ID()',
+								'<br />'
+							)
+						);
+					}
+					$results = $model->update_by_ID($save_cols_n_values, $this->ID());
+				} else {
+					$results = $model->insert($save_cols_n_values);
+					$this->_update_cached_related_model_objs_fks();
+				}
+			}
+		} else {// there is NO primary key
+			$already_in_db = false;
+			foreach ($model->unique_indexes() as $index) {
+				$uniqueness_where_params = array_intersect_key($save_cols_n_values, $index->fields());
+				if ($model->exists(array($uniqueness_where_params))) {
+					$already_in_db = true;
+				}
+			}
+			if ($already_in_db) {
+				$combined_pk_fields_n_values = array_intersect_key(
+					$save_cols_n_values,
+					$model->get_combined_primary_key_fields()
+				);
+				$results = $model->update(
+					$save_cols_n_values,
+					$combined_pk_fields_n_values
+				);
+			} else {
+				$results = $model->insert($save_cols_n_values);
+			}
+		}
+		// restore the old assumption about values being prepared by the model object
+		$model->assume_values_already_prepared_by_model_object(
+			$old_assumption_concerning_value_preparation
+		);
+		/**
+		 * After saving the model object this action is called
+		 *
+		 * @param EE_Base_Class $model_object which was just saved
+		 * @param boolean|int   $results      if it were updated, TRUE or FALSE; if it were newly inserted
+		 *                                    the new ID (or 0 if an error occurred and it wasn't updated)
+		 */
+		do_action('AHEE__EE_Base_Class__save__end', $this, $results);
+		$this->_has_changes = false;
+		return $results;
+	}
+
+
+	/**
+	 * Updates the foreign key on related models objects pointing to this to have this model object's ID
+	 * as their foreign key.  If the cached related model objects already exist in the db, saves them (so that the DB
+	 * is consistent) Especially useful in case we JUST added this model object ot the database and we want to let its
+	 * cached relations with foreign keys to it know about that change. Eg: we've created a transaction but haven't
+	 * saved it to the db. We also create a registration and don't save it to the DB, but we DO cache it on the
+	 * transaction. Now, when we save the transaction, the registration's TXN_ID will be automatically updated, whether
+	 * or not they exist in the DB (if they do, their DB records will be automatically updated)
+	 *
+	 * @return void
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected function _update_cached_related_model_objs_fks()
+	{
+		$model = $this->get_model();
+		foreach ($model->relation_settings() as $relation_name => $relation_obj) {
+			if ($relation_obj instanceof EE_Has_Many_Relation) {
+				foreach ($this->get_all_from_cache($relation_name) as $related_model_obj_in_cache) {
+					$fk_to_this = $related_model_obj_in_cache->get_model()->get_foreign_key_to(
+						$model->get_this_model_name()
+					);
+					$related_model_obj_in_cache->set($fk_to_this->get_name(), $this->ID());
+					if ($related_model_obj_in_cache->ID()) {
+						$related_model_obj_in_cache->save();
+					}
+				}
+			}
+		}
+	}
+
+
+	/**
+	 * Saves this model object and its NEW cached relations to the database.
+	 * (Meaning, for now, IT DOES NOT WORK if the cached items already exist in the DB.
+	 * In order for that to work, we would need to mark model objects as dirty/clean...
+	 * because otherwise, there's a potential for infinite looping of saving
+	 * Saves the cached related model objects, and ensures the relation between them
+	 * and this object and properly setup
+	 *
+	 * @return int ID of new model object on save; 0 on failure+
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function save_new_cached_related_model_objs()
+	{
+		// make sure this has been saved
+		if (! $this->ID()) {
+			$id = $this->save();
+		} else {
+			$id = $this->ID();
+		}
+		// now save all the NEW cached model objects  (ie they don't exist in the DB)
+		foreach ($this->get_model()->relation_settings() as $relationName => $relationObj) {
+			if ($this->_model_relations[ $relationName ]) {
+				// is this a relation where we should expect just ONE related object (ie, EE_Belongs_To_relation)
+				// or MANY related objects (ie, EE_HABTM_Relation or EE_Has_Many_Relation)?
+				/* @var $related_model_obj EE_Base_Class */
+				if ($relationObj instanceof EE_Belongs_To_Relation) {
+					// add a relation to that relation type (which saves the appropriate thing in the process)
+					// but ONLY if it DOES NOT exist in the DB
+					$related_model_obj = $this->_model_relations[ $relationName ];
+					// if( ! $related_model_obj->ID()){
+					$this->_add_relation_to($related_model_obj, $relationName);
+					$related_model_obj->save_new_cached_related_model_objs();
+					// }
+				} else {
+					foreach ($this->_model_relations[ $relationName ] as $related_model_obj) {
+						// add a relation to that relation type (which saves the appropriate thing in the process)
+						// but ONLY if it DOES NOT exist in the DB
+						// if( ! $related_model_obj->ID()){
+						$this->_add_relation_to($related_model_obj, $relationName);
+						$related_model_obj->save_new_cached_related_model_objs();
+						// }
+					}
+				}
+			}
+		}
+		return $id;
+	}
+
+
+	/**
+	 * for getting a model while instantiated.
+	 *
+	 * @return EEM_Base | EEM_CPT_Base
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get_model()
+	{
+		if (! $this->_model) {
+			$modelName = self::_get_model_classname(get_class($this));
+			$this->_model = self::_get_model_instance_with_name($modelName, $this->_timezone);
+		} else {
+			$this->_model->set_timezone($this->_timezone);
+		}
+		return $this->_model;
+	}
+
+
+	/**
+	 * @param $props_n_values
+	 * @param $classname
+	 * @return mixed bool|EE_Base_Class|EEM_CPT_Base
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected static function _get_object_from_entity_mapper($props_n_values, $classname)
+	{
+		// TODO: will not work for Term_Relationships because they have no PK!
+		$primary_id_ref = self::_get_primary_key_name($classname);
+		if (array_key_exists($primary_id_ref, $props_n_values)
+			&& ! empty($props_n_values[ $primary_id_ref ])
+		) {
+			$id = $props_n_values[ $primary_id_ref ];
+			return self::_get_model($classname)->get_from_entity_map($id);
+		}
+		return false;
+	}
+
+
+	/**
+	 * This is called by child static "new_instance" method and we'll check to see if there is an existing db entry for
+	 * the primary key (if present in incoming values). If there is a key in the incoming array that matches the
+	 * primary key for the model AND it is not null, then we check the db. If there's a an object we return it.  If not
+	 * we return false.
+	 *
+	 * @param  array  $props_n_values   incoming array of properties and their values
+	 * @param  string $classname        the classname of the child class
+	 * @param null    $timezone
+	 * @param array   $date_formats     incoming date_formats in an array where the first value is the
+	 *                                  date_format and the second value is the time format
+	 * @return mixed (EE_Base_Class|bool)
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @throws ReflectionException
+	 * @throws ReflectionException
+	 */
+	protected static function _check_for_object($props_n_values, $classname, $timezone = null, $date_formats = array())
+	{
+		$existing = null;
+		$model = self::_get_model($classname, $timezone);
+		if ($model->has_primary_key_field()) {
+			$primary_id_ref = self::_get_primary_key_name($classname);
+			if (array_key_exists($primary_id_ref, $props_n_values)
+				&& ! empty($props_n_values[ $primary_id_ref ])
+			) {
+				$existing = $model->get_one_by_ID(
+					$props_n_values[ $primary_id_ref ]
+				);
+			}
+		} elseif ($model->has_all_combined_primary_key_fields($props_n_values)) {
+			// no primary key on this model, but there's still a matching item in the DB
+			$existing = self::_get_model($classname, $timezone)->get_one_by_ID(
+				self::_get_model($classname, $timezone)
+					->get_index_primary_key_string($props_n_values)
+			);
+		}
+		if ($existing) {
+			// set date formats if present before setting values
+			if (! empty($date_formats) && is_array($date_formats)) {
+				$existing->set_date_format($date_formats[0]);
+				$existing->set_time_format($date_formats[1]);
+			} else {
+				// set default formats for date and time
+				$existing->set_date_format(get_option('date_format'));
+				$existing->set_time_format(get_option('time_format'));
+			}
+			foreach ($props_n_values as $property => $field_value) {
+				$existing->set($property, $field_value);
+			}
+			return $existing;
+		}
+		return false;
+	}
+
+
+	/**
+	 * Gets the EEM_*_Model for this class
+	 *
+	 * @access public now, as this is more convenient
+	 * @param      $classname
+	 * @param null $timezone
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @return EEM_Base
+	 */
+	protected static function _get_model($classname, $timezone = null)
+	{
+		// find model for this class
+		if (! $classname) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'What were you thinking calling _get_model(%s)?? You need to specify the class name',
+						'event_espresso'
+					),
+					$classname
+				)
+			);
+		}
+		$modelName = self::_get_model_classname($classname);
+		return self::_get_model_instance_with_name($modelName, $timezone);
+	}
+
+
+	/**
+	 * Gets the model instance (eg instance of EEM_Attendee) given its classname (eg EE_Attendee)
+	 *
+	 * @param string $model_classname
+	 * @param null   $timezone
+	 * @return EEM_Base
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	protected static function _get_model_instance_with_name($model_classname, $timezone = null)
+	{
+		$model_classname = str_replace('EEM_', '', $model_classname);
+		$model = EE_Registry::instance()->load_model($model_classname);
+		$model->set_timezone($timezone);
+		return $model;
+	}
+
+
+	/**
+	 * If a model name is provided (eg Registration), gets the model classname for that model.
+	 * Also works if a model class's classname is provided (eg EE_Registration).
+	 *
+	 * @param null $model_name
+	 * @return string like EEM_Attendee
+	 */
+	private static function _get_model_classname($model_name = null)
+	{
+		if (strpos($model_name, 'EE_') === 0) {
+			$model_classname = str_replace('EE_', 'EEM_', $model_name);
+		} else {
+			$model_classname = 'EEM_' . $model_name;
+		}
+		return $model_classname;
+	}
+
+
+	/**
+	 * returns the name of the primary key attribute
+	 *
+	 * @param null $classname
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @return string
+	 */
+	protected static function _get_primary_key_name($classname = null)
+	{
+		if (! $classname) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__('What were you thinking calling _get_primary_key_name(%s)', 'event_espresso'),
+					$classname
+				)
+			);
+		}
+		return self::_get_model($classname)->get_primary_key_field()->get_name();
+	}
+
+
+	/**
+	 * Gets the value of the primary key.
+	 * If the object hasn't yet been saved, it should be whatever the model field's default was
+	 * (eg, if this were the EE_Event class, look at the primary key field on EEM_Event and see what its default value
+	 * is. Usually defaults for integer primary keys are 0; string primary keys are usually NULL).
+	 *
+	 * @return mixed, if the primary key is of type INT it'll be an int. Otherwise it could be a string
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function ID()
+	{
+		$model = $this->get_model();
+		// now that we know the name of the variable, use a variable variable to get its value and return its
+		if ($model->has_primary_key_field()) {
+			return $this->_fields[ $model->primary_key_name() ];
+		}
+		return $model->get_index_primary_key_string($this->_fields);
+	}
+
+
+	/**
+	 * Adds a relationship to the specified EE_Base_Class object, given the relationship's name. Eg, if the current
+	 * model is related to a group of events, the $relationName should be 'Event', and should be a key in the EE
+	 * Model's $_model_relations array. If this model object doesn't exist in the DB, just caches the related thing
+	 *
+	 * @param mixed  $otherObjectModelObjectOrID       EE_Base_Class or the ID of the other object
+	 * @param string $relationName                     eg 'Events','Question',etc.
+	 *                                                 an attendee to a group, you also want to specify which role they
+	 *                                                 will have in that group. So you would use this parameter to
+	 *                                                 specify array('role-column-name'=>'role-id')
+	 * @param array  $extra_join_model_fields_n_values You can optionally include an array of key=>value pairs that
+	 *                                                 allow you to further constrict the relation to being added.
+	 *                                                 However, keep in mind that the columns (keys) given must match a
+	 *                                                 column on the JOIN table and currently only the HABTM models
+	 *                                                 accept these additional conditions.  Also remember that if an
+	 *                                                 exact match isn't found for these extra cols/val pairs, then a
+	 *                                                 NEW row is created in the join table.
+	 * @param null   $cache_id
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @return EE_Base_Class the object the relation was added to
+	 */
+	public function _add_relation_to(
+		$otherObjectModelObjectOrID,
+		$relationName,
+		$extra_join_model_fields_n_values = array(),
+		$cache_id = null
+	) {
+		$model = $this->get_model();
+		// if this thing exists in the DB, save the relation to the DB
+		if ($this->ID()) {
+			$otherObject = $model->add_relationship_to(
+				$this,
+				$otherObjectModelObjectOrID,
+				$relationName,
+				$extra_join_model_fields_n_values
+			);
+			// clear cache so future get_many_related and get_first_related() return new results.
+			$this->clear_cache($relationName, $otherObject, true);
+			if ($otherObject instanceof EE_Base_Class) {
+				$otherObject->clear_cache($model->get_this_model_name(), $this);
+			}
+		} else {
+			// this thing doesn't exist in the DB,  so just cache it
+			if (! $otherObjectModelObjectOrID instanceof EE_Base_Class) {
+				throw new EE_Error(
+					sprintf(
+						esc_html__(
+							'Before a model object is saved to the database, calls to _add_relation_to must be passed an actual object, not just an ID. You provided %s as the model object to a %s',
+							'event_espresso'
+						),
+						$otherObjectModelObjectOrID,
+						get_class($this)
+					)
+				);
+			}
+			$otherObject = $otherObjectModelObjectOrID;
+			$this->cache($relationName, $otherObjectModelObjectOrID, $cache_id);
+		}
+		if ($otherObject instanceof EE_Base_Class) {
+			// fix the reciprocal relation too
+			if ($otherObject->ID()) {
+				// its saved so assumed relations exist in the DB, so we can just
+				// clear the cache so future queries use the updated info in the DB
+				$otherObject->clear_cache(
+					$model->get_this_model_name(),
+					null,
+					true
+				);
+			} else {
+				// it's not saved, so it caches relations like this
+				$otherObject->cache($model->get_this_model_name(), $this);
+			}
+		}
+		return $otherObject;
+	}
+
+
+	/**
+	 * Removes a relationship to the specified EE_Base_Class object, given the relationships' name. Eg, if the current
+	 * model is related to a group of events, the $relationName should be 'Events', and should be a key in the EE
+	 * Model's $_model_relations array. If this model object doesn't exist in the DB, just removes the related thing
+	 * from the cache
+	 *
+	 * @param mixed  $otherObjectModelObjectOrID
+	 *                EE_Base_Class or the ID of the other object, OR an array key into the cache if this isn't saved
+	 *                to the DB yet
+	 * @param string $relationName
+	 * @param array  $where_query
+	 *                You can optionally include an array of key=>value pairs that allow you to further constrict the
+	 *                relation to being added. However, keep in mind that the columns (keys) given must match a column
+	 *                on the JOIN table and currently only the HABTM models accept these additional conditions. Also
+	 *                remember that if an exact match isn't found for these extra cols/val pairs, then no row is
+	 *                deleted.
+	 * @return EE_Base_Class the relation was removed from
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function _remove_relation_to($otherObjectModelObjectOrID, $relationName, $where_query = array())
+	{
+		if ($this->ID()) {
+			// if this exists in the DB, save the relation change to the DB too
+			$otherObject = $this->get_model()->remove_relationship_to(
+				$this,
+				$otherObjectModelObjectOrID,
+				$relationName,
+				$where_query
+			);
+			$this->clear_cache(
+				$relationName,
+				$otherObject
+			);
+		} else {
+			// this doesn't exist in the DB, just remove it from the cache
+			$otherObject = $this->clear_cache(
+				$relationName,
+				$otherObjectModelObjectOrID
+			);
+		}
+		if ($otherObject instanceof EE_Base_Class) {
+			$otherObject->clear_cache(
+				$this->get_model()->get_this_model_name(),
+				$this
+			);
+		}
+		return $otherObject;
+	}
+
+
+	/**
+	 * Removes ALL the related things for the $relationName.
+	 *
+	 * @param string $relationName
+	 * @param array  $where_query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions
+	 * @return EE_Base_Class
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function _remove_relations($relationName, $where_query_params = array())
+	{
+		if ($this->ID()) {
+			// if this exists in the DB, save the relation change to the DB too
+			$otherObjects = $this->get_model()->remove_relations(
+				$this,
+				$relationName,
+				$where_query_params
+			);
+			$this->clear_cache(
+				$relationName,
+				null,
+				true
+			);
+		} else {
+			// this doesn't exist in the DB, just remove it from the cache
+			$otherObjects = $this->clear_cache(
+				$relationName,
+				null,
+				true
+			);
+		}
+		if (is_array($otherObjects)) {
+			foreach ($otherObjects as $otherObject) {
+				$otherObject->clear_cache(
+					$this->get_model()->get_this_model_name(),
+					$this
+				);
+			}
+		}
+		return $otherObjects;
+	}
+
+
+	/**
+	 * Gets all the related model objects of the specified type. Eg, if the current class if
+	 * EE_Event, you could call $this->get_many_related('Registration') to get an array of all the
+	 * EE_Registration objects which related to this event. Note: by default, we remove the "default query params"
+	 * because we want to get even deleted items etc.
+	 *
+	 * @param string $relationName key in the model's _model_relations array
+	 * @param array  $query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions
+	 * @return EE_Base_Class[]     Results not necessarily indexed by IDs, because some results might not have primary
+	 *                             keys or might not be saved yet. Consider using EEM_Base::get_IDs() on these
+	 *                             results if you want IDs
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get_many_related($relationName, $query_params = array())
+	{
+		if ($this->ID()) {
+			// this exists in the DB, so get the related things from either the cache or the DB
+			// if there are query parameters, forget about caching the related model objects.
+			if ($query_params) {
+				$related_model_objects = $this->get_model()->get_all_related(
+					$this,
+					$relationName,
+					$query_params
+				);
+			} else {
+				// did we already cache the result of this query?
+				$cached_results = $this->get_all_from_cache($relationName);
+				if (! $cached_results) {
+					$related_model_objects = $this->get_model()->get_all_related(
+						$this,
+						$relationName,
+						$query_params
+					);
+					// if no query parameters were passed, then we got all the related model objects
+					// for that relation. We can cache them then.
+					foreach ($related_model_objects as $related_model_object) {
+						$this->cache($relationName, $related_model_object);
+					}
+				} else {
+					$related_model_objects = $cached_results;
+				}
+			}
+		} else {
+			// this doesn't exist in the DB, so just get the related things from the cache
+			$related_model_objects = $this->get_all_from_cache($relationName);
+		}
+		return $related_model_objects;
+	}
+
+
+	/**
+	 * Instead of getting the related model objects, simply counts them. Ignores default_where_conditions by default,
+	 * unless otherwise specified in the $query_params
+	 *
+	 * @param string $relation_name  model_name like 'Event', or 'Registration'
+	 * @param array  $query_params   @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
+	 * @param string $field_to_count name of field to count by. By default, uses primary key
+	 * @param bool   $distinct       if we want to only count the distinct values for the column then you can trigger
+	 *                               that by the setting $distinct to TRUE;
+	 * @return int
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function count_related($relation_name, $query_params = array(), $field_to_count = null, $distinct = false)
+	{
+		return $this->get_model()->count_related(
+			$this,
+			$relation_name,
+			$query_params,
+			$field_to_count,
+			$distinct
+		);
+	}
+
+
+	/**
+	 * Instead of getting the related model objects, simply sums up the values of the specified field.
+	 * Note: ignores default_where_conditions by default, unless otherwise specified in the $query_params
+	 *
+	 * @param string $relation_name model_name like 'Event', or 'Registration'
+	 * @param array  $query_params  @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
+	 * @param string $field_to_sum  name of field to count by.
+	 *                              By default, uses primary key
+	 *                              (which doesn't make much sense, so you should probably change it)
+	 * @return int
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function sum_related($relation_name, $query_params = array(), $field_to_sum = null)
+	{
+		return $this->get_model()->sum_related(
+			$this,
+			$relation_name,
+			$query_params,
+			$field_to_sum
+		);
+	}
+
+
+	/**
+	 * Gets the first (ie, one) related model object of the specified type.
+	 *
+	 * @param string $relationName key in the model's _model_relations array
+	 * @param array  $query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
+	 * @return EE_Base_Class (not an array, a single object)
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get_first_related($relationName, $query_params = array())
+	{
+		$model = $this->get_model();
+		if ($this->ID()) {// this exists in the DB, get from the cache OR the DB
+			// if they've provided some query parameters, don't bother trying to cache the result
+			// also make sure we're not caching the result of get_first_related
+			// on a relation which should have an array of objects (because the cache might have an array of objects)
+			if ($query_params
+				|| ! $model->related_settings_for($relationName)
+					 instanceof
+					 EE_Belongs_To_Relation
+			) {
+				$related_model_object = $model->get_first_related(
+					$this,
+					$relationName,
+					$query_params
+				);
+			} else {
+				// first, check if we've already cached the result of this query
+				$cached_result = $this->get_one_from_cache($relationName);
+				if (! $cached_result) {
+					$related_model_object = $model->get_first_related(
+						$this,
+						$relationName,
+						$query_params
+					);
+					$this->cache($relationName, $related_model_object);
+				} else {
+					$related_model_object = $cached_result;
+				}
+			}
+		} else {
+			$related_model_object = null;
+			// this doesn't exist in the Db,
+			// but maybe the relation is of type belongs to, and so the related thing might
+			if ($model->related_settings_for($relationName) instanceof EE_Belongs_To_Relation) {
+				$related_model_object = $model->get_first_related(
+					$this,
+					$relationName,
+					$query_params
+				);
+			}
+			// this doesn't exist in the DB and apparently the thing it belongs to doesn't either,
+			// just get what's cached on this object
+			if (! $related_model_object) {
+				$related_model_object = $this->get_one_from_cache($relationName);
+			}
+		}
+		return $related_model_object;
+	}
+
+
+	/**
+	 * Does a delete on all related objects of type $relationName and removes
+	 * the current model object's relation to them. If they can't be deleted (because
+	 * of blocking related model objects) does nothing. If the related model objects are
+	 * soft-deletable, they will be soft-deleted regardless of related blocking model objects.
+	 * If this model object doesn't exist yet in the DB, just removes its related things
+	 *
+	 * @param string $relationName
+	 * @param array  $query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
+	 * @return int how many deleted
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function delete_related($relationName, $query_params = array())
+	{
+		if ($this->ID()) {
+			$count = $this->get_model()->delete_related(
+				$this,
+				$relationName,
+				$query_params
+			);
+		} else {
+			$count = count($this->get_all_from_cache($relationName));
+			$this->clear_cache($relationName, null, true);
+		}
+		return $count;
+	}
+
+
+	/**
+	 * Does a hard delete (ie, removes the DB row) on all related objects of type $relationName and removes
+	 * the current model object's relation to them. If they can't be deleted (because
+	 * of blocking related model objects) just does a soft delete on it instead, if possible.
+	 * If the related thing isn't a soft-deletable model object, this function is identical
+	 * to delete_related(). If this model object doesn't exist in the DB, just remove its related things
+	 *
+	 * @param string $relationName
+	 * @param array  $query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
+	 * @return int how many deleted (including those soft deleted)
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function delete_related_permanently($relationName, $query_params = array())
+	{
+		if ($this->ID()) {
+			$count = $this->get_model()->delete_related_permanently(
+				$this,
+				$relationName,
+				$query_params
+			);
+		} else {
+			$count = count($this->get_all_from_cache($relationName));
+		}
+		$this->clear_cache($relationName, null, true);
+		return $count;
+	}
+
+
+	/**
+	 * is_set
+	 * Just a simple utility function children can use for checking if property exists
+	 *
+	 * @access  public
+	 * @param  string $field_name property to check
+	 * @return bool                              TRUE if existing,FALSE if not.
+	 */
+	public function is_set($field_name)
+	{
+		return isset($this->_fields[ $field_name ]);
+	}
+
+
+	/**
+	 * Just a simple utility function children can use for checking if property (or properties) exists and throwing an
+	 * EE_Error exception if they don't
+	 *
+	 * @param  mixed (string|array) $properties properties to check
+	 * @throws EE_Error
+	 * @return bool                              TRUE if existing, throw EE_Error if not.
+	 */
+	protected function _property_exists($properties)
+	{
+		foreach ((array) $properties as $property_name) {
+			// first make sure this property exists
+			if (! $this->_fields[ $property_name ]) {
+				throw new EE_Error(
+					sprintf(
+						esc_html__(
+							'Trying to retrieve a non-existent property (%s).  Double check the spelling please',
+							'event_espresso'
+						),
+						$property_name
+					)
+				);
+			}
+		}
+		return true;
+	}
+
+
+	/**
+	 * This simply returns an array of model fields for this object
+	 *
+	 * @return array
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function model_field_array()
+	{
+		$fields = $this->get_model()->field_settings(false);
+		$properties = array();
+		// remove prepended underscore
+		foreach ($fields as $field_name => $settings) {
+			$properties[ $field_name ] = $this->get($field_name);
+		}
+		return $properties;
+	}
+
+
+	/**
+	 * Very handy general function to allow for plugins to extend any child of EE_Base_Class.
+	 * If a method is called on a child of EE_Base_Class that doesn't exist, this function is called
+	 * (http://www.garfieldtech.com/blog/php-magic-call) and passed the method's name and arguments.
+	 * Instead of requiring a plugin to extend the EE_Base_Class
+	 * (which works fine is there's only 1 plugin, but when will that happen?)
+	 * they can add a hook onto 'filters_hook_espresso__{className}__{methodName}'
+	 * (eg, filters_hook_espresso__EE_Answer__my_great_function)
+	 * and accepts 2 arguments: the object on which the function was called,
+	 * and an array of the original arguments passed to the function.
+	 * Whatever their callback function returns will be returned by this function.
+	 * Example: in functions.php (or in a plugin):
+	 *      add_filter('FHEE__EE_Answer__my_callback','my_callback',10,3);
+	 *      function my_callback($previousReturnValue,EE_Base_Class $object,$argsArray){
+	 *          $returnString= "you called my_callback! and passed args:".implode(",",$argsArray);
+	 *          return $previousReturnValue.$returnString;
+	 *      }
+	 * require('EE_Answer.class.php');
+	 * $answer= EE_Answer::new_instance(array('REG_ID' => 2,'QST_ID' => 3,'ANS_value' => The answer is 42'));
+	 * echo $answer->my_callback('monkeys',100);
+	 * //will output "you called my_callback! and passed args:monkeys,100"
+	 *
+	 * @param string $methodName name of method which was called on a child of EE_Base_Class, but which
+	 * @param array  $args       array of original arguments passed to the function
+	 * @throws EE_Error
+	 * @return mixed whatever the plugin which calls add_filter decides
+	 */
+	public function __call($methodName, $args)
+	{
+		$className = get_class($this);
+		$tagName = "FHEE__{$className}__{$methodName}";
+		if (! has_filter($tagName)) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						"Method %s on class %s does not exist! You can create one with the following code in functions.php or in a plugin: add_filter('%s','my_callback',10,3);function my_callback(\$previousReturnValue,EE_Base_Class \$object, \$argsArray){/*function body*/return \$whatever;}",
+						'event_espresso'
+					),
+					$methodName,
+					$className,
+					$tagName
+				)
+			);
+		}
+		return apply_filters($tagName, null, $this, $args);
+	}
+
+
+	/**
+	 * Similar to insert_post_meta, adds a record in the Extra_Meta model's table with the given key and value.
+	 * A $previous_value can be specified in case there are many meta rows with the same key
+	 *
+	 * @param string $meta_key
+	 * @param mixed  $meta_value
+	 * @param mixed  $previous_value
+	 * @return bool|int # of records updated (or BOOLEAN if we actually ended up inserting the extra meta row)
+	 *                  NOTE: if the values haven't changed, returns 0
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function update_extra_meta($meta_key, $meta_value, $previous_value = null)
+	{
+		$query_params = array(
+			array(
+				'EXM_key'  => $meta_key,
+				'OBJ_ID'   => $this->ID(),
+				'EXM_type' => $this->get_model()->get_this_model_name(),
+			),
+		);
+		if ($previous_value !== null) {
+			$query_params[0]['EXM_value'] = $meta_value;
+		}
+		$existing_rows_like_that = EEM_Extra_Meta::instance()->get_all($query_params);
+		if (! $existing_rows_like_that) {
+			return $this->add_extra_meta($meta_key, $meta_value);
+		}
+		foreach ($existing_rows_like_that as $existing_row) {
+			$existing_row->save(array('EXM_value' => $meta_value));
+		}
+		return count($existing_rows_like_that);
+	}
+
+
+	/**
+	 * Adds a new extra meta record. If $unique is set to TRUE, we'll first double-check
+	 * no other extra meta for this model object have the same key. Returns TRUE if the
+	 * extra meta row was entered, false if not
+	 *
+	 * @param string  $meta_key
+	 * @param mixed   $meta_value
+	 * @param boolean $unique
+	 * @return boolean
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @throws ReflectionException
+	 */
+	public function add_extra_meta($meta_key, $meta_value, $unique = false)
+	{
+		if ($unique) {
+			$existing_extra_meta = EEM_Extra_Meta::instance()->get_one(
+				array(
+					array(
+						'EXM_key'  => $meta_key,
+						'OBJ_ID'   => $this->ID(),
+						'EXM_type' => $this->get_model()->get_this_model_name(),
+					),
+				)
+			);
+			if ($existing_extra_meta) {
+				return false;
+			}
+		}
+		$new_extra_meta = EE_Extra_Meta::new_instance(
+			array(
+				'EXM_key'   => $meta_key,
+				'EXM_value' => $meta_value,
+				'OBJ_ID'    => $this->ID(),
+				'EXM_type'  => $this->get_model()->get_this_model_name(),
+			)
+		);
+		$new_extra_meta->save();
+		return true;
+	}
+
+
+	/**
+	 * Deletes all the extra meta rows for this record as specified by key. If $meta_value
+	 * is specified, only deletes extra meta records with that value.
+	 *
+	 * @param string $meta_key
+	 * @param mixed  $meta_value
+	 * @return int number of extra meta rows deleted
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function delete_extra_meta($meta_key, $meta_value = null)
+	{
+		$query_params = array(
+			array(
+				'EXM_key'  => $meta_key,
+				'OBJ_ID'   => $this->ID(),
+				'EXM_type' => $this->get_model()->get_this_model_name(),
+			),
+		);
+		if ($meta_value !== null) {
+			$query_params[0]['EXM_value'] = $meta_value;
+		}
+		return EEM_Extra_Meta::instance()->delete($query_params);
+	}
+
+
+	/**
+	 * Gets the extra meta with the given meta key. If you specify "single" we just return 1, otherwise
+	 * an array of everything found. Requires that this model actually have a relation of type EE_Has_Many_Any_Relation.
+	 * You can specify $default is case you haven't found the extra meta
+	 *
+	 * @param string  $meta_key
+	 * @param boolean $single
+	 * @param mixed   $default if we don't find anything, what should we return?
+	 * @return mixed single value if $single; array if ! $single
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function get_extra_meta($meta_key, $single = false, $default = null)
+	{
+		if ($single) {
+			$result = $this->get_first_related(
+				'Extra_Meta',
+				array(array('EXM_key' => $meta_key))
+			);
+			if ($result instanceof EE_Extra_Meta) {
+				return $result->value();
+			}
+		} else {
+			$results = $this->get_many_related(
+				'Extra_Meta',
+				array(array('EXM_key' => $meta_key))
+			);
+			if ($results) {
+				$values = array();
+				foreach ($results as $result) {
+					if ($result instanceof EE_Extra_Meta) {
+						$values[ $result->ID() ] = $result->value();
+					}
+				}
+				return $values;
+			}
+		}
+		// if nothing discovered yet return default.
+		return apply_filters(
+			'FHEE__EE_Base_Class__get_extra_meta__default_value',
+			$default,
+			$meta_key,
+			$single,
+			$this
+		);
+	}
+
+
+	/**
+	 * Returns a simple array of all the extra meta associated with this model object.
+	 * If $one_of_each_key is true (Default), it will be an array of simple key-value pairs, keys being the
+	 * extra meta's key, and teh value being its value. However, if there are duplicate extra meta rows with
+	 * the same key, only one will be used. (eg array('foo'=>'bar','monkey'=>123))
+	 * If $one_of_each_key is false, it will return an array with the top-level keys being
+	 * the extra meta keys, but their values are also arrays, which have the extra-meta's ID as their sub-key, and
+	 * finally the extra meta's value as each sub-value. (eg
+	 * array('foo'=>array(1=>'bar',2=>'bill'),'monkey'=>array(3=>123)))
+	 *
+	 * @param boolean $one_of_each_key
+	 * @return array
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function all_extra_meta_array($one_of_each_key = true)
+	{
+		$return_array = array();
+		if ($one_of_each_key) {
+			$extra_meta_objs = $this->get_many_related(
+				'Extra_Meta',
+				array('group_by' => 'EXM_key')
+			);
+			foreach ($extra_meta_objs as $extra_meta_obj) {
+				if ($extra_meta_obj instanceof EE_Extra_Meta) {
+					$return_array[ $extra_meta_obj->key() ] = $extra_meta_obj->value();
+				}
+			}
+		} else {
+			$extra_meta_objs = $this->get_many_related('Extra_Meta');
+			foreach ($extra_meta_objs as $extra_meta_obj) {
+				if ($extra_meta_obj instanceof EE_Extra_Meta) {
+					if (! isset($return_array[ $extra_meta_obj->key() ])) {
+						$return_array[ $extra_meta_obj->key() ] = array();
+					}
+					$return_array[ $extra_meta_obj->key() ][ $extra_meta_obj->ID() ] = $extra_meta_obj->value();
+				}
+			}
+		}
+		return $return_array;
+	}
+
+
+	/**
+	 * Gets a pretty nice displayable nice for this model object. Often overridden
+	 *
+	 * @return string
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function name()
+	{
+		// find a field that's not a text field
+		$field_we_can_use = $this->get_model()->get_a_field_of_type('EE_Text_Field_Base');
+		if ($field_we_can_use) {
+			return $this->get($field_we_can_use->get_name());
+		}
+		$first_few_properties = $this->model_field_array();
+		$first_few_properties = array_slice($first_few_properties, 0, 3);
+		$name_parts = array();
+		foreach ($first_few_properties as $name => $value) {
+			$name_parts[] = "$name:$value";
+		}
+		return implode(',', $name_parts);
+	}
+
+
+	/**
+	 * in_entity_map
+	 * Checks if this model object has been proven to already be in the entity map
+	 *
+	 * @return boolean
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function in_entity_map()
+	{
+		// well, if we looked, did we find it in the entity map?
+		return $this->ID() && $this->get_model()->get_from_entity_map($this->ID()) === $this;
+	}
+
+
+	/**
+	 * refresh_from_db
+	 * Makes sure the fields and values on this model object are in-sync with what's in the database.
+	 *
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error if this model object isn't in the entity mapper (because then you should
+	 * just use what's in the entity mapper and refresh it) and WP_DEBUG is TRUE
+	 */
+	public function refresh_from_db()
+	{
+		if ($this->ID() && $this->in_entity_map()) {
+			$this->get_model()->refresh_entity_map_from_db($this->ID());
+		} else {
+			// if it doesn't have ID, you shouldn't be asking to refresh it from teh database (because its not in the database)
+			// if it has an ID but it's not in the map, and you're asking me to refresh it
+			// that's kinda dangerous. You should just use what's in the entity map, or add this to the entity map if there's
+			// absolutely nothing in it for this ID
+			if (WP_DEBUG) {
+				throw new EE_Error(
+					sprintf(
+						esc_html__(
+							'Trying to refresh a model object with ID "%1$s" that\'s not in the entity map? First off: you should put it in the entity map by calling %2$s. Second off, if you want what\'s in the database right now, you should just call %3$s yourself and discard this model object.',
+							'event_espresso'
+						),
+						$this->ID(),
+						get_class($this->get_model()) . '::instance()->add_to_entity_map()',
+						get_class($this->get_model()) . '::instance()->refresh_entity_map()'
+					)
+				);
+			}
+		}
+	}
+
+
+	/**
+	 * Change $fields' values to $new_value_sql (which is a string of raw SQL)
+	 *
+	 * @since 4.9.80.p
+	 * @param EE_Model_Field_Base[] $fields
+	 * @param string $new_value_sql
+	 *      example: 'column_name=123',
+	 *      or 'column_name=column_name+1',
+	 *      or 'column_name= CASE
+	 *          WHEN (`column_name` + `other_column` + 5) <= `yet_another_column`
+	 *          THEN `column_name` + 5
+	 *          ELSE `column_name`
+	 *      END'
+	 *      Also updates $field on this model object with the latest value from the database.
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	protected function updateFieldsInDB($fields, $new_value_sql)
+	{
+		// First make sure this model object actually exists in the DB. It would be silly to try to update it in the DB
+		// if it wasn't even there to start off.
+		if (! $this->ID()) {
+			$this->save();
+		}
+		global $wpdb;
+		if (empty($fields)) {
+			throw new InvalidArgumentException(
+				esc_html__(
+					'EE_Base_Class::updateFieldsInDB was passed an empty array of fields.',
+					'event_espresso'
+				)
+			);
+		}
+		$first_field = reset($fields);
+		$table_alias = $first_field->get_table_alias();
+		foreach ($fields as $field) {
+			if ($table_alias !== $field->get_table_alias()) {
+				throw new InvalidArgumentException(
+					sprintf(
+						esc_html__(
+							// @codingStandardsIgnoreStart
+							'EE_Base_Class::updateFieldsInDB was passed fields for different tables ("%1$s" and "%2$s"), which is not supported. Instead, please call the method multiple times.',
+							// @codingStandardsIgnoreEnd
+							'event_espresso'
+						),
+						$table_alias,
+						$field->get_table_alias()
+					)
+				);
+			}
+		}
+		// Ok the fields are now known to all be for the same table. Proceed with creating the SQL to update it.
+		$table_obj = $this->get_model()->get_table_obj_by_alias($table_alias);
+		$table_pk_value = $this->ID();
+		$table_name = $table_obj->get_table_name();
+		if ($table_obj instanceof EE_Secondary_Table) {
+			$table_pk_field_name = $table_obj->get_fk_on_table();
+		} else {
+			$table_pk_field_name = $table_obj->get_pk_column();
+		}
+
+		$query =
+			"UPDATE `{$table_name}`
             SET "
-            . $new_value_sql
-            . $wpdb->prepare(
-                "
+			. $new_value_sql
+			. $wpdb->prepare(
+				"
             WHERE `{$table_pk_field_name}` = %d;",
-                $table_pk_value
-            );
-        $result = $wpdb->query($query);
-        foreach ($fields as $field) {
-            // If it was successful, we'd like to know the new value.
-            // If it failed, we'd also like to know the new value.
-            $new_value = $this->get_model()->get_var(
-                $this->get_model()->alter_query_params_to_restrict_by_ID(
-                    $this->get_model()->get_index_primary_key_string(
-                        $this->model_field_array()
-                    ),
-                    array(
-                        'default_where_conditions' => 'minimum',
-                    )
-                ),
-                $field->get_name()
-            );
-            $this->set_from_db(
-                $field->get_name(),
-                $new_value
-            );
-        }
-        return (bool) $result;
-    }
-
-
-    /**
-     * Nudges $field_name's value by $quantity, without any conditionals (in comparison to bumpConditionally()).
-     * Does not allow negative values, however.
-     *
-     * @since 4.9.80.p
-     * @param array $fields_n_quantities keys are the field names, and values are the amount by which to bump them
-     *                                   (positive or negative). One important gotcha: all these values must be
-     *                                   on the same table (eg don't pass in one field for the posts table and
-     *                                   another for the event meta table.)
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function adjustNumericFieldsInDb(array $fields_n_quantities)
-    {
-        global $wpdb;
-        if (empty($fields_n_quantities)) {
-            // No fields to update? Well sure, we updated them to that value just fine.
-            return true;
-        }
-        $fields = [];
-        $set_sql_statements = [];
-        foreach ($fields_n_quantities as $field_name => $quantity) {
-            $field = $this->get_model()->field_settings_for($field_name, true);
-            $fields[] = $field;
-            $column_name = $field->get_table_column();
-
-            $abs_qty = absint($quantity);
-            if ($quantity > 0) {
-                // don't let the value be negative as often these fields are unsigned
-                $set_sql_statements[] = $wpdb->prepare(
-                    "`{$column_name}` = `{$column_name}` + %d",
-                    $abs_qty
-                );
-            } else {
-                $set_sql_statements[] = $wpdb->prepare(
-                    "`{$column_name}` = CASE
+				$table_pk_value
+			);
+		$result = $wpdb->query($query);
+		foreach ($fields as $field) {
+			// If it was successful, we'd like to know the new value.
+			// If it failed, we'd also like to know the new value.
+			$new_value = $this->get_model()->get_var(
+				$this->get_model()->alter_query_params_to_restrict_by_ID(
+					$this->get_model()->get_index_primary_key_string(
+						$this->model_field_array()
+					),
+					array(
+						'default_where_conditions' => 'minimum',
+					)
+				),
+				$field->get_name()
+			);
+			$this->set_from_db(
+				$field->get_name(),
+				$new_value
+			);
+		}
+		return (bool) $result;
+	}
+
+
+	/**
+	 * Nudges $field_name's value by $quantity, without any conditionals (in comparison to bumpConditionally()).
+	 * Does not allow negative values, however.
+	 *
+	 * @since 4.9.80.p
+	 * @param array $fields_n_quantities keys are the field names, and values are the amount by which to bump them
+	 *                                   (positive or negative). One important gotcha: all these values must be
+	 *                                   on the same table (eg don't pass in one field for the posts table and
+	 *                                   another for the event meta table.)
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function adjustNumericFieldsInDb(array $fields_n_quantities)
+	{
+		global $wpdb;
+		if (empty($fields_n_quantities)) {
+			// No fields to update? Well sure, we updated them to that value just fine.
+			return true;
+		}
+		$fields = [];
+		$set_sql_statements = [];
+		foreach ($fields_n_quantities as $field_name => $quantity) {
+			$field = $this->get_model()->field_settings_for($field_name, true);
+			$fields[] = $field;
+			$column_name = $field->get_table_column();
+
+			$abs_qty = absint($quantity);
+			if ($quantity > 0) {
+				// don't let the value be negative as often these fields are unsigned
+				$set_sql_statements[] = $wpdb->prepare(
+					"`{$column_name}` = `{$column_name}` + %d",
+					$abs_qty
+				);
+			} else {
+				$set_sql_statements[] = $wpdb->prepare(
+					"`{$column_name}` = CASE
                        WHEN (`{$column_name}` >= %d)
                        THEN `{$column_name}` - %d
                        ELSE 0
                     END",
-                    $abs_qty,
-                    $abs_qty
-                );
-            }
-        }
-        return $this->updateFieldsInDB(
-            $fields,
-            implode(', ', $set_sql_statements)
-        );
-    }
-
-
-    /**
-     * Increases the value of the field $field_name_to_bump by $quantity, but only if the values of
-     * $field_name_to_bump plus $field_name_affecting_total and $quantity won't exceed $limit_field_name's value.
-     * For example, this is useful when bumping the value of TKT_reserved, TKT_sold, DTT_reserved or DTT_sold.
-     * Returns true if the value was successfully bumped, and updates the value on this model object.
-     * Otherwise returns false.
-     *
-     * @since 4.9.80.p
-     * @param string $field_name_to_bump
-     * @param string $field_name_affecting_total
-     * @param string $limit_field_name
-     * @param int    $quantity
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function incrementFieldConditionallyInDb($field_name_to_bump, $field_name_affecting_total, $limit_field_name, $quantity)
-    {
-        global $wpdb;
-        $field = $this->get_model()->field_settings_for($field_name_to_bump, true);
-        $column_name = $field->get_table_column();
-
-        $field_affecting_total = $this->get_model()->field_settings_for($field_name_affecting_total, true);
-        $column_affecting_total = $field_affecting_total->get_table_column();
-
-        $limiting_field = $this->get_model()->field_settings_for($limit_field_name, true);
-        $limiting_column = $limiting_field->get_table_column();
-        return $this->updateFieldsInDB(
-            [$field],
-            $wpdb->prepare(
-                "`{$column_name}` =
+					$abs_qty,
+					$abs_qty
+				);
+			}
+		}
+		return $this->updateFieldsInDB(
+			$fields,
+			implode(', ', $set_sql_statements)
+		);
+	}
+
+
+	/**
+	 * Increases the value of the field $field_name_to_bump by $quantity, but only if the values of
+	 * $field_name_to_bump plus $field_name_affecting_total and $quantity won't exceed $limit_field_name's value.
+	 * For example, this is useful when bumping the value of TKT_reserved, TKT_sold, DTT_reserved or DTT_sold.
+	 * Returns true if the value was successfully bumped, and updates the value on this model object.
+	 * Otherwise returns false.
+	 *
+	 * @since 4.9.80.p
+	 * @param string $field_name_to_bump
+	 * @param string $field_name_affecting_total
+	 * @param string $limit_field_name
+	 * @param int    $quantity
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function incrementFieldConditionallyInDb($field_name_to_bump, $field_name_affecting_total, $limit_field_name, $quantity)
+	{
+		global $wpdb;
+		$field = $this->get_model()->field_settings_for($field_name_to_bump, true);
+		$column_name = $field->get_table_column();
+
+		$field_affecting_total = $this->get_model()->field_settings_for($field_name_affecting_total, true);
+		$column_affecting_total = $field_affecting_total->get_table_column();
+
+		$limiting_field = $this->get_model()->field_settings_for($limit_field_name, true);
+		$limiting_column = $limiting_field->get_table_column();
+		return $this->updateFieldsInDB(
+			[$field],
+			$wpdb->prepare(
+				"`{$column_name}` =
             CASE
                WHEN ((`{$column_name}` + `{$column_affecting_total}` + %d) <= `{$limiting_column}`) OR `{$limiting_column}` = %d
                THEN `{$column_name}` + %d
                ELSE `{$column_name}`
             END",
-                $quantity,
-                EE_INF_IN_DB,
-                $quantity
-            )
-        );
-    }
-
-
-    /**
-     * Because some other plugins, like Advanced Cron Manager, expect all objects to have this method
-     * (probably a bad assumption they have made, oh well)
-     *
-     * @return string
-     */
-    public function __toString()
-    {
-        try {
-            return sprintf('%s (%s)', $this->name(), $this->ID());
-        } catch (Exception $e) {
-            EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
-            return '';
-        }
-    }
-
-
-    /**
-     * Clear related model objects if they're already in the DB, because otherwise when we
-     * UN-serialize this model object we'll need to be careful to add them to the entity map.
-     * This means if we have made changes to those related model objects, and want to unserialize
-     * the this model object on a subsequent request, changes to those related model objects will be lost.
-     * Instead, those related model objects should be directly serialized and stored.
-     * Eg, the following won't work:
-     * $reg = EEM_Registration::instance()->get_one_by_ID( 123 );
-     * $att = $reg->attendee();
-     * $att->set( 'ATT_fname', 'Dirk' );
-     * update_option( 'my_option', serialize( $reg ) );
-     * //END REQUEST
-     * //START NEXT REQUEST
-     * $reg = get_option( 'my_option' );
-     * $reg->attendee()->save();
-     * And would need to be replace with:
-     * $reg = EEM_Registration::instance()->get_one_by_ID( 123 );
-     * $att = $reg->attendee();
-     * $att->set( 'ATT_fname', 'Dirk' );
-     * update_option( 'my_option', serialize( $reg ) );
-     * //END REQUEST
-     * //START NEXT REQUEST
-     * $att = get_option( 'my_option' );
-     * $att->save();
-     *
-     * @return array
-     * @throws ReflectionException
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     */
-    public function __sleep()
-    {
-        $model = $this->get_model();
-        foreach ($model->relation_settings() as $relation_name => $relation_obj) {
-            if ($relation_obj instanceof EE_Belongs_To_Relation) {
-                $classname = 'EE_' . $model->get_this_model_name();
-                if ($this->get_one_from_cache($relation_name) instanceof $classname
-                    && $this->get_one_from_cache($relation_name)->ID()
-                ) {
-                    $this->clear_cache(
-                        $relation_name,
-                        $this->get_one_from_cache($relation_name)->ID()
-                    );
-                }
-            }
-        }
-        $this->_props_n_values_provided_in_constructor = array();
-        $properties_to_serialize = get_object_vars($this);
-        // don't serialize the model. It's big and that risks recursion
-        unset($properties_to_serialize['_model']);
-        return array_keys($properties_to_serialize);
-    }
-
-
-    /**
-     * restore _props_n_values_provided_in_constructor
-     * PLZ NOTE: this will reset the array to whatever fields values were present prior to serialization,
-     * and therefore should NOT be used to determine if state change has occurred since initial construction.
-     * At best, you would only be able to detect if state change has occurred during THIS request.
-     */
-    public function __wakeup()
-    {
-        $this->_props_n_values_provided_in_constructor = $this->_fields;
-    }
-
-
-    /**
-     * Usage of this magic method is to ensure any internally cached references to object instances that must remain
-     * distinct with the clone host instance are also cloned.
-     */
-    public function __clone()
-    {
-        // handle DateTimes (this is handled in here because there's no one specific child class that uses datetimes).
-        foreach ($this->_fields as $field => $value) {
-            if ($value instanceof DateTime) {
-                $this->_fields[ $field ] = clone $value;
-            }
-        }
-    }
+				$quantity,
+				EE_INF_IN_DB,
+				$quantity
+			)
+		);
+	}
+
+
+	/**
+	 * Because some other plugins, like Advanced Cron Manager, expect all objects to have this method
+	 * (probably a bad assumption they have made, oh well)
+	 *
+	 * @return string
+	 */
+	public function __toString()
+	{
+		try {
+			return sprintf('%s (%s)', $this->name(), $this->ID());
+		} catch (Exception $e) {
+			EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
+			return '';
+		}
+	}
+
+
+	/**
+	 * Clear related model objects if they're already in the DB, because otherwise when we
+	 * UN-serialize this model object we'll need to be careful to add them to the entity map.
+	 * This means if we have made changes to those related model objects, and want to unserialize
+	 * the this model object on a subsequent request, changes to those related model objects will be lost.
+	 * Instead, those related model objects should be directly serialized and stored.
+	 * Eg, the following won't work:
+	 * $reg = EEM_Registration::instance()->get_one_by_ID( 123 );
+	 * $att = $reg->attendee();
+	 * $att->set( 'ATT_fname', 'Dirk' );
+	 * update_option( 'my_option', serialize( $reg ) );
+	 * //END REQUEST
+	 * //START NEXT REQUEST
+	 * $reg = get_option( 'my_option' );
+	 * $reg->attendee()->save();
+	 * And would need to be replace with:
+	 * $reg = EEM_Registration::instance()->get_one_by_ID( 123 );
+	 * $att = $reg->attendee();
+	 * $att->set( 'ATT_fname', 'Dirk' );
+	 * update_option( 'my_option', serialize( $reg ) );
+	 * //END REQUEST
+	 * //START NEXT REQUEST
+	 * $att = get_option( 'my_option' );
+	 * $att->save();
+	 *
+	 * @return array
+	 * @throws ReflectionException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 */
+	public function __sleep()
+	{
+		$model = $this->get_model();
+		foreach ($model->relation_settings() as $relation_name => $relation_obj) {
+			if ($relation_obj instanceof EE_Belongs_To_Relation) {
+				$classname = 'EE_' . $model->get_this_model_name();
+				if ($this->get_one_from_cache($relation_name) instanceof $classname
+					&& $this->get_one_from_cache($relation_name)->ID()
+				) {
+					$this->clear_cache(
+						$relation_name,
+						$this->get_one_from_cache($relation_name)->ID()
+					);
+				}
+			}
+		}
+		$this->_props_n_values_provided_in_constructor = array();
+		$properties_to_serialize = get_object_vars($this);
+		// don't serialize the model. It's big and that risks recursion
+		unset($properties_to_serialize['_model']);
+		return array_keys($properties_to_serialize);
+	}
+
+
+	/**
+	 * restore _props_n_values_provided_in_constructor
+	 * PLZ NOTE: this will reset the array to whatever fields values were present prior to serialization,
+	 * and therefore should NOT be used to determine if state change has occurred since initial construction.
+	 * At best, you would only be able to detect if state change has occurred during THIS request.
+	 */
+	public function __wakeup()
+	{
+		$this->_props_n_values_provided_in_constructor = $this->_fields;
+	}
+
+
+	/**
+	 * Usage of this magic method is to ensure any internally cached references to object instances that must remain
+	 * distinct with the clone host instance are also cloned.
+	 */
+	public function __clone()
+	{
+		// handle DateTimes (this is handled in here because there's no one specific child class that uses datetimes).
+		foreach ($this->_fields as $field => $value) {
+			if ($value instanceof DateTime) {
+				$this->_fields[ $field ] = clone $value;
+			}
+		}
+	}
 }

Spacing +121 added lines, -121 removed lines

@@ -146,7 +146,7 @@ 
         $fieldValues = is_array($fieldValues) ? $fieldValues : array($fieldValues);
         // verify client code has not passed any invalid field names
         foreach ($fieldValues as $field_name => $field_value) {
-            if (! isset($model_fields[ $field_name ])) {
+            if ( ! isset($model_fields[$field_name])) {
                 throw new EE_Error(
                     sprintf(
                         esc_html__(
@@ -161,7 +161,7 @@ 
             }
         }
         $this->_timezone = EEH_DTT_Helper::get_valid_timezone_string($timezone);
-        if (! empty($date_formats) && is_array($date_formats)) {
+        if ( ! empty($date_formats) && is_array($date_formats)) {
             list($this->_dt_frmt, $this->_tm_frmt) = $date_formats;
         } else {
             // set default formats for date and time
@@ -174,7 +174,7 @@ 
             foreach ($model_fields as $fieldName => $field) {
                 $this->set_from_db(
                     $fieldName,
-                    isset($fieldValues[ $fieldName ]) ? $fieldValues[ $fieldName ] : null
+                    isset($fieldValues[$fieldName]) ? $fieldValues[$fieldName] : null
                 );
             }
         } else {
@@ -183,7 +183,7 @@ 
             foreach ($model_fields as $fieldName => $field) {
                 $this->set(
                     $fieldName,
-                    isset($fieldValues[ $fieldName ]) ? $fieldValues[ $fieldName ] : null,
+                    isset($fieldValues[$fieldName]) ? $fieldValues[$fieldName] : null,
                     true
                 );
             }
@@ -191,15 +191,15 @@ 
         // remember what values were passed to this constructor
         $this->_props_n_values_provided_in_constructor = $fieldValues;
         // remember in entity mapper
-        if (! $bydb && $model->has_primary_key_field() && $this->ID()) {
+        if ( ! $bydb && $model->has_primary_key_field() && $this->ID()) {
             $model->add_to_entity_map($this);
         }
         // setup all the relations
         foreach ($model->relation_settings() as $relation_name => $relation_obj) {
             if ($relation_obj instanceof EE_Belongs_To_Relation) {
-                $this->_model_relations[ $relation_name ] = null;
+                $this->_model_relations[$relation_name] = null;
             } else {
-                $this->_model_relations[ $relation_name ] = array();
+                $this->_model_relations[$relation_name] = array();
             }
         }
         /**
@@ -250,10 +250,10 @@ 
      */
     public function get_original($field_name)
     {
-        if (isset($this->_props_n_values_provided_in_constructor[ $field_name ])
+        if (isset($this->_props_n_values_provided_in_constructor[$field_name])
             && $field_settings = $this->get_model()->field_settings_for($field_name)
         ) {
-            return $field_settings->prepare_for_get($this->_props_n_values_provided_in_constructor[ $field_name ]);
+            return $field_settings->prepare_for_get($this->_props_n_values_provided_in_constructor[$field_name]);
         }
         return null;
     }
@@ -288,8 +288,8 @@ 
     {
         // if not using default and nothing has changed, and object has already been setup (has ID),
         // then don't do anything
-        if (! $use_default
-            && $this->_fields[ $field_name ] === $field_value
+        if ( ! $use_default
+            && $this->_fields[$field_name] === $field_value
             && $this->ID()
         ) {
             return;
@@ -307,7 +307,7 @@ 
             $holder_of_value = $field_obj->prepare_for_set($field_value);
             // should the value be null?
             if (($field_value === null || $holder_of_value === null || $holder_of_value === '') && $use_default) {
-                $this->_fields[ $field_name ] = $field_obj->get_default_value();
+                $this->_fields[$field_name] = $field_obj->get_default_value();
                 /**
                  * To save having to refactor all the models, if a default value is used for a
                  * EE_Datetime_Field, and that value is not null nor is it a DateTime
@@ -317,15 +317,15 @@ 
                  * @since 4.6.10+
                  */
                 if ($field_obj instanceof EE_Datetime_Field
-                    && $this->_fields[ $field_name ] !== null
-                    && ! $this->_fields[ $field_name ] instanceof DateTime
+                    && $this->_fields[$field_name] !== null
+                    && ! $this->_fields[$field_name] instanceof DateTime
                 ) {
-                    empty($this->_fields[ $field_name ])
+                    empty($this->_fields[$field_name])
                         ? $this->set($field_name, time())
-                        : $this->set($field_name, $this->_fields[ $field_name ]);
+                        : $this->set($field_name, $this->_fields[$field_name]);
                 }
             } else {
-                $this->_fields[ $field_name ] = $holder_of_value;
+                $this->_fields[$field_name] = $holder_of_value;
             }
             // if we're not in the constructor...
             // now check if what we set was a primary key
@@ -341,7 +341,7 @@ 
                 $fields_on_model = self::_get_model(get_class($this))->field_settings();
                 $obj_in_db = self::_get_model(get_class($this))->get_one_by_ID($field_value);
                 foreach ($fields_on_model as $field_obj) {
-                    if (! array_key_exists($field_obj->get_name(), $this->_props_n_values_provided_in_constructor)
+                    if ( ! array_key_exists($field_obj->get_name(), $this->_props_n_values_provided_in_constructor)
                         && $field_obj->get_name() !== $field_name
                     ) {
                         $this->set($field_obj->get_name(), $obj_in_db->get($field_obj->get_name()));
@@ -386,8 +386,8 @@ 
      */
     public function getCustomSelect($alias)
     {
-        return isset($this->custom_selection_results[ $alias ])
-            ? $this->custom_selection_results[ $alias ]
+        return isset($this->custom_selection_results[$alias])
+            ? $this->custom_selection_results[$alias]
             : null;
     }
 
@@ -474,8 +474,8 @@ 
         foreach ($model_fields as $field_name => $field_obj) {
             if ($field_obj instanceof EE_Datetime_Field) {
                 $field_obj->set_timezone($this->_timezone);
-                if (isset($this->_fields[ $field_name ]) && $this->_fields[ $field_name ] instanceof DateTime) {
-                    EEH_DTT_Helper::setTimezone($this->_fields[ $field_name ], new DateTimeZone($this->_timezone));
+                if (isset($this->_fields[$field_name]) && $this->_fields[$field_name] instanceof DateTime) {
+                    EEH_DTT_Helper::setTimezone($this->_fields[$field_name], new DateTimeZone($this->_timezone));
                 }
             }
         }
@@ -533,7 +533,7 @@ 
      */
     public function get_format($full = true)
     {
-        return $full ? $this->_dt_frmt . ' ' . $this->_tm_frmt : array($this->_dt_frmt, $this->_tm_frmt);
+        return $full ? $this->_dt_frmt.' '.$this->_tm_frmt : array($this->_dt_frmt, $this->_tm_frmt);
     }
 
 
@@ -559,11 +559,11 @@ 
     public function cache($relationName = '', $object_to_cache = null, $cache_id = null)
     {
         // its entirely possible that there IS no related object yet in which case there is nothing to cache.
-        if (! $object_to_cache instanceof EE_Base_Class) {
+        if ( ! $object_to_cache instanceof EE_Base_Class) {
             return false;
         }
         // also get "how" the object is related, or throw an error
-        if (! $relationship_to_model = $this->get_model()->related_settings_for($relationName)) {
+        if ( ! $relationship_to_model = $this->get_model()->related_settings_for($relationName)) {
             throw new EE_Error(
                 sprintf(
                     esc_html__('There is no relationship to %s on a %s. Cannot cache it', 'event_espresso'),
@@ -577,38 +577,38 @@ 
             // if it's a "belongs to" relationship, then there's only one related model object
             // eg, if this is a registration, there's only 1 attendee for it
             // so for these model objects just set it to be cached
-            $this->_model_relations[ $relationName ] = $object_to_cache;
+            $this->_model_relations[$relationName] = $object_to_cache;
             $return = true;
         } else {
             // otherwise, this is the "many" side of a one to many relationship,
             // so we'll add the object to the array of related objects for that type.
             // eg: if this is an event, there are many registrations for that event,
             // so we cache the registrations in an array
-            if (! is_array($this->_model_relations[ $relationName ])) {
+            if ( ! is_array($this->_model_relations[$relationName])) {
                 // if for some reason, the cached item is a model object,
                 // then stick that in the array, otherwise start with an empty array
-                $this->_model_relations[ $relationName ] = $this->_model_relations[ $relationName ]
+                $this->_model_relations[$relationName] = $this->_model_relations[$relationName]
                                                            instanceof
                                                            EE_Base_Class
-                    ? array($this->_model_relations[ $relationName ]) : array();
+                    ? array($this->_model_relations[$relationName]) : array();
             }
             // first check for a cache_id which is normally empty
-            if (! empty($cache_id)) {
+            if ( ! empty($cache_id)) {
                 // if the cache_id exists, then it means we are purposely trying to cache this
                 // with a known key that can then be used to retrieve the object later on
-                $this->_model_relations[ $relationName ][ $cache_id ] = $object_to_cache;
+                $this->_model_relations[$relationName][$cache_id] = $object_to_cache;
                 $return = $cache_id;
             } elseif ($object_to_cache->ID()) {
                 // OR the cached object originally came from the db, so let's just use it's PK for an ID
-                $this->_model_relations[ $relationName ][ $object_to_cache->ID() ] = $object_to_cache;
+                $this->_model_relations[$relationName][$object_to_cache->ID()] = $object_to_cache;
                 $return = $object_to_cache->ID();
             } else {
                 // OR it's a new object with no ID, so just throw it in the array with an auto-incremented ID
-                $this->_model_relations[ $relationName ][] = $object_to_cache;
+                $this->_model_relations[$relationName][] = $object_to_cache;
                 // move the internal pointer to the end of the array
-                end($this->_model_relations[ $relationName ]);
+                end($this->_model_relations[$relationName]);
                 // and grab the key so that we can return it
-                $return = key($this->_model_relations[ $relationName ]);
+                $return = key($this->_model_relations[$relationName]);
             }
         }
         return $return;
@@ -634,7 +634,7 @@ 
         // first make sure this property exists
         $this->get_model()->field_settings_for($fieldname);
         $cache_type = empty($cache_type) ? 'standard' : $cache_type;
-        $this->_cached_properties[ $fieldname ][ $cache_type ] = $value;
+        $this->_cached_properties[$fieldname][$cache_type] = $value;
     }
 
 
@@ -663,9 +663,9 @@ 
         $model = $this->get_model();
         $model->field_settings_for($fieldname);
         $cache_type = $pretty ? 'pretty' : 'standard';
-        $cache_type .= ! empty($extra_cache_ref) ? '_' . $extra_cache_ref : '';
-        if (isset($this->_cached_properties[ $fieldname ][ $cache_type ])) {
-            return $this->_cached_properties[ $fieldname ][ $cache_type ];
+        $cache_type .= ! empty($extra_cache_ref) ? '_'.$extra_cache_ref : '';
+        if (isset($this->_cached_properties[$fieldname][$cache_type])) {
+            return $this->_cached_properties[$fieldname][$cache_type];
         }
         $value = $this->_get_fresh_property($fieldname, $pretty, $extra_cache_ref);
         $this->_set_cached_property($fieldname, $value, $cache_type);
@@ -693,12 +693,12 @@ 
         if ($field_obj instanceof EE_Datetime_Field) {
             $this->_prepare_datetime_field($field_obj, $pretty, $extra_cache_ref);
         }
-        if (! isset($this->_fields[ $fieldname ])) {
-            $this->_fields[ $fieldname ] = null;
+        if ( ! isset($this->_fields[$fieldname])) {
+            $this->_fields[$fieldname] = null;
         }
         $value = $pretty
-            ? $field_obj->prepare_for_pretty_echoing($this->_fields[ $fieldname ], $extra_cache_ref)
-            : $field_obj->prepare_for_get($this->_fields[ $fieldname ]);
+            ? $field_obj->prepare_for_pretty_echoing($this->_fields[$fieldname], $extra_cache_ref)
+            : $field_obj->prepare_for_get($this->_fields[$fieldname]);
         return $value;
     }
 
@@ -756,8 +756,8 @@ 
      */
     protected function _clear_cached_property($property_name)
     {
-        if (isset($this->_cached_properties[ $property_name ])) {
-            unset($this->_cached_properties[ $property_name ]);
+        if (isset($this->_cached_properties[$property_name])) {
+            unset($this->_cached_properties[$property_name]);
         }
     }
 
@@ -809,7 +809,7 @@ 
     {
         $relationship_to_model = $this->get_model()->related_settings_for($relationName);
         $index_in_cache = '';
-        if (! $relationship_to_model) {
+        if ( ! $relationship_to_model) {
             throw new EE_Error(
                 sprintf(
                     esc_html__('There is no relationship to %s on a %s. Cannot clear that cache', 'event_espresso'),
@@ -820,21 +820,21 @@ 
         }
         if ($clear_all) {
             $obj_removed = true;
-            $this->_model_relations[ $relationName ] = null;
+            $this->_model_relations[$relationName] = null;
         } elseif ($relationship_to_model instanceof EE_Belongs_To_Relation) {
-            $obj_removed = $this->_model_relations[ $relationName ];
-            $this->_model_relations[ $relationName ] = null;
+            $obj_removed = $this->_model_relations[$relationName];
+            $this->_model_relations[$relationName] = null;
         } else {
             if ($object_to_remove_or_index_into_array instanceof EE_Base_Class
                 && $object_to_remove_or_index_into_array->ID()
             ) {
                 $index_in_cache = $object_to_remove_or_index_into_array->ID();
-                if (is_array($this->_model_relations[ $relationName ])
-                    && ! isset($this->_model_relations[ $relationName ][ $index_in_cache ])
+                if (is_array($this->_model_relations[$relationName])
+                    && ! isset($this->_model_relations[$relationName][$index_in_cache])
                 ) {
                     $index_found_at = null;
                     // find this object in the array even though it has a different key
-                    foreach ($this->_model_relations[ $relationName ] as $index => $obj) {
+                    foreach ($this->_model_relations[$relationName] as $index => $obj) {
                         /** @noinspection TypeUnsafeComparisonInspection */
                         if ($obj instanceof EE_Base_Class
                             && (
@@ -867,9 +867,9 @@ 
             }
             // supposedly we've found it. But it could just be that the client code
             // provided a bad index/object
-            if (isset($this->_model_relations[ $relationName ][ $index_in_cache ])) {
-                $obj_removed = $this->_model_relations[ $relationName ][ $index_in_cache ];
-                unset($this->_model_relations[ $relationName ][ $index_in_cache ]);
+            if (isset($this->_model_relations[$relationName][$index_in_cache])) {
+                $obj_removed = $this->_model_relations[$relationName][$index_in_cache];
+                unset($this->_model_relations[$relationName][$index_in_cache]);
             } else {
                 // that thing was never cached anyways.
                 $obj_removed = null;
@@ -900,7 +900,7 @@ 
         $current_cache_id = ''
     ) {
         // verify that incoming object is of the correct type
-        $obj_class = 'EE_' . $relationName;
+        $obj_class = 'EE_'.$relationName;
         if ($newly_saved_object instanceof $obj_class) {
             /* @type EE_Base_Class $newly_saved_object */
             // now get the type of relation
@@ -908,17 +908,17 @@ 
             // if this is a 1:1 relationship
             if ($relationship_to_model instanceof EE_Belongs_To_Relation) {
                 // then just replace the cached object with the newly saved object
-                $this->_model_relations[ $relationName ] = $newly_saved_object;
+                $this->_model_relations[$relationName] = $newly_saved_object;
                 return true;
                 // or if it's some kind of sordid feral polyamorous relationship...
             }
-            if (is_array($this->_model_relations[ $relationName ])
-                && isset($this->_model_relations[ $relationName ][ $current_cache_id ])
+            if (is_array($this->_model_relations[$relationName])
+                && isset($this->_model_relations[$relationName][$current_cache_id])
             ) {
                 // then remove the current cached item
-                unset($this->_model_relations[ $relationName ][ $current_cache_id ]);
+                unset($this->_model_relations[$relationName][$current_cache_id]);
                 // and cache the newly saved object using it's new ID
-                $this->_model_relations[ $relationName ][ $newly_saved_object->ID() ] = $newly_saved_object;
+                $this->_model_relations[$relationName][$newly_saved_object->ID()] = $newly_saved_object;
                 return true;
             }
         }
@@ -935,8 +935,8 @@ 
      */
     public function get_one_from_cache($relationName)
     {
-        $cached_array_or_object = isset($this->_model_relations[ $relationName ])
-            ? $this->_model_relations[ $relationName ]
+        $cached_array_or_object = isset($this->_model_relations[$relationName])
+            ? $this->_model_relations[$relationName]
             : null;
         if (is_array($cached_array_or_object)) {
             return array_shift($cached_array_or_object);
@@ -959,7 +959,7 @@ 
      */
     public function get_all_from_cache($relationName)
     {
-        $objects = isset($this->_model_relations[ $relationName ]) ? $this->_model_relations[ $relationName ] : array();
+        $objects = isset($this->_model_relations[$relationName]) ? $this->_model_relations[$relationName] : array();
         // if the result is not an array, but exists, make it an array
         $objects = is_array($objects) ? $objects : array($objects);
         // bugfix for https://events.codebasehq.com/projects/event-espresso/tickets/7143
@@ -1143,7 +1143,7 @@ 
             } else {
                 $field_value = $field_obj->prepare_for_set_from_db($field_value_from_db);
             }
-            $this->_fields[ $field_name ] = $field_value;
+            $this->_fields[$field_name] = $field_value;
             $this->_clear_cached_property($field_name);
         }
     }
@@ -1183,9 +1183,9 @@ 
     public function get_raw($field_name)
     {
         $field_settings = $this->get_model()->field_settings_for($field_name);
-        return $field_settings instanceof EE_Datetime_Field && $this->_fields[ $field_name ] instanceof DateTime
-            ? $this->_fields[ $field_name ]->format('U')
-            : $this->_fields[ $field_name ];
+        return $field_settings instanceof EE_Datetime_Field && $this->_fields[$field_name] instanceof DateTime
+            ? $this->_fields[$field_name]->format('U')
+            : $this->_fields[$field_name];
     }
 
 
@@ -1207,7 +1207,7 @@ 
     public function get_DateTime_object($field_name)
     {
         $field_settings = $this->get_model()->field_settings_for($field_name);
-        if (! $field_settings instanceof EE_Datetime_Field) {
+        if ( ! $field_settings instanceof EE_Datetime_Field) {
             EE_Error::add_error(
                 sprintf(
                     esc_html__(
@@ -1222,8 +1222,8 @@ 
             );
             return false;
         }
-        return isset($this->_fields[ $field_name ]) && $this->_fields[ $field_name ] instanceof DateTime
-            ? clone $this->_fields[ $field_name ]
+        return isset($this->_fields[$field_name]) && $this->_fields[$field_name] instanceof DateTime
+            ? clone $this->_fields[$field_name]
             : null;
     }
 
@@ -1465,7 +1465,7 @@ 
      */
     public function get_i18n_datetime($field_name, $format = '')
     {
-        $format = empty($format) ? $this->_dt_frmt . ' ' . $this->_tm_frmt : $format;
+        $format = empty($format) ? $this->_dt_frmt.' '.$this->_tm_frmt : $format;
         return date_i18n(
             $format,
             EEH_DTT_Helper::get_timestamp_with_offset(
@@ -1577,21 +1577,21 @@ 
         $field->set_time_format($this->_tm_frmt);
         switch ($what) {
             case 'T':
-                $this->_fields[ $fieldname ] = $field->prepare_for_set_with_new_time(
+                $this->_fields[$fieldname] = $field->prepare_for_set_with_new_time(
                     $datetime_value,
-                    $this->_fields[ $fieldname ]
+                    $this->_fields[$fieldname]
                 );
                 $this->_has_changes = true;
                 break;
             case 'D':
-                $this->_fields[ $fieldname ] = $field->prepare_for_set_with_new_date(
+                $this->_fields[$fieldname] = $field->prepare_for_set_with_new_date(
                     $datetime_value,
-                    $this->_fields[ $fieldname ]
+                    $this->_fields[$fieldname]
                 );
                 $this->_has_changes = true;
                 break;
             case 'B':
-                $this->_fields[ $fieldname ] = $field->prepare_for_set($datetime_value);
+                $this->_fields[$fieldname] = $field->prepare_for_set($datetime_value);
                 $this->_has_changes = true;
                 break;
         }
@@ -1634,7 +1634,7 @@ 
         $this->set_timezone($timezone);
         $fn = (array) $field_name;
         $args = array_merge($fn, (array) $args);
-        if (! method_exists($this, $callback)) {
+        if ( ! method_exists($this, $callback)) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -1646,7 +1646,7 @@ 
             );
         }
         $args = (array) $args;
-        $return = $prepend . call_user_func_array(array($this, $callback), $args) . $append;
+        $return = $prepend.call_user_func_array(array($this, $callback), $args).$append;
         $this->set_timezone($original_timezone);
         return $return;
     }
@@ -1761,8 +1761,8 @@ 
     {
         $model = $this->get_model();
         foreach ($model->relation_settings() as $relation_name => $relation_obj) {
-            if (! empty($this->_model_relations[ $relation_name ])) {
-                $related_objects = $this->_model_relations[ $relation_name ];
+            if ( ! empty($this->_model_relations[$relation_name])) {
+                $related_objects = $this->_model_relations[$relation_name];
                 if ($relation_obj instanceof EE_Belongs_To_Relation) {
                     // this relation only stores a single model object, not an array
                     // but let's make it consistent
@@ -1819,7 +1819,7 @@ 
             $this->set($column, $value);
         }
         // no changes ? then don't do anything
-        if (! $this->_has_changes && $this->ID() && $model->get_primary_key_field()->is_auto_increment()) {
+        if ( ! $this->_has_changes && $this->ID() && $model->get_primary_key_field()->is_auto_increment()) {
             return 0;
         }
         /**
@@ -1829,7 +1829,7 @@ 
          * @param EE_Base_Class $model_object the model object about to be saved.
          */
         do_action('AHEE__EE_Base_Class__save__begin', $this);
-        if (! $this->allow_persist()) {
+        if ( ! $this->allow_persist()) {
             return 0;
         }
         // now get current attribute values
@@ -1844,10 +1844,10 @@ 
         if ($model->has_primary_key_field()) {
             if ($model->get_primary_key_field()->is_auto_increment()) {
                 // ok check if it's set, if so: update; if not, insert
-                if (! empty($save_cols_n_values[ $model->primary_key_name() ])) {
+                if ( ! empty($save_cols_n_values[$model->primary_key_name()])) {
                     $results = $model->update_by_ID($save_cols_n_values, $this->ID());
                 } else {
-                    unset($save_cols_n_values[ $model->primary_key_name() ]);
+                    unset($save_cols_n_values[$model->primary_key_name()]);
                     $results = $model->insert($save_cols_n_values);
                     if ($results) {
                         // if successful, set the primary key
@@ -1857,7 +1857,7 @@ 
                         // will get added to the mapper before we can add this one!
                         // but if we just avoid using the SET method, all that headache can be avoided
                         $pk_field_name = $model->primary_key_name();
-                        $this->_fields[ $pk_field_name ] = $results;
+                        $this->_fields[$pk_field_name] = $results;
                         $this->_clear_cached_property($pk_field_name);
                         $model->add_to_entity_map($this);
                         $this->_update_cached_related_model_objs_fks();
@@ -1874,8 +1874,8 @@ 
                                     'event_espresso'
                                 ),
                                 get_class($this),
-                                get_class($model) . '::instance()->add_to_entity_map()',
-                                get_class($model) . '::instance()->get_one_by_ID()',
+                                get_class($model).'::instance()->add_to_entity_map()',
+                                get_class($model).'::instance()->get_one_by_ID()',
                                 '<br />'
                             )
                         );
@@ -1977,27 +1977,27 @@ 
     public function save_new_cached_related_model_objs()
     {
         // make sure this has been saved
-        if (! $this->ID()) {
+        if ( ! $this->ID()) {
             $id = $this->save();
         } else {
             $id = $this->ID();
         }
         // now save all the NEW cached model objects  (ie they don't exist in the DB)
         foreach ($this->get_model()->relation_settings() as $relationName => $relationObj) {
-            if ($this->_model_relations[ $relationName ]) {
+            if ($this->_model_relations[$relationName]) {
                 // is this a relation where we should expect just ONE related object (ie, EE_Belongs_To_relation)
                 // or MANY related objects (ie, EE_HABTM_Relation or EE_Has_Many_Relation)?
                 /* @var $related_model_obj EE_Base_Class */
                 if ($relationObj instanceof EE_Belongs_To_Relation) {
                     // add a relation to that relation type (which saves the appropriate thing in the process)
                     // but ONLY if it DOES NOT exist in the DB
-                    $related_model_obj = $this->_model_relations[ $relationName ];
+                    $related_model_obj = $this->_model_relations[$relationName];
                     // if( ! $related_model_obj->ID()){
                     $this->_add_relation_to($related_model_obj, $relationName);
                     $related_model_obj->save_new_cached_related_model_objs();
                     // }
                 } else {
-                    foreach ($this->_model_relations[ $relationName ] as $related_model_obj) {
+                    foreach ($this->_model_relations[$relationName] as $related_model_obj) {
                         // add a relation to that relation type (which saves the appropriate thing in the process)
                         // but ONLY if it DOES NOT exist in the DB
                         // if( ! $related_model_obj->ID()){
@@ -2024,7 +2024,7 @@ 
      */
     public function get_model()
     {
-        if (! $this->_model) {
+        if ( ! $this->_model) {
             $modelName = self::_get_model_classname(get_class($this));
             $this->_model = self::_get_model_instance_with_name($modelName, $this->_timezone);
         } else {
@@ -2049,9 +2049,9 @@ 
         // TODO: will not work for Term_Relationships because they have no PK!
         $primary_id_ref = self::_get_primary_key_name($classname);
         if (array_key_exists($primary_id_ref, $props_n_values)
-            && ! empty($props_n_values[ $primary_id_ref ])
+            && ! empty($props_n_values[$primary_id_ref])
         ) {
-            $id = $props_n_values[ $primary_id_ref ];
+            $id = $props_n_values[$primary_id_ref];
             return self::_get_model($classname)->get_from_entity_map($id);
         }
         return false;
@@ -2085,10 +2085,10 @@ 
         if ($model->has_primary_key_field()) {
             $primary_id_ref = self::_get_primary_key_name($classname);
             if (array_key_exists($primary_id_ref, $props_n_values)
-                && ! empty($props_n_values[ $primary_id_ref ])
+                && ! empty($props_n_values[$primary_id_ref])
             ) {
                 $existing = $model->get_one_by_ID(
-                    $props_n_values[ $primary_id_ref ]
+                    $props_n_values[$primary_id_ref]
                 );
             }
         } elseif ($model->has_all_combined_primary_key_fields($props_n_values)) {
@@ -2100,7 +2100,7 @@ 
         }
         if ($existing) {
             // set date formats if present before setting values
-            if (! empty($date_formats) && is_array($date_formats)) {
+            if ( ! empty($date_formats) && is_array($date_formats)) {
                 $existing->set_date_format($date_formats[0]);
                 $existing->set_time_format($date_formats[1]);
             } else {
@@ -2133,7 +2133,7 @@ 
     protected static function _get_model($classname, $timezone = null)
     {
         // find model for this class
-        if (! $classname) {
+        if ( ! $classname) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -2182,7 +2182,7 @@ 
         if (strpos($model_name, 'EE_') === 0) {
             $model_classname = str_replace('EE_', 'EEM_', $model_name);
         } else {
-            $model_classname = 'EEM_' . $model_name;
+            $model_classname = 'EEM_'.$model_name;
         }
         return $model_classname;
     }
@@ -2201,7 +2201,7 @@ 
      */
     protected static function _get_primary_key_name($classname = null)
     {
-        if (! $classname) {
+        if ( ! $classname) {
             throw new EE_Error(
                 sprintf(
                     esc_html__('What were you thinking calling _get_primary_key_name(%s)', 'event_espresso'),
@@ -2231,7 +2231,7 @@ 
         $model = $this->get_model();
         // now that we know the name of the variable, use a variable variable to get its value and return its
         if ($model->has_primary_key_field()) {
-            return $this->_fields[ $model->primary_key_name() ];
+            return $this->_fields[$model->primary_key_name()];
         }
         return $model->get_index_primary_key_string($this->_fields);
     }
@@ -2284,7 +2284,7 @@ 
             }
         } else {
             // this thing doesn't exist in the DB,  so just cache it
-            if (! $otherObjectModelObjectOrID instanceof EE_Base_Class) {
+            if ( ! $otherObjectModelObjectOrID instanceof EE_Base_Class) {
                 throw new EE_Error(
                     sprintf(
                         esc_html__(
@@ -2449,7 +2449,7 @@ 
             } else {
                 // did we already cache the result of this query?
                 $cached_results = $this->get_all_from_cache($relationName);
-                if (! $cached_results) {
+                if ( ! $cached_results) {
                     $related_model_objects = $this->get_model()->get_all_related(
                         $this,
                         $relationName,
@@ -2559,7 +2559,7 @@ 
             } else {
                 // first, check if we've already cached the result of this query
                 $cached_result = $this->get_one_from_cache($relationName);
-                if (! $cached_result) {
+                if ( ! $cached_result) {
                     $related_model_object = $model->get_first_related(
                         $this,
                         $relationName,
@@ -2583,7 +2583,7 @@ 
             }
             // this doesn't exist in the DB and apparently the thing it belongs to doesn't either,
             // just get what's cached on this object
-            if (! $related_model_object) {
+            if ( ! $related_model_object) {
                 $related_model_object = $this->get_one_from_cache($relationName);
             }
         }
@@ -2665,7 +2665,7 @@ 
      */
     public function is_set($field_name)
     {
-        return isset($this->_fields[ $field_name ]);
+        return isset($this->_fields[$field_name]);
     }
 
 
@@ -2681,7 +2681,7 @@ 
     {
         foreach ((array) $properties as $property_name) {
             // first make sure this property exists
-            if (! $this->_fields[ $property_name ]) {
+            if ( ! $this->_fields[$property_name]) {
                 throw new EE_Error(
                     sprintf(
                         esc_html__(
@@ -2713,7 +2713,7 @@ 
         $properties = array();
         // remove prepended underscore
         foreach ($fields as $field_name => $settings) {
-            $properties[ $field_name ] = $this->get($field_name);
+            $properties[$field_name] = $this->get($field_name);
         }
         return $properties;
     }
@@ -2750,7 +2750,7 @@ 
     {
         $className = get_class($this);
         $tagName = "FHEE__{$className}__{$methodName}";
-        if (! has_filter($tagName)) {
+        if ( ! has_filter($tagName)) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -2795,7 +2795,7 @@ 
             $query_params[0]['EXM_value'] = $meta_value;
         }
         $existing_rows_like_that = EEM_Extra_Meta::instance()->get_all($query_params);
-        if (! $existing_rows_like_that) {
+        if ( ! $existing_rows_like_that) {
             return $this->add_extra_meta($meta_key, $meta_value);
         }
         foreach ($existing_rows_like_that as $existing_row) {
@@ -2913,7 +2913,7 @@ 
                 $values = array();
                 foreach ($results as $result) {
                     if ($result instanceof EE_Extra_Meta) {
-                        $values[ $result->ID() ] = $result->value();
+                        $values[$result->ID()] = $result->value();
                     }
                 }
                 return $values;
@@ -2958,17 +2958,17 @@ 
             );
             foreach ($extra_meta_objs as $extra_meta_obj) {
                 if ($extra_meta_obj instanceof EE_Extra_Meta) {
-                    $return_array[ $extra_meta_obj->key() ] = $extra_meta_obj->value();
+                    $return_array[$extra_meta_obj->key()] = $extra_meta_obj->value();
                 }
             }
         } else {
             $extra_meta_objs = $this->get_many_related('Extra_Meta');
             foreach ($extra_meta_objs as $extra_meta_obj) {
                 if ($extra_meta_obj instanceof EE_Extra_Meta) {
-                    if (! isset($return_array[ $extra_meta_obj->key() ])) {
-                        $return_array[ $extra_meta_obj->key() ] = array();
+                    if ( ! isset($return_array[$extra_meta_obj->key()])) {
+                        $return_array[$extra_meta_obj->key()] = array();
                     }
-                    $return_array[ $extra_meta_obj->key() ][ $extra_meta_obj->ID() ] = $extra_meta_obj->value();
+                    $return_array[$extra_meta_obj->key()][$extra_meta_obj->ID()] = $extra_meta_obj->value();
                 }
             }
         }
@@ -3049,8 +3049,8 @@ 
                             'event_espresso'
                         ),
                         $this->ID(),
-                        get_class($this->get_model()) . '::instance()->add_to_entity_map()',
-                        get_class($this->get_model()) . '::instance()->refresh_entity_map()'
+                        get_class($this->get_model()).'::instance()->add_to_entity_map()',
+                        get_class($this->get_model()).'::instance()->refresh_entity_map()'
                     )
                 );
             }
@@ -3083,7 +3083,7 @@ 
     {
         // First make sure this model object actually exists in the DB. It would be silly to try to update it in the DB
         // if it wasn't even there to start off.
-        if (! $this->ID()) {
+        if ( ! $this->ID()) {
             $this->save();
         }
         global $wpdb;
@@ -3313,7 +3313,7 @@ 
         $model = $this->get_model();
         foreach ($model->relation_settings() as $relation_name => $relation_obj) {
             if ($relation_obj instanceof EE_Belongs_To_Relation) {
-                $classname = 'EE_' . $model->get_this_model_name();
+                $classname = 'EE_'.$model->get_this_model_name();
                 if ($this->get_one_from_cache($relation_name) instanceof $classname
                     && $this->get_one_from_cache($relation_name)->ID()
                 ) {
@@ -3353,7 +3353,7 @@ 
         // handle DateTimes (this is handled in here because there's no one specific child class that uses datetimes).
         foreach ($this->_fields as $field => $value) {
             if ($value instanceof DateTime) {
-                $this->_fields[ $field ] = clone $value;
+                $this->_fields[$field] = clone $value;
             }
         }
     }

core/helpers/EEH_Schema.helper.php

Indentation +272 added lines, -272 removed lines

@@ -12,276 +12,276 @@
 {
 
 
-    /**
-     * generates JSON-based linked data for an event
-     *
-     * @param EE_Event $event
-     * @throws EE_Error
-     */
-    public static function add_json_linked_data_for_event(EE_Event $event)
-    {
-        // Check we have a valid datetime for the event
-        if (! $event->primary_datetime() instanceof EE_Datetime) {
-            return;
-        }
-
-        $template_args = array(
-            'event_permalink' => '',
-            'event_name' => '',
-            'event_description' => '',
-            'event_start' => '',
-            'event_end' => '',
-            'currency' => '',
-            'event_tickets' => array(),
-            'venue_name' => '',
-            'venue_url' => '',
-            'venue_locality' => '',
-            'venue_region' => '',
-            'venue_address' => '',
-            'event_image' => '',
-        );
-        $template_args['event_permalink'] = $event->get_permalink();
-        $template_args['event_name'] = $event->name();
-        $template_args['event_description'] = wp_strip_all_tags($event->short_description(200));
-        // clone datetime so that date formats don't override those for the original datetime
-        $primary_datetime = clone $event->primary_datetime();
-        $template_args['event_start'] = $primary_datetime->start_date(DateTime::ATOM);
-        $template_args['event_end'] = $primary_datetime->end_date(DateTime::ATOM);
-        unset($primary_datetime);
-        $template_args['currency'] = EE_Registry::instance()->CFG->currency->code;
-        foreach ($event->tickets() as $original_ticket) {
-            // clone tickets so that date formats don't override those for the original ticket
-            $ticket= clone $original_ticket;
-            $ID = $ticket->ID();
-            $template_args['event_tickets'][ $ID ]['start_date'] = $ticket->start_date(DateTime::ATOM, null);
-            $template_args['event_tickets'][ $ID ]['end_date'] = $ticket->end_date(DateTime::ATOM, null);
-            $template_args['event_tickets'][ $ID ]['price'] = number_format(
-                $ticket->price(),
-                EE_Registry::instance()->CFG->currency->dec_plc,
-                EE_Registry::instance()->CFG->currency->dec_mrk,
-                ''
-            );
-            switch ($ticket->ticket_status()) {
-                case 'TKO':
-                    $availability = 'InStock';
-                    break;
-                case 'TKS':
-                    $availability = 'SoldOut';
-                    break;
-                default:
-                    $availability = null;
-                    break;
-            }
-            $template_args['event_tickets'][ $ID ]['availability'] = $availability;
-            unset($ticket);
-        }
-        $VNU_ID = espresso_venue_id();
-        if (! empty($VNU_ID) && ! espresso_is_venue_private($VNU_ID)) {
-            $venue = EEH_Venue_View::get_venue($VNU_ID);
-            $template_args['venue_name'] = get_the_title($VNU_ID);
-            $template_args['venue_url'] = get_permalink($VNU_ID);
-            $template_args['venue_locality'] = $venue->city();
-            $template_args['venue_region'] = $venue->state_name();
-            $template_args['venue_address'] = $venue->address();
-        }
-        $template_args['event_image'] = $event->feature_image_url();
-        $template_args = apply_filters(
-            'FHEE__EEH_Schema__add_json_linked_data_for_event__template_args',
-            $template_args,
-            $event,
-            $VNU_ID
-        );
-        extract($template_args, EXTR_OVERWRITE);
-        include EE_TEMPLATES . 'json_linked_data_for_event.template.php';
-    }
-
-
-    /**
-     *    location
-     *    The location of the event, organization or action.
-     *    Should include the Venue name AND schema formatted address info
-     *
-     * @access public
-     * @param string $location
-     * @return string
-     */
-    public static function location($location = null)
-    {
-        return ! empty($location) ? '<div itemprop="location" itemscope itemtype="http://schema.org/Place">'
-                                      . $location
-                                      . '</div>' : '';
-    }
-
-
-
-    /**
-     *    name
-     *    The name of the Event or Venue.
-     *
-     * @access public
-     * @param string $name
-     * @return string
-     */
-    public static function name($name = null)
-    {
-        return ! empty($name) ? '<span itemprop="name">' . $name . '</span>' : '';
-    }
-
-
-
-    /**
-     *    streetAddress
-     *    The street address. For example, 1600 Amphitheatre Pkwy.
-     *
-     * @access public
-     * @param EEI_Address $obj_with_address
-     * @return string
-     */
-    public static function streetAddress(EEI_Address $obj_with_address = null)
-    {
-        return $obj_with_address->address() !== null && $obj_with_address->address() !== ''
-            ? '<span itemprop="streetAddress">' . $obj_with_address->address() . '</span>' : '';
-    }
-
-
-
-    /**
-     *    postOfficeBoxNumber
-     *    The post office box number for PO box addresses.
-     *
-     * @access public
-     * @param EEI_Address $obj_with_address
-     * @return string
-     */
-    public static function postOfficeBoxNumber(EEI_Address $obj_with_address = null)
-    {
-        // regex check for some form of PO Box or P.O. Box, etc, etc, etc
-        if (preg_match(
-            "/^\s*((P(OST)?.?\s*(O(FF(ICE)?)?)?.?\s+(B(IN|OX))?)|B(IN|OX))/i",
-            $obj_with_address->address2()
-        ) ) {
-            return $obj_with_address->address2() !== null && $obj_with_address->address2() !== ''
-                ? '<span itemprop="postOfficeBoxNumber">' . $obj_with_address->address2() . '</span>' : '';
-        } else {
-            return $obj_with_address->address2();
-        }
-    }
-
-
-
-    /**
-     *    addressLocality
-     *    The locality (city, town, etc). For example, Mountain View.
-     *
-     * @access public
-     * @param EEI_Address $obj_with_address
-     * @return string
-     */
-    public static function addressLocality(EEI_Address $obj_with_address = null)
-    {
-        return $obj_with_address->city() !== null && $obj_with_address->city() !== ''
-            ? '<span itemprop="addressLocality">' . $obj_with_address->city() . '</span>' : '';
-    }
-
-
-
-    /**
-     *    addressRegion
-     *    The region (state, province, etc). For example, CA.
-     *
-     * @access public
-     * @param EEI_Address $obj_with_address
-     * @return string
-     */
-    public static function addressRegion(EEI_Address $obj_with_address = null)
-    {
-        $state = $obj_with_address->state_name();
-        if (! empty($state)) {
-            return '<span itemprop="addressRegion">' . $state . '</span>';
-        } else {
-            return '';
-        }
-    }
-
-
-
-    /**
-     *    addressCountry
-     *    The country. For example, USA. You can also provide the two-letter ISO 3166-1 alpha-2 country code.
-     *
-     * @access public
-     * @param EEI_Address $obj_with_address
-     * @return string
-     */
-    public static function addressCountry(EEI_Address $obj_with_address = null)
-    {
-        $country = $obj_with_address->country_name();
-        if (! empty($country)) {
-            return '<span itemprop="addressCountry">' . $country . '</span>';
-        } else {
-            return '';
-        }
-    }
-
-
-
-    /**
-     *    postalCode
-     *    The postal code. For example, 94043.
-     *
-     * @access public
-     * @param EEI_Address $obj_with_address
-     * @return string
-     */
-    public static function postalCode(EEI_Address $obj_with_address = null)
-    {
-        return $obj_with_address->zip() !== null && $obj_with_address->zip() !== '' ? '<span itemprop="postalCode">'
-                                                                                      . $obj_with_address->zip()
-                                                                                      . '</span>' : '';
-    }
-
-
-
-    /**
-     *    telephone
-     *    The telephone number.
-     *
-     * @access public
-     * @param string $phone_nmbr
-     * @return string
-     */
-    public static function telephone($phone_nmbr = null)
-    {
-        return $phone_nmbr !== null && $phone_nmbr !== '' ? '<span itemprop="telephone">' . $phone_nmbr . '</span>'
-            : '';
-    }
-
-
-
-    /**
-     *    URL
-     *    URL of the item as a clickable link
-     *
-     * @access public
-     * @param string $url        - the URL that the link will resolve to
-     * @param string $text       - the text that will be used for the visible link
-     * @param array  $attributes - array of additional link attributes in  attribute_name => value pairs. ie: array( 'title' => 'click here', 'class' => 'link-class' )
-     * @return string (link)
-     */
-    public static function url($url = null, $text = null, $attributes = array())
-    {
-        // Check the URL includes a scheme
-        $parsed_url = parse_url($url);
-        if (empty($parsed_url['scheme'])) {
-            $url = 'http://' . ltrim($url, '/');
-        }
-
-        $atts = '';
-        foreach ($attributes as $attribute => $value) {
-            $atts .= ' ' . $attribute . '="' . $value . '"';
-        }
-        $text = $text !== null && $text !== '' ? $text : $url;
-        return $url !== null && $url !== '' ? '<a itemprop="url" href="' . $url . '"' . $atts . '>' . $text . '</a>'
-            : '';
-    }
+	/**
+	 * generates JSON-based linked data for an event
+	 *
+	 * @param EE_Event $event
+	 * @throws EE_Error
+	 */
+	public static function add_json_linked_data_for_event(EE_Event $event)
+	{
+		// Check we have a valid datetime for the event
+		if (! $event->primary_datetime() instanceof EE_Datetime) {
+			return;
+		}
+
+		$template_args = array(
+			'event_permalink' => '',
+			'event_name' => '',
+			'event_description' => '',
+			'event_start' => '',
+			'event_end' => '',
+			'currency' => '',
+			'event_tickets' => array(),
+			'venue_name' => '',
+			'venue_url' => '',
+			'venue_locality' => '',
+			'venue_region' => '',
+			'venue_address' => '',
+			'event_image' => '',
+		);
+		$template_args['event_permalink'] = $event->get_permalink();
+		$template_args['event_name'] = $event->name();
+		$template_args['event_description'] = wp_strip_all_tags($event->short_description(200));
+		// clone datetime so that date formats don't override those for the original datetime
+		$primary_datetime = clone $event->primary_datetime();
+		$template_args['event_start'] = $primary_datetime->start_date(DateTime::ATOM);
+		$template_args['event_end'] = $primary_datetime->end_date(DateTime::ATOM);
+		unset($primary_datetime);
+		$template_args['currency'] = EE_Registry::instance()->CFG->currency->code;
+		foreach ($event->tickets() as $original_ticket) {
+			// clone tickets so that date formats don't override those for the original ticket
+			$ticket= clone $original_ticket;
+			$ID = $ticket->ID();
+			$template_args['event_tickets'][ $ID ]['start_date'] = $ticket->start_date(DateTime::ATOM, null);
+			$template_args['event_tickets'][ $ID ]['end_date'] = $ticket->end_date(DateTime::ATOM, null);
+			$template_args['event_tickets'][ $ID ]['price'] = number_format(
+				$ticket->price(),
+				EE_Registry::instance()->CFG->currency->dec_plc,
+				EE_Registry::instance()->CFG->currency->dec_mrk,
+				''
+			);
+			switch ($ticket->ticket_status()) {
+				case 'TKO':
+					$availability = 'InStock';
+					break;
+				case 'TKS':
+					$availability = 'SoldOut';
+					break;
+				default:
+					$availability = null;
+					break;
+			}
+			$template_args['event_tickets'][ $ID ]['availability'] = $availability;
+			unset($ticket);
+		}
+		$VNU_ID = espresso_venue_id();
+		if (! empty($VNU_ID) && ! espresso_is_venue_private($VNU_ID)) {
+			$venue = EEH_Venue_View::get_venue($VNU_ID);
+			$template_args['venue_name'] = get_the_title($VNU_ID);
+			$template_args['venue_url'] = get_permalink($VNU_ID);
+			$template_args['venue_locality'] = $venue->city();
+			$template_args['venue_region'] = $venue->state_name();
+			$template_args['venue_address'] = $venue->address();
+		}
+		$template_args['event_image'] = $event->feature_image_url();
+		$template_args = apply_filters(
+			'FHEE__EEH_Schema__add_json_linked_data_for_event__template_args',
+			$template_args,
+			$event,
+			$VNU_ID
+		);
+		extract($template_args, EXTR_OVERWRITE);
+		include EE_TEMPLATES . 'json_linked_data_for_event.template.php';
+	}
+
+
+	/**
+	 *    location
+	 *    The location of the event, organization or action.
+	 *    Should include the Venue name AND schema formatted address info
+	 *
+	 * @access public
+	 * @param string $location
+	 * @return string
+	 */
+	public static function location($location = null)
+	{
+		return ! empty($location) ? '<div itemprop="location" itemscope itemtype="http://schema.org/Place">'
+									  . $location
+									  . '</div>' : '';
+	}
+
+
+
+	/**
+	 *    name
+	 *    The name of the Event or Venue.
+	 *
+	 * @access public
+	 * @param string $name
+	 * @return string
+	 */
+	public static function name($name = null)
+	{
+		return ! empty($name) ? '<span itemprop="name">' . $name . '</span>' : '';
+	}
+
+
+
+	/**
+	 *    streetAddress
+	 *    The street address. For example, 1600 Amphitheatre Pkwy.
+	 *
+	 * @access public
+	 * @param EEI_Address $obj_with_address
+	 * @return string
+	 */
+	public static function streetAddress(EEI_Address $obj_with_address = null)
+	{
+		return $obj_with_address->address() !== null && $obj_with_address->address() !== ''
+			? '<span itemprop="streetAddress">' . $obj_with_address->address() . '</span>' : '';
+	}
+
+
+
+	/**
+	 *    postOfficeBoxNumber
+	 *    The post office box number for PO box addresses.
+	 *
+	 * @access public
+	 * @param EEI_Address $obj_with_address
+	 * @return string
+	 */
+	public static function postOfficeBoxNumber(EEI_Address $obj_with_address = null)
+	{
+		// regex check for some form of PO Box or P.O. Box, etc, etc, etc
+		if (preg_match(
+			"/^\s*((P(OST)?.?\s*(O(FF(ICE)?)?)?.?\s+(B(IN|OX))?)|B(IN|OX))/i",
+			$obj_with_address->address2()
+		) ) {
+			return $obj_with_address->address2() !== null && $obj_with_address->address2() !== ''
+				? '<span itemprop="postOfficeBoxNumber">' . $obj_with_address->address2() . '</span>' : '';
+		} else {
+			return $obj_with_address->address2();
+		}
+	}
+
+
+
+	/**
+	 *    addressLocality
+	 *    The locality (city, town, etc). For example, Mountain View.
+	 *
+	 * @access public
+	 * @param EEI_Address $obj_with_address
+	 * @return string
+	 */
+	public static function addressLocality(EEI_Address $obj_with_address = null)
+	{
+		return $obj_with_address->city() !== null && $obj_with_address->city() !== ''
+			? '<span itemprop="addressLocality">' . $obj_with_address->city() . '</span>' : '';
+	}
+
+
+
+	/**
+	 *    addressRegion
+	 *    The region (state, province, etc). For example, CA.
+	 *
+	 * @access public
+	 * @param EEI_Address $obj_with_address
+	 * @return string
+	 */
+	public static function addressRegion(EEI_Address $obj_with_address = null)
+	{
+		$state = $obj_with_address->state_name();
+		if (! empty($state)) {
+			return '<span itemprop="addressRegion">' . $state . '</span>';
+		} else {
+			return '';
+		}
+	}
+
+
+
+	/**
+	 *    addressCountry
+	 *    The country. For example, USA. You can also provide the two-letter ISO 3166-1 alpha-2 country code.
+	 *
+	 * @access public
+	 * @param EEI_Address $obj_with_address
+	 * @return string
+	 */
+	public static function addressCountry(EEI_Address $obj_with_address = null)
+	{
+		$country = $obj_with_address->country_name();
+		if (! empty($country)) {
+			return '<span itemprop="addressCountry">' . $country . '</span>';
+		} else {
+			return '';
+		}
+	}
+
+
+
+	/**
+	 *    postalCode
+	 *    The postal code. For example, 94043.
+	 *
+	 * @access public
+	 * @param EEI_Address $obj_with_address
+	 * @return string
+	 */
+	public static function postalCode(EEI_Address $obj_with_address = null)
+	{
+		return $obj_with_address->zip() !== null && $obj_with_address->zip() !== '' ? '<span itemprop="postalCode">'
+																					  . $obj_with_address->zip()
+																					  . '</span>' : '';
+	}
+
+
+
+	/**
+	 *    telephone
+	 *    The telephone number.
+	 *
+	 * @access public
+	 * @param string $phone_nmbr
+	 * @return string
+	 */
+	public static function telephone($phone_nmbr = null)
+	{
+		return $phone_nmbr !== null && $phone_nmbr !== '' ? '<span itemprop="telephone">' . $phone_nmbr . '</span>'
+			: '';
+	}
+
+
+
+	/**
+	 *    URL
+	 *    URL of the item as a clickable link
+	 *
+	 * @access public
+	 * @param string $url        - the URL that the link will resolve to
+	 * @param string $text       - the text that will be used for the visible link
+	 * @param array  $attributes - array of additional link attributes in  attribute_name => value pairs. ie: array( 'title' => 'click here', 'class' => 'link-class' )
+	 * @return string (link)
+	 */
+	public static function url($url = null, $text = null, $attributes = array())
+	{
+		// Check the URL includes a scheme
+		$parsed_url = parse_url($url);
+		if (empty($parsed_url['scheme'])) {
+			$url = 'http://' . ltrim($url, '/');
+		}
+
+		$atts = '';
+		foreach ($attributes as $attribute => $value) {
+			$atts .= ' ' . $attribute . '="' . $value . '"';
+		}
+		$text = $text !== null && $text !== '' ? $text : $url;
+		return $url !== null && $url !== '' ? '<a itemprop="url" href="' . $url . '"' . $atts . '>' . $text . '</a>'
+			: '';
+	}
 }

core/libraries/form_sections/payment_methods/EE_Billing_Attendee_Info_Form.form.php

Indentation +157 added lines, -157 removed lines

@@ -14,172 +14,172 @@
 class EE_Billing_Attendee_Info_Form extends EE_Billing_Info_Form
 {
 
-    /**
-     *
-     * @param EE_Payment_Method $payment_method
-     * @param array $options_array @see EE_Form_Section_Proper::__construct()
-     */
-    public function __construct(EE_Payment_Method $payment_method, $options_array = array())
-    {
-        $options_array['subsections'] = array_merge(
-            array(
-                'first_name'    => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-fname', 'html_label_text' => __('First Name', 'event_espresso') )),
-                'last_name'     => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-lname', 'html_label_text' => __('Last Name', 'event_espresso') )),
-                'email'             => new EE_Email_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-email', 'html_label_text' => __('Email', 'event_espresso') )),
-                'address'           => new EE_Text_Input(array( 'html_label_text'=>  __('Address', 'event_espresso'), 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-address' )),
-                'address2'      => new EE_Text_Input(array( 'html_label_text'=> __('Address 2', 'event_espresso'), 'html_class' => 'ee-billing-qstn ee-billing-qstn-address2' )),
-                'city'                  => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-city', 'html_label_text' => __('City', 'event_espresso') )),
-                'state'                 => apply_filters('FHEE__EE_Billing_Attendee_Info_Form__state_field', new EE_State_Select_Input(null, array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-state', 'html_label_text' => __('State', 'event_espresso') ))),
-                'country'           => apply_filters('FHEE__EE_Billing_Attendee_Info_Form__country_field', new EE_Country_Select_Input(null, array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-country', 'html_label_text' => __('Country', 'event_espresso') ))),
-                'zip'                   => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-zip', 'html_label_text' => __('Zip', 'event_espresso') )),
-                'phone'         => new EE_Text_Input(array( 'html_class' => 'ee-billing-qstn ee-billing-qstn-phone', 'html_label_text' => __('Phone', 'event_espresso') )),
-            ),
-            isset($options_array['subsections']) ? $options_array['subsections'] : array()
-        );
+	/**
+	 *
+	 * @param EE_Payment_Method $payment_method
+	 * @param array $options_array @see EE_Form_Section_Proper::__construct()
+	 */
+	public function __construct(EE_Payment_Method $payment_method, $options_array = array())
+	{
+		$options_array['subsections'] = array_merge(
+			array(
+				'first_name'    => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-fname', 'html_label_text' => __('First Name', 'event_espresso') )),
+				'last_name'     => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-lname', 'html_label_text' => __('Last Name', 'event_espresso') )),
+				'email'             => new EE_Email_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-email', 'html_label_text' => __('Email', 'event_espresso') )),
+				'address'           => new EE_Text_Input(array( 'html_label_text'=>  __('Address', 'event_espresso'), 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-address' )),
+				'address2'      => new EE_Text_Input(array( 'html_label_text'=> __('Address 2', 'event_espresso'), 'html_class' => 'ee-billing-qstn ee-billing-qstn-address2' )),
+				'city'                  => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-city', 'html_label_text' => __('City', 'event_espresso') )),
+				'state'                 => apply_filters('FHEE__EE_Billing_Attendee_Info_Form__state_field', new EE_State_Select_Input(null, array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-state', 'html_label_text' => __('State', 'event_espresso') ))),
+				'country'           => apply_filters('FHEE__EE_Billing_Attendee_Info_Form__country_field', new EE_Country_Select_Input(null, array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-country', 'html_label_text' => __('Country', 'event_espresso') ))),
+				'zip'                   => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-zip', 'html_label_text' => __('Zip', 'event_espresso') )),
+				'phone'         => new EE_Text_Input(array( 'html_class' => 'ee-billing-qstn ee-billing-qstn-phone', 'html_label_text' => __('Phone', 'event_espresso') )),
+			),
+			isset($options_array['subsections']) ? $options_array['subsections'] : array()
+		);
 
-        parent::__construct($payment_method, $options_array);
-    }
+		parent::__construct($payment_method, $options_array);
+	}
 
-    /**
-     * Sets the defaults for the billing form according to the attendee's details
-     * @param EE_Attendee $attendee
-     */
-    public function populate_from_attendee($attendee)
-    {
-        $attendee = EEM_Attendee::instance()->ensure_is_obj($attendee);
+	/**
+	 * Sets the defaults for the billing form according to the attendee's details
+	 * @param EE_Attendee $attendee
+	 */
+	public function populate_from_attendee($attendee)
+	{
+		$attendee = EEM_Attendee::instance()->ensure_is_obj($attendee);
 
-        /** @var $attendee EE_Attendee */
-        $this->populate_defaults(
-            apply_filters(
-                'FHEE__EE_Billing_Attendee_Info_Form__populate_from_attendee',
-                array(
-                    'first_name'=>$attendee->fname(),
-                    'last_name'=>$attendee->lname(),
-                    'email'=>$attendee->email(),
-                    'address'=>$attendee->address(),
-                    'address2'=>$attendee->address2(),
-                    'city'=>$attendee->city(),
-                    'state'=> $this->getAttendeeStateValueForForm($attendee),
-                    'country'=> $attendee->country_ID(),
-                    'zip'=>$attendee->zip(),
-                    'phone'=>$attendee->phone(),
-                ),
-                $attendee,
-                $this
-            )
-        );
-    }
+		/** @var $attendee EE_Attendee */
+		$this->populate_defaults(
+			apply_filters(
+				'FHEE__EE_Billing_Attendee_Info_Form__populate_from_attendee',
+				array(
+					'first_name'=>$attendee->fname(),
+					'last_name'=>$attendee->lname(),
+					'email'=>$attendee->email(),
+					'address'=>$attendee->address(),
+					'address2'=>$attendee->address2(),
+					'city'=>$attendee->city(),
+					'state'=> $this->getAttendeeStateValueForForm($attendee),
+					'country'=> $attendee->country_ID(),
+					'zip'=>$attendee->zip(),
+					'phone'=>$attendee->phone(),
+				),
+				$attendee,
+				$this
+			)
+		);
+	}
 
-    /**
-     * Gets the default value to use for the billing form's state value.
-     * @since $VID:$
-     * @param EE_Attendee $attendee
-     * @return string
-     * @throws EE_Error2
-     */
-    protected function getAttendeeStateValueForForm(EE_Attendee $attendee)
-    {
-        // If the state input was removed, just return a blank string.
-        if (! $this->has_subsection('state')) {
-            return '';
-        }
-        $state_input =  $this->get_input('state', false);
-        if ($state_input instanceof EE_State_Select_Input) {
-            $state_field_to_use =  $state_input->valueFieldName();
-        } else {
-            $state_field_to_use = 'STA_ID';
-        }
-        switch ($state_field_to_use) {
-            case 'STA_abbrev':
-                $state_value = $attendee->state_abbrev();
-                break;
-            case 'STA_name':
-                $state_value = $attendee->state_name();
-                break;
-            default:
-                $state_value = $attendee->state_ID();
-        }
-        return $state_value;
-    }
+	/**
+	 * Gets the default value to use for the billing form's state value.
+	 * @since $VID:$
+	 * @param EE_Attendee $attendee
+	 * @return string
+	 * @throws EE_Error2
+	 */
+	protected function getAttendeeStateValueForForm(EE_Attendee $attendee)
+	{
+		// If the state input was removed, just return a blank string.
+		if (! $this->has_subsection('state')) {
+			return '';
+		}
+		$state_input =  $this->get_input('state', false);
+		if ($state_input instanceof EE_State_Select_Input) {
+			$state_field_to_use =  $state_input->valueFieldName();
+		} else {
+			$state_field_to_use = 'STA_ID';
+		}
+		switch ($state_field_to_use) {
+			case 'STA_abbrev':
+				$state_value = $attendee->state_abbrev();
+				break;
+			case 'STA_name':
+				$state_value = $attendee->state_name();
+				break;
+			default:
+				$state_value = $attendee->state_ID();
+		}
+		return $state_value;
+	}
 
 
 
-    /**
-     * copy_billing_form_data_to_attendee
-     * copies info from the billing form to the attendee's details
-     * @param \EE_Attendee $attendee - the attendee object to copy details to
-     * @return \EE_Attendee
-     */
-    public function copy_billing_form_data_to_attendee(EE_Attendee $attendee)
-    {
-        // grab billing form data
-        $data = $this->valid_data();
-        // copy first_name
-        if (! empty($data['first_name'])) {
-            $attendee->set_fname($data['first_name']);
-        }
-        // copy last_name
-        if (! empty($data['last_name'])) {
-            $attendee->set_lname($data['last_name']);
-        }
-        // copy email
-        if (! empty($data['email'])) {
-            $attendee->set_email($data['email']);
-        }
-        // copy address
-        if (! empty($data['address'])) {
-            $attendee->set_address($data['address']);
-        }
-        // copy address2
-        if (! empty($data['address2'])) {
-            $attendee->set_address2($data['address2']);
-        }
-        // copy city
-        if (! empty($data['city'])) {
-            $attendee->set_city($data['city']);
-        }
-        // copy state
-        if (! empty($data['state'])) {
-            $attendee->set_state($data['state']);
-        }
-        // copy country
-        if (! empty($data['country'])) {
-            $attendee->set_country($data['country']);
-        }
-        // copy zip
-        if (! empty($data['zip'])) {
-            $attendee->set_zip($data['zip']);
-        }
-        // copy phone
-        if (! empty($data['phone'])) {
-            $attendee->set_phone($data['phone']);
-        }
-        return $attendee;
-    }
+	/**
+	 * copy_billing_form_data_to_attendee
+	 * copies info from the billing form to the attendee's details
+	 * @param \EE_Attendee $attendee - the attendee object to copy details to
+	 * @return \EE_Attendee
+	 */
+	public function copy_billing_form_data_to_attendee(EE_Attendee $attendee)
+	{
+		// grab billing form data
+		$data = $this->valid_data();
+		// copy first_name
+		if (! empty($data['first_name'])) {
+			$attendee->set_fname($data['first_name']);
+		}
+		// copy last_name
+		if (! empty($data['last_name'])) {
+			$attendee->set_lname($data['last_name']);
+		}
+		// copy email
+		if (! empty($data['email'])) {
+			$attendee->set_email($data['email']);
+		}
+		// copy address
+		if (! empty($data['address'])) {
+			$attendee->set_address($data['address']);
+		}
+		// copy address2
+		if (! empty($data['address2'])) {
+			$attendee->set_address2($data['address2']);
+		}
+		// copy city
+		if (! empty($data['city'])) {
+			$attendee->set_city($data['city']);
+		}
+		// copy state
+		if (! empty($data['state'])) {
+			$attendee->set_state($data['state']);
+		}
+		// copy country
+		if (! empty($data['country'])) {
+			$attendee->set_country($data['country']);
+		}
+		// copy zip
+		if (! empty($data['zip'])) {
+			$attendee->set_zip($data['zip']);
+		}
+		// copy phone
+		if (! empty($data['phone'])) {
+			$attendee->set_phone($data['phone']);
+		}
+		return $attendee;
+	}
 
 
-    /**
-     * create_attendee_from_billing_form_data
-     * uses info from the billing form to create a new attendee
-     * @return \EE_Attendee
-     */
-    public function create_attendee_from_billing_form_data()
-    {
-        // grab billing form data
-        $data = $this->valid_data();
-        return EE_Attendee::new_instance(array(
-            'ATT_fname'         => ! empty($data['first_name']) ? $data['first_name'] : '',
-            'ATT_lname'         => ! empty($data['last_name']) ? $data['last_name'] : '',
-            'ATT_email'         => ! empty($data['email']) ? $data['email'] : '',
-            'ATT_address'       => ! empty($data['address']) ? $data['address'] : '',
-            'ATT_address2'  => ! empty($data['address2']) ? $data['address2'] : '',
-            'ATT_city'          => ! empty($data['city']) ? $data['city'] : '',
-            'STA_ID'                => ! empty($data['state']) ? $data['state'] : '',
-            'CNT_ISO'           => ! empty($data['country']) ? $data['country'] : '',
-            'ATT_zip'               => ! empty($data['zip']) ? $data['zip'] : '',
-            'ATT_phone'         => ! empty($data['phone']) ? $data['phone'] : '',
-        ));
-    }
+	/**
+	 * create_attendee_from_billing_form_data
+	 * uses info from the billing form to create a new attendee
+	 * @return \EE_Attendee
+	 */
+	public function create_attendee_from_billing_form_data()
+	{
+		// grab billing form data
+		$data = $this->valid_data();
+		return EE_Attendee::new_instance(array(
+			'ATT_fname'         => ! empty($data['first_name']) ? $data['first_name'] : '',
+			'ATT_lname'         => ! empty($data['last_name']) ? $data['last_name'] : '',
+			'ATT_email'         => ! empty($data['email']) ? $data['email'] : '',
+			'ATT_address'       => ! empty($data['address']) ? $data['address'] : '',
+			'ATT_address2'  => ! empty($data['address2']) ? $data['address2'] : '',
+			'ATT_city'          => ! empty($data['city']) ? $data['city'] : '',
+			'STA_ID'                => ! empty($data['state']) ? $data['state'] : '',
+			'CNT_ISO'           => ! empty($data['country']) ? $data['country'] : '',
+			'ATT_zip'               => ! empty($data['zip']) ? $data['zip'] : '',
+			'ATT_phone'         => ! empty($data['phone']) ? $data['phone'] : '',
+		));
+	}
 }
 
 // End of file EE_Billing_Attendee_Info_Form.form.php

Spacing +23 added lines, -23 removed lines

@@ -23,16 +23,16 @@ 
     {
         $options_array['subsections'] = array_merge(
             array(
-                'first_name'    => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-fname', 'html_label_text' => __('First Name', 'event_espresso') )),
-                'last_name'     => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-lname', 'html_label_text' => __('Last Name', 'event_espresso') )),
-                'email'             => new EE_Email_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-email', 'html_label_text' => __('Email', 'event_espresso') )),
-                'address'           => new EE_Text_Input(array( 'html_label_text'=>  __('Address', 'event_espresso'), 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-address' )),
-                'address2'      => new EE_Text_Input(array( 'html_label_text'=> __('Address 2', 'event_espresso'), 'html_class' => 'ee-billing-qstn ee-billing-qstn-address2' )),
-                'city'                  => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-city', 'html_label_text' => __('City', 'event_espresso') )),
-                'state'                 => apply_filters('FHEE__EE_Billing_Attendee_Info_Form__state_field', new EE_State_Select_Input(null, array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-state', 'html_label_text' => __('State', 'event_espresso') ))),
-                'country'           => apply_filters('FHEE__EE_Billing_Attendee_Info_Form__country_field', new EE_Country_Select_Input(null, array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-country', 'html_label_text' => __('Country', 'event_espresso') ))),
-                'zip'                   => new EE_Text_Input(array( 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-zip', 'html_label_text' => __('Zip', 'event_espresso') )),
-                'phone'         => new EE_Text_Input(array( 'html_class' => 'ee-billing-qstn ee-billing-qstn-phone', 'html_label_text' => __('Phone', 'event_espresso') )),
+                'first_name'    => new EE_Text_Input(array('required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-fname', 'html_label_text' => __('First Name', 'event_espresso'))),
+                'last_name'     => new EE_Text_Input(array('required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-lname', 'html_label_text' => __('Last Name', 'event_espresso'))),
+                'email'             => new EE_Email_Input(array('required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-email', 'html_label_text' => __('Email', 'event_espresso'))),
+                'address'           => new EE_Text_Input(array('html_label_text'=>  __('Address', 'event_espresso'), 'required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-address')),
+                'address2'      => new EE_Text_Input(array('html_label_text'=> __('Address 2', 'event_espresso'), 'html_class' => 'ee-billing-qstn ee-billing-qstn-address2')),
+                'city'                  => new EE_Text_Input(array('required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-city', 'html_label_text' => __('City', 'event_espresso'))),
+                'state'                 => apply_filters('FHEE__EE_Billing_Attendee_Info_Form__state_field', new EE_State_Select_Input(null, array('required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-state', 'html_label_text' => __('State', 'event_espresso')))),
+                'country'           => apply_filters('FHEE__EE_Billing_Attendee_Info_Form__country_field', new EE_Country_Select_Input(null, array('required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-country', 'html_label_text' => __('Country', 'event_espresso')))),
+                'zip'                   => new EE_Text_Input(array('required'=>true, 'html_class' => 'ee-billing-qstn ee-billing-qstn-zip', 'html_label_text' => __('Zip', 'event_espresso'))),
+                'phone'         => new EE_Text_Input(array('html_class' => 'ee-billing-qstn ee-billing-qstn-phone', 'html_label_text' => __('Phone', 'event_espresso'))),
             ),
             isset($options_array['subsections']) ? $options_array['subsections'] : array()
         );
@@ -80,12 +80,12 @@ 
     protected function getAttendeeStateValueForForm(EE_Attendee $attendee)
     {
         // If the state input was removed, just return a blank string.
-        if (! $this->has_subsection('state')) {
+        if ( ! $this->has_subsection('state')) {
             return '';
         }
-        $state_input =  $this->get_input('state', false);
+        $state_input = $this->get_input('state', false);
         if ($state_input instanceof EE_State_Select_Input) {
-            $state_field_to_use =  $state_input->valueFieldName();
+            $state_field_to_use = $state_input->valueFieldName();
         } else {
             $state_field_to_use = 'STA_ID';
         }
@@ -115,43 +115,43 @@ 
         // grab billing form data
         $data = $this->valid_data();
         // copy first_name
-        if (! empty($data['first_name'])) {
+        if ( ! empty($data['first_name'])) {
             $attendee->set_fname($data['first_name']);
         }
         // copy last_name
-        if (! empty($data['last_name'])) {
+        if ( ! empty($data['last_name'])) {
             $attendee->set_lname($data['last_name']);
         }
         // copy email
-        if (! empty($data['email'])) {
+        if ( ! empty($data['email'])) {
             $attendee->set_email($data['email']);
         }
         // copy address
-        if (! empty($data['address'])) {
+        if ( ! empty($data['address'])) {
             $attendee->set_address($data['address']);
         }
         // copy address2
-        if (! empty($data['address2'])) {
+        if ( ! empty($data['address2'])) {
             $attendee->set_address2($data['address2']);
         }
         // copy city
-        if (! empty($data['city'])) {
+        if ( ! empty($data['city'])) {
             $attendee->set_city($data['city']);
         }
         // copy state
-        if (! empty($data['state'])) {
+        if ( ! empty($data['state'])) {
             $attendee->set_state($data['state']);
         }
         // copy country
-        if (! empty($data['country'])) {
+        if ( ! empty($data['country'])) {
             $attendee->set_country($data['country']);
         }
         // copy zip
-        if (! empty($data['zip'])) {
+        if ( ! empty($data['zip'])) {
             $attendee->set_zip($data['zip']);
         }
         // copy phone
-        if (! empty($data['phone'])) {
+        if ( ! empty($data['phone'])) {
             $attendee->set_phone($data['phone']);
         }
         return $attendee;

modules/single_page_checkout/reg_steps/payment_options/EE_SPCO_Reg_Step_Payment_Options.class.php

Indentation +2889 added lines, -2889 removed lines

@@ -12,2893 +12,2893 @@
 class EE_SPCO_Reg_Step_Payment_Options extends EE_SPCO_Reg_Step
 {
 
-    /**
-     * @access protected
-     * @var EE_Line_Item_Display $Line_Item_Display
-     */
-    protected $line_item_display;
-
-    /**
-     * @access protected
-     * @var boolean $handle_IPN_in_this_request
-     */
-    protected $handle_IPN_in_this_request = false;
-
-
-    /**
-     *    set_hooks - for hooking into EE Core, other modules, etc
-     *
-     * @access    public
-     * @return    void
-     */
-    public static function set_hooks()
-    {
-        add_filter(
-            'FHEE__SPCO__EE_Line_Item_Filter_Collection',
-            array('EE_SPCO_Reg_Step_Payment_Options', 'add_spco_line_item_filters')
-        );
-        add_action(
-            'wp_ajax_switch_spco_billing_form',
-            array('EE_SPCO_Reg_Step_Payment_Options', 'switch_spco_billing_form')
-        );
-        add_action(
-            'wp_ajax_nopriv_switch_spco_billing_form',
-            array('EE_SPCO_Reg_Step_Payment_Options', 'switch_spco_billing_form')
-        );
-        add_action('wp_ajax_save_payer_details', array('EE_SPCO_Reg_Step_Payment_Options', 'save_payer_details'));
-        add_action(
-            'wp_ajax_nopriv_save_payer_details',
-            array('EE_SPCO_Reg_Step_Payment_Options', 'save_payer_details')
-        );
-        add_action(
-            'wp_ajax_get_transaction_details_for_gateways',
-            array('EE_SPCO_Reg_Step_Payment_Options', 'get_transaction_details')
-        );
-        add_action(
-            'wp_ajax_nopriv_get_transaction_details_for_gateways',
-            array('EE_SPCO_Reg_Step_Payment_Options', 'get_transaction_details')
-        );
-        add_filter(
-            'FHEE__EED_Recaptcha___bypass_recaptcha__bypass_request_params_array',
-            array('EE_SPCO_Reg_Step_Payment_Options', 'bypass_recaptcha_for_load_payment_method'),
-            10,
-            1
-        );
-    }
-
-
-    /**
-     *    ajax switch_spco_billing_form
-     *
-     * @throws \EE_Error
-     */
-    public static function switch_spco_billing_form()
-    {
-        EED_Single_Page_Checkout::process_ajax_request('switch_payment_method');
-    }
-
-
-    /**
-     *    ajax save_payer_details
-     *
-     * @throws \EE_Error
-     */
-    public static function save_payer_details()
-    {
-        EED_Single_Page_Checkout::process_ajax_request('save_payer_details_via_ajax');
-    }
-
-
-    /**
-     *    ajax get_transaction_details
-     *
-     * @throws \EE_Error
-     */
-    public static function get_transaction_details()
-    {
-        EED_Single_Page_Checkout::process_ajax_request('get_transaction_details_for_gateways');
-    }
-
-
-    /**
-     * bypass_recaptcha_for_load_payment_method
-     *
-     * @access public
-     * @return array
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    public static function bypass_recaptcha_for_load_payment_method()
-    {
-        return array(
-            'EESID'  => EE_Registry::instance()->SSN->id(),
-            'step'   => 'payment_options',
-            'action' => 'spco_billing_form',
-        );
-    }
-
-
-    /**
-     *    class constructor
-     *
-     * @access    public
-     * @param    EE_Checkout $checkout
-     */
-    public function __construct(EE_Checkout $checkout)
-    {
-        $this->_slug = 'payment_options';
-        $this->_name = esc_html__('Payment Options', 'event_espresso');
-        $this->_template = SPCO_REG_STEPS_PATH . $this->_slug . DS . 'payment_options_main.template.php';
-        $this->checkout = $checkout;
-        $this->_reset_success_message();
-        $this->set_instructions(
-            esc_html__(
-                'Please select a method of payment and provide any necessary billing information before proceeding.',
-                'event_espresso'
-            )
-        );
-    }
-
-
-    /**
-     * @return null
-     */
-    public function line_item_display()
-    {
-        return $this->line_item_display;
-    }
-
-
-    /**
-     * @param null $line_item_display
-     */
-    public function set_line_item_display($line_item_display)
-    {
-        $this->line_item_display = $line_item_display;
-    }
-
-
-    /**
-     * @return boolean
-     */
-    public function handle_IPN_in_this_request()
-    {
-        return $this->handle_IPN_in_this_request;
-    }
-
-
-    /**
-     * @param boolean $handle_IPN_in_this_request
-     */
-    public function set_handle_IPN_in_this_request($handle_IPN_in_this_request)
-    {
-        $this->handle_IPN_in_this_request = filter_var($handle_IPN_in_this_request, FILTER_VALIDATE_BOOLEAN);
-    }
-
-
-    /**
-     * translate_js_strings
-     *
-     * @return void
-     */
-    public function translate_js_strings()
-    {
-        EE_Registry::$i18n_js_strings['no_payment_method'] = esc_html__(
-            'Please select a method of payment in order to continue.',
-            'event_espresso'
-        );
-        EE_Registry::$i18n_js_strings['invalid_payment_method'] = esc_html__(
-            'A valid method of payment could not be determined. Please refresh the page and try again.',
-            'event_espresso'
-        );
-        EE_Registry::$i18n_js_strings['forwarding_to_offsite'] = esc_html__(
-            'Forwarding to Secure Payment Provider.',
-            'event_espresso'
-        );
-    }
-
-
-    /**
-     * enqueue_styles_and_scripts
-     *
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    public function enqueue_styles_and_scripts()
-    {
-        $transaction = $this->checkout->transaction;
-        // if the transaction isn't set or nothing is owed on it, don't enqueue any JS
-        if (! $transaction instanceof EE_Transaction || EEH_Money::compare_floats($transaction->remaining(), 0)) {
-            return;
-        }
-        foreach (EEM_Payment_Method::instance()->get_all_for_transaction(
-            $transaction,
-            EEM_Payment_Method::scope_cart
-        ) as $payment_method) {
-            $type_obj = $payment_method->type_obj();
-            if ($type_obj instanceof EE_PMT_Base) {
-                $billing_form = $type_obj->generate_new_billing_form($transaction);
-                if ($billing_form instanceof EE_Form_Section_Proper) {
-                    $billing_form->enqueue_js();
-                }
-            }
-        }
-    }
-
-
-    /**
-     * initialize_reg_step
-     *
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    public function initialize_reg_step()
-    {
-        // TODO: if /when we implement donations, then this will need overriding
-        if (// don't need payment options for:
-            // registrations made via the admin
-            // completed transactions
-            // overpaid transactions
-            // $ 0.00 transactions(no payment required)
-            ! $this->checkout->payment_required()
-            // but do NOT remove if current action being called belongs to this reg step
-            && ! is_callable(array($this, $this->checkout->action))
-            && ! $this->completed()
-        ) {
-            // and if so, then we no longer need the Payment Options step
-            if ($this->is_current_step()) {
-                $this->checkout->generate_reg_form = false;
-            }
-            $this->checkout->remove_reg_step($this->_slug);
-            // DEBUG LOG
-            // $this->checkout->log( __CLASS__, __FUNCTION__, __LINE__ );
-            return false;
-        }
-        // load EEM_Payment_Method
-        EE_Registry::instance()->load_model('Payment_Method');
-        // get all active payment methods
-        $this->checkout->available_payment_methods = EEM_Payment_Method::instance()->get_all_for_transaction(
-            $this->checkout->transaction,
-            EEM_Payment_Method::scope_cart
-        );
-        return true;
-    }
-
-
-    /**
-     * @return EE_Form_Section_Proper
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\EntityNotFoundException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     * @throws \EventEspresso\core\exceptions\InvalidStatusException
-     */
-    public function generate_reg_form()
-    {
-        // reset in case someone changes their mind
-        $this->_reset_selected_method_of_payment();
-        // set some defaults
-        $this->checkout->selected_method_of_payment = 'payments_closed';
-        $registrations_requiring_payment = array();
-        $registrations_for_free_events = array();
-        $registrations_requiring_pre_approval = array();
-        $sold_out_events = array();
-        $insufficient_spaces_available = array();
-        $no_payment_required = true;
-        // loop thru registrations to gather info
-        $registrations = $this->checkout->transaction->registrations($this->checkout->reg_cache_where_params);
-        $ejected_registrations = EE_SPCO_Reg_Step_Payment_Options::find_registrations_that_lost_their_space(
-            $registrations,
-            $this->checkout->revisit
-        );
-        foreach ($registrations as $REG_ID => $registration) {
-            /** @var $registration EE_Registration */
-            // has this registration lost it's space ?
-            if (isset($ejected_registrations[ $REG_ID ])) {
-                if ($registration->event()->is_sold_out() || $registration->event()->is_sold_out(true)) {
-                    $sold_out_events[ $registration->event()->ID() ] = $registration->event();
-                } else {
-                    $insufficient_spaces_available[ $registration->event()->ID() ] = $registration->event();
-                }
-                continue;
-            }
-            // event requires admin approval
-            if ($registration->status_ID() === EEM_Registration::status_id_not_approved) {
-                // add event to list of events with pre-approval reg status
-                $registrations_requiring_pre_approval[ $REG_ID ] = $registration;
-                do_action(
-                    'AHEE__EE_SPCO_Reg_Step_Payment_Options__generate_reg_form__event_requires_pre_approval',
-                    $registration->event(),
-                    $this
-                );
-                continue;
-            }
-            if ($this->checkout->revisit
-                && $registration->status_ID() !== EEM_Registration::status_id_approved
-                && (
-                    $registration->event()->is_sold_out()
-                    || $registration->event()->is_sold_out(true)
-                )
-            ) {
-                // add event to list of events that are sold out
-                $sold_out_events[ $registration->event()->ID() ] = $registration->event();
-                do_action(
-                    'AHEE__EE_SPCO_Reg_Step_Payment_Options__generate_reg_form__sold_out_event',
-                    $registration->event(),
-                    $this
-                );
-                continue;
-            }
-            // are they allowed to pay now and is there monies owing?
-            if ($registration->owes_monies_and_can_pay()) {
-                $registrations_requiring_payment[ $REG_ID ] = $registration;
-                do_action(
-                    'AHEE__EE_SPCO_Reg_Step_Payment_Options__generate_reg_form__event_requires_payment',
-                    $registration->event(),
-                    $this
-                );
-            } elseif (! $this->checkout->revisit
-                      && $registration->status_ID() !== EEM_Registration::status_id_not_approved
-                      && $registration->ticket()->is_free()
-            ) {
-                $registrations_for_free_events[ $registration->ticket()->ID() ] = $registration;
-            }
-        }
-        $subsections = array();
-        // now decide which template to load
-        if (! empty($sold_out_events)) {
-            $subsections['sold_out_events'] = $this->_sold_out_events($sold_out_events);
-        }
-        if (! empty($insufficient_spaces_available)) {
-            $subsections['insufficient_space'] = $this->_insufficient_spaces_available(
-                $insufficient_spaces_available
-            );
-        }
-        if (! empty($registrations_requiring_pre_approval)) {
-            $subsections['registrations_requiring_pre_approval'] = $this->_registrations_requiring_pre_approval(
-                $registrations_requiring_pre_approval
-            );
-        }
-        if (! empty($registrations_for_free_events)) {
-            $subsections['no_payment_required'] = $this->_no_payment_required($registrations_for_free_events);
-        }
-        if (! empty($registrations_requiring_payment)) {
-            if ($this->checkout->amount_owing > 0) {
-                // autoload Line_Item_Display classes
-                EEH_Autoloader::register_line_item_filter_autoloaders();
-                $line_item_filter_processor = new EE_Line_Item_Filter_Processor(
-                    apply_filters(
-                        'FHEE__SPCO__EE_Line_Item_Filter_Collection',
-                        new EE_Line_Item_Filter_Collection()
-                    ),
-                    $this->checkout->cart->get_grand_total()
-                );
-                /** @var EE_Line_Item $filtered_line_item_tree */
-                $filtered_line_item_tree = $line_item_filter_processor->process();
-                EEH_Autoloader::register_line_item_display_autoloaders();
-                $this->set_line_item_display(new EE_Line_Item_Display('spco'));
-                $subsections['payment_options'] = $this->_display_payment_options(
-                    $this->line_item_display->display_line_item(
-                        $filtered_line_item_tree,
-                        array('registrations' => $registrations)
-                    )
-                );
-                $this->checkout->amount_owing = $filtered_line_item_tree->total();
-                $this->_apply_registration_payments_to_amount_owing($registrations);
-            }
-            $no_payment_required = false;
-        } else {
-            $this->_hide_reg_step_submit_button_if_revisit();
-        }
-        $this->_save_selected_method_of_payment();
-
-        $subsections['default_hidden_inputs'] = $this->reg_step_hidden_inputs();
-        $subsections['extra_hidden_inputs'] = $this->_extra_hidden_inputs($no_payment_required);
-
-        return new EE_Form_Section_Proper(
-            array(
-                'name'            => $this->reg_form_name(),
-                'html_id'         => $this->reg_form_name(),
-                'subsections'     => $subsections,
-                'layout_strategy' => new EE_No_Layout(),
-            )
-        );
-    }
-
-
-    /**
-     * add line item filters required for this reg step
-     * these filters are applied via this line in EE_SPCO_Reg_Step_Payment_Options::set_hooks():
-     *        add_filter( 'FHEE__SPCO__EE_Line_Item_Filter_Collection', array( 'EE_SPCO_Reg_Step_Payment_Options',
-     *        'add_spco_line_item_filters' ) ); so any code that wants to use the same set of filters during the
-     *        payment options reg step, can apply these filters via the following: apply_filters(
-     *        'FHEE__SPCO__EE_Line_Item_Filter_Collection', new EE_Line_Item_Filter_Collection() ) or to an existing
-     *        filter collection by passing that instead of instantiating a new collection
-     *
-     * @param \EE_Line_Item_Filter_Collection $line_item_filter_collection
-     * @return EE_Line_Item_Filter_Collection
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\EntityNotFoundException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     * @throws \EventEspresso\core\exceptions\InvalidStatusException
-     */
-    public static function add_spco_line_item_filters(EE_Line_Item_Filter_Collection $line_item_filter_collection)
-    {
-        if (! EE_Registry::instance()->SSN instanceof EE_Session) {
-            return $line_item_filter_collection;
-        }
-        if (! EE_Registry::instance()->SSN->checkout() instanceof EE_Checkout) {
-            return $line_item_filter_collection;
-        }
-        if (! EE_Registry::instance()->SSN->checkout()->transaction instanceof EE_Transaction) {
-            return $line_item_filter_collection;
-        }
-        $line_item_filter_collection->add(
-            new EE_Billable_Line_Item_Filter(
-                EE_SPCO_Reg_Step_Payment_Options::remove_ejected_registrations(
-                    EE_Registry::instance()->SSN->checkout()->transaction->registrations(
-                        EE_Registry::instance()->SSN->checkout()->reg_cache_where_params
-                    )
-                )
-            )
-        );
-        $line_item_filter_collection->add(new EE_Non_Zero_Line_Item_Filter());
-        return $line_item_filter_collection;
-    }
-
-
-    /**
-     * remove_ejected_registrations
-     * if a registrant has lost their potential space at an event due to lack of payment,
-     * then this method removes them from the list of registrations being paid for during this request
-     *
-     * @param \EE_Registration[] $registrations
-     * @return EE_Registration[]
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\EntityNotFoundException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     * @throws \EventEspresso\core\exceptions\InvalidStatusException
-     */
-    public static function remove_ejected_registrations(array $registrations)
-    {
-        $ejected_registrations = EE_SPCO_Reg_Step_Payment_Options::find_registrations_that_lost_their_space(
-            $registrations,
-            EE_Registry::instance()->SSN->checkout()->revisit
-        );
-        foreach ($registrations as $REG_ID => $registration) {
-            // has this registration lost it's space ?
-            if (isset($ejected_registrations[ $REG_ID ])) {
-                unset($registrations[ $REG_ID ]);
-                continue;
-            }
-        }
-        return $registrations;
-    }
-
-
-    /**
-     * find_registrations_that_lost_their_space
-     * If a registrant chooses an offline payment method like Invoice,
-     * then no space is reserved for them at the event until they fully pay fo that site
-     * (unless the event's default reg status is set to APPROVED)
-     * if a registrant then later returns to pay, but the number of spaces available has been reduced due to sales,
-     * then this method will determine which registrations have lost the ability to complete the reg process.
-     *
-     * @param \EE_Registration[] $registrations
-     * @param bool               $revisit
-     * @return array
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\EntityNotFoundException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     * @throws \EventEspresso\core\exceptions\InvalidStatusException
-     */
-    public static function find_registrations_that_lost_their_space(array $registrations, $revisit = false)
-    {
-        // registrations per event
-        $event_reg_count = array();
-        // spaces left per event
-        $event_spaces_remaining = array();
-        // tickets left sorted by ID
-        $tickets_remaining = array();
-        // registrations that have lost their space
-        $ejected_registrations = array();
-        foreach ($registrations as $REG_ID => $registration) {
-            if ($registration->status_ID() === EEM_Registration::status_id_approved
-                || apply_filters(
-                    'FHEE__EE_SPCO_Reg_Step_Payment_Options__find_registrations_that_lost_their_space__allow_reg_payment',
-                    false,
-                    $registration,
-                    $revisit
-                )
-            ) {
-                continue;
-            }
-            $EVT_ID = $registration->event_ID();
-            $ticket = $registration->ticket();
-            if (! isset($tickets_remaining[ $ticket->ID() ])) {
-                $tickets_remaining[ $ticket->ID() ] = $ticket->remaining();
-            }
-            if ($tickets_remaining[ $ticket->ID() ] > 0) {
-                if (! isset($event_reg_count[ $EVT_ID ])) {
-                    $event_reg_count[ $EVT_ID ] = 0;
-                }
-                $event_reg_count[ $EVT_ID ]++;
-                if (! isset($event_spaces_remaining[ $EVT_ID ])) {
-                    $event_spaces_remaining[ $EVT_ID ] = $registration->event()->spaces_remaining_for_sale();
-                }
-            }
-            if ($revisit
-                && ($tickets_remaining[ $ticket->ID() ] === 0
-                    || $event_reg_count[ $EVT_ID ] > $event_spaces_remaining[ $EVT_ID ]
-                )
-            ) {
-                $ejected_registrations[ $REG_ID ] = $registration->event();
-                if ($registration->status_ID() !== EEM_Registration::status_id_wait_list) {
-                    /** @type EE_Registration_Processor $registration_processor */
-                    $registration_processor = EE_Registry::instance()->load_class('Registration_Processor');
-                    // at this point, we should have enough details about the registrant to consider the registration
-                    // NOT incomplete
-                    $registration_processor->manually_update_registration_status(
-                        $registration,
-                        EEM_Registration::status_id_wait_list
-                    );
-                }
-            }
-        }
-        return $ejected_registrations;
-    }
-
-
-    /**
-     * _hide_reg_step_submit_button
-     * removes the html for the reg step submit button
-     * by replacing it with an empty string via filter callback
-     *
-     * @return void
-     */
-    protected function _adjust_registration_status_if_event_old_sold()
-    {
-    }
-
-
-    /**
-     * _hide_reg_step_submit_button
-     * removes the html for the reg step submit button
-     * by replacing it with an empty string via filter callback
-     *
-     * @return void
-     */
-    protected function _hide_reg_step_submit_button_if_revisit()
-    {
-        if ($this->checkout->revisit) {
-            add_filter('FHEE__EE_SPCO_Reg_Step__reg_step_submit_button__sbmt_btn_html', '__return_empty_string');
-        }
-    }
-
-
-    /**
-     * sold_out_events
-     * displays notices regarding events that have sold out since hte registrant first signed up
-     *
-     * @param \EE_Event[] $sold_out_events_array
-     * @return \EE_Form_Section_Proper
-     * @throws \EE_Error
-     */
-    private function _sold_out_events($sold_out_events_array = array())
-    {
-        // set some defaults
-        $this->checkout->selected_method_of_payment = 'events_sold_out';
-        $sold_out_events = '';
-        foreach ($sold_out_events_array as $sold_out_event) {
-            $sold_out_events .= EEH_HTML::li(
-                EEH_HTML::span(
-                    '  ' . $sold_out_event->name(),
-                    '',
-                    'dashicons dashicons-marker ee-icon-size-16 pink-text'
-                )
-            );
-        }
-        return new EE_Form_Section_Proper(
-            array(
-                'layout_strategy' => new EE_Template_Layout(
-                    array(
-                        'layout_template_file' => SPCO_REG_STEPS_PATH
-                                                  . $this->_slug
-                                                  . DS
-                                                  . 'sold_out_events.template.php',
-                        'template_args'        => apply_filters(
-                            'FHEE__EE_SPCO_Reg_Step_Payment_Options___sold_out_events__template_args',
-                            array(
-                                'sold_out_events'     => $sold_out_events,
-                                'sold_out_events_msg' => apply_filters(
-                                    'FHEE__EE_SPCO_Reg_Step_Payment_Options___sold_out_events__sold_out_events_msg',
-                                    sprintf(
-                                        esc_html__(
-                                            'It appears that the event you were about to make a payment for has sold out since you first registered. If you have already made a partial payment towards this event, please contact the event administrator for a refund.%3$s%3$s%1$sPlease note that availability can change at any time due to cancellations, so please check back again later if registration for this event(s) is important to you.%2$s',
-                                            'event_espresso'
-                                        ),
-                                        '<strong>',
-                                        '</strong>',
-                                        '<br />'
-                                    )
-                                ),
-                            )
-                        ),
-                    )
-                ),
-            )
-        );
-    }
-
-
-    /**
-     * _insufficient_spaces_available
-     * displays notices regarding events that do not have enough remaining spaces
-     * to satisfy the current number of registrations looking to pay
-     *
-     * @param \EE_Event[] $insufficient_spaces_events_array
-     * @return \EE_Form_Section_Proper
-     * @throws \EE_Error
-     */
-    private function _insufficient_spaces_available($insufficient_spaces_events_array = array())
-    {
-        // set some defaults
-        $this->checkout->selected_method_of_payment = 'invoice';
-        $insufficient_space_events = '';
-        foreach ($insufficient_spaces_events_array as $event) {
-            if ($event instanceof EE_Event) {
-                $insufficient_space_events .= EEH_HTML::li(
-                    EEH_HTML::span(' ' . $event->name(), '', 'dashicons dashicons-marker ee-icon-size-16 pink-text')
-                );
-            }
-        }
-        return new EE_Form_Section_Proper(
-            array(
-                'subsections'     => array(
-                    'default_hidden_inputs' => $this->reg_step_hidden_inputs(),
-                    'extra_hidden_inputs'   => $this->_extra_hidden_inputs(),
-                ),
-                'layout_strategy' => new EE_Template_Layout(
-                    array(
-                        'layout_template_file' => SPCO_REG_STEPS_PATH
-                                                  . $this->_slug
-                                                  . DS
-                                                  . 'sold_out_events.template.php',
-                        'template_args'        => apply_filters(
-                            'FHEE__EE_SPCO_Reg_Step_Payment_Options___insufficient_spaces_available__template_args',
-                            array(
-                                'sold_out_events'     => $insufficient_space_events,
-                                'sold_out_events_msg' => apply_filters(
-                                    'FHEE__EE_SPCO_Reg_Step_Payment_Options___insufficient_spaces_available__insufficient_space_msg',
-                                    esc_html__(
-                                        'It appears that the event you were about to make a payment for has sold additional tickets since you first registered, and there are no longer enough spaces left to accommodate your selections. You may continue to pay and secure the available space(s) remaining, or simply cancel if you no longer wish to purchase. If you have already made a partial payment towards this event, please contact the event administrator for a refund.',
-                                        'event_espresso'
-                                    )
-                                ),
-                            )
-                        ),
-                    )
-                ),
-            )
-        );
-    }
-
-
-    /**
-     * registrations_requiring_pre_approval
-     *
-     * @param array $registrations_requiring_pre_approval
-     * @return EE_Form_Section_Proper
-     * @throws EE_Error
-     * @throws \EventEspresso\core\exceptions\EntityNotFoundException
-     */
-    private function _registrations_requiring_pre_approval($registrations_requiring_pre_approval = array())
-    {
-        $events_requiring_pre_approval = array();
-        foreach ($registrations_requiring_pre_approval as $registration) {
-            if ($registration instanceof EE_Registration && $registration->event() instanceof EE_Event) {
-                $events_requiring_pre_approval[ $registration->event()->ID() ] = EEH_HTML::li(
-                    EEH_HTML::span(
-                        '',
-                        '',
-                        'dashicons dashicons-marker ee-icon-size-16 orange-text'
-                    )
-                    . EEH_HTML::span($registration->event()->name(), '', 'orange-text')
-                );
-            }
-        }
-        return new EE_Form_Section_Proper(
-            array(
-                'layout_strategy' => new EE_Template_Layout(
-                    array(
-                        'layout_template_file' => SPCO_REG_STEPS_PATH
-                                                  . $this->_slug
-                                                  . DS
-                                                  . 'events_requiring_pre_approval.template.php', // layout_template
-                        'template_args'        => apply_filters(
-                            'FHEE__EE_SPCO_Reg_Step_Payment_Options___sold_out_events__template_args',
-                            array(
-                                'events_requiring_pre_approval'     => implode('', $events_requiring_pre_approval),
-                                'events_requiring_pre_approval_msg' => apply_filters(
-                                    'FHEE__EE_SPCO_Reg_Step_Payment_Options___events_requiring_pre_approval__events_requiring_pre_approval_msg',
-                                    esc_html__(
-                                        'The following events do not require payment at this time and will not be billed during this transaction. Billing will only occur after the attendee has been approved by the event organizer. You will be notified when your registration has been processed. If this is a free event, then no billing will occur.',
-                                        'event_espresso'
-                                    )
-                                ),
-                            )
-                        ),
-                    )
-                ),
-            )
-        );
-    }
-
-
-    /**
-     * _no_payment_required
-     *
-     * @param \EE_Event[] $registrations_for_free_events
-     * @return \EE_Form_Section_Proper
-     * @throws \EE_Error
-     */
-    private function _no_payment_required($registrations_for_free_events = array())
-    {
-        // set some defaults
-        $this->checkout->selected_method_of_payment = 'no_payment_required';
-        // generate no_payment_required form
-        return new EE_Form_Section_Proper(
-            array(
-                'layout_strategy' => new EE_Template_Layout(
-                    array(
-                        'layout_template_file' => SPCO_REG_STEPS_PATH
-                                                  . $this->_slug
-                                                  . DS
-                                                  . 'no_payment_required.template.php', // layout_template
-                        'template_args'        => apply_filters(
-                            'FHEE__EE_SPCO_Reg_Step_Payment_Options___no_payment_required__template_args',
-                            array(
-                                'revisit'                       => $this->checkout->revisit,
-                                'registrations'                 => array(),
-                                'ticket_count'                  => array(),
-                                'registrations_for_free_events' => $registrations_for_free_events,
-                                'no_payment_required_msg'       => EEH_HTML::p(
-                                    esc_html__('This is a free event, so no billing will occur.', 'event_espresso')
-                                ),
-                            )
-                        ),
-                    )
-                ),
-            )
-        );
-    }
-
-
-    /**
-     * _display_payment_options
-     *
-     * @param string $transaction_details
-     * @return EE_Form_Section_Proper
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _display_payment_options($transaction_details = '')
-    {
-        // has method_of_payment been set by no-js user?
-        $this->checkout->selected_method_of_payment = $this->_get_selected_method_of_payment();
-        // build payment options form
-        return apply_filters(
-            'FHEE__EE_SPCO_Reg_Step_Payment_Options___display_payment_options__payment_options_form',
-            new EE_Form_Section_Proper(
-                array(
-                    'subsections'     => array(
-                        'before_payment_options' => apply_filters(
-                            'FHEE__EE_SPCO_Reg_Step_Payment_Options___display_payment_options__before_payment_options',
-                            new EE_Form_Section_Proper(
-                                array('layout_strategy' => new EE_Div_Per_Section_Layout())
-                            )
-                        ),
-                        'payment_options'        => $this->_setup_payment_options(),
-                        'after_payment_options'  => apply_filters(
-                            'FHEE__EE_SPCO_Reg_Step_Payment_Options___display_payment_options__after_payment_options',
-                            new EE_Form_Section_Proper(
-                                array('layout_strategy' => new EE_Div_Per_Section_Layout())
-                            )
-                        ),
-                    ),
-                    'layout_strategy' => new EE_Template_Layout(
-                        array(
-                            'layout_template_file' => $this->_template,
-                            'template_args'        => apply_filters(
-                                'FHEE__EE_SPCO_Reg_Step_Payment_Options___display_payment_options__template_args',
-                                array(
-                                    'reg_count'                 => $this->line_item_display->total_items(),
-                                    'transaction_details'       => $transaction_details,
-                                    'available_payment_methods' => array(),
-                                )
-                            ),
-                        )
-                    ),
-                )
-            )
-        );
-    }
-
-
-    /**
-     * _extra_hidden_inputs
-     *
-     * @param bool $no_payment_required
-     * @return \EE_Form_Section_Proper
-     * @throws \EE_Error
-     */
-    private function _extra_hidden_inputs($no_payment_required = true)
-    {
-        return new EE_Form_Section_Proper(
-            array(
-                'html_id'         => 'ee-' . $this->slug() . '-extra-hidden-inputs',
-                'layout_strategy' => new EE_Div_Per_Section_Layout(),
-                'subsections'     => array(
-                    'spco_no_payment_required' => new EE_Hidden_Input(
-                        array(
-                            'normalization_strategy' => new EE_Boolean_Normalization(),
-                            'html_name'              => 'spco_no_payment_required',
-                            'html_id'                => 'spco-no-payment-required-payment_options',
-                            'default'                => $no_payment_required,
-                        )
-                    ),
-                    'spco_transaction_id'      => new EE_Fixed_Hidden_Input(
-                        array(
-                            'normalization_strategy' => new EE_Int_Normalization(),
-                            'html_name'              => 'spco_transaction_id',
-                            'html_id'                => 'spco-transaction-id',
-                            'default'                => $this->checkout->transaction->ID(),
-                        )
-                    ),
-                ),
-            )
-        );
-    }
-
-
-    /**
-     *    _apply_registration_payments_to_amount_owing
-     *
-     * @access protected
-     * @param array $registrations
-     * @throws EE_Error
-     */
-    protected function _apply_registration_payments_to_amount_owing(array $registrations)
-    {
-        $payments = array();
-        foreach ($registrations as $registration) {
-            if ($registration instanceof EE_Registration && $registration->owes_monies_and_can_pay()) {
-                $payments += $registration->registration_payments();
-            }
-        }
-        if (! empty($payments)) {
-            foreach ($payments as $payment) {
-                if ($payment instanceof EE_Registration_Payment) {
-                    $this->checkout->amount_owing -= $payment->amount();
-                }
-            }
-        }
-    }
-
-
-    /**
-     *    _reset_selected_method_of_payment
-     *
-     * @access    private
-     * @param    bool $force_reset
-     * @return void
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _reset_selected_method_of_payment($force_reset = false)
-    {
-        $reset_payment_method = $force_reset
-            ? true
-            : sanitize_text_field(EE_Registry::instance()->REQ->get('reset_payment_method', false));
-        if ($reset_payment_method) {
-            $this->checkout->selected_method_of_payment = null;
-            $this->checkout->payment_method = null;
-            $this->checkout->billing_form = null;
-            $this->_save_selected_method_of_payment();
-        }
-    }
-
-
-    /**
-     * _save_selected_method_of_payment
-     * stores the selected_method_of_payment in the session
-     * so that it's available for all subsequent requests including AJAX
-     *
-     * @access        private
-     * @param string $selected_method_of_payment
-     * @return void
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _save_selected_method_of_payment($selected_method_of_payment = '')
-    {
-        $selected_method_of_payment = ! empty($selected_method_of_payment)
-            ? $selected_method_of_payment
-            : $this->checkout->selected_method_of_payment;
-        EE_Registry::instance()->SSN->set_session_data(
-            array('selected_method_of_payment' => $selected_method_of_payment)
-        );
-    }
-
-
-    /**
-     * _setup_payment_options
-     *
-     * @return EE_Form_Section_Proper
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    public function _setup_payment_options()
-    {
-        // load payment method classes
-        $this->checkout->available_payment_methods = $this->_get_available_payment_methods();
-        if (empty($this->checkout->available_payment_methods)) {
-            EE_Error::add_error(
-                apply_filters(
-                    'FHEE__EE_SPCO_Reg_Step_Payment_Options___setup_payment_options__error_message_no_payment_methods',
-                    sprintf(
-                        esc_html__(
-                            'Sorry, you cannot complete your purchase because a payment method is not active.%1$s Please contact %2$s for assistance and provide a description of the problem.',
-                            'event_espresso'
-                        ),
-                        '<br>',
-                        EE_Registry::instance()->CFG->organization->get_pretty('email')
-                    )
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-        }
-        // switch up header depending on number of available payment methods
-        $payment_method_header = count($this->checkout->available_payment_methods) > 1
-            ? apply_filters(
-                'FHEE__registration_page_payment_options__method_of_payment_hdr',
-                esc_html__('Please Select Your Method of Payment', 'event_espresso')
-            )
-            : apply_filters(
-                'FHEE__registration_page_payment_options__method_of_payment_hdr',
-                esc_html__('Method of Payment', 'event_espresso')
-            );
-        $available_payment_methods = array(
-            // display the "Payment Method" header
-            'payment_method_header' => new EE_Form_Section_HTML(
-                apply_filters(
-                    'FHEE__EE_SPCO_Reg_Step_Payment_Options___setup_payment_options__payment_method_header',
-                    EEH_HTML::h4($payment_method_header, 'method-of-payment-hdr'),
-                    $payment_method_header
-                )
-            ),
-        );
-        // the list of actual payment methods ( invoice, paypal, etc ) in a  ( slug => HTML )  format
-        $available_payment_method_options = array();
-        $default_payment_method_option = array();
-        // additional instructions to be displayed and hidden below payment methods (adding a clearing div to start)
-        $payment_methods_billing_info = array(
-            new EE_Form_Section_HTML(
-                EEH_HTML::div('<br />', '', '', 'clear:both;')
-            ),
-        );
-        // loop through payment methods
-        foreach ($this->checkout->available_payment_methods as $payment_method) {
-            if ($payment_method instanceof EE_Payment_Method) {
-                $payment_method_button = EEH_HTML::img(
-                    $payment_method->button_url(),
-                    $payment_method->name(),
-                    'spco-payment-method-' . $payment_method->slug() . '-btn-img',
-                    'spco-payment-method-btn-img'
-                );
-                // check if any payment methods are set as default
-                // if payment method is already selected OR nothing is selected and this payment method should be
-                // open_by_default
-                if (($this->checkout->selected_method_of_payment === $payment_method->slug())
-                    || (! $this->checkout->selected_method_of_payment && $payment_method->open_by_default())
-                ) {
-                    $this->checkout->selected_method_of_payment = $payment_method->slug();
-                    $this->_save_selected_method_of_payment();
-                    $default_payment_method_option[ $payment_method->slug() ] = $payment_method_button;
-                } else {
-                    $available_payment_method_options[ $payment_method->slug() ] = $payment_method_button;
-                }
-                $payment_methods_billing_info[ $payment_method->slug(
-                ) . '-info' ] = $this->_payment_method_billing_info(
-                    $payment_method
-                );
-            }
-        }
-        // prepend available_payment_method_options with default_payment_method_option so that it appears first in list
-        // of PMs
-        $available_payment_method_options = $default_payment_method_option + $available_payment_method_options;
-        // now generate the actual form  inputs
-        $available_payment_methods['available_payment_methods'] = $this->_available_payment_method_inputs(
-            $available_payment_method_options
-        );
-        $available_payment_methods += $payment_methods_billing_info;
-        // build the available payment methods form
-        return new EE_Form_Section_Proper(
-            array(
-                'html_id'         => 'spco-available-methods-of-payment-dv',
-                'subsections'     => $available_payment_methods,
-                'layout_strategy' => new EE_Div_Per_Section_Layout(),
-            )
-        );
-    }
-
-
-    /**
-     * _get_available_payment_methods
-     *
-     * @return EE_Payment_Method[]
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    protected function _get_available_payment_methods()
-    {
-        if (! empty($this->checkout->available_payment_methods)) {
-            return $this->checkout->available_payment_methods;
-        }
-        $available_payment_methods = array();
-        // load EEM_Payment_Method
-        EE_Registry::instance()->load_model('Payment_Method');
-        /** @type EEM_Payment_Method $EEM_Payment_Method */
-        $EEM_Payment_Method = EE_Registry::instance()->LIB->EEM_Payment_Method;
-        // get all active payment methods
-        $payment_methods = $EEM_Payment_Method->get_all_for_transaction(
-            $this->checkout->transaction,
-            EEM_Payment_Method::scope_cart
-        );
-        foreach ($payment_methods as $payment_method) {
-            if ($payment_method instanceof EE_Payment_Method) {
-                $available_payment_methods[ $payment_method->slug() ] = $payment_method;
-            }
-        }
-        return $available_payment_methods;
-    }
-
-
-    /**
-     *    _available_payment_method_inputs
-     *
-     * @access    private
-     * @param    array $available_payment_method_options
-     * @return    \EE_Form_Section_Proper
-     */
-    private function _available_payment_method_inputs($available_payment_method_options = array())
-    {
-        // generate inputs
-        return new EE_Form_Section_Proper(
-            array(
-                'html_id'         => 'ee-available-payment-method-inputs',
-                'layout_strategy' => new EE_Div_Per_Section_Layout(),
-                'subsections'     => array(
-                    '' => new EE_Radio_Button_Input(
-                        $available_payment_method_options,
-                        array(
-                            'html_name'          => 'selected_method_of_payment',
-                            'html_class'         => 'spco-payment-method',
-                            'default'            => $this->checkout->selected_method_of_payment,
-                            'label_size'         => 11,
-                            'enforce_label_size' => true,
-                        )
-                    ),
-                ),
-            )
-        );
-    }
-
-
-    /**
-     *    _payment_method_billing_info
-     *
-     * @access    private
-     * @param    EE_Payment_Method $payment_method
-     * @return EE_Form_Section_Proper
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _payment_method_billing_info(EE_Payment_Method $payment_method)
-    {
-        $currently_selected = $this->checkout->selected_method_of_payment === $payment_method->slug()
-            ? true
-            : false;
-        // generate the billing form for payment method
-        $billing_form = $currently_selected
-            ? $this->_get_billing_form_for_payment_method($payment_method)
-            : new EE_Form_Section_HTML();
-        $this->checkout->billing_form = $currently_selected
-            ? $billing_form
-            : $this->checkout->billing_form;
-        // it's all in the details
-        $info_html = EEH_HTML::h3(
-            esc_html__('Important information regarding your payment', 'event_espresso'),
-            '',
-            'spco-payment-method-hdr'
-        );
-        // add some info regarding the step, either from what's saved in the admin,
-        // or a default string depending on whether the PM has a billing form or not
-        if ($payment_method->description()) {
-            $payment_method_info = $payment_method->description();
-        } elseif ($billing_form instanceof EE_Billing_Info_Form) {
-            $payment_method_info = sprintf(
-                esc_html__(
-                    'Please provide the following billing information, then click the "%1$s" button below in order to proceed.',
-                    'event_espresso'
-                ),
-                $this->submit_button_text()
-            );
-        } else {
-            $payment_method_info = sprintf(
-                esc_html__('Please click the "%1$s" button below in order to proceed.', 'event_espresso'),
-                $this->submit_button_text()
-            );
-        }
-        $info_html .= EEH_HTML::div(
-            apply_filters(
-                'FHEE__EE_SPCO_Reg_Step_Payment_Options___payment_method_billing_info__payment_method_info',
-                $payment_method_info
-            ),
-            '',
-            'spco-payment-method-desc ee-attention'
-        );
-        return new EE_Form_Section_Proper(
-            array(
-                'html_id'         => 'spco-payment-method-info-' . $payment_method->slug(),
-                'html_class'      => 'spco-payment-method-info-dv',
-                // only display the selected or default PM
-                'html_style'      => $currently_selected ? '' : 'display:none;',
-                'layout_strategy' => new EE_Div_Per_Section_Layout(),
-                'subsections'     => array(
-                    'info'         => new EE_Form_Section_HTML($info_html),
-                    'billing_form' => $currently_selected ? $billing_form : new EE_Form_Section_HTML(),
-                ),
-            )
-        );
-    }
-
-
-    /**
-     * get_billing_form_html_for_payment_method
-     *
-     * @access public
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    public function get_billing_form_html_for_payment_method()
-    {
-        // how have they chosen to pay?
-        $this->checkout->selected_method_of_payment = $this->_get_selected_method_of_payment(true);
-        $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment();
-        if (! $this->checkout->payment_method instanceof EE_Payment_Method) {
-            return false;
-        }
-        if (apply_filters(
-            'FHEE__EE_SPCO_Reg_Step_Payment_Options__registration_checkout__selected_payment_method__display_success',
-            false
-        )) {
-            EE_Error::add_success(
-                apply_filters(
-                    'FHEE__Single_Page_Checkout__registration_checkout__selected_payment_method',
-                    sprintf(
-                        esc_html__(
-                            'You have selected "%s" as your method of payment. Please note the important payment information below.',
-                            'event_espresso'
-                        ),
-                        $this->checkout->payment_method->name()
-                    )
-                )
-            );
-        }
-        // now generate billing form for selected method of payment
-        $payment_method_billing_form = $this->_get_billing_form_for_payment_method($this->checkout->payment_method);
-        // fill form with attendee info if applicable
-        if ($payment_method_billing_form instanceof EE_Billing_Attendee_Info_Form
-            && $this->checkout->transaction_has_primary_registrant()
-        ) {
-            $payment_method_billing_form->populate_from_attendee(
-                $this->checkout->transaction->primary_registration()->attendee()
-            );
-        }
-        // and debug content
-        if ($payment_method_billing_form instanceof EE_Billing_Info_Form
-            && $this->checkout->payment_method->type_obj() instanceof EE_PMT_Base
-        ) {
-            $payment_method_billing_form =
-                $this->checkout->payment_method->type_obj()->apply_billing_form_debug_settings(
-                    $payment_method_billing_form
-                );
-        }
-        $billing_info = $payment_method_billing_form instanceof EE_Form_Section_Proper
-            ? $payment_method_billing_form->get_html()
-            : '';
-        $this->checkout->json_response->set_return_data(array('payment_method_info' => $billing_info));
-        // localize validation rules for main form
-        $this->checkout->current_step->reg_form->localize_validation_rules();
-        $this->checkout->json_response->add_validation_rules(EE_Form_Section_Proper::js_localization());
-        return true;
-    }
-
-
-    /**
-     * _get_billing_form_for_payment_method
-     *
-     * @access private
-     * @param EE_Payment_Method $payment_method
-     * @return EE_Billing_Info_Form|EE_Form_Section_HTML
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _get_billing_form_for_payment_method(EE_Payment_Method $payment_method)
-    {
-        $billing_form = $payment_method->type_obj()->billing_form(
-            $this->checkout->transaction,
-            array('amount_owing' => $this->checkout->amount_owing)
-        );
-        if ($billing_form instanceof EE_Billing_Info_Form) {
-            if (apply_filters(
-                'FHEE__EE_SPCO_Reg_Step_Payment_Options__registration_checkout__selected_payment_method__display_success',
-                false
-            )
-                && EE_Registry::instance()->REQ->is_set('payment_method')
-            ) {
-                EE_Error::add_success(
-                    apply_filters(
-                        'FHEE__Single_Page_Checkout__registration_checkout__selected_payment_method',
-                        sprintf(
-                            esc_html__(
-                                'You have selected "%s" as your method of payment. Please note the important payment information below.',
-                                'event_espresso'
-                            ),
-                            $payment_method->name()
-                        )
-                    )
-                );
-            }
-            return apply_filters(
-                'FHEE__EE_SPCO_Reg_Step_Payment_Options___get_billing_form_for_payment_method__billing_form',
-                $billing_form,
-                $payment_method
-            );
-        }
-        // no actual billing form, so return empty HTML form section
-        return new EE_Form_Section_HTML();
-    }
-
-
-    /**
-     * _get_selected_method_of_payment
-     *
-     * @access private
-     * @param boolean $required whether to throw an error if the "selected_method_of_payment"
-     *                          is not found in the incoming request
-     * @param string  $request_param
-     * @return NULL|string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _get_selected_method_of_payment(
-        $required = false,
-        $request_param = 'selected_method_of_payment'
-    ) {
-        // is selected_method_of_payment set in the request ?
-        $selected_method_of_payment = EE_Registry::instance()->REQ->get($request_param, false);
-        if ($selected_method_of_payment) {
-            // sanitize it
-            $selected_method_of_payment = is_array($selected_method_of_payment)
-                ? array_shift($selected_method_of_payment)
-                : $selected_method_of_payment;
-            $selected_method_of_payment = sanitize_text_field($selected_method_of_payment);
-            // store it in the session so that it's available for all subsequent requests including AJAX
-            $this->_save_selected_method_of_payment($selected_method_of_payment);
-        } else {
-            // or is is set in the session ?
-            $selected_method_of_payment = EE_Registry::instance()->SSN->get_session_data(
-                'selected_method_of_payment'
-            );
-        }
-        // do ya really really gotta have it?
-        if (empty($selected_method_of_payment) && $required) {
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'The selected method of payment could not be determined.%sPlease ensure that you have selected one before proceeding.%sIf you continue to experience difficulties, then refresh your browser and try again, or contact %s for assistance.',
-                        'event_espresso'
-                    ),
-                    '<br/>',
-                    '<br/>',
-                    EE_Registry::instance()->CFG->organization->get_pretty('email')
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return null;
-        }
-        return $selected_method_of_payment;
-    }
-
-
-
-
-
-
-    /********************************************************************************************************/
-    /***********************************  SWITCH PAYMENT METHOD  ************************************/
-    /********************************************************************************************************/
-    /**
-     * switch_payment_method
-     *
-     * @access public
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    public function switch_payment_method()
-    {
-        if (! $this->_verify_payment_method_is_set()) {
-            return false;
-        }
-        if (apply_filters(
-            'FHEE__EE_SPCO_Reg_Step_Payment_Options__registration_checkout__selected_payment_method__display_success',
-            false
-        )) {
-            EE_Error::add_success(
-                apply_filters(
-                    'FHEE__Single_Page_Checkout__registration_checkout__selected_payment_method',
-                    sprintf(
-                        esc_html__(
-                            'You have selected "%s" as your method of payment. Please note the important payment information below.',
-                            'event_espresso'
-                        ),
-                        $this->checkout->payment_method->name()
-                    )
-                )
-            );
-        }
-        // generate billing form for selected method of payment if it hasn't been done already
-        if ($this->checkout->payment_method->type_obj()->has_billing_form()) {
-            $this->checkout->billing_form = $this->_get_billing_form_for_payment_method(
-                $this->checkout->payment_method
-            );
-        }
-        // fill form with attendee info if applicable
-        if (apply_filters(
-            'FHEE__populate_billing_form_fields_from_attendee',
-            (
-                $this->checkout->billing_form instanceof EE_Billing_Attendee_Info_Form
-                && $this->checkout->transaction_has_primary_registrant()
-            ),
-            $this->checkout->billing_form,
-            $this->checkout->transaction
-        )
-        ) {
-            $this->checkout->billing_form->populate_from_attendee(
-                $this->checkout->transaction->primary_registration()->attendee()
-            );
-        }
-        // and debug content
-        if ($this->checkout->billing_form instanceof EE_Billing_Info_Form
-            && $this->checkout->payment_method->type_obj() instanceof EE_PMT_Base
-        ) {
-            $this->checkout->billing_form =
-                $this->checkout->payment_method->type_obj()->apply_billing_form_debug_settings(
-                    $this->checkout->billing_form
-                );
-        }
-        // get html and validation rules for form
-        if ($this->checkout->billing_form instanceof EE_Form_Section_Proper) {
-            $this->checkout->json_response->set_return_data(
-                array('payment_method_info' => $this->checkout->billing_form->get_html())
-            );
-            // localize validation rules for main form
-            $this->checkout->billing_form->localize_validation_rules(true);
-            $this->checkout->json_response->add_validation_rules(EE_Form_Section_Proper::js_localization());
-        } else {
-            $this->checkout->json_response->set_return_data(array('payment_method_info' => ''));
-        }
-        // prevents advancement to next step
-        $this->checkout->continue_reg = false;
-        return true;
-    }
-
-
-    /**
-     * _verify_payment_method_is_set
-     *
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    protected function _verify_payment_method_is_set()
-    {
-        // generate billing form for selected method of payment if it hasn't been done already
-        if (empty($this->checkout->selected_method_of_payment)) {
-            // how have they chosen to pay?
-            $this->checkout->selected_method_of_payment = $this->_get_selected_method_of_payment(true);
-        } else {
-            // choose your own adventure based on method_of_payment
-            switch ($this->checkout->selected_method_of_payment) {
-                case 'events_sold_out':
-                    EE_Error::add_attention(
-                        apply_filters(
-                            'FHEE__EE_SPCO_Reg_Step_Payment_Options___verify_payment_method_is_set__sold_out_events_msg',
-                            esc_html__(
-                                'It appears that the event you were about to make a payment for has sold out since this form first loaded. Please contact the event administrator if you believe this is an error.',
-                                'event_espresso'
-                            )
-                        ),
-                        __FILE__,
-                        __FUNCTION__,
-                        __LINE__
-                    );
-                    return false;
-                    break;
-                case 'payments_closed':
-                    EE_Error::add_attention(
-                        apply_filters(
-                            'FHEE__EE_SPCO_Reg_Step_Payment_Options___verify_payment_method_is_set__payments_closed_msg',
-                            esc_html__(
-                                'It appears that the event you were about to make a payment for is not accepting payments at this time. Please contact the event administrator if you believe this is an error.',
-                                'event_espresso'
-                            )
-                        ),
-                        __FILE__,
-                        __FUNCTION__,
-                        __LINE__
-                    );
-                    return false;
-                    break;
-                case 'no_payment_required':
-                    EE_Error::add_attention(
-                        apply_filters(
-                            'FHEE__EE_SPCO_Reg_Step_Payment_Options___verify_payment_method_is_set__no_payment_required_msg',
-                            esc_html__(
-                                'It appears that the event you were about to make a payment for does not require payment. Please contact the event administrator if you believe this is an error.',
-                                'event_espresso'
-                            )
-                        ),
-                        __FILE__,
-                        __FUNCTION__,
-                        __LINE__
-                    );
-                    return false;
-                    break;
-                default:
-            }
-        }
-        // verify payment method
-        if (! $this->checkout->payment_method instanceof EE_Payment_Method) {
-            // get payment method for selected method of payment
-            $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment();
-        }
-        return $this->checkout->payment_method instanceof EE_Payment_Method ? true : false;
-    }
-
-
-
-    /********************************************************************************************************/
-    /***************************************  SAVE PAYER DETAILS  ****************************************/
-    /********************************************************************************************************/
-    /**
-     * save_payer_details_via_ajax
-     *
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws RuntimeException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    public function save_payer_details_via_ajax()
-    {
-        if (! $this->_verify_payment_method_is_set()) {
-            return;
-        }
-        // generate billing form for selected method of payment if it hasn't been done already
-        if ($this->checkout->payment_method->type_obj()->has_billing_form()) {
-            $this->checkout->billing_form = $this->_get_billing_form_for_payment_method(
-                $this->checkout->payment_method
-            );
-        }
-        // generate primary attendee from payer info if applicable
-        if (! $this->checkout->transaction_has_primary_registrant()) {
-            $attendee = $this->_create_attendee_from_request_data();
-            if ($attendee instanceof EE_Attendee) {
-                foreach ($this->checkout->transaction->registrations() as $registration) {
-                    if ($registration->is_primary_registrant()) {
-                        $this->checkout->primary_attendee_obj = $attendee;
-                        $registration->_add_relation_to($attendee, 'Attendee');
-                        $registration->set_attendee_id($attendee->ID());
-                        $registration->update_cache_after_object_save('Attendee', $attendee);
-                    }
-                }
-            }
-        }
-    }
-
-
-    /**
-     * create_attendee_from_request_data
-     * uses info from alternate GET or POST data (such as AJAX) to create a new attendee
-     *
-     * @return EE_Attendee
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    protected function _create_attendee_from_request_data()
-    {
-        // get State ID
-        $STA_ID = ! empty($_REQUEST['state']) ? sanitize_text_field($_REQUEST['state']) : '';
-        if (! empty($STA_ID)) {
-            // can we get state object from name ?
-            EE_Registry::instance()->load_model('State');
-            $state = EEM_State::instance()->get_col(array(array('STA_name' => $STA_ID), 'limit' => 1), 'STA_ID');
-            $STA_ID = is_array($state) && ! empty($state) ? reset($state) : $STA_ID;
-        }
-        // get Country ISO
-        $CNT_ISO = ! empty($_REQUEST['country']) ? sanitize_text_field($_REQUEST['country']) : '';
-        if (! empty($CNT_ISO)) {
-            // can we get country object from name ?
-            EE_Registry::instance()->load_model('Country');
-            $country = EEM_Country::instance()->get_col(
-                array(array('CNT_name' => $CNT_ISO), 'limit' => 1),
-                'CNT_ISO'
-            );
-            $CNT_ISO = is_array($country) && ! empty($country) ? reset($country) : $CNT_ISO;
-        }
-        // grab attendee data
-        $attendee_data = array(
-            'ATT_fname'    => ! empty($_REQUEST['first_name']) ? sanitize_text_field($_REQUEST['first_name']) : '',
-            'ATT_lname'    => ! empty($_REQUEST['last_name']) ? sanitize_text_field($_REQUEST['last_name']) : '',
-            'ATT_email'    => ! empty($_REQUEST['email']) ? sanitize_email($_REQUEST['email']) : '',
-            'ATT_address'  => ! empty($_REQUEST['address']) ? sanitize_text_field($_REQUEST['address']) : '',
-            'ATT_address2' => ! empty($_REQUEST['address2']) ? sanitize_text_field($_REQUEST['address2']) : '',
-            'ATT_city'     => ! empty($_REQUEST['city']) ? sanitize_text_field($_REQUEST['city']) : '',
-            'STA_ID'       => $STA_ID,
-            'CNT_ISO'      => $CNT_ISO,
-            'ATT_zip'      => ! empty($_REQUEST['zip']) ? sanitize_text_field($_REQUEST['zip']) : '',
-            'ATT_phone'    => ! empty($_REQUEST['phone']) ? sanitize_text_field($_REQUEST['phone']) : '',
-        );
-        // validate the email address since it is the most important piece of info
-        if (empty($attendee_data['ATT_email']) || $attendee_data['ATT_email'] !== $_REQUEST['email']) {
-            EE_Error::add_error(
-                esc_html__('An invalid email address was submitted.', 'event_espresso'),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-        }
-        // does this attendee already exist in the db ? we're searching using a combination of first name, last name,
-        // AND email address
-        if (! empty($attendee_data['ATT_fname'])
-            && ! empty($attendee_data['ATT_lname'])
-            && ! empty($attendee_data['ATT_email'])
-        ) {
-            $existing_attendee = EE_Registry::instance()->LIB->EEM_Attendee->find_existing_attendee(
-                array(
-                    'ATT_fname' => $attendee_data['ATT_fname'],
-                    'ATT_lname' => $attendee_data['ATT_lname'],
-                    'ATT_email' => $attendee_data['ATT_email'],
-                )
-            );
-            if ($existing_attendee instanceof EE_Attendee) {
-                return $existing_attendee;
-            }
-        }
-        // no existing attendee? kk let's create a new one
-        // kinda lame, but we need a first and last name to create an attendee, so use the email address if those
-        // don't exist
-        $attendee_data['ATT_fname'] = ! empty($attendee_data['ATT_fname'])
-            ? $attendee_data['ATT_fname']
-            : $attendee_data['ATT_email'];
-        $attendee_data['ATT_lname'] = ! empty($attendee_data['ATT_lname'])
-            ? $attendee_data['ATT_lname']
-            : $attendee_data['ATT_email'];
-        return EE_Attendee::new_instance($attendee_data);
-    }
-
-
-
-    /********************************************************************************************************/
-    /****************************************  PROCESS REG STEP  *****************************************/
-    /********************************************************************************************************/
-    /**
-     * process_reg_step
-     *
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\EntityNotFoundException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     * @throws \EventEspresso\core\exceptions\InvalidStatusException
-     */
-    public function process_reg_step()
-    {
-        // how have they chosen to pay?
-        $this->checkout->selected_method_of_payment = $this->checkout->transaction->is_free()
-            ? 'no_payment_required'
-            : $this->_get_selected_method_of_payment(true);
-        // choose your own adventure based on method_of_payment
-        switch ($this->checkout->selected_method_of_payment) {
-            case 'events_sold_out':
-                $this->checkout->redirect = true;
-                $this->checkout->redirect_url = $this->checkout->cancel_page_url;
-                $this->checkout->json_response->set_redirect_url($this->checkout->redirect_url);
-                // mark this reg step as completed
-                $this->set_completed();
-                return false;
-                break;
-
-            case 'payments_closed':
-                if (apply_filters(
-                    'FHEE__EE_SPCO_Reg_Step_Payment_Options__process_reg_step__payments_closed__display_success',
-                    false
-                )) {
-                    EE_Error::add_success(
-                        esc_html__('no payment required at this time.', 'event_espresso'),
-                        __FILE__,
-                        __FUNCTION__,
-                        __LINE__
-                    );
-                }
-                // mark this reg step as completed
-                $this->set_completed();
-                return true;
-                break;
-
-            case 'no_payment_required':
-                if (apply_filters(
-                    'FHEE__EE_SPCO_Reg_Step_Payment_Options__process_reg_step__no_payment_required__display_success',
-                    false
-                )) {
-                    EE_Error::add_success(
-                        esc_html__('no payment required.', 'event_espresso'),
-                        __FILE__,
-                        __FUNCTION__,
-                        __LINE__
-                    );
-                }
-                // mark this reg step as completed
-                $this->set_completed();
-                return true;
-                break;
-
-            default:
-                $registrations = EE_Registry::instance()->SSN->checkout()->transaction->registrations(
-                    EE_Registry::instance()->SSN->checkout()->reg_cache_where_params
-                );
-                $ejected_registrations = EE_SPCO_Reg_Step_Payment_Options::find_registrations_that_lost_their_space(
-                    $registrations,
-                    EE_Registry::instance()->SSN->checkout()->revisit
-                );
-                // calculate difference between the two arrays
-                $registrations = array_diff($registrations, $ejected_registrations);
-                if (empty($registrations)) {
-                    $this->_redirect_because_event_sold_out();
-                    return false;
-                }
-                $payment_successful = $this->_process_payment();
-                if ($payment_successful) {
-                    $this->checkout->continue_reg = true;
-                    $this->_maybe_set_completed($this->checkout->payment_method);
-                } else {
-                    $this->checkout->continue_reg = false;
-                }
-                return $payment_successful;
-        }
-    }
-
-
-    /**
-     * _redirect_because_event_sold_out
-     *
-     * @access protected
-     * @return void
-     */
-    protected function _redirect_because_event_sold_out()
-    {
-        $this->checkout->continue_reg = false;
-        // set redirect URL
-        $this->checkout->redirect_url = add_query_arg(
-            array('e_reg_url_link' => $this->checkout->reg_url_link),
-            $this->checkout->current_step->reg_step_url()
-        );
-        $this->checkout->json_response->set_redirect_url($this->checkout->redirect_url);
-    }
-
-
-    /**
-     * _maybe_set_completed
-     *
-     * @access protected
-     * @param \EE_Payment_Method $payment_method
-     * @return void
-     * @throws \EE_Error
-     */
-    protected function _maybe_set_completed(EE_Payment_Method $payment_method)
-    {
-        switch ($payment_method->type_obj()->payment_occurs()) {
-            case EE_PMT_Base::offsite:
-                break;
-            case EE_PMT_Base::onsite:
-            case EE_PMT_Base::offline:
-                // mark this reg step as completed
-                $this->set_completed();
-                break;
-        }
-    }
-
-
-    /**
-     *    update_reg_step
-     *    this is the final step after a user  revisits the site to retry a payment
-     *
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\EntityNotFoundException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     * @throws \EventEspresso\core\exceptions\InvalidStatusException
-     */
-    public function update_reg_step()
-    {
-        $success = true;
-        // if payment required
-        if ($this->checkout->transaction->total() > 0) {
-            do_action(
-                'AHEE__EE_Single_Page_Checkout__process_finalize_registration__before_gateway',
-                $this->checkout->transaction
-            );
-            // attempt payment via payment method
-            $success = $this->process_reg_step();
-        }
-        if ($success && ! $this->checkout->redirect) {
-            $this->checkout->cart->get_grand_total()->save_this_and_descendants_to_txn(
-                $this->checkout->transaction->ID()
-            );
-            // set return URL
-            $this->checkout->redirect_url = add_query_arg(
-                array('e_reg_url_link' => $this->checkout->reg_url_link),
-                $this->checkout->thank_you_page_url
-            );
-        }
-        return $success;
-    }
-
-
-    /**
-     *    _process_payment
-     *
-     * @access private
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws RuntimeException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _process_payment()
-    {
-        // basically confirm that the event hasn't sold out since they hit the page
-        if (! $this->_last_second_ticket_verifications()) {
-            return false;
-        }
-        // ya gotta make a choice man
-        if (empty($this->checkout->selected_method_of_payment)) {
-            $this->checkout->json_response->set_plz_select_method_of_payment(
-                esc_html__('Please select a method of payment before proceeding.', 'event_espresso')
-            );
-            return false;
-        }
-        // get EE_Payment_Method object
-        if (! $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment()) {
-            return false;
-        }
-        // setup billing form
-        if ($this->checkout->payment_method->is_on_site()) {
-            $this->checkout->billing_form = $this->_get_billing_form_for_payment_method(
-                $this->checkout->payment_method
-            );
-            // bad billing form ?
-            if (! $this->_billing_form_is_valid()) {
-                return false;
-            }
-        }
-        // ensure primary registrant has been fully processed
-        if (! $this->_setup_primary_registrant_prior_to_payment()) {
-            return false;
-        }
-        // if session is close to expiring (under 10 minutes by default)
-        if ((time() - EE_Registry::instance()->SSN->expiration()) < EE_Registry::instance()->SSN->extension()) {
-            // add some time to session expiration so that payment can be completed
-            EE_Registry::instance()->SSN->extend_expiration();
-        }
-        /** @type EE_Transaction_Processor $transaction_processor */
-        // $transaction_processor = EE_Registry::instance()->load_class( 'Transaction_Processor' );
-        // in case a registrant leaves to an Off-Site Gateway and never returns, we want to approve any registrations
-        // for events with a default reg status of Approved
-        // $transaction_processor->toggle_registration_statuses_for_default_approved_events(
-        //      $this->checkout->transaction, $this->checkout->reg_cache_where_params
-        // );
-        // attempt payment
-        $payment = $this->_attempt_payment($this->checkout->payment_method);
-        // process results
-        $payment = $this->_validate_payment($payment);
-        $payment = $this->_post_payment_processing($payment);
-        // verify payment
-        if ($payment instanceof EE_Payment) {
-            // store that for later
-            $this->checkout->payment = $payment;
-            // we can also consider the TXN to not have been failed, so temporarily upgrade it's status to abandoned
-            $this->checkout->transaction->toggle_failed_transaction_status();
-            $payment_status = $payment->status();
-            if ($payment_status === EEM_Payment::status_id_approved
-                || $payment_status === EEM_Payment::status_id_pending
-            ) {
-                return true;
-            } else {
-                return false;
-            }
-        } elseif ($payment === true) {
-            // please note that offline payment methods will NOT make a payment,
-            // but instead just mark themselves as the PMD_ID on the transaction, and return true
-            $this->checkout->payment = $payment;
-            return true;
-        }
-        // where's my money?
-        return false;
-    }
-
-
-    /**
-     * _last_second_ticket_verifications
-     *
-     * @access public
-     * @return bool
-     * @throws EE_Error
-     */
-    protected function _last_second_ticket_verifications()
-    {
-        // don't bother re-validating if not a return visit
-        if (! $this->checkout->revisit) {
-            return true;
-        }
-        $registrations = $this->checkout->transaction->registrations();
-        if (empty($registrations)) {
-            return false;
-        }
-        foreach ($registrations as $registration) {
-            if ($registration instanceof EE_Registration && ! $registration->is_approved()) {
-                $event = $registration->event_obj();
-                if ($event instanceof EE_Event && $event->is_sold_out(true)) {
-                    EE_Error::add_error(
-                        apply_filters(
-                            'FHEE__EE_SPCO_Reg_Step_Payment_Options___last_second_ticket_verifications__sold_out_events_msg',
-                            sprintf(
-                                esc_html__(
-                                    'It appears that the %1$s event that you were about to make a payment for has sold out since you first registered and/or arrived at this page. Please refresh the page and try again. If you have already made a partial payment towards this event, please contact the event administrator for a refund.',
-                                    'event_espresso'
-                                ),
-                                $event->name()
-                            )
-                        ),
-                        __FILE__,
-                        __FUNCTION__,
-                        __LINE__
-                    );
-                    return false;
-                }
-            }
-        }
-        return true;
-    }
-
-
-    /**
-     * redirect_form
-     *
-     * @access public
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    public function redirect_form()
-    {
-        $payment_method_billing_info = $this->_payment_method_billing_info(
-            $this->_get_payment_method_for_selected_method_of_payment()
-        );
-        $html = $payment_method_billing_info->get_html();
-        $html .= $this->checkout->redirect_form;
-        EE_Registry::instance()->REQ->add_output($html);
-        return true;
-    }
-
-
-    /**
-     * _billing_form_is_valid
-     *
-     * @access private
-     * @return bool
-     * @throws \EE_Error
-     */
-    private function _billing_form_is_valid()
-    {
-        if (! $this->checkout->payment_method->type_obj()->has_billing_form()) {
-            return true;
-        }
-        if ($this->checkout->billing_form instanceof EE_Billing_Info_Form) {
-            if ($this->checkout->billing_form->was_submitted()) {
-                $this->checkout->billing_form->receive_form_submission();
-                if ($this->checkout->billing_form->is_valid()) {
-                    return true;
-                }
-                $validation_errors = $this->checkout->billing_form->get_validation_errors_accumulated();
-                $error_strings = array();
-                foreach ($validation_errors as $validation_error) {
-                    if ($validation_error instanceof EE_Validation_Error) {
-                        $form_section = $validation_error->get_form_section();
-                        if ($form_section instanceof EE_Form_Input_Base) {
-                            $label = $form_section->html_label_text();
-                        } elseif ($form_section instanceof EE_Form_Section_Base) {
-                            $label = $form_section->name();
-                        } else {
-                            $label = esc_html__('Validation Error', 'event_espresso');
-                        }
-                        $error_strings[] = sprintf('%1$s: %2$s', $label, $validation_error->getMessage());
-                    }
-                }
-                EE_Error::add_error(
-                    sprintf(
-                        esc_html__(
-                            'One or more billing form inputs are invalid and require correction before proceeding. %1$s %2$s',
-                            'event_espresso'
-                        ),
-                        '<br/>',
-                        implode('<br/>', $error_strings)
-                    ),
-                    __FILE__,
-                    __FUNCTION__,
-                    __LINE__
-                );
-            } else {
-                EE_Error::add_error(
-                    esc_html__(
-                        'The billing form was not submitted or something prevented it\'s submission.',
-                        'event_espresso'
-                    ),
-                    __FILE__,
-                    __FUNCTION__,
-                    __LINE__
-                );
-            }
-        } else {
-            EE_Error::add_error(
-                esc_html__(
-                    'The submitted billing form is invalid possibly due to a technical reason.',
-                    'event_espresso'
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-        }
-        return false;
-    }
-
-
-    /**
-     * _setup_primary_registrant_prior_to_payment
-     * ensures that the primary registrant has a valid attendee object created with the critical details populated
-     * (first & last name & email) and that both the transaction object and primary registration object have been saved
-     * plz note that any other registrations will NOT be saved at this point (because they may not have any details
-     * yet)
-     *
-     * @access private
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws RuntimeException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _setup_primary_registrant_prior_to_payment()
-    {
-        // check if transaction has a primary registrant and that it has a related Attendee object
-        // if not, then we need to at least gather some primary registrant data before attempting payment
-        if ($this->checkout->billing_form instanceof EE_Billing_Attendee_Info_Form
-            && ! $this->checkout->transaction_has_primary_registrant()
-            && ! $this->_capture_primary_registration_data_from_billing_form()
-        ) {
-            return false;
-        }
-        // because saving an object clears it's cache, we need to do the chevy shuffle
-        // grab the primary_registration object
-        $primary_registration = $this->checkout->transaction->primary_registration();
-        // at this point we'll consider a TXN to not have been failed
-        $this->checkout->transaction->toggle_failed_transaction_status();
-        // save the TXN ( which clears cached copy of primary_registration)
-        $this->checkout->transaction->save();
-        // grab TXN ID and save it to the primary_registration
-        $primary_registration->set_transaction_id($this->checkout->transaction->ID());
-        // save what we have so far
-        $primary_registration->save();
-        return true;
-    }
-
-
-    /**
-     * _capture_primary_registration_data_from_billing_form
-     *
-     * @access private
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _capture_primary_registration_data_from_billing_form()
-    {
-        // convert billing form data into an attendee
-        $this->checkout->primary_attendee_obj = $this->checkout->billing_form->create_attendee_from_billing_form_data();
-        if (! $this->checkout->primary_attendee_obj instanceof EE_Attendee) {
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'The billing form details could not be used for attendee details due to a technical issue.%sPlease try again or contact %s for assistance.',
-                        'event_espresso'
-                    ),
-                    '<br/>',
-                    EE_Registry::instance()->CFG->organization->get_pretty('email')
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return false;
-        }
-        $primary_registration = $this->checkout->transaction->primary_registration();
-        if (! $primary_registration instanceof EE_Registration) {
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'The primary registrant for this transaction could not be determined due to a technical issue.%sPlease try again or contact %s for assistance.',
-                        'event_espresso'
-                    ),
-                    '<br/>',
-                    EE_Registry::instance()->CFG->organization->get_pretty('email')
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return false;
-        }
-        if (! $primary_registration->_add_relation_to($this->checkout->primary_attendee_obj, 'Attendee')
-              instanceof
-              EE_Attendee
-        ) {
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'The primary registrant could not be associated with this transaction due to a technical issue.%sPlease try again or contact %s for assistance.',
-                        'event_espresso'
-                    ),
-                    '<br/>',
-                    EE_Registry::instance()->CFG->organization->get_pretty('email')
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return false;
-        }
-        /** @type EE_Registration_Processor $registration_processor */
-        $registration_processor = EE_Registry::instance()->load_class('Registration_Processor');
-        // at this point, we should have enough details about the registrant to consider the registration NOT incomplete
-        $registration_processor->toggle_incomplete_registration_status_to_default($primary_registration);
-        return true;
-    }
-
-
-    /**
-     * _get_payment_method_for_selected_method_of_payment
-     * retrieves a valid payment method
-     *
-     * @access public
-     * @return EE_Payment_Method
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _get_payment_method_for_selected_method_of_payment()
-    {
-        if ($this->checkout->selected_method_of_payment === 'events_sold_out') {
-            $this->_redirect_because_event_sold_out();
-            return null;
-        }
-        // get EE_Payment_Method object
-        if (isset($this->checkout->available_payment_methods[ $this->checkout->selected_method_of_payment ])) {
-            $payment_method = $this->checkout->available_payment_methods[ $this->checkout->selected_method_of_payment ];
-        } else {
-            // load EEM_Payment_Method
-            EE_Registry::instance()->load_model('Payment_Method');
-            /** @type EEM_Payment_Method $EEM_Payment_Method */
-            $EEM_Payment_Method = EE_Registry::instance()->LIB->EEM_Payment_Method;
-            $payment_method = $EEM_Payment_Method->get_one_by_slug($this->checkout->selected_method_of_payment);
-        }
-        // verify $payment_method
-        if (! $payment_method instanceof EE_Payment_Method) {
-            // not a payment
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'The selected method of payment could not be determined due to a technical issue.%sPlease try again or contact %s for assistance.',
-                        'event_espresso'
-                    ),
-                    '<br/>',
-                    EE_Registry::instance()->CFG->organization->get_pretty('email')
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return null;
-        }
-        // and verify it has a valid Payment_Method Type object
-        if (! $payment_method->type_obj() instanceof EE_PMT_Base) {
-            // not a payment
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'A valid payment method could not be determined due to a technical issue.%sPlease try again or contact %s for assistance.',
-                        'event_espresso'
-                    ),
-                    '<br/>',
-                    EE_Registry::instance()->CFG->organization->get_pretty('email')
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return null;
-        }
-        return $payment_method;
-    }
-
-
-    /**
-     *    _attempt_payment
-     *
-     * @access    private
-     * @type    EE_Payment_Method $payment_method
-     * @return mixed EE_Payment | boolean
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _attempt_payment(EE_Payment_Method $payment_method)
-    {
-        $payment = null;
-        $this->checkout->transaction->save();
-        $payment_processor = EE_Registry::instance()->load_core('Payment_Processor');
-        if (! $payment_processor instanceof EE_Payment_Processor) {
-            return false;
-        }
-        try {
-            $payment_processor->set_revisit($this->checkout->revisit);
-            // generate payment object
-            $payment = $payment_processor->process_payment(
-                $payment_method,
-                $this->checkout->transaction,
-                $this->checkout->amount_owing,
-                $this->checkout->billing_form,
-                $this->_get_return_url($payment_method),
-                'CART',
-                $this->checkout->admin_request,
-                true,
-                $this->reg_step_url()
-            );
-        } catch (Exception $e) {
-            $this->_handle_payment_processor_exception($e);
-        }
-        return $payment;
-    }
-
-
-    /**
-     * _handle_payment_processor_exception
-     *
-     * @access protected
-     * @param \Exception $e
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    protected function _handle_payment_processor_exception(Exception $e)
-    {
-        EE_Error::add_error(
-            sprintf(
-                esc_html__(
-                    'The payment could not br processed due to a technical issue.%1$sPlease try again or contact %2$s for assistance.||The following Exception was thrown in %4$s on line %5$s:%1$s%3$s',
-                    'event_espresso'
-                ),
-                '<br/>',
-                EE_Registry::instance()->CFG->organization->get_pretty('email'),
-                $e->getMessage(),
-                $e->getFile(),
-                $e->getLine()
-            ),
-            __FILE__,
-            __FUNCTION__,
-            __LINE__
-        );
-    }
-
-
-    /**
-     * _get_return_url
-     *
-     * @access protected
-     * @param \EE_Payment_Method $payment_method
-     * @return string
-     * @throws \EE_Error
-     */
-    protected function _get_return_url(EE_Payment_Method $payment_method)
-    {
-        $return_url = '';
-        switch ($payment_method->type_obj()->payment_occurs()) {
-            case EE_PMT_Base::offsite:
-                $return_url = add_query_arg(
-                    array(
-                        'action'                     => 'process_gateway_response',
-                        'selected_method_of_payment' => $this->checkout->selected_method_of_payment,
-                        'spco_txn'                   => $this->checkout->transaction->ID(),
-                    ),
-                    $this->reg_step_url()
-                );
-                break;
-            case EE_PMT_Base::onsite:
-            case EE_PMT_Base::offline:
-                $return_url = $this->checkout->next_step->reg_step_url();
-                break;
-        }
-        return $return_url;
-    }
-
-
-    /**
-     * _validate_payment
-     *
-     * @access private
-     * @param EE_Payment $payment
-     * @return EE_Payment|FALSE
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _validate_payment($payment = null)
-    {
-        if ($this->checkout->payment_method->is_off_line()) {
-            return true;
-        }
-        // verify payment object
-        if (! $payment instanceof EE_Payment) {
-            // not a payment
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'A valid payment was not generated due to a technical issue.%1$sPlease try again or contact %2$s for assistance.',
-                        'event_espresso'
-                    ),
-                    '<br/>',
-                    EE_Registry::instance()->CFG->organization->get_pretty('email')
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return false;
-        }
-        return $payment;
-    }
-
-
-    /**
-     * _post_payment_processing
-     *
-     * @access private
-     * @param EE_Payment|bool $payment
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _post_payment_processing($payment = null)
-    {
-        // Off-Line payment?
-        if ($payment === true) {
-            // $this->_setup_redirect_for_next_step();
-            return true;
-            // On-Site payment?
-        } elseif ($this->checkout->payment_method->is_on_site()) {
-            if (! $this->_process_payment_status($payment, EE_PMT_Base::onsite)) {
-                // $this->_setup_redirect_for_next_step();
-                $this->checkout->continue_reg = false;
-            }
-            // Off-Site payment?
-        } elseif ($this->checkout->payment_method->is_off_site()) {
-            // if a payment object was made and it specifies a redirect url, then we'll setup that redirect info
-            if ($payment instanceof EE_Payment && $payment->redirect_url()) {
-                do_action('AHEE_log', __CLASS__, __FUNCTION__, $payment->redirect_url(), '$payment->redirect_url()');
-                $this->checkout->redirect = true;
-                $this->checkout->redirect_form = $payment->redirect_form();
-                $this->checkout->redirect_url = $this->reg_step_url('redirect_form');
-                // set JSON response
-                $this->checkout->json_response->set_redirect_form($this->checkout->redirect_form);
-                // and lastly, let's bump the payment status to pending
-                $payment->set_status(EEM_Payment::status_id_pending);
-                $payment->save();
-            } else {
-                // not a payment
-                $this->checkout->continue_reg = false;
-                EE_Error::add_error(
-                    sprintf(
-                        esc_html__(
-                            'It appears the Off Site Payment Method was not configured properly.%sPlease try again or contact %s for assistance.',
-                            'event_espresso'
-                        ),
-                        '<br/>',
-                        EE_Registry::instance()->CFG->organization->get_pretty('email')
-                    ),
-                    __FILE__,
-                    __FUNCTION__,
-                    __LINE__
-                );
-            }
-        } else {
-            // ummm ya... not Off-Line, not On-Site, not off-Site ????
-            $this->checkout->continue_reg = false;
-            return false;
-        }
-        return $payment;
-    }
-
-
-    /**
-     *    _process_payment_status
-     *
-     * @access private
-     * @type    EE_Payment $payment
-     * @param string       $payment_occurs
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _process_payment_status($payment, $payment_occurs = EE_PMT_Base::offline)
-    {
-        // off-line payment? carry on
-        if ($payment_occurs === EE_PMT_Base::offline) {
-            return true;
-        }
-        // verify payment validity
-        if ($payment instanceof EE_Payment) {
-            do_action('AHEE_log', __CLASS__, __FUNCTION__, $payment->status(), '$payment->status()');
-            $msg = $payment->gateway_response();
-            // check results
-            switch ($payment->status()) {
-                // good payment
-                case EEM_Payment::status_id_approved:
-                    EE_Error::add_success(
-                        esc_html__('Your payment was processed successfully.', 'event_espresso'),
-                        __FILE__,
-                        __FUNCTION__,
-                        __LINE__
-                    );
-                    return true;
-                    break;
-                // slow payment
-                case EEM_Payment::status_id_pending:
-                    if (empty($msg)) {
-                        $msg = esc_html__(
-                            'Your payment appears to have been processed successfully, but the Instant Payment Notification has not yet been received. It should arrive shortly.',
-                            'event_espresso'
-                        );
-                    }
-                    EE_Error::add_success($msg, __FILE__, __FUNCTION__, __LINE__);
-                    return true;
-                    break;
-                // don't wanna payment
-                case EEM_Payment::status_id_cancelled:
-                    if (empty($msg)) {
-                        $msg = _n(
-                            'Payment cancelled. Please try again.',
-                            'Payment cancelled. Please try again or select another method of payment.',
-                            count($this->checkout->available_payment_methods),
-                            'event_espresso'
-                        );
-                    }
-                    EE_Error::add_attention($msg, __FILE__, __FUNCTION__, __LINE__);
-                    return false;
-                    break;
-                // not enough payment
-                case EEM_Payment::status_id_declined:
-                    if (empty($msg)) {
-                        $msg = _n(
-                            'We\'re sorry but your payment was declined. Please try again.',
-                            'We\'re sorry but your payment was declined. Please try again or select another method of payment.',
-                            count($this->checkout->available_payment_methods),
-                            'event_espresso'
-                        );
-                    }
-                    EE_Error::add_attention($msg, __FILE__, __FUNCTION__, __LINE__);
-                    return false;
-                    break;
-                // bad payment
-                case EEM_Payment::status_id_failed:
-                    if (! empty($msg)) {
-                        EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
-                        return false;
-                    }
-                    // default to error below
-                    break;
-            }
-        }
-        // off-site payment gateway responses are too unreliable, so let's just assume that
-        // the payment processing is just running slower than the registrant's request
-        if ($payment_occurs === EE_PMT_Base::offsite) {
-            return true;
-        }
-        EE_Error::add_error(
-            sprintf(
-                esc_html__(
-                    'Your payment could not be processed successfully due to a technical issue.%sPlease try again or contact %s for assistance.',
-                    'event_espresso'
-                ),
-                '<br/>',
-                EE_Registry::instance()->CFG->organization->get_pretty('email')
-            ),
-            __FILE__,
-            __FUNCTION__,
-            __LINE__
-        );
-        return false;
-    }
-
-
-
-
-
-
-    /********************************************************************************************************/
-    /**********************************  PROCESS GATEWAY RESPONSE  **********************************/
-    /********************************************************************************************************/
-    /**
-     * process_gateway_response
-     * this is the return point for Off-Site Payment Methods
-     * It will attempt to "handle the IPN" if it appears that this has not already occurred,
-     * otherwise, it will load up the last payment made for the TXN.
-     * If the payment retrieved looks good, it will then either:
-     *    complete the current step and allow advancement to the next reg step
-     *        or present the payment options again
-     *
-     * @access private
-     * @return EE_Payment|FALSE
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     * @throws \EventEspresso\core\exceptions\InvalidSessionDataException
-     */
-    public function process_gateway_response()
-    {
-        $payment = null;
-        // how have they chosen to pay?
-        $this->checkout->selected_method_of_payment = $this->_get_selected_method_of_payment(true);
-        // get EE_Payment_Method object
-        if (! $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment()) {
-            $this->checkout->continue_reg = false;
-            return false;
-        }
-        if (! $this->checkout->payment_method->is_off_site()) {
-            return false;
-        }
-        $this->_validate_offsite_return();
-        // DEBUG LOG
-        // $this->checkout->log(
-        //     __CLASS__,
-        //     __FUNCTION__,
-        //     __LINE__,
-        //     array(
-        //         'selected_method_of_payment' => $this->checkout->selected_method_of_payment,
-        //         'payment_method'             => $this->checkout->payment_method,
-        //     ),
-        //     true
-        // );
-        // verify TXN
-        if ($this->checkout->transaction instanceof EE_Transaction) {
-            $gateway = $this->checkout->payment_method->type_obj()->get_gateway();
-            if (! $gateway instanceof EE_Offsite_Gateway) {
-                $this->checkout->continue_reg = false;
-                return false;
-            }
-            $payment = $this->_process_off_site_payment($gateway);
-            $payment = $this->_process_cancelled_payments($payment);
-            $payment = $this->_validate_payment($payment);
-            // if payment was not declined by the payment gateway or cancelled by the registrant
-            if ($this->_process_payment_status($payment, EE_PMT_Base::offsite)) {
-                // $this->_setup_redirect_for_next_step();
-                // store that for later
-                $this->checkout->payment = $payment;
-                // mark this reg step as completed, as long as gateway doesn't use a separate IPN request,
-                // because we will complete this step during the IPN processing then
-                if ($gateway instanceof EE_Offsite_Gateway && ! $this->handle_IPN_in_this_request()) {
-                    $this->set_completed();
-                }
-                return true;
-            }
-        }
-        // DEBUG LOG
-        // $this->checkout->log(
-        //     __CLASS__,
-        //     __FUNCTION__,
-        //     __LINE__,
-        //     array('payment' => $payment)
-        // );
-        $this->checkout->continue_reg = false;
-        return false;
-    }
-
-
-    /**
-     * _validate_return
-     *
-     * @access private
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     * @throws \EventEspresso\core\exceptions\InvalidSessionDataException
-     */
-    private function _validate_offsite_return()
-    {
-        $TXN_ID = (int) EE_Registry::instance()->REQ->get('spco_txn', 0);
-        if ($TXN_ID !== $this->checkout->transaction->ID()) {
-            // Houston... we might have a problem
-            $invalid_TXN = false;
-            // first gather some info
-            $valid_TXN = EEM_Transaction::instance()->get_one_by_ID($TXN_ID);
-            $primary_registrant = $valid_TXN instanceof EE_Transaction
-                ? $valid_TXN->primary_registration()
-                : null;
-            // let's start by retrieving the cart for this TXN
-            $cart = $this->checkout->get_cart_for_transaction($this->checkout->transaction);
-            if ($cart instanceof EE_Cart) {
-                // verify that the current cart has tickets
-                $tickets = $cart->get_tickets();
-                if (empty($tickets)) {
-                    $invalid_TXN = true;
-                }
-            } else {
-                $invalid_TXN = true;
-            }
-            $valid_TXN_SID = $primary_registrant instanceof EE_Registration
-                ? $primary_registrant->session_ID()
-                : null;
-            // validate current Session ID and compare against valid TXN session ID
-            if ($invalid_TXN // if this is already true, then skip other checks
-                || EE_Session::instance()->id() === null
-                || (
-                    // WARNING !!!
-                    // this could be PayPal sending back duplicate requests (ya they do that)
-                    // or it **could** mean someone is simply registering AGAIN after having just done so
-                    // so now we need to determine if this current TXN looks valid or not
-                    // and whether this reg step has even been started ?
-                    EE_Session::instance()->id() === $valid_TXN_SID
-                    // really? you're half way through this reg step, but you never started it ?
-                    && $this->checkout->transaction->reg_step_completed($this->slug()) === false
-                )
-            ) {
-                $invalid_TXN = true;
-            }
-            if ($invalid_TXN) {
-                // is the valid TXN completed ?
-                if ($valid_TXN instanceof EE_Transaction) {
-                    // has this step even been started ?
-                    $reg_step_completed = $valid_TXN->reg_step_completed($this->slug());
-                    if ($reg_step_completed !== false && $reg_step_completed !== true) {
-                        // so it **looks** like this is a double request from PayPal
-                        // so let's try to pick up where we left off
-                        $this->checkout->transaction = $valid_TXN;
-                        $this->checkout->refresh_all_entities(true);
-                        return;
-                    }
-                }
-                // you appear to be lost?
-                $this->_redirect_wayward_request($primary_registrant);
-            }
-        }
-    }
-
-
-    /**
-     * _redirect_wayward_request
-     *
-     * @access private
-     * @param \EE_Registration|null $primary_registrant
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _redirect_wayward_request(EE_Registration $primary_registrant)
-    {
-        if (! $primary_registrant instanceof EE_Registration) {
-            // try redirecting based on the current TXN
-            $primary_registrant = $this->checkout->transaction instanceof EE_Transaction
-                ? $this->checkout->transaction->primary_registration()
-                : null;
-        }
-        if (! $primary_registrant instanceof EE_Registration) {
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'Invalid information was received from the Off-Site Payment Processor and your Transaction details could not be retrieved from the database.%1$sPlease try again or contact %2$s for assistance.',
-                        'event_espresso'
-                    ),
-                    '<br/>',
-                    EE_Registry::instance()->CFG->organization->get_pretty('email')
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return false;
-        }
-        // make sure transaction is not locked
-        $this->checkout->transaction->unlock();
-        wp_safe_redirect(
-            add_query_arg(
-                array(
-                    'e_reg_url_link' => $primary_registrant->reg_url_link(),
-                ),
-                $this->checkout->thank_you_page_url
-            )
-        );
-        exit();
-    }
-
-
-    /**
-     * _process_off_site_payment
-     *
-     * @access private
-     * @param \EE_Offsite_Gateway $gateway
-     * @return EE_Payment
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    private function _process_off_site_payment(EE_Offsite_Gateway $gateway)
-    {
-        try {
-            $request_data = \EE_Registry::instance()->REQ->params();
-            // if gateway uses_separate_IPN_request, then we don't have to process the IPN manually
-            $this->set_handle_IPN_in_this_request(
-                $gateway->handle_IPN_in_this_request($request_data, false)
-            );
-            if ($this->handle_IPN_in_this_request()) {
-                // get payment details and process results
-                /** @type EE_Payment_Processor $payment_processor */
-                $payment_processor = EE_Registry::instance()->load_core('Payment_Processor');
-                $payment = $payment_processor->process_ipn(
-                    $request_data,
-                    $this->checkout->transaction,
-                    $this->checkout->payment_method,
-                    true,
-                    false
-                );
-                // $payment_source = 'process_ipn';
-            } else {
-                $payment = $this->checkout->transaction->last_payment();
-                // $payment_source = 'last_payment';
-            }
-        } catch (Exception $e) {
-            // let's just eat the exception and try to move on using any previously set payment info
-            $payment = $this->checkout->transaction->last_payment();
-            // $payment_source = 'last_payment after Exception';
-            // but if we STILL don't have a payment object
-            if (! $payment instanceof EE_Payment) {
-                // then we'll object ! ( not object like a thing... but object like what a lawyer says ! )
-                $this->_handle_payment_processor_exception($e);
-            }
-        }
-        // DEBUG LOG
-        // $this->checkout->log(
-        //     __CLASS__,
-        //     __FUNCTION__,
-        //     __LINE__,
-        //     array(
-        //         'process_ipn_payment' => $payment,
-        //         'payment_source'      => $payment_source,
-        //     )
-        // );
-        return $payment;
-    }
-
-
-    /**
-     * _process_cancelled_payments
-     * just makes sure that the payment status gets updated correctly
-     * so tha tan error isn't generated during payment validation
-     *
-     * @access private
-     * @param EE_Payment $payment
-     * @return EE_Payment | FALSE
-     * @throws \EE_Error
-     */
-    private function _process_cancelled_payments($payment = null)
-    {
-        if ($payment instanceof EE_Payment
-            && isset($_REQUEST['ee_cancel_payment'])
-            && $payment->status() === EEM_Payment::status_id_failed
-        ) {
-            $payment->set_status(EEM_Payment::status_id_cancelled);
-        }
-        return $payment;
-    }
-
-
-    /**
-     *    get_transaction_details_for_gateways
-     *
-     * @access    public
-     * @return int
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
-     * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
-     */
-    public function get_transaction_details_for_gateways()
-    {
-        $txn_details = array();
-        // ya gotta make a choice man
-        if (empty($this->checkout->selected_method_of_payment)) {
-            $txn_details = array(
-                'error' => esc_html__('Please select a method of payment before proceeding.', 'event_espresso'),
-            );
-        }
-        // get EE_Payment_Method object
-        if (empty($txn_details)
-            &&
-            ! $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment()
-        ) {
-            $txn_details = array(
-                'selected_method_of_payment' => $this->checkout->selected_method_of_payment,
-                'error'                      => esc_html__(
-                    'A valid Payment Method could not be determined.',
-                    'event_espresso'
-                ),
-            );
-        }
-        if (empty($txn_details) && $this->checkout->transaction instanceof EE_Transaction) {
-            $return_url = $this->_get_return_url($this->checkout->payment_method);
-            $txn_details = array(
-                'TXN_ID'         => $this->checkout->transaction->ID(),
-                'TXN_timestamp'  => $this->checkout->transaction->datetime(),
-                'TXN_total'      => $this->checkout->transaction->total(),
-                'TXN_paid'       => $this->checkout->transaction->paid(),
-                'TXN_reg_steps'  => $this->checkout->transaction->reg_steps(),
-                'STS_ID'         => $this->checkout->transaction->status_ID(),
-                'PMD_ID'         => $this->checkout->transaction->payment_method_ID(),
-                'payment_amount' => $this->checkout->amount_owing,
-                'return_url'     => $return_url,
-                'cancel_url'     => add_query_arg(array('ee_cancel_payment' => true), $return_url),
-                'notify_url'     => EE_Config::instance()->core->txn_page_url(
-                    array(
-                        'e_reg_url_link'    => $this->checkout->transaction->primary_registration()->reg_url_link(),
-                        'ee_payment_method' => $this->checkout->payment_method->slug(),
-                    )
-                ),
-            );
-        }
-        echo wp_json_encode($txn_details);
-        exit();
-    }
-
-
-    /**
-     *    __sleep
-     * to conserve db space, let's remove the reg_form and the EE_Checkout object from EE_SPCO_Reg_Step objects upon
-     * serialization EE_Checkout will handle the reimplementation of itself upon waking, but we won't bother with the
-     * reg form, because if needed, it will be regenerated anyways
-     *
-     * @return array
-     */
-    public function __sleep()
-    {
-        // remove the reg form and the checkout
-        return array_diff(array_keys(get_object_vars($this)), array('reg_form', 'checkout', 'line_item_display'));
-    }
+	/**
+	 * @access protected
+	 * @var EE_Line_Item_Display $Line_Item_Display
+	 */
+	protected $line_item_display;
+
+	/**
+	 * @access protected
+	 * @var boolean $handle_IPN_in_this_request
+	 */
+	protected $handle_IPN_in_this_request = false;
+
+
+	/**
+	 *    set_hooks - for hooking into EE Core, other modules, etc
+	 *
+	 * @access    public
+	 * @return    void
+	 */
+	public static function set_hooks()
+	{
+		add_filter(
+			'FHEE__SPCO__EE_Line_Item_Filter_Collection',
+			array('EE_SPCO_Reg_Step_Payment_Options', 'add_spco_line_item_filters')
+		);
+		add_action(
+			'wp_ajax_switch_spco_billing_form',
+			array('EE_SPCO_Reg_Step_Payment_Options', 'switch_spco_billing_form')
+		);
+		add_action(
+			'wp_ajax_nopriv_switch_spco_billing_form',
+			array('EE_SPCO_Reg_Step_Payment_Options', 'switch_spco_billing_form')
+		);
+		add_action('wp_ajax_save_payer_details', array('EE_SPCO_Reg_Step_Payment_Options', 'save_payer_details'));
+		add_action(
+			'wp_ajax_nopriv_save_payer_details',
+			array('EE_SPCO_Reg_Step_Payment_Options', 'save_payer_details')
+		);
+		add_action(
+			'wp_ajax_get_transaction_details_for_gateways',
+			array('EE_SPCO_Reg_Step_Payment_Options', 'get_transaction_details')
+		);
+		add_action(
+			'wp_ajax_nopriv_get_transaction_details_for_gateways',
+			array('EE_SPCO_Reg_Step_Payment_Options', 'get_transaction_details')
+		);
+		add_filter(
+			'FHEE__EED_Recaptcha___bypass_recaptcha__bypass_request_params_array',
+			array('EE_SPCO_Reg_Step_Payment_Options', 'bypass_recaptcha_for_load_payment_method'),
+			10,
+			1
+		);
+	}
+
+
+	/**
+	 *    ajax switch_spco_billing_form
+	 *
+	 * @throws \EE_Error
+	 */
+	public static function switch_spco_billing_form()
+	{
+		EED_Single_Page_Checkout::process_ajax_request('switch_payment_method');
+	}
+
+
+	/**
+	 *    ajax save_payer_details
+	 *
+	 * @throws \EE_Error
+	 */
+	public static function save_payer_details()
+	{
+		EED_Single_Page_Checkout::process_ajax_request('save_payer_details_via_ajax');
+	}
+
+
+	/**
+	 *    ajax get_transaction_details
+	 *
+	 * @throws \EE_Error
+	 */
+	public static function get_transaction_details()
+	{
+		EED_Single_Page_Checkout::process_ajax_request('get_transaction_details_for_gateways');
+	}
+
+
+	/**
+	 * bypass_recaptcha_for_load_payment_method
+	 *
+	 * @access public
+	 * @return array
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	public static function bypass_recaptcha_for_load_payment_method()
+	{
+		return array(
+			'EESID'  => EE_Registry::instance()->SSN->id(),
+			'step'   => 'payment_options',
+			'action' => 'spco_billing_form',
+		);
+	}
+
+
+	/**
+	 *    class constructor
+	 *
+	 * @access    public
+	 * @param    EE_Checkout $checkout
+	 */
+	public function __construct(EE_Checkout $checkout)
+	{
+		$this->_slug = 'payment_options';
+		$this->_name = esc_html__('Payment Options', 'event_espresso');
+		$this->_template = SPCO_REG_STEPS_PATH . $this->_slug . DS . 'payment_options_main.template.php';
+		$this->checkout = $checkout;
+		$this->_reset_success_message();
+		$this->set_instructions(
+			esc_html__(
+				'Please select a method of payment and provide any necessary billing information before proceeding.',
+				'event_espresso'
+			)
+		);
+	}
+
+
+	/**
+	 * @return null
+	 */
+	public function line_item_display()
+	{
+		return $this->line_item_display;
+	}
+
+
+	/**
+	 * @param null $line_item_display
+	 */
+	public function set_line_item_display($line_item_display)
+	{
+		$this->line_item_display = $line_item_display;
+	}
+
+
+	/**
+	 * @return boolean
+	 */
+	public function handle_IPN_in_this_request()
+	{
+		return $this->handle_IPN_in_this_request;
+	}
+
+
+	/**
+	 * @param boolean $handle_IPN_in_this_request
+	 */
+	public function set_handle_IPN_in_this_request($handle_IPN_in_this_request)
+	{
+		$this->handle_IPN_in_this_request = filter_var($handle_IPN_in_this_request, FILTER_VALIDATE_BOOLEAN);
+	}
+
+
+	/**
+	 * translate_js_strings
+	 *
+	 * @return void
+	 */
+	public function translate_js_strings()
+	{
+		EE_Registry::$i18n_js_strings['no_payment_method'] = esc_html__(
+			'Please select a method of payment in order to continue.',
+			'event_espresso'
+		);
+		EE_Registry::$i18n_js_strings['invalid_payment_method'] = esc_html__(
+			'A valid method of payment could not be determined. Please refresh the page and try again.',
+			'event_espresso'
+		);
+		EE_Registry::$i18n_js_strings['forwarding_to_offsite'] = esc_html__(
+			'Forwarding to Secure Payment Provider.',
+			'event_espresso'
+		);
+	}
+
+
+	/**
+	 * enqueue_styles_and_scripts
+	 *
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	public function enqueue_styles_and_scripts()
+	{
+		$transaction = $this->checkout->transaction;
+		// if the transaction isn't set or nothing is owed on it, don't enqueue any JS
+		if (! $transaction instanceof EE_Transaction || EEH_Money::compare_floats($transaction->remaining(), 0)) {
+			return;
+		}
+		foreach (EEM_Payment_Method::instance()->get_all_for_transaction(
+			$transaction,
+			EEM_Payment_Method::scope_cart
+		) as $payment_method) {
+			$type_obj = $payment_method->type_obj();
+			if ($type_obj instanceof EE_PMT_Base) {
+				$billing_form = $type_obj->generate_new_billing_form($transaction);
+				if ($billing_form instanceof EE_Form_Section_Proper) {
+					$billing_form->enqueue_js();
+				}
+			}
+		}
+	}
+
+
+	/**
+	 * initialize_reg_step
+	 *
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	public function initialize_reg_step()
+	{
+		// TODO: if /when we implement donations, then this will need overriding
+		if (// don't need payment options for:
+			// registrations made via the admin
+			// completed transactions
+			// overpaid transactions
+			// $ 0.00 transactions(no payment required)
+			! $this->checkout->payment_required()
+			// but do NOT remove if current action being called belongs to this reg step
+			&& ! is_callable(array($this, $this->checkout->action))
+			&& ! $this->completed()
+		) {
+			// and if so, then we no longer need the Payment Options step
+			if ($this->is_current_step()) {
+				$this->checkout->generate_reg_form = false;
+			}
+			$this->checkout->remove_reg_step($this->_slug);
+			// DEBUG LOG
+			// $this->checkout->log( __CLASS__, __FUNCTION__, __LINE__ );
+			return false;
+		}
+		// load EEM_Payment_Method
+		EE_Registry::instance()->load_model('Payment_Method');
+		// get all active payment methods
+		$this->checkout->available_payment_methods = EEM_Payment_Method::instance()->get_all_for_transaction(
+			$this->checkout->transaction,
+			EEM_Payment_Method::scope_cart
+		);
+		return true;
+	}
+
+
+	/**
+	 * @return EE_Form_Section_Proper
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\EntityNotFoundException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 * @throws \EventEspresso\core\exceptions\InvalidStatusException
+	 */
+	public function generate_reg_form()
+	{
+		// reset in case someone changes their mind
+		$this->_reset_selected_method_of_payment();
+		// set some defaults
+		$this->checkout->selected_method_of_payment = 'payments_closed';
+		$registrations_requiring_payment = array();
+		$registrations_for_free_events = array();
+		$registrations_requiring_pre_approval = array();
+		$sold_out_events = array();
+		$insufficient_spaces_available = array();
+		$no_payment_required = true;
+		// loop thru registrations to gather info
+		$registrations = $this->checkout->transaction->registrations($this->checkout->reg_cache_where_params);
+		$ejected_registrations = EE_SPCO_Reg_Step_Payment_Options::find_registrations_that_lost_their_space(
+			$registrations,
+			$this->checkout->revisit
+		);
+		foreach ($registrations as $REG_ID => $registration) {
+			/** @var $registration EE_Registration */
+			// has this registration lost it's space ?
+			if (isset($ejected_registrations[ $REG_ID ])) {
+				if ($registration->event()->is_sold_out() || $registration->event()->is_sold_out(true)) {
+					$sold_out_events[ $registration->event()->ID() ] = $registration->event();
+				} else {
+					$insufficient_spaces_available[ $registration->event()->ID() ] = $registration->event();
+				}
+				continue;
+			}
+			// event requires admin approval
+			if ($registration->status_ID() === EEM_Registration::status_id_not_approved) {
+				// add event to list of events with pre-approval reg status
+				$registrations_requiring_pre_approval[ $REG_ID ] = $registration;
+				do_action(
+					'AHEE__EE_SPCO_Reg_Step_Payment_Options__generate_reg_form__event_requires_pre_approval',
+					$registration->event(),
+					$this
+				);
+				continue;
+			}
+			if ($this->checkout->revisit
+				&& $registration->status_ID() !== EEM_Registration::status_id_approved
+				&& (
+					$registration->event()->is_sold_out()
+					|| $registration->event()->is_sold_out(true)
+				)
+			) {
+				// add event to list of events that are sold out
+				$sold_out_events[ $registration->event()->ID() ] = $registration->event();
+				do_action(
+					'AHEE__EE_SPCO_Reg_Step_Payment_Options__generate_reg_form__sold_out_event',
+					$registration->event(),
+					$this
+				);
+				continue;
+			}
+			// are they allowed to pay now and is there monies owing?
+			if ($registration->owes_monies_and_can_pay()) {
+				$registrations_requiring_payment[ $REG_ID ] = $registration;
+				do_action(
+					'AHEE__EE_SPCO_Reg_Step_Payment_Options__generate_reg_form__event_requires_payment',
+					$registration->event(),
+					$this
+				);
+			} elseif (! $this->checkout->revisit
+					  && $registration->status_ID() !== EEM_Registration::status_id_not_approved
+					  && $registration->ticket()->is_free()
+			) {
+				$registrations_for_free_events[ $registration->ticket()->ID() ] = $registration;
+			}
+		}
+		$subsections = array();
+		// now decide which template to load
+		if (! empty($sold_out_events)) {
+			$subsections['sold_out_events'] = $this->_sold_out_events($sold_out_events);
+		}
+		if (! empty($insufficient_spaces_available)) {
+			$subsections['insufficient_space'] = $this->_insufficient_spaces_available(
+				$insufficient_spaces_available
+			);
+		}
+		if (! empty($registrations_requiring_pre_approval)) {
+			$subsections['registrations_requiring_pre_approval'] = $this->_registrations_requiring_pre_approval(
+				$registrations_requiring_pre_approval
+			);
+		}
+		if (! empty($registrations_for_free_events)) {
+			$subsections['no_payment_required'] = $this->_no_payment_required($registrations_for_free_events);
+		}
+		if (! empty($registrations_requiring_payment)) {
+			if ($this->checkout->amount_owing > 0) {
+				// autoload Line_Item_Display classes
+				EEH_Autoloader::register_line_item_filter_autoloaders();
+				$line_item_filter_processor = new EE_Line_Item_Filter_Processor(
+					apply_filters(
+						'FHEE__SPCO__EE_Line_Item_Filter_Collection',
+						new EE_Line_Item_Filter_Collection()
+					),
+					$this->checkout->cart->get_grand_total()
+				);
+				/** @var EE_Line_Item $filtered_line_item_tree */
+				$filtered_line_item_tree = $line_item_filter_processor->process();
+				EEH_Autoloader::register_line_item_display_autoloaders();
+				$this->set_line_item_display(new EE_Line_Item_Display('spco'));
+				$subsections['payment_options'] = $this->_display_payment_options(
+					$this->line_item_display->display_line_item(
+						$filtered_line_item_tree,
+						array('registrations' => $registrations)
+					)
+				);
+				$this->checkout->amount_owing = $filtered_line_item_tree->total();
+				$this->_apply_registration_payments_to_amount_owing($registrations);
+			}
+			$no_payment_required = false;
+		} else {
+			$this->_hide_reg_step_submit_button_if_revisit();
+		}
+		$this->_save_selected_method_of_payment();
+
+		$subsections['default_hidden_inputs'] = $this->reg_step_hidden_inputs();
+		$subsections['extra_hidden_inputs'] = $this->_extra_hidden_inputs($no_payment_required);
+
+		return new EE_Form_Section_Proper(
+			array(
+				'name'            => $this->reg_form_name(),
+				'html_id'         => $this->reg_form_name(),
+				'subsections'     => $subsections,
+				'layout_strategy' => new EE_No_Layout(),
+			)
+		);
+	}
+
+
+	/**
+	 * add line item filters required for this reg step
+	 * these filters are applied via this line in EE_SPCO_Reg_Step_Payment_Options::set_hooks():
+	 *        add_filter( 'FHEE__SPCO__EE_Line_Item_Filter_Collection', array( 'EE_SPCO_Reg_Step_Payment_Options',
+	 *        'add_spco_line_item_filters' ) ); so any code that wants to use the same set of filters during the
+	 *        payment options reg step, can apply these filters via the following: apply_filters(
+	 *        'FHEE__SPCO__EE_Line_Item_Filter_Collection', new EE_Line_Item_Filter_Collection() ) or to an existing
+	 *        filter collection by passing that instead of instantiating a new collection
+	 *
+	 * @param \EE_Line_Item_Filter_Collection $line_item_filter_collection
+	 * @return EE_Line_Item_Filter_Collection
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\EntityNotFoundException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 * @throws \EventEspresso\core\exceptions\InvalidStatusException
+	 */
+	public static function add_spco_line_item_filters(EE_Line_Item_Filter_Collection $line_item_filter_collection)
+	{
+		if (! EE_Registry::instance()->SSN instanceof EE_Session) {
+			return $line_item_filter_collection;
+		}
+		if (! EE_Registry::instance()->SSN->checkout() instanceof EE_Checkout) {
+			return $line_item_filter_collection;
+		}
+		if (! EE_Registry::instance()->SSN->checkout()->transaction instanceof EE_Transaction) {
+			return $line_item_filter_collection;
+		}
+		$line_item_filter_collection->add(
+			new EE_Billable_Line_Item_Filter(
+				EE_SPCO_Reg_Step_Payment_Options::remove_ejected_registrations(
+					EE_Registry::instance()->SSN->checkout()->transaction->registrations(
+						EE_Registry::instance()->SSN->checkout()->reg_cache_where_params
+					)
+				)
+			)
+		);
+		$line_item_filter_collection->add(new EE_Non_Zero_Line_Item_Filter());
+		return $line_item_filter_collection;
+	}
+
+
+	/**
+	 * remove_ejected_registrations
+	 * if a registrant has lost their potential space at an event due to lack of payment,
+	 * then this method removes them from the list of registrations being paid for during this request
+	 *
+	 * @param \EE_Registration[] $registrations
+	 * @return EE_Registration[]
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\EntityNotFoundException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 * @throws \EventEspresso\core\exceptions\InvalidStatusException
+	 */
+	public static function remove_ejected_registrations(array $registrations)
+	{
+		$ejected_registrations = EE_SPCO_Reg_Step_Payment_Options::find_registrations_that_lost_their_space(
+			$registrations,
+			EE_Registry::instance()->SSN->checkout()->revisit
+		);
+		foreach ($registrations as $REG_ID => $registration) {
+			// has this registration lost it's space ?
+			if (isset($ejected_registrations[ $REG_ID ])) {
+				unset($registrations[ $REG_ID ]);
+				continue;
+			}
+		}
+		return $registrations;
+	}
+
+
+	/**
+	 * find_registrations_that_lost_their_space
+	 * If a registrant chooses an offline payment method like Invoice,
+	 * then no space is reserved for them at the event until they fully pay fo that site
+	 * (unless the event's default reg status is set to APPROVED)
+	 * if a registrant then later returns to pay, but the number of spaces available has been reduced due to sales,
+	 * then this method will determine which registrations have lost the ability to complete the reg process.
+	 *
+	 * @param \EE_Registration[] $registrations
+	 * @param bool               $revisit
+	 * @return array
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\EntityNotFoundException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 * @throws \EventEspresso\core\exceptions\InvalidStatusException
+	 */
+	public static function find_registrations_that_lost_their_space(array $registrations, $revisit = false)
+	{
+		// registrations per event
+		$event_reg_count = array();
+		// spaces left per event
+		$event_spaces_remaining = array();
+		// tickets left sorted by ID
+		$tickets_remaining = array();
+		// registrations that have lost their space
+		$ejected_registrations = array();
+		foreach ($registrations as $REG_ID => $registration) {
+			if ($registration->status_ID() === EEM_Registration::status_id_approved
+				|| apply_filters(
+					'FHEE__EE_SPCO_Reg_Step_Payment_Options__find_registrations_that_lost_their_space__allow_reg_payment',
+					false,
+					$registration,
+					$revisit
+				)
+			) {
+				continue;
+			}
+			$EVT_ID = $registration->event_ID();
+			$ticket = $registration->ticket();
+			if (! isset($tickets_remaining[ $ticket->ID() ])) {
+				$tickets_remaining[ $ticket->ID() ] = $ticket->remaining();
+			}
+			if ($tickets_remaining[ $ticket->ID() ] > 0) {
+				if (! isset($event_reg_count[ $EVT_ID ])) {
+					$event_reg_count[ $EVT_ID ] = 0;
+				}
+				$event_reg_count[ $EVT_ID ]++;
+				if (! isset($event_spaces_remaining[ $EVT_ID ])) {
+					$event_spaces_remaining[ $EVT_ID ] = $registration->event()->spaces_remaining_for_sale();
+				}
+			}
+			if ($revisit
+				&& ($tickets_remaining[ $ticket->ID() ] === 0
+					|| $event_reg_count[ $EVT_ID ] > $event_spaces_remaining[ $EVT_ID ]
+				)
+			) {
+				$ejected_registrations[ $REG_ID ] = $registration->event();
+				if ($registration->status_ID() !== EEM_Registration::status_id_wait_list) {
+					/** @type EE_Registration_Processor $registration_processor */
+					$registration_processor = EE_Registry::instance()->load_class('Registration_Processor');
+					// at this point, we should have enough details about the registrant to consider the registration
+					// NOT incomplete
+					$registration_processor->manually_update_registration_status(
+						$registration,
+						EEM_Registration::status_id_wait_list
+					);
+				}
+			}
+		}
+		return $ejected_registrations;
+	}
+
+
+	/**
+	 * _hide_reg_step_submit_button
+	 * removes the html for the reg step submit button
+	 * by replacing it with an empty string via filter callback
+	 *
+	 * @return void
+	 */
+	protected function _adjust_registration_status_if_event_old_sold()
+	{
+	}
+
+
+	/**
+	 * _hide_reg_step_submit_button
+	 * removes the html for the reg step submit button
+	 * by replacing it with an empty string via filter callback
+	 *
+	 * @return void
+	 */
+	protected function _hide_reg_step_submit_button_if_revisit()
+	{
+		if ($this->checkout->revisit) {
+			add_filter('FHEE__EE_SPCO_Reg_Step__reg_step_submit_button__sbmt_btn_html', '__return_empty_string');
+		}
+	}
+
+
+	/**
+	 * sold_out_events
+	 * displays notices regarding events that have sold out since hte registrant first signed up
+	 *
+	 * @param \EE_Event[] $sold_out_events_array
+	 * @return \EE_Form_Section_Proper
+	 * @throws \EE_Error
+	 */
+	private function _sold_out_events($sold_out_events_array = array())
+	{
+		// set some defaults
+		$this->checkout->selected_method_of_payment = 'events_sold_out';
+		$sold_out_events = '';
+		foreach ($sold_out_events_array as $sold_out_event) {
+			$sold_out_events .= EEH_HTML::li(
+				EEH_HTML::span(
+					'  ' . $sold_out_event->name(),
+					'',
+					'dashicons dashicons-marker ee-icon-size-16 pink-text'
+				)
+			);
+		}
+		return new EE_Form_Section_Proper(
+			array(
+				'layout_strategy' => new EE_Template_Layout(
+					array(
+						'layout_template_file' => SPCO_REG_STEPS_PATH
+												  . $this->_slug
+												  . DS
+												  . 'sold_out_events.template.php',
+						'template_args'        => apply_filters(
+							'FHEE__EE_SPCO_Reg_Step_Payment_Options___sold_out_events__template_args',
+							array(
+								'sold_out_events'     => $sold_out_events,
+								'sold_out_events_msg' => apply_filters(
+									'FHEE__EE_SPCO_Reg_Step_Payment_Options___sold_out_events__sold_out_events_msg',
+									sprintf(
+										esc_html__(
+											'It appears that the event you were about to make a payment for has sold out since you first registered. If you have already made a partial payment towards this event, please contact the event administrator for a refund.%3$s%3$s%1$sPlease note that availability can change at any time due to cancellations, so please check back again later if registration for this event(s) is important to you.%2$s',
+											'event_espresso'
+										),
+										'<strong>',
+										'</strong>',
+										'<br />'
+									)
+								),
+							)
+						),
+					)
+				),
+			)
+		);
+	}
+
+
+	/**
+	 * _insufficient_spaces_available
+	 * displays notices regarding events that do not have enough remaining spaces
+	 * to satisfy the current number of registrations looking to pay
+	 *
+	 * @param \EE_Event[] $insufficient_spaces_events_array
+	 * @return \EE_Form_Section_Proper
+	 * @throws \EE_Error
+	 */
+	private function _insufficient_spaces_available($insufficient_spaces_events_array = array())
+	{
+		// set some defaults
+		$this->checkout->selected_method_of_payment = 'invoice';
+		$insufficient_space_events = '';
+		foreach ($insufficient_spaces_events_array as $event) {
+			if ($event instanceof EE_Event) {
+				$insufficient_space_events .= EEH_HTML::li(
+					EEH_HTML::span(' ' . $event->name(), '', 'dashicons dashicons-marker ee-icon-size-16 pink-text')
+				);
+			}
+		}
+		return new EE_Form_Section_Proper(
+			array(
+				'subsections'     => array(
+					'default_hidden_inputs' => $this->reg_step_hidden_inputs(),
+					'extra_hidden_inputs'   => $this->_extra_hidden_inputs(),
+				),
+				'layout_strategy' => new EE_Template_Layout(
+					array(
+						'layout_template_file' => SPCO_REG_STEPS_PATH
+												  . $this->_slug
+												  . DS
+												  . 'sold_out_events.template.php',
+						'template_args'        => apply_filters(
+							'FHEE__EE_SPCO_Reg_Step_Payment_Options___insufficient_spaces_available__template_args',
+							array(
+								'sold_out_events'     => $insufficient_space_events,
+								'sold_out_events_msg' => apply_filters(
+									'FHEE__EE_SPCO_Reg_Step_Payment_Options___insufficient_spaces_available__insufficient_space_msg',
+									esc_html__(
+										'It appears that the event you were about to make a payment for has sold additional tickets since you first registered, and there are no longer enough spaces left to accommodate your selections. You may continue to pay and secure the available space(s) remaining, or simply cancel if you no longer wish to purchase. If you have already made a partial payment towards this event, please contact the event administrator for a refund.',
+										'event_espresso'
+									)
+								),
+							)
+						),
+					)
+				),
+			)
+		);
+	}
+
+
+	/**
+	 * registrations_requiring_pre_approval
+	 *
+	 * @param array $registrations_requiring_pre_approval
+	 * @return EE_Form_Section_Proper
+	 * @throws EE_Error
+	 * @throws \EventEspresso\core\exceptions\EntityNotFoundException
+	 */
+	private function _registrations_requiring_pre_approval($registrations_requiring_pre_approval = array())
+	{
+		$events_requiring_pre_approval = array();
+		foreach ($registrations_requiring_pre_approval as $registration) {
+			if ($registration instanceof EE_Registration && $registration->event() instanceof EE_Event) {
+				$events_requiring_pre_approval[ $registration->event()->ID() ] = EEH_HTML::li(
+					EEH_HTML::span(
+						'',
+						'',
+						'dashicons dashicons-marker ee-icon-size-16 orange-text'
+					)
+					. EEH_HTML::span($registration->event()->name(), '', 'orange-text')
+				);
+			}
+		}
+		return new EE_Form_Section_Proper(
+			array(
+				'layout_strategy' => new EE_Template_Layout(
+					array(
+						'layout_template_file' => SPCO_REG_STEPS_PATH
+												  . $this->_slug
+												  . DS
+												  . 'events_requiring_pre_approval.template.php', // layout_template
+						'template_args'        => apply_filters(
+							'FHEE__EE_SPCO_Reg_Step_Payment_Options___sold_out_events__template_args',
+							array(
+								'events_requiring_pre_approval'     => implode('', $events_requiring_pre_approval),
+								'events_requiring_pre_approval_msg' => apply_filters(
+									'FHEE__EE_SPCO_Reg_Step_Payment_Options___events_requiring_pre_approval__events_requiring_pre_approval_msg',
+									esc_html__(
+										'The following events do not require payment at this time and will not be billed during this transaction. Billing will only occur after the attendee has been approved by the event organizer. You will be notified when your registration has been processed. If this is a free event, then no billing will occur.',
+										'event_espresso'
+									)
+								),
+							)
+						),
+					)
+				),
+			)
+		);
+	}
+
+
+	/**
+	 * _no_payment_required
+	 *
+	 * @param \EE_Event[] $registrations_for_free_events
+	 * @return \EE_Form_Section_Proper
+	 * @throws \EE_Error
+	 */
+	private function _no_payment_required($registrations_for_free_events = array())
+	{
+		// set some defaults
+		$this->checkout->selected_method_of_payment = 'no_payment_required';
+		// generate no_payment_required form
+		return new EE_Form_Section_Proper(
+			array(
+				'layout_strategy' => new EE_Template_Layout(
+					array(
+						'layout_template_file' => SPCO_REG_STEPS_PATH
+												  . $this->_slug
+												  . DS
+												  . 'no_payment_required.template.php', // layout_template
+						'template_args'        => apply_filters(
+							'FHEE__EE_SPCO_Reg_Step_Payment_Options___no_payment_required__template_args',
+							array(
+								'revisit'                       => $this->checkout->revisit,
+								'registrations'                 => array(),
+								'ticket_count'                  => array(),
+								'registrations_for_free_events' => $registrations_for_free_events,
+								'no_payment_required_msg'       => EEH_HTML::p(
+									esc_html__('This is a free event, so no billing will occur.', 'event_espresso')
+								),
+							)
+						),
+					)
+				),
+			)
+		);
+	}
+
+
+	/**
+	 * _display_payment_options
+	 *
+	 * @param string $transaction_details
+	 * @return EE_Form_Section_Proper
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _display_payment_options($transaction_details = '')
+	{
+		// has method_of_payment been set by no-js user?
+		$this->checkout->selected_method_of_payment = $this->_get_selected_method_of_payment();
+		// build payment options form
+		return apply_filters(
+			'FHEE__EE_SPCO_Reg_Step_Payment_Options___display_payment_options__payment_options_form',
+			new EE_Form_Section_Proper(
+				array(
+					'subsections'     => array(
+						'before_payment_options' => apply_filters(
+							'FHEE__EE_SPCO_Reg_Step_Payment_Options___display_payment_options__before_payment_options',
+							new EE_Form_Section_Proper(
+								array('layout_strategy' => new EE_Div_Per_Section_Layout())
+							)
+						),
+						'payment_options'        => $this->_setup_payment_options(),
+						'after_payment_options'  => apply_filters(
+							'FHEE__EE_SPCO_Reg_Step_Payment_Options___display_payment_options__after_payment_options',
+							new EE_Form_Section_Proper(
+								array('layout_strategy' => new EE_Div_Per_Section_Layout())
+							)
+						),
+					),
+					'layout_strategy' => new EE_Template_Layout(
+						array(
+							'layout_template_file' => $this->_template,
+							'template_args'        => apply_filters(
+								'FHEE__EE_SPCO_Reg_Step_Payment_Options___display_payment_options__template_args',
+								array(
+									'reg_count'                 => $this->line_item_display->total_items(),
+									'transaction_details'       => $transaction_details,
+									'available_payment_methods' => array(),
+								)
+							),
+						)
+					),
+				)
+			)
+		);
+	}
+
+
+	/**
+	 * _extra_hidden_inputs
+	 *
+	 * @param bool $no_payment_required
+	 * @return \EE_Form_Section_Proper
+	 * @throws \EE_Error
+	 */
+	private function _extra_hidden_inputs($no_payment_required = true)
+	{
+		return new EE_Form_Section_Proper(
+			array(
+				'html_id'         => 'ee-' . $this->slug() . '-extra-hidden-inputs',
+				'layout_strategy' => new EE_Div_Per_Section_Layout(),
+				'subsections'     => array(
+					'spco_no_payment_required' => new EE_Hidden_Input(
+						array(
+							'normalization_strategy' => new EE_Boolean_Normalization(),
+							'html_name'              => 'spco_no_payment_required',
+							'html_id'                => 'spco-no-payment-required-payment_options',
+							'default'                => $no_payment_required,
+						)
+					),
+					'spco_transaction_id'      => new EE_Fixed_Hidden_Input(
+						array(
+							'normalization_strategy' => new EE_Int_Normalization(),
+							'html_name'              => 'spco_transaction_id',
+							'html_id'                => 'spco-transaction-id',
+							'default'                => $this->checkout->transaction->ID(),
+						)
+					),
+				),
+			)
+		);
+	}
+
+
+	/**
+	 *    _apply_registration_payments_to_amount_owing
+	 *
+	 * @access protected
+	 * @param array $registrations
+	 * @throws EE_Error
+	 */
+	protected function _apply_registration_payments_to_amount_owing(array $registrations)
+	{
+		$payments = array();
+		foreach ($registrations as $registration) {
+			if ($registration instanceof EE_Registration && $registration->owes_monies_and_can_pay()) {
+				$payments += $registration->registration_payments();
+			}
+		}
+		if (! empty($payments)) {
+			foreach ($payments as $payment) {
+				if ($payment instanceof EE_Registration_Payment) {
+					$this->checkout->amount_owing -= $payment->amount();
+				}
+			}
+		}
+	}
+
+
+	/**
+	 *    _reset_selected_method_of_payment
+	 *
+	 * @access    private
+	 * @param    bool $force_reset
+	 * @return void
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _reset_selected_method_of_payment($force_reset = false)
+	{
+		$reset_payment_method = $force_reset
+			? true
+			: sanitize_text_field(EE_Registry::instance()->REQ->get('reset_payment_method', false));
+		if ($reset_payment_method) {
+			$this->checkout->selected_method_of_payment = null;
+			$this->checkout->payment_method = null;
+			$this->checkout->billing_form = null;
+			$this->_save_selected_method_of_payment();
+		}
+	}
+
+
+	/**
+	 * _save_selected_method_of_payment
+	 * stores the selected_method_of_payment in the session
+	 * so that it's available for all subsequent requests including AJAX
+	 *
+	 * @access        private
+	 * @param string $selected_method_of_payment
+	 * @return void
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _save_selected_method_of_payment($selected_method_of_payment = '')
+	{
+		$selected_method_of_payment = ! empty($selected_method_of_payment)
+			? $selected_method_of_payment
+			: $this->checkout->selected_method_of_payment;
+		EE_Registry::instance()->SSN->set_session_data(
+			array('selected_method_of_payment' => $selected_method_of_payment)
+		);
+	}
+
+
+	/**
+	 * _setup_payment_options
+	 *
+	 * @return EE_Form_Section_Proper
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	public function _setup_payment_options()
+	{
+		// load payment method classes
+		$this->checkout->available_payment_methods = $this->_get_available_payment_methods();
+		if (empty($this->checkout->available_payment_methods)) {
+			EE_Error::add_error(
+				apply_filters(
+					'FHEE__EE_SPCO_Reg_Step_Payment_Options___setup_payment_options__error_message_no_payment_methods',
+					sprintf(
+						esc_html__(
+							'Sorry, you cannot complete your purchase because a payment method is not active.%1$s Please contact %2$s for assistance and provide a description of the problem.',
+							'event_espresso'
+						),
+						'<br>',
+						EE_Registry::instance()->CFG->organization->get_pretty('email')
+					)
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+		}
+		// switch up header depending on number of available payment methods
+		$payment_method_header = count($this->checkout->available_payment_methods) > 1
+			? apply_filters(
+				'FHEE__registration_page_payment_options__method_of_payment_hdr',
+				esc_html__('Please Select Your Method of Payment', 'event_espresso')
+			)
+			: apply_filters(
+				'FHEE__registration_page_payment_options__method_of_payment_hdr',
+				esc_html__('Method of Payment', 'event_espresso')
+			);
+		$available_payment_methods = array(
+			// display the "Payment Method" header
+			'payment_method_header' => new EE_Form_Section_HTML(
+				apply_filters(
+					'FHEE__EE_SPCO_Reg_Step_Payment_Options___setup_payment_options__payment_method_header',
+					EEH_HTML::h4($payment_method_header, 'method-of-payment-hdr'),
+					$payment_method_header
+				)
+			),
+		);
+		// the list of actual payment methods ( invoice, paypal, etc ) in a  ( slug => HTML )  format
+		$available_payment_method_options = array();
+		$default_payment_method_option = array();
+		// additional instructions to be displayed and hidden below payment methods (adding a clearing div to start)
+		$payment_methods_billing_info = array(
+			new EE_Form_Section_HTML(
+				EEH_HTML::div('<br />', '', '', 'clear:both;')
+			),
+		);
+		// loop through payment methods
+		foreach ($this->checkout->available_payment_methods as $payment_method) {
+			if ($payment_method instanceof EE_Payment_Method) {
+				$payment_method_button = EEH_HTML::img(
+					$payment_method->button_url(),
+					$payment_method->name(),
+					'spco-payment-method-' . $payment_method->slug() . '-btn-img',
+					'spco-payment-method-btn-img'
+				);
+				// check if any payment methods are set as default
+				// if payment method is already selected OR nothing is selected and this payment method should be
+				// open_by_default
+				if (($this->checkout->selected_method_of_payment === $payment_method->slug())
+					|| (! $this->checkout->selected_method_of_payment && $payment_method->open_by_default())
+				) {
+					$this->checkout->selected_method_of_payment = $payment_method->slug();
+					$this->_save_selected_method_of_payment();
+					$default_payment_method_option[ $payment_method->slug() ] = $payment_method_button;
+				} else {
+					$available_payment_method_options[ $payment_method->slug() ] = $payment_method_button;
+				}
+				$payment_methods_billing_info[ $payment_method->slug(
+				) . '-info' ] = $this->_payment_method_billing_info(
+					$payment_method
+				);
+			}
+		}
+		// prepend available_payment_method_options with default_payment_method_option so that it appears first in list
+		// of PMs
+		$available_payment_method_options = $default_payment_method_option + $available_payment_method_options;
+		// now generate the actual form  inputs
+		$available_payment_methods['available_payment_methods'] = $this->_available_payment_method_inputs(
+			$available_payment_method_options
+		);
+		$available_payment_methods += $payment_methods_billing_info;
+		// build the available payment methods form
+		return new EE_Form_Section_Proper(
+			array(
+				'html_id'         => 'spco-available-methods-of-payment-dv',
+				'subsections'     => $available_payment_methods,
+				'layout_strategy' => new EE_Div_Per_Section_Layout(),
+			)
+		);
+	}
+
+
+	/**
+	 * _get_available_payment_methods
+	 *
+	 * @return EE_Payment_Method[]
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	protected function _get_available_payment_methods()
+	{
+		if (! empty($this->checkout->available_payment_methods)) {
+			return $this->checkout->available_payment_methods;
+		}
+		$available_payment_methods = array();
+		// load EEM_Payment_Method
+		EE_Registry::instance()->load_model('Payment_Method');
+		/** @type EEM_Payment_Method $EEM_Payment_Method */
+		$EEM_Payment_Method = EE_Registry::instance()->LIB->EEM_Payment_Method;
+		// get all active payment methods
+		$payment_methods = $EEM_Payment_Method->get_all_for_transaction(
+			$this->checkout->transaction,
+			EEM_Payment_Method::scope_cart
+		);
+		foreach ($payment_methods as $payment_method) {
+			if ($payment_method instanceof EE_Payment_Method) {
+				$available_payment_methods[ $payment_method->slug() ] = $payment_method;
+			}
+		}
+		return $available_payment_methods;
+	}
+
+
+	/**
+	 *    _available_payment_method_inputs
+	 *
+	 * @access    private
+	 * @param    array $available_payment_method_options
+	 * @return    \EE_Form_Section_Proper
+	 */
+	private function _available_payment_method_inputs($available_payment_method_options = array())
+	{
+		// generate inputs
+		return new EE_Form_Section_Proper(
+			array(
+				'html_id'         => 'ee-available-payment-method-inputs',
+				'layout_strategy' => new EE_Div_Per_Section_Layout(),
+				'subsections'     => array(
+					'' => new EE_Radio_Button_Input(
+						$available_payment_method_options,
+						array(
+							'html_name'          => 'selected_method_of_payment',
+							'html_class'         => 'spco-payment-method',
+							'default'            => $this->checkout->selected_method_of_payment,
+							'label_size'         => 11,
+							'enforce_label_size' => true,
+						)
+					),
+				),
+			)
+		);
+	}
+
+
+	/**
+	 *    _payment_method_billing_info
+	 *
+	 * @access    private
+	 * @param    EE_Payment_Method $payment_method
+	 * @return EE_Form_Section_Proper
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _payment_method_billing_info(EE_Payment_Method $payment_method)
+	{
+		$currently_selected = $this->checkout->selected_method_of_payment === $payment_method->slug()
+			? true
+			: false;
+		// generate the billing form for payment method
+		$billing_form = $currently_selected
+			? $this->_get_billing_form_for_payment_method($payment_method)
+			: new EE_Form_Section_HTML();
+		$this->checkout->billing_form = $currently_selected
+			? $billing_form
+			: $this->checkout->billing_form;
+		// it's all in the details
+		$info_html = EEH_HTML::h3(
+			esc_html__('Important information regarding your payment', 'event_espresso'),
+			'',
+			'spco-payment-method-hdr'
+		);
+		// add some info regarding the step, either from what's saved in the admin,
+		// or a default string depending on whether the PM has a billing form or not
+		if ($payment_method->description()) {
+			$payment_method_info = $payment_method->description();
+		} elseif ($billing_form instanceof EE_Billing_Info_Form) {
+			$payment_method_info = sprintf(
+				esc_html__(
+					'Please provide the following billing information, then click the "%1$s" button below in order to proceed.',
+					'event_espresso'
+				),
+				$this->submit_button_text()
+			);
+		} else {
+			$payment_method_info = sprintf(
+				esc_html__('Please click the "%1$s" button below in order to proceed.', 'event_espresso'),
+				$this->submit_button_text()
+			);
+		}
+		$info_html .= EEH_HTML::div(
+			apply_filters(
+				'FHEE__EE_SPCO_Reg_Step_Payment_Options___payment_method_billing_info__payment_method_info',
+				$payment_method_info
+			),
+			'',
+			'spco-payment-method-desc ee-attention'
+		);
+		return new EE_Form_Section_Proper(
+			array(
+				'html_id'         => 'spco-payment-method-info-' . $payment_method->slug(),
+				'html_class'      => 'spco-payment-method-info-dv',
+				// only display the selected or default PM
+				'html_style'      => $currently_selected ? '' : 'display:none;',
+				'layout_strategy' => new EE_Div_Per_Section_Layout(),
+				'subsections'     => array(
+					'info'         => new EE_Form_Section_HTML($info_html),
+					'billing_form' => $currently_selected ? $billing_form : new EE_Form_Section_HTML(),
+				),
+			)
+		);
+	}
+
+
+	/**
+	 * get_billing_form_html_for_payment_method
+	 *
+	 * @access public
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	public function get_billing_form_html_for_payment_method()
+	{
+		// how have they chosen to pay?
+		$this->checkout->selected_method_of_payment = $this->_get_selected_method_of_payment(true);
+		$this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment();
+		if (! $this->checkout->payment_method instanceof EE_Payment_Method) {
+			return false;
+		}
+		if (apply_filters(
+			'FHEE__EE_SPCO_Reg_Step_Payment_Options__registration_checkout__selected_payment_method__display_success',
+			false
+		)) {
+			EE_Error::add_success(
+				apply_filters(
+					'FHEE__Single_Page_Checkout__registration_checkout__selected_payment_method',
+					sprintf(
+						esc_html__(
+							'You have selected "%s" as your method of payment. Please note the important payment information below.',
+							'event_espresso'
+						),
+						$this->checkout->payment_method->name()
+					)
+				)
+			);
+		}
+		// now generate billing form for selected method of payment
+		$payment_method_billing_form = $this->_get_billing_form_for_payment_method($this->checkout->payment_method);
+		// fill form with attendee info if applicable
+		if ($payment_method_billing_form instanceof EE_Billing_Attendee_Info_Form
+			&& $this->checkout->transaction_has_primary_registrant()
+		) {
+			$payment_method_billing_form->populate_from_attendee(
+				$this->checkout->transaction->primary_registration()->attendee()
+			);
+		}
+		// and debug content
+		if ($payment_method_billing_form instanceof EE_Billing_Info_Form
+			&& $this->checkout->payment_method->type_obj() instanceof EE_PMT_Base
+		) {
+			$payment_method_billing_form =
+				$this->checkout->payment_method->type_obj()->apply_billing_form_debug_settings(
+					$payment_method_billing_form
+				);
+		}
+		$billing_info = $payment_method_billing_form instanceof EE_Form_Section_Proper
+			? $payment_method_billing_form->get_html()
+			: '';
+		$this->checkout->json_response->set_return_data(array('payment_method_info' => $billing_info));
+		// localize validation rules for main form
+		$this->checkout->current_step->reg_form->localize_validation_rules();
+		$this->checkout->json_response->add_validation_rules(EE_Form_Section_Proper::js_localization());
+		return true;
+	}
+
+
+	/**
+	 * _get_billing_form_for_payment_method
+	 *
+	 * @access private
+	 * @param EE_Payment_Method $payment_method
+	 * @return EE_Billing_Info_Form|EE_Form_Section_HTML
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _get_billing_form_for_payment_method(EE_Payment_Method $payment_method)
+	{
+		$billing_form = $payment_method->type_obj()->billing_form(
+			$this->checkout->transaction,
+			array('amount_owing' => $this->checkout->amount_owing)
+		);
+		if ($billing_form instanceof EE_Billing_Info_Form) {
+			if (apply_filters(
+				'FHEE__EE_SPCO_Reg_Step_Payment_Options__registration_checkout__selected_payment_method__display_success',
+				false
+			)
+				&& EE_Registry::instance()->REQ->is_set('payment_method')
+			) {
+				EE_Error::add_success(
+					apply_filters(
+						'FHEE__Single_Page_Checkout__registration_checkout__selected_payment_method',
+						sprintf(
+							esc_html__(
+								'You have selected "%s" as your method of payment. Please note the important payment information below.',
+								'event_espresso'
+							),
+							$payment_method->name()
+						)
+					)
+				);
+			}
+			return apply_filters(
+				'FHEE__EE_SPCO_Reg_Step_Payment_Options___get_billing_form_for_payment_method__billing_form',
+				$billing_form,
+				$payment_method
+			);
+		}
+		// no actual billing form, so return empty HTML form section
+		return new EE_Form_Section_HTML();
+	}
+
+
+	/**
+	 * _get_selected_method_of_payment
+	 *
+	 * @access private
+	 * @param boolean $required whether to throw an error if the "selected_method_of_payment"
+	 *                          is not found in the incoming request
+	 * @param string  $request_param
+	 * @return NULL|string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _get_selected_method_of_payment(
+		$required = false,
+		$request_param = 'selected_method_of_payment'
+	) {
+		// is selected_method_of_payment set in the request ?
+		$selected_method_of_payment = EE_Registry::instance()->REQ->get($request_param, false);
+		if ($selected_method_of_payment) {
+			// sanitize it
+			$selected_method_of_payment = is_array($selected_method_of_payment)
+				? array_shift($selected_method_of_payment)
+				: $selected_method_of_payment;
+			$selected_method_of_payment = sanitize_text_field($selected_method_of_payment);
+			// store it in the session so that it's available for all subsequent requests including AJAX
+			$this->_save_selected_method_of_payment($selected_method_of_payment);
+		} else {
+			// or is is set in the session ?
+			$selected_method_of_payment = EE_Registry::instance()->SSN->get_session_data(
+				'selected_method_of_payment'
+			);
+		}
+		// do ya really really gotta have it?
+		if (empty($selected_method_of_payment) && $required) {
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'The selected method of payment could not be determined.%sPlease ensure that you have selected one before proceeding.%sIf you continue to experience difficulties, then refresh your browser and try again, or contact %s for assistance.',
+						'event_espresso'
+					),
+					'<br/>',
+					'<br/>',
+					EE_Registry::instance()->CFG->organization->get_pretty('email')
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return null;
+		}
+		return $selected_method_of_payment;
+	}
+
+
+
+
+
+
+	/********************************************************************************************************/
+	/***********************************  SWITCH PAYMENT METHOD  ************************************/
+	/********************************************************************************************************/
+	/**
+	 * switch_payment_method
+	 *
+	 * @access public
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	public function switch_payment_method()
+	{
+		if (! $this->_verify_payment_method_is_set()) {
+			return false;
+		}
+		if (apply_filters(
+			'FHEE__EE_SPCO_Reg_Step_Payment_Options__registration_checkout__selected_payment_method__display_success',
+			false
+		)) {
+			EE_Error::add_success(
+				apply_filters(
+					'FHEE__Single_Page_Checkout__registration_checkout__selected_payment_method',
+					sprintf(
+						esc_html__(
+							'You have selected "%s" as your method of payment. Please note the important payment information below.',
+							'event_espresso'
+						),
+						$this->checkout->payment_method->name()
+					)
+				)
+			);
+		}
+		// generate billing form for selected method of payment if it hasn't been done already
+		if ($this->checkout->payment_method->type_obj()->has_billing_form()) {
+			$this->checkout->billing_form = $this->_get_billing_form_for_payment_method(
+				$this->checkout->payment_method
+			);
+		}
+		// fill form with attendee info if applicable
+		if (apply_filters(
+			'FHEE__populate_billing_form_fields_from_attendee',
+			(
+				$this->checkout->billing_form instanceof EE_Billing_Attendee_Info_Form
+				&& $this->checkout->transaction_has_primary_registrant()
+			),
+			$this->checkout->billing_form,
+			$this->checkout->transaction
+		)
+		) {
+			$this->checkout->billing_form->populate_from_attendee(
+				$this->checkout->transaction->primary_registration()->attendee()
+			);
+		}
+		// and debug content
+		if ($this->checkout->billing_form instanceof EE_Billing_Info_Form
+			&& $this->checkout->payment_method->type_obj() instanceof EE_PMT_Base
+		) {
+			$this->checkout->billing_form =
+				$this->checkout->payment_method->type_obj()->apply_billing_form_debug_settings(
+					$this->checkout->billing_form
+				);
+		}
+		// get html and validation rules for form
+		if ($this->checkout->billing_form instanceof EE_Form_Section_Proper) {
+			$this->checkout->json_response->set_return_data(
+				array('payment_method_info' => $this->checkout->billing_form->get_html())
+			);
+			// localize validation rules for main form
+			$this->checkout->billing_form->localize_validation_rules(true);
+			$this->checkout->json_response->add_validation_rules(EE_Form_Section_Proper::js_localization());
+		} else {
+			$this->checkout->json_response->set_return_data(array('payment_method_info' => ''));
+		}
+		// prevents advancement to next step
+		$this->checkout->continue_reg = false;
+		return true;
+	}
+
+
+	/**
+	 * _verify_payment_method_is_set
+	 *
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	protected function _verify_payment_method_is_set()
+	{
+		// generate billing form for selected method of payment if it hasn't been done already
+		if (empty($this->checkout->selected_method_of_payment)) {
+			// how have they chosen to pay?
+			$this->checkout->selected_method_of_payment = $this->_get_selected_method_of_payment(true);
+		} else {
+			// choose your own adventure based on method_of_payment
+			switch ($this->checkout->selected_method_of_payment) {
+				case 'events_sold_out':
+					EE_Error::add_attention(
+						apply_filters(
+							'FHEE__EE_SPCO_Reg_Step_Payment_Options___verify_payment_method_is_set__sold_out_events_msg',
+							esc_html__(
+								'It appears that the event you were about to make a payment for has sold out since this form first loaded. Please contact the event administrator if you believe this is an error.',
+								'event_espresso'
+							)
+						),
+						__FILE__,
+						__FUNCTION__,
+						__LINE__
+					);
+					return false;
+					break;
+				case 'payments_closed':
+					EE_Error::add_attention(
+						apply_filters(
+							'FHEE__EE_SPCO_Reg_Step_Payment_Options___verify_payment_method_is_set__payments_closed_msg',
+							esc_html__(
+								'It appears that the event you were about to make a payment for is not accepting payments at this time. Please contact the event administrator if you believe this is an error.',
+								'event_espresso'
+							)
+						),
+						__FILE__,
+						__FUNCTION__,
+						__LINE__
+					);
+					return false;
+					break;
+				case 'no_payment_required':
+					EE_Error::add_attention(
+						apply_filters(
+							'FHEE__EE_SPCO_Reg_Step_Payment_Options___verify_payment_method_is_set__no_payment_required_msg',
+							esc_html__(
+								'It appears that the event you were about to make a payment for does not require payment. Please contact the event administrator if you believe this is an error.',
+								'event_espresso'
+							)
+						),
+						__FILE__,
+						__FUNCTION__,
+						__LINE__
+					);
+					return false;
+					break;
+				default:
+			}
+		}
+		// verify payment method
+		if (! $this->checkout->payment_method instanceof EE_Payment_Method) {
+			// get payment method for selected method of payment
+			$this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment();
+		}
+		return $this->checkout->payment_method instanceof EE_Payment_Method ? true : false;
+	}
+
+
+
+	/********************************************************************************************************/
+	/***************************************  SAVE PAYER DETAILS  ****************************************/
+	/********************************************************************************************************/
+	/**
+	 * save_payer_details_via_ajax
+	 *
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws RuntimeException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	public function save_payer_details_via_ajax()
+	{
+		if (! $this->_verify_payment_method_is_set()) {
+			return;
+		}
+		// generate billing form for selected method of payment if it hasn't been done already
+		if ($this->checkout->payment_method->type_obj()->has_billing_form()) {
+			$this->checkout->billing_form = $this->_get_billing_form_for_payment_method(
+				$this->checkout->payment_method
+			);
+		}
+		// generate primary attendee from payer info if applicable
+		if (! $this->checkout->transaction_has_primary_registrant()) {
+			$attendee = $this->_create_attendee_from_request_data();
+			if ($attendee instanceof EE_Attendee) {
+				foreach ($this->checkout->transaction->registrations() as $registration) {
+					if ($registration->is_primary_registrant()) {
+						$this->checkout->primary_attendee_obj = $attendee;
+						$registration->_add_relation_to($attendee, 'Attendee');
+						$registration->set_attendee_id($attendee->ID());
+						$registration->update_cache_after_object_save('Attendee', $attendee);
+					}
+				}
+			}
+		}
+	}
+
+
+	/**
+	 * create_attendee_from_request_data
+	 * uses info from alternate GET or POST data (such as AJAX) to create a new attendee
+	 *
+	 * @return EE_Attendee
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	protected function _create_attendee_from_request_data()
+	{
+		// get State ID
+		$STA_ID = ! empty($_REQUEST['state']) ? sanitize_text_field($_REQUEST['state']) : '';
+		if (! empty($STA_ID)) {
+			// can we get state object from name ?
+			EE_Registry::instance()->load_model('State');
+			$state = EEM_State::instance()->get_col(array(array('STA_name' => $STA_ID), 'limit' => 1), 'STA_ID');
+			$STA_ID = is_array($state) && ! empty($state) ? reset($state) : $STA_ID;
+		}
+		// get Country ISO
+		$CNT_ISO = ! empty($_REQUEST['country']) ? sanitize_text_field($_REQUEST['country']) : '';
+		if (! empty($CNT_ISO)) {
+			// can we get country object from name ?
+			EE_Registry::instance()->load_model('Country');
+			$country = EEM_Country::instance()->get_col(
+				array(array('CNT_name' => $CNT_ISO), 'limit' => 1),
+				'CNT_ISO'
+			);
+			$CNT_ISO = is_array($country) && ! empty($country) ? reset($country) : $CNT_ISO;
+		}
+		// grab attendee data
+		$attendee_data = array(
+			'ATT_fname'    => ! empty($_REQUEST['first_name']) ? sanitize_text_field($_REQUEST['first_name']) : '',
+			'ATT_lname'    => ! empty($_REQUEST['last_name']) ? sanitize_text_field($_REQUEST['last_name']) : '',
+			'ATT_email'    => ! empty($_REQUEST['email']) ? sanitize_email($_REQUEST['email']) : '',
+			'ATT_address'  => ! empty($_REQUEST['address']) ? sanitize_text_field($_REQUEST['address']) : '',
+			'ATT_address2' => ! empty($_REQUEST['address2']) ? sanitize_text_field($_REQUEST['address2']) : '',
+			'ATT_city'     => ! empty($_REQUEST['city']) ? sanitize_text_field($_REQUEST['city']) : '',
+			'STA_ID'       => $STA_ID,
+			'CNT_ISO'      => $CNT_ISO,
+			'ATT_zip'      => ! empty($_REQUEST['zip']) ? sanitize_text_field($_REQUEST['zip']) : '',
+			'ATT_phone'    => ! empty($_REQUEST['phone']) ? sanitize_text_field($_REQUEST['phone']) : '',
+		);
+		// validate the email address since it is the most important piece of info
+		if (empty($attendee_data['ATT_email']) || $attendee_data['ATT_email'] !== $_REQUEST['email']) {
+			EE_Error::add_error(
+				esc_html__('An invalid email address was submitted.', 'event_espresso'),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+		}
+		// does this attendee already exist in the db ? we're searching using a combination of first name, last name,
+		// AND email address
+		if (! empty($attendee_data['ATT_fname'])
+			&& ! empty($attendee_data['ATT_lname'])
+			&& ! empty($attendee_data['ATT_email'])
+		) {
+			$existing_attendee = EE_Registry::instance()->LIB->EEM_Attendee->find_existing_attendee(
+				array(
+					'ATT_fname' => $attendee_data['ATT_fname'],
+					'ATT_lname' => $attendee_data['ATT_lname'],
+					'ATT_email' => $attendee_data['ATT_email'],
+				)
+			);
+			if ($existing_attendee instanceof EE_Attendee) {
+				return $existing_attendee;
+			}
+		}
+		// no existing attendee? kk let's create a new one
+		// kinda lame, but we need a first and last name to create an attendee, so use the email address if those
+		// don't exist
+		$attendee_data['ATT_fname'] = ! empty($attendee_data['ATT_fname'])
+			? $attendee_data['ATT_fname']
+			: $attendee_data['ATT_email'];
+		$attendee_data['ATT_lname'] = ! empty($attendee_data['ATT_lname'])
+			? $attendee_data['ATT_lname']
+			: $attendee_data['ATT_email'];
+		return EE_Attendee::new_instance($attendee_data);
+	}
+
+
+
+	/********************************************************************************************************/
+	/****************************************  PROCESS REG STEP  *****************************************/
+	/********************************************************************************************************/
+	/**
+	 * process_reg_step
+	 *
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\EntityNotFoundException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 * @throws \EventEspresso\core\exceptions\InvalidStatusException
+	 */
+	public function process_reg_step()
+	{
+		// how have they chosen to pay?
+		$this->checkout->selected_method_of_payment = $this->checkout->transaction->is_free()
+			? 'no_payment_required'
+			: $this->_get_selected_method_of_payment(true);
+		// choose your own adventure based on method_of_payment
+		switch ($this->checkout->selected_method_of_payment) {
+			case 'events_sold_out':
+				$this->checkout->redirect = true;
+				$this->checkout->redirect_url = $this->checkout->cancel_page_url;
+				$this->checkout->json_response->set_redirect_url($this->checkout->redirect_url);
+				// mark this reg step as completed
+				$this->set_completed();
+				return false;
+				break;
+
+			case 'payments_closed':
+				if (apply_filters(
+					'FHEE__EE_SPCO_Reg_Step_Payment_Options__process_reg_step__payments_closed__display_success',
+					false
+				)) {
+					EE_Error::add_success(
+						esc_html__('no payment required at this time.', 'event_espresso'),
+						__FILE__,
+						__FUNCTION__,
+						__LINE__
+					);
+				}
+				// mark this reg step as completed
+				$this->set_completed();
+				return true;
+				break;
+
+			case 'no_payment_required':
+				if (apply_filters(
+					'FHEE__EE_SPCO_Reg_Step_Payment_Options__process_reg_step__no_payment_required__display_success',
+					false
+				)) {
+					EE_Error::add_success(
+						esc_html__('no payment required.', 'event_espresso'),
+						__FILE__,
+						__FUNCTION__,
+						__LINE__
+					);
+				}
+				// mark this reg step as completed
+				$this->set_completed();
+				return true;
+				break;
+
+			default:
+				$registrations = EE_Registry::instance()->SSN->checkout()->transaction->registrations(
+					EE_Registry::instance()->SSN->checkout()->reg_cache_where_params
+				);
+				$ejected_registrations = EE_SPCO_Reg_Step_Payment_Options::find_registrations_that_lost_their_space(
+					$registrations,
+					EE_Registry::instance()->SSN->checkout()->revisit
+				);
+				// calculate difference between the two arrays
+				$registrations = array_diff($registrations, $ejected_registrations);
+				if (empty($registrations)) {
+					$this->_redirect_because_event_sold_out();
+					return false;
+				}
+				$payment_successful = $this->_process_payment();
+				if ($payment_successful) {
+					$this->checkout->continue_reg = true;
+					$this->_maybe_set_completed($this->checkout->payment_method);
+				} else {
+					$this->checkout->continue_reg = false;
+				}
+				return $payment_successful;
+		}
+	}
+
+
+	/**
+	 * _redirect_because_event_sold_out
+	 *
+	 * @access protected
+	 * @return void
+	 */
+	protected function _redirect_because_event_sold_out()
+	{
+		$this->checkout->continue_reg = false;
+		// set redirect URL
+		$this->checkout->redirect_url = add_query_arg(
+			array('e_reg_url_link' => $this->checkout->reg_url_link),
+			$this->checkout->current_step->reg_step_url()
+		);
+		$this->checkout->json_response->set_redirect_url($this->checkout->redirect_url);
+	}
+
+
+	/**
+	 * _maybe_set_completed
+	 *
+	 * @access protected
+	 * @param \EE_Payment_Method $payment_method
+	 * @return void
+	 * @throws \EE_Error
+	 */
+	protected function _maybe_set_completed(EE_Payment_Method $payment_method)
+	{
+		switch ($payment_method->type_obj()->payment_occurs()) {
+			case EE_PMT_Base::offsite:
+				break;
+			case EE_PMT_Base::onsite:
+			case EE_PMT_Base::offline:
+				// mark this reg step as completed
+				$this->set_completed();
+				break;
+		}
+	}
+
+
+	/**
+	 *    update_reg_step
+	 *    this is the final step after a user  revisits the site to retry a payment
+	 *
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\EntityNotFoundException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 * @throws \EventEspresso\core\exceptions\InvalidStatusException
+	 */
+	public function update_reg_step()
+	{
+		$success = true;
+		// if payment required
+		if ($this->checkout->transaction->total() > 0) {
+			do_action(
+				'AHEE__EE_Single_Page_Checkout__process_finalize_registration__before_gateway',
+				$this->checkout->transaction
+			);
+			// attempt payment via payment method
+			$success = $this->process_reg_step();
+		}
+		if ($success && ! $this->checkout->redirect) {
+			$this->checkout->cart->get_grand_total()->save_this_and_descendants_to_txn(
+				$this->checkout->transaction->ID()
+			);
+			// set return URL
+			$this->checkout->redirect_url = add_query_arg(
+				array('e_reg_url_link' => $this->checkout->reg_url_link),
+				$this->checkout->thank_you_page_url
+			);
+		}
+		return $success;
+	}
+
+
+	/**
+	 *    _process_payment
+	 *
+	 * @access private
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws RuntimeException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _process_payment()
+	{
+		// basically confirm that the event hasn't sold out since they hit the page
+		if (! $this->_last_second_ticket_verifications()) {
+			return false;
+		}
+		// ya gotta make a choice man
+		if (empty($this->checkout->selected_method_of_payment)) {
+			$this->checkout->json_response->set_plz_select_method_of_payment(
+				esc_html__('Please select a method of payment before proceeding.', 'event_espresso')
+			);
+			return false;
+		}
+		// get EE_Payment_Method object
+		if (! $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment()) {
+			return false;
+		}
+		// setup billing form
+		if ($this->checkout->payment_method->is_on_site()) {
+			$this->checkout->billing_form = $this->_get_billing_form_for_payment_method(
+				$this->checkout->payment_method
+			);
+			// bad billing form ?
+			if (! $this->_billing_form_is_valid()) {
+				return false;
+			}
+		}
+		// ensure primary registrant has been fully processed
+		if (! $this->_setup_primary_registrant_prior_to_payment()) {
+			return false;
+		}
+		// if session is close to expiring (under 10 minutes by default)
+		if ((time() - EE_Registry::instance()->SSN->expiration()) < EE_Registry::instance()->SSN->extension()) {
+			// add some time to session expiration so that payment can be completed
+			EE_Registry::instance()->SSN->extend_expiration();
+		}
+		/** @type EE_Transaction_Processor $transaction_processor */
+		// $transaction_processor = EE_Registry::instance()->load_class( 'Transaction_Processor' );
+		// in case a registrant leaves to an Off-Site Gateway and never returns, we want to approve any registrations
+		// for events with a default reg status of Approved
+		// $transaction_processor->toggle_registration_statuses_for_default_approved_events(
+		//      $this->checkout->transaction, $this->checkout->reg_cache_where_params
+		// );
+		// attempt payment
+		$payment = $this->_attempt_payment($this->checkout->payment_method);
+		// process results
+		$payment = $this->_validate_payment($payment);
+		$payment = $this->_post_payment_processing($payment);
+		// verify payment
+		if ($payment instanceof EE_Payment) {
+			// store that for later
+			$this->checkout->payment = $payment;
+			// we can also consider the TXN to not have been failed, so temporarily upgrade it's status to abandoned
+			$this->checkout->transaction->toggle_failed_transaction_status();
+			$payment_status = $payment->status();
+			if ($payment_status === EEM_Payment::status_id_approved
+				|| $payment_status === EEM_Payment::status_id_pending
+			) {
+				return true;
+			} else {
+				return false;
+			}
+		} elseif ($payment === true) {
+			// please note that offline payment methods will NOT make a payment,
+			// but instead just mark themselves as the PMD_ID on the transaction, and return true
+			$this->checkout->payment = $payment;
+			return true;
+		}
+		// where's my money?
+		return false;
+	}
+
+
+	/**
+	 * _last_second_ticket_verifications
+	 *
+	 * @access public
+	 * @return bool
+	 * @throws EE_Error
+	 */
+	protected function _last_second_ticket_verifications()
+	{
+		// don't bother re-validating if not a return visit
+		if (! $this->checkout->revisit) {
+			return true;
+		}
+		$registrations = $this->checkout->transaction->registrations();
+		if (empty($registrations)) {
+			return false;
+		}
+		foreach ($registrations as $registration) {
+			if ($registration instanceof EE_Registration && ! $registration->is_approved()) {
+				$event = $registration->event_obj();
+				if ($event instanceof EE_Event && $event->is_sold_out(true)) {
+					EE_Error::add_error(
+						apply_filters(
+							'FHEE__EE_SPCO_Reg_Step_Payment_Options___last_second_ticket_verifications__sold_out_events_msg',
+							sprintf(
+								esc_html__(
+									'It appears that the %1$s event that you were about to make a payment for has sold out since you first registered and/or arrived at this page. Please refresh the page and try again. If you have already made a partial payment towards this event, please contact the event administrator for a refund.',
+									'event_espresso'
+								),
+								$event->name()
+							)
+						),
+						__FILE__,
+						__FUNCTION__,
+						__LINE__
+					);
+					return false;
+				}
+			}
+		}
+		return true;
+	}
+
+
+	/**
+	 * redirect_form
+	 *
+	 * @access public
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	public function redirect_form()
+	{
+		$payment_method_billing_info = $this->_payment_method_billing_info(
+			$this->_get_payment_method_for_selected_method_of_payment()
+		);
+		$html = $payment_method_billing_info->get_html();
+		$html .= $this->checkout->redirect_form;
+		EE_Registry::instance()->REQ->add_output($html);
+		return true;
+	}
+
+
+	/**
+	 * _billing_form_is_valid
+	 *
+	 * @access private
+	 * @return bool
+	 * @throws \EE_Error
+	 */
+	private function _billing_form_is_valid()
+	{
+		if (! $this->checkout->payment_method->type_obj()->has_billing_form()) {
+			return true;
+		}
+		if ($this->checkout->billing_form instanceof EE_Billing_Info_Form) {
+			if ($this->checkout->billing_form->was_submitted()) {
+				$this->checkout->billing_form->receive_form_submission();
+				if ($this->checkout->billing_form->is_valid()) {
+					return true;
+				}
+				$validation_errors = $this->checkout->billing_form->get_validation_errors_accumulated();
+				$error_strings = array();
+				foreach ($validation_errors as $validation_error) {
+					if ($validation_error instanceof EE_Validation_Error) {
+						$form_section = $validation_error->get_form_section();
+						if ($form_section instanceof EE_Form_Input_Base) {
+							$label = $form_section->html_label_text();
+						} elseif ($form_section instanceof EE_Form_Section_Base) {
+							$label = $form_section->name();
+						} else {
+							$label = esc_html__('Validation Error', 'event_espresso');
+						}
+						$error_strings[] = sprintf('%1$s: %2$s', $label, $validation_error->getMessage());
+					}
+				}
+				EE_Error::add_error(
+					sprintf(
+						esc_html__(
+							'One or more billing form inputs are invalid and require correction before proceeding. %1$s %2$s',
+							'event_espresso'
+						),
+						'<br/>',
+						implode('<br/>', $error_strings)
+					),
+					__FILE__,
+					__FUNCTION__,
+					__LINE__
+				);
+			} else {
+				EE_Error::add_error(
+					esc_html__(
+						'The billing form was not submitted or something prevented it\'s submission.',
+						'event_espresso'
+					),
+					__FILE__,
+					__FUNCTION__,
+					__LINE__
+				);
+			}
+		} else {
+			EE_Error::add_error(
+				esc_html__(
+					'The submitted billing form is invalid possibly due to a technical reason.',
+					'event_espresso'
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+		}
+		return false;
+	}
+
+
+	/**
+	 * _setup_primary_registrant_prior_to_payment
+	 * ensures that the primary registrant has a valid attendee object created with the critical details populated
+	 * (first & last name & email) and that both the transaction object and primary registration object have been saved
+	 * plz note that any other registrations will NOT be saved at this point (because they may not have any details
+	 * yet)
+	 *
+	 * @access private
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws RuntimeException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _setup_primary_registrant_prior_to_payment()
+	{
+		// check if transaction has a primary registrant and that it has a related Attendee object
+		// if not, then we need to at least gather some primary registrant data before attempting payment
+		if ($this->checkout->billing_form instanceof EE_Billing_Attendee_Info_Form
+			&& ! $this->checkout->transaction_has_primary_registrant()
+			&& ! $this->_capture_primary_registration_data_from_billing_form()
+		) {
+			return false;
+		}
+		// because saving an object clears it's cache, we need to do the chevy shuffle
+		// grab the primary_registration object
+		$primary_registration = $this->checkout->transaction->primary_registration();
+		// at this point we'll consider a TXN to not have been failed
+		$this->checkout->transaction->toggle_failed_transaction_status();
+		// save the TXN ( which clears cached copy of primary_registration)
+		$this->checkout->transaction->save();
+		// grab TXN ID and save it to the primary_registration
+		$primary_registration->set_transaction_id($this->checkout->transaction->ID());
+		// save what we have so far
+		$primary_registration->save();
+		return true;
+	}
+
+
+	/**
+	 * _capture_primary_registration_data_from_billing_form
+	 *
+	 * @access private
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _capture_primary_registration_data_from_billing_form()
+	{
+		// convert billing form data into an attendee
+		$this->checkout->primary_attendee_obj = $this->checkout->billing_form->create_attendee_from_billing_form_data();
+		if (! $this->checkout->primary_attendee_obj instanceof EE_Attendee) {
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'The billing form details could not be used for attendee details due to a technical issue.%sPlease try again or contact %s for assistance.',
+						'event_espresso'
+					),
+					'<br/>',
+					EE_Registry::instance()->CFG->organization->get_pretty('email')
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return false;
+		}
+		$primary_registration = $this->checkout->transaction->primary_registration();
+		if (! $primary_registration instanceof EE_Registration) {
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'The primary registrant for this transaction could not be determined due to a technical issue.%sPlease try again or contact %s for assistance.',
+						'event_espresso'
+					),
+					'<br/>',
+					EE_Registry::instance()->CFG->organization->get_pretty('email')
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return false;
+		}
+		if (! $primary_registration->_add_relation_to($this->checkout->primary_attendee_obj, 'Attendee')
+			  instanceof
+			  EE_Attendee
+		) {
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'The primary registrant could not be associated with this transaction due to a technical issue.%sPlease try again or contact %s for assistance.',
+						'event_espresso'
+					),
+					'<br/>',
+					EE_Registry::instance()->CFG->organization->get_pretty('email')
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return false;
+		}
+		/** @type EE_Registration_Processor $registration_processor */
+		$registration_processor = EE_Registry::instance()->load_class('Registration_Processor');
+		// at this point, we should have enough details about the registrant to consider the registration NOT incomplete
+		$registration_processor->toggle_incomplete_registration_status_to_default($primary_registration);
+		return true;
+	}
+
+
+	/**
+	 * _get_payment_method_for_selected_method_of_payment
+	 * retrieves a valid payment method
+	 *
+	 * @access public
+	 * @return EE_Payment_Method
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _get_payment_method_for_selected_method_of_payment()
+	{
+		if ($this->checkout->selected_method_of_payment === 'events_sold_out') {
+			$this->_redirect_because_event_sold_out();
+			return null;
+		}
+		// get EE_Payment_Method object
+		if (isset($this->checkout->available_payment_methods[ $this->checkout->selected_method_of_payment ])) {
+			$payment_method = $this->checkout->available_payment_methods[ $this->checkout->selected_method_of_payment ];
+		} else {
+			// load EEM_Payment_Method
+			EE_Registry::instance()->load_model('Payment_Method');
+			/** @type EEM_Payment_Method $EEM_Payment_Method */
+			$EEM_Payment_Method = EE_Registry::instance()->LIB->EEM_Payment_Method;
+			$payment_method = $EEM_Payment_Method->get_one_by_slug($this->checkout->selected_method_of_payment);
+		}
+		// verify $payment_method
+		if (! $payment_method instanceof EE_Payment_Method) {
+			// not a payment
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'The selected method of payment could not be determined due to a technical issue.%sPlease try again or contact %s for assistance.',
+						'event_espresso'
+					),
+					'<br/>',
+					EE_Registry::instance()->CFG->organization->get_pretty('email')
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return null;
+		}
+		// and verify it has a valid Payment_Method Type object
+		if (! $payment_method->type_obj() instanceof EE_PMT_Base) {
+			// not a payment
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'A valid payment method could not be determined due to a technical issue.%sPlease try again or contact %s for assistance.',
+						'event_espresso'
+					),
+					'<br/>',
+					EE_Registry::instance()->CFG->organization->get_pretty('email')
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return null;
+		}
+		return $payment_method;
+	}
+
+
+	/**
+	 *    _attempt_payment
+	 *
+	 * @access    private
+	 * @type    EE_Payment_Method $payment_method
+	 * @return mixed EE_Payment | boolean
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _attempt_payment(EE_Payment_Method $payment_method)
+	{
+		$payment = null;
+		$this->checkout->transaction->save();
+		$payment_processor = EE_Registry::instance()->load_core('Payment_Processor');
+		if (! $payment_processor instanceof EE_Payment_Processor) {
+			return false;
+		}
+		try {
+			$payment_processor->set_revisit($this->checkout->revisit);
+			// generate payment object
+			$payment = $payment_processor->process_payment(
+				$payment_method,
+				$this->checkout->transaction,
+				$this->checkout->amount_owing,
+				$this->checkout->billing_form,
+				$this->_get_return_url($payment_method),
+				'CART',
+				$this->checkout->admin_request,
+				true,
+				$this->reg_step_url()
+			);
+		} catch (Exception $e) {
+			$this->_handle_payment_processor_exception($e);
+		}
+		return $payment;
+	}
+
+
+	/**
+	 * _handle_payment_processor_exception
+	 *
+	 * @access protected
+	 * @param \Exception $e
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	protected function _handle_payment_processor_exception(Exception $e)
+	{
+		EE_Error::add_error(
+			sprintf(
+				esc_html__(
+					'The payment could not br processed due to a technical issue.%1$sPlease try again or contact %2$s for assistance.||The following Exception was thrown in %4$s on line %5$s:%1$s%3$s',
+					'event_espresso'
+				),
+				'<br/>',
+				EE_Registry::instance()->CFG->organization->get_pretty('email'),
+				$e->getMessage(),
+				$e->getFile(),
+				$e->getLine()
+			),
+			__FILE__,
+			__FUNCTION__,
+			__LINE__
+		);
+	}
+
+
+	/**
+	 * _get_return_url
+	 *
+	 * @access protected
+	 * @param \EE_Payment_Method $payment_method
+	 * @return string
+	 * @throws \EE_Error
+	 */
+	protected function _get_return_url(EE_Payment_Method $payment_method)
+	{
+		$return_url = '';
+		switch ($payment_method->type_obj()->payment_occurs()) {
+			case EE_PMT_Base::offsite:
+				$return_url = add_query_arg(
+					array(
+						'action'                     => 'process_gateway_response',
+						'selected_method_of_payment' => $this->checkout->selected_method_of_payment,
+						'spco_txn'                   => $this->checkout->transaction->ID(),
+					),
+					$this->reg_step_url()
+				);
+				break;
+			case EE_PMT_Base::onsite:
+			case EE_PMT_Base::offline:
+				$return_url = $this->checkout->next_step->reg_step_url();
+				break;
+		}
+		return $return_url;
+	}
+
+
+	/**
+	 * _validate_payment
+	 *
+	 * @access private
+	 * @param EE_Payment $payment
+	 * @return EE_Payment|FALSE
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _validate_payment($payment = null)
+	{
+		if ($this->checkout->payment_method->is_off_line()) {
+			return true;
+		}
+		// verify payment object
+		if (! $payment instanceof EE_Payment) {
+			// not a payment
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'A valid payment was not generated due to a technical issue.%1$sPlease try again or contact %2$s for assistance.',
+						'event_espresso'
+					),
+					'<br/>',
+					EE_Registry::instance()->CFG->organization->get_pretty('email')
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return false;
+		}
+		return $payment;
+	}
+
+
+	/**
+	 * _post_payment_processing
+	 *
+	 * @access private
+	 * @param EE_Payment|bool $payment
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _post_payment_processing($payment = null)
+	{
+		// Off-Line payment?
+		if ($payment === true) {
+			// $this->_setup_redirect_for_next_step();
+			return true;
+			// On-Site payment?
+		} elseif ($this->checkout->payment_method->is_on_site()) {
+			if (! $this->_process_payment_status($payment, EE_PMT_Base::onsite)) {
+				// $this->_setup_redirect_for_next_step();
+				$this->checkout->continue_reg = false;
+			}
+			// Off-Site payment?
+		} elseif ($this->checkout->payment_method->is_off_site()) {
+			// if a payment object was made and it specifies a redirect url, then we'll setup that redirect info
+			if ($payment instanceof EE_Payment && $payment->redirect_url()) {
+				do_action('AHEE_log', __CLASS__, __FUNCTION__, $payment->redirect_url(), '$payment->redirect_url()');
+				$this->checkout->redirect = true;
+				$this->checkout->redirect_form = $payment->redirect_form();
+				$this->checkout->redirect_url = $this->reg_step_url('redirect_form');
+				// set JSON response
+				$this->checkout->json_response->set_redirect_form($this->checkout->redirect_form);
+				// and lastly, let's bump the payment status to pending
+				$payment->set_status(EEM_Payment::status_id_pending);
+				$payment->save();
+			} else {
+				// not a payment
+				$this->checkout->continue_reg = false;
+				EE_Error::add_error(
+					sprintf(
+						esc_html__(
+							'It appears the Off Site Payment Method was not configured properly.%sPlease try again or contact %s for assistance.',
+							'event_espresso'
+						),
+						'<br/>',
+						EE_Registry::instance()->CFG->organization->get_pretty('email')
+					),
+					__FILE__,
+					__FUNCTION__,
+					__LINE__
+				);
+			}
+		} else {
+			// ummm ya... not Off-Line, not On-Site, not off-Site ????
+			$this->checkout->continue_reg = false;
+			return false;
+		}
+		return $payment;
+	}
+
+
+	/**
+	 *    _process_payment_status
+	 *
+	 * @access private
+	 * @type    EE_Payment $payment
+	 * @param string       $payment_occurs
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _process_payment_status($payment, $payment_occurs = EE_PMT_Base::offline)
+	{
+		// off-line payment? carry on
+		if ($payment_occurs === EE_PMT_Base::offline) {
+			return true;
+		}
+		// verify payment validity
+		if ($payment instanceof EE_Payment) {
+			do_action('AHEE_log', __CLASS__, __FUNCTION__, $payment->status(), '$payment->status()');
+			$msg = $payment->gateway_response();
+			// check results
+			switch ($payment->status()) {
+				// good payment
+				case EEM_Payment::status_id_approved:
+					EE_Error::add_success(
+						esc_html__('Your payment was processed successfully.', 'event_espresso'),
+						__FILE__,
+						__FUNCTION__,
+						__LINE__
+					);
+					return true;
+					break;
+				// slow payment
+				case EEM_Payment::status_id_pending:
+					if (empty($msg)) {
+						$msg = esc_html__(
+							'Your payment appears to have been processed successfully, but the Instant Payment Notification has not yet been received. It should arrive shortly.',
+							'event_espresso'
+						);
+					}
+					EE_Error::add_success($msg, __FILE__, __FUNCTION__, __LINE__);
+					return true;
+					break;
+				// don't wanna payment
+				case EEM_Payment::status_id_cancelled:
+					if (empty($msg)) {
+						$msg = _n(
+							'Payment cancelled. Please try again.',
+							'Payment cancelled. Please try again or select another method of payment.',
+							count($this->checkout->available_payment_methods),
+							'event_espresso'
+						);
+					}
+					EE_Error::add_attention($msg, __FILE__, __FUNCTION__, __LINE__);
+					return false;
+					break;
+				// not enough payment
+				case EEM_Payment::status_id_declined:
+					if (empty($msg)) {
+						$msg = _n(
+							'We\'re sorry but your payment was declined. Please try again.',
+							'We\'re sorry but your payment was declined. Please try again or select another method of payment.',
+							count($this->checkout->available_payment_methods),
+							'event_espresso'
+						);
+					}
+					EE_Error::add_attention($msg, __FILE__, __FUNCTION__, __LINE__);
+					return false;
+					break;
+				// bad payment
+				case EEM_Payment::status_id_failed:
+					if (! empty($msg)) {
+						EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
+						return false;
+					}
+					// default to error below
+					break;
+			}
+		}
+		// off-site payment gateway responses are too unreliable, so let's just assume that
+		// the payment processing is just running slower than the registrant's request
+		if ($payment_occurs === EE_PMT_Base::offsite) {
+			return true;
+		}
+		EE_Error::add_error(
+			sprintf(
+				esc_html__(
+					'Your payment could not be processed successfully due to a technical issue.%sPlease try again or contact %s for assistance.',
+					'event_espresso'
+				),
+				'<br/>',
+				EE_Registry::instance()->CFG->organization->get_pretty('email')
+			),
+			__FILE__,
+			__FUNCTION__,
+			__LINE__
+		);
+		return false;
+	}
+
+
+
+
+
+
+	/********************************************************************************************************/
+	/**********************************  PROCESS GATEWAY RESPONSE  **********************************/
+	/********************************************************************************************************/
+	/**
+	 * process_gateway_response
+	 * this is the return point for Off-Site Payment Methods
+	 * It will attempt to "handle the IPN" if it appears that this has not already occurred,
+	 * otherwise, it will load up the last payment made for the TXN.
+	 * If the payment retrieved looks good, it will then either:
+	 *    complete the current step and allow advancement to the next reg step
+	 *        or present the payment options again
+	 *
+	 * @access private
+	 * @return EE_Payment|FALSE
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 * @throws \EventEspresso\core\exceptions\InvalidSessionDataException
+	 */
+	public function process_gateway_response()
+	{
+		$payment = null;
+		// how have they chosen to pay?
+		$this->checkout->selected_method_of_payment = $this->_get_selected_method_of_payment(true);
+		// get EE_Payment_Method object
+		if (! $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment()) {
+			$this->checkout->continue_reg = false;
+			return false;
+		}
+		if (! $this->checkout->payment_method->is_off_site()) {
+			return false;
+		}
+		$this->_validate_offsite_return();
+		// DEBUG LOG
+		// $this->checkout->log(
+		//     __CLASS__,
+		//     __FUNCTION__,
+		//     __LINE__,
+		//     array(
+		//         'selected_method_of_payment' => $this->checkout->selected_method_of_payment,
+		//         'payment_method'             => $this->checkout->payment_method,
+		//     ),
+		//     true
+		// );
+		// verify TXN
+		if ($this->checkout->transaction instanceof EE_Transaction) {
+			$gateway = $this->checkout->payment_method->type_obj()->get_gateway();
+			if (! $gateway instanceof EE_Offsite_Gateway) {
+				$this->checkout->continue_reg = false;
+				return false;
+			}
+			$payment = $this->_process_off_site_payment($gateway);
+			$payment = $this->_process_cancelled_payments($payment);
+			$payment = $this->_validate_payment($payment);
+			// if payment was not declined by the payment gateway or cancelled by the registrant
+			if ($this->_process_payment_status($payment, EE_PMT_Base::offsite)) {
+				// $this->_setup_redirect_for_next_step();
+				// store that for later
+				$this->checkout->payment = $payment;
+				// mark this reg step as completed, as long as gateway doesn't use a separate IPN request,
+				// because we will complete this step during the IPN processing then
+				if ($gateway instanceof EE_Offsite_Gateway && ! $this->handle_IPN_in_this_request()) {
+					$this->set_completed();
+				}
+				return true;
+			}
+		}
+		// DEBUG LOG
+		// $this->checkout->log(
+		//     __CLASS__,
+		//     __FUNCTION__,
+		//     __LINE__,
+		//     array('payment' => $payment)
+		// );
+		$this->checkout->continue_reg = false;
+		return false;
+	}
+
+
+	/**
+	 * _validate_return
+	 *
+	 * @access private
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 * @throws \EventEspresso\core\exceptions\InvalidSessionDataException
+	 */
+	private function _validate_offsite_return()
+	{
+		$TXN_ID = (int) EE_Registry::instance()->REQ->get('spco_txn', 0);
+		if ($TXN_ID !== $this->checkout->transaction->ID()) {
+			// Houston... we might have a problem
+			$invalid_TXN = false;
+			// first gather some info
+			$valid_TXN = EEM_Transaction::instance()->get_one_by_ID($TXN_ID);
+			$primary_registrant = $valid_TXN instanceof EE_Transaction
+				? $valid_TXN->primary_registration()
+				: null;
+			// let's start by retrieving the cart for this TXN
+			$cart = $this->checkout->get_cart_for_transaction($this->checkout->transaction);
+			if ($cart instanceof EE_Cart) {
+				// verify that the current cart has tickets
+				$tickets = $cart->get_tickets();
+				if (empty($tickets)) {
+					$invalid_TXN = true;
+				}
+			} else {
+				$invalid_TXN = true;
+			}
+			$valid_TXN_SID = $primary_registrant instanceof EE_Registration
+				? $primary_registrant->session_ID()
+				: null;
+			// validate current Session ID and compare against valid TXN session ID
+			if ($invalid_TXN // if this is already true, then skip other checks
+				|| EE_Session::instance()->id() === null
+				|| (
+					// WARNING !!!
+					// this could be PayPal sending back duplicate requests (ya they do that)
+					// or it **could** mean someone is simply registering AGAIN after having just done so
+					// so now we need to determine if this current TXN looks valid or not
+					// and whether this reg step has even been started ?
+					EE_Session::instance()->id() === $valid_TXN_SID
+					// really? you're half way through this reg step, but you never started it ?
+					&& $this->checkout->transaction->reg_step_completed($this->slug()) === false
+				)
+			) {
+				$invalid_TXN = true;
+			}
+			if ($invalid_TXN) {
+				// is the valid TXN completed ?
+				if ($valid_TXN instanceof EE_Transaction) {
+					// has this step even been started ?
+					$reg_step_completed = $valid_TXN->reg_step_completed($this->slug());
+					if ($reg_step_completed !== false && $reg_step_completed !== true) {
+						// so it **looks** like this is a double request from PayPal
+						// so let's try to pick up where we left off
+						$this->checkout->transaction = $valid_TXN;
+						$this->checkout->refresh_all_entities(true);
+						return;
+					}
+				}
+				// you appear to be lost?
+				$this->_redirect_wayward_request($primary_registrant);
+			}
+		}
+	}
+
+
+	/**
+	 * _redirect_wayward_request
+	 *
+	 * @access private
+	 * @param \EE_Registration|null $primary_registrant
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _redirect_wayward_request(EE_Registration $primary_registrant)
+	{
+		if (! $primary_registrant instanceof EE_Registration) {
+			// try redirecting based on the current TXN
+			$primary_registrant = $this->checkout->transaction instanceof EE_Transaction
+				? $this->checkout->transaction->primary_registration()
+				: null;
+		}
+		if (! $primary_registrant instanceof EE_Registration) {
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'Invalid information was received from the Off-Site Payment Processor and your Transaction details could not be retrieved from the database.%1$sPlease try again or contact %2$s for assistance.',
+						'event_espresso'
+					),
+					'<br/>',
+					EE_Registry::instance()->CFG->organization->get_pretty('email')
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return false;
+		}
+		// make sure transaction is not locked
+		$this->checkout->transaction->unlock();
+		wp_safe_redirect(
+			add_query_arg(
+				array(
+					'e_reg_url_link' => $primary_registrant->reg_url_link(),
+				),
+				$this->checkout->thank_you_page_url
+			)
+		);
+		exit();
+	}
+
+
+	/**
+	 * _process_off_site_payment
+	 *
+	 * @access private
+	 * @param \EE_Offsite_Gateway $gateway
+	 * @return EE_Payment
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	private function _process_off_site_payment(EE_Offsite_Gateway $gateway)
+	{
+		try {
+			$request_data = \EE_Registry::instance()->REQ->params();
+			// if gateway uses_separate_IPN_request, then we don't have to process the IPN manually
+			$this->set_handle_IPN_in_this_request(
+				$gateway->handle_IPN_in_this_request($request_data, false)
+			);
+			if ($this->handle_IPN_in_this_request()) {
+				// get payment details and process results
+				/** @type EE_Payment_Processor $payment_processor */
+				$payment_processor = EE_Registry::instance()->load_core('Payment_Processor');
+				$payment = $payment_processor->process_ipn(
+					$request_data,
+					$this->checkout->transaction,
+					$this->checkout->payment_method,
+					true,
+					false
+				);
+				// $payment_source = 'process_ipn';
+			} else {
+				$payment = $this->checkout->transaction->last_payment();
+				// $payment_source = 'last_payment';
+			}
+		} catch (Exception $e) {
+			// let's just eat the exception and try to move on using any previously set payment info
+			$payment = $this->checkout->transaction->last_payment();
+			// $payment_source = 'last_payment after Exception';
+			// but if we STILL don't have a payment object
+			if (! $payment instanceof EE_Payment) {
+				// then we'll object ! ( not object like a thing... but object like what a lawyer says ! )
+				$this->_handle_payment_processor_exception($e);
+			}
+		}
+		// DEBUG LOG
+		// $this->checkout->log(
+		//     __CLASS__,
+		//     __FUNCTION__,
+		//     __LINE__,
+		//     array(
+		//         'process_ipn_payment' => $payment,
+		//         'payment_source'      => $payment_source,
+		//     )
+		// );
+		return $payment;
+	}
+
+
+	/**
+	 * _process_cancelled_payments
+	 * just makes sure that the payment status gets updated correctly
+	 * so tha tan error isn't generated during payment validation
+	 *
+	 * @access private
+	 * @param EE_Payment $payment
+	 * @return EE_Payment | FALSE
+	 * @throws \EE_Error
+	 */
+	private function _process_cancelled_payments($payment = null)
+	{
+		if ($payment instanceof EE_Payment
+			&& isset($_REQUEST['ee_cancel_payment'])
+			&& $payment->status() === EEM_Payment::status_id_failed
+		) {
+			$payment->set_status(EEM_Payment::status_id_cancelled);
+		}
+		return $payment;
+	}
+
+
+	/**
+	 *    get_transaction_details_for_gateways
+	 *
+	 * @access    public
+	 * @return int
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws \EventEspresso\core\exceptions\InvalidDataTypeException
+	 * @throws \EventEspresso\core\exceptions\InvalidInterfaceException
+	 */
+	public function get_transaction_details_for_gateways()
+	{
+		$txn_details = array();
+		// ya gotta make a choice man
+		if (empty($this->checkout->selected_method_of_payment)) {
+			$txn_details = array(
+				'error' => esc_html__('Please select a method of payment before proceeding.', 'event_espresso'),
+			);
+		}
+		// get EE_Payment_Method object
+		if (empty($txn_details)
+			&&
+			! $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment()
+		) {
+			$txn_details = array(
+				'selected_method_of_payment' => $this->checkout->selected_method_of_payment,
+				'error'                      => esc_html__(
+					'A valid Payment Method could not be determined.',
+					'event_espresso'
+				),
+			);
+		}
+		if (empty($txn_details) && $this->checkout->transaction instanceof EE_Transaction) {
+			$return_url = $this->_get_return_url($this->checkout->payment_method);
+			$txn_details = array(
+				'TXN_ID'         => $this->checkout->transaction->ID(),
+				'TXN_timestamp'  => $this->checkout->transaction->datetime(),
+				'TXN_total'      => $this->checkout->transaction->total(),
+				'TXN_paid'       => $this->checkout->transaction->paid(),
+				'TXN_reg_steps'  => $this->checkout->transaction->reg_steps(),
+				'STS_ID'         => $this->checkout->transaction->status_ID(),
+				'PMD_ID'         => $this->checkout->transaction->payment_method_ID(),
+				'payment_amount' => $this->checkout->amount_owing,
+				'return_url'     => $return_url,
+				'cancel_url'     => add_query_arg(array('ee_cancel_payment' => true), $return_url),
+				'notify_url'     => EE_Config::instance()->core->txn_page_url(
+					array(
+						'e_reg_url_link'    => $this->checkout->transaction->primary_registration()->reg_url_link(),
+						'ee_payment_method' => $this->checkout->payment_method->slug(),
+					)
+				),
+			);
+		}
+		echo wp_json_encode($txn_details);
+		exit();
+	}
+
+
+	/**
+	 *    __sleep
+	 * to conserve db space, let's remove the reg_form and the EE_Checkout object from EE_SPCO_Reg_Step objects upon
+	 * serialization EE_Checkout will handle the reimplementation of itself upon waking, but we won't bother with the
+	 * reg form, because if needed, it will be regenerated anyways
+	 *
+	 * @return array
+	 */
+	public function __sleep()
+	{
+		// remove the reg form and the checkout
+		return array_diff(array_keys(get_object_vars($this)), array('reg_form', 'checkout', 'line_item_display'));
+	}
 }

Spacing +76 added lines, -76 removed lines

@@ -129,7 +129,7 @@ 
     {
         $this->_slug = 'payment_options';
         $this->_name = esc_html__('Payment Options', 'event_espresso');
-        $this->_template = SPCO_REG_STEPS_PATH . $this->_slug . DS . 'payment_options_main.template.php';
+        $this->_template = SPCO_REG_STEPS_PATH.$this->_slug.DS.'payment_options_main.template.php';
         $this->checkout = $checkout;
         $this->_reset_success_message();
         $this->set_instructions(
@@ -212,7 +212,7 @@ 
     {
         $transaction = $this->checkout->transaction;
         // if the transaction isn't set or nothing is owed on it, don't enqueue any JS
-        if (! $transaction instanceof EE_Transaction || EEH_Money::compare_floats($transaction->remaining(), 0)) {
+        if ( ! $transaction instanceof EE_Transaction || EEH_Money::compare_floats($transaction->remaining(), 0)) {
             return;
         }
         foreach (EEM_Payment_Method::instance()->get_all_for_transaction(
@@ -304,18 +304,18 @@ 
         foreach ($registrations as $REG_ID => $registration) {
             /** @var $registration EE_Registration */
             // has this registration lost it's space ?
-            if (isset($ejected_registrations[ $REG_ID ])) {
+            if (isset($ejected_registrations[$REG_ID])) {
                 if ($registration->event()->is_sold_out() || $registration->event()->is_sold_out(true)) {
-                    $sold_out_events[ $registration->event()->ID() ] = $registration->event();
+                    $sold_out_events[$registration->event()->ID()] = $registration->event();
                 } else {
-                    $insufficient_spaces_available[ $registration->event()->ID() ] = $registration->event();
+                    $insufficient_spaces_available[$registration->event()->ID()] = $registration->event();
                 }
                 continue;
             }
             // event requires admin approval
             if ($registration->status_ID() === EEM_Registration::status_id_not_approved) {
                 // add event to list of events with pre-approval reg status
-                $registrations_requiring_pre_approval[ $REG_ID ] = $registration;
+                $registrations_requiring_pre_approval[$REG_ID] = $registration;
                 do_action(
                     'AHEE__EE_SPCO_Reg_Step_Payment_Options__generate_reg_form__event_requires_pre_approval',
                     $registration->event(),
@@ -331,7 +331,7 @@ 
                 )
             ) {
                 // add event to list of events that are sold out
-                $sold_out_events[ $registration->event()->ID() ] = $registration->event();
+                $sold_out_events[$registration->event()->ID()] = $registration->event();
                 do_action(
                     'AHEE__EE_SPCO_Reg_Step_Payment_Options__generate_reg_form__sold_out_event',
                     $registration->event(),
@@ -341,38 +341,38 @@ 
             }
             // are they allowed to pay now and is there monies owing?
             if ($registration->owes_monies_and_can_pay()) {
-                $registrations_requiring_payment[ $REG_ID ] = $registration;
+                $registrations_requiring_payment[$REG_ID] = $registration;
                 do_action(
                     'AHEE__EE_SPCO_Reg_Step_Payment_Options__generate_reg_form__event_requires_payment',
                     $registration->event(),
                     $this
                 );
-            } elseif (! $this->checkout->revisit
+            } elseif ( ! $this->checkout->revisit
                       && $registration->status_ID() !== EEM_Registration::status_id_not_approved
                       && $registration->ticket()->is_free()
             ) {
-                $registrations_for_free_events[ $registration->ticket()->ID() ] = $registration;
+                $registrations_for_free_events[$registration->ticket()->ID()] = $registration;
             }
         }
         $subsections = array();
         // now decide which template to load
-        if (! empty($sold_out_events)) {
+        if ( ! empty($sold_out_events)) {
             $subsections['sold_out_events'] = $this->_sold_out_events($sold_out_events);
         }
-        if (! empty($insufficient_spaces_available)) {
+        if ( ! empty($insufficient_spaces_available)) {
             $subsections['insufficient_space'] = $this->_insufficient_spaces_available(
                 $insufficient_spaces_available
             );
         }
-        if (! empty($registrations_requiring_pre_approval)) {
+        if ( ! empty($registrations_requiring_pre_approval)) {
             $subsections['registrations_requiring_pre_approval'] = $this->_registrations_requiring_pre_approval(
                 $registrations_requiring_pre_approval
             );
         }
-        if (! empty($registrations_for_free_events)) {
+        if ( ! empty($registrations_for_free_events)) {
             $subsections['no_payment_required'] = $this->_no_payment_required($registrations_for_free_events);
         }
-        if (! empty($registrations_requiring_payment)) {
+        if ( ! empty($registrations_requiring_payment)) {
             if ($this->checkout->amount_owing > 0) {
                 // autoload Line_Item_Display classes
                 EEH_Autoloader::register_line_item_filter_autoloaders();
@@ -437,13 +437,13 @@ 
      */
     public static function add_spco_line_item_filters(EE_Line_Item_Filter_Collection $line_item_filter_collection)
     {
-        if (! EE_Registry::instance()->SSN instanceof EE_Session) {
+        if ( ! EE_Registry::instance()->SSN instanceof EE_Session) {
             return $line_item_filter_collection;
         }
-        if (! EE_Registry::instance()->SSN->checkout() instanceof EE_Checkout) {
+        if ( ! EE_Registry::instance()->SSN->checkout() instanceof EE_Checkout) {
             return $line_item_filter_collection;
         }
-        if (! EE_Registry::instance()->SSN->checkout()->transaction instanceof EE_Transaction) {
+        if ( ! EE_Registry::instance()->SSN->checkout()->transaction instanceof EE_Transaction) {
             return $line_item_filter_collection;
         }
         $line_item_filter_collection->add(
@@ -483,8 +483,8 @@ 
         );
         foreach ($registrations as $REG_ID => $registration) {
             // has this registration lost it's space ?
-            if (isset($ejected_registrations[ $REG_ID ])) {
-                unset($registrations[ $REG_ID ]);
+            if (isset($ejected_registrations[$REG_ID])) {
+                unset($registrations[$REG_ID]);
                 continue;
             }
         }
@@ -534,24 +534,24 @@ 
             }
             $EVT_ID = $registration->event_ID();
             $ticket = $registration->ticket();
-            if (! isset($tickets_remaining[ $ticket->ID() ])) {
-                $tickets_remaining[ $ticket->ID() ] = $ticket->remaining();
+            if ( ! isset($tickets_remaining[$ticket->ID()])) {
+                $tickets_remaining[$ticket->ID()] = $ticket->remaining();
             }
-            if ($tickets_remaining[ $ticket->ID() ] > 0) {
-                if (! isset($event_reg_count[ $EVT_ID ])) {
-                    $event_reg_count[ $EVT_ID ] = 0;
+            if ($tickets_remaining[$ticket->ID()] > 0) {
+                if ( ! isset($event_reg_count[$EVT_ID])) {
+                    $event_reg_count[$EVT_ID] = 0;
                 }
-                $event_reg_count[ $EVT_ID ]++;
-                if (! isset($event_spaces_remaining[ $EVT_ID ])) {
-                    $event_spaces_remaining[ $EVT_ID ] = $registration->event()->spaces_remaining_for_sale();
+                $event_reg_count[$EVT_ID]++;
+                if ( ! isset($event_spaces_remaining[$EVT_ID])) {
+                    $event_spaces_remaining[$EVT_ID] = $registration->event()->spaces_remaining_for_sale();
                 }
             }
             if ($revisit
-                && ($tickets_remaining[ $ticket->ID() ] === 0
-                    || $event_reg_count[ $EVT_ID ] > $event_spaces_remaining[ $EVT_ID ]
+                && ($tickets_remaining[$ticket->ID()] === 0
+                    || $event_reg_count[$EVT_ID] > $event_spaces_remaining[$EVT_ID]
                 )
             ) {
-                $ejected_registrations[ $REG_ID ] = $registration->event();
+                $ejected_registrations[$REG_ID] = $registration->event();
                 if ($registration->status_ID() !== EEM_Registration::status_id_wait_list) {
                     /** @type EE_Registration_Processor $registration_processor */
                     $registration_processor = EE_Registry::instance()->load_class('Registration_Processor');
@@ -611,7 +611,7 @@ 
         foreach ($sold_out_events_array as $sold_out_event) {
             $sold_out_events .= EEH_HTML::li(
                 EEH_HTML::span(
-                    '  ' . $sold_out_event->name(),
+                    '  '.$sold_out_event->name(),
                     '',
                     'dashicons dashicons-marker ee-icon-size-16 pink-text'
                 )
@@ -667,7 +667,7 @@ 
         foreach ($insufficient_spaces_events_array as $event) {
             if ($event instanceof EE_Event) {
                 $insufficient_space_events .= EEH_HTML::li(
-                    EEH_HTML::span(' ' . $event->name(), '', 'dashicons dashicons-marker ee-icon-size-16 pink-text')
+                    EEH_HTML::span(' '.$event->name(), '', 'dashicons dashicons-marker ee-icon-size-16 pink-text')
                 );
             }
         }
@@ -716,7 +716,7 @@ 
         $events_requiring_pre_approval = array();
         foreach ($registrations_requiring_pre_approval as $registration) {
             if ($registration instanceof EE_Registration && $registration->event() instanceof EE_Event) {
-                $events_requiring_pre_approval[ $registration->event()->ID() ] = EEH_HTML::li(
+                $events_requiring_pre_approval[$registration->event()->ID()] = EEH_HTML::li(
                     EEH_HTML::span(
                         '',
                         '',
@@ -857,7 +857,7 @@ 
     {
         return new EE_Form_Section_Proper(
             array(
-                'html_id'         => 'ee-' . $this->slug() . '-extra-hidden-inputs',
+                'html_id'         => 'ee-'.$this->slug().'-extra-hidden-inputs',
                 'layout_strategy' => new EE_Div_Per_Section_Layout(),
                 'subsections'     => array(
                     'spco_no_payment_required' => new EE_Hidden_Input(
@@ -897,7 +897,7 @@ 
                 $payments += $registration->registration_payments();
             }
         }
-        if (! empty($payments)) {
+        if ( ! empty($payments)) {
             foreach ($payments as $payment) {
                 if ($payment instanceof EE_Registration_Payment) {
                     $this->checkout->amount_owing -= $payment->amount();
@@ -1021,23 +1021,23 @@ 
                 $payment_method_button = EEH_HTML::img(
                     $payment_method->button_url(),
                     $payment_method->name(),
-                    'spco-payment-method-' . $payment_method->slug() . '-btn-img',
+                    'spco-payment-method-'.$payment_method->slug().'-btn-img',
                     'spco-payment-method-btn-img'
                 );
                 // check if any payment methods are set as default
                 // if payment method is already selected OR nothing is selected and this payment method should be
                 // open_by_default
                 if (($this->checkout->selected_method_of_payment === $payment_method->slug())
-                    || (! $this->checkout->selected_method_of_payment && $payment_method->open_by_default())
+                    || ( ! $this->checkout->selected_method_of_payment && $payment_method->open_by_default())
                 ) {
                     $this->checkout->selected_method_of_payment = $payment_method->slug();
                     $this->_save_selected_method_of_payment();
-                    $default_payment_method_option[ $payment_method->slug() ] = $payment_method_button;
+                    $default_payment_method_option[$payment_method->slug()] = $payment_method_button;
                 } else {
-                    $available_payment_method_options[ $payment_method->slug() ] = $payment_method_button;
+                    $available_payment_method_options[$payment_method->slug()] = $payment_method_button;
                 }
-                $payment_methods_billing_info[ $payment_method->slug(
-                ) . '-info' ] = $this->_payment_method_billing_info(
+                $payment_methods_billing_info[$payment_method->slug(
+                ).'-info'] = $this->_payment_method_billing_info(
                     $payment_method
                 );
             }
@@ -1073,7 +1073,7 @@ 
      */
     protected function _get_available_payment_methods()
     {
-        if (! empty($this->checkout->available_payment_methods)) {
+        if ( ! empty($this->checkout->available_payment_methods)) {
             return $this->checkout->available_payment_methods;
         }
         $available_payment_methods = array();
@@ -1088,7 +1088,7 @@ 
         );
         foreach ($payment_methods as $payment_method) {
             if ($payment_method instanceof EE_Payment_Method) {
-                $available_payment_methods[ $payment_method->slug() ] = $payment_method;
+                $available_payment_methods[$payment_method->slug()] = $payment_method;
             }
         }
         return $available_payment_methods;
@@ -1183,7 +1183,7 @@ 
         );
         return new EE_Form_Section_Proper(
             array(
-                'html_id'         => 'spco-payment-method-info-' . $payment_method->slug(),
+                'html_id'         => 'spco-payment-method-info-'.$payment_method->slug(),
                 'html_class'      => 'spco-payment-method-info-dv',
                 // only display the selected or default PM
                 'html_style'      => $currently_selected ? '' : 'display:none;',
@@ -1213,7 +1213,7 @@ 
         // how have they chosen to pay?
         $this->checkout->selected_method_of_payment = $this->_get_selected_method_of_payment(true);
         $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment();
-        if (! $this->checkout->payment_method instanceof EE_Payment_Method) {
+        if ( ! $this->checkout->payment_method instanceof EE_Payment_Method) {
             return false;
         }
         if (apply_filters(
@@ -1385,7 +1385,7 @@ 
      */
     public function switch_payment_method()
     {
-        if (! $this->_verify_payment_method_is_set()) {
+        if ( ! $this->_verify_payment_method_is_set()) {
             return false;
         }
         if (apply_filters(
@@ -1520,7 +1520,7 @@ 
             }
         }
         // verify payment method
-        if (! $this->checkout->payment_method instanceof EE_Payment_Method) {
+        if ( ! $this->checkout->payment_method instanceof EE_Payment_Method) {
             // get payment method for selected method of payment
             $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment();
         }
@@ -1545,7 +1545,7 @@ 
      */
     public function save_payer_details_via_ajax()
     {
-        if (! $this->_verify_payment_method_is_set()) {
+        if ( ! $this->_verify_payment_method_is_set()) {
             return;
         }
         // generate billing form for selected method of payment if it hasn't been done already
@@ -1555,7 +1555,7 @@ 
             );
         }
         // generate primary attendee from payer info if applicable
-        if (! $this->checkout->transaction_has_primary_registrant()) {
+        if ( ! $this->checkout->transaction_has_primary_registrant()) {
             $attendee = $this->_create_attendee_from_request_data();
             if ($attendee instanceof EE_Attendee) {
                 foreach ($this->checkout->transaction->registrations() as $registration) {
@@ -1586,7 +1586,7 @@ 
     {
         // get State ID
         $STA_ID = ! empty($_REQUEST['state']) ? sanitize_text_field($_REQUEST['state']) : '';
-        if (! empty($STA_ID)) {
+        if ( ! empty($STA_ID)) {
             // can we get state object from name ?
             EE_Registry::instance()->load_model('State');
             $state = EEM_State::instance()->get_col(array(array('STA_name' => $STA_ID), 'limit' => 1), 'STA_ID');
@@ -1594,7 +1594,7 @@ 
         }
         // get Country ISO
         $CNT_ISO = ! empty($_REQUEST['country']) ? sanitize_text_field($_REQUEST['country']) : '';
-        if (! empty($CNT_ISO)) {
+        if ( ! empty($CNT_ISO)) {
             // can we get country object from name ?
             EE_Registry::instance()->load_model('Country');
             $country = EEM_Country::instance()->get_col(
@@ -1627,7 +1627,7 @@ 
         }
         // does this attendee already exist in the db ? we're searching using a combination of first name, last name,
         // AND email address
-        if (! empty($attendee_data['ATT_fname'])
+        if ( ! empty($attendee_data['ATT_fname'])
             && ! empty($attendee_data['ATT_lname'])
             && ! empty($attendee_data['ATT_email'])
         ) {
@@ -1842,7 +1842,7 @@ 
     private function _process_payment()
     {
         // basically confirm that the event hasn't sold out since they hit the page
-        if (! $this->_last_second_ticket_verifications()) {
+        if ( ! $this->_last_second_ticket_verifications()) {
             return false;
         }
         // ya gotta make a choice man
@@ -1853,7 +1853,7 @@ 
             return false;
         }
         // get EE_Payment_Method object
-        if (! $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment()) {
+        if ( ! $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment()) {
             return false;
         }
         // setup billing form
@@ -1862,12 +1862,12 @@ 
                 $this->checkout->payment_method
             );
             // bad billing form ?
-            if (! $this->_billing_form_is_valid()) {
+            if ( ! $this->_billing_form_is_valid()) {
                 return false;
             }
         }
         // ensure primary registrant has been fully processed
-        if (! $this->_setup_primary_registrant_prior_to_payment()) {
+        if ( ! $this->_setup_primary_registrant_prior_to_payment()) {
             return false;
         }
         // if session is close to expiring (under 10 minutes by default)
@@ -1922,7 +1922,7 @@ 
     protected function _last_second_ticket_verifications()
     {
         // don't bother re-validating if not a return visit
-        if (! $this->checkout->revisit) {
+        if ( ! $this->checkout->revisit) {
             return true;
         }
         $registrations = $this->checkout->transaction->registrations();
@@ -1988,7 +1988,7 @@ 
      */
     private function _billing_form_is_valid()
     {
-        if (! $this->checkout->payment_method->type_obj()->has_billing_form()) {
+        if ( ! $this->checkout->payment_method->type_obj()->has_billing_form()) {
             return true;
         }
         if ($this->checkout->billing_form instanceof EE_Billing_Info_Form) {
@@ -2107,7 +2107,7 @@ 
     {
         // convert billing form data into an attendee
         $this->checkout->primary_attendee_obj = $this->checkout->billing_form->create_attendee_from_billing_form_data();
-        if (! $this->checkout->primary_attendee_obj instanceof EE_Attendee) {
+        if ( ! $this->checkout->primary_attendee_obj instanceof EE_Attendee) {
             EE_Error::add_error(
                 sprintf(
                     esc_html__(
@@ -2124,7 +2124,7 @@ 
             return false;
         }
         $primary_registration = $this->checkout->transaction->primary_registration();
-        if (! $primary_registration instanceof EE_Registration) {
+        if ( ! $primary_registration instanceof EE_Registration) {
             EE_Error::add_error(
                 sprintf(
                     esc_html__(
@@ -2140,7 +2140,7 @@ 
             );
             return false;
         }
-        if (! $primary_registration->_add_relation_to($this->checkout->primary_attendee_obj, 'Attendee')
+        if ( ! $primary_registration->_add_relation_to($this->checkout->primary_attendee_obj, 'Attendee')
               instanceof
               EE_Attendee
         ) {
@@ -2186,8 +2186,8 @@ 
             return null;
         }
         // get EE_Payment_Method object
-        if (isset($this->checkout->available_payment_methods[ $this->checkout->selected_method_of_payment ])) {
-            $payment_method = $this->checkout->available_payment_methods[ $this->checkout->selected_method_of_payment ];
+        if (isset($this->checkout->available_payment_methods[$this->checkout->selected_method_of_payment])) {
+            $payment_method = $this->checkout->available_payment_methods[$this->checkout->selected_method_of_payment];
         } else {
             // load EEM_Payment_Method
             EE_Registry::instance()->load_model('Payment_Method');
@@ -2196,7 +2196,7 @@ 
             $payment_method = $EEM_Payment_Method->get_one_by_slug($this->checkout->selected_method_of_payment);
         }
         // verify $payment_method
-        if (! $payment_method instanceof EE_Payment_Method) {
+        if ( ! $payment_method instanceof EE_Payment_Method) {
             // not a payment
             EE_Error::add_error(
                 sprintf(
@@ -2214,7 +2214,7 @@ 
             return null;
         }
         // and verify it has a valid Payment_Method Type object
-        if (! $payment_method->type_obj() instanceof EE_PMT_Base) {
+        if ( ! $payment_method->type_obj() instanceof EE_PMT_Base) {
             // not a payment
             EE_Error::add_error(
                 sprintf(
@@ -2252,7 +2252,7 @@ 
         $payment = null;
         $this->checkout->transaction->save();
         $payment_processor = EE_Registry::instance()->load_core('Payment_Processor');
-        if (! $payment_processor instanceof EE_Payment_Processor) {
+        if ( ! $payment_processor instanceof EE_Payment_Processor) {
             return false;
         }
         try {
@@ -2356,7 +2356,7 @@ 
             return true;
         }
         // verify payment object
-        if (! $payment instanceof EE_Payment) {
+        if ( ! $payment instanceof EE_Payment) {
             // not a payment
             EE_Error::add_error(
                 sprintf(
@@ -2396,7 +2396,7 @@ 
             return true;
             // On-Site payment?
         } elseif ($this->checkout->payment_method->is_on_site()) {
-            if (! $this->_process_payment_status($payment, EE_PMT_Base::onsite)) {
+            if ( ! $this->_process_payment_status($payment, EE_PMT_Base::onsite)) {
                 // $this->_setup_redirect_for_next_step();
                 $this->checkout->continue_reg = false;
             }
@@ -2512,7 +2512,7 @@ 
                     break;
                 // bad payment
                 case EEM_Payment::status_id_failed:
-                    if (! empty($msg)) {
+                    if ( ! empty($msg)) {
                         EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
                         return false;
                     }
@@ -2573,11 +2573,11 @@ 
         // how have they chosen to pay?
         $this->checkout->selected_method_of_payment = $this->_get_selected_method_of_payment(true);
         // get EE_Payment_Method object
-        if (! $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment()) {
+        if ( ! $this->checkout->payment_method = $this->_get_payment_method_for_selected_method_of_payment()) {
             $this->checkout->continue_reg = false;
             return false;
         }
-        if (! $this->checkout->payment_method->is_off_site()) {
+        if ( ! $this->checkout->payment_method->is_off_site()) {
             return false;
         }
         $this->_validate_offsite_return();
@@ -2595,7 +2595,7 @@ 
         // verify TXN
         if ($this->checkout->transaction instanceof EE_Transaction) {
             $gateway = $this->checkout->payment_method->type_obj()->get_gateway();
-            if (! $gateway instanceof EE_Offsite_Gateway) {
+            if ( ! $gateway instanceof EE_Offsite_Gateway) {
                 $this->checkout->continue_reg = false;
                 return false;
             }
@@ -2712,13 +2712,13 @@ 
      */
     private function _redirect_wayward_request(EE_Registration $primary_registrant)
     {
-        if (! $primary_registrant instanceof EE_Registration) {
+        if ( ! $primary_registrant instanceof EE_Registration) {
             // try redirecting based on the current TXN
             $primary_registrant = $this->checkout->transaction instanceof EE_Transaction
                 ? $this->checkout->transaction->primary_registration()
                 : null;
         }
-        if (! $primary_registrant instanceof EE_Registration) {
+        if ( ! $primary_registrant instanceof EE_Registration) {
             EE_Error::add_error(
                 sprintf(
                     esc_html__(
@@ -2788,7 +2788,7 @@ 
             $payment = $this->checkout->transaction->last_payment();
             // $payment_source = 'last_payment after Exception';
             // but if we STILL don't have a payment object
-            if (! $payment instanceof EE_Payment) {
+            if ( ! $payment instanceof EE_Payment) {
                 // then we'll object ! ( not object like a thing... but object like what a lawyer says ! )
                 $this->_handle_payment_processor_exception($e);
             }