eventespresso / event-espresso-core

core/db_classes/EE_Registration.class.php

Spacing +14 added lines, -14 removed lines

@@ -119,7 +119,7 @@ 
     {
         switch ($field_name) {
             case 'REG_code':
-                if (! empty($field_value) && $this->reg_code() === null) {
+                if ( ! empty($field_value) && $this->reg_code() === null) {
                     $this->set_reg_code($field_value, $use_default);
                 }
                 break;
@@ -406,7 +406,7 @@ 
     public function event()
     {
         $event = $this->get_first_related('Event');
-        if (! $event instanceof \EE_Event) {
+        if ( ! $event instanceof \EE_Event) {
             throw new EntityNotFoundException('Event ID', $this->event_ID());
         }
         return $event;
@@ -449,7 +449,7 @@ 
     {
         // reserved ticket and datetime counts will be decremented as sold counts are incremented
         // so stop tracking that this reg has a ticket reserved
-        $this->release_reserved_ticket(false, "REG: {$this->ID()} (ln:" . __LINE__ . ')');
+        $this->release_reserved_ticket(false, "REG: {$this->ID()} (ln:".__LINE__.')');
         $ticket = $this->ticket();
         $ticket->increaseSold();
         // possibly set event status to sold out
@@ -504,7 +504,7 @@ 
                 && $update_ticket
             ) {
                 $ticket = $this->ticket();
-                $ticket->increaseReserved(1, "REG: {$this->ID()} (ln:" . __LINE__ . ')');
+                $ticket->increaseReserved(1, "REG: {$this->ID()} (ln:".__LINE__.')');
                 $ticket->save();
             }
         }
@@ -536,7 +536,7 @@ 
                 && $update_ticket
             ) {
                 $ticket = $this->ticket();
-                $ticket->decreaseReserved(1, true, "REG: {$this->ID()} (ln:" . __LINE__ . ')');
+                $ticket->decreaseReserved(1, true, "REG: {$this->ID()} (ln:".__LINE__.')');
             }
         }
     }
@@ -1211,7 +1211,7 @@ 
                     : '';
                 break;
         }
-        return $icon . $status[ $this->status_ID() ];
+        return $icon.$status[$this->status_ID()];
     }
 
 
@@ -1455,7 +1455,7 @@ 
     {
         $DTT_ID = EEM_Datetime::instance()->ensure_is_ID($DTT_OR_ID);
 
-        if (! $DTT_ID) {
+        if ( ! $DTT_ID) {
             return false;
         }
 
@@ -1463,7 +1463,7 @@ 
 
         // if max uses is not set or equals infinity then return true cause its not a factor for whether user can
         // check-in or not.
-        if (! $max_uses || $max_uses === EE_INF) {
+        if ( ! $max_uses || $max_uses === EE_INF) {
             return true;
         }
 
@@ -1523,7 +1523,7 @@ 
             $datetime = $this->get_latest_related_datetime();
             $DTT_ID = $datetime instanceof EE_Datetime ? $datetime->ID() : 0;
             // verify the registration can checkin for the given DTT_ID
-        } elseif (! $this->can_checkin($DTT_ID, $verify)) {
+        } elseif ( ! $this->can_checkin($DTT_ID, $verify)) {
             EE_Error::add_error(
                 sprintf(
                     esc_html__(
@@ -1546,7 +1546,7 @@ 
         );
         // start by getting the current status so we know what status we'll be changing to.
         $cur_status = $this->check_in_status_for_datetime($DTT_ID, null);
-        $status_to = $status_paths[ $cur_status ];
+        $status_to = $status_paths[$cur_status];
         // database only records true for checked IN or false for checked OUT
         // no record ( null ) means checked in NEVER, but we obviously don't save that
         $new_status = $status_to === EE_Checkin::status_checked_in ? true : false;
@@ -1714,7 +1714,7 @@ 
     public function transaction()
     {
         $transaction = $this->get_first_related('Transaction');
-        if (! $transaction instanceof \EE_Transaction) {
+        if ( ! $transaction instanceof \EE_Transaction) {
             throw new EntityNotFoundException('Transaction ID', $this->transaction_ID());
         }
         return $transaction;
@@ -1768,11 +1768,11 @@ 
             );
             return;
         }
-        if (! $this->reg_code()) {
+        if ( ! $this->reg_code()) {
             parent::set('REG_code', $REG_code, $use_default);
         } else {
             EE_Error::doing_it_wrong(
-                __CLASS__ . '::' . __FUNCTION__,
+                __CLASS__.'::'.__FUNCTION__,
                 esc_html__('Can not change a registration REG_code once it has been set.', 'event_espresso'),
                 '4.6.0'
             );
@@ -1924,7 +1924,7 @@ 
                 break;
             }
         }
-        if (! ($line_item instanceof \EE_Line_Item && $line_item->OBJ_type() === 'Ticket')) {
+        if ( ! ($line_item instanceof \EE_Line_Item && $line_item->OBJ_type() === 'Ticket')) {
             throw new EntityNotFoundException('Line Item Ticket ID', $ticket->ID());
         }
         return $line_item;

Indentation +2113 added lines, -2113 removed lines

@@ -17,2117 +17,2117 @@
 {
 
 
-    /**
-     * Used to reference when a registration has never been checked in.
-     *
-     * @deprecated use \EE_Checkin::status_checked_never instead
-     * @type int
-     */
-    const checkin_status_never = 2;
-
-    /**
-     * Used to reference when a registration has been checked in.
-     *
-     * @deprecated use \EE_Checkin::status_checked_in instead
-     * @type int
-     */
-    const checkin_status_in = 1;
-
-
-    /**
-     * Used to reference when a registration has been checked out.
-     *
-     * @deprecated use \EE_Checkin::status_checked_out instead
-     * @type int
-     */
-    const checkin_status_out = 0;
-
-
-    /**
-     * extra meta key for tracking reg status os trashed registrations
-     *
-     * @type string
-     */
-    const PRE_TRASH_REG_STATUS_KEY = 'pre_trash_registration_status';
-
-
-    /**
-     * extra meta key for tracking if registration has reserved ticket
-     *
-     * @type string
-     */
-    const HAS_RESERVED_TICKET_KEY = 'has_reserved_ticket';
-
-
-    /**
-     * @param array  $props_n_values          incoming values
-     * @param string $timezone                incoming timezone (if not set the timezone set for the website will be
-     *                                        used.)
-     * @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 EE_Registration
-     * @throws EE_Error
-     */
-    public static function new_instance($props_n_values = array(), $timezone = null, $date_formats = array())
-    {
-        $has_object = parent::_check_for_object($props_n_values, __CLASS__, $timezone, $date_formats);
-        return $has_object ? $has_object : new self($props_n_values, false, $timezone, $date_formats);
-    }
-
-
-    /**
-     * @param array  $props_n_values  incoming values from the database
-     * @param string $timezone        incoming timezone as set by the model.  If not set the timezone for
-     *                                the website will be used.
-     * @return EE_Registration
-     */
-    public static function new_instance_from_db($props_n_values = array(), $timezone = null)
-    {
-        return new self($props_n_values, true, $timezone);
-    }
-
-
-    /**
-     *        Set Event ID
-     *
-     * @param        int $EVT_ID Event ID
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_event($EVT_ID = 0)
-    {
-        $this->set('EVT_ID', $EVT_ID);
-    }
-
-
-    /**
-     * Overrides parent set() method so that all calls to set( 'REG_code', $REG_code ) OR set( 'STS_ID', $STS_ID ) can
-     * be routed to internal methods
-     *
-     * @param string $field_name
-     * @param mixed  $field_value
-     * @param bool   $use_default
-     * @throws EE_Error
-     * @throws EntityNotFoundException
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @throws RuntimeException
-     */
-    public function set($field_name, $field_value, $use_default = false)
-    {
-        switch ($field_name) {
-            case 'REG_code':
-                if (! empty($field_value) && $this->reg_code() === null) {
-                    $this->set_reg_code($field_value, $use_default);
-                }
-                break;
-            case 'STS_ID':
-                $this->set_status($field_value, $use_default);
-                break;
-            default:
-                parent::set($field_name, $field_value, $use_default);
-        }
-    }
-
-
-    /**
-     * Set Status ID
-     * updates the registration status and ALSO...
-     * calls reserve_registration_space() if the reg status changes TO approved from any other reg status
-     * calls release_registration_space() if the reg status changes FROM approved to any other reg status
-     *
-     * @param string                $new_STS_ID
-     * @param boolean               $use_default
-     * @param ContextInterface|null $context
-     * @return bool
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws EntityNotFoundException
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @throws RuntimeException
-     * @throws UnexpectedEntityException
-     */
-    public function set_status($new_STS_ID = null, $use_default = false, ContextInterface $context = null)
-    {
-        // get current REG_Status
-        $old_STS_ID = $this->status_ID();
-        // if status has changed
-        if (
-            $old_STS_ID !== $new_STS_ID // and that status has actually changed
-            && ! empty($old_STS_ID) // and that old status is actually set
-            && ! empty($new_STS_ID) // as well as the new status
-            && $this->ID() // ensure registration is in the db
-        ) {
-            // update internal status first
-            parent::set('STS_ID', $new_STS_ID, $use_default);
-            // THEN handle other changes that occur when reg status changes
-            // TO approved
-            if ($new_STS_ID === EEM_Registration::status_id_approved) {
-                // reserve a space by incrementing ticket and datetime sold values
-                $this->reserveRegistrationSpace();
-                do_action('AHEE__EE_Registration__set_status__to_approved', $this, $old_STS_ID, $new_STS_ID, $context);
-                // OR FROM  approved
-            } elseif ($old_STS_ID === EEM_Registration::status_id_approved) {
-                // release a space by decrementing ticket and datetime sold values
-                $this->releaseRegistrationSpace();
-                do_action(
-                    'AHEE__EE_Registration__set_status__from_approved',
-                    $this,
-                    $old_STS_ID,
-                    $new_STS_ID,
-                    $context
-                );
-            }
-            // update status
-            parent::set('STS_ID', $new_STS_ID, $use_default);
-            $this->updateIfCanceledOrReinstated($new_STS_ID, $old_STS_ID, $context);
-            if ($this->statusChangeUpdatesTransaction($context)) {
-                $this->updateTransactionAfterStatusChange();
-            }
-            do_action('AHEE__EE_Registration__set_status__after_update', $this, $old_STS_ID, $new_STS_ID, $context);
-            return true;
-        }
-        // even though the old value matches the new value, it's still good to
-        // allow the parent set method to have a say
-        parent::set('STS_ID', $new_STS_ID, $use_default);
-        return true;
-    }
-
-
-    /**
-     * update REGs and TXN when cancelled or declined registrations involved
-     *
-     * @param string                $new_STS_ID
-     * @param string                $old_STS_ID
-     * @param ContextInterface|null $context
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @throws RuntimeException
-     */
-    private function updateIfCanceledOrReinstated($new_STS_ID, $old_STS_ID, ContextInterface $context = null)
-    {
-        // these reg statuses should not be considered in any calculations involving monies owing
-        $closed_reg_statuses = EEM_Registration::closed_reg_statuses();
-        // true if registration has been cancelled or declined
-        $this->updateIfCanceled(
-            $closed_reg_statuses,
-            $new_STS_ID,
-            $old_STS_ID,
-            $context
-        );
-        $this->updateIfReinstated(
-            $closed_reg_statuses,
-            $new_STS_ID,
-            $old_STS_ID,
-            $context
-        );
-    }
-
-
-    /**
-     * update REGs and TXN when cancelled or declined registrations involved
-     *
-     * @param array                 $closed_reg_statuses
-     * @param string                $new_STS_ID
-     * @param string                $old_STS_ID
-     * @param ContextInterface|null $context
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @throws RuntimeException
-     */
-    private function updateIfCanceled(
-        array $closed_reg_statuses,
-        $new_STS_ID,
-        $old_STS_ID,
-        ContextInterface $context = null
-    ) {
-        // true if registration has been cancelled or declined
-        if (
-            in_array($new_STS_ID, $closed_reg_statuses, true)
-            && ! in_array($old_STS_ID, $closed_reg_statuses, true)
-        ) {
-            /** @type EE_Registration_Processor $registration_processor */
-            $registration_processor = EE_Registry::instance()->load_class('Registration_Processor');
-            /** @type EE_Transaction_Processor $transaction_processor */
-            $transaction_processor = EE_Registry::instance()->load_class('Transaction_Processor');
-            // cancelled or declined registration
-            $registration_processor->update_registration_after_being_canceled_or_declined(
-                $this,
-                $closed_reg_statuses
-            );
-            $transaction_processor->update_transaction_after_canceled_or_declined_registration(
-                $this,
-                $closed_reg_statuses,
-                false
-            );
-            do_action(
-                'AHEE__EE_Registration__set_status__canceled_or_declined',
-                $this,
-                $old_STS_ID,
-                $new_STS_ID,
-                $context
-            );
-            return;
-        }
-    }
-
-
-    /**
-     * update REGs and TXN when cancelled or declined registrations involved
-     *
-     * @param array                 $closed_reg_statuses
-     * @param string                $new_STS_ID
-     * @param string                $old_STS_ID
-     * @param ContextInterface|null $context
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    private function updateIfReinstated(
-        array $closed_reg_statuses,
-        $new_STS_ID,
-        $old_STS_ID,
-        ContextInterface $context = null
-    ) {
-        // true if reinstating cancelled or declined registration
-        if (
-            in_array($old_STS_ID, $closed_reg_statuses, true)
-            && ! in_array($new_STS_ID, $closed_reg_statuses, true)
-        ) {
-            /** @type EE_Registration_Processor $registration_processor */
-            $registration_processor = EE_Registry::instance()->load_class('Registration_Processor');
-            /** @type EE_Transaction_Processor $transaction_processor */
-            $transaction_processor = EE_Registry::instance()->load_class('Transaction_Processor');
-            // reinstating cancelled or declined registration
-            $registration_processor->update_canceled_or_declined_registration_after_being_reinstated(
-                $this,
-                $closed_reg_statuses
-            );
-            $transaction_processor->update_transaction_after_reinstating_canceled_registration(
-                $this,
-                $closed_reg_statuses,
-                false
-            );
-            do_action(
-                'AHEE__EE_Registration__set_status__after_reinstated',
-                $this,
-                $old_STS_ID,
-                $new_STS_ID,
-                $context
-            );
-        }
-    }
-
-
-    /**
-     * @param ContextInterface|null $context
-     * @return bool
-     */
-    private function statusChangeUpdatesTransaction(ContextInterface $context = null)
-    {
-        $contexts_that_do_not_update_transaction = (array) apply_filters(
-            'AHEE__EE_Registration__statusChangeUpdatesTransaction__contexts_that_do_not_update_transaction',
-            array('spco_reg_step_attendee_information_process_registrations'),
-            $context,
-            $this
-        );
-        return ! (
-            $context instanceof ContextInterface
-            && in_array($context->slug(), $contexts_that_do_not_update_transaction, true)
-        );
-    }
-
-
-    /**
-     * @throws EE_Error
-     * @throws EntityNotFoundException
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @throws RuntimeException
-     */
-    private function updateTransactionAfterStatusChange()
-    {
-        /** @type EE_Transaction_Payments $transaction_payments */
-        $transaction_payments = EE_Registry::instance()->load_class('Transaction_Payments');
-        $transaction_payments->recalculate_transaction_total($this->transaction(), false);
-        $this->transaction()->update_status_based_on_total_paid(true);
-    }
-
-
-    /**
-     *        get Status ID
-     */
-    public function status_ID()
-    {
-        return $this->get('STS_ID');
-    }
-
-
-    /**
-     * Gets the ticket this registration is for
-     *
-     * @param boolean $include_archived whether to include archived tickets or not.
-     *
-     * @return EE_Ticket|EE_Base_Class
-     * @throws EE_Error
-     */
-    public function ticket($include_archived = true)
-    {
-        $query_params = array();
-        if ($include_archived) {
-            $query_params['default_where_conditions'] = 'none';
-        }
-        return $this->get_first_related('Ticket', $query_params);
-    }
-
-
-    /**
-     * Gets the event this registration is for
-     *
-     * @return EE_Event
-     * @throws EE_Error
-     * @throws EntityNotFoundException
-     */
-    public function event()
-    {
-        $event = $this->get_first_related('Event');
-        if (! $event instanceof \EE_Event) {
-            throw new EntityNotFoundException('Event ID', $this->event_ID());
-        }
-        return $event;
-    }
-
-
-    /**
-     * Gets the "author" of the registration.  Note that for the purposes of registrations, the author will correspond
-     * with the author of the event this registration is for.
-     *
-     * @since 4.5.0
-     * @return int
-     * @throws EE_Error
-     * @throws EntityNotFoundException
-     */
-    public function wp_user()
-    {
-        $event = $this->event();
-        if ($event instanceof EE_Event) {
-            return $event->wp_user();
-        }
-        return 0;
-    }
-
-
-    /**
-     * increments this registration's related ticket sold and corresponding datetime sold values
-     *
-     * @return void
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws EntityNotFoundException
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @throws UnexpectedEntityException
-     */
-    private function reserveRegistrationSpace()
-    {
-        // reserved ticket and datetime counts will be decremented as sold counts are incremented
-        // so stop tracking that this reg has a ticket reserved
-        $this->release_reserved_ticket(false, "REG: {$this->ID()} (ln:" . __LINE__ . ')');
-        $ticket = $this->ticket();
-        $ticket->increaseSold();
-        // possibly set event status to sold out
-        $this->event()->perform_sold_out_status_check();
-    }
-
-
-    /**
-     * decrements (subtracts) this registration's related ticket sold and corresponding datetime sold values
-     *
-     * @return void
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws EntityNotFoundException
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @throws UnexpectedEntityException
-     */
-    private function releaseRegistrationSpace()
-    {
-        $ticket = $this->ticket();
-        $ticket->decreaseSold();
-        // possibly change event status from sold out back to previous status
-        $this->event()->perform_sold_out_status_check();
-    }
-
-
-    /**
-     * tracks this registration's ticket reservation in extra meta
-     * and can increment related ticket reserved and corresponding datetime reserved values
-     *
-     * @param bool $update_ticket if true, will increment ticket and datetime reserved count
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function reserve_ticket($update_ticket = false, $source = 'unknown')
-    {
-        // only reserve ticket if space is not currently reserved
-        if ((bool) $this->get_extra_meta(EE_Registration::HAS_RESERVED_TICKET_KEY, true) !== true) {
-            $this->update_extra_meta('reserve_ticket', "{$this->ticket_ID()} from {$source}");
-            // IMPORTANT !!!
-            // although checking $update_ticket first would be more efficient,
-            // we NEED to ALWAYS call update_extra_meta(), which is why that is done first
-            if (
-                $this->update_extra_meta(EE_Registration::HAS_RESERVED_TICKET_KEY, true)
-                && $update_ticket
-            ) {
-                $ticket = $this->ticket();
-                $ticket->increaseReserved(1, "REG: {$this->ID()} (ln:" . __LINE__ . ')');
-                $ticket->save();
-            }
-        }
-    }
-
-
-    /**
-     * stops tracking this registration's ticket reservation in extra meta
-     * decrements (subtracts) related ticket reserved and corresponding datetime reserved values
-     *
-     * @param bool $update_ticket if true, will decrement ticket and datetime reserved count
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function release_reserved_ticket($update_ticket = false, $source = 'unknown')
-    {
-        // only release ticket if space is currently reserved
-        if ((bool) $this->get_extra_meta(EE_Registration::HAS_RESERVED_TICKET_KEY, true) === true) {
-            $this->update_extra_meta('release_reserved_ticket', "{$this->ticket_ID()} from {$source}");
-            // IMPORTANT !!!
-            // although checking $update_ticket first would be more efficient,
-            // we NEED to ALWAYS call update_extra_meta(), which is why that is done first
-            if (
-                $this->update_extra_meta(EE_Registration::HAS_RESERVED_TICKET_KEY, false)
-                && $update_ticket
-            ) {
-                $ticket = $this->ticket();
-                $ticket->decreaseReserved(1, true, "REG: {$this->ID()} (ln:" . __LINE__ . ')');
-            }
-        }
-    }
-
-
-    /**
-     * Set Attendee ID
-     *
-     * @param        int $ATT_ID Attendee ID
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_attendee_id($ATT_ID = 0)
-    {
-        $this->set('ATT_ID', $ATT_ID);
-    }
-
-
-    /**
-     *        Set Transaction ID
-     *
-     * @param        int $TXN_ID Transaction ID
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_transaction_id($TXN_ID = 0)
-    {
-        $this->set('TXN_ID', $TXN_ID);
-    }
-
-
-    /**
-     *        Set Session
-     *
-     * @param    string $REG_session PHP Session ID
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_session($REG_session = '')
-    {
-        $this->set('REG_session', $REG_session);
-    }
-
-
-    /**
-     *        Set Registration URL Link
-     *
-     * @param    string $REG_url_link Registration URL Link
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_reg_url_link($REG_url_link = '')
-    {
-        $this->set('REG_url_link', $REG_url_link);
-    }
-
-
-    /**
-     *        Set Attendee Counter
-     *
-     * @param        int $REG_count Primary Attendee
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_count($REG_count = 1)
-    {
-        $this->set('REG_count', $REG_count);
-    }
-
-
-    /**
-     *        Set Group Size
-     *
-     * @param        boolean $REG_group_size Group Registration
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_group_size($REG_group_size = false)
-    {
-        $this->set('REG_group_size', $REG_group_size);
-    }
-
-
-    /**
-     *    is_not_approved -  convenience method that returns TRUE if REG status ID ==
-     *    EEM_Registration::status_id_not_approved
-     *
-     * @return        boolean
-     */
-    public function is_not_approved()
-    {
-        return $this->status_ID() == EEM_Registration::status_id_not_approved ? true : false;
-    }
-
-
-    /**
-     *    is_pending_payment -  convenience method that returns TRUE if REG status ID ==
-     *    EEM_Registration::status_id_pending_payment
-     *
-     * @return        boolean
-     */
-    public function is_pending_payment()
-    {
-        return $this->status_ID() == EEM_Registration::status_id_pending_payment ? true : false;
-    }
-
-
-    /**
-     *    is_approved -  convenience method that returns TRUE if REG status ID == EEM_Registration::status_id_approved
-     *
-     * @return        boolean
-     */
-    public function is_approved()
-    {
-        return $this->status_ID() == EEM_Registration::status_id_approved ? true : false;
-    }
-
-
-    /**
-     *    is_cancelled -  convenience method that returns TRUE if REG status ID == EEM_Registration::status_id_cancelled
-     *
-     * @return        boolean
-     */
-    public function is_cancelled()
-    {
-        return $this->status_ID() == EEM_Registration::status_id_cancelled ? true : false;
-    }
-
-
-    /**
-     *    is_declined -  convenience method that returns TRUE if REG status ID == EEM_Registration::status_id_declined
-     *
-     * @return        boolean
-     */
-    public function is_declined()
-    {
-        return $this->status_ID() == EEM_Registration::status_id_declined ? true : false;
-    }
-
-
-    /**
-     *    is_incomplete -  convenience method that returns TRUE if REG status ID ==
-     *    EEM_Registration::status_id_incomplete
-     *
-     * @return        boolean
-     */
-    public function is_incomplete()
-    {
-        return $this->status_ID() == EEM_Registration::status_id_incomplete ? true : false;
-    }
-
-
-    /**
-     *        Set Registration Date
-     *
-     * @param        mixed ( int or string ) $REG_date Registration Date - Unix timestamp or string representation of
-     *                                                 Date
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_reg_date($REG_date = false)
-    {
-        $this->set('REG_date', $REG_date);
-    }
-
-
-    /**
-     *    Set final price owing for this registration after all ticket/price modifications
-     *
-     * @access    public
-     * @param    float $REG_final_price
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_final_price($REG_final_price = 0.00)
-    {
-        $this->set('REG_final_price', $REG_final_price);
-    }
-
-
-    /**
-     *    Set amount paid towards this registration's final price
-     *
-     * @access    public
-     * @param    float $REG_paid
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_paid($REG_paid = 0.00)
-    {
-        $this->set('REG_paid', $REG_paid);
-    }
-
-
-    /**
-     *        Attendee Is Going
-     *
-     * @param        boolean $REG_att_is_going Attendee Is Going
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_att_is_going($REG_att_is_going = false)
-    {
-        $this->set('REG_att_is_going', $REG_att_is_going);
-    }
-
-
-    /**
-     * Gets the related attendee
-     *
-     * @return EE_Attendee
-     * @throws EE_Error
-     */
-    public function attendee()
-    {
-        return $this->get_first_related('Attendee');
-    }
-
-    /**
-     * Gets the name of the attendee.
-     * @since 4.10.12.p
-     * @param bool $apply_html_entities set to true if you want to use HTML entities.
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function attendeeName($apply_html_entities = false)
-    {
-        $attendee = $this->get_first_related('Attendee');
-        if ($attendee instanceof EE_Attendee) {
-            $attendee_name = $attendee->full_name($apply_html_entities);
-        } else {
-            $attendee_name = esc_html__('Unknown', 'event_espresso');
-        }
-        return $attendee_name;
-    }
-
-
-    /**
-     *        get Event ID
-     */
-    public function event_ID()
-    {
-        return $this->get('EVT_ID');
-    }
-
-
-    /**
-     *        get Event ID
-     */
-    public function event_name()
-    {
-        $event = $this->event_obj();
-        if ($event) {
-            return $event->name();
-        } else {
-            return null;
-        }
-    }
-
-
-    /**
-     * Fetches the event this registration is for
-     *
-     * @return EE_Event
-     * @throws EE_Error
-     */
-    public function event_obj()
-    {
-        return $this->get_first_related('Event');
-    }
-
-
-    /**
-     *        get Attendee ID
-     */
-    public function attendee_ID()
-    {
-        return $this->get('ATT_ID');
-    }
-
-
-    /**
-     *        get PHP Session ID
-     */
-    public function session_ID()
-    {
-        return $this->get('REG_session');
-    }
-
-
-    /**
-     * Gets the string which represents the URL trigger for the receipt template in the message template system.
-     *
-     * @param string $messenger 'pdf' or 'html'.  Default 'html'.
-     * @return string
-     */
-    public function receipt_url($messenger = 'html')
-    {
-
-        /**
-         * The below will be deprecated one version after this.  We check first if there is a custom receipt template
-         * already in use on old system.  If there is then we just return the standard url for it.
-         *
-         * @since 4.5.0
-         */
-        $template_relative_path = 'modules/gateways/Invoice/lib/templates/receipt_body.template.php';
-        $has_custom = EEH_Template::locate_template(
-            $template_relative_path,
-            array(),
-            true,
-            true,
-            true
-        );
-
-        if ($has_custom) {
-            return add_query_arg(array('receipt' => 'true'), $this->invoice_url('launch'));
-        }
-        return apply_filters('FHEE__EE_Registration__receipt_url__receipt_url', '', $this, $messenger, 'receipt');
-    }
-
-
-    /**
-     * Gets the string which represents the URL trigger for the invoice template in the message template system.
-     *
-     * @param string $messenger 'pdf' or 'html'.  Default 'html'.
-     * @return string
-     * @throws EE_Error
-     */
-    public function invoice_url($messenger = 'html')
-    {
-        /**
-         * The below will be deprecated one version after this.  We check first if there is a custom invoice template
-         * already in use on old system.  If there is then we just return the standard url for it.
-         *
-         * @since 4.5.0
-         */
-        $template_relative_path = 'modules/gateways/Invoice/lib/templates/invoice_body.template.php';
-        $has_custom = EEH_Template::locate_template(
-            $template_relative_path,
-            array(),
-            true,
-            true,
-            true
-        );
-
-        if ($has_custom) {
-            if ($messenger == 'html') {
-                return $this->invoice_url('launch');
-            }
-            $route = $messenger == 'download' || $messenger == 'pdf' ? 'download_invoice' : 'launch_invoice';
-
-            $query_args = array('ee' => $route, 'id' => $this->reg_url_link());
-            if ($messenger == 'html') {
-                $query_args['html'] = true;
-            }
-            return add_query_arg($query_args, get_permalink(EE_Registry::instance()->CFG->core->thank_you_page_id));
-        }
-        return apply_filters('FHEE__EE_Registration__invoice_url__invoice_url', '', $this, $messenger, 'invoice');
-    }
-
-
-    /**
-     * get Registration URL Link
-     *
-     * @access public
-     * @return string
-     * @throws EE_Error
-     */
-    public function reg_url_link()
-    {
-        return (string) $this->get('REG_url_link');
-    }
-
-
-    /**
-     * Echoes out invoice_url()
-     *
-     * @param string $type 'download','launch', or 'html' (default is 'launch')
-     * @return void
-     * @throws EE_Error
-     */
-    public function e_invoice_url($type = 'launch')
-    {
-        echo esc_url_raw($this->invoice_url($type));
-    }
-
-
-    /**
-     * Echoes out payment_overview_url
-     */
-    public function e_payment_overview_url()
-    {
-        echo esc_url_raw($this->payment_overview_url());
-    }
-
-
-    /**
-     * Gets the URL for the checkout payment options reg step
-     * with this registration's REG_url_link added as a query parameter
-     *
-     * @param bool $clear_session Set to true when you want to clear the session on revisiting the
-     *                            payment overview url.
-     * @return string
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     */
-    public function payment_overview_url($clear_session = false)
-    {
-        return add_query_arg(
-            (array) apply_filters(
-                'FHEE__EE_Registration__payment_overview_url__query_args',
-                array(
-                    'e_reg_url_link' => $this->reg_url_link(),
-                    'step'           => 'payment_options',
-                    'revisit'        => true,
-                    'clear_session'  => (bool) $clear_session,
-                ),
-                $this
-            ),
-            EE_Registry::instance()->CFG->core->reg_page_url()
-        );
-    }
-
-
-    /**
-     * Gets the URL for the checkout attendee information reg step
-     * with this registration's REG_url_link added as a query parameter
-     *
-     * @return string
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     */
-    public function edit_attendee_information_url()
-    {
-        return add_query_arg(
-            (array) apply_filters(
-                'FHEE__EE_Registration__edit_attendee_information_url__query_args',
-                array(
-                    'e_reg_url_link' => $this->reg_url_link(),
-                    'step'           => 'attendee_information',
-                    'revisit'        => true,
-                ),
-                $this
-            ),
-            EE_Registry::instance()->CFG->core->reg_page_url()
-        );
-    }
-
-
-    /**
-     * Simply generates and returns the appropriate admin_url link to edit this registration
-     *
-     * @return string
-     * @throws EE_Error
-     */
-    public function get_admin_edit_url()
-    {
-        return EEH_URL::add_query_args_and_nonce(
-            array(
-                'page'    => 'espresso_registrations',
-                'action'  => 'view_registration',
-                '_REG_ID' => $this->ID(),
-            ),
-            admin_url('admin.php')
-        );
-    }
-
-
-    /**
-     *    is_primary_registrant?
-     */
-    public function is_primary_registrant()
-    {
-        return $this->get('REG_count') === 1 ? true : false;
-    }
-
-
-    /**
-     * This returns the primary registration object for this registration group (which may be this object).
-     *
-     * @return EE_Registration
-     * @throws EE_Error
-     */
-    public function get_primary_registration()
-    {
-        if ($this->is_primary_registrant()) {
-            return $this;
-        }
-
-        // k reg_count !== 1 so let's get the EE_Registration object matching this txn_id and reg_count == 1
-        /** @var EE_Registration $primary_registrant */
-        $primary_registrant = EEM_Registration::instance()->get_one(
-            array(
-                array(
-                    'TXN_ID'    => $this->transaction_ID(),
-                    'REG_count' => 1,
-                ),
-            )
-        );
-        return $primary_registrant;
-    }
-
-
-    /**
-     *        get  Attendee Number
-     *
-     * @access        public
-     */
-    public function count()
-    {
-        return $this->get('REG_count');
-    }
-
-
-    /**
-     *        get Group Size
-     */
-    public function group_size()
-    {
-        return $this->get('REG_group_size');
-    }
-
-
-    /**
-     *        get Registration Date
-     */
-    public function date()
-    {
-        return $this->get('REG_date');
-    }
-
-
-    /**
-     * gets a pretty date
-     *
-     * @param string $date_format
-     * @param string $time_format
-     * @return string
-     * @throws EE_Error
-     */
-    public function pretty_date($date_format = null, $time_format = null)
-    {
-        return $this->get_datetime('REG_date', $date_format, $time_format);
-    }
-
-
-    /**
-     * final_price
-     * the registration's share of the transaction total, so that the
-     * sum of all the transaction's REG_final_prices equal the transaction's total
-     *
-     * @return float
-     * @throws EE_Error
-     */
-    public function final_price()
-    {
-        return $this->get('REG_final_price');
-    }
-
-
-    /**
-     * pretty_final_price
-     *  final price as formatted string, with correct decimal places and currency symbol
-     *
-     * @return string
-     * @throws EE_Error
-     */
-    public function pretty_final_price()
-    {
-        return $this->get_pretty('REG_final_price');
-    }
-
-
-    /**
-     * get paid (yeah)
-     *
-     * @return float
-     * @throws EE_Error
-     */
-    public function paid()
-    {
-        return $this->get('REG_paid');
-    }
-
-
-    /**
-     * pretty_paid
-     *
-     * @return float
-     * @throws EE_Error
-     */
-    public function pretty_paid()
-    {
-        return $this->get_pretty('REG_paid');
-    }
-
-
-    /**
-     * owes_monies_and_can_pay
-     * whether or not this registration has monies owing and it's' status allows payment
-     *
-     * @param array $requires_payment
-     * @return bool
-     * @throws EE_Error
-     */
-    public function owes_monies_and_can_pay($requires_payment = array())
-    {
-        // these reg statuses require payment (if event is not free)
-        $requires_payment = ! empty($requires_payment)
-            ? $requires_payment
-            : EEM_Registration::reg_statuses_that_allow_payment();
-        if (
-            in_array($this->status_ID(), $requires_payment) &&
-            $this->final_price() != 0 &&
-            $this->final_price() != $this->paid()
-        ) {
-            return true;
-        } else {
-            return false;
-        }
-    }
-
-
-    /**
-     * Prints out the return value of $this->pretty_status()
-     *
-     * @param bool $show_icons
-     * @return void
-     * @throws EE_Error
-     */
-    public function e_pretty_status($show_icons = false)
-    {
-        echo $this->pretty_status($show_icons); // already escaped
-    }
-
-
-    /**
-     * Returns a nice version of the status for displaying to customers
-     *
-     * @param bool $show_icons
-     * @return string
-     * @throws EE_Error
-     */
-    public function pretty_status($show_icons = false)
-    {
-        $status = EEM_Status::instance()->localized_status(
-            array($this->status_ID() => esc_html__('unknown', 'event_espresso')),
-            false,
-            'sentence'
-        );
-        $icon = '';
-        switch ($this->status_ID()) {
-            case EEM_Registration::status_id_approved:
-                $icon = $show_icons
-                    ? '<span class="dashicons dashicons-star-filled ee-icon-size-16 green-text"></span>'
-                    : '';
-                break;
-            case EEM_Registration::status_id_pending_payment:
-                $icon = $show_icons
-                    ? '<span class="dashicons dashicons-star-half ee-icon-size-16 orange-text"></span>'
-                    : '';
-                break;
-            case EEM_Registration::status_id_not_approved:
-                $icon = $show_icons
-                    ? '<span class="dashicons dashicons-marker ee-icon-size-16 orange-text"></span>'
-                    : '';
-                break;
-            case EEM_Registration::status_id_cancelled:
-                $icon = $show_icons
-                    ? '<span class="dashicons dashicons-no ee-icon-size-16 lt-grey-text"></span>'
-                    : '';
-                break;
-            case EEM_Registration::status_id_incomplete:
-                $icon = $show_icons
-                    ? '<span class="dashicons dashicons-no ee-icon-size-16 lt-orange-text"></span>'
-                    : '';
-                break;
-            case EEM_Registration::status_id_declined:
-                $icon = $show_icons
-                    ? '<span class="dashicons dashicons-no ee-icon-size-16 red-text"></span>'
-                    : '';
-                break;
-            case EEM_Registration::status_id_wait_list:
-                $icon = $show_icons
-                    ? '<span class="dashicons dashicons-clipboard ee-icon-size-16 purple-text"></span>'
-                    : '';
-                break;
-        }
-        return $icon . $status[ $this->status_ID() ];
-    }
-
-
-    /**
-     *        get Attendee Is Going
-     */
-    public function att_is_going()
-    {
-        return $this->get('REG_att_is_going');
-    }
-
-
-    /**
-     * Gets related answers
-     *
-     * @param array $query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
-     * @return EE_Answer[]
-     * @throws EE_Error
-     */
-    public function answers($query_params = null)
-    {
-        return $this->get_many_related('Answer', $query_params);
-    }
-
-
-    /**
-     * Gets the registration's answer value to the specified question
-     * (either the question's ID or a question object)
-     *
-     * @param EE_Question|int $question
-     * @param bool            $pretty_value
-     * @return array|string if pretty_value= true, the result will always be a string
-     * (because the answer might be an array of answer values, so passing pretty_value=true
-     * will convert it into some kind of string)
-     * @throws EE_Error
-     */
-    public function answer_value_to_question($question, $pretty_value = true)
-    {
-        $question_id = EEM_Question::instance()->ensure_is_ID($question);
-        return EEM_Answer::instance()->get_answer_value_to_question($this, $question_id, $pretty_value);
-    }
-
-
-    /**
-     * question_groups
-     * returns an array of EE_Question_Group objects for this registration
-     *
-     * @return EE_Question_Group[]
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function question_groups()
-    {
-        return EEM_Event::instance()->get_question_groups_for_event($this->event_ID(), $this);
-    }
-
-
-    /**
-     * count_question_groups
-     * returns a count of the number of EE_Question_Group objects for this registration
-     *
-     * @return int
-     * @throws EE_Error
-     * @throws EntityNotFoundException
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function count_question_groups()
-    {
-        return EEM_Event::instance()->count_related(
-            $this->event_ID(),
-            'Question_Group',
-            [
-                [
-                    'Event_Question_Group.'
-                    . EEM_Event_Question_Group::instance()->fieldNameForContext($this->is_primary_registrant()) => true,
-                ]
-            ]
-        );
-    }
-
-
-    /**
-     * Returns the registration date in the 'standard' string format
-     * (function may be improved in the future to allow for different formats and timezones)
-     *
-     * @return string
-     * @throws EE_Error
-     */
-    public function reg_date()
-    {
-        return $this->get_datetime('REG_date');
-    }
-
-
-    /**
-     * Gets the datetime-ticket for this registration (ie, it can be used to isolate
-     * the ticket this registration purchased, or the datetime they have registered
-     * to attend)
-     *
-     * @return EE_Datetime_Ticket
-     * @throws EE_Error
-     */
-    public function datetime_ticket()
-    {
-        return $this->get_first_related('Datetime_Ticket');
-    }
-
-
-    /**
-     * Sets the registration's datetime_ticket.
-     *
-     * @param EE_Datetime_Ticket $datetime_ticket
-     * @return EE_Datetime_Ticket
-     * @throws EE_Error
-     */
-    public function set_datetime_ticket($datetime_ticket)
-    {
-        return $this->_add_relation_to($datetime_ticket, 'Datetime_Ticket');
-    }
-
-    /**
-     * Gets deleted
-     *
-     * @return bool
-     * @throws EE_Error
-     */
-    public function deleted()
-    {
-        return $this->get('REG_deleted');
-    }
-
-    /**
-     * Sets deleted
-     *
-     * @param boolean $deleted
-     * @return bool
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_deleted($deleted)
-    {
-        if ($deleted) {
-            $this->delete();
-        } else {
-            $this->restore();
-        }
-    }
-
-
-    /**
-     * Get the status object of this object
-     *
-     * @return EE_Status
-     * @throws EE_Error
-     */
-    public function status_obj()
-    {
-        return $this->get_first_related('Status');
-    }
-
-
-    /**
-     * Returns the number of times this registration has checked into any of the datetimes
-     * its available for
-     *
-     * @return int
-     * @throws EE_Error
-     */
-    public function count_checkins()
-    {
-        return $this->get_model()->count_related($this, 'Checkin');
-    }
-
-
-    /**
-     * Returns the number of current Check-ins this registration is checked into for any of the datetimes the
-     * registration is for.  Note, this is ONLY checked in (does not include checkedout)
-     *
-     * @return int
-     * @throws EE_Error
-     */
-    public function count_checkins_not_checkedout()
-    {
-        return $this->get_model()->count_related($this, 'Checkin', array(array('CHK_in' => 1)));
-    }
-
-
-    /**
-     * The purpose of this method is simply to check whether this registration can checkin to the given datetime.
-     *
-     * @param int | EE_Datetime $DTT_OR_ID      The datetime the registration is being checked against
-     * @param bool              $check_approved This is used to indicate whether the caller wants can_checkin to also
-     *                                          consider registration status as well as datetime access.
-     * @return bool
-     * @throws EE_Error
-     */
-    public function can_checkin($DTT_OR_ID, $check_approved = true)
-    {
-        $DTT_ID = EEM_Datetime::instance()->ensure_is_ID($DTT_OR_ID);
-
-        // first check registration status
-        if (($check_approved && ! $this->is_approved()) || ! $DTT_ID) {
-            return false;
-        }
-        // is there a datetime ticket that matches this dtt_ID?
-        if (
-            ! (EEM_Datetime_Ticket::instance()->exists(
-                array(
-                array(
-                    'TKT_ID' => $this->get('TKT_ID'),
-                    'DTT_ID' => $DTT_ID,
-                ),
-                )
-            ))
-        ) {
-            return false;
-        }
-
-        // final check is against TKT_uses
-        return $this->verify_can_checkin_against_TKT_uses($DTT_ID);
-    }
-
-
-    /**
-     * This method verifies whether the user can checkin for the given datetime considering the max uses value set on
-     * the ticket. To do this,  a query is done to get the count of the datetime records already checked into.  If the
-     * datetime given does not have a check-in record and checking in for that datetime will exceed the allowed uses,
-     * then return false.  Otherwise return true.
-     *
-     * @param int | EE_Datetime $DTT_OR_ID The datetime the registration is being checked against
-     * @return bool true means can checkin.  false means cannot checkin.
-     * @throws EE_Error
-     */
-    public function verify_can_checkin_against_TKT_uses($DTT_OR_ID)
-    {
-        $DTT_ID = EEM_Datetime::instance()->ensure_is_ID($DTT_OR_ID);
-
-        if (! $DTT_ID) {
-            return false;
-        }
-
-        $max_uses = $this->ticket() instanceof EE_Ticket ? $this->ticket()->uses() : EE_INF;
-
-        // if max uses is not set or equals infinity then return true cause its not a factor for whether user can
-        // check-in or not.
-        if (! $max_uses || $max_uses === EE_INF) {
-            return true;
-        }
-
-        // does this datetime have a checkin record?  If so, then the dtt count has already been verified so we can just
-        // go ahead and toggle.
-        if (EEM_Checkin::instance()->exists(array(array('REG_ID' => $this->ID(), 'DTT_ID' => $DTT_ID)))) {
-            return true;
-        }
-
-        // made it here so the last check is whether the number of checkins per unique datetime on this registration
-        // disallows further check-ins.
-        $count_unique_dtt_checkins = EEM_Checkin::instance()->count(
-            array(
-                array(
-                    'REG_ID' => $this->ID(),
-                    'CHK_in' => true,
-                ),
-            ),
-            'DTT_ID',
-            true
-        );
-        // checkins have already reached their max number of uses
-        // so registrant can NOT checkin
-        if ($count_unique_dtt_checkins >= $max_uses) {
-            EE_Error::add_error(
-                esc_html__(
-                    'Check-in denied because number of datetime uses for the ticket has been reached or exceeded.',
-                    'event_espresso'
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return false;
-        }
-        return true;
-    }
-
-
-    /**
-     * toggle Check-in status for this registration
-     * Check-ins are toggled in the following order:
-     * never checked in -> checked in
-     * checked in -> checked out
-     * checked out -> checked in
-     *
-     * @param  int $DTT_ID  include specific datetime to toggle Check-in for.
-     *                      If not included or null, then it is assumed latest datetime is being toggled.
-     * @param bool $verify  If true then can_checkin() is used to verify whether the person
-     *                      can be checked in or not.  Otherwise this forces change in checkin status.
-     * @return bool|int     the chk_in status toggled to OR false if nothing got changed.
-     * @throws EE_Error
-     */
-    public function toggle_checkin_status($DTT_ID = null, $verify = false)
-    {
-        if (empty($DTT_ID)) {
-            $datetime = $this->get_latest_related_datetime();
-            $DTT_ID = $datetime instanceof EE_Datetime ? $datetime->ID() : 0;
-            // verify the registration can checkin for the given DTT_ID
-        } elseif (! $this->can_checkin($DTT_ID, $verify)) {
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'The given registration (ID:%1$d) can not be checked in to the given DTT_ID (%2$d), because the registration does not have access',
-                        'event_espresso'
-                    ),
-                    $this->ID(),
-                    $DTT_ID
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return false;
-        }
-        $status_paths = array(
-            EE_Checkin::status_checked_never => EE_Checkin::status_checked_in,
-            EE_Checkin::status_checked_in    => EE_Checkin::status_checked_out,
-            EE_Checkin::status_checked_out   => EE_Checkin::status_checked_in,
-        );
-        // start by getting the current status so we know what status we'll be changing to.
-        $cur_status = $this->check_in_status_for_datetime($DTT_ID, null);
-        $status_to = $status_paths[ $cur_status ];
-        // database only records true for checked IN or false for checked OUT
-        // no record ( null ) means checked in NEVER, but we obviously don't save that
-        $new_status = $status_to === EE_Checkin::status_checked_in ? true : false;
-        // add relation - note Check-ins are always creating new rows
-        // because we are keeping track of Check-ins over time.
-        // Eventually we'll probably want to show a list table
-        // for the individual Check-ins so that they can be managed.
-        $checkin = EE_Checkin::new_instance(
-            array(
-                'REG_ID' => $this->ID(),
-                'DTT_ID' => $DTT_ID,
-                'CHK_in' => $new_status,
-            )
-        );
-        // if the record could not be saved then return false
-        if ($checkin->save() === 0) {
-            if (WP_DEBUG) {
-                global $wpdb;
-                $error = sprintf(
-                    esc_html__(
-                        'Registration check in update failed because of the following database error: %1$s%2$s',
-                        'event_espresso'
-                    ),
-                    '<br />',
-                    $wpdb->last_error
-                );
-            } else {
-                $error = esc_html__(
-                    'Registration check in update failed because of an unknown database error',
-                    'event_espresso'
-                );
-            }
-            EE_Error::add_error($error, __FILE__, __FUNCTION__, __LINE__);
-            return false;
-        }
-        // Fire a checked_in and checkout_out action.
-        $checked_status = $status_to === EE_Checkin::status_checked_in ? 'checked_in' : 'checked_out';
-        do_action("AHEE__EE_Registration__toggle_checkin_status__{$checked_status}", $this, $DTT_ID);
-        return $status_to;
-    }
-
-
-    /**
-     * Returns the latest datetime related to this registration (via the ticket attached to the registration).
-     * "Latest" is defined by the `DTT_EVT_start` column.
-     *
-     * @return EE_Datetime|null
-     * @throws EE_Error
-     */
-    public function get_latest_related_datetime()
-    {
-        return EEM_Datetime::instance()->get_one(
-            array(
-                array(
-                    'Ticket.Registration.REG_ID' => $this->ID(),
-                ),
-                'order_by' => array('DTT_EVT_start' => 'DESC'),
-            )
-        );
-    }
-
-
-    /**
-     * Returns the earliest datetime related to this registration (via the ticket attached to the registration).
-     * "Earliest" is defined by the `DTT_EVT_start` column.
-     *
-     * @throws EE_Error
-     */
-    public function get_earliest_related_datetime()
-    {
-        return EEM_Datetime::instance()->get_one(
-            array(
-                array(
-                    'Ticket.Registration.REG_ID' => $this->ID(),
-                ),
-                'order_by' => array('DTT_EVT_start' => 'ASC'),
-            )
-        );
-    }
-
-
-    /**
-     * This method simply returns the check-in status for this registration and the given datetime.
-     * If neither the datetime nor the checkin values are provided as arguments,
-     * then this will return the LATEST check-in status for the registration across all datetimes it belongs to.
-     *
-     * @param  int       $DTT_ID  The ID of the datetime we're checking against
-     *                            (if empty we'll get the primary datetime for
-     *                            this registration (via event) and use it's ID);
-     * @param EE_Checkin $checkin If present, we use the given checkin object rather than the dtt_id.
-     *
-     * @return int                Integer representing Check-in status.
-     * @throws EE_Error
-     */
-    public function check_in_status_for_datetime($DTT_ID = 0, $checkin = null)
-    {
-        $checkin_query_params = array(
-            'order_by' => array('CHK_timestamp' => 'DESC'),
-        );
-
-        if ($DTT_ID > 0) {
-            $checkin_query_params[0] = array('DTT_ID' => $DTT_ID);
-        }
-
-        // get checkin object (if exists)
-        $checkin = $checkin instanceof EE_Checkin
-            ? $checkin
-            : $this->get_first_related('Checkin', $checkin_query_params);
-        if ($checkin instanceof EE_Checkin) {
-            if ($checkin->get('CHK_in')) {
-                return EE_Checkin::status_checked_in; // checked in
-            }
-            return EE_Checkin::status_checked_out; // had checked in but is now checked out.
-        }
-        return EE_Checkin::status_checked_never; // never been checked in
-    }
-
-
-    /**
-     * This method returns a localized message for the toggled Check-in message.
-     *
-     * @param  int $DTT_ID include specific datetime to get the correct Check-in message.  If not included or null,
-     *                     then it is assumed Check-in for primary datetime was toggled.
-     * @param bool $error  This just flags that you want an error message returned. This is put in so that the error
-     *                     message can be customized with the attendee name.
-     * @return string internationalized message
-     * @throws EE_Error
-     */
-    public function get_checkin_msg($DTT_ID, $error = false)
-    {
-        // let's get the attendee first so we can include the name of the attendee
-        $attendee = $this->get_first_related('Attendee');
-        if ($attendee instanceof EE_Attendee) {
-            if ($error) {
-                return sprintf(esc_html__("%s's check-in status was not changed.", "event_espresso"), $attendee->full_name());
-            }
-            $cur_status = $this->check_in_status_for_datetime($DTT_ID);
-            // what is the status message going to be?
-            switch ($cur_status) {
-                case EE_Checkin::status_checked_never:
-                    return sprintf(
-                        esc_html__("%s has been removed from Check-in records", "event_espresso"),
-                        $attendee->full_name()
-                    );
-                    break;
-                case EE_Checkin::status_checked_in:
-                    return sprintf(esc_html__('%s has been checked in', 'event_espresso'), $attendee->full_name());
-                    break;
-                case EE_Checkin::status_checked_out:
-                    return sprintf(esc_html__('%s has been checked out', 'event_espresso'), $attendee->full_name());
-                    break;
-            }
-        }
-        return esc_html__("The check-in status could not be determined.", "event_espresso");
-    }
-
-
-    /**
-     * Returns the related EE_Transaction to this registration
-     *
-     * @return EE_Transaction
-     * @throws EE_Error
-     * @throws EntityNotFoundException
-     */
-    public function transaction()
-    {
-        $transaction = $this->get_first_related('Transaction');
-        if (! $transaction instanceof \EE_Transaction) {
-            throw new EntityNotFoundException('Transaction ID', $this->transaction_ID());
-        }
-        return $transaction;
-    }
-
-
-    /**
-     *        get Registration Code
-     */
-    public function reg_code()
-    {
-        return $this->get('REG_code');
-    }
-
-
-    /**
-     *        get Transaction ID
-     */
-    public function transaction_ID()
-    {
-        return $this->get('TXN_ID');
-    }
-
-
-    /**
-     * @return int
-     * @throws EE_Error
-     */
-    public function ticket_ID()
-    {
-        return $this->get('TKT_ID');
-    }
-
-
-    /**
-     *        Set Registration Code
-     *
-     * @access    public
-     * @param    string  $REG_code Registration Code
-     * @param    boolean $use_default
-     * @throws EE_Error
-     */
-    public function set_reg_code($REG_code, $use_default = false)
-    {
-        if (empty($REG_code)) {
-            EE_Error::add_error(
-                esc_html__('REG_code can not be empty.', 'event_espresso'),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return;
-        }
-        if (! $this->reg_code()) {
-            parent::set('REG_code', $REG_code, $use_default);
-        } else {
-            EE_Error::doing_it_wrong(
-                __CLASS__ . '::' . __FUNCTION__,
-                esc_html__('Can not change a registration REG_code once it has been set.', 'event_espresso'),
-                '4.6.0'
-            );
-        }
-    }
-
-
-    /**
-     * Returns all other registrations in the same group as this registrant who have the same ticket option.
-     * Note, if you want to just get all registrations in the same transaction (group), use:
-     *    $registration->transaction()->registrations();
-     *
-     * @since 4.5.0
-     * @return EE_Registration[] or empty array if this isn't a group registration.
-     * @throws EE_Error
-     */
-    public function get_all_other_registrations_in_group()
-    {
-        if ($this->group_size() < 2) {
-            return array();
-        }
-
-        $query[0] = array(
-            'TXN_ID' => $this->transaction_ID(),
-            'REG_ID' => array('!=', $this->ID()),
-            'TKT_ID' => $this->ticket_ID(),
-        );
-        /** @var EE_Registration[] $registrations */
-        $registrations = $this->get_model()->get_all($query);
-        return $registrations;
-    }
-
-    /**
-     * Return the link to the admin details for the object.
-     *
-     * @return string
-     * @throws EE_Error
-     */
-    public function get_admin_details_link()
-    {
-        EE_Registry::instance()->load_helper('URL');
-        return EEH_URL::add_query_args_and_nonce(
-            array(
-                'page'    => 'espresso_registrations',
-                'action'  => 'view_registration',
-                '_REG_ID' => $this->ID(),
-            ),
-            admin_url('admin.php')
-        );
-    }
-
-    /**
-     * Returns the link to the editor for the object.  Sometimes this is the same as the details.
-     *
-     * @return string
-     * @throws EE_Error
-     */
-    public function get_admin_edit_link()
-    {
-        return $this->get_admin_details_link();
-    }
-
-    /**
-     * Returns the link to a settings page for the object.
-     *
-     * @return string
-     * @throws EE_Error
-     */
-    public function get_admin_settings_link()
-    {
-        return $this->get_admin_details_link();
-    }
-
-    /**
-     * Returns the link to the "overview" for the object (typically the "list table" view).
-     *
-     * @return string
-     */
-    public function get_admin_overview_link()
-    {
-        EE_Registry::instance()->load_helper('URL');
-        return EEH_URL::add_query_args_and_nonce(
-            array(
-                'page' => 'espresso_registrations',
-            ),
-            admin_url('admin.php')
-        );
-    }
-
-
-    /**
-     * @param array $query_params
-     *
-     * @return \EE_Registration[]
-     * @throws EE_Error
-     */
-    public function payments($query_params = array())
-    {
-        return $this->get_many_related('Payment', $query_params);
-    }
-
-
-    /**
-     * @param array $query_params
-     *
-     * @return \EE_Registration_Payment[]
-     * @throws EE_Error
-     */
-    public function registration_payments($query_params = array())
-    {
-        return $this->get_many_related('Registration_Payment', $query_params);
-    }
-
-
-    /**
-     * This grabs the payment method corresponding to the last payment made for the amount owing on the registration.
-     * Note: if there are no payments on the registration there will be no payment method returned.
-     *
-     * @return EE_Payment_Method|null
-     */
-    public function payment_method()
-    {
-        return EEM_Payment_Method::instance()->get_last_used_for_registration($this);
-    }
-
-
-    /**
-     * @return \EE_Line_Item
-     * @throws EntityNotFoundException
-     * @throws EE_Error
-     */
-    public function ticket_line_item()
-    {
-        $ticket = $this->ticket();
-        $transaction = $this->transaction();
-        $line_item = null;
-        $ticket_line_items = \EEH_Line_Item::get_line_items_by_object_type_and_IDs(
-            $transaction->total_line_item(),
-            'Ticket',
-            array($ticket->ID())
-        );
-        foreach ($ticket_line_items as $ticket_line_item) {
-            if (
-                $ticket_line_item instanceof \EE_Line_Item
-                && $ticket_line_item->OBJ_type() === 'Ticket'
-                && $ticket_line_item->OBJ_ID() === $ticket->ID()
-            ) {
-                $line_item = $ticket_line_item;
-                break;
-            }
-        }
-        if (! ($line_item instanceof \EE_Line_Item && $line_item->OBJ_type() === 'Ticket')) {
-            throw new EntityNotFoundException('Line Item Ticket ID', $ticket->ID());
-        }
-        return $line_item;
-    }
-
-
-    /**
-     * Soft Deletes this model object.
-     *
-     * @return boolean | int
-     * @throws RuntimeException
-     * @throws EE_Error
-     */
-    public function delete()
-    {
-        if ($this->update_extra_meta(EE_Registration::PRE_TRASH_REG_STATUS_KEY, $this->status_ID()) === true) {
-            $this->set_status(EEM_Registration::status_id_cancelled);
-        }
-        return parent::delete();
-    }
-
-
-    /**
-     * Restores whatever the previous status was on a registration before it was trashed (if possible)
-     *
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function restore()
-    {
-        $previous_status = $this->get_extra_meta(
-            EE_Registration::PRE_TRASH_REG_STATUS_KEY,
-            true,
-            EEM_Registration::status_id_cancelled
-        );
-        if ($previous_status) {
-            $this->delete_extra_meta(EE_Registration::PRE_TRASH_REG_STATUS_KEY);
-            $this->set_status($previous_status);
-        }
-        return parent::restore();
-    }
-
-
-    /**
-     * possibly toggle Registration status based on comparison of REG_paid vs REG_final_price
-     *
-     * @param  boolean $trigger_set_status_logic EE_Registration::set_status() can trigger additional logic
-     *                                           depending on whether the reg status changes to or from "Approved"
-     * @return boolean whether the Registration status was updated
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function updateStatusBasedOnTotalPaid($trigger_set_status_logic = true)
-    {
-        $paid = $this->paid();
-        $price = $this->final_price();
-        switch (true) {
-            // overpaid or paid
-            case EEH_Money::compare_floats($paid, $price, '>'):
-            case EEH_Money::compare_floats($paid, $price):
-                $new_status = EEM_Registration::status_id_approved;
-                break;
-            //  underpaid
-            case EEH_Money::compare_floats($paid, $price, '<'):
-                $new_status = EEM_Registration::status_id_pending_payment;
-                break;
-            // uhhh Houston...
-            default:
-                throw new RuntimeException(
-                    esc_html__('The total paid calculation for this registration is inaccurate.', 'event_espresso')
-                );
-        }
-        if ($new_status !== $this->status_ID()) {
-            if ($trigger_set_status_logic) {
-                return $this->set_status($new_status);
-            }
-            parent::set('STS_ID', $new_status);
-            return true;
-        }
-        return false;
-    }
-
-
-    /*************************** DEPRECATED ***************************/
-
-
-    /**
-     * @deprecated
-     * @since     4.7.0
-     * @access    public
-     */
-    public function price_paid()
-    {
-        EE_Error::doing_it_wrong(
-            'EE_Registration::price_paid()',
-            esc_html__(
-                'This method is deprecated, please use EE_Registration::final_price() instead.',
-                'event_espresso'
-            ),
-            '4.7.0'
-        );
-        return $this->final_price();
-    }
-
-
-    /**
-     * @deprecated
-     * @since     4.7.0
-     * @access    public
-     * @param    float $REG_final_price
-     * @throws EE_Error
-     * @throws RuntimeException
-     */
-    public function set_price_paid($REG_final_price = 0.00)
-    {
-        EE_Error::doing_it_wrong(
-            'EE_Registration::set_price_paid()',
-            esc_html__(
-                'This method is deprecated, please use EE_Registration::set_final_price() instead.',
-                'event_espresso'
-            ),
-            '4.7.0'
-        );
-        $this->set_final_price($REG_final_price);
-    }
-
-
-    /**
-     * @deprecated
-     * @since 4.7.0
-     * @return string
-     * @throws EE_Error
-     */
-    public function pretty_price_paid()
-    {
-        EE_Error::doing_it_wrong(
-            'EE_Registration::pretty_price_paid()',
-            esc_html__(
-                'This method is deprecated, please use EE_Registration::pretty_final_price() instead.',
-                'event_espresso'
-            ),
-            '4.7.0'
-        );
-        return $this->pretty_final_price();
-    }
-
-
-    /**
-     * Gets the primary datetime related to this registration via the related Event to this registration
-     *
-     * @deprecated 4.9.17
-     * @return EE_Datetime
-     * @throws EE_Error
-     * @throws EntityNotFoundException
-     */
-    public function get_related_primary_datetime()
-    {
-        EE_Error::doing_it_wrong(
-            __METHOD__,
-            esc_html__(
-                'Use EE_Registration::get_latest_related_datetime() or EE_Registration::get_earliest_related_datetime()',
-                'event_espresso'
-            ),
-            '4.9.17',
-            '5.0.0'
-        );
-        return $this->event()->primary_datetime();
-    }
-
-    /**
-     * Returns the contact's name (or "Unknown" if there is no contact.)
-     * @since 4.10.12.p
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function name()
-    {
-        return $this->attendeeName();
-    }
+	/**
+	 * Used to reference when a registration has never been checked in.
+	 *
+	 * @deprecated use \EE_Checkin::status_checked_never instead
+	 * @type int
+	 */
+	const checkin_status_never = 2;
+
+	/**
+	 * Used to reference when a registration has been checked in.
+	 *
+	 * @deprecated use \EE_Checkin::status_checked_in instead
+	 * @type int
+	 */
+	const checkin_status_in = 1;
+
+
+	/**
+	 * Used to reference when a registration has been checked out.
+	 *
+	 * @deprecated use \EE_Checkin::status_checked_out instead
+	 * @type int
+	 */
+	const checkin_status_out = 0;
+
+
+	/**
+	 * extra meta key for tracking reg status os trashed registrations
+	 *
+	 * @type string
+	 */
+	const PRE_TRASH_REG_STATUS_KEY = 'pre_trash_registration_status';
+
+
+	/**
+	 * extra meta key for tracking if registration has reserved ticket
+	 *
+	 * @type string
+	 */
+	const HAS_RESERVED_TICKET_KEY = 'has_reserved_ticket';
+
+
+	/**
+	 * @param array  $props_n_values          incoming values
+	 * @param string $timezone                incoming timezone (if not set the timezone set for the website will be
+	 *                                        used.)
+	 * @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 EE_Registration
+	 * @throws EE_Error
+	 */
+	public static function new_instance($props_n_values = array(), $timezone = null, $date_formats = array())
+	{
+		$has_object = parent::_check_for_object($props_n_values, __CLASS__, $timezone, $date_formats);
+		return $has_object ? $has_object : new self($props_n_values, false, $timezone, $date_formats);
+	}
+
+
+	/**
+	 * @param array  $props_n_values  incoming values from the database
+	 * @param string $timezone        incoming timezone as set by the model.  If not set the timezone for
+	 *                                the website will be used.
+	 * @return EE_Registration
+	 */
+	public static function new_instance_from_db($props_n_values = array(), $timezone = null)
+	{
+		return new self($props_n_values, true, $timezone);
+	}
+
+
+	/**
+	 *        Set Event ID
+	 *
+	 * @param        int $EVT_ID Event ID
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_event($EVT_ID = 0)
+	{
+		$this->set('EVT_ID', $EVT_ID);
+	}
+
+
+	/**
+	 * Overrides parent set() method so that all calls to set( 'REG_code', $REG_code ) OR set( 'STS_ID', $STS_ID ) can
+	 * be routed to internal methods
+	 *
+	 * @param string $field_name
+	 * @param mixed  $field_value
+	 * @param bool   $use_default
+	 * @throws EE_Error
+	 * @throws EntityNotFoundException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @throws RuntimeException
+	 */
+	public function set($field_name, $field_value, $use_default = false)
+	{
+		switch ($field_name) {
+			case 'REG_code':
+				if (! empty($field_value) && $this->reg_code() === null) {
+					$this->set_reg_code($field_value, $use_default);
+				}
+				break;
+			case 'STS_ID':
+				$this->set_status($field_value, $use_default);
+				break;
+			default:
+				parent::set($field_name, $field_value, $use_default);
+		}
+	}
+
+
+	/**
+	 * Set Status ID
+	 * updates the registration status and ALSO...
+	 * calls reserve_registration_space() if the reg status changes TO approved from any other reg status
+	 * calls release_registration_space() if the reg status changes FROM approved to any other reg status
+	 *
+	 * @param string                $new_STS_ID
+	 * @param boolean               $use_default
+	 * @param ContextInterface|null $context
+	 * @return bool
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws EntityNotFoundException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @throws RuntimeException
+	 * @throws UnexpectedEntityException
+	 */
+	public function set_status($new_STS_ID = null, $use_default = false, ContextInterface $context = null)
+	{
+		// get current REG_Status
+		$old_STS_ID = $this->status_ID();
+		// if status has changed
+		if (
+			$old_STS_ID !== $new_STS_ID // and that status has actually changed
+			&& ! empty($old_STS_ID) // and that old status is actually set
+			&& ! empty($new_STS_ID) // as well as the new status
+			&& $this->ID() // ensure registration is in the db
+		) {
+			// update internal status first
+			parent::set('STS_ID', $new_STS_ID, $use_default);
+			// THEN handle other changes that occur when reg status changes
+			// TO approved
+			if ($new_STS_ID === EEM_Registration::status_id_approved) {
+				// reserve a space by incrementing ticket and datetime sold values
+				$this->reserveRegistrationSpace();
+				do_action('AHEE__EE_Registration__set_status__to_approved', $this, $old_STS_ID, $new_STS_ID, $context);
+				// OR FROM  approved
+			} elseif ($old_STS_ID === EEM_Registration::status_id_approved) {
+				// release a space by decrementing ticket and datetime sold values
+				$this->releaseRegistrationSpace();
+				do_action(
+					'AHEE__EE_Registration__set_status__from_approved',
+					$this,
+					$old_STS_ID,
+					$new_STS_ID,
+					$context
+				);
+			}
+			// update status
+			parent::set('STS_ID', $new_STS_ID, $use_default);
+			$this->updateIfCanceledOrReinstated($new_STS_ID, $old_STS_ID, $context);
+			if ($this->statusChangeUpdatesTransaction($context)) {
+				$this->updateTransactionAfterStatusChange();
+			}
+			do_action('AHEE__EE_Registration__set_status__after_update', $this, $old_STS_ID, $new_STS_ID, $context);
+			return true;
+		}
+		// even though the old value matches the new value, it's still good to
+		// allow the parent set method to have a say
+		parent::set('STS_ID', $new_STS_ID, $use_default);
+		return true;
+	}
+
+
+	/**
+	 * update REGs and TXN when cancelled or declined registrations involved
+	 *
+	 * @param string                $new_STS_ID
+	 * @param string                $old_STS_ID
+	 * @param ContextInterface|null $context
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @throws RuntimeException
+	 */
+	private function updateIfCanceledOrReinstated($new_STS_ID, $old_STS_ID, ContextInterface $context = null)
+	{
+		// these reg statuses should not be considered in any calculations involving monies owing
+		$closed_reg_statuses = EEM_Registration::closed_reg_statuses();
+		// true if registration has been cancelled or declined
+		$this->updateIfCanceled(
+			$closed_reg_statuses,
+			$new_STS_ID,
+			$old_STS_ID,
+			$context
+		);
+		$this->updateIfReinstated(
+			$closed_reg_statuses,
+			$new_STS_ID,
+			$old_STS_ID,
+			$context
+		);
+	}
+
+
+	/**
+	 * update REGs and TXN when cancelled or declined registrations involved
+	 *
+	 * @param array                 $closed_reg_statuses
+	 * @param string                $new_STS_ID
+	 * @param string                $old_STS_ID
+	 * @param ContextInterface|null $context
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @throws RuntimeException
+	 */
+	private function updateIfCanceled(
+		array $closed_reg_statuses,
+		$new_STS_ID,
+		$old_STS_ID,
+		ContextInterface $context = null
+	) {
+		// true if registration has been cancelled or declined
+		if (
+			in_array($new_STS_ID, $closed_reg_statuses, true)
+			&& ! in_array($old_STS_ID, $closed_reg_statuses, true)
+		) {
+			/** @type EE_Registration_Processor $registration_processor */
+			$registration_processor = EE_Registry::instance()->load_class('Registration_Processor');
+			/** @type EE_Transaction_Processor $transaction_processor */
+			$transaction_processor = EE_Registry::instance()->load_class('Transaction_Processor');
+			// cancelled or declined registration
+			$registration_processor->update_registration_after_being_canceled_or_declined(
+				$this,
+				$closed_reg_statuses
+			);
+			$transaction_processor->update_transaction_after_canceled_or_declined_registration(
+				$this,
+				$closed_reg_statuses,
+				false
+			);
+			do_action(
+				'AHEE__EE_Registration__set_status__canceled_or_declined',
+				$this,
+				$old_STS_ID,
+				$new_STS_ID,
+				$context
+			);
+			return;
+		}
+	}
+
+
+	/**
+	 * update REGs and TXN when cancelled or declined registrations involved
+	 *
+	 * @param array                 $closed_reg_statuses
+	 * @param string                $new_STS_ID
+	 * @param string                $old_STS_ID
+	 * @param ContextInterface|null $context
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	private function updateIfReinstated(
+		array $closed_reg_statuses,
+		$new_STS_ID,
+		$old_STS_ID,
+		ContextInterface $context = null
+	) {
+		// true if reinstating cancelled or declined registration
+		if (
+			in_array($old_STS_ID, $closed_reg_statuses, true)
+			&& ! in_array($new_STS_ID, $closed_reg_statuses, true)
+		) {
+			/** @type EE_Registration_Processor $registration_processor */
+			$registration_processor = EE_Registry::instance()->load_class('Registration_Processor');
+			/** @type EE_Transaction_Processor $transaction_processor */
+			$transaction_processor = EE_Registry::instance()->load_class('Transaction_Processor');
+			// reinstating cancelled or declined registration
+			$registration_processor->update_canceled_or_declined_registration_after_being_reinstated(
+				$this,
+				$closed_reg_statuses
+			);
+			$transaction_processor->update_transaction_after_reinstating_canceled_registration(
+				$this,
+				$closed_reg_statuses,
+				false
+			);
+			do_action(
+				'AHEE__EE_Registration__set_status__after_reinstated',
+				$this,
+				$old_STS_ID,
+				$new_STS_ID,
+				$context
+			);
+		}
+	}
+
+
+	/**
+	 * @param ContextInterface|null $context
+	 * @return bool
+	 */
+	private function statusChangeUpdatesTransaction(ContextInterface $context = null)
+	{
+		$contexts_that_do_not_update_transaction = (array) apply_filters(
+			'AHEE__EE_Registration__statusChangeUpdatesTransaction__contexts_that_do_not_update_transaction',
+			array('spco_reg_step_attendee_information_process_registrations'),
+			$context,
+			$this
+		);
+		return ! (
+			$context instanceof ContextInterface
+			&& in_array($context->slug(), $contexts_that_do_not_update_transaction, true)
+		);
+	}
+
+
+	/**
+	 * @throws EE_Error
+	 * @throws EntityNotFoundException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @throws RuntimeException
+	 */
+	private function updateTransactionAfterStatusChange()
+	{
+		/** @type EE_Transaction_Payments $transaction_payments */
+		$transaction_payments = EE_Registry::instance()->load_class('Transaction_Payments');
+		$transaction_payments->recalculate_transaction_total($this->transaction(), false);
+		$this->transaction()->update_status_based_on_total_paid(true);
+	}
+
+
+	/**
+	 *        get Status ID
+	 */
+	public function status_ID()
+	{
+		return $this->get('STS_ID');
+	}
+
+
+	/**
+	 * Gets the ticket this registration is for
+	 *
+	 * @param boolean $include_archived whether to include archived tickets or not.
+	 *
+	 * @return EE_Ticket|EE_Base_Class
+	 * @throws EE_Error
+	 */
+	public function ticket($include_archived = true)
+	{
+		$query_params = array();
+		if ($include_archived) {
+			$query_params['default_where_conditions'] = 'none';
+		}
+		return $this->get_first_related('Ticket', $query_params);
+	}
+
+
+	/**
+	 * Gets the event this registration is for
+	 *
+	 * @return EE_Event
+	 * @throws EE_Error
+	 * @throws EntityNotFoundException
+	 */
+	public function event()
+	{
+		$event = $this->get_first_related('Event');
+		if (! $event instanceof \EE_Event) {
+			throw new EntityNotFoundException('Event ID', $this->event_ID());
+		}
+		return $event;
+	}
+
+
+	/**
+	 * Gets the "author" of the registration.  Note that for the purposes of registrations, the author will correspond
+	 * with the author of the event this registration is for.
+	 *
+	 * @since 4.5.0
+	 * @return int
+	 * @throws EE_Error
+	 * @throws EntityNotFoundException
+	 */
+	public function wp_user()
+	{
+		$event = $this->event();
+		if ($event instanceof EE_Event) {
+			return $event->wp_user();
+		}
+		return 0;
+	}
+
+
+	/**
+	 * increments this registration's related ticket sold and corresponding datetime sold values
+	 *
+	 * @return void
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws EntityNotFoundException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @throws UnexpectedEntityException
+	 */
+	private function reserveRegistrationSpace()
+	{
+		// reserved ticket and datetime counts will be decremented as sold counts are incremented
+		// so stop tracking that this reg has a ticket reserved
+		$this->release_reserved_ticket(false, "REG: {$this->ID()} (ln:" . __LINE__ . ')');
+		$ticket = $this->ticket();
+		$ticket->increaseSold();
+		// possibly set event status to sold out
+		$this->event()->perform_sold_out_status_check();
+	}
+
+
+	/**
+	 * decrements (subtracts) this registration's related ticket sold and corresponding datetime sold values
+	 *
+	 * @return void
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws EntityNotFoundException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @throws UnexpectedEntityException
+	 */
+	private function releaseRegistrationSpace()
+	{
+		$ticket = $this->ticket();
+		$ticket->decreaseSold();
+		// possibly change event status from sold out back to previous status
+		$this->event()->perform_sold_out_status_check();
+	}
+
+
+	/**
+	 * tracks this registration's ticket reservation in extra meta
+	 * and can increment related ticket reserved and corresponding datetime reserved values
+	 *
+	 * @param bool $update_ticket if true, will increment ticket and datetime reserved count
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function reserve_ticket($update_ticket = false, $source = 'unknown')
+	{
+		// only reserve ticket if space is not currently reserved
+		if ((bool) $this->get_extra_meta(EE_Registration::HAS_RESERVED_TICKET_KEY, true) !== true) {
+			$this->update_extra_meta('reserve_ticket', "{$this->ticket_ID()} from {$source}");
+			// IMPORTANT !!!
+			// although checking $update_ticket first would be more efficient,
+			// we NEED to ALWAYS call update_extra_meta(), which is why that is done first
+			if (
+				$this->update_extra_meta(EE_Registration::HAS_RESERVED_TICKET_KEY, true)
+				&& $update_ticket
+			) {
+				$ticket = $this->ticket();
+				$ticket->increaseReserved(1, "REG: {$this->ID()} (ln:" . __LINE__ . ')');
+				$ticket->save();
+			}
+		}
+	}
+
+
+	/**
+	 * stops tracking this registration's ticket reservation in extra meta
+	 * decrements (subtracts) related ticket reserved and corresponding datetime reserved values
+	 *
+	 * @param bool $update_ticket if true, will decrement ticket and datetime reserved count
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function release_reserved_ticket($update_ticket = false, $source = 'unknown')
+	{
+		// only release ticket if space is currently reserved
+		if ((bool) $this->get_extra_meta(EE_Registration::HAS_RESERVED_TICKET_KEY, true) === true) {
+			$this->update_extra_meta('release_reserved_ticket', "{$this->ticket_ID()} from {$source}");
+			// IMPORTANT !!!
+			// although checking $update_ticket first would be more efficient,
+			// we NEED to ALWAYS call update_extra_meta(), which is why that is done first
+			if (
+				$this->update_extra_meta(EE_Registration::HAS_RESERVED_TICKET_KEY, false)
+				&& $update_ticket
+			) {
+				$ticket = $this->ticket();
+				$ticket->decreaseReserved(1, true, "REG: {$this->ID()} (ln:" . __LINE__ . ')');
+			}
+		}
+	}
+
+
+	/**
+	 * Set Attendee ID
+	 *
+	 * @param        int $ATT_ID Attendee ID
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_attendee_id($ATT_ID = 0)
+	{
+		$this->set('ATT_ID', $ATT_ID);
+	}
+
+
+	/**
+	 *        Set Transaction ID
+	 *
+	 * @param        int $TXN_ID Transaction ID
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_transaction_id($TXN_ID = 0)
+	{
+		$this->set('TXN_ID', $TXN_ID);
+	}
+
+
+	/**
+	 *        Set Session
+	 *
+	 * @param    string $REG_session PHP Session ID
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_session($REG_session = '')
+	{
+		$this->set('REG_session', $REG_session);
+	}
+
+
+	/**
+	 *        Set Registration URL Link
+	 *
+	 * @param    string $REG_url_link Registration URL Link
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_reg_url_link($REG_url_link = '')
+	{
+		$this->set('REG_url_link', $REG_url_link);
+	}
+
+
+	/**
+	 *        Set Attendee Counter
+	 *
+	 * @param        int $REG_count Primary Attendee
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_count($REG_count = 1)
+	{
+		$this->set('REG_count', $REG_count);
+	}
+
+
+	/**
+	 *        Set Group Size
+	 *
+	 * @param        boolean $REG_group_size Group Registration
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_group_size($REG_group_size = false)
+	{
+		$this->set('REG_group_size', $REG_group_size);
+	}
+
+
+	/**
+	 *    is_not_approved -  convenience method that returns TRUE if REG status ID ==
+	 *    EEM_Registration::status_id_not_approved
+	 *
+	 * @return        boolean
+	 */
+	public function is_not_approved()
+	{
+		return $this->status_ID() == EEM_Registration::status_id_not_approved ? true : false;
+	}
+
+
+	/**
+	 *    is_pending_payment -  convenience method that returns TRUE if REG status ID ==
+	 *    EEM_Registration::status_id_pending_payment
+	 *
+	 * @return        boolean
+	 */
+	public function is_pending_payment()
+	{
+		return $this->status_ID() == EEM_Registration::status_id_pending_payment ? true : false;
+	}
+
+
+	/**
+	 *    is_approved -  convenience method that returns TRUE if REG status ID == EEM_Registration::status_id_approved
+	 *
+	 * @return        boolean
+	 */
+	public function is_approved()
+	{
+		return $this->status_ID() == EEM_Registration::status_id_approved ? true : false;
+	}
+
+
+	/**
+	 *    is_cancelled -  convenience method that returns TRUE if REG status ID == EEM_Registration::status_id_cancelled
+	 *
+	 * @return        boolean
+	 */
+	public function is_cancelled()
+	{
+		return $this->status_ID() == EEM_Registration::status_id_cancelled ? true : false;
+	}
+
+
+	/**
+	 *    is_declined -  convenience method that returns TRUE if REG status ID == EEM_Registration::status_id_declined
+	 *
+	 * @return        boolean
+	 */
+	public function is_declined()
+	{
+		return $this->status_ID() == EEM_Registration::status_id_declined ? true : false;
+	}
+
+
+	/**
+	 *    is_incomplete -  convenience method that returns TRUE if REG status ID ==
+	 *    EEM_Registration::status_id_incomplete
+	 *
+	 * @return        boolean
+	 */
+	public function is_incomplete()
+	{
+		return $this->status_ID() == EEM_Registration::status_id_incomplete ? true : false;
+	}
+
+
+	/**
+	 *        Set Registration Date
+	 *
+	 * @param        mixed ( int or string ) $REG_date Registration Date - Unix timestamp or string representation of
+	 *                                                 Date
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_reg_date($REG_date = false)
+	{
+		$this->set('REG_date', $REG_date);
+	}
+
+
+	/**
+	 *    Set final price owing for this registration after all ticket/price modifications
+	 *
+	 * @access    public
+	 * @param    float $REG_final_price
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_final_price($REG_final_price = 0.00)
+	{
+		$this->set('REG_final_price', $REG_final_price);
+	}
+
+
+	/**
+	 *    Set amount paid towards this registration's final price
+	 *
+	 * @access    public
+	 * @param    float $REG_paid
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_paid($REG_paid = 0.00)
+	{
+		$this->set('REG_paid', $REG_paid);
+	}
+
+
+	/**
+	 *        Attendee Is Going
+	 *
+	 * @param        boolean $REG_att_is_going Attendee Is Going
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_att_is_going($REG_att_is_going = false)
+	{
+		$this->set('REG_att_is_going', $REG_att_is_going);
+	}
+
+
+	/**
+	 * Gets the related attendee
+	 *
+	 * @return EE_Attendee
+	 * @throws EE_Error
+	 */
+	public function attendee()
+	{
+		return $this->get_first_related('Attendee');
+	}
+
+	/**
+	 * Gets the name of the attendee.
+	 * @since 4.10.12.p
+	 * @param bool $apply_html_entities set to true if you want to use HTML entities.
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function attendeeName($apply_html_entities = false)
+	{
+		$attendee = $this->get_first_related('Attendee');
+		if ($attendee instanceof EE_Attendee) {
+			$attendee_name = $attendee->full_name($apply_html_entities);
+		} else {
+			$attendee_name = esc_html__('Unknown', 'event_espresso');
+		}
+		return $attendee_name;
+	}
+
+
+	/**
+	 *        get Event ID
+	 */
+	public function event_ID()
+	{
+		return $this->get('EVT_ID');
+	}
+
+
+	/**
+	 *        get Event ID
+	 */
+	public function event_name()
+	{
+		$event = $this->event_obj();
+		if ($event) {
+			return $event->name();
+		} else {
+			return null;
+		}
+	}
+
+
+	/**
+	 * Fetches the event this registration is for
+	 *
+	 * @return EE_Event
+	 * @throws EE_Error
+	 */
+	public function event_obj()
+	{
+		return $this->get_first_related('Event');
+	}
+
+
+	/**
+	 *        get Attendee ID
+	 */
+	public function attendee_ID()
+	{
+		return $this->get('ATT_ID');
+	}
+
+
+	/**
+	 *        get PHP Session ID
+	 */
+	public function session_ID()
+	{
+		return $this->get('REG_session');
+	}
+
+
+	/**
+	 * Gets the string which represents the URL trigger for the receipt template in the message template system.
+	 *
+	 * @param string $messenger 'pdf' or 'html'.  Default 'html'.
+	 * @return string
+	 */
+	public function receipt_url($messenger = 'html')
+	{
+
+		/**
+		 * The below will be deprecated one version after this.  We check first if there is a custom receipt template
+		 * already in use on old system.  If there is then we just return the standard url for it.
+		 *
+		 * @since 4.5.0
+		 */
+		$template_relative_path = 'modules/gateways/Invoice/lib/templates/receipt_body.template.php';
+		$has_custom = EEH_Template::locate_template(
+			$template_relative_path,
+			array(),
+			true,
+			true,
+			true
+		);
+
+		if ($has_custom) {
+			return add_query_arg(array('receipt' => 'true'), $this->invoice_url('launch'));
+		}
+		return apply_filters('FHEE__EE_Registration__receipt_url__receipt_url', '', $this, $messenger, 'receipt');
+	}
+
+
+	/**
+	 * Gets the string which represents the URL trigger for the invoice template in the message template system.
+	 *
+	 * @param string $messenger 'pdf' or 'html'.  Default 'html'.
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function invoice_url($messenger = 'html')
+	{
+		/**
+		 * The below will be deprecated one version after this.  We check first if there is a custom invoice template
+		 * already in use on old system.  If there is then we just return the standard url for it.
+		 *
+		 * @since 4.5.0
+		 */
+		$template_relative_path = 'modules/gateways/Invoice/lib/templates/invoice_body.template.php';
+		$has_custom = EEH_Template::locate_template(
+			$template_relative_path,
+			array(),
+			true,
+			true,
+			true
+		);
+
+		if ($has_custom) {
+			if ($messenger == 'html') {
+				return $this->invoice_url('launch');
+			}
+			$route = $messenger == 'download' || $messenger == 'pdf' ? 'download_invoice' : 'launch_invoice';
+
+			$query_args = array('ee' => $route, 'id' => $this->reg_url_link());
+			if ($messenger == 'html') {
+				$query_args['html'] = true;
+			}
+			return add_query_arg($query_args, get_permalink(EE_Registry::instance()->CFG->core->thank_you_page_id));
+		}
+		return apply_filters('FHEE__EE_Registration__invoice_url__invoice_url', '', $this, $messenger, 'invoice');
+	}
+
+
+	/**
+	 * get Registration URL Link
+	 *
+	 * @access public
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function reg_url_link()
+	{
+		return (string) $this->get('REG_url_link');
+	}
+
+
+	/**
+	 * Echoes out invoice_url()
+	 *
+	 * @param string $type 'download','launch', or 'html' (default is 'launch')
+	 * @return void
+	 * @throws EE_Error
+	 */
+	public function e_invoice_url($type = 'launch')
+	{
+		echo esc_url_raw($this->invoice_url($type));
+	}
+
+
+	/**
+	 * Echoes out payment_overview_url
+	 */
+	public function e_payment_overview_url()
+	{
+		echo esc_url_raw($this->payment_overview_url());
+	}
+
+
+	/**
+	 * Gets the URL for the checkout payment options reg step
+	 * with this registration's REG_url_link added as a query parameter
+	 *
+	 * @param bool $clear_session Set to true when you want to clear the session on revisiting the
+	 *                            payment overview url.
+	 * @return string
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 */
+	public function payment_overview_url($clear_session = false)
+	{
+		return add_query_arg(
+			(array) apply_filters(
+				'FHEE__EE_Registration__payment_overview_url__query_args',
+				array(
+					'e_reg_url_link' => $this->reg_url_link(),
+					'step'           => 'payment_options',
+					'revisit'        => true,
+					'clear_session'  => (bool) $clear_session,
+				),
+				$this
+			),
+			EE_Registry::instance()->CFG->core->reg_page_url()
+		);
+	}
+
+
+	/**
+	 * Gets the URL for the checkout attendee information reg step
+	 * with this registration's REG_url_link added as a query parameter
+	 *
+	 * @return string
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 */
+	public function edit_attendee_information_url()
+	{
+		return add_query_arg(
+			(array) apply_filters(
+				'FHEE__EE_Registration__edit_attendee_information_url__query_args',
+				array(
+					'e_reg_url_link' => $this->reg_url_link(),
+					'step'           => 'attendee_information',
+					'revisit'        => true,
+				),
+				$this
+			),
+			EE_Registry::instance()->CFG->core->reg_page_url()
+		);
+	}
+
+
+	/**
+	 * Simply generates and returns the appropriate admin_url link to edit this registration
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function get_admin_edit_url()
+	{
+		return EEH_URL::add_query_args_and_nonce(
+			array(
+				'page'    => 'espresso_registrations',
+				'action'  => 'view_registration',
+				'_REG_ID' => $this->ID(),
+			),
+			admin_url('admin.php')
+		);
+	}
+
+
+	/**
+	 *    is_primary_registrant?
+	 */
+	public function is_primary_registrant()
+	{
+		return $this->get('REG_count') === 1 ? true : false;
+	}
+
+
+	/**
+	 * This returns the primary registration object for this registration group (which may be this object).
+	 *
+	 * @return EE_Registration
+	 * @throws EE_Error
+	 */
+	public function get_primary_registration()
+	{
+		if ($this->is_primary_registrant()) {
+			return $this;
+		}
+
+		// k reg_count !== 1 so let's get the EE_Registration object matching this txn_id and reg_count == 1
+		/** @var EE_Registration $primary_registrant */
+		$primary_registrant = EEM_Registration::instance()->get_one(
+			array(
+				array(
+					'TXN_ID'    => $this->transaction_ID(),
+					'REG_count' => 1,
+				),
+			)
+		);
+		return $primary_registrant;
+	}
+
+
+	/**
+	 *        get  Attendee Number
+	 *
+	 * @access        public
+	 */
+	public function count()
+	{
+		return $this->get('REG_count');
+	}
+
+
+	/**
+	 *        get Group Size
+	 */
+	public function group_size()
+	{
+		return $this->get('REG_group_size');
+	}
+
+
+	/**
+	 *        get Registration Date
+	 */
+	public function date()
+	{
+		return $this->get('REG_date');
+	}
+
+
+	/**
+	 * gets a pretty date
+	 *
+	 * @param string $date_format
+	 * @param string $time_format
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function pretty_date($date_format = null, $time_format = null)
+	{
+		return $this->get_datetime('REG_date', $date_format, $time_format);
+	}
+
+
+	/**
+	 * final_price
+	 * the registration's share of the transaction total, so that the
+	 * sum of all the transaction's REG_final_prices equal the transaction's total
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 */
+	public function final_price()
+	{
+		return $this->get('REG_final_price');
+	}
+
+
+	/**
+	 * pretty_final_price
+	 *  final price as formatted string, with correct decimal places and currency symbol
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function pretty_final_price()
+	{
+		return $this->get_pretty('REG_final_price');
+	}
+
+
+	/**
+	 * get paid (yeah)
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 */
+	public function paid()
+	{
+		return $this->get('REG_paid');
+	}
+
+
+	/**
+	 * pretty_paid
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 */
+	public function pretty_paid()
+	{
+		return $this->get_pretty('REG_paid');
+	}
+
+
+	/**
+	 * owes_monies_and_can_pay
+	 * whether or not this registration has monies owing and it's' status allows payment
+	 *
+	 * @param array $requires_payment
+	 * @return bool
+	 * @throws EE_Error
+	 */
+	public function owes_monies_and_can_pay($requires_payment = array())
+	{
+		// these reg statuses require payment (if event is not free)
+		$requires_payment = ! empty($requires_payment)
+			? $requires_payment
+			: EEM_Registration::reg_statuses_that_allow_payment();
+		if (
+			in_array($this->status_ID(), $requires_payment) &&
+			$this->final_price() != 0 &&
+			$this->final_price() != $this->paid()
+		) {
+			return true;
+		} else {
+			return false;
+		}
+	}
+
+
+	/**
+	 * Prints out the return value of $this->pretty_status()
+	 *
+	 * @param bool $show_icons
+	 * @return void
+	 * @throws EE_Error
+	 */
+	public function e_pretty_status($show_icons = false)
+	{
+		echo $this->pretty_status($show_icons); // already escaped
+	}
+
+
+	/**
+	 * Returns a nice version of the status for displaying to customers
+	 *
+	 * @param bool $show_icons
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function pretty_status($show_icons = false)
+	{
+		$status = EEM_Status::instance()->localized_status(
+			array($this->status_ID() => esc_html__('unknown', 'event_espresso')),
+			false,
+			'sentence'
+		);
+		$icon = '';
+		switch ($this->status_ID()) {
+			case EEM_Registration::status_id_approved:
+				$icon = $show_icons
+					? '<span class="dashicons dashicons-star-filled ee-icon-size-16 green-text"></span>'
+					: '';
+				break;
+			case EEM_Registration::status_id_pending_payment:
+				$icon = $show_icons
+					? '<span class="dashicons dashicons-star-half ee-icon-size-16 orange-text"></span>'
+					: '';
+				break;
+			case EEM_Registration::status_id_not_approved:
+				$icon = $show_icons
+					? '<span class="dashicons dashicons-marker ee-icon-size-16 orange-text"></span>'
+					: '';
+				break;
+			case EEM_Registration::status_id_cancelled:
+				$icon = $show_icons
+					? '<span class="dashicons dashicons-no ee-icon-size-16 lt-grey-text"></span>'
+					: '';
+				break;
+			case EEM_Registration::status_id_incomplete:
+				$icon = $show_icons
+					? '<span class="dashicons dashicons-no ee-icon-size-16 lt-orange-text"></span>'
+					: '';
+				break;
+			case EEM_Registration::status_id_declined:
+				$icon = $show_icons
+					? '<span class="dashicons dashicons-no ee-icon-size-16 red-text"></span>'
+					: '';
+				break;
+			case EEM_Registration::status_id_wait_list:
+				$icon = $show_icons
+					? '<span class="dashicons dashicons-clipboard ee-icon-size-16 purple-text"></span>'
+					: '';
+				break;
+		}
+		return $icon . $status[ $this->status_ID() ];
+	}
+
+
+	/**
+	 *        get Attendee Is Going
+	 */
+	public function att_is_going()
+	{
+		return $this->get('REG_att_is_going');
+	}
+
+
+	/**
+	 * Gets related answers
+	 *
+	 * @param array $query_params @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
+	 * @return EE_Answer[]
+	 * @throws EE_Error
+	 */
+	public function answers($query_params = null)
+	{
+		return $this->get_many_related('Answer', $query_params);
+	}
+
+
+	/**
+	 * Gets the registration's answer value to the specified question
+	 * (either the question's ID or a question object)
+	 *
+	 * @param EE_Question|int $question
+	 * @param bool            $pretty_value
+	 * @return array|string if pretty_value= true, the result will always be a string
+	 * (because the answer might be an array of answer values, so passing pretty_value=true
+	 * will convert it into some kind of string)
+	 * @throws EE_Error
+	 */
+	public function answer_value_to_question($question, $pretty_value = true)
+	{
+		$question_id = EEM_Question::instance()->ensure_is_ID($question);
+		return EEM_Answer::instance()->get_answer_value_to_question($this, $question_id, $pretty_value);
+	}
+
+
+	/**
+	 * question_groups
+	 * returns an array of EE_Question_Group objects for this registration
+	 *
+	 * @return EE_Question_Group[]
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function question_groups()
+	{
+		return EEM_Event::instance()->get_question_groups_for_event($this->event_ID(), $this);
+	}
+
+
+	/**
+	 * count_question_groups
+	 * returns a count of the number of EE_Question_Group objects for this registration
+	 *
+	 * @return int
+	 * @throws EE_Error
+	 * @throws EntityNotFoundException
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function count_question_groups()
+	{
+		return EEM_Event::instance()->count_related(
+			$this->event_ID(),
+			'Question_Group',
+			[
+				[
+					'Event_Question_Group.'
+					. EEM_Event_Question_Group::instance()->fieldNameForContext($this->is_primary_registrant()) => true,
+				]
+			]
+		);
+	}
+
+
+	/**
+	 * Returns the registration date in the 'standard' string format
+	 * (function may be improved in the future to allow for different formats and timezones)
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function reg_date()
+	{
+		return $this->get_datetime('REG_date');
+	}
+
+
+	/**
+	 * Gets the datetime-ticket for this registration (ie, it can be used to isolate
+	 * the ticket this registration purchased, or the datetime they have registered
+	 * to attend)
+	 *
+	 * @return EE_Datetime_Ticket
+	 * @throws EE_Error
+	 */
+	public function datetime_ticket()
+	{
+		return $this->get_first_related('Datetime_Ticket');
+	}
+
+
+	/**
+	 * Sets the registration's datetime_ticket.
+	 *
+	 * @param EE_Datetime_Ticket $datetime_ticket
+	 * @return EE_Datetime_Ticket
+	 * @throws EE_Error
+	 */
+	public function set_datetime_ticket($datetime_ticket)
+	{
+		return $this->_add_relation_to($datetime_ticket, 'Datetime_Ticket');
+	}
+
+	/**
+	 * Gets deleted
+	 *
+	 * @return bool
+	 * @throws EE_Error
+	 */
+	public function deleted()
+	{
+		return $this->get('REG_deleted');
+	}
+
+	/**
+	 * Sets deleted
+	 *
+	 * @param boolean $deleted
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_deleted($deleted)
+	{
+		if ($deleted) {
+			$this->delete();
+		} else {
+			$this->restore();
+		}
+	}
+
+
+	/**
+	 * Get the status object of this object
+	 *
+	 * @return EE_Status
+	 * @throws EE_Error
+	 */
+	public function status_obj()
+	{
+		return $this->get_first_related('Status');
+	}
+
+
+	/**
+	 * Returns the number of times this registration has checked into any of the datetimes
+	 * its available for
+	 *
+	 * @return int
+	 * @throws EE_Error
+	 */
+	public function count_checkins()
+	{
+		return $this->get_model()->count_related($this, 'Checkin');
+	}
+
+
+	/**
+	 * Returns the number of current Check-ins this registration is checked into for any of the datetimes the
+	 * registration is for.  Note, this is ONLY checked in (does not include checkedout)
+	 *
+	 * @return int
+	 * @throws EE_Error
+	 */
+	public function count_checkins_not_checkedout()
+	{
+		return $this->get_model()->count_related($this, 'Checkin', array(array('CHK_in' => 1)));
+	}
+
+
+	/**
+	 * The purpose of this method is simply to check whether this registration can checkin to the given datetime.
+	 *
+	 * @param int | EE_Datetime $DTT_OR_ID      The datetime the registration is being checked against
+	 * @param bool              $check_approved This is used to indicate whether the caller wants can_checkin to also
+	 *                                          consider registration status as well as datetime access.
+	 * @return bool
+	 * @throws EE_Error
+	 */
+	public function can_checkin($DTT_OR_ID, $check_approved = true)
+	{
+		$DTT_ID = EEM_Datetime::instance()->ensure_is_ID($DTT_OR_ID);
+
+		// first check registration status
+		if (($check_approved && ! $this->is_approved()) || ! $DTT_ID) {
+			return false;
+		}
+		// is there a datetime ticket that matches this dtt_ID?
+		if (
+			! (EEM_Datetime_Ticket::instance()->exists(
+				array(
+				array(
+					'TKT_ID' => $this->get('TKT_ID'),
+					'DTT_ID' => $DTT_ID,
+				),
+				)
+			))
+		) {
+			return false;
+		}
+
+		// final check is against TKT_uses
+		return $this->verify_can_checkin_against_TKT_uses($DTT_ID);
+	}
+
+
+	/**
+	 * This method verifies whether the user can checkin for the given datetime considering the max uses value set on
+	 * the ticket. To do this,  a query is done to get the count of the datetime records already checked into.  If the
+	 * datetime given does not have a check-in record and checking in for that datetime will exceed the allowed uses,
+	 * then return false.  Otherwise return true.
+	 *
+	 * @param int | EE_Datetime $DTT_OR_ID The datetime the registration is being checked against
+	 * @return bool true means can checkin.  false means cannot checkin.
+	 * @throws EE_Error
+	 */
+	public function verify_can_checkin_against_TKT_uses($DTT_OR_ID)
+	{
+		$DTT_ID = EEM_Datetime::instance()->ensure_is_ID($DTT_OR_ID);
+
+		if (! $DTT_ID) {
+			return false;
+		}
+
+		$max_uses = $this->ticket() instanceof EE_Ticket ? $this->ticket()->uses() : EE_INF;
+
+		// if max uses is not set or equals infinity then return true cause its not a factor for whether user can
+		// check-in or not.
+		if (! $max_uses || $max_uses === EE_INF) {
+			return true;
+		}
+
+		// does this datetime have a checkin record?  If so, then the dtt count has already been verified so we can just
+		// go ahead and toggle.
+		if (EEM_Checkin::instance()->exists(array(array('REG_ID' => $this->ID(), 'DTT_ID' => $DTT_ID)))) {
+			return true;
+		}
+
+		// made it here so the last check is whether the number of checkins per unique datetime on this registration
+		// disallows further check-ins.
+		$count_unique_dtt_checkins = EEM_Checkin::instance()->count(
+			array(
+				array(
+					'REG_ID' => $this->ID(),
+					'CHK_in' => true,
+				),
+			),
+			'DTT_ID',
+			true
+		);
+		// checkins have already reached their max number of uses
+		// so registrant can NOT checkin
+		if ($count_unique_dtt_checkins >= $max_uses) {
+			EE_Error::add_error(
+				esc_html__(
+					'Check-in denied because number of datetime uses for the ticket has been reached or exceeded.',
+					'event_espresso'
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return false;
+		}
+		return true;
+	}
+
+
+	/**
+	 * toggle Check-in status for this registration
+	 * Check-ins are toggled in the following order:
+	 * never checked in -> checked in
+	 * checked in -> checked out
+	 * checked out -> checked in
+	 *
+	 * @param  int $DTT_ID  include specific datetime to toggle Check-in for.
+	 *                      If not included or null, then it is assumed latest datetime is being toggled.
+	 * @param bool $verify  If true then can_checkin() is used to verify whether the person
+	 *                      can be checked in or not.  Otherwise this forces change in checkin status.
+	 * @return bool|int     the chk_in status toggled to OR false if nothing got changed.
+	 * @throws EE_Error
+	 */
+	public function toggle_checkin_status($DTT_ID = null, $verify = false)
+	{
+		if (empty($DTT_ID)) {
+			$datetime = $this->get_latest_related_datetime();
+			$DTT_ID = $datetime instanceof EE_Datetime ? $datetime->ID() : 0;
+			// verify the registration can checkin for the given DTT_ID
+		} elseif (! $this->can_checkin($DTT_ID, $verify)) {
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'The given registration (ID:%1$d) can not be checked in to the given DTT_ID (%2$d), because the registration does not have access',
+						'event_espresso'
+					),
+					$this->ID(),
+					$DTT_ID
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return false;
+		}
+		$status_paths = array(
+			EE_Checkin::status_checked_never => EE_Checkin::status_checked_in,
+			EE_Checkin::status_checked_in    => EE_Checkin::status_checked_out,
+			EE_Checkin::status_checked_out   => EE_Checkin::status_checked_in,
+		);
+		// start by getting the current status so we know what status we'll be changing to.
+		$cur_status = $this->check_in_status_for_datetime($DTT_ID, null);
+		$status_to = $status_paths[ $cur_status ];
+		// database only records true for checked IN or false for checked OUT
+		// no record ( null ) means checked in NEVER, but we obviously don't save that
+		$new_status = $status_to === EE_Checkin::status_checked_in ? true : false;
+		// add relation - note Check-ins are always creating new rows
+		// because we are keeping track of Check-ins over time.
+		// Eventually we'll probably want to show a list table
+		// for the individual Check-ins so that they can be managed.
+		$checkin = EE_Checkin::new_instance(
+			array(
+				'REG_ID' => $this->ID(),
+				'DTT_ID' => $DTT_ID,
+				'CHK_in' => $new_status,
+			)
+		);
+		// if the record could not be saved then return false
+		if ($checkin->save() === 0) {
+			if (WP_DEBUG) {
+				global $wpdb;
+				$error = sprintf(
+					esc_html__(
+						'Registration check in update failed because of the following database error: %1$s%2$s',
+						'event_espresso'
+					),
+					'<br />',
+					$wpdb->last_error
+				);
+			} else {
+				$error = esc_html__(
+					'Registration check in update failed because of an unknown database error',
+					'event_espresso'
+				);
+			}
+			EE_Error::add_error($error, __FILE__, __FUNCTION__, __LINE__);
+			return false;
+		}
+		// Fire a checked_in and checkout_out action.
+		$checked_status = $status_to === EE_Checkin::status_checked_in ? 'checked_in' : 'checked_out';
+		do_action("AHEE__EE_Registration__toggle_checkin_status__{$checked_status}", $this, $DTT_ID);
+		return $status_to;
+	}
+
+
+	/**
+	 * Returns the latest datetime related to this registration (via the ticket attached to the registration).
+	 * "Latest" is defined by the `DTT_EVT_start` column.
+	 *
+	 * @return EE_Datetime|null
+	 * @throws EE_Error
+	 */
+	public function get_latest_related_datetime()
+	{
+		return EEM_Datetime::instance()->get_one(
+			array(
+				array(
+					'Ticket.Registration.REG_ID' => $this->ID(),
+				),
+				'order_by' => array('DTT_EVT_start' => 'DESC'),
+			)
+		);
+	}
+
+
+	/**
+	 * Returns the earliest datetime related to this registration (via the ticket attached to the registration).
+	 * "Earliest" is defined by the `DTT_EVT_start` column.
+	 *
+	 * @throws EE_Error
+	 */
+	public function get_earliest_related_datetime()
+	{
+		return EEM_Datetime::instance()->get_one(
+			array(
+				array(
+					'Ticket.Registration.REG_ID' => $this->ID(),
+				),
+				'order_by' => array('DTT_EVT_start' => 'ASC'),
+			)
+		);
+	}
+
+
+	/**
+	 * This method simply returns the check-in status for this registration and the given datetime.
+	 * If neither the datetime nor the checkin values are provided as arguments,
+	 * then this will return the LATEST check-in status for the registration across all datetimes it belongs to.
+	 *
+	 * @param  int       $DTT_ID  The ID of the datetime we're checking against
+	 *                            (if empty we'll get the primary datetime for
+	 *                            this registration (via event) and use it's ID);
+	 * @param EE_Checkin $checkin If present, we use the given checkin object rather than the dtt_id.
+	 *
+	 * @return int                Integer representing Check-in status.
+	 * @throws EE_Error
+	 */
+	public function check_in_status_for_datetime($DTT_ID = 0, $checkin = null)
+	{
+		$checkin_query_params = array(
+			'order_by' => array('CHK_timestamp' => 'DESC'),
+		);
+
+		if ($DTT_ID > 0) {
+			$checkin_query_params[0] = array('DTT_ID' => $DTT_ID);
+		}
+
+		// get checkin object (if exists)
+		$checkin = $checkin instanceof EE_Checkin
+			? $checkin
+			: $this->get_first_related('Checkin', $checkin_query_params);
+		if ($checkin instanceof EE_Checkin) {
+			if ($checkin->get('CHK_in')) {
+				return EE_Checkin::status_checked_in; // checked in
+			}
+			return EE_Checkin::status_checked_out; // had checked in but is now checked out.
+		}
+		return EE_Checkin::status_checked_never; // never been checked in
+	}
+
+
+	/**
+	 * This method returns a localized message for the toggled Check-in message.
+	 *
+	 * @param  int $DTT_ID include specific datetime to get the correct Check-in message.  If not included or null,
+	 *                     then it is assumed Check-in for primary datetime was toggled.
+	 * @param bool $error  This just flags that you want an error message returned. This is put in so that the error
+	 *                     message can be customized with the attendee name.
+	 * @return string internationalized message
+	 * @throws EE_Error
+	 */
+	public function get_checkin_msg($DTT_ID, $error = false)
+	{
+		// let's get the attendee first so we can include the name of the attendee
+		$attendee = $this->get_first_related('Attendee');
+		if ($attendee instanceof EE_Attendee) {
+			if ($error) {
+				return sprintf(esc_html__("%s's check-in status was not changed.", "event_espresso"), $attendee->full_name());
+			}
+			$cur_status = $this->check_in_status_for_datetime($DTT_ID);
+			// what is the status message going to be?
+			switch ($cur_status) {
+				case EE_Checkin::status_checked_never:
+					return sprintf(
+						esc_html__("%s has been removed from Check-in records", "event_espresso"),
+						$attendee->full_name()
+					);
+					break;
+				case EE_Checkin::status_checked_in:
+					return sprintf(esc_html__('%s has been checked in', 'event_espresso'), $attendee->full_name());
+					break;
+				case EE_Checkin::status_checked_out:
+					return sprintf(esc_html__('%s has been checked out', 'event_espresso'), $attendee->full_name());
+					break;
+			}
+		}
+		return esc_html__("The check-in status could not be determined.", "event_espresso");
+	}
+
+
+	/**
+	 * Returns the related EE_Transaction to this registration
+	 *
+	 * @return EE_Transaction
+	 * @throws EE_Error
+	 * @throws EntityNotFoundException
+	 */
+	public function transaction()
+	{
+		$transaction = $this->get_first_related('Transaction');
+		if (! $transaction instanceof \EE_Transaction) {
+			throw new EntityNotFoundException('Transaction ID', $this->transaction_ID());
+		}
+		return $transaction;
+	}
+
+
+	/**
+	 *        get Registration Code
+	 */
+	public function reg_code()
+	{
+		return $this->get('REG_code');
+	}
+
+
+	/**
+	 *        get Transaction ID
+	 */
+	public function transaction_ID()
+	{
+		return $this->get('TXN_ID');
+	}
+
+
+	/**
+	 * @return int
+	 * @throws EE_Error
+	 */
+	public function ticket_ID()
+	{
+		return $this->get('TKT_ID');
+	}
+
+
+	/**
+	 *        Set Registration Code
+	 *
+	 * @access    public
+	 * @param    string  $REG_code Registration Code
+	 * @param    boolean $use_default
+	 * @throws EE_Error
+	 */
+	public function set_reg_code($REG_code, $use_default = false)
+	{
+		if (empty($REG_code)) {
+			EE_Error::add_error(
+				esc_html__('REG_code can not be empty.', 'event_espresso'),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return;
+		}
+		if (! $this->reg_code()) {
+			parent::set('REG_code', $REG_code, $use_default);
+		} else {
+			EE_Error::doing_it_wrong(
+				__CLASS__ . '::' . __FUNCTION__,
+				esc_html__('Can not change a registration REG_code once it has been set.', 'event_espresso'),
+				'4.6.0'
+			);
+		}
+	}
+
+
+	/**
+	 * Returns all other registrations in the same group as this registrant who have the same ticket option.
+	 * Note, if you want to just get all registrations in the same transaction (group), use:
+	 *    $registration->transaction()->registrations();
+	 *
+	 * @since 4.5.0
+	 * @return EE_Registration[] or empty array if this isn't a group registration.
+	 * @throws EE_Error
+	 */
+	public function get_all_other_registrations_in_group()
+	{
+		if ($this->group_size() < 2) {
+			return array();
+		}
+
+		$query[0] = array(
+			'TXN_ID' => $this->transaction_ID(),
+			'REG_ID' => array('!=', $this->ID()),
+			'TKT_ID' => $this->ticket_ID(),
+		);
+		/** @var EE_Registration[] $registrations */
+		$registrations = $this->get_model()->get_all($query);
+		return $registrations;
+	}
+
+	/**
+	 * Return the link to the admin details for the object.
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function get_admin_details_link()
+	{
+		EE_Registry::instance()->load_helper('URL');
+		return EEH_URL::add_query_args_and_nonce(
+			array(
+				'page'    => 'espresso_registrations',
+				'action'  => 'view_registration',
+				'_REG_ID' => $this->ID(),
+			),
+			admin_url('admin.php')
+		);
+	}
+
+	/**
+	 * Returns the link to the editor for the object.  Sometimes this is the same as the details.
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function get_admin_edit_link()
+	{
+		return $this->get_admin_details_link();
+	}
+
+	/**
+	 * Returns the link to a settings page for the object.
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function get_admin_settings_link()
+	{
+		return $this->get_admin_details_link();
+	}
+
+	/**
+	 * Returns the link to the "overview" for the object (typically the "list table" view).
+	 *
+	 * @return string
+	 */
+	public function get_admin_overview_link()
+	{
+		EE_Registry::instance()->load_helper('URL');
+		return EEH_URL::add_query_args_and_nonce(
+			array(
+				'page' => 'espresso_registrations',
+			),
+			admin_url('admin.php')
+		);
+	}
+
+
+	/**
+	 * @param array $query_params
+	 *
+	 * @return \EE_Registration[]
+	 * @throws EE_Error
+	 */
+	public function payments($query_params = array())
+	{
+		return $this->get_many_related('Payment', $query_params);
+	}
+
+
+	/**
+	 * @param array $query_params
+	 *
+	 * @return \EE_Registration_Payment[]
+	 * @throws EE_Error
+	 */
+	public function registration_payments($query_params = array())
+	{
+		return $this->get_many_related('Registration_Payment', $query_params);
+	}
+
+
+	/**
+	 * This grabs the payment method corresponding to the last payment made for the amount owing on the registration.
+	 * Note: if there are no payments on the registration there will be no payment method returned.
+	 *
+	 * @return EE_Payment_Method|null
+	 */
+	public function payment_method()
+	{
+		return EEM_Payment_Method::instance()->get_last_used_for_registration($this);
+	}
+
+
+	/**
+	 * @return \EE_Line_Item
+	 * @throws EntityNotFoundException
+	 * @throws EE_Error
+	 */
+	public function ticket_line_item()
+	{
+		$ticket = $this->ticket();
+		$transaction = $this->transaction();
+		$line_item = null;
+		$ticket_line_items = \EEH_Line_Item::get_line_items_by_object_type_and_IDs(
+			$transaction->total_line_item(),
+			'Ticket',
+			array($ticket->ID())
+		);
+		foreach ($ticket_line_items as $ticket_line_item) {
+			if (
+				$ticket_line_item instanceof \EE_Line_Item
+				&& $ticket_line_item->OBJ_type() === 'Ticket'
+				&& $ticket_line_item->OBJ_ID() === $ticket->ID()
+			) {
+				$line_item = $ticket_line_item;
+				break;
+			}
+		}
+		if (! ($line_item instanceof \EE_Line_Item && $line_item->OBJ_type() === 'Ticket')) {
+			throw new EntityNotFoundException('Line Item Ticket ID', $ticket->ID());
+		}
+		return $line_item;
+	}
+
+
+	/**
+	 * Soft Deletes this model object.
+	 *
+	 * @return boolean | int
+	 * @throws RuntimeException
+	 * @throws EE_Error
+	 */
+	public function delete()
+	{
+		if ($this->update_extra_meta(EE_Registration::PRE_TRASH_REG_STATUS_KEY, $this->status_ID()) === true) {
+			$this->set_status(EEM_Registration::status_id_cancelled);
+		}
+		return parent::delete();
+	}
+
+
+	/**
+	 * Restores whatever the previous status was on a registration before it was trashed (if possible)
+	 *
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function restore()
+	{
+		$previous_status = $this->get_extra_meta(
+			EE_Registration::PRE_TRASH_REG_STATUS_KEY,
+			true,
+			EEM_Registration::status_id_cancelled
+		);
+		if ($previous_status) {
+			$this->delete_extra_meta(EE_Registration::PRE_TRASH_REG_STATUS_KEY);
+			$this->set_status($previous_status);
+		}
+		return parent::restore();
+	}
+
+
+	/**
+	 * possibly toggle Registration status based on comparison of REG_paid vs REG_final_price
+	 *
+	 * @param  boolean $trigger_set_status_logic EE_Registration::set_status() can trigger additional logic
+	 *                                           depending on whether the reg status changes to or from "Approved"
+	 * @return boolean whether the Registration status was updated
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function updateStatusBasedOnTotalPaid($trigger_set_status_logic = true)
+	{
+		$paid = $this->paid();
+		$price = $this->final_price();
+		switch (true) {
+			// overpaid or paid
+			case EEH_Money::compare_floats($paid, $price, '>'):
+			case EEH_Money::compare_floats($paid, $price):
+				$new_status = EEM_Registration::status_id_approved;
+				break;
+			//  underpaid
+			case EEH_Money::compare_floats($paid, $price, '<'):
+				$new_status = EEM_Registration::status_id_pending_payment;
+				break;
+			// uhhh Houston...
+			default:
+				throw new RuntimeException(
+					esc_html__('The total paid calculation for this registration is inaccurate.', 'event_espresso')
+				);
+		}
+		if ($new_status !== $this->status_ID()) {
+			if ($trigger_set_status_logic) {
+				return $this->set_status($new_status);
+			}
+			parent::set('STS_ID', $new_status);
+			return true;
+		}
+		return false;
+	}
+
+
+	/*************************** DEPRECATED ***************************/
+
+
+	/**
+	 * @deprecated
+	 * @since     4.7.0
+	 * @access    public
+	 */
+	public function price_paid()
+	{
+		EE_Error::doing_it_wrong(
+			'EE_Registration::price_paid()',
+			esc_html__(
+				'This method is deprecated, please use EE_Registration::final_price() instead.',
+				'event_espresso'
+			),
+			'4.7.0'
+		);
+		return $this->final_price();
+	}
+
+
+	/**
+	 * @deprecated
+	 * @since     4.7.0
+	 * @access    public
+	 * @param    float $REG_final_price
+	 * @throws EE_Error
+	 * @throws RuntimeException
+	 */
+	public function set_price_paid($REG_final_price = 0.00)
+	{
+		EE_Error::doing_it_wrong(
+			'EE_Registration::set_price_paid()',
+			esc_html__(
+				'This method is deprecated, please use EE_Registration::set_final_price() instead.',
+				'event_espresso'
+			),
+			'4.7.0'
+		);
+		$this->set_final_price($REG_final_price);
+	}
+
+
+	/**
+	 * @deprecated
+	 * @since 4.7.0
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function pretty_price_paid()
+	{
+		EE_Error::doing_it_wrong(
+			'EE_Registration::pretty_price_paid()',
+			esc_html__(
+				'This method is deprecated, please use EE_Registration::pretty_final_price() instead.',
+				'event_espresso'
+			),
+			'4.7.0'
+		);
+		return $this->pretty_final_price();
+	}
+
+
+	/**
+	 * Gets the primary datetime related to this registration via the related Event to this registration
+	 *
+	 * @deprecated 4.9.17
+	 * @return EE_Datetime
+	 * @throws EE_Error
+	 * @throws EntityNotFoundException
+	 */
+	public function get_related_primary_datetime()
+	{
+		EE_Error::doing_it_wrong(
+			__METHOD__,
+			esc_html__(
+				'Use EE_Registration::get_latest_related_datetime() or EE_Registration::get_earliest_related_datetime()',
+				'event_espresso'
+			),
+			'4.9.17',
+			'5.0.0'
+		);
+		return $this->event()->primary_datetime();
+	}
+
+	/**
+	 * Returns the contact's name (or "Unknown" if there is no contact.)
+	 * @since 4.10.12.p
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function name()
+	{
+		return $this->attendeeName();
+	}
 }

core/db_classes/EE_Base_Class.class.php

Spacing +119 added lines, -119 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();
             }
         }
         /**
@@ -251,10 +251,10 @@ 
     public function get_original($field_name)
     {
         if (
-            isset($this->_props_n_values_provided_in_constructor[ $field_name ])
+            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;
     }
@@ -291,7 +291,7 @@ 
         // then don't do anything
         if (
             ! $use_default
-            && $this->_fields[ $field_name ] === $field_value
+            && $this->_fields[$field_name] === $field_value
             && $this->ID()
         ) {
             return;
@@ -309,7 +309,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
@@ -320,15 +320,15 @@ 
                  */
                 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
@@ -391,8 +391,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;
     }
 
@@ -479,8 +479,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));
                 }
             }
         }
@@ -538,7 +538,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);
     }
 
 
@@ -564,11 +564,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'),
@@ -582,38 +582,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;
@@ -639,7 +639,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;
     }
 
 
@@ -668,9 +668,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);
@@ -698,12 +698,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;
     }
 
@@ -761,8 +761,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]);
         }
     }
 
@@ -814,7 +814,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'),
@@ -825,10 +825,10 @@ 
         }
         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
@@ -836,12 +836,12 @@ 
             ) {
                 $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 ])
+                    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
@@ -875,9 +875,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;
@@ -908,7 +908,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
@@ -916,18 +916,18 @@ 
             // 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 ])
+                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;
             }
         }
@@ -944,8 +944,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);
@@ -968,7 +968,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
@@ -1152,7 +1152,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);
         }
     }
@@ -1192,9 +1192,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];
     }
 
 
@@ -1216,7 +1216,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__(
@@ -1231,8 +1231,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;
     }
 
@@ -1474,7 +1474,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(
@@ -1586,21 +1586,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;
         }
@@ -1643,7 +1643,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__(
@@ -1655,7 +1655,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;
     }
@@ -1770,8 +1770,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
@@ -1828,7 +1828,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;
         }
         /**
@@ -1838,7 +1838,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
@@ -1853,10 +1853,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
@@ -1866,7 +1866,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();
@@ -1883,8 +1883,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 />'
                             )
                         );
@@ -1986,27 +1986,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()){
@@ -2033,7 +2033,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 {
@@ -2059,9 +2059,9 @@ 
         $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;
@@ -2096,10 +2096,10 @@ 
             $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)) {
@@ -2111,7 +2111,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 {
@@ -2144,7 +2144,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__(
@@ -2193,7 +2193,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;
     }
@@ -2212,7 +2212,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'),
@@ -2242,7 +2242,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);
     }
@@ -2295,7 +2295,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__(
@@ -2460,7 +2460,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,
@@ -2571,7 +2571,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,
@@ -2595,7 +2595,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);
             }
         }
@@ -2677,7 +2677,7 @@ 
      */
     public function is_set($field_name)
     {
-        return isset($this->_fields[ $field_name ]);
+        return isset($this->_fields[$field_name]);
     }
 
 
@@ -2693,7 +2693,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__(
@@ -2725,7 +2725,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;
     }
@@ -2762,7 +2762,7 @@ 
     {
         $className = get_class($this);
         $tagName = "FHEE__{$className}__{$methodName}";
-        if (! has_filter($tagName)) {
+        if ( ! has_filter($tagName)) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -2807,7 +2807,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) {
@@ -2925,7 +2925,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;
@@ -2970,17 +2970,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();
                 }
             }
         }
@@ -3061,8 +3061,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()'
                     )
                 );
             }
@@ -3095,7 +3095,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;
@@ -3325,7 +3325,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()
@@ -3366,7 +3366,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;
             }
         }
     }

Indentation +3347 added lines, -3347 removed lines

@@ -13,3363 +13,3363 @@
 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 (
+	/**
+	 * 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); // sanitized
-    }
-
-
-    /**
-     * 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)
-     * @return false|int|string         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 InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @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->_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); // sanitized
+	}
+
+
+	/**
+	 * 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)
+	 * @return false|int|string         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 InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @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;
+			}
+		}
+	}
 }

core/EE_Data_Mapper.core.php

Indentation +95 added lines, -95 removed lines

@@ -16,99 +16,99 @@
 {
 
 
-    /**
-     * instance of the EE_Data_Mapper Object
-     *
-     * @private _instance
-     */
-    private static $_instance = null;
-
-
-    public $data = array();
-
-
-    /**
-     *private constructor to prevent direct creation
-     *
-     * @Constructor
-     * @access private
-     * @return void
-     */
-    private function __construct()
-    {
-    }
-
-
-    /**
-     *@ singleton method used to instantiate class object
-     *@ access public
-     *@ return class instance
-     */
-    public function &instance()
-    {
-        // check if class object is instantiated
-        if (
-            self::$_instance === null
-            || ! is_object(self::$_instance)
-            || ! self::$_instance instanceof EE_Data_Mapper
-        ) {
-            self::$_instance = new self();
-        }
-        return self::$_instance;
-    }
-
-
-    /**
-     *        @ override magic methods
-     *        @ return void
-     */
-    final public function __destruct()
-    {
-    }
-
-    final public function __call($a, $b)
-    {
-    }
-
-    public static function __callStatic($a, $b)
-    {
-    }
-
-    final public function __get($a)
-    {
-    }
-
-    final public function __set($a, $b)
-    {
-    }
-
-    final public function __isset($a)
-    {
-    }
-
-    final public function __unset($a)
-    {
-    }
-
-    final public function __sleep()
-    {
-        return array();
-    }
-
-    final public function __wakeup()
-    {
-    }
-
-    final public function __toString()
-    {
-        return '';
-    }
-
-    final public function __invoke()
-    {
-    }
-
-    final public function __clone()
-    {
-    }
+	/**
+	 * instance of the EE_Data_Mapper Object
+	 *
+	 * @private _instance
+	 */
+	private static $_instance = null;
+
+
+	public $data = array();
+
+
+	/**
+	 *private constructor to prevent direct creation
+	 *
+	 * @Constructor
+	 * @access private
+	 * @return void
+	 */
+	private function __construct()
+	{
+	}
+
+
+	/**
+	 *@ singleton method used to instantiate class object
+	 *@ access public
+	 *@ return class instance
+	 */
+	public function &instance()
+	{
+		// check if class object is instantiated
+		if (
+			self::$_instance === null
+			|| ! is_object(self::$_instance)
+			|| ! self::$_instance instanceof EE_Data_Mapper
+		) {
+			self::$_instance = new self();
+		}
+		return self::$_instance;
+	}
+
+
+	/**
+	 *        @ override magic methods
+	 *        @ return void
+	 */
+	final public function __destruct()
+	{
+	}
+
+	final public function __call($a, $b)
+	{
+	}
+
+	public static function __callStatic($a, $b)
+	{
+	}
+
+	final public function __get($a)
+	{
+	}
+
+	final public function __set($a, $b)
+	{
+	}
+
+	final public function __isset($a)
+	{
+	}
+
+	final public function __unset($a)
+	{
+	}
+
+	final public function __sleep()
+	{
+		return array();
+	}
+
+	final public function __wakeup()
+	{
+	}
+
+	final public function __toString()
+	{
+		return '';
+	}
+
+	final public function __invoke()
+	{
+	}
+
+	final public function __clone()
+	{
+	}
 }

core/data_migration_scripts/EE_Data_Migration_Script_Base.core.php

Spacing +25 added lines, -25 removed lines

@@ -135,7 +135,7 @@ 
     public function __construct(TableManager $table_manager = null, TableAnalysis $table_analysis = null)
     {
         $this->_migration_stages = (array) apply_filters(
-            'FHEE__' . get_class($this) . '__construct__migration_stages',
+            'FHEE__'.get_class($this).'__construct__migration_stages',
             $this->_migration_stages
         );
         foreach ($this->_migration_stages as $migration_stage) {
@@ -170,10 +170,10 @@ 
     public function set_mapping($old_table, $old_pk, $new_table, $new_pk)
     {
         // make sure it has the needed keys
-        if (! isset($this->_mappings[ $old_table ]) || ! isset($this->_mappings[ $old_table ][ $new_table ])) {
-            $this->_mappings[ $old_table ][ $new_table ] = $this->_get_mapping_option($old_table, $new_table);
+        if ( ! isset($this->_mappings[$old_table]) || ! isset($this->_mappings[$old_table][$new_table])) {
+            $this->_mappings[$old_table][$new_table] = $this->_get_mapping_option($old_table, $new_table);
         }
-        $this->_mappings[ $old_table ][ $new_table ][ $old_pk ] = $new_pk;
+        $this->_mappings[$old_table][$new_table][$old_pk] = $new_pk;
     }
 
 
@@ -189,14 +189,14 @@ 
     public function get_mapping_new_pk($old_table, $old_pk, $new_table)
     {
         if (
-            ! isset($this->_mappings[ $old_table ]) ||
-            ! isset($this->_mappings[ $old_table ][ $new_table ])
+            ! isset($this->_mappings[$old_table]) ||
+            ! isset($this->_mappings[$old_table][$new_table])
         ) {
             // try fetching the option
-            $this->_mappings[ $old_table ][ $new_table ] = $this->_get_mapping_option($old_table, $new_table);
+            $this->_mappings[$old_table][$new_table] = $this->_get_mapping_option($old_table, $new_table);
         }
-        return isset($this->_mappings[ $old_table ][ $new_table ][ $old_pk ])
-            ? $this->_mappings[ $old_table ][ $new_table ][ $old_pk ] : null;
+        return isset($this->_mappings[$old_table][$new_table][$old_pk])
+            ? $this->_mappings[$old_table][$new_table][$old_pk] : null;
     }
 
 
@@ -212,16 +212,16 @@ 
     public function get_mapping_old_pk($old_table, $new_table, $new_pk)
     {
         if (
-            ! isset($this->_mappings[ $old_table ]) ||
-            ! isset($this->_mappings[ $old_table ][ $new_table ])
+            ! isset($this->_mappings[$old_table]) ||
+            ! isset($this->_mappings[$old_table][$new_table])
         ) {
             // try fetching the option
-            $this->_mappings[ $old_table ][ $new_table ] = $this->_get_mapping_option($old_table, $new_table);
+            $this->_mappings[$old_table][$new_table] = $this->_get_mapping_option($old_table, $new_table);
         }
-        if (isset($this->_mappings[ $old_table ][ $new_table ])) {
-            $new_pk_to_old_pk = array_flip($this->_mappings[ $old_table ][ $new_table ]);
-            if (isset($new_pk_to_old_pk[ $new_pk ])) {
-                return $new_pk_to_old_pk[ $new_pk ];
+        if (isset($this->_mappings[$old_table][$new_table])) {
+            $new_pk_to_old_pk = array_flip($this->_mappings[$old_table][$new_table]);
+            if (isset($new_pk_to_old_pk[$new_pk])) {
+                return $new_pk_to_old_pk[$new_pk];
             }
         }
         return null;
@@ -271,7 +271,7 @@ 
         $new_table_name_sans_wp = str_replace($wpdb->prefix, "", $new_table_name);
         $migrates_to = EE_Data_Migration_Manager::instance()->script_migrates_to_version(get_class($this));
         return substr(
-            EE_Data_Migration_Manager::data_migration_script_mapping_option_prefix . $migrates_to ['slug'] . '_' . $migrates_to['version'] . '_' . $old_table_name_sans_wp . '_' . $new_table_name_sans_wp,
+            EE_Data_Migration_Manager::data_migration_script_mapping_option_prefix.$migrates_to ['slug'].'_'.$migrates_to['version'].'_'.$old_table_name_sans_wp.'_'.$new_table_name_sans_wp,
             0,
             64
         );
@@ -343,12 +343,12 @@ 
                         $num_records_to_migrate_limit - $num_records_actually_migrated
                     );
                     $num_records_actually_migrated += $records_migrated_during_stage;
-                    $records_migrated_per_stage[ $stage->pretty_name() ] = $records_migrated_during_stage;
+                    $records_migrated_per_stage[$stage->pretty_name()] = $records_migrated_during_stage;
                 } catch (Exception $e) {
                     // yes if we catch an exception here, we consider that migration stage borked.
                     $stage->set_status(EE_Data_Migration_Manager::status_fatal_error);
                     $this->set_status(EE_Data_Migration_Manager::status_fatal_error);
-                    $stage->add_error($e->getMessage() . ". Stack-trace:" . $e->getTraceAsString());
+                    $stage->add_error($e->getMessage().". Stack-trace:".$e->getTraceAsString());
                     throw $e;
                 }
                 // check that the migration stage didn't mark itself as having a fatal error
@@ -421,8 +421,8 @@ 
     private function _maybe_do_schema_changes($before = true)
     {
         // so this property will be either _schema_changes_after_migration_ran or _schema_changes_before_migration_ran
-        $property_name = '_schema_changes_' . ($before ? 'before' : 'after') . '_migration_ran';
-        if (! $this->{$property_name}) {
+        $property_name = '_schema_changes_'.($before ? 'before' : 'after').'_migration_ran';
+        if ( ! $this->{$property_name}) {
             try {
                 ob_start();
                 if ($before) {
@@ -659,7 +659,7 @@ 
         try {
             EEH_Activation::create_table($table_name, $table_definition_sql, $engine_string, $drop_pre_existing_tables);
         } catch (EE_Error $e) {
-            $message = $e->getMessage() . '<br>Stack Trace:' . $e->getTraceAsString();
+            $message = $e->getMessage().'<br>Stack Trace:'.$e->getTraceAsString();
             $this->add_error($message);
             $this->_feedback_message .= $message;
         }
@@ -705,7 +705,7 @@ 
     public function get_errors()
     {
         $all_errors = $this->_errors;
-        if (! is_array($all_errors)) {
+        if ( ! is_array($all_errors)) {
             $all_errors = array();
         }
         foreach ($this->stages() as $stage) {
@@ -739,7 +739,7 @@ 
      */
     protected function stages()
     {
-        $stages = apply_filters('FHEE__' . get_class($this) . '__stages', $this->_migration_stages);
+        $stages = apply_filters('FHEE__'.get_class($this).'__stages', $this->_migration_stages);
         ksort($stages);
         return $stages;
     }
@@ -768,7 +768,7 @@ 
         $properties = parent::properties_as_array();
         $properties['_migration_stages'] = array();
         foreach ($this->_migration_stages as $migration_stage_priority => $migration_stage_class) {
-            $properties['_migration_stages'][ $migration_stage_priority ] = $migration_stage_class->properties_as_array(
+            $properties['_migration_stages'][$migration_stage_priority] = $migration_stage_class->properties_as_array(
             );
         }
         unset($properties['_mappings']);

Indentation +890 added lines, -890 removed lines

@@ -15,894 +15,894 @@
 abstract class EE_Data_Migration_Script_Base extends EE_Data_Migration_Class_Base
 {
 
-    /**
-     * Set by client code to indicate this DMS is being ran as part of a proper migration,
-     * instead of being used to merely setup (or verify) the database structure.
-     * Defaults to TRUE, so client code that's NOT using this DMS as part of a proper migration
-     * should call EE_Data_Migration_Script_Base::set_migrating( FALSE )
-     *
-     * @var boolean
-     */
-    protected $_migrating = true;
-
-    /**
-     * numerically-indexed array where each value is EE_Data_Migration_Script_Stage object
-     *
-     * @var EE_Data_Migration_Script_Stage[] $migration_functions
-     */
-    protected $_migration_stages = array();
-
-    /**
-     * Indicates we've already ran the schema changes that needed to happen BEFORE the data migration
-     *
-     * @var boolean
-     */
-    protected $_schema_changes_before_migration_ran = null;
-
-    /**
-     * Indicates we've already ran the schema changes that needed to happen AFTER the data migration
-     *
-     * @var boolean
-     */
-    protected $_schema_changes_after_migration_ran = null;
-
-    /**
-     * String which describes what's currently happening in this migration
-     *
-     * @var string
-     */
-    protected $_feedback_message;
-
-    /**
-     * Indicates the script's priority. Like wp's add_action and add_filter, lower numbers
-     * correspond to earlier execution
-     *
-     * @var int
-     */
-    protected $_priority = 5;
-
-    /**
-     * Multi-dimensional array that defines the mapping from OLD table Primary Keys
-     * to NEW table Primary Keys.
-     * Top-level array keys are OLD table names (minus the "wp_" part),
-     * 2nd-level array keys are NEW table names (again, minus the "wp_" part),
-     * 3rd-level array keys are the OLD table primary keys
-     * and 3rd-level array values are the NEW table primary keys
-     *
-     * @var array
-     */
-    protected $_mappings = array();
-
-    /**
-     * @var EE_Data_Migration_Script_Base
-     */
-    protected $previous_dms;
-
-
-    /**
-     * Returns whether or not this data migration script can operate on the given version of the database.
-     * Eg, if this migration script can migrate from 3.1.26 or higher (but not anything after 4.0.0), and
-     * it's passed a string like '3.1.38B', it should return true.
-     * If this DMS is to migrate data from an EE3 addon, you will probably want to use
-     * EventEspresso\core\services\database\TableAnalysis::tableExists() to check for old EE3 tables, and
-     * EE_Data_Migration_Manager::get_migration_ran() to check that core was already
-     * migrated from EE3 to EE4 (ie, this DMS probably relies on some migration data generated
-     * during the Core 4.1.0 DMS. If core didn't run that DMS, you probably don't want
-     * to run this DMS).
-     * If this DMS migrates data from a previous version of this EE4 addon, just
-     * comparing $current_database_state_of[ $this->slug() ] will probably suffice.
-     * If this DMS should never migrate data, because it's only used to define the initial
-     * database state, just return FALSE (and core's activation process will take care
-     * of calling its schema_changes_before_migration() and
-     * schema_changes_after_migration() for you. )
-     *
-     * @param array $current_database_state_of keys are EE plugin slugs (eg 'Core', 'Calendar', 'Mailchimp', etc)
-     * @return boolean
-     */
-    abstract public function can_migrate_from_version($current_database_state_of);
-
-
-    /**
-     * Performs database schema changes that need to occur BEFORE the data is migrated.
-     * Eg, if we were going to change user passwords from plaintext to encoded versions
-     * during this migration, this would probably add a new column called something like
-     * "encoded_password".
-     *
-     * @return boolean of success
-     */
-    abstract public function schema_changes_before_migration();
-
-
-    /**
-     * Performs the database schema changes that need to occur AFTER the data has been migrated.
-     * Usually this will mean we'll be removing old columns. Eg, if we were changing passwords
-     * from plaintext to encoded versions, and we had added a column called "encoded_password",
-     * this function would probably remove the old column "password" (which still holds the plaintext password)
-     * and possibly rename "encoded_password" to "password"
-     *
-     * @return boolean of success
-     */
-    abstract public function schema_changes_after_migration();
-
-
-    /**
-     * All children of this must call parent::__construct()
-     * at the end of their constructor or suffer the consequences!
-     *
-     * @param TableManager  $table_manager
-     * @param TableAnalysis $table_analysis
-     */
-    public function __construct(TableManager $table_manager = null, TableAnalysis $table_analysis = null)
-    {
-        $this->_migration_stages = (array) apply_filters(
-            'FHEE__' . get_class($this) . '__construct__migration_stages',
-            $this->_migration_stages
-        );
-        foreach ($this->_migration_stages as $migration_stage) {
-            if ($migration_stage instanceof EE_Data_Migration_Script_Stage) {
-                $migration_stage->_construct_finalize($this);
-            }
-        }
-        parent::__construct($table_manager, $table_analysis);
-    }
-
-
-    /**
-     * Place to add hooks and filters for tweaking the migrations page, in order
-     * to customize it
-     */
-    public function migration_page_hooks()
-    {
-        // by default none are added because we normally like the default look of the migration page
-    }
-
-
-    /**
-     * Sets the mapping from old table primary keys to new table primary keys.
-     * This mapping is automatically persisted as a property on the migration
-     *
-     * @param string     $old_table with wpdb prefix (wp_). Eg: wp_events_detail
-     * @param int|string $old_pk    old primary key. Eg events_detail.id's value
-     * @param string     $new_table with wpdb prefix (wp_). Eg: wp_posts
-     * @param int|string $new_pk    eg posts.ID
-     * @return void
-     */
-    public function set_mapping($old_table, $old_pk, $new_table, $new_pk)
-    {
-        // make sure it has the needed keys
-        if (! isset($this->_mappings[ $old_table ]) || ! isset($this->_mappings[ $old_table ][ $new_table ])) {
-            $this->_mappings[ $old_table ][ $new_table ] = $this->_get_mapping_option($old_table, $new_table);
-        }
-        $this->_mappings[ $old_table ][ $new_table ][ $old_pk ] = $new_pk;
-    }
-
-
-    /**
-     * Gets the new primary key, if provided with the OLD table and the primary key
-     * of an item in the old table, and the new table
-     *
-     * @param string     $old_table with wpdb prefix (wp_). Eg: wp_events_detail
-     * @param int|string $old_pk    old primary key. Eg events_detail.id's value
-     * @param string     $new_table with wpdb prefix (wp_). Eg: wp_posts
-     * @return mixed the primary key on the new table
-     */
-    public function get_mapping_new_pk($old_table, $old_pk, $new_table)
-    {
-        if (
-            ! isset($this->_mappings[ $old_table ]) ||
-            ! isset($this->_mappings[ $old_table ][ $new_table ])
-        ) {
-            // try fetching the option
-            $this->_mappings[ $old_table ][ $new_table ] = $this->_get_mapping_option($old_table, $new_table);
-        }
-        return isset($this->_mappings[ $old_table ][ $new_table ][ $old_pk ])
-            ? $this->_mappings[ $old_table ][ $new_table ][ $old_pk ] : null;
-    }
-
-
-    /**
-     * Gets the old primary key, if provided with the OLD table,
-     * and the new table and the primary key of an item in the new table
-     *
-     * @param string $old_table with wpdb prefix (wp_). Eg: wp_events_detail
-     * @param string $new_table with wpdb prefix (wp_). Eg: wp_posts
-     * @param mixed  $new_pk
-     * @return mixed
-     */
-    public function get_mapping_old_pk($old_table, $new_table, $new_pk)
-    {
-        if (
-            ! isset($this->_mappings[ $old_table ]) ||
-            ! isset($this->_mappings[ $old_table ][ $new_table ])
-        ) {
-            // try fetching the option
-            $this->_mappings[ $old_table ][ $new_table ] = $this->_get_mapping_option($old_table, $new_table);
-        }
-        if (isset($this->_mappings[ $old_table ][ $new_table ])) {
-            $new_pk_to_old_pk = array_flip($this->_mappings[ $old_table ][ $new_table ]);
-            if (isset($new_pk_to_old_pk[ $new_pk ])) {
-                return $new_pk_to_old_pk[ $new_pk ];
-            }
-        }
-        return null;
-    }
-
-
-    /**
-     * Gets the mapping array option specified by the table names
-     *
-     * @param string $old_table_name
-     * @param string $new_table_name
-     * @return array
-     */
-    protected function _get_mapping_option($old_table_name, $new_table_name)
-    {
-        $option = get_option($this->_get_mapping_option_name($old_table_name, $new_table_name), array());
-        return $option;
-    }
-
-
-    /**
-     * Updates the mapping option specified by the table names with the array provided
-     *
-     * @param string $old_table_name
-     * @param string $new_table_name
-     * @param array  $mapping_array
-     * @return boolean success of updating option
-     */
-    protected function _set_mapping_option($old_table_name, $new_table_name, $mapping_array)
-    {
-        $success = update_option($this->_get_mapping_option_name($old_table_name, $new_table_name), $mapping_array, false);
-        return $success;
-    }
-
-
-    /**
-     * Gets the option name for this script to map from $old_table_name to $new_table_name
-     *
-     * @param string $old_table_name
-     * @param string $new_table_name
-     * @return string
-     */
-    protected function _get_mapping_option_name($old_table_name, $new_table_name)
-    {
-        global $wpdb;
-        $old_table_name_sans_wp = str_replace($wpdb->prefix, "", $old_table_name);
-        $new_table_name_sans_wp = str_replace($wpdb->prefix, "", $new_table_name);
-        $migrates_to = EE_Data_Migration_Manager::instance()->script_migrates_to_version(get_class($this));
-        return substr(
-            EE_Data_Migration_Manager::data_migration_script_mapping_option_prefix . $migrates_to ['slug'] . '_' . $migrates_to['version'] . '_' . $old_table_name_sans_wp . '_' . $new_table_name_sans_wp,
-            0,
-            64
-        );
-    }
-
-
-    /**
-     * Counts all the records that will be migrated during this data migration.
-     * For example, if we were changing old user passwords from plaintext to encoded versions,
-     * this would be a count of all users who have passwords. If we were going to also split
-     * attendee records into transactions, registrations, and attendee records, this would include
-     * the count of all attendees currently in existence in the DB (ie, users + attendees).
-     * If you can't determine how many records there are to migrate, just provide a guess: this
-     * number will only be used in calculating the percent complete. If you estimate there to be
-     * 100 records to migrate, and it turns out there's 120, we'll just show the migration as being at
-     * 99% until the function "migration_step" returns EE_Data_Migration_Script_Base::status_complete.
-     *
-     * @return int
-     */
-    protected function _count_records_to_migrate()
-    {
-        $count = 0;
-        foreach ($this->stages() as $stage) {
-            $count += $stage->count_records_to_migrate();
-        }
-        return $count;
-    }
-
-
-    /**
-     * Returns the number of records updated so far. Usually this is easiest to do
-     * by just setting a transient and updating it after each migration_step
-     *
-     * @return int
-     */
-    public function count_records_migrated()
-    {
-        $count = 0;
-        foreach ($this->stages() as $stage) {
-            $count += $stage->count_records_migrated();
-        }
-        $this->_records_migrated = $count;
-        return $count;
-    }
-
-
-    /**
-     * @param int $num_records_to_migrate_limit
-     * @return int
-     * @throws EE_Error
-     * @throws Exception
-     */
-    public function migration_step($num_records_to_migrate_limit)
-    {
-        // reset the feedback message
-        $this->_feedback_message = '';
-        // if we haven't yet done the 1st schema changes, do them now. buffer any output
-        $this->_maybe_do_schema_changes(true);
-
-        $num_records_actually_migrated = 0;
-        $records_migrated_per_stage = array();
-        // setup the 'stage' variable, which should hold the last run stage of the migration  (or none at all if nothing runs)
-        $stage = null;
-        // get the next stage that isn't complete
-        foreach ($this->stages() as $stage) {
-            if ($stage->get_status() == EE_Data_Migration_Manager::status_continue) {
-                try {
-                    $records_migrated_during_stage = $stage->migration_step(
-                        $num_records_to_migrate_limit - $num_records_actually_migrated
-                    );
-                    $num_records_actually_migrated += $records_migrated_during_stage;
-                    $records_migrated_per_stage[ $stage->pretty_name() ] = $records_migrated_during_stage;
-                } catch (Exception $e) {
-                    // yes if we catch an exception here, we consider that migration stage borked.
-                    $stage->set_status(EE_Data_Migration_Manager::status_fatal_error);
-                    $this->set_status(EE_Data_Migration_Manager::status_fatal_error);
-                    $stage->add_error($e->getMessage() . ". Stack-trace:" . $e->getTraceAsString());
-                    throw $e;
-                }
-                // check that the migration stage didn't mark itself as having a fatal error
-                if ($stage->is_broken()) {
-                    $this->set_broken();
-                    throw new EE_Error($stage->get_last_error());
-                }
-            }
-            // once we've migrated all the number we intended to (possibly from different stages), stop migrating
-            // or if we had a fatal error
-            // or if the current script stopped early- its not done, but it's done all it thinks we should do on this step
-            if (
-                $num_records_actually_migrated >= $num_records_to_migrate_limit
-                || $stage->is_broken()
-                || $stage->has_more_to_do()
-            ) {
-                break;
-            }
-        }
-        // check if we're all done this data migration...
-        // which is indicated by being done early AND the last stage claims to be done
-        if ($stage == null) {
-            // this migration script apparently has NO stages... which is super weird, but whatever
-            $this->set_completed();
-            $this->_maybe_do_schema_changes(false);
-        } elseif ($num_records_actually_migrated < $num_records_to_migrate_limit && ! $stage->has_more_to_do()) {
-            // apparently we're done, because we couldn't migrate the number we intended to
-            $this->set_completed();
-            $this->_update_feedback_message(array_reverse($records_migrated_per_stage));
-            // do schema changes for after the migration now
-            // first double-check we haven't already done this
-            $this->_maybe_do_schema_changes(false);
-        } else {
-            // update feedback message, keeping in mind that we show them with the most recent at the top
-            $this->_update_feedback_message(array_reverse($records_migrated_per_stage));
-        }
-        return $num_records_actually_migrated;
-    }
-
-
-    /**
-     * Updates the feedback message according to what was done during this migration stage.
-     *
-     * @param array $records_migrated_per_stage KEYS are pretty names for each stage; values are the count of records
-     *                                          migrated from that stage
-     * @return void
-     */
-    private function _update_feedback_message($records_migrated_per_stage)
-    {
-        $feedback_message_array = array();
-        foreach ($records_migrated_per_stage as $migration_stage_name => $num_records_migrated) {
-            $feedback_message_array[] = sprintf(
-                esc_html__("Migrated %d records successfully during %s", "event_espresso"),
-                $num_records_migrated,
-                $migration_stage_name
-            );
-        }
-        $this->_feedback_message .= implode("<br>", $feedback_message_array);
-    }
-
-
-    /**
-     * Calls either schema_changes_before_migration() (if $before==true) or schema_changes_after_migration
-     * (if $before==false). Buffers their outputs and stores them on the class.
-     *
-     * @param boolean $before
-     * @throws Exception
-     * @return void
-     */
-    private function _maybe_do_schema_changes($before = true)
-    {
-        // so this property will be either _schema_changes_after_migration_ran or _schema_changes_before_migration_ran
-        $property_name = '_schema_changes_' . ($before ? 'before' : 'after') . '_migration_ran';
-        if (! $this->{$property_name}) {
-            try {
-                ob_start();
-                if ($before) {
-                    $this->schema_changes_before_migration();
-                } else {
-                    $this->schema_changes_after_migration();
-                }
-                $output = ob_get_contents();
-                ob_end_clean();
-            } catch (Exception $e) {
-                $this->set_status(EE_Data_Migration_Manager::status_fatal_error);
-                throw $e;
-            }
-            // record that we've done these schema changes
-            $this->{$property_name} = true;
-            // if there were any warnings etc, record them as non-fatal errors
-            if ($output) {
-                // there were some warnings
-                $this->_errors[] = $output;
-            }
-        }
-    }
-
-
-    /**
-     * Wrapper for EEH_Activation::create_table. However, takes into account the request type when
-     * deciding what to pass for its 4th arg, $drop_pre_existing_tables. Using this function, instead
-     * of _table_should_exist_previously, indicates that this table should be new to the EE version being migrated to
-     * or
-     * activated currently. If this is a brand new activation or a migration, and we're indicating this table should
-     * not
-     * previously exist, then we want to set $drop_pre_existing_tables to TRUE (ie, we shouldn't discover that this
-     * table exists in the DB in EEH_Activation::create_table- if it DOES exist, something's wrong and the old table
-     * should be nuked.
-     *
-     * Just for a bit of context, the migration script's db_schema_changes_* methods
-     * are called basically in 3 cases: on brand new activation of EE4 (ie no previous version of EE existed and the
-     * plugin is being activated and we want to add all the brand new tables), upon reactivation of EE4 (it was
-     * deactivated and then reactivated, in which case we want to just verify the DB structure is ok) that table should
-     * be dropped), and during a migration when we're moving the DB to the state of the migration script
-     *
-     * @param string $table_name
-     * @param string $table_definition_sql
-     * @param string $engine_string
-     */
-    protected function _table_is_new_in_this_version(
-        $table_name,
-        $table_definition_sql,
-        $engine_string = 'ENGINE=InnoDB '
-    ) {
-        $this->_create_table_and_catch_errors(
-            $table_name,
-            $table_definition_sql,
-            $engine_string,
-            $this->_pre_existing_table_should_be_dropped(true)
-        );
-    }
-
-    /**
-     * Like _table_is_new_in_this_version and _table_should_exist_previously, this function verifies the given table
-     * exists. But we understand that this table has CHANGED in this version since the previous version. So it's not
-     * completely new, but it's different. So we need to treat it like a new table in terms of verifying it's schema is
-     * correct on activations, migrations, upgrades; but if it exists when it shouldn't, we need to be as lenient as
-     * _table_should_exist_previously.
-     * 8656]{Assumes only this plugin could have added this table (ie, if its a new activation of this plugin, the
-     * table shouldn't exist).
-     *
-     * @param string $table_name
-     * @param string $table_definition_sql
-     * @param string $engine_string
-     */
-    protected function _table_is_changed_in_this_version(
-        $table_name,
-        $table_definition_sql,
-        $engine_string = 'ENGINE=MyISAM'
-    ) {
-        $this->_create_table_and_catch_errors(
-            $table_name,
-            $table_definition_sql,
-            $engine_string,
-            $this->_pre_existing_table_should_be_dropped(false)
-        );
-    }
-
-
-    /**
-     * _old_table_exists
-     * returns TRUE if the requested table exists in the current database
-     *
-     * @param string $table_name
-     * @return boolean
-     */
-    protected function _old_table_exists($table_name)
-    {
-        return $this->_get_table_analysis()->tableExists($table_name);
-    }
-
-
-    /**
-     * _delete_table_if_empty
-     * returns TRUE if the requested table was empty and successfully empty
-     *
-     * @param string $table_name
-     * @return boolean
-     */
-    protected function _delete_table_if_empty($table_name)
-    {
-        return EEH_Activation::delete_db_table_if_empty($table_name);
-    }
-
-
-    /**
-     * It is preferred to use _table_has_not_changed_since_previous or _table_is_changed_in_this_version
-     * as these are significantly more efficient or explicit.
-     * Please see description of _table_is_new_in_this_version. This function will only set
-     * EEH_Activation::create_table's $drop_pre_existing_tables to TRUE if it's a brand
-     * new activation. ie, a more accurate name for this method would be "_table_added_previously_by_this_plugin"
-     * because the table will be cleared out if this is a new activation (ie, if its a new activation, it actually
-     * should exist previously). Otherwise, we'll always set $drop_pre_existing_tables to FALSE because the table
-     * should have existed. Note, if the table is being MODIFIED in this version being activated or migrated to, then
-     * you want _table_is_changed_in_this_version NOT this one. We don't check this table's structure during migrations
-     * because apparently it hasn't changed since the previous one, right?
-     *
-     * @param string $table_name
-     * @param string $table_definition_sql
-     * @param string $engine_string
-     */
-    protected function _table_should_exist_previously(
-        $table_name,
-        $table_definition_sql,
-        $engine_string = 'ENGINE=MyISAM'
-    ) {
-        $this->_create_table_and_catch_errors(
-            $table_name,
-            $table_definition_sql,
-            $engine_string,
-            $this->_pre_existing_table_should_be_dropped(false)
-        );
-    }
-
-    /**
-     * Exactly the same as _table_should_exist_previously(), except if this migration script is currently doing
-     * a migration, we skip checking this table's structure in the database and just assume it's correct.
-     * So this is useful only to improve efficiency when doing migrations (not a big deal for single site installs,
-     * but important for multisite where migrations can take a very long time otherwise).
-     * If the table is known to have changed since previous version, use _table_is_changed_in_this_version().
-     * Assumes only this plugin could have added this table (ie, if its a new activation of this plugin, the table
-     * shouldn't exist).
-     *
-     * @param string $table_name
-     * @param string $table_definition_sql
-     * @param string $engine_string
-     */
-    protected function _table_has_not_changed_since_previous(
-        $table_name,
-        $table_definition_sql,
-        $engine_string = 'ENGINE=MyISAM'
-    ) {
-        if ($this->_currently_migrating()) {
-            // if we're doing a migration, and this table apparently already exists, then we don't need do anything right?
-            return;
-        }
-        $this->_create_table_and_catch_errors(
-            $table_name,
-            $table_definition_sql,
-            $engine_string,
-            $this->_pre_existing_table_should_be_dropped(false)
-        );
-    }
-
-    /**
-     * Returns whether or not this migration script is being used as part of an actual migration
-     *
-     * @return boolean
-     */
-    protected function _currently_migrating()
-    {
-        // we want to know if we are currently performing a migration. We could just believe what was set on the _migrating property, but let's double-check (ie the script should apply and we should be in MM)
-        return $this->_migrating &&
-               $this->can_migrate_from_version(
-                   EE_Data_Migration_Manager::instance()->ensure_current_database_state_is_set()
-               ) &&
-               EE_Maintenance_Mode::instance()->real_level() == EE_Maintenance_Mode::level_2_complete_maintenance;
-    }
-
-    /**
-     * Determines if a table should be dropped, based on whether it's reported to be new in $table_is_new,
-     * and the plugin's request type.
-     * Assumes only this plugin could have added the table (ie, if its a new activation of this plugin, the table
-     * shouldn't exist no matter what).
-     *
-     * @param boolean $table_is_new
-     * @return boolean
-     */
-    protected function _pre_existing_table_should_be_dropped($table_is_new)
-    {
-        if ($table_is_new) {
-            if (
-                $this->_get_req_type_for_plugin_corresponding_to_this_dms() == EE_System::req_type_new_activation
-                || $this->_currently_migrating()
-            ) {
-                return true;
-            } else {
-                return false;
-            }
-        } else {
-            if (
-                in_array(
-                    $this->_get_req_type_for_plugin_corresponding_to_this_dms(),
-                    array(EE_System::req_type_new_activation)
-                )
-            ) {
-                return true;
-            } else {
-                return false;
-            }
-        }
-    }
-
-    /**
-     * Just wraps EEH_Activation::create_table, but catches any errors it may throw and adds them as errors on the DMS
-     *
-     * @param string  $table_name
-     * @param string  $table_definition_sql
-     * @param string  $engine_string
-     * @param boolean $drop_pre_existing_tables
-     */
-    private function _create_table_and_catch_errors(
-        $table_name,
-        $table_definition_sql,
-        $engine_string = 'ENGINE=MyISAM',
-        $drop_pre_existing_tables = false
-    ) {
-        try {
-            EEH_Activation::create_table($table_name, $table_definition_sql, $engine_string, $drop_pre_existing_tables);
-        } catch (EE_Error $e) {
-            $message = $e->getMessage() . '<br>Stack Trace:' . $e->getTraceAsString();
-            $this->add_error($message);
-            $this->_feedback_message .= $message;
-        }
-    }
-
-
-    /**
-     * Gets the request type for the plugin (core or addon) that corresponds to this DMS
-     *
-     * @return int one of EE_System::_req_type_* constants
-     * @throws EE_Error
-     */
-    private function _get_req_type_for_plugin_corresponding_to_this_dms()
-    {
-        if ($this->slug() == 'Core') {
-            return EE_System::instance()->detect_req_type();
-        } else {// it must be for an addon
-            $addon_name = $this->slug();
-            if (EE_Registry::instance()->get_addon_by_name($addon_name)) {
-                return EE_Registry::instance()->get_addon_by_name($addon_name)->detect_req_type();
-            } else {
-                throw new EE_Error(
-                    sprintf(
-                        esc_html__(
-                            "The DMS slug '%s' should correspond to the addon's name, which should also be '%s', but no such addon was registered. These are the registered addons' names: %s",
-                            "event_espresso"
-                        ),
-                        $this->slug(),
-                        $addon_name,
-                        implode(",", array_keys(EE_Registry::instance()->get_addons_by_name()))
-                    )
-                );
-            }
-        }
-    }
-
-
-    /**
-     * returns an array of strings describing errors by all the script's stages
-     *
-     * @return array
-     */
-    public function get_errors()
-    {
-        $all_errors = $this->_errors;
-        if (! is_array($all_errors)) {
-            $all_errors = array();
-        }
-        foreach ($this->stages() as $stage) {
-            $all_errors = array_merge($stage->get_errors(), $all_errors);
-        }
-        return $all_errors;
-    }
-
-
-    /**
-     * Indicates whether or not this migration script should continue
-     *
-     * @return boolean
-     */
-    public function can_continue()
-    {
-        return in_array(
-            $this->get_status(),
-            EE_Data_Migration_Manager::instance()->stati_that_indicate_to_continue_single_migration_script
-        );
-    }
-
-
-    /**
-     * Gets all the data migration stages associated with this script. Note:
-     * addons can filter this list to add their own stages, and because the list is
-     * numerically-indexed, they can insert their stage wherever they like and it will
-     * get ordered by the indexes
-     *
-     * @return EE_Data_Migration_Script_Stage[]
-     */
-    protected function stages()
-    {
-        $stages = apply_filters('FHEE__' . get_class($this) . '__stages', $this->_migration_stages);
-        ksort($stages);
-        return $stages;
-    }
-
-
-    /**
-     * Gets a string which should describe what's going on currently with this migration, which
-     * can be displayed to the user
-     *
-     * @return string
-     */
-    public function get_feedback_message()
-    {
-        return $this->_feedback_message;
-    }
-
-
-    /**
-     * A lot like "__sleep()" magic method in purpose, this is meant for persisting this class'
-     * properties to the DB. However, we don't want to use __sleep() because its quite
-     * possible that this class is defined when it goes to sleep, but NOT available when it
-     * awakes (eg, this class is part of an addon that is deactivated at some point).
-     */
-    public function properties_as_array()
-    {
-        $properties = parent::properties_as_array();
-        $properties['_migration_stages'] = array();
-        foreach ($this->_migration_stages as $migration_stage_priority => $migration_stage_class) {
-            $properties['_migration_stages'][ $migration_stage_priority ] = $migration_stage_class->properties_as_array(
-            );
-        }
-        unset($properties['_mappings']);
-        unset($properties['previous_dms']);
-
-        foreach ($this->_mappings as $old_table_name => $mapping_to_new_table) {
-            foreach ($mapping_to_new_table as $new_table_name => $mapping) {
-                $this->_set_mapping_option($old_table_name, $new_table_name, $mapping);
-            }
-        }
-        return $properties;
-    }
-
-
-    /**
-     * Sets all of the properties of this script stage to match what's in the array, which is assumed
-     * to have been made from the properties_as_array() function.
-     *
-     * @param array $array_of_properties like what's produced from properties_as_array() method
-     * @return void
-     */
-    public function instantiate_from_array_of_properties($array_of_properties)
-    {
-        $stages_properties_arrays = $array_of_properties['_migration_stages'];
-        unset($array_of_properties['_migration_stages']);
-        unset($array_of_properties['class']);
-        foreach ($array_of_properties as $property_name => $property_value) {
-            $this->{$property_name} = $property_value;
-        }
-        // _migration_stages are already instantiated, but have only default data
-        foreach ($this->_migration_stages as $stage) {
-            $stage_data = $this->_find_migration_stage_data_with_classname(
-                get_class($stage),
-                $stages_properties_arrays
-            );
-            // SO, if we found the stage data that was saved, use it. Otherwise, I guess the stage is new? (maybe added by
-            // an addon? Unlikely... not sure why it wouldn't exist, but if it doesn't just treat it like it was never started yet)
-            if ($stage_data) {
-                $stage->instantiate_from_array_of_properties($stage_data);
-            }
-        }
-    }
-
-
-    /**
-     * Gets the migration data from the array $migration_stage_data_arrays (which is an array of arrays, each of which
-     * is pretty well identical to EE_Data_Migration_Stage objects except all their properties are array indexes)
-     * for the given classname
-     *
-     * @param string $classname
-     * @param array  $migration_stage_data_arrays
-     * @return null
-     */
-    private function _find_migration_stage_data_with_classname($classname, $migration_stage_data_arrays)
-    {
-        foreach ($migration_stage_data_arrays as $migration_stage_data_array) {
-            if (isset($migration_stage_data_array['class']) && $migration_stage_data_array['class'] == $classname) {
-                return $migration_stage_data_array;
-            }
-        }
-        return null;
-    }
-
-
-    /**
-     * Returns the version that this script migrates to, based on the script's name.
-     * Cannot be overwritten because lots of code needs to know which version a script
-     * migrates to knowing only its name.
-     *
-     * @return array where the first key is the plugin's slug, the 2nd is the version of that plugin
-     * that will be updated to. Eg array('Core','4.1.0')
-     */
-    final public function migrates_to_version()
-    {
-        return EE_Data_Migration_Manager::instance()->script_migrates_to_version(get_class($this));
-    }
-
-
-    /**
-     * Gets this addon's slug as it would appear in the current_db_state wp option,
-     * and if this migration script is for an addon, it SHOULD match the addon's slug
-     * (and also the addon's classname, minus the 'EE_' prefix.). Eg, 'Calendar' for the EE_Calendar addon.
-     * Or 'Core' for core (non-addon).
-     *
-     * @return string
-     */
-    public function slug()
-    {
-        $migrates_to_version_info = $this->migrates_to_version();
-        // the slug is the first part of the array
-        return $migrates_to_version_info['slug'];
-    }
-
-
-    /**
-     * Returns the script's priority relative to DMSs from other addons. However, when
-     * two DMSs from the same addon/core apply, this is ignored (and instead the version that
-     * the script migrates to is used to determine which to run first). The default is 5, but all core DMSs
-     * normally have priority 10. (So if you want a DMS "A" to run before DMS "B", both of which are from addons,
-     * and both of which CAN run at the same time (ie, "B" doesn't depend on "A" to set
-     * the database up so it can run), then you can set "A" to priority 3 or something.
-     *
-     * @return int
-     */
-    public function priority()
-    {
-        return $this->_priority;
-    }
-
-
-    /**
-     * Sets whether or not this DMS is being ran as part of a migration, instead of
-     * just being used to setup (or verify) the current database structure matches
-     * what the latest DMS indicates it should be
-     *
-     * @param boolean $migrating
-     * @return void
-     */
-    public function set_migrating($migrating = true)
-    {
-        $this->_migrating = $migrating;
-    }
-
-    /**
-     * Marks that we think this migration class can continue to migrate
-     */
-    public function reattempt()
-    {
-        parent::reattempt();
-        // also, we want to reattempt any stages that were marked as borked
-        foreach ($this->stages() as $stage) {
-            if ($stage->is_broken()) {
-                $stage->reattempt();
-            }
-        }
-    }
+	/**
+	 * Set by client code to indicate this DMS is being ran as part of a proper migration,
+	 * instead of being used to merely setup (or verify) the database structure.
+	 * Defaults to TRUE, so client code that's NOT using this DMS as part of a proper migration
+	 * should call EE_Data_Migration_Script_Base::set_migrating( FALSE )
+	 *
+	 * @var boolean
+	 */
+	protected $_migrating = true;
+
+	/**
+	 * numerically-indexed array where each value is EE_Data_Migration_Script_Stage object
+	 *
+	 * @var EE_Data_Migration_Script_Stage[] $migration_functions
+	 */
+	protected $_migration_stages = array();
+
+	/**
+	 * Indicates we've already ran the schema changes that needed to happen BEFORE the data migration
+	 *
+	 * @var boolean
+	 */
+	protected $_schema_changes_before_migration_ran = null;
+
+	/**
+	 * Indicates we've already ran the schema changes that needed to happen AFTER the data migration
+	 *
+	 * @var boolean
+	 */
+	protected $_schema_changes_after_migration_ran = null;
+
+	/**
+	 * String which describes what's currently happening in this migration
+	 *
+	 * @var string
+	 */
+	protected $_feedback_message;
+
+	/**
+	 * Indicates the script's priority. Like wp's add_action and add_filter, lower numbers
+	 * correspond to earlier execution
+	 *
+	 * @var int
+	 */
+	protected $_priority = 5;
+
+	/**
+	 * Multi-dimensional array that defines the mapping from OLD table Primary Keys
+	 * to NEW table Primary Keys.
+	 * Top-level array keys are OLD table names (minus the "wp_" part),
+	 * 2nd-level array keys are NEW table names (again, minus the "wp_" part),
+	 * 3rd-level array keys are the OLD table primary keys
+	 * and 3rd-level array values are the NEW table primary keys
+	 *
+	 * @var array
+	 */
+	protected $_mappings = array();
+
+	/**
+	 * @var EE_Data_Migration_Script_Base
+	 */
+	protected $previous_dms;
+
+
+	/**
+	 * Returns whether or not this data migration script can operate on the given version of the database.
+	 * Eg, if this migration script can migrate from 3.1.26 or higher (but not anything after 4.0.0), and
+	 * it's passed a string like '3.1.38B', it should return true.
+	 * If this DMS is to migrate data from an EE3 addon, you will probably want to use
+	 * EventEspresso\core\services\database\TableAnalysis::tableExists() to check for old EE3 tables, and
+	 * EE_Data_Migration_Manager::get_migration_ran() to check that core was already
+	 * migrated from EE3 to EE4 (ie, this DMS probably relies on some migration data generated
+	 * during the Core 4.1.0 DMS. If core didn't run that DMS, you probably don't want
+	 * to run this DMS).
+	 * If this DMS migrates data from a previous version of this EE4 addon, just
+	 * comparing $current_database_state_of[ $this->slug() ] will probably suffice.
+	 * If this DMS should never migrate data, because it's only used to define the initial
+	 * database state, just return FALSE (and core's activation process will take care
+	 * of calling its schema_changes_before_migration() and
+	 * schema_changes_after_migration() for you. )
+	 *
+	 * @param array $current_database_state_of keys are EE plugin slugs (eg 'Core', 'Calendar', 'Mailchimp', etc)
+	 * @return boolean
+	 */
+	abstract public function can_migrate_from_version($current_database_state_of);
+
+
+	/**
+	 * Performs database schema changes that need to occur BEFORE the data is migrated.
+	 * Eg, if we were going to change user passwords from plaintext to encoded versions
+	 * during this migration, this would probably add a new column called something like
+	 * "encoded_password".
+	 *
+	 * @return boolean of success
+	 */
+	abstract public function schema_changes_before_migration();
+
+
+	/**
+	 * Performs the database schema changes that need to occur AFTER the data has been migrated.
+	 * Usually this will mean we'll be removing old columns. Eg, if we were changing passwords
+	 * from plaintext to encoded versions, and we had added a column called "encoded_password",
+	 * this function would probably remove the old column "password" (which still holds the plaintext password)
+	 * and possibly rename "encoded_password" to "password"
+	 *
+	 * @return boolean of success
+	 */
+	abstract public function schema_changes_after_migration();
+
+
+	/**
+	 * All children of this must call parent::__construct()
+	 * at the end of their constructor or suffer the consequences!
+	 *
+	 * @param TableManager  $table_manager
+	 * @param TableAnalysis $table_analysis
+	 */
+	public function __construct(TableManager $table_manager = null, TableAnalysis $table_analysis = null)
+	{
+		$this->_migration_stages = (array) apply_filters(
+			'FHEE__' . get_class($this) . '__construct__migration_stages',
+			$this->_migration_stages
+		);
+		foreach ($this->_migration_stages as $migration_stage) {
+			if ($migration_stage instanceof EE_Data_Migration_Script_Stage) {
+				$migration_stage->_construct_finalize($this);
+			}
+		}
+		parent::__construct($table_manager, $table_analysis);
+	}
+
+
+	/**
+	 * Place to add hooks and filters for tweaking the migrations page, in order
+	 * to customize it
+	 */
+	public function migration_page_hooks()
+	{
+		// by default none are added because we normally like the default look of the migration page
+	}
+
+
+	/**
+	 * Sets the mapping from old table primary keys to new table primary keys.
+	 * This mapping is automatically persisted as a property on the migration
+	 *
+	 * @param string     $old_table with wpdb prefix (wp_). Eg: wp_events_detail
+	 * @param int|string $old_pk    old primary key. Eg events_detail.id's value
+	 * @param string     $new_table with wpdb prefix (wp_). Eg: wp_posts
+	 * @param int|string $new_pk    eg posts.ID
+	 * @return void
+	 */
+	public function set_mapping($old_table, $old_pk, $new_table, $new_pk)
+	{
+		// make sure it has the needed keys
+		if (! isset($this->_mappings[ $old_table ]) || ! isset($this->_mappings[ $old_table ][ $new_table ])) {
+			$this->_mappings[ $old_table ][ $new_table ] = $this->_get_mapping_option($old_table, $new_table);
+		}
+		$this->_mappings[ $old_table ][ $new_table ][ $old_pk ] = $new_pk;
+	}
+
+
+	/**
+	 * Gets the new primary key, if provided with the OLD table and the primary key
+	 * of an item in the old table, and the new table
+	 *
+	 * @param string     $old_table with wpdb prefix (wp_). Eg: wp_events_detail
+	 * @param int|string $old_pk    old primary key. Eg events_detail.id's value
+	 * @param string     $new_table with wpdb prefix (wp_). Eg: wp_posts
+	 * @return mixed the primary key on the new table
+	 */
+	public function get_mapping_new_pk($old_table, $old_pk, $new_table)
+	{
+		if (
+			! isset($this->_mappings[ $old_table ]) ||
+			! isset($this->_mappings[ $old_table ][ $new_table ])
+		) {
+			// try fetching the option
+			$this->_mappings[ $old_table ][ $new_table ] = $this->_get_mapping_option($old_table, $new_table);
+		}
+		return isset($this->_mappings[ $old_table ][ $new_table ][ $old_pk ])
+			? $this->_mappings[ $old_table ][ $new_table ][ $old_pk ] : null;
+	}
+
+
+	/**
+	 * Gets the old primary key, if provided with the OLD table,
+	 * and the new table and the primary key of an item in the new table
+	 *
+	 * @param string $old_table with wpdb prefix (wp_). Eg: wp_events_detail
+	 * @param string $new_table with wpdb prefix (wp_). Eg: wp_posts
+	 * @param mixed  $new_pk
+	 * @return mixed
+	 */
+	public function get_mapping_old_pk($old_table, $new_table, $new_pk)
+	{
+		if (
+			! isset($this->_mappings[ $old_table ]) ||
+			! isset($this->_mappings[ $old_table ][ $new_table ])
+		) {
+			// try fetching the option
+			$this->_mappings[ $old_table ][ $new_table ] = $this->_get_mapping_option($old_table, $new_table);
+		}
+		if (isset($this->_mappings[ $old_table ][ $new_table ])) {
+			$new_pk_to_old_pk = array_flip($this->_mappings[ $old_table ][ $new_table ]);
+			if (isset($new_pk_to_old_pk[ $new_pk ])) {
+				return $new_pk_to_old_pk[ $new_pk ];
+			}
+		}
+		return null;
+	}
+
+
+	/**
+	 * Gets the mapping array option specified by the table names
+	 *
+	 * @param string $old_table_name
+	 * @param string $new_table_name
+	 * @return array
+	 */
+	protected function _get_mapping_option($old_table_name, $new_table_name)
+	{
+		$option = get_option($this->_get_mapping_option_name($old_table_name, $new_table_name), array());
+		return $option;
+	}
+
+
+	/**
+	 * Updates the mapping option specified by the table names with the array provided
+	 *
+	 * @param string $old_table_name
+	 * @param string $new_table_name
+	 * @param array  $mapping_array
+	 * @return boolean success of updating option
+	 */
+	protected function _set_mapping_option($old_table_name, $new_table_name, $mapping_array)
+	{
+		$success = update_option($this->_get_mapping_option_name($old_table_name, $new_table_name), $mapping_array, false);
+		return $success;
+	}
+
+
+	/**
+	 * Gets the option name for this script to map from $old_table_name to $new_table_name
+	 *
+	 * @param string $old_table_name
+	 * @param string $new_table_name
+	 * @return string
+	 */
+	protected function _get_mapping_option_name($old_table_name, $new_table_name)
+	{
+		global $wpdb;
+		$old_table_name_sans_wp = str_replace($wpdb->prefix, "", $old_table_name);
+		$new_table_name_sans_wp = str_replace($wpdb->prefix, "", $new_table_name);
+		$migrates_to = EE_Data_Migration_Manager::instance()->script_migrates_to_version(get_class($this));
+		return substr(
+			EE_Data_Migration_Manager::data_migration_script_mapping_option_prefix . $migrates_to ['slug'] . '_' . $migrates_to['version'] . '_' . $old_table_name_sans_wp . '_' . $new_table_name_sans_wp,
+			0,
+			64
+		);
+	}
+
+
+	/**
+	 * Counts all the records that will be migrated during this data migration.
+	 * For example, if we were changing old user passwords from plaintext to encoded versions,
+	 * this would be a count of all users who have passwords. If we were going to also split
+	 * attendee records into transactions, registrations, and attendee records, this would include
+	 * the count of all attendees currently in existence in the DB (ie, users + attendees).
+	 * If you can't determine how many records there are to migrate, just provide a guess: this
+	 * number will only be used in calculating the percent complete. If you estimate there to be
+	 * 100 records to migrate, and it turns out there's 120, we'll just show the migration as being at
+	 * 99% until the function "migration_step" returns EE_Data_Migration_Script_Base::status_complete.
+	 *
+	 * @return int
+	 */
+	protected function _count_records_to_migrate()
+	{
+		$count = 0;
+		foreach ($this->stages() as $stage) {
+			$count += $stage->count_records_to_migrate();
+		}
+		return $count;
+	}
+
+
+	/**
+	 * Returns the number of records updated so far. Usually this is easiest to do
+	 * by just setting a transient and updating it after each migration_step
+	 *
+	 * @return int
+	 */
+	public function count_records_migrated()
+	{
+		$count = 0;
+		foreach ($this->stages() as $stage) {
+			$count += $stage->count_records_migrated();
+		}
+		$this->_records_migrated = $count;
+		return $count;
+	}
+
+
+	/**
+	 * @param int $num_records_to_migrate_limit
+	 * @return int
+	 * @throws EE_Error
+	 * @throws Exception
+	 */
+	public function migration_step($num_records_to_migrate_limit)
+	{
+		// reset the feedback message
+		$this->_feedback_message = '';
+		// if we haven't yet done the 1st schema changes, do them now. buffer any output
+		$this->_maybe_do_schema_changes(true);
+
+		$num_records_actually_migrated = 0;
+		$records_migrated_per_stage = array();
+		// setup the 'stage' variable, which should hold the last run stage of the migration  (or none at all if nothing runs)
+		$stage = null;
+		// get the next stage that isn't complete
+		foreach ($this->stages() as $stage) {
+			if ($stage->get_status() == EE_Data_Migration_Manager::status_continue) {
+				try {
+					$records_migrated_during_stage = $stage->migration_step(
+						$num_records_to_migrate_limit - $num_records_actually_migrated
+					);
+					$num_records_actually_migrated += $records_migrated_during_stage;
+					$records_migrated_per_stage[ $stage->pretty_name() ] = $records_migrated_during_stage;
+				} catch (Exception $e) {
+					// yes if we catch an exception here, we consider that migration stage borked.
+					$stage->set_status(EE_Data_Migration_Manager::status_fatal_error);
+					$this->set_status(EE_Data_Migration_Manager::status_fatal_error);
+					$stage->add_error($e->getMessage() . ". Stack-trace:" . $e->getTraceAsString());
+					throw $e;
+				}
+				// check that the migration stage didn't mark itself as having a fatal error
+				if ($stage->is_broken()) {
+					$this->set_broken();
+					throw new EE_Error($stage->get_last_error());
+				}
+			}
+			// once we've migrated all the number we intended to (possibly from different stages), stop migrating
+			// or if we had a fatal error
+			// or if the current script stopped early- its not done, but it's done all it thinks we should do on this step
+			if (
+				$num_records_actually_migrated >= $num_records_to_migrate_limit
+				|| $stage->is_broken()
+				|| $stage->has_more_to_do()
+			) {
+				break;
+			}
+		}
+		// check if we're all done this data migration...
+		// which is indicated by being done early AND the last stage claims to be done
+		if ($stage == null) {
+			// this migration script apparently has NO stages... which is super weird, but whatever
+			$this->set_completed();
+			$this->_maybe_do_schema_changes(false);
+		} elseif ($num_records_actually_migrated < $num_records_to_migrate_limit && ! $stage->has_more_to_do()) {
+			// apparently we're done, because we couldn't migrate the number we intended to
+			$this->set_completed();
+			$this->_update_feedback_message(array_reverse($records_migrated_per_stage));
+			// do schema changes for after the migration now
+			// first double-check we haven't already done this
+			$this->_maybe_do_schema_changes(false);
+		} else {
+			// update feedback message, keeping in mind that we show them with the most recent at the top
+			$this->_update_feedback_message(array_reverse($records_migrated_per_stage));
+		}
+		return $num_records_actually_migrated;
+	}
+
+
+	/**
+	 * Updates the feedback message according to what was done during this migration stage.
+	 *
+	 * @param array $records_migrated_per_stage KEYS are pretty names for each stage; values are the count of records
+	 *                                          migrated from that stage
+	 * @return void
+	 */
+	private function _update_feedback_message($records_migrated_per_stage)
+	{
+		$feedback_message_array = array();
+		foreach ($records_migrated_per_stage as $migration_stage_name => $num_records_migrated) {
+			$feedback_message_array[] = sprintf(
+				esc_html__("Migrated %d records successfully during %s", "event_espresso"),
+				$num_records_migrated,
+				$migration_stage_name
+			);
+		}
+		$this->_feedback_message .= implode("<br>", $feedback_message_array);
+	}
+
+
+	/**
+	 * Calls either schema_changes_before_migration() (if $before==true) or schema_changes_after_migration
+	 * (if $before==false). Buffers their outputs and stores them on the class.
+	 *
+	 * @param boolean $before
+	 * @throws Exception
+	 * @return void
+	 */
+	private function _maybe_do_schema_changes($before = true)
+	{
+		// so this property will be either _schema_changes_after_migration_ran or _schema_changes_before_migration_ran
+		$property_name = '_schema_changes_' . ($before ? 'before' : 'after') . '_migration_ran';
+		if (! $this->{$property_name}) {
+			try {
+				ob_start();
+				if ($before) {
+					$this->schema_changes_before_migration();
+				} else {
+					$this->schema_changes_after_migration();
+				}
+				$output = ob_get_contents();
+				ob_end_clean();
+			} catch (Exception $e) {
+				$this->set_status(EE_Data_Migration_Manager::status_fatal_error);
+				throw $e;
+			}
+			// record that we've done these schema changes
+			$this->{$property_name} = true;
+			// if there were any warnings etc, record them as non-fatal errors
+			if ($output) {
+				// there were some warnings
+				$this->_errors[] = $output;
+			}
+		}
+	}
+
+
+	/**
+	 * Wrapper for EEH_Activation::create_table. However, takes into account the request type when
+	 * deciding what to pass for its 4th arg, $drop_pre_existing_tables. Using this function, instead
+	 * of _table_should_exist_previously, indicates that this table should be new to the EE version being migrated to
+	 * or
+	 * activated currently. If this is a brand new activation or a migration, and we're indicating this table should
+	 * not
+	 * previously exist, then we want to set $drop_pre_existing_tables to TRUE (ie, we shouldn't discover that this
+	 * table exists in the DB in EEH_Activation::create_table- if it DOES exist, something's wrong and the old table
+	 * should be nuked.
+	 *
+	 * Just for a bit of context, the migration script's db_schema_changes_* methods
+	 * are called basically in 3 cases: on brand new activation of EE4 (ie no previous version of EE existed and the
+	 * plugin is being activated and we want to add all the brand new tables), upon reactivation of EE4 (it was
+	 * deactivated and then reactivated, in which case we want to just verify the DB structure is ok) that table should
+	 * be dropped), and during a migration when we're moving the DB to the state of the migration script
+	 *
+	 * @param string $table_name
+	 * @param string $table_definition_sql
+	 * @param string $engine_string
+	 */
+	protected function _table_is_new_in_this_version(
+		$table_name,
+		$table_definition_sql,
+		$engine_string = 'ENGINE=InnoDB '
+	) {
+		$this->_create_table_and_catch_errors(
+			$table_name,
+			$table_definition_sql,
+			$engine_string,
+			$this->_pre_existing_table_should_be_dropped(true)
+		);
+	}
+
+	/**
+	 * Like _table_is_new_in_this_version and _table_should_exist_previously, this function verifies the given table
+	 * exists. But we understand that this table has CHANGED in this version since the previous version. So it's not
+	 * completely new, but it's different. So we need to treat it like a new table in terms of verifying it's schema is
+	 * correct on activations, migrations, upgrades; but if it exists when it shouldn't, we need to be as lenient as
+	 * _table_should_exist_previously.
+	 * 8656]{Assumes only this plugin could have added this table (ie, if its a new activation of this plugin, the
+	 * table shouldn't exist).
+	 *
+	 * @param string $table_name
+	 * @param string $table_definition_sql
+	 * @param string $engine_string
+	 */
+	protected function _table_is_changed_in_this_version(
+		$table_name,
+		$table_definition_sql,
+		$engine_string = 'ENGINE=MyISAM'
+	) {
+		$this->_create_table_and_catch_errors(
+			$table_name,
+			$table_definition_sql,
+			$engine_string,
+			$this->_pre_existing_table_should_be_dropped(false)
+		);
+	}
+
+
+	/**
+	 * _old_table_exists
+	 * returns TRUE if the requested table exists in the current database
+	 *
+	 * @param string $table_name
+	 * @return boolean
+	 */
+	protected function _old_table_exists($table_name)
+	{
+		return $this->_get_table_analysis()->tableExists($table_name);
+	}
+
+
+	/**
+	 * _delete_table_if_empty
+	 * returns TRUE if the requested table was empty and successfully empty
+	 *
+	 * @param string $table_name
+	 * @return boolean
+	 */
+	protected function _delete_table_if_empty($table_name)
+	{
+		return EEH_Activation::delete_db_table_if_empty($table_name);
+	}
+
+
+	/**
+	 * It is preferred to use _table_has_not_changed_since_previous or _table_is_changed_in_this_version
+	 * as these are significantly more efficient or explicit.
+	 * Please see description of _table_is_new_in_this_version. This function will only set
+	 * EEH_Activation::create_table's $drop_pre_existing_tables to TRUE if it's a brand
+	 * new activation. ie, a more accurate name for this method would be "_table_added_previously_by_this_plugin"
+	 * because the table will be cleared out if this is a new activation (ie, if its a new activation, it actually
+	 * should exist previously). Otherwise, we'll always set $drop_pre_existing_tables to FALSE because the table
+	 * should have existed. Note, if the table is being MODIFIED in this version being activated or migrated to, then
+	 * you want _table_is_changed_in_this_version NOT this one. We don't check this table's structure during migrations
+	 * because apparently it hasn't changed since the previous one, right?
+	 *
+	 * @param string $table_name
+	 * @param string $table_definition_sql
+	 * @param string $engine_string
+	 */
+	protected function _table_should_exist_previously(
+		$table_name,
+		$table_definition_sql,
+		$engine_string = 'ENGINE=MyISAM'
+	) {
+		$this->_create_table_and_catch_errors(
+			$table_name,
+			$table_definition_sql,
+			$engine_string,
+			$this->_pre_existing_table_should_be_dropped(false)
+		);
+	}
+
+	/**
+	 * Exactly the same as _table_should_exist_previously(), except if this migration script is currently doing
+	 * a migration, we skip checking this table's structure in the database and just assume it's correct.
+	 * So this is useful only to improve efficiency when doing migrations (not a big deal for single site installs,
+	 * but important for multisite where migrations can take a very long time otherwise).
+	 * If the table is known to have changed since previous version, use _table_is_changed_in_this_version().
+	 * Assumes only this plugin could have added this table (ie, if its a new activation of this plugin, the table
+	 * shouldn't exist).
+	 *
+	 * @param string $table_name
+	 * @param string $table_definition_sql
+	 * @param string $engine_string
+	 */
+	protected function _table_has_not_changed_since_previous(
+		$table_name,
+		$table_definition_sql,
+		$engine_string = 'ENGINE=MyISAM'
+	) {
+		if ($this->_currently_migrating()) {
+			// if we're doing a migration, and this table apparently already exists, then we don't need do anything right?
+			return;
+		}
+		$this->_create_table_and_catch_errors(
+			$table_name,
+			$table_definition_sql,
+			$engine_string,
+			$this->_pre_existing_table_should_be_dropped(false)
+		);
+	}
+
+	/**
+	 * Returns whether or not this migration script is being used as part of an actual migration
+	 *
+	 * @return boolean
+	 */
+	protected function _currently_migrating()
+	{
+		// we want to know if we are currently performing a migration. We could just believe what was set on the _migrating property, but let's double-check (ie the script should apply and we should be in MM)
+		return $this->_migrating &&
+			   $this->can_migrate_from_version(
+				   EE_Data_Migration_Manager::instance()->ensure_current_database_state_is_set()
+			   ) &&
+			   EE_Maintenance_Mode::instance()->real_level() == EE_Maintenance_Mode::level_2_complete_maintenance;
+	}
+
+	/**
+	 * Determines if a table should be dropped, based on whether it's reported to be new in $table_is_new,
+	 * and the plugin's request type.
+	 * Assumes only this plugin could have added the table (ie, if its a new activation of this plugin, the table
+	 * shouldn't exist no matter what).
+	 *
+	 * @param boolean $table_is_new
+	 * @return boolean
+	 */
+	protected function _pre_existing_table_should_be_dropped($table_is_new)
+	{
+		if ($table_is_new) {
+			if (
+				$this->_get_req_type_for_plugin_corresponding_to_this_dms() == EE_System::req_type_new_activation
+				|| $this->_currently_migrating()
+			) {
+				return true;
+			} else {
+				return false;
+			}
+		} else {
+			if (
+				in_array(
+					$this->_get_req_type_for_plugin_corresponding_to_this_dms(),
+					array(EE_System::req_type_new_activation)
+				)
+			) {
+				return true;
+			} else {
+				return false;
+			}
+		}
+	}
+
+	/**
+	 * Just wraps EEH_Activation::create_table, but catches any errors it may throw and adds them as errors on the DMS
+	 *
+	 * @param string  $table_name
+	 * @param string  $table_definition_sql
+	 * @param string  $engine_string
+	 * @param boolean $drop_pre_existing_tables
+	 */
+	private function _create_table_and_catch_errors(
+		$table_name,
+		$table_definition_sql,
+		$engine_string = 'ENGINE=MyISAM',
+		$drop_pre_existing_tables = false
+	) {
+		try {
+			EEH_Activation::create_table($table_name, $table_definition_sql, $engine_string, $drop_pre_existing_tables);
+		} catch (EE_Error $e) {
+			$message = $e->getMessage() . '<br>Stack Trace:' . $e->getTraceAsString();
+			$this->add_error($message);
+			$this->_feedback_message .= $message;
+		}
+	}
+
+
+	/**
+	 * Gets the request type for the plugin (core or addon) that corresponds to this DMS
+	 *
+	 * @return int one of EE_System::_req_type_* constants
+	 * @throws EE_Error
+	 */
+	private function _get_req_type_for_plugin_corresponding_to_this_dms()
+	{
+		if ($this->slug() == 'Core') {
+			return EE_System::instance()->detect_req_type();
+		} else {// it must be for an addon
+			$addon_name = $this->slug();
+			if (EE_Registry::instance()->get_addon_by_name($addon_name)) {
+				return EE_Registry::instance()->get_addon_by_name($addon_name)->detect_req_type();
+			} else {
+				throw new EE_Error(
+					sprintf(
+						esc_html__(
+							"The DMS slug '%s' should correspond to the addon's name, which should also be '%s', but no such addon was registered. These are the registered addons' names: %s",
+							"event_espresso"
+						),
+						$this->slug(),
+						$addon_name,
+						implode(",", array_keys(EE_Registry::instance()->get_addons_by_name()))
+					)
+				);
+			}
+		}
+	}
+
+
+	/**
+	 * returns an array of strings describing errors by all the script's stages
+	 *
+	 * @return array
+	 */
+	public function get_errors()
+	{
+		$all_errors = $this->_errors;
+		if (! is_array($all_errors)) {
+			$all_errors = array();
+		}
+		foreach ($this->stages() as $stage) {
+			$all_errors = array_merge($stage->get_errors(), $all_errors);
+		}
+		return $all_errors;
+	}
+
+
+	/**
+	 * Indicates whether or not this migration script should continue
+	 *
+	 * @return boolean
+	 */
+	public function can_continue()
+	{
+		return in_array(
+			$this->get_status(),
+			EE_Data_Migration_Manager::instance()->stati_that_indicate_to_continue_single_migration_script
+		);
+	}
+
+
+	/**
+	 * Gets all the data migration stages associated with this script. Note:
+	 * addons can filter this list to add their own stages, and because the list is
+	 * numerically-indexed, they can insert their stage wherever they like and it will
+	 * get ordered by the indexes
+	 *
+	 * @return EE_Data_Migration_Script_Stage[]
+	 */
+	protected function stages()
+	{
+		$stages = apply_filters('FHEE__' . get_class($this) . '__stages', $this->_migration_stages);
+		ksort($stages);
+		return $stages;
+	}
+
+
+	/**
+	 * Gets a string which should describe what's going on currently with this migration, which
+	 * can be displayed to the user
+	 *
+	 * @return string
+	 */
+	public function get_feedback_message()
+	{
+		return $this->_feedback_message;
+	}
+
+
+	/**
+	 * A lot like "__sleep()" magic method in purpose, this is meant for persisting this class'
+	 * properties to the DB. However, we don't want to use __sleep() because its quite
+	 * possible that this class is defined when it goes to sleep, but NOT available when it
+	 * awakes (eg, this class is part of an addon that is deactivated at some point).
+	 */
+	public function properties_as_array()
+	{
+		$properties = parent::properties_as_array();
+		$properties['_migration_stages'] = array();
+		foreach ($this->_migration_stages as $migration_stage_priority => $migration_stage_class) {
+			$properties['_migration_stages'][ $migration_stage_priority ] = $migration_stage_class->properties_as_array(
+			);
+		}
+		unset($properties['_mappings']);
+		unset($properties['previous_dms']);
+
+		foreach ($this->_mappings as $old_table_name => $mapping_to_new_table) {
+			foreach ($mapping_to_new_table as $new_table_name => $mapping) {
+				$this->_set_mapping_option($old_table_name, $new_table_name, $mapping);
+			}
+		}
+		return $properties;
+	}
+
+
+	/**
+	 * Sets all of the properties of this script stage to match what's in the array, which is assumed
+	 * to have been made from the properties_as_array() function.
+	 *
+	 * @param array $array_of_properties like what's produced from properties_as_array() method
+	 * @return void
+	 */
+	public function instantiate_from_array_of_properties($array_of_properties)
+	{
+		$stages_properties_arrays = $array_of_properties['_migration_stages'];
+		unset($array_of_properties['_migration_stages']);
+		unset($array_of_properties['class']);
+		foreach ($array_of_properties as $property_name => $property_value) {
+			$this->{$property_name} = $property_value;
+		}
+		// _migration_stages are already instantiated, but have only default data
+		foreach ($this->_migration_stages as $stage) {
+			$stage_data = $this->_find_migration_stage_data_with_classname(
+				get_class($stage),
+				$stages_properties_arrays
+			);
+			// SO, if we found the stage data that was saved, use it. Otherwise, I guess the stage is new? (maybe added by
+			// an addon? Unlikely... not sure why it wouldn't exist, but if it doesn't just treat it like it was never started yet)
+			if ($stage_data) {
+				$stage->instantiate_from_array_of_properties($stage_data);
+			}
+		}
+	}
+
+
+	/**
+	 * Gets the migration data from the array $migration_stage_data_arrays (which is an array of arrays, each of which
+	 * is pretty well identical to EE_Data_Migration_Stage objects except all their properties are array indexes)
+	 * for the given classname
+	 *
+	 * @param string $classname
+	 * @param array  $migration_stage_data_arrays
+	 * @return null
+	 */
+	private function _find_migration_stage_data_with_classname($classname, $migration_stage_data_arrays)
+	{
+		foreach ($migration_stage_data_arrays as $migration_stage_data_array) {
+			if (isset($migration_stage_data_array['class']) && $migration_stage_data_array['class'] == $classname) {
+				return $migration_stage_data_array;
+			}
+		}
+		return null;
+	}
+
+
+	/**
+	 * Returns the version that this script migrates to, based on the script's name.
+	 * Cannot be overwritten because lots of code needs to know which version a script
+	 * migrates to knowing only its name.
+	 *
+	 * @return array where the first key is the plugin's slug, the 2nd is the version of that plugin
+	 * that will be updated to. Eg array('Core','4.1.0')
+	 */
+	final public function migrates_to_version()
+	{
+		return EE_Data_Migration_Manager::instance()->script_migrates_to_version(get_class($this));
+	}
+
+
+	/**
+	 * Gets this addon's slug as it would appear in the current_db_state wp option,
+	 * and if this migration script is for an addon, it SHOULD match the addon's slug
+	 * (and also the addon's classname, minus the 'EE_' prefix.). Eg, 'Calendar' for the EE_Calendar addon.
+	 * Or 'Core' for core (non-addon).
+	 *
+	 * @return string
+	 */
+	public function slug()
+	{
+		$migrates_to_version_info = $this->migrates_to_version();
+		// the slug is the first part of the array
+		return $migrates_to_version_info['slug'];
+	}
+
+
+	/**
+	 * Returns the script's priority relative to DMSs from other addons. However, when
+	 * two DMSs from the same addon/core apply, this is ignored (and instead the version that
+	 * the script migrates to is used to determine which to run first). The default is 5, but all core DMSs
+	 * normally have priority 10. (So if you want a DMS "A" to run before DMS "B", both of which are from addons,
+	 * and both of which CAN run at the same time (ie, "B" doesn't depend on "A" to set
+	 * the database up so it can run), then you can set "A" to priority 3 or something.
+	 *
+	 * @return int
+	 */
+	public function priority()
+	{
+		return $this->_priority;
+	}
+
+
+	/**
+	 * Sets whether or not this DMS is being ran as part of a migration, instead of
+	 * just being used to setup (or verify) the current database structure matches
+	 * what the latest DMS indicates it should be
+	 *
+	 * @param boolean $migrating
+	 * @return void
+	 */
+	public function set_migrating($migrating = true)
+	{
+		$this->_migrating = $migrating;
+	}
+
+	/**
+	 * Marks that we think this migration class can continue to migrate
+	 */
+	public function reattempt()
+	{
+		parent::reattempt();
+		// also, we want to reattempt any stages that were marked as borked
+		foreach ($this->stages() as $stage) {
+			if ($stage->is_broken()) {
+				$stage->reattempt();
+			}
+		}
+	}
 }

core/data_migration_scripts/4_1_0_stages/EE_DMS_4_1_0_shortcodes.dmsstage.php

Spacing +2 added lines, -2 removed lines

@@ -18,7 +18,7 @@ 
     {
         $new_post_content = $this->_change_event_list_shortcode($old_row['post_content']);
         global $wpdb;
-        $wpdb->query($wpdb->prepare("UPDATE " . $this->_old_table . " SET post_content=%s WHERE ID=%d", $new_post_content, $old_row['ID']));
+        $wpdb->query($wpdb->prepare("UPDATE ".$this->_old_table." SET post_content=%s WHERE ID=%d", $new_post_content, $old_row['ID']));
     }
 
     /**
@@ -48,7 +48,7 @@ 
     public function _count_records_to_migrate()
     {
         global $wpdb;
-        $count = $wpdb->get_var("SELECT COUNT(id) FROM " . $this->_old_table . $this->_sql_to_only_select_non_drafts());
+        $count = $wpdb->get_var("SELECT COUNT(id) FROM ".$this->_old_table.$this->_sql_to_only_select_non_drafts());
         return $count;
     }
 

Indentation +47 added lines, -48 removed lines

@@ -2,58 +2,57 @@
 
 /**
  * Goes through all the posts and pages, and converts old shortcodes to new ones
-
-*/
+ */
 
 class EE_DMS_4_1_0_shortcodes extends EE_Data_Migration_Script_Stage
 {
-    public function __construct()
-    {
-        global $wpdb;
-        $this->_pretty_name = esc_html__("Shortcodes", "event_espresso");
-        $this->_old_table = $wpdb->posts;
-        parent::__construct();
-    }
-    protected function _migrate_old_row($old_row)
-    {
-        $new_post_content = $this->_change_event_list_shortcode($old_row['post_content']);
-        global $wpdb;
-        $wpdb->query($wpdb->prepare("UPDATE " . $this->_old_table . " SET post_content=%s WHERE ID=%d", $new_post_content, $old_row['ID']));
-    }
+	public function __construct()
+	{
+		global $wpdb;
+		$this->_pretty_name = esc_html__("Shortcodes", "event_espresso");
+		$this->_old_table = $wpdb->posts;
+		parent::__construct();
+	}
+	protected function _migrate_old_row($old_row)
+	{
+		$new_post_content = $this->_change_event_list_shortcode($old_row['post_content']);
+		global $wpdb;
+		$wpdb->query($wpdb->prepare("UPDATE " . $this->_old_table . " SET post_content=%s WHERE ID=%d", $new_post_content, $old_row['ID']));
+	}
 
-    /**
-     * replaces [EVENT_LIST... with [ESPRESSO_EVENTS...]
-     * @param string $old_content
-     */
-    private function _change_event_list_shortcode($old_content)
-    {
-        return str_replace("[EVENT_LIST", "[ESPRESSO_EVENTS", $old_content);
-    }
+	/**
+	 * replaces [EVENT_LIST... with [ESPRESSO_EVENTS...]
+	 * @param string $old_content
+	 */
+	private function _change_event_list_shortcode($old_content)
+	{
+		return str_replace("[EVENT_LIST", "[ESPRESSO_EVENTS", $old_content);
+	}
 
-    public function _migration_step($num_items = 50)
-    {
-        global $wpdb;
-        $start_at_record = $this->count_records_migrated();
-        $rows = $wpdb->get_results($wpdb->prepare("SELECT * FROM $this->_old_table {$this->_sql_to_only_select_non_drafts()} LIMIT %d,%d", $start_at_record, $num_items), ARRAY_A);
-        $items_actually_migrated = 0;
-        foreach ($rows as $old_row) {
-            $this->_migrate_old_row($old_row);
-            $items_actually_migrated++;
-        }
-        if ($this->count_records_migrated() + $items_actually_migrated >= $this->count_records_to_migrate()) {
-            $this->set_completed();
-        }
-        return $items_actually_migrated;
-    }
-    public function _count_records_to_migrate()
-    {
-        global $wpdb;
-        $count = $wpdb->get_var("SELECT COUNT(id) FROM " . $this->_old_table . $this->_sql_to_only_select_non_drafts());
-        return $count;
-    }
+	public function _migration_step($num_items = 50)
+	{
+		global $wpdb;
+		$start_at_record = $this->count_records_migrated();
+		$rows = $wpdb->get_results($wpdb->prepare("SELECT * FROM $this->_old_table {$this->_sql_to_only_select_non_drafts()} LIMIT %d,%d", $start_at_record, $num_items), ARRAY_A);
+		$items_actually_migrated = 0;
+		foreach ($rows as $old_row) {
+			$this->_migrate_old_row($old_row);
+			$items_actually_migrated++;
+		}
+		if ($this->count_records_migrated() + $items_actually_migrated >= $this->count_records_to_migrate()) {
+			$this->set_completed();
+		}
+		return $items_actually_migrated;
+	}
+	public function _count_records_to_migrate()
+	{
+		global $wpdb;
+		$count = $wpdb->get_var("SELECT COUNT(id) FROM " . $this->_old_table . $this->_sql_to_only_select_non_drafts());
+		return $count;
+	}
 
-    private function _sql_to_only_select_non_drafts()
-    {
-        return " WHERE post_type NOT IN ('revision','auto-draft','attachment','nav_menu_item') ";
-    }
+	private function _sql_to_only_select_non_drafts()
+	{
+		return " WHERE post_type NOT IN ('revision','auto-draft','attachment','nav_menu_item') ";
+	}
 }

core/data_migration_scripts/4_1_0_stages/EE_DMS_4_1_0_checkins.dmsstage.php

Indentation +142 added lines, -142 removed lines

@@ -26,160 +26,160 @@
 
 class EE_DMS_4_1_0_checkins extends EE_Data_Migration_Script_Stage_Table
 {
-    private $_new_table;
-    public function __construct()
-    {
-        global $wpdb;
-        $this->_pretty_name = esc_html__('Checkins', 'event_espresso');
-        $this->_old_table = $wpdb->prefix . "events_attendee";
-        $this->select_expression = 'att.*, e.event_status';
-        $this->_extra_where_sql = 'AS att
+	private $_new_table;
+	public function __construct()
+	{
+		global $wpdb;
+		$this->_pretty_name = esc_html__('Checkins', 'event_espresso');
+		$this->_old_table = $wpdb->prefix . "events_attendee";
+		$this->select_expression = 'att.*, e.event_status';
+		$this->_extra_where_sql = 'AS att
             INNER JOIN ' . $wpdb->prefix . 'events_detail AS e ON att.event_id=e.id
             WHERE e.event_status!="D"';
-        $this->_new_table = $wpdb->prefix . "esp_checkin";
-        parent::__construct();
-    }
-    protected function _migrate_old_row($old_row)
-    {
-        global $wpdb;
-        $new_reg_table = $wpdb->prefix . "esp_registration";
+		$this->_new_table = $wpdb->prefix . "esp_checkin";
+		parent::__construct();
+	}
+	protected function _migrate_old_row($old_row)
+	{
+		global $wpdb;
+		$new_reg_table = $wpdb->prefix . "esp_registration";
 
-        $num_to_checkin_at_this_time = max(array(intval($old_row['checked_in_quantity']),intval($old_row['checked_in']))) ;
+		$num_to_checkin_at_this_time = max(array(intval($old_row['checked_in_quantity']),intval($old_row['checked_in']))) ;
 
-        $new_registrations_for_attendee = $this->get_migration_script()->get_mapping_new_pk($this->_old_table, $old_row['id'], $new_reg_table);
-        if (! $new_registrations_for_attendee) {
-            $new_registrations_for_attendee = array();
-        }
-        $new_datetime = $this->_try_to_find_datetime($old_row);
+		$new_registrations_for_attendee = $this->get_migration_script()->get_mapping_new_pk($this->_old_table, $old_row['id'], $new_reg_table);
+		if (! $new_registrations_for_attendee) {
+			$new_registrations_for_attendee = array();
+		}
+		$new_datetime = $this->_try_to_find_datetime($old_row);
 
-        // make sure registrations array is numerically indexed starting at 0 (it probably already is)
-        $new_registrations_for_attendee = array_values($new_registrations_for_attendee);
-        $new_checkin_ids = array();
-        for ($i = 0; $i < abs($num_to_checkin_at_this_time); $i++) {
-            $new_reg_id = $new_registrations_for_attendee[ $i ];
-            if (! $new_reg_id) {
-                $this->add_error(sprintf(
-                    esc_html__(
-                        /* translators: %1$s database row represented in JSON, %2$s number of registrations to check-in
+		// make sure registrations array is numerically indexed starting at 0 (it probably already is)
+		$new_registrations_for_attendee = array_values($new_registrations_for_attendee);
+		$new_checkin_ids = array();
+		for ($i = 0; $i < abs($num_to_checkin_at_this_time); $i++) {
+			$new_reg_id = $new_registrations_for_attendee[ $i ];
+			if (! $new_reg_id) {
+				$this->add_error(sprintf(
+					esc_html__(
+						/* translators: %1$s database row represented in JSON, %2$s number of registrations to check-in
                         *  %3$s number of registrations for the attendee, %4$s new registration rows represented in JSON
                         */
-                        // @codingStandardsIgnoreStart
-                        'It appears we wanted to check-in more registrations than actually exist. The old attendee record (%1$s) indicated we should check-in %2$d registrations, but there are only %3$d registrations for that attendee (%4$s)',
-                        // @codingStandardsIgnoreEnd
-                        'event_espresso'
-                    ),
-                    $this->_json_encode($old_row),
-                    abs($num_to_checkin_at_this_time),
-                    count($new_registrations_for_attendee),
-                    $this->_json_encode($new_registrations_for_attendee)
-                ));
-                break;
-            }
-            $existing_checkin_record = $wpdb->get_var(
-                $wpdb->prepare(
-                    "SELECT CHK_ID FROM $this->_new_table WHERE REG_ID = %d ORDER BY CHK_ID DESC LIMIT 1",
-                    $new_reg_id
-                )
-            );
-            if (! $existing_checkin_record) {
-                $new_id = $this->_insert_checkin_record($new_reg_id, $new_datetime);
-                if ($new_id) {
-                    $new_checkin_ids[] = $new_id;
-                }
-            }
-        }
-        if ($new_checkin_ids) {
-            $this->get_migration_script()->set_mapping(
-                $this->_old_table,
-                $old_row['id'],
-                $this->_new_table,
-                $new_checkin_ids
-            );
-        }
-    }
+						// @codingStandardsIgnoreStart
+						'It appears we wanted to check-in more registrations than actually exist. The old attendee record (%1$s) indicated we should check-in %2$d registrations, but there are only %3$d registrations for that attendee (%4$s)',
+						// @codingStandardsIgnoreEnd
+						'event_espresso'
+					),
+					$this->_json_encode($old_row),
+					abs($num_to_checkin_at_this_time),
+					count($new_registrations_for_attendee),
+					$this->_json_encode($new_registrations_for_attendee)
+				));
+				break;
+			}
+			$existing_checkin_record = $wpdb->get_var(
+				$wpdb->prepare(
+					"SELECT CHK_ID FROM $this->_new_table WHERE REG_ID = %d ORDER BY CHK_ID DESC LIMIT 1",
+					$new_reg_id
+				)
+			);
+			if (! $existing_checkin_record) {
+				$new_id = $this->_insert_checkin_record($new_reg_id, $new_datetime);
+				if ($new_id) {
+					$new_checkin_ids[] = $new_id;
+				}
+			}
+		}
+		if ($new_checkin_ids) {
+			$this->get_migration_script()->set_mapping(
+				$this->_old_table,
+				$old_row['id'],
+				$this->_new_table,
+				$new_checkin_ids
+			);
+		}
+	}
 
 
-    /**
-     * Tries to find the new datetime the Check-in was for, based on the attendee row
-     * (because we know the attendee was for an event as a specific time, and we know
-     * the event's OLD ID...)
-     * @global type $wpdb
-     * @param array $old_attendee_row
-     * @return array row of datetime from DB
-     */
-    private function _try_to_find_datetime($old_attendee)
-    {
-        global $wpdb;
+	/**
+	 * Tries to find the new datetime the Check-in was for, based on the attendee row
+	 * (because we know the attendee was for an event as a specific time, and we know
+	 * the event's OLD ID...)
+	 * @global type $wpdb
+	 * @param array $old_attendee_row
+	 * @return array row of datetime from DB
+	 */
+	private function _try_to_find_datetime($old_attendee)
+	{
+		global $wpdb;
 
-        $new_event_id = $this->get_migration_script()->get_mapping_new_pk($wpdb->prefix . "events_detail", $old_attendee['event_id'], $wpdb->posts);
-        if (! $new_event_id) {
-            $this->add_error(
-                sprintf(
-                    esc_html__(
-                        /* translators: 1: original event ID, 2: original attendee database row */
-                        // @codingStandardsIgnoreStart
-                        'Could not find new event ID with old event ID %1$d, on attendee row %2$s; and because of that couldn\'t find the correct datetime for Check-in',
-                        // @codingStandardsIgnoreEnd
-                        'event_espresso'
-                    ),
-                    $old_attendee['event_id'],
-                    $this->_json_encode($old_attendee)
-                )
-            );
-            return 0;
-        }
-        $old_att_start_date = $old_attendee['start_date'];
-        $old_att_start_time = $this->get_migration_script()->convertTimeFromAMPM($old_attendee['event_time']);
-        $old_att_datetime = $this->get_migration_script()->convert_date_string_to_utc($this, $old_attendee, "$old_att_start_date $old_att_start_time:00");
+		$new_event_id = $this->get_migration_script()->get_mapping_new_pk($wpdb->prefix . "events_detail", $old_attendee['event_id'], $wpdb->posts);
+		if (! $new_event_id) {
+			$this->add_error(
+				sprintf(
+					esc_html__(
+						/* translators: 1: original event ID, 2: original attendee database row */
+						// @codingStandardsIgnoreStart
+						'Could not find new event ID with old event ID %1$d, on attendee row %2$s; and because of that couldn\'t find the correct datetime for Check-in',
+						// @codingStandardsIgnoreEnd
+						'event_espresso'
+					),
+					$old_attendee['event_id'],
+					$this->_json_encode($old_attendee)
+				)
+			);
+			return 0;
+		}
+		$old_att_start_date = $old_attendee['start_date'];
+		$old_att_start_time = $this->get_migration_script()->convertTimeFromAMPM($old_attendee['event_time']);
+		$old_att_datetime = $this->get_migration_script()->convert_date_string_to_utc($this, $old_attendee, "$old_att_start_date $old_att_start_time:00");
 
-        $datetime_table = $wpdb->prefix . "esp_datetime";
-        // add all conditions to an array from which we can SHIFT conditions off in order to widen our search
-        // the most important condition should be last, as it will be array_shift'ed off last
-        $conditions = array(
-            $wpdb->prepare("$datetime_table.DTT_EVT_start = %s", $old_att_datetime),// times match?
-            $wpdb->prepare("$datetime_table.EVT_ID = %d", $new_event_id),// events match?
-        );
-        // start running queries, widening search each time by removing a condition
-        $datetime_found = null;
-        do {
-            $full_query = "SELECT * FROM $datetime_table WHERE " . implode(" AND ", $conditions) . " LIMIT 1";
-            $datetime_found = $wpdb->get_row($full_query, ARRAY_A);
-            array_shift($conditions);
-        } while (! $datetime_found && $conditions);
-        return $datetime_found;
-    }
+		$datetime_table = $wpdb->prefix . "esp_datetime";
+		// add all conditions to an array from which we can SHIFT conditions off in order to widen our search
+		// the most important condition should be last, as it will be array_shift'ed off last
+		$conditions = array(
+			$wpdb->prepare("$datetime_table.DTT_EVT_start = %s", $old_att_datetime),// times match?
+			$wpdb->prepare("$datetime_table.EVT_ID = %d", $new_event_id),// events match?
+		);
+		// start running queries, widening search each time by removing a condition
+		$datetime_found = null;
+		do {
+			$full_query = "SELECT * FROM $datetime_table WHERE " . implode(" AND ", $conditions) . " LIMIT 1";
+			$datetime_found = $wpdb->get_row($full_query, ARRAY_A);
+			array_shift($conditions);
+		} while (! $datetime_found && $conditions);
+		return $datetime_found;
+	}
 
-    /**
-     * Adds a new Check-in/checkout record according for $new_reg_id,$new_datetime_id,$checking_in, and $timestmap
-     * @param int $new_reg_id
-     * @param int $new_datetime_id
-     * @param string $timestamp mysql datetime
-     * @return int new Check-in id
-     */
-    private function _insert_checkin_record($new_reg_id, $new_datetime)
-    {
-        global $wpdb;
+	/**
+	 * Adds a new Check-in/checkout record according for $new_reg_id,$new_datetime_id,$checking_in, and $timestmap
+	 * @param int $new_reg_id
+	 * @param int $new_datetime_id
+	 * @param string $timestamp mysql datetime
+	 * @return int new Check-in id
+	 */
+	private function _insert_checkin_record($new_reg_id, $new_datetime)
+	{
+		global $wpdb;
 
 
-        // ok we can actually do what we set out to do: add a checkin/checkout record
-        $cols_n_values = array(
-            'REG_ID' => $new_reg_id,
-            'DTT_ID' => $new_datetime['DTT_ID'],
-            'CHK_in' => true,
-            'CHK_timestamp' => $new_datetime['DTT_EVT_start']
-        );
-        $datatypes = array(
-            '%d',// REG_ID
-            '%d',// DTT_ID
-            '%d',// CHK_in
-            '%s',// CHK_timestamp
-        );
-        $success = $wpdb->insert($this->_new_table, $cols_n_values, $datatypes);
-        if (! $success) {
-            $this->add_error($this->get_migration_script()->_create_error_message_for_db_insertion($this->_old_table, $old_checkin, $this->_new_table, $cols_n_values, $datatypes));
-            return 0;
-        }
-        $new_id = $wpdb->insert_id;
-        return $new_id;
-    }
+		// ok we can actually do what we set out to do: add a checkin/checkout record
+		$cols_n_values = array(
+			'REG_ID' => $new_reg_id,
+			'DTT_ID' => $new_datetime['DTT_ID'],
+			'CHK_in' => true,
+			'CHK_timestamp' => $new_datetime['DTT_EVT_start']
+		);
+		$datatypes = array(
+			'%d',// REG_ID
+			'%d',// DTT_ID
+			'%d',// CHK_in
+			'%s',// CHK_timestamp
+		);
+		$success = $wpdb->insert($this->_new_table, $cols_n_values, $datatypes);
+		if (! $success) {
+			$this->add_error($this->get_migration_script()->_create_error_message_for_db_insertion($this->_old_table, $old_checkin, $this->_new_table, $cols_n_values, $datatypes));
+			return 0;
+		}
+		$new_id = $wpdb->insert_id;
+		return $new_id;
+	}
 }

Spacing +21 added lines, -21 removed lines

@@ -31,23 +31,23 @@ 
     {
         global $wpdb;
         $this->_pretty_name = esc_html__('Checkins', 'event_espresso');
-        $this->_old_table = $wpdb->prefix . "events_attendee";
+        $this->_old_table = $wpdb->prefix."events_attendee";
         $this->select_expression = 'att.*, e.event_status';
         $this->_extra_where_sql = 'AS att
-            INNER JOIN ' . $wpdb->prefix . 'events_detail AS e ON att.event_id=e.id
+            INNER JOIN ' . $wpdb->prefix.'events_detail AS e ON att.event_id=e.id
             WHERE e.event_status!="D"';
-        $this->_new_table = $wpdb->prefix . "esp_checkin";
+        $this->_new_table = $wpdb->prefix."esp_checkin";
         parent::__construct();
     }
     protected function _migrate_old_row($old_row)
     {
         global $wpdb;
-        $new_reg_table = $wpdb->prefix . "esp_registration";
+        $new_reg_table = $wpdb->prefix."esp_registration";
 
-        $num_to_checkin_at_this_time = max(array(intval($old_row['checked_in_quantity']),intval($old_row['checked_in']))) ;
+        $num_to_checkin_at_this_time = max(array(intval($old_row['checked_in_quantity']), intval($old_row['checked_in'])));
 
         $new_registrations_for_attendee = $this->get_migration_script()->get_mapping_new_pk($this->_old_table, $old_row['id'], $new_reg_table);
-        if (! $new_registrations_for_attendee) {
+        if ( ! $new_registrations_for_attendee) {
             $new_registrations_for_attendee = array();
         }
         $new_datetime = $this->_try_to_find_datetime($old_row);
@@ -56,8 +56,8 @@ 
         $new_registrations_for_attendee = array_values($new_registrations_for_attendee);
         $new_checkin_ids = array();
         for ($i = 0; $i < abs($num_to_checkin_at_this_time); $i++) {
-            $new_reg_id = $new_registrations_for_attendee[ $i ];
-            if (! $new_reg_id) {
+            $new_reg_id = $new_registrations_for_attendee[$i];
+            if ( ! $new_reg_id) {
                 $this->add_error(sprintf(
                     esc_html__(
                         /* translators: %1$s database row represented in JSON, %2$s number of registrations to check-in
@@ -81,7 +81,7 @@ 
                     $new_reg_id
                 )
             );
-            if (! $existing_checkin_record) {
+            if ( ! $existing_checkin_record) {
                 $new_id = $this->_insert_checkin_record($new_reg_id, $new_datetime);
                 if ($new_id) {
                     $new_checkin_ids[] = $new_id;
@@ -111,8 +111,8 @@ 
     {
         global $wpdb;
 
-        $new_event_id = $this->get_migration_script()->get_mapping_new_pk($wpdb->prefix . "events_detail", $old_attendee['event_id'], $wpdb->posts);
-        if (! $new_event_id) {
+        $new_event_id = $this->get_migration_script()->get_mapping_new_pk($wpdb->prefix."events_detail", $old_attendee['event_id'], $wpdb->posts);
+        if ( ! $new_event_id) {
             $this->add_error(
                 sprintf(
                     esc_html__(
@@ -132,20 +132,20 @@ 
         $old_att_start_time = $this->get_migration_script()->convertTimeFromAMPM($old_attendee['event_time']);
         $old_att_datetime = $this->get_migration_script()->convert_date_string_to_utc($this, $old_attendee, "$old_att_start_date $old_att_start_time:00");
 
-        $datetime_table = $wpdb->prefix . "esp_datetime";
+        $datetime_table = $wpdb->prefix."esp_datetime";
         // add all conditions to an array from which we can SHIFT conditions off in order to widen our search
         // the most important condition should be last, as it will be array_shift'ed off last
         $conditions = array(
-            $wpdb->prepare("$datetime_table.DTT_EVT_start = %s", $old_att_datetime),// times match?
-            $wpdb->prepare("$datetime_table.EVT_ID = %d", $new_event_id),// events match?
+            $wpdb->prepare("$datetime_table.DTT_EVT_start = %s", $old_att_datetime), // times match?
+            $wpdb->prepare("$datetime_table.EVT_ID = %d", $new_event_id), // events match?
         );
         // start running queries, widening search each time by removing a condition
         $datetime_found = null;
         do {
-            $full_query = "SELECT * FROM $datetime_table WHERE " . implode(" AND ", $conditions) . " LIMIT 1";
+            $full_query = "SELECT * FROM $datetime_table WHERE ".implode(" AND ", $conditions)." LIMIT 1";
             $datetime_found = $wpdb->get_row($full_query, ARRAY_A);
             array_shift($conditions);
-        } while (! $datetime_found && $conditions);
+        }while ( ! $datetime_found && $conditions);
         return $datetime_found;
     }
 
@@ -169,13 +169,13 @@ 
             'CHK_timestamp' => $new_datetime['DTT_EVT_start']
         );
         $datatypes = array(
-            '%d',// REG_ID
-            '%d',// DTT_ID
-            '%d',// CHK_in
-            '%s',// CHK_timestamp
+            '%d', // REG_ID
+            '%d', // DTT_ID
+            '%d', // CHK_in
+            '%s', // CHK_timestamp
         );
         $success = $wpdb->insert($this->_new_table, $cols_n_values, $datatypes);
-        if (! $success) {
+        if ( ! $success) {
             $this->add_error($this->get_migration_script()->_create_error_message_for_db_insertion($this->_old_table, $old_checkin, $this->_new_table, $cols_n_values, $datatypes));
             return 0;
         }

core/data_migration_scripts/EE_DMS_Core_4_9_0.dms.php

Indentation +310 added lines, -310 removed lines

@@ -12,9 +12,9 @@ 
 $stages = glob(EE_CORE . 'data_migration_scripts/4_9_0_stages/*');
 $class_to_filepath = array();
 foreach ($stages as $filepath) {
-    $matches = array();
-    preg_match('~4_9_0_stages/(.*).dmsstage.php~', $filepath, $matches);
-    $class_to_filepath[ $matches[1] ] = $filepath;
+	$matches = array();
+	preg_match('~4_9_0_stages/(.*).dmsstage.php~', $filepath, $matches);
+	$class_to_filepath[ $matches[1] ] = $filepath;
 }
 // give addons a chance to autoload their stages too
 $class_to_filepath = apply_filters('FHEE__EE_DMS_4_9_0__autoloaded_stages', $class_to_filepath);
@@ -34,68 +34,68 @@ 
 class EE_DMS_Core_4_9_0 extends EE_Data_Migration_Script_Base
 {
 
-    /**
-     * return EE_DMS_Core_4_9_0
-     *
-     * @param TableManager  $table_manager
-     * @param TableAnalysis $table_analysis
-     */
-    public function __construct(TableManager $table_manager = null, TableAnalysis $table_analysis = null)
-    {
-        $this->_pretty_name = esc_html__("Data Update to Event Espresso 4.9.0", "event_espresso");
-        $this->_priority = 10;
-        $this->_migration_stages = array(
-            new EE_DMS_4_9_0_Email_System_Question(),
-            new EE_DMS_4_9_0_Answers_With_No_Registration(),
-        );
-        parent::__construct($table_manager, $table_analysis);
-    }
+	/**
+	 * return EE_DMS_Core_4_9_0
+	 *
+	 * @param TableManager  $table_manager
+	 * @param TableAnalysis $table_analysis
+	 */
+	public function __construct(TableManager $table_manager = null, TableAnalysis $table_analysis = null)
+	{
+		$this->_pretty_name = esc_html__("Data Update to Event Espresso 4.9.0", "event_espresso");
+		$this->_priority = 10;
+		$this->_migration_stages = array(
+			new EE_DMS_4_9_0_Email_System_Question(),
+			new EE_DMS_4_9_0_Answers_With_No_Registration(),
+		);
+		parent::__construct($table_manager, $table_analysis);
+	}
 
 
 
-    /**
-     * Whether to migrate or not.
-     *
-     * @param array $version_array
-     * @return bool
-     */
-    public function can_migrate_from_version($version_array)
-    {
-        $version_string = $version_array['Core'];
-        if (version_compare($version_string, '4.9.0.decaf', '<') && version_compare($version_string, '4.8.0.decaf', '>=')) {
-            //          echo "$version_string can be migrated from";
-            return true;
-        } elseif (! $version_string) {
-            //          echo "no version string provided: $version_string";
-            // no version string provided... this must be pre 4.3
-            return false;// changed mind. dont want people thinking they should migrate yet because they cant
-        } else {
-            //          echo "$version_string doesnt apply";
-            return false;
-        }
-    }
+	/**
+	 * Whether to migrate or not.
+	 *
+	 * @param array $version_array
+	 * @return bool
+	 */
+	public function can_migrate_from_version($version_array)
+	{
+		$version_string = $version_array['Core'];
+		if (version_compare($version_string, '4.9.0.decaf', '<') && version_compare($version_string, '4.8.0.decaf', '>=')) {
+			//          echo "$version_string can be migrated from";
+			return true;
+		} elseif (! $version_string) {
+			//          echo "no version string provided: $version_string";
+			// no version string provided... this must be pre 4.3
+			return false;// changed mind. dont want people thinking they should migrate yet because they cant
+		} else {
+			//          echo "$version_string doesnt apply";
+			return false;
+		}
+	}
 
 
 
-    /**
-     * @return bool
-     */
-    public function schema_changes_before_migration()
-    {
-        require_once(EE_HELPERS . 'EEH_Activation.helper.php');
-        $now_in_mysql = current_time('mysql', true);
-        $table_name = 'esp_answer';
-        $sql = " ANS_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+	/**
+	 * @return bool
+	 */
+	public function schema_changes_before_migration()
+	{
+		require_once(EE_HELPERS . 'EEH_Activation.helper.php');
+		$now_in_mysql = current_time('mysql', true);
+		$table_name = 'esp_answer';
+		$sql = " ANS_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 					REG_ID int(10) unsigned NOT NULL,
 					QST_ID int(10) unsigned NOT NULL,
 					ANS_value text NOT NULL,
 					PRIMARY KEY  (ANS_ID),
 					KEY REG_ID (REG_ID),
 					KEY QST_ID (QST_ID)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_attendee_meta';
-        $this->_get_table_manager()->dropIndexIfSizeNot($table_name, 'ATT_email');
-        $sql = "ATTM_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_attendee_meta';
+		$this->_get_table_manager()->dropIndexIfSizeNot($table_name, 'ATT_email');
+		$sql = "ATTM_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				ATT_ID bigint(20) unsigned NOT NULL,
 				ATT_fname varchar(45) NOT NULL,
 				ATT_lname varchar(45) NOT NULL,
@@ -112,9 +112,9 @@ 
 				KEY ATT_email (ATT_email(191)),
 				KEY ATT_lname (ATT_lname),
 				KEY ATT_fname (ATT_fname)";
-        $this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB ');
-        $table_name = 'esp_checkin';
-        $sql = "CHK_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB ');
+		$table_name = 'esp_checkin';
+		$sql = "CHK_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				REG_ID int(10) unsigned NOT NULL,
 				DTT_ID int(10) unsigned NOT NULL,
 				CHK_in tinyint(1) unsigned NOT NULL DEFAULT 1,
@@ -122,9 +122,9 @@ 
 				PRIMARY KEY  (CHK_ID),
 				KEY REG_ID (REG_ID),
 				KEY DTT_ID (DTT_ID)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_country';
-        $sql = "CNT_ISO varchar(2) NOT NULL,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_country';
+		$sql = "CNT_ISO varchar(2) NOT NULL,
 				CNT_ISO3 varchar(3) NOT NULL,
 				RGN_ID tinyint(3) unsigned DEFAULT NULL,
 				CNT_name varchar(45) NOT NULL,
@@ -140,29 +140,29 @@ 
 				CNT_is_EU tinyint(1) DEFAULT '0',
 				CNT_active tinyint(1) DEFAULT '0',
 				PRIMARY KEY  (CNT_ISO)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_currency';
-        $sql = "CUR_code varchar(6) NOT NULL,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_currency';
+		$sql = "CUR_code varchar(6) NOT NULL,
 				CUR_single varchar(45) DEFAULT 'dollar',
 				CUR_plural varchar(45) DEFAULT 'dollars',
 				CUR_sign varchar(45) DEFAULT '$',
 				CUR_dec_plc varchar(1) NOT NULL DEFAULT '2',
 				CUR_active tinyint(1) DEFAULT '0',
 				PRIMARY KEY  (CUR_code)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        // note: although this table is no longer in use,
-        // it hasn't been removed because then queries to the model will have errors.
-        // but you should expect this table and its corresponding model to be removed in
-        // the next few months
-        $table_name = 'esp_currency_payment_method';
-        $sql = "CPM_ID int(11) NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		// note: although this table is no longer in use,
+		// it hasn't been removed because then queries to the model will have errors.
+		// but you should expect this table and its corresponding model to be removed in
+		// the next few months
+		$table_name = 'esp_currency_payment_method';
+		$sql = "CPM_ID int(11) NOT NULL AUTO_INCREMENT,
 				CUR_code varchar(6) NOT NULL,
 				PMD_ID int(11) NOT NULL,
 				PRIMARY KEY  (CPM_ID),
 				KEY PMD_ID (PMD_ID)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB ');
-        $table_name = 'esp_datetime';
-        $sql = "DTT_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB ');
+		$table_name = 'esp_datetime';
+		$sql = "DTT_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				EVT_ID bigint(20) unsigned NOT NULL,
 				DTT_name varchar(255) NOT NULL DEFAULT '',
 				DTT_description text NOT NULL,
@@ -179,25 +179,25 @@ 
 				KEY DTT_EVT_start (DTT_EVT_start),
 				KEY EVT_ID (EVT_ID),
 				KEY DTT_is_primary (DTT_is_primary)";
-        $this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = "esp_datetime_ticket";
-        $sql = "DTK_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = "esp_datetime_ticket";
+		$sql = "DTK_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				DTT_ID int(10) unsigned NOT NULL,
 				TKT_ID int(10) unsigned NOT NULL,
 				PRIMARY KEY  (DTK_ID),
 				KEY DTT_ID (DTT_ID),
 				KEY TKT_ID (TKT_ID)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_event_message_template';
-        $sql = "EMT_ID bigint(20) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_event_message_template';
+		$sql = "EMT_ID bigint(20) unsigned NOT NULL AUTO_INCREMENT,
 				EVT_ID bigint(20) unsigned NOT NULL DEFAULT 0,
 				GRP_ID int(10) unsigned NOT NULL DEFAULT 0,
 				PRIMARY KEY  (EMT_ID),
 				KEY EVT_ID (EVT_ID),
 				KEY GRP_ID (GRP_ID)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_event_meta';
-        $sql = "EVTM_ID int(10) NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_event_meta';
+		$sql = "EVTM_ID int(10) NOT NULL AUTO_INCREMENT,
 				EVT_ID bigint(20) unsigned NOT NULL,
 				EVT_display_desc tinyint(1) unsigned NOT NULL DEFAULT 1,
 				EVT_display_ticket_selector tinyint(1) unsigned NOT NULL DEFAULT 1,
@@ -212,34 +212,34 @@ 
 				EVT_donations tinyint(1) NULL,
 				PRIMARY KEY  (EVTM_ID),
 				KEY EVT_ID (EVT_ID)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_event_question_group';
-        $sql = "EQG_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_event_question_group';
+		$sql = "EQG_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				EVT_ID bigint(20) unsigned NOT NULL,
 				QSG_ID int(10) unsigned NOT NULL,
 				EQG_primary tinyint(1) unsigned NOT NULL DEFAULT 0,
 				PRIMARY KEY  (EQG_ID),
 				KEY EVT_ID (EVT_ID),
 				KEY QSG_ID (QSG_ID)";
-        $this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_event_venue';
-        $sql = "EVV_ID int(11) NOT NULL AUTO_INCREMENT,
+		$this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_event_venue';
+		$sql = "EVV_ID int(11) NOT NULL AUTO_INCREMENT,
 				EVT_ID bigint(20) unsigned NOT NULL,
 				VNU_ID bigint(20) unsigned NOT NULL,
 				EVV_primary tinyint(1) unsigned NOT NULL DEFAULT 0,
 				PRIMARY KEY  (EVV_ID)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_extra_meta';
-        $sql = "EXM_ID int(11) NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_extra_meta';
+		$sql = "EXM_ID int(11) NOT NULL AUTO_INCREMENT,
 				OBJ_ID int(11) DEFAULT NULL,
 				EXM_type varchar(45) DEFAULT NULL,
 				EXM_key varchar(45) DEFAULT NULL,
 				EXM_value text,
 				PRIMARY KEY  (EXM_ID),
 				KEY EXM_type (EXM_type,OBJ_ID,EXM_key)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_extra_join';
-        $sql = "EXJ_ID int(11) NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_extra_join';
+		$sql = "EXJ_ID int(11) NOT NULL AUTO_INCREMENT,
 				EXJ_first_model_id varchar(6) NOT NULL,
 				EXJ_first_model_name varchar(20) NOT NULL,
 				EXJ_second_model_id varchar(6) NOT NULL,
@@ -247,9 +247,9 @@ 
 				PRIMARY KEY  (EXJ_ID),
 				KEY first_model (EXJ_first_model_name,EXJ_first_model_id),
 				KEY second_model (EXJ_second_model_name,EXJ_second_model_id)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB ');
-        $table_name = 'esp_line_item';
-        $sql = "LIN_ID int(11) NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB ');
+		$table_name = 'esp_line_item';
+		$sql = "LIN_ID int(11) NOT NULL AUTO_INCREMENT,
 				LIN_code varchar(245) NOT NULL DEFAULT '',
 				TXN_ID int(11) DEFAULT NULL,
 				LIN_name varchar(245) NOT NULL DEFAULT '',
@@ -270,11 +270,11 @@ 
 				KEY txn_type_timestamp (TXN_ID,LIN_type,LIN_timestamp),
 				KEY txn_obj_id_obj_type (TXN_ID,OBJ_ID,OBJ_type),
 				KEY obj_id_obj_type (OBJ_ID,OBJ_type)";
-        $this->_get_table_manager()->dropIndex('esp_line_item', 'TXN_ID');
-        $this->_get_table_manager()->dropIndex('esp_line_item', 'LIN_code');
-        $this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_log';
-        $sql = "LOG_ID int(11) NOT NULL AUTO_INCREMENT,
+		$this->_get_table_manager()->dropIndex('esp_line_item', 'TXN_ID');
+		$this->_get_table_manager()->dropIndex('esp_line_item', 'LIN_code');
+		$this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_log';
+		$sql = "LOG_ID int(11) NOT NULL AUTO_INCREMENT,
 				LOG_time datetime DEFAULT NULL,
 				OBJ_ID varchar(45) DEFAULT NULL,
 				OBJ_type varchar(45) DEFAULT NULL,
@@ -285,12 +285,12 @@ 
 				KEY LOG_time (LOG_time),
 				KEY OBJ (OBJ_type,OBJ_ID),
 				KEY LOG_type (LOG_type)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_message';
-        $this->_get_table_manager()->dropIndexIfSizeNot($table_name, 'MSG_to');
-        $this->_get_table_manager()->dropIndexIfSizeNot($table_name, 'MSG_from');
-        $this->_get_table_manager()->dropIndexIfSizeNot($table_name, 'MSG_subject');
-        $sql = "MSG_ID bigint(20) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_message';
+		$this->_get_table_manager()->dropIndexIfSizeNot($table_name, 'MSG_to');
+		$this->_get_table_manager()->dropIndexIfSizeNot($table_name, 'MSG_from');
+		$this->_get_table_manager()->dropIndexIfSizeNot($table_name, 'MSG_subject');
+		$sql = "MSG_ID bigint(20) unsigned NOT NULL AUTO_INCREMENT,
 				GRP_ID int(10) unsigned NULL,
 				MSG_token varchar(255) NULL,
 				TXN_ID int(10) unsigned NULL,
@@ -322,18 +322,18 @@ 
 				KEY STS_ID (STS_ID),
 				KEY MSG_created (MSG_created),
 				KEY MSG_modified (MSG_modified)";
-        $this->_table_is_new_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_message_template';
-        $sql = "MTP_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_is_new_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_message_template';
+		$sql = "MTP_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				GRP_ID int(10) unsigned NOT NULL,
 				MTP_context varchar(50) NOT NULL,
 				MTP_template_field varchar(30) NOT NULL,
 				MTP_content text NOT NULL,
 				PRIMARY KEY  (MTP_ID),
 				KEY GRP_ID (GRP_ID)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_message_template_group';
-        $sql = "GRP_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_message_template_group';
+		$sql = "GRP_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				MTP_user_id int(10) NOT NULL DEFAULT '1',
 				MTP_name varchar(245) NOT NULL DEFAULT '',
 				MTP_description varchar(245) NOT NULL DEFAULT '',
@@ -345,9 +345,9 @@ 
 				MTP_is_active tinyint(1) NOT NULL DEFAULT '1',
 				PRIMARY KEY  (GRP_ID),
 				KEY MTP_user_id (MTP_user_id)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_payment';
-        $sql = "PAY_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_payment';
+		$sql = "PAY_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				TXN_ID int(10) unsigned DEFAULT NULL,
 				STS_ID varchar(3) DEFAULT NULL,
 				PAY_timestamp datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
@@ -364,9 +364,9 @@ 
 				PRIMARY KEY  (PAY_ID),
 				KEY PAY_timestamp (PAY_timestamp),
 				KEY TXN_ID (TXN_ID)";
-        $this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB ');
-        $table_name = 'esp_payment_method';
-        $sql = "PMD_ID int(11) NOT NULL AUTO_INCREMENT,
+		$this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB ');
+		$table_name = 'esp_payment_method';
+		$sql = "PMD_ID int(11) NOT NULL AUTO_INCREMENT,
 				PMD_type varchar(124) DEFAULT NULL,
 				PMD_name varchar(255) DEFAULT NULL,
 				PMD_desc text,
@@ -382,24 +382,24 @@ 
 				PRIMARY KEY  (PMD_ID),
 				UNIQUE KEY PMD_slug_UNIQUE (PMD_slug),
 				KEY PMD_type (PMD_type)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB ');
-        $table_name = "esp_ticket_price";
-        $sql = "TKP_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB ');
+		$table_name = "esp_ticket_price";
+		$sql = "TKP_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				TKT_ID int(10) unsigned NOT NULL,
 				PRC_ID int(10) unsigned NOT NULL,
 				PRIMARY KEY  (TKP_ID),
 				KEY TKT_ID (TKT_ID),
 				KEY PRC_ID (PRC_ID)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = "esp_ticket_template";
-        $sql = "TTM_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = "esp_ticket_template";
+		$sql = "TTM_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				TTM_name varchar(45) NOT NULL,
 				TTM_description text,
 				TTM_file varchar(45),
 				PRIMARY KEY  (TTM_ID)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_question';
-        $sql = 'QST_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_question';
+		$sql = 'QST_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				QST_display_text text NOT NULL,
 				QST_admin_label varchar(255) NOT NULL,
 				QST_system varchar(25) DEFAULT NULL,
@@ -413,18 +413,18 @@ 
 				QST_deleted tinyint(2) unsigned NOT NULL DEFAULT 0,
 				PRIMARY KEY  (QST_ID),
 				KEY QST_order (QST_order)';
-        $this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_question_group_question';
-        $sql = "QGQ_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_question_group_question';
+		$sql = "QGQ_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				QSG_ID int(10) unsigned NOT NULL,
 				QST_ID int(10) unsigned NOT NULL,
 				QGQ_order int(10) unsigned NOT NULL DEFAULT 0,
 				PRIMARY KEY  (QGQ_ID),
 				KEY QST_ID (QST_ID),
 				KEY QSG_ID_order (QSG_ID,QGQ_order)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_question_option';
-        $sql = "QSO_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_question_option';
+		$sql = "QSO_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				QSO_value varchar(255) NOT NULL,
 				QSO_desc text NOT NULL,
 				QST_ID int(10) unsigned NOT NULL,
@@ -434,9 +434,9 @@ 
 				PRIMARY KEY  (QSO_ID),
 				KEY QST_ID (QST_ID),
 				KEY QSO_order (QSO_order)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_registration';
-        $sql = "REG_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_registration';
+		$sql = "REG_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				EVT_ID bigint(20) unsigned NOT NULL,
 				ATT_ID bigint(20) unsigned NOT NULL,
 				TXN_ID int(10) unsigned NOT NULL,
@@ -460,18 +460,18 @@ 
 				KEY TKT_ID (TKT_ID),
 				KEY EVT_ID (EVT_ID),
 				KEY STS_ID (STS_ID)";
-        $this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB ');
-        $table_name = 'esp_registration_payment';
-        $sql = "RPY_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB ');
+		$table_name = 'esp_registration_payment';
+		$sql = "RPY_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 					  REG_ID int(10) unsigned NOT NULL,
 					  PAY_ID int(10) unsigned NULL,
 					  RPY_amount decimal(12,3) NOT NULL DEFAULT '0.00',
 					  PRIMARY KEY  (RPY_ID),
 					  KEY REG_ID (REG_ID),
 					  KEY PAY_ID (PAY_ID)";
-        $this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB ');
-        $table_name = 'esp_state';
-        $sql = "STA_ID smallint(5) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB ');
+		$table_name = 'esp_state';
+		$sql = "STA_ID smallint(5) unsigned NOT NULL AUTO_INCREMENT,
 				CNT_ISO varchar(2) NOT NULL,
 				STA_abbrev varchar(24) NOT NULL,
 				STA_name varchar(100) NOT NULL,
@@ -479,9 +479,9 @@ 
 				PRIMARY KEY  (STA_ID),
 				KEY STA_abbrev (STA_abbrev),
 				KEY CNT_ISO (CNT_ISO)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_status';
-        $sql = "STS_ID varchar(3) NOT NULL,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_status';
+		$sql = "STS_ID varchar(3) NOT NULL,
 				STS_code varchar(45) NOT NULL,
 				STS_type varchar(45) NOT NULL,
 				STS_can_edit tinyint(1) NOT NULL DEFAULT 0,
@@ -489,9 +489,9 @@ 
 				STS_open tinyint(1) NOT NULL DEFAULT 1,
 				UNIQUE KEY STS_ID_UNIQUE (STS_ID),
 				KEY STS_type (STS_type)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_transaction';
-        $sql = "TXN_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_transaction';
+		$sql = "TXN_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				TXN_timestamp datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
 				TXN_total decimal(12,3) DEFAULT '0.00',
 				TXN_paid decimal(12,3) NOT NULL DEFAULT '0.00',
@@ -503,9 +503,9 @@ 
 				PRIMARY KEY  (TXN_ID),
 				KEY TXN_timestamp (TXN_timestamp),
 				KEY STS_ID (STS_ID)";
-        $this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_venue_meta';
-        $sql = "VNUM_ID int(11) NOT NULL AUTO_INCREMENT,
+		$this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_venue_meta';
+		$sql = "VNUM_ID int(11) NOT NULL AUTO_INCREMENT,
 			VNU_ID bigint(20) unsigned NOT NULL DEFAULT 0,
 			VNU_address varchar(255) DEFAULT NULL,
 			VNU_address2 varchar(255) DEFAULT NULL,
@@ -524,10 +524,10 @@ 
 			KEY VNU_ID (VNU_ID),
 			KEY STA_ID (STA_ID),
 			KEY CNT_ISO (CNT_ISO)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        // modified tables
-        $table_name = "esp_price";
-        $sql = "PRC_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		// modified tables
+		$table_name = "esp_price";
+		$sql = "PRC_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				PRT_ID tinyint(3) unsigned NOT NULL,
 				PRC_amount decimal(12,3) NOT NULL DEFAULT '0.00',
 				PRC_name varchar(245) NOT NULL,
@@ -540,9 +540,9 @@ 
 				PRC_parent int(10) unsigned DEFAULT 0,
 				PRIMARY KEY  (PRC_ID),
 				KEY PRT_ID (PRT_ID)";
-        $this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = "esp_price_type";
-        $sql = "PRT_ID tinyint(3) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = "esp_price_type";
+		$sql = "PRT_ID tinyint(3) unsigned NOT NULL AUTO_INCREMENT,
 				PRT_name varchar(45) NOT NULL,
 				PBT_ID tinyint(3) unsigned NOT NULL DEFAULT '1',
 				PRT_is_percent tinyint(1) NOT NULL DEFAULT '0',
@@ -551,9 +551,9 @@ 
 				PRT_deleted tinyint(1) NOT NULL DEFAULT '0',
 				UNIQUE KEY PRT_name_UNIQUE (PRT_name),
 				PRIMARY KEY  (PRT_ID)";
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB ');
-        $table_name = "esp_ticket";
-        $sql = "TKT_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB ');
+		$table_name = "esp_ticket";
+		$sql = "TKT_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				TTM_ID int(10) unsigned NOT NULL,
 				TKT_name varchar(245) NOT NULL DEFAULT '',
 				TKT_description text NOT NULL,
@@ -576,9 +576,9 @@ 
 				TKT_deleted tinyint(1) NOT NULL DEFAULT '0',
 				PRIMARY KEY  (TKT_ID),
 				KEY TKT_start_date (TKT_start_date)";
-        $this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
-        $table_name = 'esp_question_group';
-        $sql = 'QSG_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
+		$this->_table_is_changed_in_this_version($table_name, $sql, 'ENGINE=InnoDB');
+		$table_name = 'esp_question_group';
+		$sql = 'QSG_ID int(10) unsigned NOT NULL AUTO_INCREMENT,
 				QSG_name varchar(255) NOT NULL,
 				QSG_identifier varchar(100) NOT NULL,
 				QSG_desc text NULL,
@@ -591,165 +591,165 @@ 
 				PRIMARY KEY  (QSG_ID),
 				UNIQUE KEY QSG_identifier_UNIQUE (QSG_identifier),
 				KEY QSG_order (QSG_order)';
-        $this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
-        $this->insert_default_data();
-        return true;
-    }
+		$this->_table_has_not_changed_since_previous($table_name, $sql, 'ENGINE=InnoDB');
+		$this->insert_default_data();
+		return true;
+	}
 
-    /**
-     * Inserts default data after parent was called.
-     * @since 4.10.0.p
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public function insert_default_data()
-    {
-        /** @var EE_DMS_Core_4_1_0 $script_4_1_defaults */
-        $script_4_1_defaults = EE_Registry::instance()->load_dms('Core_4_1_0');
-        // (because many need to convert old string states to foreign keys into the states table)
-        $script_4_1_defaults->insert_default_states();
-        $script_4_1_defaults->insert_default_countries();
-        /** @var EE_DMS_Core_4_5_0 $script_4_5_defaults */
-        $script_4_5_defaults = EE_Registry::instance()->load_dms('Core_4_5_0');
-        $script_4_5_defaults->insert_default_price_types();
-        $script_4_5_defaults->insert_default_prices();
-        $script_4_5_defaults->insert_default_tickets();
-        /** @var EE_DMS_Core_4_6_0 $script_4_6_defaults */
-        $script_4_6_defaults = EE_Registry::instance()->load_dms('Core_4_6_0');
-        $script_4_6_defaults->add_default_admin_only_payments();
-        $script_4_6_defaults->insert_default_currencies();
-        /** @var EE_DMS_Core_4_8_0 $script_4_8_defaults */
-        $script_4_8_defaults = EE_Registry::instance()->load_dms('Core_4_8_0');
-        $script_4_8_defaults->verify_new_countries();
-        $script_4_8_defaults->verify_new_currencies();
-        $this->verify_db_collations();
-        $this->verify_db_collations_again();
-    }
+	/**
+	 * Inserts default data after parent was called.
+	 * @since 4.10.0.p
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public function insert_default_data()
+	{
+		/** @var EE_DMS_Core_4_1_0 $script_4_1_defaults */
+		$script_4_1_defaults = EE_Registry::instance()->load_dms('Core_4_1_0');
+		// (because many need to convert old string states to foreign keys into the states table)
+		$script_4_1_defaults->insert_default_states();
+		$script_4_1_defaults->insert_default_countries();
+		/** @var EE_DMS_Core_4_5_0 $script_4_5_defaults */
+		$script_4_5_defaults = EE_Registry::instance()->load_dms('Core_4_5_0');
+		$script_4_5_defaults->insert_default_price_types();
+		$script_4_5_defaults->insert_default_prices();
+		$script_4_5_defaults->insert_default_tickets();
+		/** @var EE_DMS_Core_4_6_0 $script_4_6_defaults */
+		$script_4_6_defaults = EE_Registry::instance()->load_dms('Core_4_6_0');
+		$script_4_6_defaults->add_default_admin_only_payments();
+		$script_4_6_defaults->insert_default_currencies();
+		/** @var EE_DMS_Core_4_8_0 $script_4_8_defaults */
+		$script_4_8_defaults = EE_Registry::instance()->load_dms('Core_4_8_0');
+		$script_4_8_defaults->verify_new_countries();
+		$script_4_8_defaults->verify_new_currencies();
+		$this->verify_db_collations();
+		$this->verify_db_collations_again();
+	}
 
 
 
-    /**
-     * @return boolean
-     */
-    public function schema_changes_after_migration()
-    {
-        return true;
-    }
+	/**
+	 * @return boolean
+	 */
+	public function schema_changes_after_migration()
+	{
+		return true;
+	}
 
 
 
-    public function migration_page_hooks()
-    {
-    }
+	public function migration_page_hooks()
+	{
+	}
 
 
 
-    /**
-     * Verify all EE4 models' tables use utf8mb4 collation
-     *
-     * @return void
-     */
-    public function verify_db_collations()
-    {
-        global $wpdb;
-        // double-check we haven't already done it or that that the DB doesn't support utf8mb4
-        if (
-            'utf8mb4' !== $wpdb->charset
-            || get_option('ee_verified_db_collations', false)
-        ) {
-            return;
-        }
-        // grab tables from each model
-        $tables_to_check = array();
-        foreach (EE_Registry::instance()->non_abstract_db_models as $model_name) {
-            if (method_exists($model_name, 'instance')) {
-                $model_obj = call_user_func(array($model_name, 'instance'));
-                if ($model_obj instanceof EEM_Base) {
-                    foreach ($model_obj->get_tables() as $table) {
-                        if (
-                            strpos($table->get_table_name(), 'esp_')
-                            && (is_main_site()// for main tables, verify global tables
-                                || ! $table->is_global()// if not the main site, then only verify non-global tables (avoid doubling up)
-                            )
-                            && function_exists('maybe_convert_table_to_utf8mb4')
-                        ) {
-                            $tables_to_check[] = $table->get_table_name();
-                        }
-                    }
-                }
-            }
-        }
-        // and let's just be sure these addons' tables get migrated too. They already get handled if their addons are active
-        // when this code is run, but not otherwise. Once we record what tables EE added, we'll be able to use that instead
-        // of hard-coding this
-        $addon_tables = array(
-            // mailchimp
-            'esp_event_mailchimp_list_group',
-            'esp_event_question_mailchimp_field',
-            // multisite
-            'esp_blog_meta',
-            // people
-            'esp_people_to_post',
-            // promotions
-            'esp_promotion',
-            'esp_promotion_object',
-        );
-        foreach ($addon_tables as $table_name) {
-                $tables_to_check[] = $table_name;
-        }
-        $this->_verify_db_collations_for_tables(array_unique($tables_to_check));
-        // ok and now let's remember this was done (without needing to check the db schemas all over again)
-        add_option('ee_verified_db_collations', true, null, 'no');
-        // seeing how this ran with the fix from 10435, no need to check again
-        add_option('ee_verified_db_collations_again', true, null, 'no');
-    }
+	/**
+	 * Verify all EE4 models' tables use utf8mb4 collation
+	 *
+	 * @return void
+	 */
+	public function verify_db_collations()
+	{
+		global $wpdb;
+		// double-check we haven't already done it or that that the DB doesn't support utf8mb4
+		if (
+			'utf8mb4' !== $wpdb->charset
+			|| get_option('ee_verified_db_collations', false)
+		) {
+			return;
+		}
+		// grab tables from each model
+		$tables_to_check = array();
+		foreach (EE_Registry::instance()->non_abstract_db_models as $model_name) {
+			if (method_exists($model_name, 'instance')) {
+				$model_obj = call_user_func(array($model_name, 'instance'));
+				if ($model_obj instanceof EEM_Base) {
+					foreach ($model_obj->get_tables() as $table) {
+						if (
+							strpos($table->get_table_name(), 'esp_')
+							&& (is_main_site()// for main tables, verify global tables
+								|| ! $table->is_global()// if not the main site, then only verify non-global tables (avoid doubling up)
+							)
+							&& function_exists('maybe_convert_table_to_utf8mb4')
+						) {
+							$tables_to_check[] = $table->get_table_name();
+						}
+					}
+				}
+			}
+		}
+		// and let's just be sure these addons' tables get migrated too. They already get handled if their addons are active
+		// when this code is run, but not otherwise. Once we record what tables EE added, we'll be able to use that instead
+		// of hard-coding this
+		$addon_tables = array(
+			// mailchimp
+			'esp_event_mailchimp_list_group',
+			'esp_event_question_mailchimp_field',
+			// multisite
+			'esp_blog_meta',
+			// people
+			'esp_people_to_post',
+			// promotions
+			'esp_promotion',
+			'esp_promotion_object',
+		);
+		foreach ($addon_tables as $table_name) {
+				$tables_to_check[] = $table_name;
+		}
+		$this->_verify_db_collations_for_tables(array_unique($tables_to_check));
+		// ok and now let's remember this was done (without needing to check the db schemas all over again)
+		add_option('ee_verified_db_collations', true, null, 'no');
+		// seeing how this ran with the fix from 10435, no need to check again
+		add_option('ee_verified_db_collations_again', true, null, 'no');
+	}
 
 
 
-    /**
-     * Verifies DB collations because a bug was discovered on https://events.codebasehq.com/projects/event-espresso/tickets/10435
-     * which meant some DB collations might not have been updated
-     * @return void
-     */
-    public function verify_db_collations_again()
-    {
-        global $wpdb;
-        // double-check we haven't already done this or that the DB doesn't support it
-        // compare to how WordPress' upgrade_430() function does this check
-        if (
-            'utf8mb4' !== $wpdb->charset
-            || get_option('ee_verified_db_collations_again', false)
-        ) {
-            return;
-        }
-        $tables_to_check = array(
-            'esp_attendee_meta',
-            'esp_message'
-        );
-        $this->_verify_db_collations_for_tables(array_unique($tables_to_check));
-        add_option('ee_verified_db_collations_again', true, null, 'no');
-    }
+	/**
+	 * Verifies DB collations because a bug was discovered on https://events.codebasehq.com/projects/event-espresso/tickets/10435
+	 * which meant some DB collations might not have been updated
+	 * @return void
+	 */
+	public function verify_db_collations_again()
+	{
+		global $wpdb;
+		// double-check we haven't already done this or that the DB doesn't support it
+		// compare to how WordPress' upgrade_430() function does this check
+		if (
+			'utf8mb4' !== $wpdb->charset
+			|| get_option('ee_verified_db_collations_again', false)
+		) {
+			return;
+		}
+		$tables_to_check = array(
+			'esp_attendee_meta',
+			'esp_message'
+		);
+		$this->_verify_db_collations_for_tables(array_unique($tables_to_check));
+		add_option('ee_verified_db_collations_again', true, null, 'no');
+	}
 
 
 
-    /**
-     * Runs maybe_convert_table_to_utf8mb4 on the specified tables
-     * @param $tables_to_check
-     * @return boolean true if logic ran, false if it didn't
-     */
-    protected function _verify_db_collations_for_tables($tables_to_check)
-    {
-        foreach ($tables_to_check as $table_name) {
-            $table_name = $this->_table_analysis->ensureTableNameHasPrefix($table_name);
-            if (
-                ! apply_filters('FHEE__EE_DMS_Core_4_9_0__verify_db_collations__check_overridden', false, $table_name)
-                && $this->_get_table_analysis()->tableExists($table_name)
-            ) {
-                maybe_convert_table_to_utf8mb4($table_name);
-            }
-        }
-    }
+	/**
+	 * Runs maybe_convert_table_to_utf8mb4 on the specified tables
+	 * @param $tables_to_check
+	 * @return boolean true if logic ran, false if it didn't
+	 */
+	protected function _verify_db_collations_for_tables($tables_to_check)
+	{
+		foreach ($tables_to_check as $table_name) {
+			$table_name = $this->_table_analysis->ensureTableNameHasPrefix($table_name);
+			if (
+				! apply_filters('FHEE__EE_DMS_Core_4_9_0__verify_db_collations__check_overridden', false, $table_name)
+				&& $this->_get_table_analysis()->tableExists($table_name)
+			) {
+				maybe_convert_table_to_utf8mb4($table_name);
+			}
+		}
+	}
 }

Spacing +5 added lines, -5 removed lines

@@ -9,12 +9,12 @@ 
 // unfortunately, this needs to be done upon INCLUSION of this file,
 // instead of construction, because it only gets constructed on first page load
 // (all other times it gets resurrected from a wordpress option)
-$stages = glob(EE_CORE . 'data_migration_scripts/4_9_0_stages/*');
+$stages = glob(EE_CORE.'data_migration_scripts/4_9_0_stages/*');
 $class_to_filepath = array();
 foreach ($stages as $filepath) {
     $matches = array();
     preg_match('~4_9_0_stages/(.*).dmsstage.php~', $filepath, $matches);
-    $class_to_filepath[ $matches[1] ] = $filepath;
+    $class_to_filepath[$matches[1]] = $filepath;
 }
 // give addons a chance to autoload their stages too
 $class_to_filepath = apply_filters('FHEE__EE_DMS_4_9_0__autoloaded_stages', $class_to_filepath);
@@ -65,10 +65,10 @@ 
         if (version_compare($version_string, '4.9.0.decaf', '<') && version_compare($version_string, '4.8.0.decaf', '>=')) {
             //          echo "$version_string can be migrated from";
             return true;
-        } elseif (! $version_string) {
+        } elseif ( ! $version_string) {
             //          echo "no version string provided: $version_string";
             // no version string provided... this must be pre 4.3
-            return false;// changed mind. dont want people thinking they should migrate yet because they cant
+            return false; // changed mind. dont want people thinking they should migrate yet because they cant
         } else {
             //          echo "$version_string doesnt apply";
             return false;
@@ -82,7 +82,7 @@ 
      */
     public function schema_changes_before_migration()
     {
-        require_once(EE_HELPERS . 'EEH_Activation.helper.php');
+        require_once(EE_HELPERS.'EEH_Activation.helper.php');
         $now_in_mysql = current_time('mysql', true);
         $table_name = 'esp_answer';
         $sql = " ANS_ID int(10) unsigned NOT NULL AUTO_INCREMENT,

core/data_migration_scripts/4_6_0_stages/EE_DMS_4_6_0_invoice_settings.dmsstage.php

Spacing +2 added lines, -2 removed lines

@@ -66,8 +66,8 @@
     {
 
         $templates_relative_path = 'modules/gateways/Invoice/lib/templates/';
-        $overridden_invoice_body = EEH_Template::locate_template($templates_relative_path . 'invoice_body.template.php', null, false, false, true);
-        $overridden_receipt_body = EEH_Template::locate_template($templates_relative_path . 'receipt_body.template.php', null, false, false, true);
+        $overridden_invoice_body = EEH_Template::locate_template($templates_relative_path.'invoice_body.template.php', null, false, false, true);
+        $overridden_receipt_body = EEH_Template::locate_template($templates_relative_path.'receipt_body.template.php', null, false, false, true);
         if ($overridden_invoice_body || $overridden_receipt_body) {
             new PersistentAdminNotice(
                 'invoice_overriding_templates',

Indentation +47 added lines, -47 removed lines

@@ -28,59 +28,59 @@
 class EE_DMS_4_6_0_invoice_settings extends EE_Data_Migration_Script_Stage
 {
 
-    /**
-     * Just initializes the status of the migration
-     */
-    public function __construct()
-    {
-        $this->_pretty_name = esc_html__('Update Invoice Settings', 'event_espresso');
-        parent::__construct();
-    }
+	/**
+	 * Just initializes the status of the migration
+	 */
+	public function __construct()
+	{
+		$this->_pretty_name = esc_html__('Update Invoice Settings', 'event_espresso');
+		parent::__construct();
+	}
 
 
 
-    /**
-     * _count_records_to_migrate
-     * Counts the records to migrate; the public version may cache it
-     *
-     * @access protected
-     * @return int
-     */
-    protected function _count_records_to_migrate()
-    {
-        return 1;
-    }
+	/**
+	 * _count_records_to_migrate
+	 * Counts the records to migrate; the public version may cache it
+	 *
+	 * @access protected
+	 * @return int
+	 */
+	protected function _count_records_to_migrate()
+	{
+		return 1;
+	}
 
 
 
-    /**
-     *    _migration_step
-     *
-     * @access protected
-     * @param int $num_items
-     * @throws EE_Error
-     * @return int number of items ACTUALLY migrated
-     * @throws InvalidDataTypeException
-     */
-    protected function _migration_step($num_items = 1)
-    {
+	/**
+	 *    _migration_step
+	 *
+	 * @access protected
+	 * @param int $num_items
+	 * @throws EE_Error
+	 * @return int number of items ACTUALLY migrated
+	 * @throws InvalidDataTypeException
+	 */
+	protected function _migration_step($num_items = 1)
+	{
 
-        $templates_relative_path = 'modules/gateways/Invoice/lib/templates/';
-        $overridden_invoice_body = EEH_Template::locate_template($templates_relative_path . 'invoice_body.template.php', null, false, false, true);
-        $overridden_receipt_body = EEH_Template::locate_template($templates_relative_path . 'receipt_body.template.php', null, false, false, true);
-        if ($overridden_invoice_body || $overridden_receipt_body) {
-            new PersistentAdminNotice(
-                'invoice_overriding_templates',
-                esc_html__(
-                    'Note: in this version of Event Espresso, PDF and HTML Invoices and Receipts are now Messages and can be changed just like any other messages; however we noticed you had previously overridden the old default Invoice/Receipt templates. Because of this, your old Invoice/Receipt templates will continue to be used INSTEAD of the new Invoice/Receipt message equivalents (but this will be removed in an upcoming version). We recommend deleting your old Invoice/Receipt templates and using the new messages system. Then modify the new Invoice and Receipt messages\'s content in Messages -> Invoice and Messages -> Receipt.',
-                    'event_espresso'
-                ),
-                true
-            );
-        }
+		$templates_relative_path = 'modules/gateways/Invoice/lib/templates/';
+		$overridden_invoice_body = EEH_Template::locate_template($templates_relative_path . 'invoice_body.template.php', null, false, false, true);
+		$overridden_receipt_body = EEH_Template::locate_template($templates_relative_path . 'receipt_body.template.php', null, false, false, true);
+		if ($overridden_invoice_body || $overridden_receipt_body) {
+			new PersistentAdminNotice(
+				'invoice_overriding_templates',
+				esc_html__(
+					'Note: in this version of Event Espresso, PDF and HTML Invoices and Receipts are now Messages and can be changed just like any other messages; however we noticed you had previously overridden the old default Invoice/Receipt templates. Because of this, your old Invoice/Receipt templates will continue to be used INSTEAD of the new Invoice/Receipt message equivalents (but this will be removed in an upcoming version). We recommend deleting your old Invoice/Receipt templates and using the new messages system. Then modify the new Invoice and Receipt messages\'s content in Messages -> Invoice and Messages -> Receipt.',
+					'event_espresso'
+				),
+				true
+			);
+		}
 
-        // regardless of whether it worked or not, we ought to continue the migration
-        $this->set_completed();
-        return 1;
-    }
+		// regardless of whether it worked or not, we ought to continue the migration
+		$this->set_completed();
+		return 1;
+	}
 }

core/EE_Load_Textdomain.core.php

Indentation +91 added lines, -91 removed lines

@@ -13,105 +13,105 @@
 class EE_Load_Textdomain extends EE_Base
 {
 
-    /**
-     * holds the current lang in WP
-     *
-     * @var string
-     */
-    private static $locale;
+	/**
+	 * holds the current lang in WP
+	 *
+	 * @var string
+	 */
+	private static $locale;
 
 
-    /**
-     * this takes care of retrieving a matching textdomain for event espresso for the current WPLANG from EE GitHub
-     * repo (if necessary) and then loading it for translations. should only be called in wp plugins_loaded callback
-     *
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public static function load_textdomain()
-    {
-        EE_Load_Textdomain::loadTranslationsForLocale();
-        // now load the textdomain
-        if (!empty(EE_Load_Textdomain::$locale)) {
-            $github_mo_path = EE_LANGUAGES_SAFE_DIR . 'event_espresso-' . EE_Load_Textdomain::$locale . '.mo';
-            if (is_readable($github_mo_path)) {
-                load_plugin_textdomain('event_espresso', false, EE_LANGUAGES_SAFE_LOC);
-                return;
-            }
-            $glotpress_mo_path = EE_LANGUAGES_SAFE_DIR . 'event-espresso-4-' . EE_Load_Textdomain::$locale . '.mo';
-            if (is_readable($glotpress_mo_path)) {
-                load_textdomain('event_espresso', $glotpress_mo_path);
-                return;
-            }
-        }
-        load_plugin_textdomain('event_espresso', false, dirname(EE_PLUGIN_BASENAME) . '/languages/');
-    }
+	/**
+	 * this takes care of retrieving a matching textdomain for event espresso for the current WPLANG from EE GitHub
+	 * repo (if necessary) and then loading it for translations. should only be called in wp plugins_loaded callback
+	 *
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public static function load_textdomain()
+	{
+		EE_Load_Textdomain::loadTranslationsForLocale();
+		// now load the textdomain
+		if (!empty(EE_Load_Textdomain::$locale)) {
+			$github_mo_path = EE_LANGUAGES_SAFE_DIR . 'event_espresso-' . EE_Load_Textdomain::$locale . '.mo';
+			if (is_readable($github_mo_path)) {
+				load_plugin_textdomain('event_espresso', false, EE_LANGUAGES_SAFE_LOC);
+				return;
+			}
+			$glotpress_mo_path = EE_LANGUAGES_SAFE_DIR . 'event-espresso-4-' . EE_Load_Textdomain::$locale . '.mo';
+			if (is_readable($glotpress_mo_path)) {
+				load_textdomain('event_espresso', $glotpress_mo_path);
+				return;
+			}
+		}
+		load_plugin_textdomain('event_espresso', false, dirname(EE_PLUGIN_BASENAME) . '/languages/');
+	}
 
 
-    /**
-     * The purpose of this method is to sideload all of the lang files for EE, this includes the POT file and also the PO/MO files for the given WPLANG locale (if necessary).
-     *
-     * @access private
-     * @static
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    private static function loadTranslationsForLocale()
-    {
-        EE_Load_Textdomain::$locale = get_locale();
-        // can't download a language file if a language isn't set <taps temple>
-        if (empty(EE_Load_Textdomain::$locale)) {
-            return;
-        }
-        $language_check_option_name = 'ee_lang_check_' . EE_Load_Textdomain::$locale . '_' . EVENT_ESPRESSO_VERSION;
-        // check if language files has already been sideloaded
-        if (get_option($language_check_option_name)) {
-            return;
-        }
+	/**
+	 * The purpose of this method is to sideload all of the lang files for EE, this includes the POT file and also the PO/MO files for the given WPLANG locale (if necessary).
+	 *
+	 * @access private
+	 * @static
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	private static function loadTranslationsForLocale()
+	{
+		EE_Load_Textdomain::$locale = get_locale();
+		// can't download a language file if a language isn't set <taps temple>
+		if (empty(EE_Load_Textdomain::$locale)) {
+			return;
+		}
+		$language_check_option_name = 'ee_lang_check_' . EE_Load_Textdomain::$locale . '_' . EVENT_ESPRESSO_VERSION;
+		// check if language files has already been sideloaded
+		if (get_option($language_check_option_name)) {
+			return;
+		}
 
-        $repo_base_URL = 'https://github.com/eventespresso/languages-ee4/blob/master/event_espresso';
+		$repo_base_URL = 'https://github.com/eventespresso/languages-ee4/blob/master/event_espresso';
 
-        // load sideloader and sideload the .POT file as this should always be included.
-        $sideloader_args = array(
-            '_upload_to'     => EE_PLUGIN_DIR_PATH . 'languages/',
-            '_download_from'   => $repo_base_URL . '.pot?raw=true',
-            '_new_file_name' => 'event_espresso.pot',
-        );
-        /** @var EEH_Sideloader $sideloader */
-        $sideloader = EE_Registry::instance()->load_helper('Sideloader', $sideloader_args, false);
-        // sideload the .POT file only for main site of the network, or if not running Multisite.
-        if (is_main_site()) {
-            $sideloader->sideload();
-        }
+		// load sideloader and sideload the .POT file as this should always be included.
+		$sideloader_args = array(
+			'_upload_to'     => EE_PLUGIN_DIR_PATH . 'languages/',
+			'_download_from'   => $repo_base_URL . '.pot?raw=true',
+			'_new_file_name' => 'event_espresso.pot',
+		);
+		/** @var EEH_Sideloader $sideloader */
+		$sideloader = EE_Registry::instance()->load_helper('Sideloader', $sideloader_args, false);
+		// sideload the .POT file only for main site of the network, or if not running Multisite.
+		if (is_main_site()) {
+			$sideloader->sideload();
+		}
 
-        // if locale is "en_US" then lets just get out, since Event Espresso core is already "en_US"
-        if (EE_Load_Textdomain::$locale === 'en_US') {
-            // but set option first else we'll forever be downloading the pot file
-            update_option($language_check_option_name, 1);
-            return;
-        }
-        $repo_locale_URL = $repo_base_URL . '-' . EE_Load_Textdomain::$locale;
-        $file_name_base = 'event_espresso-' . EE_Load_Textdomain::$locale;
+		// if locale is "en_US" then lets just get out, since Event Espresso core is already "en_US"
+		if (EE_Load_Textdomain::$locale === 'en_US') {
+			// but set option first else we'll forever be downloading the pot file
+			update_option($language_check_option_name, 1);
+			return;
+		}
+		$repo_locale_URL = $repo_base_URL . '-' . EE_Load_Textdomain::$locale;
+		$file_name_base = 'event_espresso-' . EE_Load_Textdomain::$locale;
 
-        // made it here so let's get the language files from the github repo, first the .mo file
-        $sideloader->set_download_from("{$repo_locale_URL}.mo?raw=true");
-        $sideloader->set_new_file_name("{$file_name_base}.mo");
-        $sideloader->sideload();
+		// made it here so let's get the language files from the github repo, first the .mo file
+		$sideloader->set_download_from("{$repo_locale_URL}.mo?raw=true");
+		$sideloader->set_new_file_name("{$file_name_base}.mo");
+		$sideloader->sideload();
 
-        // now the .po file:
-        $sideloader->set_download_from("{$repo_locale_URL}.po?raw=true");
-        $sideloader->set_new_file_name("{$file_name_base}.po");
-        $sideloader->sideload();
+		// now the .po file:
+		$sideloader->set_download_from("{$repo_locale_URL}.po?raw=true");
+		$sideloader->set_new_file_name("{$file_name_base}.po");
+		$sideloader->sideload();
 
-        // set option so the above only runs when EE updates.
-        update_option($language_check_option_name, 1);
-    }
+		// set option so the above only runs when EE updates.
+		update_option($language_check_option_name, 1);
+	}
 }

Spacing +9 added lines, -9 removed lines

@@ -36,19 +36,19 @@ 
     {
         EE_Load_Textdomain::loadTranslationsForLocale();
         // now load the textdomain
-        if (!empty(EE_Load_Textdomain::$locale)) {
-            $github_mo_path = EE_LANGUAGES_SAFE_DIR . 'event_espresso-' . EE_Load_Textdomain::$locale . '.mo';
+        if ( ! empty(EE_Load_Textdomain::$locale)) {
+            $github_mo_path = EE_LANGUAGES_SAFE_DIR.'event_espresso-'.EE_Load_Textdomain::$locale.'.mo';
             if (is_readable($github_mo_path)) {
                 load_plugin_textdomain('event_espresso', false, EE_LANGUAGES_SAFE_LOC);
                 return;
             }
-            $glotpress_mo_path = EE_LANGUAGES_SAFE_DIR . 'event-espresso-4-' . EE_Load_Textdomain::$locale . '.mo';
+            $glotpress_mo_path = EE_LANGUAGES_SAFE_DIR.'event-espresso-4-'.EE_Load_Textdomain::$locale.'.mo';
             if (is_readable($glotpress_mo_path)) {
                 load_textdomain('event_espresso', $glotpress_mo_path);
                 return;
             }
         }
-        load_plugin_textdomain('event_espresso', false, dirname(EE_PLUGIN_BASENAME) . '/languages/');
+        load_plugin_textdomain('event_espresso', false, dirname(EE_PLUGIN_BASENAME).'/languages/');
     }
 
 
@@ -71,7 +71,7 @@ 
         if (empty(EE_Load_Textdomain::$locale)) {
             return;
         }
-        $language_check_option_name = 'ee_lang_check_' . EE_Load_Textdomain::$locale . '_' . EVENT_ESPRESSO_VERSION;
+        $language_check_option_name = 'ee_lang_check_'.EE_Load_Textdomain::$locale.'_'.EVENT_ESPRESSO_VERSION;
         // check if language files has already been sideloaded
         if (get_option($language_check_option_name)) {
             return;
@@ -81,8 +81,8 @@ 
 
         // load sideloader and sideload the .POT file as this should always be included.
         $sideloader_args = array(
-            '_upload_to'     => EE_PLUGIN_DIR_PATH . 'languages/',
-            '_download_from'   => $repo_base_URL . '.pot?raw=true',
+            '_upload_to'     => EE_PLUGIN_DIR_PATH.'languages/',
+            '_download_from'   => $repo_base_URL.'.pot?raw=true',
             '_new_file_name' => 'event_espresso.pot',
         );
         /** @var EEH_Sideloader $sideloader */
@@ -98,8 +98,8 @@ 
             update_option($language_check_option_name, 1);
             return;
         }
-        $repo_locale_URL = $repo_base_URL . '-' . EE_Load_Textdomain::$locale;
-        $file_name_base = 'event_espresso-' . EE_Load_Textdomain::$locale;
+        $repo_locale_URL = $repo_base_URL.'-'.EE_Load_Textdomain::$locale;
+        $file_name_base = 'event_espresso-'.EE_Load_Textdomain::$locale;
 
         // made it here so let's get the language files from the github repo, first the .mo file
         $sideloader->set_download_from("{$repo_locale_URL}.mo?raw=true");