eventespresso / event-espresso-core

core/libraries/messages/EE_Messages_Queue.lib.php

Indentation +677 added lines, -677 removed lines

@@ -2,7 +2,7 @@ 
 use \EventEspresso\core\exceptions\SendMessageException;
 
 if (! defined('EVENT_ESPRESSO_VERSION')) {
-    exit('No direct script access allowed');
+	exit('No direct script access allowed');
 }
 
 /**
@@ -18,681 +18,681 @@ 
 {
 
 
-    /**
-     * @type    string  reference for sending action
-     */
-    const action_sending = 'sending';
-
-    /**
-     * @type    string  reference for generation action
-     */
-    const action_generating = 'generation';
-
-
-    /**
-     * @type EE_Message_Repository $_message_repository
-     */
-    protected $_message_repository;
-
-    /**
-     * Sets the limit of how many messages are generated per process.
-     *
-     * @type int
-     */
-    protected $_batch_count;
-
-    /**
-     * Sets the limit of how many messages can be sent per hour.
-     *
-     * @type int
-     */
-    protected $_rate_limit;
-
-    /**
-     * This is an array of cached queue items being stored in this object.
-     * The array keys will be the ID of the EE_Message in the db if saved.  If the EE_Message
-     * is not saved to the db then its key will be an increment of "UNS" (i.e. UNS1, UNS2 etc.)
-     *
-     * @type EE_Message[]
-     */
-    protected $_cached_queue_items;
-
-    /**
-     * Tracks the number of unsaved queue items.
-     *
-     * @type int
-     */
-    protected $_unsaved_count = 0;
-
-    /**
-     * used to record if a do_messenger_hooks has already been called for a message type.  This prevents multiple
-     * hooks getting fired if users have setup their action/filter hooks to prevent duplicate calls.
-     *
-     * @type array
-     */
-    protected $_did_hook = array();
-
-
-    /**
-     * Constructor.
-     * Setup all the initial properties and load a EE_Message_Repository.
-     *
-     * @param \EE_Message_Repository $message_repository
-     */
-    public function __construct(EE_Message_Repository $message_repository)
-    {
-        $this->_batch_count        = apply_filters('FHEE__EE_Messages_Queue___batch_count', 50);
-        $this->_rate_limit         = $this->get_rate_limit();
-        $this->_message_repository = $message_repository;
-    }
-
-
-    /**
-     * Add a EE_Message object to the queue
-     *
-     * @param EE_Message $message
-     * @param array      $data         This will be an array of data to attach to the object in the repository.  If the
-     *                                 object is persisted, this data will be saved on an extra_meta object related to
-     *                                 EE_Message.
-     * @param  bool      $preview      Whether this EE_Message represents a preview or not.
-     * @param  bool      $test_send    This indicates whether to do a test send instead of actual send. A test send will
-     *                                 use the messenger send method but typically is based on preview data.
-     * @return bool          Whether the message was successfully added to the repository or not.
-     */
-    public function add(EE_Message $message, $data = array(), $preview = false, $test_send = false)
-    {
-        $data['preview']   = $preview;
-        $data['test_send'] = $test_send;
-        return $this->_message_repository->add($message, $data);
-    }
-
-
-    /**
-     * Removes EE_Message from _queue that matches the given EE_Message if the pointer is on a matching EE_Message
-     *
-     * @param EE_Message $message The message to detach from the queue
-     * @param bool       $persist This flag indicates whether to attempt to delete the object from the db as well.
-     * @return bool
-     */
-    public function remove(EE_Message $message, $persist = false)
-    {
-        if ($persist && $this->_message_repository->current() !== $message) {
-            //get pointer on right message
-            if ($this->_message_repository->has($message)) {
-                $this->_message_repository->rewind();
-                while ($this->_message_repository->valid()) {
-                    if ($this->_message_repository->current() === $message) {
-                        break;
-                    }
-                    $this->_message_repository->next();
-                }
-            } else {
-                return false;
-            }
-        }
-        return $persist ? $this->_message_repository->delete() : $this->_message_repository->remove($message);
-    }
-
-
-    /**
-     * Persists all queued EE_Message objects to the db.
-     *
-     * @param bool $do_hooks_only       @see EE_Message_Repository::saveAll
-     * @return array @see EE_Messages_Repository::saveAll() for return values.
-     */
-    public function save($do_hooks_only = false)
-    {
-        return $this->_message_repository->saveAll($do_hooks_only);
-    }
-
-
-    /**
-     * @return EE_Message_Repository
-     */
-    public function get_message_repository()
-    {
-        return $this->_message_repository;
-    }
-
-
-    /**
-     * This does the following things:
-     * 1. Checks if there is a lock on generation (prevents race conditions).  If there is a lock then exits (return
-     * false).
-     * 2. If no lock, sets lock, then retrieves a batch of non-generated EE_Message objects and adds to queue
-     * 3. Returns bool.  True = batch ready.  False = no batch ready (or nothing available for generation).
-     * Note: Callers should make sure they release the lock otherwise batch generation will be prevented from
-     * continuing. The lock is on a transient that is set to expire after one hour as a fallback in case locks are not
-     * removed.
-     *
-     * @return bool  true if successfully retrieved batch, false no batch ready.
-     */
-    public function get_batch_to_generate()
-    {
-        if ($this->is_locked(EE_Messages_Queue::action_generating)) {
-            return false;
-        }
-
-        //lock batch generation to prevent race conditions.
-        $this->lock_queue(EE_Messages_Queue::action_generating);
-
-        $query_args = array(
-            // key 0 = where conditions
-            0          => array('STS_ID' => EEM_Message::status_incomplete),
-            'order_by' => $this->_get_priority_orderby(),
-            'limit'    => $this->_batch_count,
-        );
-        $messages   = EEM_Message::instance()->get_all($query_args);
-
-        if ( ! $messages) {
-            return false; //nothing to generate
-        }
-
-        foreach ($messages as $message) {
-            if ($message instanceof EE_Message) {
-                $data = $message->all_extra_meta_array();
-                $this->add($message, $data);
-            }
-        }
-        return true;
-    }
-
-
-    /**
-     * This does the following things:
-     * 1. Checks if there is a lock on sending (prevents race conditions).  If there is a lock then exits (return
-     * false).
-     * 2. Grabs the allowed number of messages to send for the rate_limit.  If cannot send any more messages, then
-     * return false.
-     * 2. If no lock, sets lock, then retrieves a batch of EE_Message objects, adds to queue and triggers execution.
-     * 3. On success or unsuccessful send, sets status appropriately.
-     * 4. Saves messages via the queue
-     * 5. Releases lock.
-     *
-     * @return bool  true on success, false if something preventing sending (i.e. lock set).  Note: true does not
-     *               necessarily mean that all messages were successfully sent.  It just means that this method
-     *               successfully completed. On true, client may want to call $this->count_STS_in_queue(
-     *               EEM_Message::status_failed ) to see if any failed EE_Message objects.  Each failed message object
-     *               will also have a saved error message on it to assist with notifying user.
-     */
-    public function get_to_send_batch_and_send()
-    {
-        if ($this->is_locked(EE_Messages_Queue::action_sending) || $this->_rate_limit < 1) {
-            return false;
-        }
-
-        $this->lock_queue(EE_Messages_Queue::action_sending);
-
-        $batch = $this->_batch_count < $this->_rate_limit ? $this->_batch_count : $this->_rate_limit;
-
-        $query_args = array(
-            // key 0 = where conditions
-            0          => array('STS_ID' => array('IN', EEM_Message::instance()->stati_indicating_to_send())),
-            'order_by' => $this->_get_priority_orderby(),
-            'limit'    => $batch,
-        );
-
-        $messages_to_send = EEM_Message::instance()->get_all($query_args);
-
-
-        //any to send?
-        if ( ! $messages_to_send) {
-            $this->unlock_queue(EE_Messages_Queue::action_sending);
-            return false;
-        }
-
-        //add to queue.
-        foreach ($messages_to_send as $message) {
-            if ($message instanceof EE_Message) {
-                $this->add($message);
-            }
-        }
-
-        //send messages  (this also updates the rate limit)
-        $this->execute();
-
-        //release lock
-        $this->unlock_queue(EE_Messages_Queue::action_sending);
-        return true;
-    }
-
-
-    /**
-     * Locks the queue so that no other queues can call the "batch" methods.
-     *
-     * @param   string $type The type of queue being locked.
-     */
-    public function lock_queue($type = EE_Messages_Queue::action_generating)
-    {
-        set_transient($this->_get_lock_key($type), 1, $this->_get_lock_expiry($type));
-    }
-
-
-    /**
-     * Unlocks the queue so that batch methods can be used.
-     *
-     * @param   string $type The type of queue being unlocked.
-     */
-    public function unlock_queue($type = EE_Messages_Queue::action_generating)
-    {
-        delete_transient($this->_get_lock_key($type));
-    }
-
-
-    /**
-     * Retrieve the key used for the lock transient.
-     *
-     * @param string $type The type of lock.
-     * @return string
-     */
-    protected function _get_lock_key($type = EE_Messages_Queue::action_generating)
-    {
-        return '_ee_lock_' . $type;
-    }
-
-
-    /**
-     * Retrieve the expiry time for the lock transient.
-     *
-     * @param string $type The type of lock
-     * @return int   time to expiry in seconds.
-     */
-    protected function _get_lock_expiry($type = EE_Messages_Queue::action_generating)
-    {
-        return (int)apply_filters('FHEE__EE_Messages_Queue__lock_expiry', HOUR_IN_SECONDS, $type);
-    }
-
-
-    /**
-     * Returns the key used for rate limit transient.
-     *
-     * @return string
-     */
-    protected function _get_rate_limit_key()
-    {
-        return '_ee_rate_limit';
-    }
-
-
-    /**
-     * Returns the rate limit expiry time.
-     *
-     * @return int
-     */
-    protected function _get_rate_limit_expiry()
-    {
-        return (int)apply_filters('FHEE__EE_Messages_Queue__rate_limit_expiry', HOUR_IN_SECONDS);
-    }
-
-
-    /**
-     * Returns the default rate limit for sending messages.
-     *
-     * @return int
-     */
-    protected function _default_rate_limit()
-    {
-        return (int)apply_filters('FHEE__EE_Messages_Queue___rate_limit', 200);
-    }
-
-
-    /**
-     * Return the orderby array for priority.
-     *
-     * @return array
-     */
-    protected function _get_priority_orderby()
-    {
-        return array(
-            'MSG_priority' => 'ASC',
-            'MSG_modified' => 'DESC',
-        );
-    }
-
-
-    /**
-     * Returns whether batch methods are "locked" or not.
-     *
-     * @param  string $type The type of lock being checked for.
-     * @return bool
-     */
-    public function is_locked($type = EE_Messages_Queue::action_generating)
-    {
-        /**
-         * This filters the default is_locked behaviour.
-         */
-        $is_locked = filter_var(
-            apply_filters(
-                'FHEE__EE_Messages_Queue__is_locked',
-                get_transient($this->_get_lock_key($type)),
-                $this
-            ),
-            FILTER_VALIDATE_BOOLEAN
-        );
-
-        /**
-         * @see usage of this filter in EE_Messages_Queue::initiate_request_by_priority() method.
-         *            Also implemented here because messages processed on the same request should not have any locks applied.
-         */
-        if (
-            apply_filters('FHEE__EE_Messages_Processor__initiate_request_by_priority__do_immediate_processing', false)
-            || EE_Registry::instance()->NET_CFG->core->do_messages_on_same_request
-        ) {
-            $is_locked = false;
-        }
-
-
-        return $is_locked;
-    }
-
-
-    /**
-     * Retrieves the rate limit that may be cached as a transient.
-     * If the rate limit is not set, then this sets the default rate limit and expiry and returns it.
-     *
-     * @return int
-     */
-    public function get_rate_limit()
-    {
-        if ( ! $rate_limit = get_transient($this->_get_rate_limit_key())) {
-            $rate_limit = $this->_default_rate_limit();
-            set_transient($this->_get_rate_limit_key(), $rate_limit, $this->_get_rate_limit_key());
-        }
-        return $rate_limit;
-    }
-
-
-    /**
-     * This updates existing rate limit with the new limit which is the old minus the batch.
-     *
-     * @param int $batch_completed This sets the new rate limit based on the given batch that was completed.
-     */
-    public function set_rate_limit($batch_completed)
-    {
-        //first get the most up to date rate limit (in case its expired and reset)
-        $rate_limit = $this->get_rate_limit();
-        $new_limit  = $rate_limit - $batch_completed;
-        //updating the transient option directly to avoid resetting the expiry.
-        update_option('_transient_' . $this->_get_rate_limit_key(), $new_limit);
-    }
-
-
-    /**
-     * This method checks the queue for ANY EE_Message objects with a priority matching the given priority passed in.
-     * If that exists, then we immediately initiate a non-blocking request to do the requested action type.
-     * Note: Keep in mind that there is the possibility that the request will not execute if there is already another
-     * request running on a queue for the given task.
-     *
-     * @param string $task     This indicates what type of request is going to be initiated.
-     * @param int    $priority This indicates the priority that triggers initiating the request.
-     */
-    public function initiate_request_by_priority($task = 'generate', $priority = EEM_Message::priority_high)
-    {
-        //determine what status is matched with the priority as part of the trigger conditions.
-        $status = $task == 'generate'
-            ? EEM_Message::status_incomplete
-            : EEM_Message::instance()->stati_indicating_to_send();
-        // always make sure we save because either this will get executed immediately on a separate request
-        // or remains in the queue for the regularly scheduled queue batch.
-        $this->save();
-        /**
-         * This filter/option allows users to override processing of messages on separate requests and instead have everything
-         * happen on the same request.  If this is utilized remember:
-         * - message priorities don't matter
-         * - existing unprocessed messages in the queue will not get processed unless manually triggered.
-         * - things will be perceived to take longer to happen for end users (i.e. registrations) because of the additional
-         *   processing happening on the same request.
-         * - any race condition protection (locks) are removed because they don't apply when things are processed on
-         *   the same request.
-         */
-        if (
-            apply_filters('FHEE__EE_Messages_Processor__initiate_request_by_priority__do_immediate_processing', false)
-            || EE_Registry::instance()->NET_CFG->core->do_messages_on_same_request
-        ) {
-            $messages_processor = EE_Registry::instance()->load_lib('Messages_Processor');
-            if ($messages_processor instanceof EE_Messages_Processor) {
-                return $messages_processor->process_immediately_from_queue($this);
-            }
-            //if we get here then that means the messages processor couldn't be loaded so messages will just remain
-            //queued for manual triggering by end user.
-        }
-
-        if ($this->_message_repository->count_by_priority_and_status($priority, $status)) {
-            EE_Messages_Scheduler::initiate_scheduled_non_blocking_request($task);
-        }
-    }
-
-
-    /**
-     *  Loops through the EE_Message objects in the _queue and calls the messenger send methods for each message.
-     *
-     * @param   bool     $save                    Used to indicate whether to save the message queue after sending
-     *                                            (default will save).
-     * @param   mixed    $sending_messenger       (optional) When the sending messenger is different than
-     *                                            what is on the EE_Message object in the queue.
-     *                                            For instance, showing the browser view of an email message,
-     *                                            or giving a pdf generated view of an html document.
-     *                                            This should be an instance of EE_messenger but if you call this
-     *                                            method
-     *                                            intending it to be a sending messenger but a valid one could not be
-     *                                            retrieved then send in an instance of EE_Error that contains the
-     *                                            related error message.
-     * @param   bool|int $by_priority             When set, this indicates that only messages
-     *                                            matching the given priority should be executed.
-     * @return int        Number of messages sent.  Note, 0 does not mean that no messages were processed.
-     *                                            Also, if the messenger is an request type messenger (or a preview),
-     *                                            its entirely possible that the messenger will exit before
-     */
-    public function execute($save = true, $sending_messenger = null, $by_priority = false)
-    {
-        $messages_sent   = 0;
-        $this->_did_hook = array();
-        $this->_message_repository->rewind();
-
-        while ($this->_message_repository->valid()) {
-            $error_messages = array();
-            /** @type EE_Message $message */
-            $message = $this->_message_repository->current();
-            //only process things that are queued for sending
-            if (! in_array($message->STS_ID(), EEM_Message::instance()->stati_indicating_to_send())) {
-                $this->_message_repository->next();
-                continue;
-            }
-            //if $by_priority is set and does not match then continue;
-            if ($by_priority && $by_priority != $message->priority()) {
-                $this->_message_repository->next();
-                continue;
-            }
-            //error checking
-            if (! $message->valid_messenger()) {
-                $error_messages[] = sprintf(
-                    __('The %s messenger is not active at time of sending.', 'event_espresso'),
-                    $message->messenger()
-                );
-            }
-            if (! $message->valid_message_type()) {
-                $error_messages[] = sprintf(
-                    __('The %s message type is not active at the time of sending.', 'event_espresso'),
-                    $message->message_type()
-                );
-            }
-            // if there was supposed to be a sending messenger for this message, but it was invalid/inactive,
-            // then it will instead be an EE_Error object, so let's check for that
-            if ($sending_messenger instanceof EE_Error) {
-                $error_messages[] = $sending_messenger->getMessage();
-            }
-            // if there are no errors, then let's process the message
-            if (empty($error_messages)) {
-                if ($save) {
-                    $message->set_messenger_is_executing();
-                }
-                if ($this->_process_message($message, $sending_messenger)) {
-                    $messages_sent++;
-                }
-            }
-            $this->_set_error_message($message, $error_messages);
-            //add modified time
-            $message->set_modified(time());
-            //we save each message after its processed to make sure its status persists in case PHP times-out or runs
-            //out of memory. @see https://events.codebasehq.com/projects/event-espresso/tickets/10281
-            if ($save) {
-                $message->save();
-            }
-
-            $this->_message_repository->next();
-        }
-        if ($save) {
-            $this->save(true);
-        }
-        return $messages_sent;
-    }
-
-
-    /**
-     * _process_message
-     *
-     * @param EE_Message $message
-     * @param mixed      $sending_messenger (optional)
-     * @return bool
-     */
-    protected function _process_message(EE_Message $message, $sending_messenger = null)
-    {
-        // these *should* have been validated in the execute() method above
-        $messenger    = $message->messenger_object();
-        $message_type = $message->message_type_object();
-        //do actions for sending messenger if it differs from generating messenger and swap values.
-        if (
-            $sending_messenger instanceof EE_messenger
-            && $messenger instanceof EE_messenger
-            && $sending_messenger->name != $messenger->name
-        ) {
-            $messenger->do_secondary_messenger_hooks($sending_messenger->name);
-            $messenger = $sending_messenger;
-        }
-        // send using messenger, but double check objects
-        if ($messenger instanceof EE_messenger && $message_type instanceof EE_message_type) {
-            //set hook for message type (but only if not using another messenger to send).
-            if ( ! isset($this->_did_hook[$message_type->name])) {
-                $message_type->do_messenger_hooks($messenger);
-                $this->_did_hook[$message_type->name] = 1;
-            }
-            //if preview then use preview method
-            return $this->_message_repository->is_preview()
-                ? $this->_do_preview($message, $messenger, $message_type, $this->_message_repository->is_test_send())
-                : $this->_do_send($message, $messenger, $message_type);
-        }
-        return false;
-    }
-
-
-    /**
-     * The intention of this method is to count how many EE_Message objects
-     * are in the queue with a given status.
-     * Example usage:
-     * After a caller calls the "EE_Message_Queue::execute()" method, the caller can check if there were any failed
-     * sends by calling $queue->count_STS_in_queue( EEM_Message_Queue::status_failed ).
-     *
-     * @param array|string $status Stati to check for in queue
-     * @return int  Count of EE_Message's matching the given status.
-     */
-    public function count_STS_in_queue($status)
-    {
-        $count  = 0;
-        $status = is_array($status) ? $status : array($status);
-        $this->_message_repository->rewind();
-        foreach ($this->_message_repository as $message) {
-            if (in_array($message->STS_ID(), $status)) {
-                $count++;
-            }
-        }
-        return $count;
-    }
-
-
-    /**
-     * Executes the get_preview method on the provided messenger.
-     *
-     * @param EE_Message      $message
-     * @param EE_messenger    $messenger
-     * @param EE_message_type $message_type
-     * @param                 $test_send
-     * @return bool   true means all went well, false means, not so much.
-     */
-    protected function _do_preview(
-        EE_Message $message,
-        EE_messenger $messenger,
-        EE_message_type $message_type,
-        $test_send
-    ) {
-        if ($preview = $messenger->get_preview($message, $message_type, $test_send)) {
-            if ( ! $test_send) {
-                $message->set_content($preview);
-            }
-            $message->set_STS_ID(EEM_Message::status_sent);
-            return true;
-        } else {
-            $message->set_STS_ID(EEM_Message::status_failed);
-            return false;
-        }
-    }
-
-
-    /**
-     * Executes the send method on the provided messenger
-     * EE_Messengers are expected to:
-     * - return true if the send was successful.
-     * - return false if the send was unsuccessful but can be tried again.
-     * - throw an Exception if the send was unsuccessful and cannot be tried again.
-     *
-     * @param EE_Message      $message
-     * @param EE_messenger    $messenger
-     * @param EE_message_type $message_type
-     * @return bool true means all went well, false means, not so much.
-     */
-    protected function _do_send(EE_Message $message, EE_messenger $messenger, EE_message_type $message_type)
-    {
-        try {
-            if ($messenger->send_message($message, $message_type)) {
-                $message->set_STS_ID(EEM_Message::status_sent);
-                return true;
-            } else {
-                $message->set_STS_ID(EEM_Message::status_retry);
-                return false;
-            }
-        } catch (SendMessageException $e) {
-            $message->set_STS_ID(EEM_Message::status_failed);
-            $message->set_error_message($e->getMessage());
-            return false;
-        }
-    }
-
-
-    /**
-     * This sets any necessary error messages on the message object and its status to failed.
-     *
-     * @param EE_Message $message
-     * @param array      $error_messages the response from the messenger.
-     */
-    protected function _set_error_message(EE_Message $message, $error_messages)
-    {
-        $error_messages = (array)$error_messages;
-        if (in_array($message->STS_ID(), EEM_Message::instance()->stati_indicating_failed_sending())) {
-            $notices          = EE_Error::has_notices();
-            $error_messages[] = __(
-                'Messenger and Message Type were valid and active, but the messenger send method failed.',
-                'event_espresso'
-            );
-            if ($notices === 1) {
-                $notices           = EE_Error::get_vanilla_notices();
-                $notices['errors'] = isset($notices['errors']) ? $notices['errors'] : array();
-                $error_messages[]  = implode("\n", $notices['errors']);
-            }
-        }
-        if (count($error_messages) > 0) {
-            $msg = __('Message was not executed successfully.', 'event_espresso');
-            $msg = $msg . "\n" . implode("\n", $error_messages);
-            $message->set_error_message($msg);
-        }
-    }
+	/**
+	 * @type    string  reference for sending action
+	 */
+	const action_sending = 'sending';
+
+	/**
+	 * @type    string  reference for generation action
+	 */
+	const action_generating = 'generation';
+
+
+	/**
+	 * @type EE_Message_Repository $_message_repository
+	 */
+	protected $_message_repository;
+
+	/**
+	 * Sets the limit of how many messages are generated per process.
+	 *
+	 * @type int
+	 */
+	protected $_batch_count;
+
+	/**
+	 * Sets the limit of how many messages can be sent per hour.
+	 *
+	 * @type int
+	 */
+	protected $_rate_limit;
+
+	/**
+	 * This is an array of cached queue items being stored in this object.
+	 * The array keys will be the ID of the EE_Message in the db if saved.  If the EE_Message
+	 * is not saved to the db then its key will be an increment of "UNS" (i.e. UNS1, UNS2 etc.)
+	 *
+	 * @type EE_Message[]
+	 */
+	protected $_cached_queue_items;
+
+	/**
+	 * Tracks the number of unsaved queue items.
+	 *
+	 * @type int
+	 */
+	protected $_unsaved_count = 0;
+
+	/**
+	 * used to record if a do_messenger_hooks has already been called for a message type.  This prevents multiple
+	 * hooks getting fired if users have setup their action/filter hooks to prevent duplicate calls.
+	 *
+	 * @type array
+	 */
+	protected $_did_hook = array();
+
+
+	/**
+	 * Constructor.
+	 * Setup all the initial properties and load a EE_Message_Repository.
+	 *
+	 * @param \EE_Message_Repository $message_repository
+	 */
+	public function __construct(EE_Message_Repository $message_repository)
+	{
+		$this->_batch_count        = apply_filters('FHEE__EE_Messages_Queue___batch_count', 50);
+		$this->_rate_limit         = $this->get_rate_limit();
+		$this->_message_repository = $message_repository;
+	}
+
+
+	/**
+	 * Add a EE_Message object to the queue
+	 *
+	 * @param EE_Message $message
+	 * @param array      $data         This will be an array of data to attach to the object in the repository.  If the
+	 *                                 object is persisted, this data will be saved on an extra_meta object related to
+	 *                                 EE_Message.
+	 * @param  bool      $preview      Whether this EE_Message represents a preview or not.
+	 * @param  bool      $test_send    This indicates whether to do a test send instead of actual send. A test send will
+	 *                                 use the messenger send method but typically is based on preview data.
+	 * @return bool          Whether the message was successfully added to the repository or not.
+	 */
+	public function add(EE_Message $message, $data = array(), $preview = false, $test_send = false)
+	{
+		$data['preview']   = $preview;
+		$data['test_send'] = $test_send;
+		return $this->_message_repository->add($message, $data);
+	}
+
+
+	/**
+	 * Removes EE_Message from _queue that matches the given EE_Message if the pointer is on a matching EE_Message
+	 *
+	 * @param EE_Message $message The message to detach from the queue
+	 * @param bool       $persist This flag indicates whether to attempt to delete the object from the db as well.
+	 * @return bool
+	 */
+	public function remove(EE_Message $message, $persist = false)
+	{
+		if ($persist && $this->_message_repository->current() !== $message) {
+			//get pointer on right message
+			if ($this->_message_repository->has($message)) {
+				$this->_message_repository->rewind();
+				while ($this->_message_repository->valid()) {
+					if ($this->_message_repository->current() === $message) {
+						break;
+					}
+					$this->_message_repository->next();
+				}
+			} else {
+				return false;
+			}
+		}
+		return $persist ? $this->_message_repository->delete() : $this->_message_repository->remove($message);
+	}
+
+
+	/**
+	 * Persists all queued EE_Message objects to the db.
+	 *
+	 * @param bool $do_hooks_only       @see EE_Message_Repository::saveAll
+	 * @return array @see EE_Messages_Repository::saveAll() for return values.
+	 */
+	public function save($do_hooks_only = false)
+	{
+		return $this->_message_repository->saveAll($do_hooks_only);
+	}
+
+
+	/**
+	 * @return EE_Message_Repository
+	 */
+	public function get_message_repository()
+	{
+		return $this->_message_repository;
+	}
+
+
+	/**
+	 * This does the following things:
+	 * 1. Checks if there is a lock on generation (prevents race conditions).  If there is a lock then exits (return
+	 * false).
+	 * 2. If no lock, sets lock, then retrieves a batch of non-generated EE_Message objects and adds to queue
+	 * 3. Returns bool.  True = batch ready.  False = no batch ready (or nothing available for generation).
+	 * Note: Callers should make sure they release the lock otherwise batch generation will be prevented from
+	 * continuing. The lock is on a transient that is set to expire after one hour as a fallback in case locks are not
+	 * removed.
+	 *
+	 * @return bool  true if successfully retrieved batch, false no batch ready.
+	 */
+	public function get_batch_to_generate()
+	{
+		if ($this->is_locked(EE_Messages_Queue::action_generating)) {
+			return false;
+		}
+
+		//lock batch generation to prevent race conditions.
+		$this->lock_queue(EE_Messages_Queue::action_generating);
+
+		$query_args = array(
+			// key 0 = where conditions
+			0          => array('STS_ID' => EEM_Message::status_incomplete),
+			'order_by' => $this->_get_priority_orderby(),
+			'limit'    => $this->_batch_count,
+		);
+		$messages   = EEM_Message::instance()->get_all($query_args);
+
+		if ( ! $messages) {
+			return false; //nothing to generate
+		}
+
+		foreach ($messages as $message) {
+			if ($message instanceof EE_Message) {
+				$data = $message->all_extra_meta_array();
+				$this->add($message, $data);
+			}
+		}
+		return true;
+	}
+
+
+	/**
+	 * This does the following things:
+	 * 1. Checks if there is a lock on sending (prevents race conditions).  If there is a lock then exits (return
+	 * false).
+	 * 2. Grabs the allowed number of messages to send for the rate_limit.  If cannot send any more messages, then
+	 * return false.
+	 * 2. If no lock, sets lock, then retrieves a batch of EE_Message objects, adds to queue and triggers execution.
+	 * 3. On success or unsuccessful send, sets status appropriately.
+	 * 4. Saves messages via the queue
+	 * 5. Releases lock.
+	 *
+	 * @return bool  true on success, false if something preventing sending (i.e. lock set).  Note: true does not
+	 *               necessarily mean that all messages were successfully sent.  It just means that this method
+	 *               successfully completed. On true, client may want to call $this->count_STS_in_queue(
+	 *               EEM_Message::status_failed ) to see if any failed EE_Message objects.  Each failed message object
+	 *               will also have a saved error message on it to assist with notifying user.
+	 */
+	public function get_to_send_batch_and_send()
+	{
+		if ($this->is_locked(EE_Messages_Queue::action_sending) || $this->_rate_limit < 1) {
+			return false;
+		}
+
+		$this->lock_queue(EE_Messages_Queue::action_sending);
+
+		$batch = $this->_batch_count < $this->_rate_limit ? $this->_batch_count : $this->_rate_limit;
+
+		$query_args = array(
+			// key 0 = where conditions
+			0          => array('STS_ID' => array('IN', EEM_Message::instance()->stati_indicating_to_send())),
+			'order_by' => $this->_get_priority_orderby(),
+			'limit'    => $batch,
+		);
+
+		$messages_to_send = EEM_Message::instance()->get_all($query_args);
+
+
+		//any to send?
+		if ( ! $messages_to_send) {
+			$this->unlock_queue(EE_Messages_Queue::action_sending);
+			return false;
+		}
+
+		//add to queue.
+		foreach ($messages_to_send as $message) {
+			if ($message instanceof EE_Message) {
+				$this->add($message);
+			}
+		}
+
+		//send messages  (this also updates the rate limit)
+		$this->execute();
+
+		//release lock
+		$this->unlock_queue(EE_Messages_Queue::action_sending);
+		return true;
+	}
+
+
+	/**
+	 * Locks the queue so that no other queues can call the "batch" methods.
+	 *
+	 * @param   string $type The type of queue being locked.
+	 */
+	public function lock_queue($type = EE_Messages_Queue::action_generating)
+	{
+		set_transient($this->_get_lock_key($type), 1, $this->_get_lock_expiry($type));
+	}
+
+
+	/**
+	 * Unlocks the queue so that batch methods can be used.
+	 *
+	 * @param   string $type The type of queue being unlocked.
+	 */
+	public function unlock_queue($type = EE_Messages_Queue::action_generating)
+	{
+		delete_transient($this->_get_lock_key($type));
+	}
+
+
+	/**
+	 * Retrieve the key used for the lock transient.
+	 *
+	 * @param string $type The type of lock.
+	 * @return string
+	 */
+	protected function _get_lock_key($type = EE_Messages_Queue::action_generating)
+	{
+		return '_ee_lock_' . $type;
+	}
+
+
+	/**
+	 * Retrieve the expiry time for the lock transient.
+	 *
+	 * @param string $type The type of lock
+	 * @return int   time to expiry in seconds.
+	 */
+	protected function _get_lock_expiry($type = EE_Messages_Queue::action_generating)
+	{
+		return (int)apply_filters('FHEE__EE_Messages_Queue__lock_expiry', HOUR_IN_SECONDS, $type);
+	}
+
+
+	/**
+	 * Returns the key used for rate limit transient.
+	 *
+	 * @return string
+	 */
+	protected function _get_rate_limit_key()
+	{
+		return '_ee_rate_limit';
+	}
+
+
+	/**
+	 * Returns the rate limit expiry time.
+	 *
+	 * @return int
+	 */
+	protected function _get_rate_limit_expiry()
+	{
+		return (int)apply_filters('FHEE__EE_Messages_Queue__rate_limit_expiry', HOUR_IN_SECONDS);
+	}
+
+
+	/**
+	 * Returns the default rate limit for sending messages.
+	 *
+	 * @return int
+	 */
+	protected function _default_rate_limit()
+	{
+		return (int)apply_filters('FHEE__EE_Messages_Queue___rate_limit', 200);
+	}
+
+
+	/**
+	 * Return the orderby array for priority.
+	 *
+	 * @return array
+	 */
+	protected function _get_priority_orderby()
+	{
+		return array(
+			'MSG_priority' => 'ASC',
+			'MSG_modified' => 'DESC',
+		);
+	}
+
+
+	/**
+	 * Returns whether batch methods are "locked" or not.
+	 *
+	 * @param  string $type The type of lock being checked for.
+	 * @return bool
+	 */
+	public function is_locked($type = EE_Messages_Queue::action_generating)
+	{
+		/**
+		 * This filters the default is_locked behaviour.
+		 */
+		$is_locked = filter_var(
+			apply_filters(
+				'FHEE__EE_Messages_Queue__is_locked',
+				get_transient($this->_get_lock_key($type)),
+				$this
+			),
+			FILTER_VALIDATE_BOOLEAN
+		);
+
+		/**
+		 * @see usage of this filter in EE_Messages_Queue::initiate_request_by_priority() method.
+		 *            Also implemented here because messages processed on the same request should not have any locks applied.
+		 */
+		if (
+			apply_filters('FHEE__EE_Messages_Processor__initiate_request_by_priority__do_immediate_processing', false)
+			|| EE_Registry::instance()->NET_CFG->core->do_messages_on_same_request
+		) {
+			$is_locked = false;
+		}
+
+
+		return $is_locked;
+	}
+
+
+	/**
+	 * Retrieves the rate limit that may be cached as a transient.
+	 * If the rate limit is not set, then this sets the default rate limit and expiry and returns it.
+	 *
+	 * @return int
+	 */
+	public function get_rate_limit()
+	{
+		if ( ! $rate_limit = get_transient($this->_get_rate_limit_key())) {
+			$rate_limit = $this->_default_rate_limit();
+			set_transient($this->_get_rate_limit_key(), $rate_limit, $this->_get_rate_limit_key());
+		}
+		return $rate_limit;
+	}
+
+
+	/**
+	 * This updates existing rate limit with the new limit which is the old minus the batch.
+	 *
+	 * @param int $batch_completed This sets the new rate limit based on the given batch that was completed.
+	 */
+	public function set_rate_limit($batch_completed)
+	{
+		//first get the most up to date rate limit (in case its expired and reset)
+		$rate_limit = $this->get_rate_limit();
+		$new_limit  = $rate_limit - $batch_completed;
+		//updating the transient option directly to avoid resetting the expiry.
+		update_option('_transient_' . $this->_get_rate_limit_key(), $new_limit);
+	}
+
+
+	/**
+	 * This method checks the queue for ANY EE_Message objects with a priority matching the given priority passed in.
+	 * If that exists, then we immediately initiate a non-blocking request to do the requested action type.
+	 * Note: Keep in mind that there is the possibility that the request will not execute if there is already another
+	 * request running on a queue for the given task.
+	 *
+	 * @param string $task     This indicates what type of request is going to be initiated.
+	 * @param int    $priority This indicates the priority that triggers initiating the request.
+	 */
+	public function initiate_request_by_priority($task = 'generate', $priority = EEM_Message::priority_high)
+	{
+		//determine what status is matched with the priority as part of the trigger conditions.
+		$status = $task == 'generate'
+			? EEM_Message::status_incomplete
+			: EEM_Message::instance()->stati_indicating_to_send();
+		// always make sure we save because either this will get executed immediately on a separate request
+		// or remains in the queue for the regularly scheduled queue batch.
+		$this->save();
+		/**
+		 * This filter/option allows users to override processing of messages on separate requests and instead have everything
+		 * happen on the same request.  If this is utilized remember:
+		 * - message priorities don't matter
+		 * - existing unprocessed messages in the queue will not get processed unless manually triggered.
+		 * - things will be perceived to take longer to happen for end users (i.e. registrations) because of the additional
+		 *   processing happening on the same request.
+		 * - any race condition protection (locks) are removed because they don't apply when things are processed on
+		 *   the same request.
+		 */
+		if (
+			apply_filters('FHEE__EE_Messages_Processor__initiate_request_by_priority__do_immediate_processing', false)
+			|| EE_Registry::instance()->NET_CFG->core->do_messages_on_same_request
+		) {
+			$messages_processor = EE_Registry::instance()->load_lib('Messages_Processor');
+			if ($messages_processor instanceof EE_Messages_Processor) {
+				return $messages_processor->process_immediately_from_queue($this);
+			}
+			//if we get here then that means the messages processor couldn't be loaded so messages will just remain
+			//queued for manual triggering by end user.
+		}
+
+		if ($this->_message_repository->count_by_priority_and_status($priority, $status)) {
+			EE_Messages_Scheduler::initiate_scheduled_non_blocking_request($task);
+		}
+	}
+
+
+	/**
+	 *  Loops through the EE_Message objects in the _queue and calls the messenger send methods for each message.
+	 *
+	 * @param   bool     $save                    Used to indicate whether to save the message queue after sending
+	 *                                            (default will save).
+	 * @param   mixed    $sending_messenger       (optional) When the sending messenger is different than
+	 *                                            what is on the EE_Message object in the queue.
+	 *                                            For instance, showing the browser view of an email message,
+	 *                                            or giving a pdf generated view of an html document.
+	 *                                            This should be an instance of EE_messenger but if you call this
+	 *                                            method
+	 *                                            intending it to be a sending messenger but a valid one could not be
+	 *                                            retrieved then send in an instance of EE_Error that contains the
+	 *                                            related error message.
+	 * @param   bool|int $by_priority             When set, this indicates that only messages
+	 *                                            matching the given priority should be executed.
+	 * @return int        Number of messages sent.  Note, 0 does not mean that no messages were processed.
+	 *                                            Also, if the messenger is an request type messenger (or a preview),
+	 *                                            its entirely possible that the messenger will exit before
+	 */
+	public function execute($save = true, $sending_messenger = null, $by_priority = false)
+	{
+		$messages_sent   = 0;
+		$this->_did_hook = array();
+		$this->_message_repository->rewind();
+
+		while ($this->_message_repository->valid()) {
+			$error_messages = array();
+			/** @type EE_Message $message */
+			$message = $this->_message_repository->current();
+			//only process things that are queued for sending
+			if (! in_array($message->STS_ID(), EEM_Message::instance()->stati_indicating_to_send())) {
+				$this->_message_repository->next();
+				continue;
+			}
+			//if $by_priority is set and does not match then continue;
+			if ($by_priority && $by_priority != $message->priority()) {
+				$this->_message_repository->next();
+				continue;
+			}
+			//error checking
+			if (! $message->valid_messenger()) {
+				$error_messages[] = sprintf(
+					__('The %s messenger is not active at time of sending.', 'event_espresso'),
+					$message->messenger()
+				);
+			}
+			if (! $message->valid_message_type()) {
+				$error_messages[] = sprintf(
+					__('The %s message type is not active at the time of sending.', 'event_espresso'),
+					$message->message_type()
+				);
+			}
+			// if there was supposed to be a sending messenger for this message, but it was invalid/inactive,
+			// then it will instead be an EE_Error object, so let's check for that
+			if ($sending_messenger instanceof EE_Error) {
+				$error_messages[] = $sending_messenger->getMessage();
+			}
+			// if there are no errors, then let's process the message
+			if (empty($error_messages)) {
+				if ($save) {
+					$message->set_messenger_is_executing();
+				}
+				if ($this->_process_message($message, $sending_messenger)) {
+					$messages_sent++;
+				}
+			}
+			$this->_set_error_message($message, $error_messages);
+			//add modified time
+			$message->set_modified(time());
+			//we save each message after its processed to make sure its status persists in case PHP times-out or runs
+			//out of memory. @see https://events.codebasehq.com/projects/event-espresso/tickets/10281
+			if ($save) {
+				$message->save();
+			}
+
+			$this->_message_repository->next();
+		}
+		if ($save) {
+			$this->save(true);
+		}
+		return $messages_sent;
+	}
+
+
+	/**
+	 * _process_message
+	 *
+	 * @param EE_Message $message
+	 * @param mixed      $sending_messenger (optional)
+	 * @return bool
+	 */
+	protected function _process_message(EE_Message $message, $sending_messenger = null)
+	{
+		// these *should* have been validated in the execute() method above
+		$messenger    = $message->messenger_object();
+		$message_type = $message->message_type_object();
+		//do actions for sending messenger if it differs from generating messenger and swap values.
+		if (
+			$sending_messenger instanceof EE_messenger
+			&& $messenger instanceof EE_messenger
+			&& $sending_messenger->name != $messenger->name
+		) {
+			$messenger->do_secondary_messenger_hooks($sending_messenger->name);
+			$messenger = $sending_messenger;
+		}
+		// send using messenger, but double check objects
+		if ($messenger instanceof EE_messenger && $message_type instanceof EE_message_type) {
+			//set hook for message type (but only if not using another messenger to send).
+			if ( ! isset($this->_did_hook[$message_type->name])) {
+				$message_type->do_messenger_hooks($messenger);
+				$this->_did_hook[$message_type->name] = 1;
+			}
+			//if preview then use preview method
+			return $this->_message_repository->is_preview()
+				? $this->_do_preview($message, $messenger, $message_type, $this->_message_repository->is_test_send())
+				: $this->_do_send($message, $messenger, $message_type);
+		}
+		return false;
+	}
+
+
+	/**
+	 * The intention of this method is to count how many EE_Message objects
+	 * are in the queue with a given status.
+	 * Example usage:
+	 * After a caller calls the "EE_Message_Queue::execute()" method, the caller can check if there were any failed
+	 * sends by calling $queue->count_STS_in_queue( EEM_Message_Queue::status_failed ).
+	 *
+	 * @param array|string $status Stati to check for in queue
+	 * @return int  Count of EE_Message's matching the given status.
+	 */
+	public function count_STS_in_queue($status)
+	{
+		$count  = 0;
+		$status = is_array($status) ? $status : array($status);
+		$this->_message_repository->rewind();
+		foreach ($this->_message_repository as $message) {
+			if (in_array($message->STS_ID(), $status)) {
+				$count++;
+			}
+		}
+		return $count;
+	}
+
+
+	/**
+	 * Executes the get_preview method on the provided messenger.
+	 *
+	 * @param EE_Message      $message
+	 * @param EE_messenger    $messenger
+	 * @param EE_message_type $message_type
+	 * @param                 $test_send
+	 * @return bool   true means all went well, false means, not so much.
+	 */
+	protected function _do_preview(
+		EE_Message $message,
+		EE_messenger $messenger,
+		EE_message_type $message_type,
+		$test_send
+	) {
+		if ($preview = $messenger->get_preview($message, $message_type, $test_send)) {
+			if ( ! $test_send) {
+				$message->set_content($preview);
+			}
+			$message->set_STS_ID(EEM_Message::status_sent);
+			return true;
+		} else {
+			$message->set_STS_ID(EEM_Message::status_failed);
+			return false;
+		}
+	}
+
+
+	/**
+	 * Executes the send method on the provided messenger
+	 * EE_Messengers are expected to:
+	 * - return true if the send was successful.
+	 * - return false if the send was unsuccessful but can be tried again.
+	 * - throw an Exception if the send was unsuccessful and cannot be tried again.
+	 *
+	 * @param EE_Message      $message
+	 * @param EE_messenger    $messenger
+	 * @param EE_message_type $message_type
+	 * @return bool true means all went well, false means, not so much.
+	 */
+	protected function _do_send(EE_Message $message, EE_messenger $messenger, EE_message_type $message_type)
+	{
+		try {
+			if ($messenger->send_message($message, $message_type)) {
+				$message->set_STS_ID(EEM_Message::status_sent);
+				return true;
+			} else {
+				$message->set_STS_ID(EEM_Message::status_retry);
+				return false;
+			}
+		} catch (SendMessageException $e) {
+			$message->set_STS_ID(EEM_Message::status_failed);
+			$message->set_error_message($e->getMessage());
+			return false;
+		}
+	}
+
+
+	/**
+	 * This sets any necessary error messages on the message object and its status to failed.
+	 *
+	 * @param EE_Message $message
+	 * @param array      $error_messages the response from the messenger.
+	 */
+	protected function _set_error_message(EE_Message $message, $error_messages)
+	{
+		$error_messages = (array)$error_messages;
+		if (in_array($message->STS_ID(), EEM_Message::instance()->stati_indicating_failed_sending())) {
+			$notices          = EE_Error::has_notices();
+			$error_messages[] = __(
+				'Messenger and Message Type were valid and active, but the messenger send method failed.',
+				'event_espresso'
+			);
+			if ($notices === 1) {
+				$notices           = EE_Error::get_vanilla_notices();
+				$notices['errors'] = isset($notices['errors']) ? $notices['errors'] : array();
+				$error_messages[]  = implode("\n", $notices['errors']);
+			}
+		}
+		if (count($error_messages) > 0) {
+			$msg = __('Message was not executed successfully.', 'event_espresso');
+			$msg = $msg . "\n" . implode("\n", $error_messages);
+			$message->set_error_message($msg);
+		}
+	}
 
 } //end EE_Messages_Queue class

core/libraries/messages/EE_Messages_Processor.lib.php

Indentation +4 added lines, -4 removed lines

@@ -560,10 +560,10 @@
 
 		foreach ( $regs_to_send as $status_group ) {
 			foreach ( $status_group as $status_id => $registrations ) {
-			    $message_type = EEH_MSG_Template::convert_reg_status_to_message_type($status_id);
-			    if (! $message_type) {
-			        continue;
-                }
+				$message_type = EEH_MSG_Template::convert_reg_status_to_message_type($status_id);
+				if (! $message_type) {
+					continue;
+				}
 				$messages_to_generate = array_merge(
 					$messages_to_generate,
 					$this->setup_mtgs_for_all_active_messengers(

Spacing +108 added lines, -108 removed lines

@@ -35,7 +35,7 @@ 
 	 *
 	 * @param EE_Message_Resource_Manager $message_resource_manager
 	 */
-	public function __construct( EE_Message_Resource_Manager $message_resource_manager ) {
+	public function __construct(EE_Message_Resource_Manager $message_resource_manager) {
 		$this->_message_resource_manager = $message_resource_manager;
 		$this->_init_queue_and_generator();
 	}
@@ -50,7 +50,7 @@ 
 	 * - $_generator = holds the messages generator
 	 */
 	protected function _init_queue_and_generator() {
-		$this->_generator = EE_Registry::factory( 'EE_Messages_Generator' );
+		$this->_generator = EE_Registry::factory('EE_Messages_Generator');
 		$this->_queue = $this->_generator->generation_queue();
 	}
 
@@ -75,31 +75,31 @@ 
 	 * @param EE_Messages_Queue $queue_to_process
 	 * @return bool  true for success false for error.
 	 */
-	public function process_immediately_from_queue( EE_Messages_Queue $queue_to_process ) {
+	public function process_immediately_from_queue(EE_Messages_Queue $queue_to_process) {
 		$success = false;
 		$messages_to_send = array();
 		$messages_to_generate = array();
 		//loop through and setup the various messages from the queue so we know what is being processed
 		$queue_to_process->get_message_repository()->rewind();
-		foreach ( $queue_to_process->get_message_repository() as $message ) {
-			if ( $message->STS_ID() === EEM_Message::status_incomplete ) {
+		foreach ($queue_to_process->get_message_repository() as $message) {
+			if ($message->STS_ID() === EEM_Message::status_incomplete) {
 				$messages_to_generate[] = $message;
 				continue;
 			}
 
-			if ( in_array( $message->STS_ID(), EEM_Message::instance()->stati_indicating_to_send() ) ) {
+			if (in_array($message->STS_ID(), EEM_Message::instance()->stati_indicating_to_send())) {
 				$messages_to_send[] = $message;
 				continue;
 			}
 		}
 
 		//do generation/sends
-		if ( $messages_to_generate ) {
-			$success = $this->batch_generate_from_queue( $messages_to_generate, true );
+		if ($messages_to_generate) {
+			$success = $this->batch_generate_from_queue($messages_to_generate, true);
 		}
 
-		if ( $messages_to_send ) {
-			$sent = $this->batch_send_from_queue( $messages_to_send, true );
+		if ($messages_to_send) {
+			$sent = $this->batch_send_from_queue($messages_to_send, true);
 			//if there was messages to generate and it failed, then we override any success value for the sending process
 			//otherwise we just use the return from batch send.  The intent is that there is a simple response for success/fail.
 			//Either everything was successful or we consider it a fail.  To be clear, this is a limitation of doing
@@ -119,13 +119,13 @@ 
 	 * @return bool|EE_Messages_Queue return false if nothing generated.  This returns a new EE_Message_Queue with
 	 *                                   generated messages.
 	 */
-	public function batch_generate_from_queue( $messages = array(), $clear_queue = false ) {
-		if ( $this->_build_queue_for_generation( $messages, $clear_queue ) ) {
+	public function batch_generate_from_queue($messages = array(), $clear_queue = false) {
+		if ($this->_build_queue_for_generation($messages, $clear_queue)) {
 			$new_queue = $this->_generator->generate();
-			if ( $new_queue instanceof EE_Messages_Queue ) {
+			if ($new_queue instanceof EE_Messages_Queue) {
 				//unlock queue
 				$this->_queue->unlock_queue();
-				$new_queue->initiate_request_by_priority( 'send' );
+				$new_queue->initiate_request_by_priority('send');
 				return $new_queue;
 			}
 		}
@@ -146,24 +146,24 @@ 
 	 *
 	 * @return bool true means queue prepped, false means there was a lock so no generation please.
 	 */
-	protected function _build_queue_for_generation( $messages = array(), $clear_queue = false ) {
+	protected function _build_queue_for_generation($messages = array(), $clear_queue = false) {
 
-		if ( $clear_queue ) {
+		if ($clear_queue) {
 			$this->_init_queue_and_generator();
 		}
 
-		if ( $messages ) {
+		if ($messages) {
 			//if generation is locked then get out now because that means processing is already happening.
-			if ( $this->_queue->is_locked() ) {
+			if ($this->_queue->is_locked()) {
 				return false;
 			}
 
 			$this->_queue->lock_queue();
-			$messages = is_array( $messages ) ? $messages : array( $messages );
-			foreach ( $messages as $message ) {
-				if ( $message instanceof EE_Message ) {
+			$messages = is_array($messages) ? $messages : array($messages);
+			foreach ($messages as $message) {
+				if ($message instanceof EE_Message) {
 					$data = $message->all_extra_meta_array();
-					$this->_queue->add( $message, $data );
+					$this->_queue->add($message, $data);
 				}
 			}
 			return true;
@@ -181,22 +181,22 @@ 
 	 *
 	 * @return bool true means queue prepped, false means there was a lock so no queue prepped.
 	 */
-	protected function _build_queue_for_sending( $messages, $clear_queue = false ) {
+	protected function _build_queue_for_sending($messages, $clear_queue = false) {
 		//if sending is locked then get out now because that means processing is already happening.
-		if ( $this->_queue->is_locked( EE_Messages_Queue::action_sending ) ) {
+		if ($this->_queue->is_locked(EE_Messages_Queue::action_sending)) {
 			return false;
 		}
 
-		$this->_queue->lock_queue( EE_Messages_Queue::action_sending );
+		$this->_queue->lock_queue(EE_Messages_Queue::action_sending);
 
-		if ( $clear_queue ) {
+		if ($clear_queue) {
 			$this->_init_queue_and_generator();
 		}
 
-		$messages = is_array( $messages ) ? $messages : array( $messages );
+		$messages = is_array($messages) ? $messages : array($messages);
 
-		foreach ( $messages as $message ) {
-			$this->_queue->add( $message );
+		foreach ($messages as $message) {
+			$this->_queue->add($message);
 		}
 		return true;
 	}
@@ -212,11 +212,11 @@ 
 	 *
 	 * @return EE_Messages_Queue
 	 */
-	public function batch_send_from_queue( $messages = array(), $clear_queue = false ) {
+	public function batch_send_from_queue($messages = array(), $clear_queue = false) {
 
-		if ( $messages && $this->_build_queue_for_sending( $messages, $clear_queue ) ) {
+		if ($messages && $this->_build_queue_for_sending($messages, $clear_queue)) {
 			$this->_queue->execute();
-			$this->_queue->unlock_queue( EE_Messages_Queue::action_sending );
+			$this->_queue->unlock_queue(EE_Messages_Queue::action_sending);
 		} else {
 			//get messages to send and execute.
 			$this->_queue->get_to_send_batch_and_send();
@@ -239,10 +239,10 @@ 
 	 * @param EE_Message_To_Generate[] $messages_to_generate
 	 * @return EE_Messages_Queue
 	 */
-	public function generate_and_return(  $messages_to_generate ) {
+	public function generate_and_return($messages_to_generate) {
 		$this->_init_queue_and_generator();
-		$this->_queue_for_generation_loop( $messages_to_generate );
-		return $this->_generator->generate( false );
+		$this->_queue_for_generation_loop($messages_to_generate);
+		return $this->_generator->generate(false);
 	}
 
 
@@ -253,8 +253,8 @@ 
 	 * @param  bool     $persist    Indicate whether to instruct the generator to persist the generated queue (true) or not (false).
 	 * @return EE_Messages_Queue
 	 */
-	public function generate_queue( $persist = true ) {
-		return $this->_generator->generate( $persist );
+	public function generate_queue($persist = true) {
+		return $this->_generator->generate($persist);
 	}
 
 
@@ -267,9 +267,9 @@ 
 	 * @param bool                   $test_send             Whether this item is for a test send or not.
 	 * @return  EE_Messages_Queue
 	 */
-	public function queue_for_generation( EE_Message_To_Generate $message_to_generate, $test_send = false ) {
-		if ( $message_to_generate->valid() ) {
-			$this->_generator->create_and_add_message_to_queue( $message_to_generate, $test_send );
+	public function queue_for_generation(EE_Message_To_Generate $message_to_generate, $test_send = false) {
+		if ($message_to_generate->valid()) {
+			$this->_generator->create_and_add_message_to_queue($message_to_generate, $test_send);
 		}
 	}
 
@@ -285,9 +285,9 @@ 
 	 *
 	 * @param EE_Message_To_Generate[] $messages_to_generate
 	 */
-	public function batch_queue_for_generation_and_persist( $messages_to_generate ) {
+	public function batch_queue_for_generation_and_persist($messages_to_generate) {
 		$this->_init_queue_and_generator();
-		$this->_queue_for_generation_loop( $messages_to_generate );
+		$this->_queue_for_generation_loop($messages_to_generate);
 		$this->_queue->save();
 	}
 
@@ -303,9 +303,9 @@ 
 	 *
 	 * @param EE_Message_To_Generate[]  $messages_to_generate
 	 */
-	public function batch_queue_for_generation_no_persist( $messages_to_generate ) {
+	public function batch_queue_for_generation_no_persist($messages_to_generate) {
 		$this->_init_queue_and_generator();
-		$this->_queue_for_generation_loop( $messages_to_generate );
+		$this->_queue_for_generation_loop($messages_to_generate);
 	}
 
 
@@ -317,15 +317,15 @@ 
 	 *
 	 * @param EE_Message_To_Generate[] $messages_to_generate
 	 */
-	protected function _queue_for_generation_loop( $messages_to_generate ) {
+	protected function _queue_for_generation_loop($messages_to_generate) {
 		//make sure is in an array.
-		if ( ! is_array( $messages_to_generate ) ) {
-			$messages_to_generate = array( $messages_to_generate );
+		if ( ! is_array($messages_to_generate)) {
+			$messages_to_generate = array($messages_to_generate);
 		}
 
-		foreach ( $messages_to_generate as $message_to_generate ) {
-			if ( $message_to_generate instanceof EE_Message_To_Generate && $message_to_generate->valid() ) {
-				$this->queue_for_generation( $message_to_generate );
+		foreach ($messages_to_generate as $message_to_generate) {
+			if ($message_to_generate instanceof EE_Message_To_Generate && $message_to_generate->valid()) {
+				$this->queue_for_generation($message_to_generate);
 			}
 		}
 	}
@@ -340,10 +340,10 @@ 
 	 * @param  EE_Message_To_Generate[]
 	 * @return EE_Messages_Queue
 	 */
-	public function generate_and_queue_for_sending( $messages_to_generate ) {
+	public function generate_and_queue_for_sending($messages_to_generate) {
 		$this->_init_queue_and_generator();
-		$this->_queue_for_generation_loop( $messages_to_generate );
-		return $this->_generator->generate( true );
+		$this->_queue_for_generation_loop($messages_to_generate);
+		return $this->_generator->generate(true);
 	}
 
 
@@ -357,10 +357,10 @@ 
 	 * @param   bool                   $test_send                Whether this is a test send or not.
 	 * @return  EE_Messages_Queue | bool   false if unable to generate otherwise the generated queue.
 	 */
-	public function generate_for_preview( EE_Message_To_Generate $message_to_generate, $test_send = false ) {
-		if ( ! $message_to_generate->valid() ) {
+	public function generate_for_preview(EE_Message_To_Generate $message_to_generate, $test_send = false) {
+		if ( ! $message_to_generate->valid()) {
 			EE_Error::add_error(
-				__( 'Unable to generate preview because of invalid data', 'event_espresso' ),
+				__('Unable to generate preview because of invalid data', 'event_espresso'),
 				__FILE__,
 				__FUNCTION__,
 				__LINE__
@@ -368,14 +368,14 @@ 
 			return false;
 		}
 		//just make sure preview is set on the $message_to_generate (in case client forgot)
-		$message_to_generate->set_preview( true );
+		$message_to_generate->set_preview(true);
 		$this->_init_queue_and_generator();
-		$this->queue_for_generation( $message_to_generate, $test_send );
-		$generated_queue = $this->_generator->generate( false );
-		if ( $generated_queue->execute( false ) ) {
+		$this->queue_for_generation($message_to_generate, $test_send);
+		$generated_queue = $this->_generator->generate(false);
+		if ($generated_queue->execute(false)) {
 			//the first queue item should be the preview
 			$generated_queue->get_message_repository()->rewind();
-			if ( ! $generated_queue->get_message_repository()->valid() ) {
+			if ( ! $generated_queue->get_message_repository()->valid()) {
 				return $generated_queue;
 			}
 			return $generated_queue;
@@ -392,15 +392,15 @@ 
 	 * @param EE_Message_To_Generate $message_to_generate
 	 * @return bool true or false for success.
 	 */
-	public function queue_for_sending( EE_Message_To_Generate $message_to_generate ) {
-		if ( ! $message_to_generate->valid() ) {
+	public function queue_for_sending(EE_Message_To_Generate $message_to_generate) {
+		if ( ! $message_to_generate->valid()) {
 			return false;
 		}
 		$this->_init_queue_and_generator();
 		$message = $message_to_generate->get_EE_Message();
-		$this->_queue->add( $message );
-		if ( $message->send_now() ) {
-			$this->_queue->execute( false );
+		$this->_queue->add($message);
+		if ($message->send_now()) {
+			$this->_queue->execute(false);
 		} else {
 			$this->_queue->save();
 		}
@@ -413,12 +413,12 @@ 
 	 * @param EE_Message_To_Generate $message_to_generate
 	 * @return EE_Messages_Queue | null
 	 */
-	public function generate_and_send_now( EE_Message_To_Generate $message_to_generate ) {
-		if ( ! $message_to_generate->valid() ) {
+	public function generate_and_send_now(EE_Message_To_Generate $message_to_generate) {
+		if ( ! $message_to_generate->valid()) {
 			return null;
 		}
 		// is there supposed to be a sending messenger for this message?
-		if ( $message_to_generate instanceof EEI_Has_Sending_Messenger ) {
+		if ($message_to_generate instanceof EEI_Has_Sending_Messenger) {
 			// make sure it's valid, but if it's not,
 			// then set the value of $sending_messenger to an EE_Error object
 			// so that downstream code can easily see that things went wrong.
@@ -434,14 +434,14 @@ 
 			$sending_messenger = null;
 		}
 
-		if ( $message_to_generate->get_EE_Message()->STS_ID() === EEM_Message::status_idle ) {
+		if ($message_to_generate->get_EE_Message()->STS_ID() === EEM_Message::status_idle) {
 			$this->_init_queue_and_generator();
-			$this->_queue->add( $message_to_generate->get_EE_Message() );
-			$this->_queue->execute( false, $sending_messenger );
+			$this->_queue->add($message_to_generate->get_EE_Message());
+			$this->_queue->execute(false, $sending_messenger);
 			return $this->_queue;
-		} elseif ( $message_to_generate->get_EE_Message()->STS_ID() === EEM_Message::status_incomplete ) {
-			$generated_queue = $this->generate_and_return( array( $message_to_generate ) );
-			$generated_queue->execute( false, $sending_messenger );
+		} elseif ($message_to_generate->get_EE_Message()->STS_ID() === EEM_Message::status_incomplete) {
+			$generated_queue = $this->generate_and_return(array($message_to_generate));
+			$generated_queue->execute(false, $sending_messenger);
 			return $generated_queue;
 		}
 		return null;
@@ -458,13 +458,13 @@ 
 	 * @param mixed  $data   The data being used for generation.
 	 * @param bool   $persist   Whether to persist the queued messages to the db or not.
 	 */
-	public function generate_for_all_active_messengers( $message_type, $data, $persist = true ) {
-		$messages_to_generate = $this->setup_mtgs_for_all_active_messengers( $message_type, $data );
-		if ( $persist ) {
-			$this->batch_queue_for_generation_and_persist( $messages_to_generate );
+	public function generate_for_all_active_messengers($message_type, $data, $persist = true) {
+		$messages_to_generate = $this->setup_mtgs_for_all_active_messengers($message_type, $data);
+		if ($persist) {
+			$this->batch_queue_for_generation_and_persist($messages_to_generate);
 			$this->_queue->initiate_request_by_priority();
 		} else {
-			$this->batch_queue_for_generation_no_persist( $messages_to_generate );
+			$this->batch_queue_for_generation_no_persist($messages_to_generate);
 		}
 	}
 
@@ -479,11 +479,11 @@ 
 	 *
 	 * @return EE_Message_To_Generate[]
 	 */
-	public function setup_mtgs_for_all_active_messengers( $message_type, $data ) {
+	public function setup_mtgs_for_all_active_messengers($message_type, $data) {
 		$messages_to_generate = array();
-		foreach ( $this->_message_resource_manager->active_messengers() as $messenger_slug => $messenger_object  ) {
-			$message_to_generate = new EE_Message_To_Generate( $messenger_slug, $message_type, $data );
-			if ( $message_to_generate->valid() ) {
+		foreach ($this->_message_resource_manager->active_messengers() as $messenger_slug => $messenger_object) {
+			$message_to_generate = new EE_Message_To_Generate($messenger_slug, $message_type, $data);
+			if ($message_to_generate->valid()) {
 				$messages_to_generate[] = $message_to_generate;
 			}
 		}
@@ -498,29 +498,29 @@ 
 	 * and send.
 	 * @param array $message_ids
 	 */
-	public function setup_messages_from_ids_and_send( $message_ids ) {
+	public function setup_messages_from_ids_and_send($message_ids) {
 		$this->_init_queue_and_generator();
-		$messages = EEM_Message::instance()->get_all( array(
+		$messages = EEM_Message::instance()->get_all(array(
 			array(
-				'MSG_ID' => array( 'IN', $message_ids ),
+				'MSG_ID' => array('IN', $message_ids),
 				'STS_ID' => array(
 					'IN',
 					array_merge(
 						EEM_Message::instance()->stati_indicating_sent(),
-						array( EEM_Message::status_retry )
+						array(EEM_Message::status_retry)
 					),
 				),
 			),
 		));
 		//set the Messages to resend.
-		foreach ( $messages as $message ) {
-			if ( $message instanceof EE_Message ) {
-				$message->set_STS_ID( EEM_Message::status_resend );
-				$this->_queue->add( $message );
+		foreach ($messages as $message) {
+			if ($message instanceof EE_Message) {
+				$message->set_STS_ID(EEM_Message::status_resend);
+				$this->_queue->add($message);
 			}
 		}
 
-		$this->_queue->initiate_request_by_priority( 'send' );
+		$this->_queue->initiate_request_by_priority('send');
 	}
 
 
@@ -534,23 +534,23 @@ 
 	 *
 	 * @return EE_Message_To_Generate[]
 	 */
-	public function setup_messages_to_generate_from_registration_ids_in_request( $registration_ids_key = '_REG_ID' ) {
-		EE_Registry::instance()->load_core( 'Request_Handler' );
-		EE_Registry::instance()->load_helper( 'MSG_Template' );
+	public function setup_messages_to_generate_from_registration_ids_in_request($registration_ids_key = '_REG_ID') {
+		EE_Registry::instance()->load_core('Request_Handler');
+		EE_Registry::instance()->load_helper('MSG_Template');
 		$regs_to_send = array();
-		$regIDs = EE_Registry::instance()->REQ->get( $registration_ids_key );
-		if ( empty( $regIDs ) ) {
-			EE_Error::add_error( __('Something went wrong because we\'re missing the registration ID', 'event_espresso'), __FILE__, __FUNCTION__, __LINE__ );
+		$regIDs = EE_Registry::instance()->REQ->get($registration_ids_key);
+		if (empty($regIDs)) {
+			EE_Error::add_error(__('Something went wrong because we\'re missing the registration ID', 'event_espresso'), __FILE__, __FUNCTION__, __LINE__);
 			return false;
 		}
 
 		//make sure is an array
-		$regIDs = is_array( $regIDs ) ? $regIDs : array( $regIDs );
+		$regIDs = is_array($regIDs) ? $regIDs : array($regIDs);
 
-		foreach( $regIDs as $regID ) {
-			$reg = EEM_Registration::instance()->get_one_by_ID( $regID );
-			if ( ! $reg instanceof EE_Registration ) {
-				EE_Error::add_error( sprintf( __('Unable to retrieve a registration object for the given reg id (%s)', 'event_espresso'), $regID ) );
+		foreach ($regIDs as $regID) {
+			$reg = EEM_Registration::instance()->get_one_by_ID($regID);
+			if ( ! $reg instanceof EE_Registration) {
+				EE_Error::add_error(sprintf(__('Unable to retrieve a registration object for the given reg id (%s)', 'event_espresso'), $regID));
 				return false;
 			}
 			$regs_to_send[$reg->transaction_ID()][$reg->status_ID()][] = $reg;
@@ -558,17 +558,17 @@ 
 
 		$messages_to_generate = array();
 
-		foreach ( $regs_to_send as $status_group ) {
-			foreach ( $status_group as $status_id => $registrations ) {
+		foreach ($regs_to_send as $status_group) {
+			foreach ($status_group as $status_id => $registrations) {
 			    $message_type = EEH_MSG_Template::convert_reg_status_to_message_type($status_id);
-			    if (! $message_type) {
+			    if ( ! $message_type) {
 			        continue;
                 }
 				$messages_to_generate = array_merge(
 					$messages_to_generate,
 					$this->setup_mtgs_for_all_active_messengers(
 						$message_type,
-						array( $registrations, $status_id )
+						array($registrations, $status_id)
 					)
 				);
 			}

core/domain/entities/Context.php

Indentation +58 added lines, -58 removed lines

@@ -18,64 +18,64 @@
 class Context
 {
 
-    /**
-     * @var string $slug
-     */
-    private $slug;
-
-    /**
-     * @var string $description
-     */
-    private $description;
-
-
-    /**
-     * Context constructor.
-     *
-     * @param string $slug
-     * @param string $description
-     */
-    public function __construct($slug, $description)
-    {
-        $this->setSlug($slug);
-        $this->setDescription($description);
-    }
-
-
-    /**
-     * @return string
-     */
-    public function slug()
-    {
-        return $this->slug;
-    }
-
-
-    /**
-     * @param string $slug
-     */
-    private function setSlug($slug)
-    {
-        $this->slug = sanitize_key($slug);
-    }
-
-
-    /**
-     * @return string
-     */
-    public function description()
-    {
-        return $this->description;
-    }
-
-
-    /**
-     * @param string $description
-     */
-    private function setDescription($description)
-    {
-        $this->description = sanitize_text_field($description);
-    }
+	/**
+	 * @var string $slug
+	 */
+	private $slug;
+
+	/**
+	 * @var string $description
+	 */
+	private $description;
+
+
+	/**
+	 * Context constructor.
+	 *
+	 * @param string $slug
+	 * @param string $description
+	 */
+	public function __construct($slug, $description)
+	{
+		$this->setSlug($slug);
+		$this->setDescription($description);
+	}
+
+
+	/**
+	 * @return string
+	 */
+	public function slug()
+	{
+		return $this->slug;
+	}
+
+
+	/**
+	 * @param string $slug
+	 */
+	private function setSlug($slug)
+	{
+		$this->slug = sanitize_key($slug);
+	}
+
+
+	/**
+	 * @return string
+	 */
+	public function description()
+	{
+		return $this->description;
+	}
+
+
+	/**
+	 * @param string $description
+	 */
+	private function setDescription($description)
+	{
+		$this->description = sanitize_text_field($description);
+	}
 
 }
 // Location: Context.php

core/domain/Domain.php

Indentation +8 added lines, -8 removed lines

@@ -15,13 +15,13 @@
  */
 class Domain extends DomainBase
 {
-    /**
-     * Slug used for the context where a registration status is changed from a manual trigger in the Registration Admin
-     * Page ui.
-     */
-    const CONTEXT_REGISTRATION_STATUS_CHANGE_REGISTRATION_ADMIN
-        = 'manual_registration_status_change_from_registration_admin';
+	/**
+	 * Slug used for the context where a registration status is changed from a manual trigger in the Registration Admin
+	 * Page ui.
+	 */
+	const CONTEXT_REGISTRATION_STATUS_CHANGE_REGISTRATION_ADMIN
+		= 'manual_registration_status_change_from_registration_admin';
 
-    const CONTEXT_REGISTRATION_STATUS_CHANGE_REGISTRATION_ADMIN_NOTIFY
-        = 'manual_registration_status_change_from_registration_admin_and_notify';
+	const CONTEXT_REGISTRATION_STATUS_CHANGE_REGISTRATION_ADMIN_NOTIFY
+		= 'manual_registration_status_change_from_registration_admin_and_notify';
 }

admin_pages/transactions/Transactions_Admin_Page.core.php

Indentation +1972 added lines, -1972 removed lines

@@ -1,5 +1,5 @@ 
 <?php if ( ! defined('EVENT_ESPRESSO_VERSION')) {
-    exit('No direct script access allowed');
+	exit('No direct script access allowed');
 }
 
 /**
@@ -27,1980 +27,1980 @@ 
 class Transactions_Admin_Page extends EE_Admin_Page
 {
 
-    /**
-     * @var EE_Transaction
-     */
-    private $_transaction;
-
-    /**
-     * @var EE_Session
-     */
-    private $_session;
-
-    /**
-     * @var array $_txn_status
-     */
-    private static $_txn_status;
-
-    /**
-     * @var array $_pay_status
-     */
-    private static $_pay_status;
-
-    /**
-     * @var array $_existing_reg_payment_REG_IDs
-     */
-    protected $_existing_reg_payment_REG_IDs = null;
-
-
-    /**
-     * @Constructor
-     * @access public
-     *
-     * @param bool $routing
-     *
-     * @return Transactions_Admin_Page
-     */
-    public function __construct($routing = true)
-    {
-        parent::__construct($routing);
-    }
-
-
-    /**
-     *    _init_page_props
-     * @return void
-     */
-    protected function _init_page_props()
-    {
-        $this->page_slug        = TXN_PG_SLUG;
-        $this->page_label       = esc_html__('Transactions', 'event_espresso');
-        $this->_admin_base_url  = TXN_ADMIN_URL;
-        $this->_admin_base_path = TXN_ADMIN;
-    }
-
-
-    /**
-     *    _ajax_hooks
-     * @return void
-     */
-    protected function _ajax_hooks()
-    {
-        add_action('wp_ajax_espresso_apply_payment', array($this, 'apply_payments_or_refunds'));
-        add_action('wp_ajax_espresso_apply_refund', array($this, 'apply_payments_or_refunds'));
-        add_action('wp_ajax_espresso_delete_payment', array($this, 'delete_payment'));
-    }
-
-
-    /**
-     *    _define_page_props
-     * @return void
-     */
-    protected function _define_page_props()
-    {
-        $this->_admin_page_title = $this->page_label;
-        $this->_labels           = array(
-            'buttons' => array(
-                'add'    => esc_html__('Add New Transaction', 'event_espresso'),
-                'edit'   => esc_html__('Edit Transaction', 'event_espresso'),
-                'delete' => esc_html__('Delete Transaction', 'event_espresso'),
-            )
-        );
-    }
-
-
-    /**
-     *        grab url requests and route them
-     * @access private
-     * @return void
-     */
-    public function _set_page_routes()
-    {
-
-        $this->_set_transaction_status_array();
-
-        $txn_id = ! empty($this->_req_data['TXN_ID']) && ! is_array($this->_req_data['TXN_ID']) ? $this->_req_data['TXN_ID'] : 0;
-
-        $this->_page_routes = array(
-
-            'default' => array(
-                'func'       => '_transactions_overview_list_table',
-                'capability' => 'ee_read_transactions'
-            ),
-
-            'view_transaction' => array(
-                'func'       => '_transaction_details',
-                'capability' => 'ee_read_transaction',
-                'obj_id'     => $txn_id
-            ),
-
-            'send_payment_reminder' => array(
-                'func'       => '_send_payment_reminder',
-                'noheader'   => true,
-                'capability' => 'ee_send_message'
-            ),
-
-            'espresso_apply_payment' => array(
-                'func'       => 'apply_payments_or_refunds',
-                'noheader'   => true,
-                'capability' => 'ee_edit_payments'
-            ),
-
-            'espresso_apply_refund' => array(
-                'func'       => 'apply_payments_or_refunds',
-                'noheader'   => true,
-                'capability' => 'ee_edit_payments'
-            ),
-
-            'espresso_delete_payment' => array(
-                'func'       => 'delete_payment',
-                'noheader'   => true,
-                'capability' => 'ee_delete_payments'
-            ),
-
-        );
-
-    }
-
-
-    protected function _set_page_config()
-    {
-        $this->_page_config = array(
-            'default'          => array(
-                'nav'           => array(
-                    'label' => esc_html__('Overview', 'event_espresso'),
-                    'order' => 10
-                ),
-                'list_table'    => 'EE_Admin_Transactions_List_Table',
-                'help_tabs'     => array(
-                    'transactions_overview_help_tab'                       => array(
-                        'title'    => esc_html__('Transactions Overview', 'event_espresso'),
-                        'filename' => 'transactions_overview'
-                    ),
-                    'transactions_overview_table_column_headings_help_tab' => array(
-                        'title'    => esc_html__('Transactions Table Column Headings', 'event_espresso'),
-                        'filename' => 'transactions_overview_table_column_headings'
-                    ),
-                    'transactions_overview_views_filters_help_tab'         => array(
-                        'title'    => esc_html__('Transaction Views & Filters & Search', 'event_espresso'),
-                        'filename' => 'transactions_overview_views_filters_search'
-                    ),
-                ),
-                'help_tour'     => array('Transactions_Overview_Help_Tour'),
-                /**
-                 * commented out because currently we are not displaying tips for transaction list table status but this
-                 * may change in a later iteration so want to keep the code for then.
-                 */
-                //'qtips' => array( 'Transactions_List_Table_Tips' ),
-                'require_nonce' => false
-            ),
-            'view_transaction' => array(
-                'nav'       => array(
-                    'label'      => esc_html__('View Transaction', 'event_espresso'),
-                    'order'      => 5,
-                    'url'        => isset($this->_req_data['TXN_ID']) ? add_query_arg(array('TXN_ID' => $this->_req_data['TXN_ID']),
-                        $this->_current_page_view_url) : $this->_admin_base_url,
-                    'persistent' => false
-                ),
-                'help_tabs' => array(
-                    'transactions_view_transaction_help_tab'                                              => array(
-                        'title'    => esc_html__('View Transaction', 'event_espresso'),
-                        'filename' => 'transactions_view_transaction'
-                    ),
-                    'transactions_view_transaction_transaction_details_table_help_tab'                    => array(
-                        'title'    => esc_html__('Transaction Details Table', 'event_espresso'),
-                        'filename' => 'transactions_view_transaction_transaction_details_table'
-                    ),
-                    'transactions_view_transaction_attendees_registered_help_tab'                         => array(
-                        'title'    => esc_html__('Attendees Registered', 'event_espresso'),
-                        'filename' => 'transactions_view_transaction_attendees_registered'
-                    ),
-                    'transactions_view_transaction_views_primary_registrant_billing_information_help_tab' => array(
-                        'title'    => esc_html__('Primary Registrant & Billing Information', 'event_espresso'),
-                        'filename' => 'transactions_view_transaction_primary_registrant_billing_information'
-                    ),
-                ),
-                'qtips'     => array('Transaction_Details_Tips'),
-                'help_tour' => array('Transaction_Details_Help_Tour'),
-                'metaboxes' => array('_transaction_details_metaboxes'),
-
-                'require_nonce' => false
-            )
-        );
-    }
-
-
-    /**
-     * The below methods aren't used by this class currently
-     */
-    protected function _add_screen_options()
-    {
-    }
-
-    protected function _add_feature_pointers()
-    {
-    }
-
-    public function admin_init()
-    {
-        // IF a registration was JUST added via the admin...
-        if (
-        isset(
-            $this->_req_data['redirect_from'],
-            $this->_req_data['EVT_ID'],
-            $this->_req_data['event_name']
-        )
-        ) {
-            // then set a cookie so that we can block any attempts to use
-            // the back button as a way to enter another registration.
-            setcookie('ee_registration_added', $this->_req_data['EVT_ID'], time() + WEEK_IN_SECONDS, '/');
-            // and update the global
-            $_COOKIE['ee_registration_added'] = $this->_req_data['EVT_ID'];
-        }
-        EE_Registry::$i18n_js_strings['invalid_server_response'] = esc_html__('An error occurred! Your request may have been processed, but a valid response from the server was not received. Please refresh the page and try again.',
-            'event_espresso');
-        EE_Registry::$i18n_js_strings['error_occurred']          = esc_html__('An error occurred! Please refresh the page and try again.',
-            'event_espresso');
-        EE_Registry::$i18n_js_strings['txn_status_array']        = self::$_txn_status;
-        EE_Registry::$i18n_js_strings['pay_status_array']        = self::$_pay_status;
-        EE_Registry::$i18n_js_strings['payments_total']          = esc_html__('Payments Total', 'event_espresso');
-        EE_Registry::$i18n_js_strings['transaction_overpaid']    = esc_html__('This transaction has been overpaid ! Payments Total',
-            'event_espresso');
-    }
-
-    public function admin_notices()
-    {
-    }
-
-    public function admin_footer_scripts()
-    {
-    }
-
-
-    /**
-     * _set_transaction_status_array
-     * sets list of transaction statuses
-     *
-     * @access private
-     * @return void
-     */
-    private function _set_transaction_status_array()
-    {
-        self::$_txn_status = EEM_Transaction::instance()->status_array(true);
-    }
-
-
-    /**
-     * get_transaction_status_array
-     * return the transaction status array for wp_list_table
-     *
-     * @access public
-     * @return array
-     */
-    public function get_transaction_status_array()
-    {
-        return self::$_txn_status;
-    }
-
-
-    /**
-     *    get list of payment statuses
-     *
-     * @access private
-     * @return void
-     */
-    private function _get_payment_status_array()
-    {
-        self::$_pay_status                      = EEM_Payment::instance()->status_array(true);
-        $this->_template_args['payment_status'] = self::$_pay_status;
-
-    }
-
-
-    /**
-     *    _add_screen_options_default
-     *
-     * @access protected
-     * @return void
-     */
-    protected function _add_screen_options_default()
-    {
-        $this->_per_page_screen_option();
-    }
-
-
-    /**
-     * load_scripts_styles
-     *
-     * @access public
-     * @return void
-     */
-    public function load_scripts_styles()
-    {
-        //enqueue style
-        wp_register_style('espresso_txn', TXN_ASSETS_URL . 'espresso_transactions_admin.css', array(),
-            EVENT_ESPRESSO_VERSION);
-        wp_enqueue_style('espresso_txn');
-        //scripts
-        wp_register_script('espresso_txn', TXN_ASSETS_URL . 'espresso_transactions_admin.js', array(
-            'ee_admin_js',
-            'ee-datepicker',
-            'jquery-ui-datepicker',
-            'jquery-ui-draggable',
-            'ee-dialog',
-            'ee-accounting',
-            'ee-serialize-full-array'
-        ), EVENT_ESPRESSO_VERSION, true);
-        wp_enqueue_script('espresso_txn');
-
-    }
-
-
-    /**
-     *    load_scripts_styles_view_transaction
-     *
-     * @access public
-     * @return void
-     */
-    public function load_scripts_styles_view_transaction()
-    {
-        //styles
-        wp_enqueue_style('espresso-ui-theme');
-    }
-
-
-    /**
-     *    load_scripts_styles_default
-     *
-     * @access public
-     * @return void
-     */
-    public function load_scripts_styles_default()
-    {
-        //styles
-        wp_enqueue_style('espresso-ui-theme');
-    }
-
-
-    /**
-     *    _set_list_table_views_default
-     *
-     * @access protected
-     * @return void
-     */
-    protected function _set_list_table_views_default()
-    {
-        $this->_views = array(
-            'all'       => array(
-                'slug'  => 'all',
-                'label' => esc_html__('View All Transactions', 'event_espresso'),
-                'count' => 0
-            ),
-            'abandoned' => array(
-                'slug'  => 'abandoned',
-                'label' => esc_html__('Abandoned Transactions', 'event_espresso'),
-                'count' => 0
-            ),
-            'failed'    => array(
-                'slug'  => 'failed',
-                'label' => esc_html__('Failed Transactions', 'event_espresso'),
-                'count' => 0
-            )
-        );
-    }
-
-
-    /**
-     * _set_transaction_object
-     * This sets the _transaction property for the transaction details screen
-     *
-     * @access private
-     * @return void
-     */
-    private function _set_transaction_object()
-    {
-        if (is_object($this->_transaction)) {
-            return;
-        } //get out we've already set the object
-
-        $TXN = EEM_Transaction::instance();
-
-        $TXN_ID = ( ! empty($this->_req_data['TXN_ID'])) ? absint($this->_req_data['TXN_ID']) : false;
-
-        //get transaction object
-        $this->_transaction = $TXN->get_one_by_ID($TXN_ID);
-        $this->_session     = ! empty($this->_transaction) ? $this->_transaction->get('TXN_session_data') : null;
-        $this->_transaction->verify_abandoned_transaction_status();
-
-        if (empty($this->_transaction)) {
-            $error_msg = esc_html__('An error occurred and the details for Transaction ID #',
-                    'event_espresso') . $TXN_ID . esc_html__(' could not be retrieved.', 'event_espresso');
-            EE_Error::add_error($error_msg, __FILE__, __FUNCTION__, __LINE__);
-        }
-    }
-
-
-    /**
-     *    _transaction_legend_items
-     *
-     * @access protected
-     * @return array
-     */
-    protected function _transaction_legend_items()
-    {
-        EE_Registry::instance()->load_helper('MSG_Template');
-        $items = array();
-
-        if (EE_Registry::instance()->CAP->current_user_can('ee_read_global_messages', 'view_filtered_messages')) {
-            $related_for_icon = EEH_MSG_Template::get_message_action_icon('see_notifications_for');
-            if (isset($related_for_icon['css_class']) && isset($related_for_icon['label'])) {
-                $items['view_related_messages'] = array(
-                    'class' => $related_for_icon['css_class'],
-                    'desc'  => $related_for_icon['label'],
-                );
-            }
-        }
-
-        $items = apply_filters(
-            'FHEE__Transactions_Admin_Page___transaction_legend_items__items',
-            array_merge($items,
-                array(
-                    'view_details'      => array(
-                        'class' => 'dashicons dashicons-cart',
-                        'desc'  => esc_html__('View Transaction Details', 'event_espresso')
-                    ),
-                    'view_invoice'      => array(
-                        'class' => 'dashicons dashicons-media-spreadsheet',
-                        'desc'  => esc_html__('View Transaction Invoice', 'event_espresso')
-                    ),
-                    'view_receipt'      => array(
-                        'class' => 'dashicons dashicons-media-default',
-                        'desc'  => esc_html__('View Transaction Receipt', 'event_espresso')
-                    ),
-                    'view_registration' => array(
-                        'class' => 'dashicons dashicons-clipboard',
-                        'desc'  => esc_html__('View Registration Details', 'event_espresso')
-                    ),
-                    'payment_overview_link' => array(
-                        'class' => 'dashicons dashicons-money',
-                        'desc' => esc_html__('Make Payment on Frontend', 'event_espresso')
-                    )
-                )
-            )
-        );
-
-        if (EE_Registry::instance()->CAP->current_user_can('ee_send_message',
-            'espresso_transactions_send_payment_reminder')
-        ) {
-            if (EEH_MSG_Template::is_mt_active('payment_reminder')) {
-                $items['send_payment_reminder'] = array(
-                    'class' => 'dashicons dashicons-email-alt',
-                    'desc'  => esc_html__('Send Payment Reminder', 'event_espresso')
-                );
-            } else {
-                $items['blank*'] = array(
-                    'class' => '',
-                    'desc'  => ''
-                );
-            }
-        } else {
-            $items['blank*'] = array(
-                'class' => '',
-                'desc'  => ''
-            );
-        }
-        $more_items = apply_filters(
-            'FHEE__Transactions_Admin_Page___transaction_legend_items__more_items',
-            array(
-                'overpaid'   => array(
-                    'class' => 'ee-status-legend ee-status-legend-' . EEM_Transaction::overpaid_status_code,
-                    'desc'  => EEH_Template::pretty_status(EEM_Transaction::overpaid_status_code, false, 'sentence')
-                ),
-                'complete'   => array(
-                    'class' => 'ee-status-legend ee-status-legend-' . EEM_Transaction::complete_status_code,
-                    'desc'  => EEH_Template::pretty_status(EEM_Transaction::complete_status_code, false, 'sentence')
-                ),
-                'incomplete' => array(
-                    'class' => 'ee-status-legend ee-status-legend-' . EEM_Transaction::incomplete_status_code,
-                    'desc'  => EEH_Template::pretty_status(EEM_Transaction::incomplete_status_code, false, 'sentence')
-                ),
-                'abandoned'  => array(
-                    'class' => 'ee-status-legend ee-status-legend-' . EEM_Transaction::abandoned_status_code,
-                    'desc'  => EEH_Template::pretty_status(EEM_Transaction::abandoned_status_code, false, 'sentence')
-                ),
-                'failed'     => array(
-                    'class' => 'ee-status-legend ee-status-legend-' . EEM_Transaction::failed_status_code,
-                    'desc'  => EEH_Template::pretty_status(EEM_Transaction::failed_status_code, false, 'sentence')
-                )
-            )
-        );
-
-        return array_merge($items, $more_items);
-    }
-
-
-    /**
-     *    _transactions_overview_list_table
-     *
-     * @access protected
-     * @return void
-     */
-    protected function _transactions_overview_list_table()
-    {
-        $this->_admin_page_title                   = esc_html__('Transactions', 'event_espresso');
-        $event                                     = isset($this->_req_data['EVT_ID']) ? EEM_Event::instance()->get_one_by_ID($this->_req_data['EVT_ID']) : null;
-        $this->_template_args['admin_page_header'] = $event instanceof EE_Event ? sprintf(esc_html__('%sViewing Transactions for the Event: %s%s',
-            'event_espresso'), '<h3>',
-            '<a href="' . EE_Admin_Page::add_query_args_and_nonce(array('action' => 'edit', 'post' => $event->ID()),
-                EVENTS_ADMIN_URL) . '" title="' . esc_attr__('Click to Edit event',
-                'event_espresso') . '">' . $event->get('EVT_name') . '</a>', '</h3>') : '';
-        $this->_template_args['after_list_table']  = $this->_display_legend($this->_transaction_legend_items());
-        $this->display_admin_list_table_page_with_no_sidebar();
-    }
-
-
-    /**
-     *    _transaction_details
-     * generates HTML for the View Transaction Details Admin page
-     *
-     * @access protected
-     * @return void
-     */
-    protected function _transaction_details()
-    {
-        do_action('AHEE__Transactions_Admin_Page__transaction_details__start', $this->_transaction);
-
-        $this->_set_transaction_status_array();
-
-        $this->_template_args                      = array();
-        $this->_template_args['transactions_page'] = $this->_wp_page_slug;
-
-        $this->_set_transaction_object();
-
-        $primary_registration = $this->_transaction->primary_registration();
-        $attendee             = $primary_registration instanceof EE_Registration ? $primary_registration->attendee() : null;
-
-        $this->_template_args['txn_nmbr']['value'] = $this->_transaction->ID();
-        $this->_template_args['txn_nmbr']['label'] = esc_html__('Transaction Number', 'event_espresso');
-
-        $this->_template_args['txn_datetime']['value'] = $this->_transaction->get_i18n_datetime('TXN_timestamp');
-        $this->_template_args['txn_datetime']['label'] = esc_html__('Date', 'event_espresso');
-
-        $this->_template_args['txn_status']['value'] = self::$_txn_status[$this->_transaction->get('STS_ID')];
-        $this->_template_args['txn_status']['label'] = esc_html__('Transaction Status', 'event_espresso');
-        $this->_template_args['txn_status']['class'] = 'status-' . $this->_transaction->get('STS_ID');
-
-        $this->_template_args['grand_total'] = $this->_transaction->get('TXN_total');
-        $this->_template_args['total_paid']  = $this->_transaction->get('TXN_paid');
-
-        if (
-            $attendee instanceof EE_Attendee
-            && EE_Registry::instance()->CAP->current_user_can(
-                'ee_send_message',
-                'espresso_transactions_send_payment_reminder'
-            )
-        ) {
-            $this->_template_args['send_payment_reminder_button'] =
-                EEH_MSG_Template::is_mt_active('payment_reminder')
-                && $this->_transaction->get('STS_ID') != EEM_Transaction::complete_status_code
-                && $this->_transaction->get('STS_ID') != EEM_Transaction::overpaid_status_code
-                    ? EEH_Template::get_button_or_link(
-                    EE_Admin_Page::add_query_args_and_nonce(
-                        array(
-                            'action'      => 'send_payment_reminder',
-                            'TXN_ID'      => $this->_transaction->ID(),
-                            'redirect_to' => 'view_transaction'
-                        ),
-                        TXN_ADMIN_URL
-                    ),
-                    __(' Send Payment Reminder', 'event_espresso'),
-                    'button secondary-button right',
-                    'dashicons dashicons-email-alt'
-                )
-                    : '';
-        } else {
-            $this->_template_args['send_payment_reminder_button'] = '';
-        }
-
-        $amount_due                         = $this->_transaction->get('TXN_total') - $this->_transaction->get('TXN_paid');
-        $this->_template_args['amount_due'] = EEH_Template::format_currency($amount_due, true);
-        if (EE_Registry::instance()->CFG->currency->sign_b4) {
-            $this->_template_args['amount_due'] = EE_Registry::instance()->CFG->currency->sign . $this->_template_args['amount_due'];
-        } else {
-            $this->_template_args['amount_due'] = $this->_template_args['amount_due'] . EE_Registry::instance()->CFG->currency->sign;
-        }
-        $this->_template_args['amount_due_class'] = '';
-
-        if ($this->_transaction->get('TXN_paid') == $this->_transaction->get('TXN_total')) {
-            // paid in full
-            $this->_template_args['amount_due'] = false;
-        } elseif ($this->_transaction->get('TXN_paid') > $this->_transaction->get('TXN_total')) {
-            // overpaid
-            $this->_template_args['amount_due_class'] = 'txn-overview-no-payment-spn';
-        } elseif (($this->_transaction->get('TXN_total') > 0) && ($this->_transaction->get('TXN_paid') > 0)) {
-            // monies owing
-            $this->_template_args['amount_due_class'] = 'txn-overview-part-payment-spn';
-        } elseif (($this->_transaction->get('TXN_total') > 0) && ($this->_transaction->get('TXN_paid') == 0)) {
-            // no payments made yet
-            $this->_template_args['amount_due_class'] = 'txn-overview-no-payment-spn';
-        } elseif ($this->_transaction->get('TXN_total') == 0) {
-            // free event
-            $this->_template_args['amount_due'] = false;
-        }
-
-        $payment_method = $this->_transaction->payment_method();
-
-        $this->_template_args['method_of_payment_name'] = $payment_method instanceof EE_Payment_Method
-            ? $payment_method->admin_name()
-            : esc_html__('Unknown', 'event_espresso');
-
-        $this->_template_args['currency_sign'] = EE_Registry::instance()->CFG->currency->sign;
-        // link back to overview
-        $this->_template_args['txn_overview_url'] = ! empty ($_SERVER['HTTP_REFERER'])
-            ? $_SERVER['HTTP_REFERER']
-            : TXN_ADMIN_URL;
-
-
-        // next link
-        $next_txn                                 = $this->_transaction->next(
-            null,
-            array(array('STS_ID' => array('!=', EEM_Transaction::failed_status_code))),
-            'TXN_ID'
-        );
-        $this->_template_args['next_transaction'] = $next_txn
-            ? $this->_next_link(
-                EE_Admin_Page::add_query_args_and_nonce(
-                    array('action' => 'view_transaction', 'TXN_ID' => $next_txn['TXN_ID']),
-                    TXN_ADMIN_URL
-                ),
-                'dashicons dashicons-arrow-right ee-icon-size-22'
-            )
-            : '';
-        // previous link
-        $previous_txn                                 = $this->_transaction->previous(
-            null,
-            array(array('STS_ID' => array('!=', EEM_Transaction::failed_status_code))),
-            'TXN_ID'
-        );
-        $this->_template_args['previous_transaction'] = $previous_txn
-            ? $this->_previous_link(
-                EE_Admin_Page::add_query_args_and_nonce(
-                    array('action' => 'view_transaction', 'TXN_ID' => $previous_txn['TXN_ID']),
-                    TXN_ADMIN_URL
-                ),
-                'dashicons dashicons-arrow-left ee-icon-size-22'
-            )
-            : '';
-
-        // were we just redirected here after adding a new registration ???
-        if (
-        isset(
-            $this->_req_data['redirect_from'],
-            $this->_req_data['EVT_ID'],
-            $this->_req_data['event_name']
-        )
-        ) {
-            if (
-            EE_Registry::instance()->CAP->current_user_can(
-                'ee_edit_registrations',
-                'espresso_registrations_new_registration',
-                $this->_req_data['EVT_ID']
-            )
-            ) {
-                $this->_admin_page_title .= '<a id="add-new-registration" class="add-new-h2 button-primary" href="';
-                $this->_admin_page_title .= EE_Admin_Page::add_query_args_and_nonce(
-                    array(
-                        'page'     => 'espresso_registrations',
-                        'action'   => 'new_registration',
-                        'return'   => 'default',
-                        'TXN_ID'   => $this->_transaction->ID(),
-                        'event_id' => $this->_req_data['EVT_ID'],
-                    ),
-                    REG_ADMIN_URL
-                );
-                $this->_admin_page_title .= '">';
-
-                $this->_admin_page_title .= sprintf(
-                    esc_html__('Add Another New Registration to Event: "%1$s" ?', 'event_espresso'),
-                    htmlentities(urldecode($this->_req_data['event_name']), ENT_QUOTES, 'UTF-8')
-                );
-                $this->_admin_page_title .= '</a>';
-            }
-            EE_Registry::instance()->SSN->clear_session(__CLASS__, __FUNCTION__);
-        }
-        // grab messages at the last second
-        $this->_template_args['notices'] = EE_Error::get_notices();
-        // path to template
-        $template_path                             = TXN_TEMPLATE_PATH . 'txn_admin_details_header.template.php';
-        $this->_template_args['admin_page_header'] = EEH_Template::display_template($template_path,
-            $this->_template_args, true);
-
-        // the details template wrapper
-        $this->display_admin_page_with_sidebar();
-
-    }
-
-
-    /**
-     *        _transaction_details_metaboxes
-     *
-     * @access protected
-     * @return void
-     */
-    protected function _transaction_details_metaboxes()
-    {
-
-        $this->_set_transaction_object();
-
-        add_meta_box('edit-txn-details-mbox', esc_html__('Transaction Details', 'event_espresso'),
-            array($this, 'txn_details_meta_box'), $this->_wp_page_slug, 'normal', 'high');
-        add_meta_box(
-            'edit-txn-attendees-mbox',
-            esc_html__('Attendees Registered in this Transaction', 'event_espresso'),
-            array($this, 'txn_attendees_meta_box'),
-            $this->_wp_page_slug,
-            'normal',
-            'high',
-            array('TXN_ID' => $this->_transaction->ID())
-        );
-        add_meta_box('edit-txn-registrant-mbox', esc_html__('Primary Contact', 'event_espresso'),
-            array($this, 'txn_registrant_side_meta_box'), $this->_wp_page_slug, 'side', 'high');
-        add_meta_box('edit-txn-billing-info-mbox', esc_html__('Billing Information', 'event_espresso'),
-            array($this, 'txn_billing_info_side_meta_box'), $this->_wp_page_slug, 'side', 'high');
-
-    }
-
-
-    /**
-     * txn_details_meta_box
-     * generates HTML for the Transaction main meta box
-     *
-     * @access public
-     * @return void
-     */
-    public function txn_details_meta_box()
-    {
-
-        $this->_set_transaction_object();
-        $this->_template_args['TXN_ID']   = $this->_transaction->ID();
-        $this->_template_args['attendee'] = $this->_transaction->primary_registration() instanceof EE_Registration ? $this->_transaction->primary_registration()->attendee() : null;
-
-        //get line table
-        EEH_Autoloader::register_line_item_display_autoloaders();
-        $Line_Item_Display                       = new EE_Line_Item_Display('admin_table',
-            'EE_Admin_Table_Line_Item_Display_Strategy');
-        $this->_template_args['line_item_table'] = $Line_Item_Display->display_line_item($this->_transaction->total_line_item());
-        $this->_template_args['REG_code']        = $this->_transaction->get_first_related('Registration')->get('REG_code');
-
-        // process taxes
-        $taxes                         = $this->_transaction->get_many_related('Line_Item',
-            array(array('LIN_type' => EEM_Line_Item::type_tax)));
-        $this->_template_args['taxes'] = ! empty($taxes) ? $taxes : false;
-
-        $this->_template_args['grand_total']     = EEH_Template::format_currency($this->_transaction->get('TXN_total'),
-            false, false);
-        $this->_template_args['grand_raw_total'] = $this->_transaction->get('TXN_total');
-        $this->_template_args['TXN_status']      = $this->_transaction->get('STS_ID');
+	/**
+	 * @var EE_Transaction
+	 */
+	private $_transaction;
+
+	/**
+	 * @var EE_Session
+	 */
+	private $_session;
+
+	/**
+	 * @var array $_txn_status
+	 */
+	private static $_txn_status;
+
+	/**
+	 * @var array $_pay_status
+	 */
+	private static $_pay_status;
+
+	/**
+	 * @var array $_existing_reg_payment_REG_IDs
+	 */
+	protected $_existing_reg_payment_REG_IDs = null;
+
+
+	/**
+	 * @Constructor
+	 * @access public
+	 *
+	 * @param bool $routing
+	 *
+	 * @return Transactions_Admin_Page
+	 */
+	public function __construct($routing = true)
+	{
+		parent::__construct($routing);
+	}
+
+
+	/**
+	 *    _init_page_props
+	 * @return void
+	 */
+	protected function _init_page_props()
+	{
+		$this->page_slug        = TXN_PG_SLUG;
+		$this->page_label       = esc_html__('Transactions', 'event_espresso');
+		$this->_admin_base_url  = TXN_ADMIN_URL;
+		$this->_admin_base_path = TXN_ADMIN;
+	}
+
+
+	/**
+	 *    _ajax_hooks
+	 * @return void
+	 */
+	protected function _ajax_hooks()
+	{
+		add_action('wp_ajax_espresso_apply_payment', array($this, 'apply_payments_or_refunds'));
+		add_action('wp_ajax_espresso_apply_refund', array($this, 'apply_payments_or_refunds'));
+		add_action('wp_ajax_espresso_delete_payment', array($this, 'delete_payment'));
+	}
+
+
+	/**
+	 *    _define_page_props
+	 * @return void
+	 */
+	protected function _define_page_props()
+	{
+		$this->_admin_page_title = $this->page_label;
+		$this->_labels           = array(
+			'buttons' => array(
+				'add'    => esc_html__('Add New Transaction', 'event_espresso'),
+				'edit'   => esc_html__('Edit Transaction', 'event_espresso'),
+				'delete' => esc_html__('Delete Transaction', 'event_espresso'),
+			)
+		);
+	}
+
+
+	/**
+	 *        grab url requests and route them
+	 * @access private
+	 * @return void
+	 */
+	public function _set_page_routes()
+	{
+
+		$this->_set_transaction_status_array();
+
+		$txn_id = ! empty($this->_req_data['TXN_ID']) && ! is_array($this->_req_data['TXN_ID']) ? $this->_req_data['TXN_ID'] : 0;
+
+		$this->_page_routes = array(
+
+			'default' => array(
+				'func'       => '_transactions_overview_list_table',
+				'capability' => 'ee_read_transactions'
+			),
+
+			'view_transaction' => array(
+				'func'       => '_transaction_details',
+				'capability' => 'ee_read_transaction',
+				'obj_id'     => $txn_id
+			),
+
+			'send_payment_reminder' => array(
+				'func'       => '_send_payment_reminder',
+				'noheader'   => true,
+				'capability' => 'ee_send_message'
+			),
+
+			'espresso_apply_payment' => array(
+				'func'       => 'apply_payments_or_refunds',
+				'noheader'   => true,
+				'capability' => 'ee_edit_payments'
+			),
+
+			'espresso_apply_refund' => array(
+				'func'       => 'apply_payments_or_refunds',
+				'noheader'   => true,
+				'capability' => 'ee_edit_payments'
+			),
+
+			'espresso_delete_payment' => array(
+				'func'       => 'delete_payment',
+				'noheader'   => true,
+				'capability' => 'ee_delete_payments'
+			),
+
+		);
+
+	}
+
+
+	protected function _set_page_config()
+	{
+		$this->_page_config = array(
+			'default'          => array(
+				'nav'           => array(
+					'label' => esc_html__('Overview', 'event_espresso'),
+					'order' => 10
+				),
+				'list_table'    => 'EE_Admin_Transactions_List_Table',
+				'help_tabs'     => array(
+					'transactions_overview_help_tab'                       => array(
+						'title'    => esc_html__('Transactions Overview', 'event_espresso'),
+						'filename' => 'transactions_overview'
+					),
+					'transactions_overview_table_column_headings_help_tab' => array(
+						'title'    => esc_html__('Transactions Table Column Headings', 'event_espresso'),
+						'filename' => 'transactions_overview_table_column_headings'
+					),
+					'transactions_overview_views_filters_help_tab'         => array(
+						'title'    => esc_html__('Transaction Views & Filters & Search', 'event_espresso'),
+						'filename' => 'transactions_overview_views_filters_search'
+					),
+				),
+				'help_tour'     => array('Transactions_Overview_Help_Tour'),
+				/**
+				 * commented out because currently we are not displaying tips for transaction list table status but this
+				 * may change in a later iteration so want to keep the code for then.
+				 */
+				//'qtips' => array( 'Transactions_List_Table_Tips' ),
+				'require_nonce' => false
+			),
+			'view_transaction' => array(
+				'nav'       => array(
+					'label'      => esc_html__('View Transaction', 'event_espresso'),
+					'order'      => 5,
+					'url'        => isset($this->_req_data['TXN_ID']) ? add_query_arg(array('TXN_ID' => $this->_req_data['TXN_ID']),
+						$this->_current_page_view_url) : $this->_admin_base_url,
+					'persistent' => false
+				),
+				'help_tabs' => array(
+					'transactions_view_transaction_help_tab'                                              => array(
+						'title'    => esc_html__('View Transaction', 'event_espresso'),
+						'filename' => 'transactions_view_transaction'
+					),
+					'transactions_view_transaction_transaction_details_table_help_tab'                    => array(
+						'title'    => esc_html__('Transaction Details Table', 'event_espresso'),
+						'filename' => 'transactions_view_transaction_transaction_details_table'
+					),
+					'transactions_view_transaction_attendees_registered_help_tab'                         => array(
+						'title'    => esc_html__('Attendees Registered', 'event_espresso'),
+						'filename' => 'transactions_view_transaction_attendees_registered'
+					),
+					'transactions_view_transaction_views_primary_registrant_billing_information_help_tab' => array(
+						'title'    => esc_html__('Primary Registrant & Billing Information', 'event_espresso'),
+						'filename' => 'transactions_view_transaction_primary_registrant_billing_information'
+					),
+				),
+				'qtips'     => array('Transaction_Details_Tips'),
+				'help_tour' => array('Transaction_Details_Help_Tour'),
+				'metaboxes' => array('_transaction_details_metaboxes'),
+
+				'require_nonce' => false
+			)
+		);
+	}
+
+
+	/**
+	 * The below methods aren't used by this class currently
+	 */
+	protected function _add_screen_options()
+	{
+	}
+
+	protected function _add_feature_pointers()
+	{
+	}
+
+	public function admin_init()
+	{
+		// IF a registration was JUST added via the admin...
+		if (
+		isset(
+			$this->_req_data['redirect_from'],
+			$this->_req_data['EVT_ID'],
+			$this->_req_data['event_name']
+		)
+		) {
+			// then set a cookie so that we can block any attempts to use
+			// the back button as a way to enter another registration.
+			setcookie('ee_registration_added', $this->_req_data['EVT_ID'], time() + WEEK_IN_SECONDS, '/');
+			// and update the global
+			$_COOKIE['ee_registration_added'] = $this->_req_data['EVT_ID'];
+		}
+		EE_Registry::$i18n_js_strings['invalid_server_response'] = esc_html__('An error occurred! Your request may have been processed, but a valid response from the server was not received. Please refresh the page and try again.',
+			'event_espresso');
+		EE_Registry::$i18n_js_strings['error_occurred']          = esc_html__('An error occurred! Please refresh the page and try again.',
+			'event_espresso');
+		EE_Registry::$i18n_js_strings['txn_status_array']        = self::$_txn_status;
+		EE_Registry::$i18n_js_strings['pay_status_array']        = self::$_pay_status;
+		EE_Registry::$i18n_js_strings['payments_total']          = esc_html__('Payments Total', 'event_espresso');
+		EE_Registry::$i18n_js_strings['transaction_overpaid']    = esc_html__('This transaction has been overpaid ! Payments Total',
+			'event_espresso');
+	}
+
+	public function admin_notices()
+	{
+	}
+
+	public function admin_footer_scripts()
+	{
+	}
+
+
+	/**
+	 * _set_transaction_status_array
+	 * sets list of transaction statuses
+	 *
+	 * @access private
+	 * @return void
+	 */
+	private function _set_transaction_status_array()
+	{
+		self::$_txn_status = EEM_Transaction::instance()->status_array(true);
+	}
+
+
+	/**
+	 * get_transaction_status_array
+	 * return the transaction status array for wp_list_table
+	 *
+	 * @access public
+	 * @return array
+	 */
+	public function get_transaction_status_array()
+	{
+		return self::$_txn_status;
+	}
+
+
+	/**
+	 *    get list of payment statuses
+	 *
+	 * @access private
+	 * @return void
+	 */
+	private function _get_payment_status_array()
+	{
+		self::$_pay_status                      = EEM_Payment::instance()->status_array(true);
+		$this->_template_args['payment_status'] = self::$_pay_status;
+
+	}
+
+
+	/**
+	 *    _add_screen_options_default
+	 *
+	 * @access protected
+	 * @return void
+	 */
+	protected function _add_screen_options_default()
+	{
+		$this->_per_page_screen_option();
+	}
+
+
+	/**
+	 * load_scripts_styles
+	 *
+	 * @access public
+	 * @return void
+	 */
+	public function load_scripts_styles()
+	{
+		//enqueue style
+		wp_register_style('espresso_txn', TXN_ASSETS_URL . 'espresso_transactions_admin.css', array(),
+			EVENT_ESPRESSO_VERSION);
+		wp_enqueue_style('espresso_txn');
+		//scripts
+		wp_register_script('espresso_txn', TXN_ASSETS_URL . 'espresso_transactions_admin.js', array(
+			'ee_admin_js',
+			'ee-datepicker',
+			'jquery-ui-datepicker',
+			'jquery-ui-draggable',
+			'ee-dialog',
+			'ee-accounting',
+			'ee-serialize-full-array'
+		), EVENT_ESPRESSO_VERSION, true);
+		wp_enqueue_script('espresso_txn');
+
+	}
+
+
+	/**
+	 *    load_scripts_styles_view_transaction
+	 *
+	 * @access public
+	 * @return void
+	 */
+	public function load_scripts_styles_view_transaction()
+	{
+		//styles
+		wp_enqueue_style('espresso-ui-theme');
+	}
+
+
+	/**
+	 *    load_scripts_styles_default
+	 *
+	 * @access public
+	 * @return void
+	 */
+	public function load_scripts_styles_default()
+	{
+		//styles
+		wp_enqueue_style('espresso-ui-theme');
+	}
+
+
+	/**
+	 *    _set_list_table_views_default
+	 *
+	 * @access protected
+	 * @return void
+	 */
+	protected function _set_list_table_views_default()
+	{
+		$this->_views = array(
+			'all'       => array(
+				'slug'  => 'all',
+				'label' => esc_html__('View All Transactions', 'event_espresso'),
+				'count' => 0
+			),
+			'abandoned' => array(
+				'slug'  => 'abandoned',
+				'label' => esc_html__('Abandoned Transactions', 'event_espresso'),
+				'count' => 0
+			),
+			'failed'    => array(
+				'slug'  => 'failed',
+				'label' => esc_html__('Failed Transactions', 'event_espresso'),
+				'count' => 0
+			)
+		);
+	}
+
+
+	/**
+	 * _set_transaction_object
+	 * This sets the _transaction property for the transaction details screen
+	 *
+	 * @access private
+	 * @return void
+	 */
+	private function _set_transaction_object()
+	{
+		if (is_object($this->_transaction)) {
+			return;
+		} //get out we've already set the object
+
+		$TXN = EEM_Transaction::instance();
+
+		$TXN_ID = ( ! empty($this->_req_data['TXN_ID'])) ? absint($this->_req_data['TXN_ID']) : false;
+
+		//get transaction object
+		$this->_transaction = $TXN->get_one_by_ID($TXN_ID);
+		$this->_session     = ! empty($this->_transaction) ? $this->_transaction->get('TXN_session_data') : null;
+		$this->_transaction->verify_abandoned_transaction_status();
+
+		if (empty($this->_transaction)) {
+			$error_msg = esc_html__('An error occurred and the details for Transaction ID #',
+					'event_espresso') . $TXN_ID . esc_html__(' could not be retrieved.', 'event_espresso');
+			EE_Error::add_error($error_msg, __FILE__, __FUNCTION__, __LINE__);
+		}
+	}
+
+
+	/**
+	 *    _transaction_legend_items
+	 *
+	 * @access protected
+	 * @return array
+	 */
+	protected function _transaction_legend_items()
+	{
+		EE_Registry::instance()->load_helper('MSG_Template');
+		$items = array();
+
+		if (EE_Registry::instance()->CAP->current_user_can('ee_read_global_messages', 'view_filtered_messages')) {
+			$related_for_icon = EEH_MSG_Template::get_message_action_icon('see_notifications_for');
+			if (isset($related_for_icon['css_class']) && isset($related_for_icon['label'])) {
+				$items['view_related_messages'] = array(
+					'class' => $related_for_icon['css_class'],
+					'desc'  => $related_for_icon['label'],
+				);
+			}
+		}
+
+		$items = apply_filters(
+			'FHEE__Transactions_Admin_Page___transaction_legend_items__items',
+			array_merge($items,
+				array(
+					'view_details'      => array(
+						'class' => 'dashicons dashicons-cart',
+						'desc'  => esc_html__('View Transaction Details', 'event_espresso')
+					),
+					'view_invoice'      => array(
+						'class' => 'dashicons dashicons-media-spreadsheet',
+						'desc'  => esc_html__('View Transaction Invoice', 'event_espresso')
+					),
+					'view_receipt'      => array(
+						'class' => 'dashicons dashicons-media-default',
+						'desc'  => esc_html__('View Transaction Receipt', 'event_espresso')
+					),
+					'view_registration' => array(
+						'class' => 'dashicons dashicons-clipboard',
+						'desc'  => esc_html__('View Registration Details', 'event_espresso')
+					),
+					'payment_overview_link' => array(
+						'class' => 'dashicons dashicons-money',
+						'desc' => esc_html__('Make Payment on Frontend', 'event_espresso')
+					)
+				)
+			)
+		);
+
+		if (EE_Registry::instance()->CAP->current_user_can('ee_send_message',
+			'espresso_transactions_send_payment_reminder')
+		) {
+			if (EEH_MSG_Template::is_mt_active('payment_reminder')) {
+				$items['send_payment_reminder'] = array(
+					'class' => 'dashicons dashicons-email-alt',
+					'desc'  => esc_html__('Send Payment Reminder', 'event_espresso')
+				);
+			} else {
+				$items['blank*'] = array(
+					'class' => '',
+					'desc'  => ''
+				);
+			}
+		} else {
+			$items['blank*'] = array(
+				'class' => '',
+				'desc'  => ''
+			);
+		}
+		$more_items = apply_filters(
+			'FHEE__Transactions_Admin_Page___transaction_legend_items__more_items',
+			array(
+				'overpaid'   => array(
+					'class' => 'ee-status-legend ee-status-legend-' . EEM_Transaction::overpaid_status_code,
+					'desc'  => EEH_Template::pretty_status(EEM_Transaction::overpaid_status_code, false, 'sentence')
+				),
+				'complete'   => array(
+					'class' => 'ee-status-legend ee-status-legend-' . EEM_Transaction::complete_status_code,
+					'desc'  => EEH_Template::pretty_status(EEM_Transaction::complete_status_code, false, 'sentence')
+				),
+				'incomplete' => array(
+					'class' => 'ee-status-legend ee-status-legend-' . EEM_Transaction::incomplete_status_code,
+					'desc'  => EEH_Template::pretty_status(EEM_Transaction::incomplete_status_code, false, 'sentence')
+				),
+				'abandoned'  => array(
+					'class' => 'ee-status-legend ee-status-legend-' . EEM_Transaction::abandoned_status_code,
+					'desc'  => EEH_Template::pretty_status(EEM_Transaction::abandoned_status_code, false, 'sentence')
+				),
+				'failed'     => array(
+					'class' => 'ee-status-legend ee-status-legend-' . EEM_Transaction::failed_status_code,
+					'desc'  => EEH_Template::pretty_status(EEM_Transaction::failed_status_code, false, 'sentence')
+				)
+			)
+		);
+
+		return array_merge($items, $more_items);
+	}
+
+
+	/**
+	 *    _transactions_overview_list_table
+	 *
+	 * @access protected
+	 * @return void
+	 */
+	protected function _transactions_overview_list_table()
+	{
+		$this->_admin_page_title                   = esc_html__('Transactions', 'event_espresso');
+		$event                                     = isset($this->_req_data['EVT_ID']) ? EEM_Event::instance()->get_one_by_ID($this->_req_data['EVT_ID']) : null;
+		$this->_template_args['admin_page_header'] = $event instanceof EE_Event ? sprintf(esc_html__('%sViewing Transactions for the Event: %s%s',
+			'event_espresso'), '<h3>',
+			'<a href="' . EE_Admin_Page::add_query_args_and_nonce(array('action' => 'edit', 'post' => $event->ID()),
+				EVENTS_ADMIN_URL) . '" title="' . esc_attr__('Click to Edit event',
+				'event_espresso') . '">' . $event->get('EVT_name') . '</a>', '</h3>') : '';
+		$this->_template_args['after_list_table']  = $this->_display_legend($this->_transaction_legend_items());
+		$this->display_admin_list_table_page_with_no_sidebar();
+	}
+
+
+	/**
+	 *    _transaction_details
+	 * generates HTML for the View Transaction Details Admin page
+	 *
+	 * @access protected
+	 * @return void
+	 */
+	protected function _transaction_details()
+	{
+		do_action('AHEE__Transactions_Admin_Page__transaction_details__start', $this->_transaction);
+
+		$this->_set_transaction_status_array();
+
+		$this->_template_args                      = array();
+		$this->_template_args['transactions_page'] = $this->_wp_page_slug;
+
+		$this->_set_transaction_object();
+
+		$primary_registration = $this->_transaction->primary_registration();
+		$attendee             = $primary_registration instanceof EE_Registration ? $primary_registration->attendee() : null;
+
+		$this->_template_args['txn_nmbr']['value'] = $this->_transaction->ID();
+		$this->_template_args['txn_nmbr']['label'] = esc_html__('Transaction Number', 'event_espresso');
+
+		$this->_template_args['txn_datetime']['value'] = $this->_transaction->get_i18n_datetime('TXN_timestamp');
+		$this->_template_args['txn_datetime']['label'] = esc_html__('Date', 'event_espresso');
+
+		$this->_template_args['txn_status']['value'] = self::$_txn_status[$this->_transaction->get('STS_ID')];
+		$this->_template_args['txn_status']['label'] = esc_html__('Transaction Status', 'event_espresso');
+		$this->_template_args['txn_status']['class'] = 'status-' . $this->_transaction->get('STS_ID');
+
+		$this->_template_args['grand_total'] = $this->_transaction->get('TXN_total');
+		$this->_template_args['total_paid']  = $this->_transaction->get('TXN_paid');
+
+		if (
+			$attendee instanceof EE_Attendee
+			&& EE_Registry::instance()->CAP->current_user_can(
+				'ee_send_message',
+				'espresso_transactions_send_payment_reminder'
+			)
+		) {
+			$this->_template_args['send_payment_reminder_button'] =
+				EEH_MSG_Template::is_mt_active('payment_reminder')
+				&& $this->_transaction->get('STS_ID') != EEM_Transaction::complete_status_code
+				&& $this->_transaction->get('STS_ID') != EEM_Transaction::overpaid_status_code
+					? EEH_Template::get_button_or_link(
+					EE_Admin_Page::add_query_args_and_nonce(
+						array(
+							'action'      => 'send_payment_reminder',
+							'TXN_ID'      => $this->_transaction->ID(),
+							'redirect_to' => 'view_transaction'
+						),
+						TXN_ADMIN_URL
+					),
+					__(' Send Payment Reminder', 'event_espresso'),
+					'button secondary-button right',
+					'dashicons dashicons-email-alt'
+				)
+					: '';
+		} else {
+			$this->_template_args['send_payment_reminder_button'] = '';
+		}
+
+		$amount_due                         = $this->_transaction->get('TXN_total') - $this->_transaction->get('TXN_paid');
+		$this->_template_args['amount_due'] = EEH_Template::format_currency($amount_due, true);
+		if (EE_Registry::instance()->CFG->currency->sign_b4) {
+			$this->_template_args['amount_due'] = EE_Registry::instance()->CFG->currency->sign . $this->_template_args['amount_due'];
+		} else {
+			$this->_template_args['amount_due'] = $this->_template_args['amount_due'] . EE_Registry::instance()->CFG->currency->sign;
+		}
+		$this->_template_args['amount_due_class'] = '';
+
+		if ($this->_transaction->get('TXN_paid') == $this->_transaction->get('TXN_total')) {
+			// paid in full
+			$this->_template_args['amount_due'] = false;
+		} elseif ($this->_transaction->get('TXN_paid') > $this->_transaction->get('TXN_total')) {
+			// overpaid
+			$this->_template_args['amount_due_class'] = 'txn-overview-no-payment-spn';
+		} elseif (($this->_transaction->get('TXN_total') > 0) && ($this->_transaction->get('TXN_paid') > 0)) {
+			// monies owing
+			$this->_template_args['amount_due_class'] = 'txn-overview-part-payment-spn';
+		} elseif (($this->_transaction->get('TXN_total') > 0) && ($this->_transaction->get('TXN_paid') == 0)) {
+			// no payments made yet
+			$this->_template_args['amount_due_class'] = 'txn-overview-no-payment-spn';
+		} elseif ($this->_transaction->get('TXN_total') == 0) {
+			// free event
+			$this->_template_args['amount_due'] = false;
+		}
+
+		$payment_method = $this->_transaction->payment_method();
+
+		$this->_template_args['method_of_payment_name'] = $payment_method instanceof EE_Payment_Method
+			? $payment_method->admin_name()
+			: esc_html__('Unknown', 'event_espresso');
+
+		$this->_template_args['currency_sign'] = EE_Registry::instance()->CFG->currency->sign;
+		// link back to overview
+		$this->_template_args['txn_overview_url'] = ! empty ($_SERVER['HTTP_REFERER'])
+			? $_SERVER['HTTP_REFERER']
+			: TXN_ADMIN_URL;
+
+
+		// next link
+		$next_txn                                 = $this->_transaction->next(
+			null,
+			array(array('STS_ID' => array('!=', EEM_Transaction::failed_status_code))),
+			'TXN_ID'
+		);
+		$this->_template_args['next_transaction'] = $next_txn
+			? $this->_next_link(
+				EE_Admin_Page::add_query_args_and_nonce(
+					array('action' => 'view_transaction', 'TXN_ID' => $next_txn['TXN_ID']),
+					TXN_ADMIN_URL
+				),
+				'dashicons dashicons-arrow-right ee-icon-size-22'
+			)
+			: '';
+		// previous link
+		$previous_txn                                 = $this->_transaction->previous(
+			null,
+			array(array('STS_ID' => array('!=', EEM_Transaction::failed_status_code))),
+			'TXN_ID'
+		);
+		$this->_template_args['previous_transaction'] = $previous_txn
+			? $this->_previous_link(
+				EE_Admin_Page::add_query_args_and_nonce(
+					array('action' => 'view_transaction', 'TXN_ID' => $previous_txn['TXN_ID']),
+					TXN_ADMIN_URL
+				),
+				'dashicons dashicons-arrow-left ee-icon-size-22'
+			)
+			: '';
+
+		// were we just redirected here after adding a new registration ???
+		if (
+		isset(
+			$this->_req_data['redirect_from'],
+			$this->_req_data['EVT_ID'],
+			$this->_req_data['event_name']
+		)
+		) {
+			if (
+			EE_Registry::instance()->CAP->current_user_can(
+				'ee_edit_registrations',
+				'espresso_registrations_new_registration',
+				$this->_req_data['EVT_ID']
+			)
+			) {
+				$this->_admin_page_title .= '<a id="add-new-registration" class="add-new-h2 button-primary" href="';
+				$this->_admin_page_title .= EE_Admin_Page::add_query_args_and_nonce(
+					array(
+						'page'     => 'espresso_registrations',
+						'action'   => 'new_registration',
+						'return'   => 'default',
+						'TXN_ID'   => $this->_transaction->ID(),
+						'event_id' => $this->_req_data['EVT_ID'],
+					),
+					REG_ADMIN_URL
+				);
+				$this->_admin_page_title .= '">';
+
+				$this->_admin_page_title .= sprintf(
+					esc_html__('Add Another New Registration to Event: "%1$s" ?', 'event_espresso'),
+					htmlentities(urldecode($this->_req_data['event_name']), ENT_QUOTES, 'UTF-8')
+				);
+				$this->_admin_page_title .= '</a>';
+			}
+			EE_Registry::instance()->SSN->clear_session(__CLASS__, __FUNCTION__);
+		}
+		// grab messages at the last second
+		$this->_template_args['notices'] = EE_Error::get_notices();
+		// path to template
+		$template_path                             = TXN_TEMPLATE_PATH . 'txn_admin_details_header.template.php';
+		$this->_template_args['admin_page_header'] = EEH_Template::display_template($template_path,
+			$this->_template_args, true);
+
+		// the details template wrapper
+		$this->display_admin_page_with_sidebar();
+
+	}
+
+
+	/**
+	 *        _transaction_details_metaboxes
+	 *
+	 * @access protected
+	 * @return void
+	 */
+	protected function _transaction_details_metaboxes()
+	{
+
+		$this->_set_transaction_object();
+
+		add_meta_box('edit-txn-details-mbox', esc_html__('Transaction Details', 'event_espresso'),
+			array($this, 'txn_details_meta_box'), $this->_wp_page_slug, 'normal', 'high');
+		add_meta_box(
+			'edit-txn-attendees-mbox',
+			esc_html__('Attendees Registered in this Transaction', 'event_espresso'),
+			array($this, 'txn_attendees_meta_box'),
+			$this->_wp_page_slug,
+			'normal',
+			'high',
+			array('TXN_ID' => $this->_transaction->ID())
+		);
+		add_meta_box('edit-txn-registrant-mbox', esc_html__('Primary Contact', 'event_espresso'),
+			array($this, 'txn_registrant_side_meta_box'), $this->_wp_page_slug, 'side', 'high');
+		add_meta_box('edit-txn-billing-info-mbox', esc_html__('Billing Information', 'event_espresso'),
+			array($this, 'txn_billing_info_side_meta_box'), $this->_wp_page_slug, 'side', 'high');
+
+	}
+
+
+	/**
+	 * txn_details_meta_box
+	 * generates HTML for the Transaction main meta box
+	 *
+	 * @access public
+	 * @return void
+	 */
+	public function txn_details_meta_box()
+	{
+
+		$this->_set_transaction_object();
+		$this->_template_args['TXN_ID']   = $this->_transaction->ID();
+		$this->_template_args['attendee'] = $this->_transaction->primary_registration() instanceof EE_Registration ? $this->_transaction->primary_registration()->attendee() : null;
+
+		//get line table
+		EEH_Autoloader::register_line_item_display_autoloaders();
+		$Line_Item_Display                       = new EE_Line_Item_Display('admin_table',
+			'EE_Admin_Table_Line_Item_Display_Strategy');
+		$this->_template_args['line_item_table'] = $Line_Item_Display->display_line_item($this->_transaction->total_line_item());
+		$this->_template_args['REG_code']        = $this->_transaction->get_first_related('Registration')->get('REG_code');
+
+		// process taxes
+		$taxes                         = $this->_transaction->get_many_related('Line_Item',
+			array(array('LIN_type' => EEM_Line_Item::type_tax)));
+		$this->_template_args['taxes'] = ! empty($taxes) ? $taxes : false;
+
+		$this->_template_args['grand_total']     = EEH_Template::format_currency($this->_transaction->get('TXN_total'),
+			false, false);
+		$this->_template_args['grand_raw_total'] = $this->_transaction->get('TXN_total');
+		$this->_template_args['TXN_status']      = $this->_transaction->get('STS_ID');
 
 //		$txn_status_class = 'status-' . $this->_transaction->get('STS_ID');
 
-        // process payment details
-        $payments = $this->_transaction->get_many_related('Payment');
-        if ( ! empty($payments)) {
-            $this->_template_args['payments']              = $payments;
-            $this->_template_args['existing_reg_payments'] = $this->_get_registration_payment_IDs($payments);
-        } else {
-            $this->_template_args['payments']              = false;
-            $this->_template_args['existing_reg_payments'] = array();
-        }
-
-        $this->_template_args['edit_payment_url']   = add_query_arg(array('action' => 'edit_payment'), TXN_ADMIN_URL);
-        $this->_template_args['delete_payment_url'] = add_query_arg(array('action' => 'espresso_delete_payment'),
-            TXN_ADMIN_URL);
-
-        if (isset($txn_details['invoice_number'])) {
-            $this->_template_args['txn_details']['invoice_number']['value'] = $this->_template_args['REG_code'];
-            $this->_template_args['txn_details']['invoice_number']['label'] = esc_html__('Invoice Number',
-                'event_espresso');
-        }
-
-        $this->_template_args['txn_details']['registration_session']['value'] = $this->_transaction->get_first_related('Registration')->get('REG_session');
-        $this->_template_args['txn_details']['registration_session']['label'] = esc_html__('Registration Session',
-            'event_espresso');
-
-        $this->_template_args['txn_details']['ip_address']['value'] = isset($this->_session['ip_address']) ? $this->_session['ip_address'] : '';
-        $this->_template_args['txn_details']['ip_address']['label'] = esc_html__('Transaction placed from IP',
-            'event_espresso');
-
-        $this->_template_args['txn_details']['user_agent']['value'] = isset($this->_session['user_agent']) ? $this->_session['user_agent'] : '';
-        $this->_template_args['txn_details']['user_agent']['label'] = esc_html__('Registrant User Agent',
-            'event_espresso');
-
-        $reg_steps = '<ul>';
-        foreach ($this->_transaction->reg_steps() as $reg_step => $reg_step_status) {
-            if ($reg_step_status === true) {
-                $reg_steps .= '<li style="color:#70cc50">' . sprintf(esc_html__('%1$s : Completed', 'event_espresso'),
-                        ucwords(str_replace('_', ' ', $reg_step))) . '</li>';
-            } else if (is_numeric($reg_step_status) && $reg_step_status !== false) {
-                $reg_steps .= '<li style="color:#2EA2CC">' . sprintf(
-                        esc_html__('%1$s : Initiated %2$s', 'event_espresso'),
-                        ucwords(str_replace('_', ' ', $reg_step)),
-                        date(get_option('date_format') . ' ' . get_option('time_format'),
-                            ($reg_step_status + (get_option('gmt_offset') * HOUR_IN_SECONDS)))
-                    ) . '</li>';
-            } else {
-                $reg_steps .= '<li style="color:#E76700">' . sprintf(esc_html__('%1$s : Never Initiated',
-                        'event_espresso'), ucwords(str_replace('_', ' ', $reg_step))) . '</li>';
-            }
-        }
-        $reg_steps .= '</ul>';
-        $this->_template_args['txn_details']['reg_steps']['value'] = $reg_steps;
-        $this->_template_args['txn_details']['reg_steps']['label'] = esc_html__('Registration Step Progress',
-            'event_espresso');
-
-
-        $this->_get_registrations_to_apply_payment_to();
-        $this->_get_payment_methods($payments);
-        $this->_get_payment_status_array();
-        $this->_get_reg_status_selection(); //sets up the template args for the reg status array for the transaction.
-
-        $this->_template_args['transaction_form_url']    = add_query_arg(array(
-            'action'  => 'edit_transaction',
-            'process' => 'transaction'
-        ), TXN_ADMIN_URL);
-        $this->_template_args['apply_payment_form_url']  = add_query_arg(array(
-            'page'   => 'espresso_transactions',
-            'action' => 'espresso_apply_payment'
-        ), WP_AJAX_URL);
-        $this->_template_args['delete_payment_form_url'] = add_query_arg(array(
-            'page'   => 'espresso_transactions',
-            'action' => 'espresso_delete_payment'
-        ), WP_AJAX_URL);
-
-        // 'espresso_delete_payment_nonce'
-
-        $template_path = TXN_TEMPLATE_PATH . 'txn_admin_details_main_meta_box_txn_details.template.php';
-        echo EEH_Template::display_template($template_path, $this->_template_args, true);
-
-    }
-
-
-    /**
-     * _get_registration_payment_IDs
-     *
-     *    generates an array of Payment IDs and their corresponding Registration IDs
-     *
-     * @access protected
-     *
-     * @param EE_Payment[] $payments
-     *
-     * @return array
-     */
-    protected function _get_registration_payment_IDs($payments = array())
-    {
-        $existing_reg_payments = array();
-        // get all reg payments for these payments
-        $reg_payments = EEM_Registration_Payment::instance()->get_all(array(
-            array(
-                'PAY_ID' => array(
-                    'IN',
-                    array_keys($payments)
-                )
-            )
-        ));
-        if ( ! empty($reg_payments)) {
-            foreach ($payments as $payment) {
-                if ( ! $payment instanceof EE_Payment) {
-                    continue;
-                } else if ( ! isset($existing_reg_payments[$payment->ID()])) {
-                    $existing_reg_payments[$payment->ID()] = array();
-                }
-                foreach ($reg_payments as $reg_payment) {
-                    if ($reg_payment instanceof EE_Registration_Payment && $reg_payment->payment_ID() === $payment->ID()) {
-                        $existing_reg_payments[$payment->ID()][] = $reg_payment->registration_ID();
-                    }
-                }
-            }
-        }
-
-        return $existing_reg_payments;
-    }
-
-
-    /**
-     * _get_registrations_to_apply_payment_to
-     *    generates HTML for displaying a series of checkboxes in the admin payment modal window
-     * which allows the admin to only apply the payment to the specific registrations
-     *
-     * @access protected
-     * @return void
-     * @throws \EE_Error
-     */
-    protected function _get_registrations_to_apply_payment_to()
-    {
-        // we want any registration with an active status (ie: not deleted or cancelled)
-        $query_params                      = array(
-            array(
-                'STS_ID' => array(
-                    'IN',
-                    array(
-                        EEM_Registration::status_id_approved,
-                        EEM_Registration::status_id_pending_payment,
-                        EEM_Registration::status_id_not_approved,
-                    )
-                )
-            )
-        );
-        $registrations_to_apply_payment_to = EEH_HTML::br() . EEH_HTML::div(
-                '', 'txn-admin-apply-payment-to-registrations-dv', '', 'clear: both; margin: 1.5em 0 0; display: none;'
-            );
-        $registrations_to_apply_payment_to .= EEH_HTML::br() . EEH_HTML::div('', '', 'admin-primary-mbox-tbl-wrap');
-        $registrations_to_apply_payment_to .= EEH_HTML::table('', '', 'admin-primary-mbox-tbl');
-        $registrations_to_apply_payment_to .= EEH_HTML::thead(
-            EEH_HTML::tr(
-                EEH_HTML::th(esc_html__('ID', 'event_espresso')) .
-                EEH_HTML::th(esc_html__('Registrant', 'event_espresso')) .
-                EEH_HTML::th(esc_html__('Ticket', 'event_espresso')) .
-                EEH_HTML::th(esc_html__('Event', 'event_espresso')) .
-                EEH_HTML::th(esc_html__('Paid', 'event_espresso'), '', 'txn-admin-payment-paid-td jst-cntr') .
-                EEH_HTML::th(esc_html__('Owing', 'event_espresso'), '', 'txn-admin-payment-owing-td jst-cntr') .
-                EEH_HTML::th(esc_html__('Apply', 'event_espresso'), '', 'jst-cntr')
-            )
-        );
-        $registrations_to_apply_payment_to .= EEH_HTML::tbody();
-        // get registrations for TXN
-        $registrations = $this->_transaction->registrations($query_params);
-        foreach ($registrations as $registration) {
-            if ($registration instanceof EE_Registration) {
-                $attendee_name = $registration->attendee() instanceof EE_Attendee
-                    ? $registration->attendee()->full_name()
-                    : esc_html__('Unknown Attendee', 'event_espresso');
-                $owing         = $registration->final_price() - $registration->paid();
-                $taxable       = $registration->ticket()->taxable()
-                    ? ' <span class="smaller-text lt-grey-text"> ' . esc_html__('+ tax', 'event_espresso') . '</span>'
-                    : '';
-                $checked       = empty($existing_reg_payments) || in_array($registration->ID(), $existing_reg_payments)
-                    ? ' checked="checked"'
-                    : '';
-                $disabled      = $registration->final_price() > 0 ? '' : ' disabled';
-                $registrations_to_apply_payment_to .= EEH_HTML::tr(
-                    EEH_HTML::td($registration->ID()) .
-                    EEH_HTML::td($attendee_name) .
-                    EEH_HTML::td(
-                        $registration->ticket()->name() . ' : ' . $registration->ticket()->pretty_price() . $taxable
-                    ) .
-                    EEH_HTML::td($registration->event_name()) .
-                    EEH_HTML::td($registration->pretty_paid(), '', 'txn-admin-payment-paid-td jst-cntr') .
-                    EEH_HTML::td(EEH_Template::format_currency($owing), '', 'txn-admin-payment-owing-td jst-cntr') .
-                    EEH_HTML::td(
-                        '<input type="checkbox" value="' . $registration->ID()
-                        . '" name="txn_admin_payment[registrations]"'
-                        . $checked . $disabled . '>',
-                        '', 'jst-cntr'
-                    ),
-                    'apply-payment-registration-row-' . $registration->ID()
-                );
-            }
-        }
-        $registrations_to_apply_payment_to .= EEH_HTML::tbodyx();
-        $registrations_to_apply_payment_to .= EEH_HTML::tablex();
-        $registrations_to_apply_payment_to .= EEH_HTML::divx();
-        $registrations_to_apply_payment_to .= EEH_HTML::p(
-            esc_html__(
-                'The payment will only be applied to the registrations that have a check mark in their corresponding check box. Checkboxes for free registrations have been disabled.',
-                'event_espresso'
-            ),
-            '', 'clear description'
-        );
-        $registrations_to_apply_payment_to .= EEH_HTML::divx();
-        $this->_template_args['registrations_to_apply_payment_to'] = $registrations_to_apply_payment_to;
-    }
-
-
-    /**
-     * _get_reg_status_selection
-     *
-     * @todo   this will need to be adjusted either once MER comes along OR we move default reg status to tickets
-     *         instead of events.
-     * @access protected
-     * @return void
-     */
-    protected function _get_reg_status_selection()
-    {
-        //first get all possible statuses
-        $statuses = EEM_Registration::reg_status_array(array(), true);
-        //let's add a "don't change" option.
-        $status_array['NAN']                                 = esc_html__('Leave the Same', 'event_espresso');
-        $status_array                                        = array_merge($status_array, $statuses);
-        $this->_template_args['status_change_select']        = EEH_Form_Fields::select_input('txn_reg_status_change[reg_status]',
-            $status_array, 'NAN', 'id="txn-admin-payment-reg-status-inp"', 'txn-reg-status-change-reg-status');
-        $this->_template_args['delete_status_change_select'] = EEH_Form_Fields::select_input('delete_txn_reg_status_change[reg_status]',
-            $status_array, 'NAN', 'delete-txn-admin-payment-reg-status-inp', 'delete-txn-reg-status-change-reg-status');
-
-    }
-
-
-    /**
-     *    _get_payment_methods
-     * Gets all the payment methods available generally, or the ones that are already
-     * selected on these payments (in case their payment methods are no longer active).
-     * Has the side-effect of updating the template args' payment_methods item
-     * @access private
-     *
-     * @param EE_Payment[] to show on this page
-     *
-     * @return void
-     */
-    private function _get_payment_methods($payments = array())
-    {
-        $payment_methods_of_payments = array();
-        foreach ($payments as $payment) {
-            if ($payment instanceof EE_Payment) {
-                $payment_methods_of_payments[] = $payment->get('PMD_ID');
-            }
-        }
-        if ($payment_methods_of_payments) {
-            $query_args = array(
-                array(
-                    'OR*payment_method_for_payment' => array(
-                        'PMD_ID'    => array('IN', $payment_methods_of_payments),
-                        'PMD_scope' => array('LIKE', '%' . EEM_Payment_Method::scope_admin . '%')
-                    )
-                )
-            );
-        } else {
-            $query_args = array(array('PMD_scope' => array('LIKE', '%' . EEM_Payment_Method::scope_admin . '%')));
-        }
-        $this->_template_args['payment_methods'] = EEM_Payment_Method::instance()->get_all($query_args);
-    }
-
-
-    /**
-     * txn_attendees_meta_box
-     *    generates HTML for the Attendees Transaction main meta box
-     *
-     * @access public
-     *
-     * @param WP_Post $post
-     * @param array   $metabox
-     *
-     * @return void
-     */
-    public function txn_attendees_meta_box($post, $metabox = array('args' => array()))
-    {
-
-        extract($metabox['args']);
-        $this->_template_args['post']            = $post;
-        $this->_template_args['event_attendees'] = array();
-        // process items in cart
-        $line_items = $this->_transaction->get_many_related('Line_Item', array(array('LIN_type' => 'line-item')));
-        if ( ! empty($line_items)) {
-            foreach ($line_items as $item) {
-                if ($item instanceof EE_Line_Item) {
-                    switch ($item->OBJ_type()) {
-
-                        case 'Event' :
-                            break;
-
-                        case 'Ticket' :
-                            $ticket = $item->ticket();
-                            //right now we're only handling tickets here.  Cause its expected that only tickets will have attendees right?
-                            if ( ! $ticket instanceof EE_Ticket) {
-                                continue;
-                            }
-                            try {
-                                $event_name = $ticket->get_event_name();
-                            } catch (Exception $e) {
-                                EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
-                                $event_name = esc_html__('Unknown Event', 'event_espresso');
-                            }
-                            $event_name .= ' - ' . $item->get('LIN_name');
-                            $ticket_price = EEH_Template::format_currency($item->get('LIN_unit_price'));
-                            // now get all of the registrations for this transaction that use this ticket
-                            $registrations = $ticket->get_many_related('Registration',
-                                array(array('TXN_ID' => $this->_transaction->ID())));
-                            foreach ($registrations as $registration) {
-                                if ( ! $registration instanceof EE_Registration) {
-                                    continue;
-                                }
-                                $this->_template_args['event_attendees'][$registration->ID()]['STS_ID']            = $registration->status_ID();
-                                $this->_template_args['event_attendees'][$registration->ID()]['att_num']           = $registration->count();
-                                $this->_template_args['event_attendees'][$registration->ID()]['event_ticket_name'] = $event_name;
-                                $this->_template_args['event_attendees'][$registration->ID()]['ticket_price']      = $ticket_price;
-                                // attendee info
-                                $attendee = $registration->get_first_related('Attendee');
-                                if ($attendee instanceof EE_Attendee) {
-                                    $this->_template_args['event_attendees'][$registration->ID()]['att_id']   = $attendee->ID();
-                                    $this->_template_args['event_attendees'][$registration->ID()]['attendee'] = $attendee->full_name();
-                                    $this->_template_args['event_attendees'][$registration->ID()]['email']    = '<a href="mailto:' . $attendee->email() . '?subject=' . $event_name . esc_html__(' Event',
-                                            'event_espresso') . '">' . $attendee->email() . '</a>';
-                                    $this->_template_args['event_attendees'][$registration->ID()]['address']  = EEH_Address::format($attendee,
-                                        'inline', false, false);
-                                } else {
-                                    $this->_template_args['event_attendees'][$registration->ID()]['att_id']   = '';
-                                    $this->_template_args['event_attendees'][$registration->ID()]['attendee'] = '';
-                                    $this->_template_args['event_attendees'][$registration->ID()]['email']    = '';
-                                    $this->_template_args['event_attendees'][$registration->ID()]['address']  = '';
-                                }
-                            }
-                            break;
-
-                    }
-                }
-            }
-
-            $this->_template_args['transaction_form_url'] = add_query_arg(array(
-                'action'  => 'edit_transaction',
-                'process' => 'attendees'
-            ), TXN_ADMIN_URL);
-            echo EEH_Template::display_template(TXN_TEMPLATE_PATH . 'txn_admin_details_main_meta_box_attendees.template.php',
-                $this->_template_args, true);
-
-        } else {
-            echo sprintf(
-                esc_html__('%1$sFor some reason, there are no attendees registered for this transaction. Likely the registration was abandoned in process.%2$s',
-                    'event_espresso'),
-                '<p class="important-notice">',
-                '</p>'
-            );
-        }
-    }
-
-
-    /**
-     * txn_registrant_side_meta_box
-     * generates HTML for the Edit Transaction side meta box
-     *
-     * @access public
-     * @throws \EE_Error
-     * @return void
-     */
-    public function txn_registrant_side_meta_box()
-    {
-        $primary_att = $this->_transaction->primary_registration() instanceof EE_Registration ? $this->_transaction->primary_registration()->get_first_related('Attendee') : null;
-        if ( ! $primary_att instanceof EE_Attendee) {
-            $this->_template_args['no_attendee_message'] = esc_html__('There is no attached contact for this transaction.  The transaction either failed due to an error or was abandoned.',
-                'event_espresso');
-            $primary_att                                 = EEM_Attendee::instance()->create_default_object();
-        }
-        $this->_template_args['ATT_ID']            = $primary_att->ID();
-        $this->_template_args['prime_reg_fname']   = $primary_att->fname();
-        $this->_template_args['prime_reg_lname']   = $primary_att->lname();
-        $this->_template_args['prime_reg_email']   = $primary_att->email();
-        $this->_template_args['prime_reg_phone']   = $primary_att->phone();
-        $this->_template_args['edit_attendee_url'] = EE_Admin_Page::add_query_args_and_nonce(array(
-            'action' => 'edit_attendee',
-            'post'   => $primary_att->ID()
-        ), REG_ADMIN_URL);
-        // get formatted address for registrant
-        $this->_template_args['formatted_address'] = EEH_Address::format($primary_att);
-        echo EEH_Template::display_template(TXN_TEMPLATE_PATH . 'txn_admin_details_side_meta_box_registrant.template.php',
-            $this->_template_args, true);
-    }
-
-
-    /**
-     * txn_billing_info_side_meta_box
-     *    generates HTML for the Edit Transaction side meta box
-     *
-     * @access public
-     * @return void
-     */
-    public function txn_billing_info_side_meta_box()
-    {
-
-        $this->_template_args['billing_form']     = $this->_transaction->billing_info();
-        $this->_template_args['billing_form_url'] = add_query_arg(
-            array('action' => 'edit_transaction', 'process' => 'billing'),
-            TXN_ADMIN_URL
-        );
-
-        $template_path = TXN_TEMPLATE_PATH . 'txn_admin_details_side_meta_box_billing_info.template.php';
-        echo EEH_Template::display_template($template_path, $this->_template_args, true);/**/
-    }
-
-
-    /**
-     * apply_payments_or_refunds
-     *    registers a payment or refund made towards a transaction
-     *
-     * @access public
-     * @return void
-     */
-    public function apply_payments_or_refunds()
-    {
-        $json_response_data = array('return_data' => false);
-        $valid_data         = $this->_validate_payment_request_data();
-        if ( ! empty($valid_data)) {
-            $PAY_ID = $valid_data['PAY_ID'];
-            //save  the new payment
-            $payment = $this->_create_payment_from_request_data($valid_data);
-            // get the TXN for this payment
-            $transaction = $payment->transaction();
-            // verify transaction
-            if ($transaction instanceof EE_Transaction) {
-                // calculate_total_payments_and_update_status
-                $this->_process_transaction_payments($transaction);
-                $REG_IDs = $this->_get_REG_IDs_to_apply_payment_to($payment);
-                $this->_remove_existing_registration_payments($payment, $PAY_ID);
-                // apply payment to registrations (if applicable)
-                if ( ! empty($REG_IDs)) {
-                    $this->_update_registration_payments($transaction, $payment, $REG_IDs);
-                    $this->_maybe_send_notifications();
-                    // now process status changes for the same registrations
-                    $this->_process_registration_status_change($transaction, $REG_IDs);
-                }
-                $this->_maybe_send_notifications($payment);
-                //prepare to render page
-                $json_response_data['return_data'] = $this->_build_payment_json_response($payment, $REG_IDs);
-                do_action('AHEE__Transactions_Admin_Page__apply_payments_or_refund__after_recording', $transaction,
-                    $payment);
-            } else {
-                EE_Error::add_error(
-                    esc_html__('A valid Transaction for this payment could not be retrieved.', 'event_espresso'),
-                    __FILE__, __FUNCTION__, __LINE__
-                );
-            }
-        } else {
-            EE_Error::add_error(esc_html__('The payment form data could not be processed. Please try again.',
-                'event_espresso'), __FILE__, __FUNCTION__, __LINE__);
-        }
-
-        $notices              = EE_Error::get_notices(false, false, false);
-        $this->_template_args = array(
-            'data'    => $json_response_data,
-            'error'   => $notices['errors'],
-            'success' => $notices['success']
-        );
-        $this->_return_json();
-    }
-
-
-    /**
-     * _validate_payment_request_data
-     *
-     * @return array
-     */
-    protected function _validate_payment_request_data()
-    {
-        if ( ! isset($this->_req_data['txn_admin_payment'])) {
-            return false;
-        }
-        $payment_form = $this->_generate_payment_form_section();
-        try {
-            if ($payment_form->was_submitted()) {
-                $payment_form->receive_form_submission();
-                if ( ! $payment_form->is_valid()) {
-                    $submission_error_messages = array();
-                    foreach ($payment_form->get_validation_errors_accumulated() as $validation_error) {
-                        if ($validation_error instanceof EE_Validation_Error) {
-                            $submission_error_messages[] = sprintf(
-                                _x('%s : %s', 'Form Section Name : Form Validation Error', 'event_espresso'),
-                                $validation_error->get_form_section()->html_label_text(),
-                                $validation_error->getMessage()
-                            );
-                        }
-                    }
-                    EE_Error::add_error(join('<br />', $submission_error_messages), __FILE__, __FUNCTION__, __LINE__);
-
-                    return array();
-                }
-            }
-        } catch (EE_Error $e) {
-            EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
-
-            return array();
-        }
-
-        return $payment_form->valid_data();
-    }
-
-
-    /**
-     * _generate_payment_form_section
-     *
-     * @return EE_Form_Section_Proper
-     */
-    protected function _generate_payment_form_section()
-    {
-        return new EE_Form_Section_Proper(
-            array(
-                'name'        => 'txn_admin_payment',
-                'subsections' => array(
-                    'PAY_ID'          => new EE_Text_Input(
-                        array(
-                            'default'               => 0,
-                            'required'              => false,
-                            'html_label_text'       => esc_html__('Payment ID', 'event_espresso'),
-                            'validation_strategies' => array(new EE_Int_Normalization())
-                        )
-                    ),
-                    'TXN_ID'          => new EE_Text_Input(
-                        array(
-                            'default'               => 0,
-                            'required'              => true,
-                            'html_label_text'       => esc_html__('Transaction ID', 'event_espresso'),
-                            'validation_strategies' => array(new EE_Int_Normalization())
-                        )
-                    ),
-                    'type'            => new EE_Text_Input(
-                        array(
-                            'default'               => 1,
-                            'required'              => true,
-                            'html_label_text'       => esc_html__('Payment or Refund', 'event_espresso'),
-                            'validation_strategies' => array(new EE_Int_Normalization())
-                        )
-                    ),
-                    'amount'          => new EE_Text_Input(
-                        array(
-                            'default'               => 0,
-                            'required'              => true,
-                            'html_label_text'       => esc_html__('Payment amount', 'event_espresso'),
-                            'validation_strategies' => array(new EE_Float_Normalization())
-                        )
-                    ),
-                    'status'          => new EE_Text_Input(
-                        array(
-                            'default'         => EEM_Payment::status_id_approved,
-                            'required'        => true,
-                            'html_label_text' => esc_html__('Payment status', 'event_espresso'),
-                        )
-                    ),
-                    'PMD_ID'          => new EE_Text_Input(
-                        array(
-                            'default'               => 2,
-                            'required'              => true,
-                            'html_label_text'       => esc_html__('Payment Method', 'event_espresso'),
-                            'validation_strategies' => array(new EE_Int_Normalization())
-                        )
-                    ),
-                    'date'            => new EE_Text_Input(
-                        array(
-                            'default'         => time(),
-                            'required'        => true,
-                            'html_label_text' => esc_html__('Payment date', 'event_espresso'),
-                        )
-                    ),
-                    'txn_id_chq_nmbr' => new EE_Text_Input(
-                        array(
-                            'default'               => '',
-                            'required'              => false,
-                            'html_label_text'       => esc_html__('Transaction or Cheque Number', 'event_espresso'),
-                            'validation_strategies' => array(
-                                new EE_Max_Length_Validation_Strategy(esc_html__('Input too long', 'event_espresso'),
-                                    100),
-                            )
-                        )
-                    ),
-                    'po_number'       => new EE_Text_Input(
-                        array(
-                            'default'               => '',
-                            'required'              => false,
-                            'html_label_text'       => esc_html__('Purchase Order Number', 'event_espresso'),
-                            'validation_strategies' => array(
-                                new EE_Max_Length_Validation_Strategy(esc_html__('Input too long', 'event_espresso'),
-                                    100),
-                            )
-                        )
-                    ),
-                    'accounting'      => new EE_Text_Input(
-                        array(
-                            'default'               => '',
-                            'required'              => false,
-                            'html_label_text'       => esc_html__('Extra Field for Accounting', 'event_espresso'),
-                            'validation_strategies' => array(
-                                new EE_Max_Length_Validation_Strategy(esc_html__('Input too long', 'event_espresso'),
-                                    100),
-                            )
-                        )
-                    ),
-                )
-            )
-        );
-    }
-
-
-    /**
-     * _create_payment_from_request_data
-     *
-     * @param array $valid_data
-     *
-     * @return EE_Payment
-     */
-    protected function _create_payment_from_request_data($valid_data)
-    {
-        $PAY_ID = $valid_data['PAY_ID'];
-        // get payment amount
-        $amount = $valid_data['amount'] ? abs($valid_data['amount']) : 0;
-        // payments have a type value of 1 and refunds have a type value of -1
-        // so multiplying amount by type will give a positive value for payments, and negative values for refunds
-        $amount = $valid_data['type'] < 0 ? $amount * -1 : $amount;
-        // for some reason the date string coming in has extra spaces between the date and time.  This fixes that.
-        $date    = $valid_data['date'] ? preg_replace('/\s+/', ' ', $valid_data['date']) : date('Y-m-d g:i a',
-            current_time('timestamp'));
-        $payment = EE_Payment::new_instance(
-            array(
-                'TXN_ID'              => $valid_data['TXN_ID'],
-                'STS_ID'              => $valid_data['status'],
-                'PAY_timestamp'       => $date,
-                'PAY_source'          => EEM_Payment_Method::scope_admin,
-                'PMD_ID'              => $valid_data['PMD_ID'],
-                'PAY_amount'          => $amount,
-                'PAY_txn_id_chq_nmbr' => $valid_data['txn_id_chq_nmbr'],
-                'PAY_po_number'       => $valid_data['po_number'],
-                'PAY_extra_accntng'   => $valid_data['accounting'],
-                'PAY_details'         => $valid_data,
-                'PAY_ID'              => $PAY_ID
-            ),
-            '',
-            array('Y-m-d', 'g:i a')
-        );
-
-        if ( ! $payment->save()) {
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__('Payment %1$d has not been successfully saved to the database.', 'event_espresso'),
-                    $payment->ID()
-                ),
-                __FILE__, __FUNCTION__, __LINE__
-            );
-        }
-
-        return $payment;
-    }
-
-
-    /**
-     * _process_transaction_payments
-     *
-     * @param \EE_Transaction $transaction
-     *
-     * @return array
-     */
-    protected function _process_transaction_payments(EE_Transaction $transaction)
-    {
-        /** @type EE_Transaction_Payments $transaction_payments */
-        $transaction_payments = EE_Registry::instance()->load_class('Transaction_Payments');
-        //update the transaction with this payment
-        if ($transaction_payments->calculate_total_payments_and_update_status($transaction)) {
-            EE_Error::add_success(esc_html__('The payment has been processed successfully.', 'event_espresso'),
-                __FILE__, __FUNCTION__, __LINE__);
-        } else {
-            EE_Error::add_error(
-                esc_html__('The payment was processed successfully but the amount paid for the transaction was not updated.',
-                    'event_espresso')
-                , __FILE__, __FUNCTION__, __LINE__
-            );
-        }
-    }
-
-
-    /**
-     * _get_REG_IDs_to_apply_payment_to
-     *
-     * returns a list of registration IDs that the payment will apply to
-     *
-     * @param \EE_Payment $payment
-     *
-     * @return array
-     */
-    protected function _get_REG_IDs_to_apply_payment_to(EE_Payment $payment)
-    {
-        $REG_IDs = array();
-        // grab array of IDs for specific registrations to apply changes to
-        if (isset($this->_req_data['txn_admin_payment']['registrations'])) {
-            $REG_IDs = (array)$this->_req_data['txn_admin_payment']['registrations'];
-        }
-        //nothing specified ? then get all reg IDs
-        if (empty($REG_IDs)) {
-            $registrations = $payment->transaction()->registrations();
-            $REG_IDs       = ! empty($registrations) ? array_keys($registrations) : $this->_get_existing_reg_payment_REG_IDs($payment);
-        }
-
-        // ensure that REG_IDs are integers and NOT strings
-        return array_map('intval', $REG_IDs);
-    }
-
-
-    /**
-     * @return array
-     */
-    public function existing_reg_payment_REG_IDs()
-    {
-        return $this->_existing_reg_payment_REG_IDs;
-    }
-
-
-    /**
-     * @param array $existing_reg_payment_REG_IDs
-     */
-    public function set_existing_reg_payment_REG_IDs($existing_reg_payment_REG_IDs = null)
-    {
-        $this->_existing_reg_payment_REG_IDs = $existing_reg_payment_REG_IDs;
-    }
-
-
-    /**
-     * _get_existing_reg_payment_REG_IDs
-     *
-     * returns a list of registration IDs that the payment is currently related to
-     * as recorded in the database
-     *
-     * @param \EE_Payment $payment
-     *
-     * @return array
-     */
-    protected function _get_existing_reg_payment_REG_IDs(EE_Payment $payment)
-    {
-        if ($this->existing_reg_payment_REG_IDs() === null) {
-            // let's get any existing reg payment records for this payment
-            $existing_reg_payment_REG_IDs = $payment->get_many_related('Registration');
-            // but we only want the REG IDs, so grab the array keys
-            $existing_reg_payment_REG_IDs = ! empty($existing_reg_payment_REG_IDs) ? array_keys($existing_reg_payment_REG_IDs) : array();
-            $this->set_existing_reg_payment_REG_IDs($existing_reg_payment_REG_IDs);
-        }
-
-        return $this->existing_reg_payment_REG_IDs();
-    }
-
-
-    /**
-     * _remove_existing_registration_payments
-     *
-     * this calculates the difference between existing relations
-     * to the supplied payment and the new list registration IDs,
-     * removes any related registrations that no longer apply,
-     * and then updates the registration paid fields
-     *
-     * @param \EE_Payment $payment
-     * @param int         $PAY_ID
-     *
-     * @return bool;
-     */
-    protected function _remove_existing_registration_payments(EE_Payment $payment, $PAY_ID = 0)
-    {
-        // newly created payments will have nothing recorded for $PAY_ID
-        if ($PAY_ID == 0) {
-            return false;
-        }
-        $existing_reg_payment_REG_IDs = $this->_get_existing_reg_payment_REG_IDs($payment);
-        if (empty($existing_reg_payment_REG_IDs)) {
-            return false;
-        }
-        /** @type EE_Transaction_Payments $transaction_payments */
-        $transaction_payments = EE_Registry::instance()->load_class('Transaction_Payments');
-
-        return $transaction_payments->delete_registration_payments_and_update_registrations(
-            $payment,
-            array(
-                array(
-                    'PAY_ID' => $payment->ID(),
-                    'REG_ID' => array('IN', $existing_reg_payment_REG_IDs),
-                )
-            )
-        );
-    }
-
-
-    /**
-     * _update_registration_payments
-     *
-     * this applies the payments to the selected registrations
-     * but only if they have not already been paid for
-     *
-     * @param  EE_Transaction $transaction
-     * @param \EE_Payment     $payment
-     * @param array           $REG_IDs
-     *
-     * @return bool
-     */
-    protected function _update_registration_payments(
-        EE_Transaction $transaction,
-        EE_Payment $payment,
-        $REG_IDs = array()
-    ) {
-        // we can pass our own custom set of registrations to EE_Payment_Processor::process_registration_payments()
-        // so let's do that using our set of REG_IDs from the form
-        $registration_query_where_params = array(
-            'REG_ID' => array('IN', $REG_IDs)
-        );
-        // but add in some conditions regarding payment,
-        // so that we don't apply payments to registrations that are free or have already been paid for
-        // but ONLY if the payment is NOT a refund ( ie: the payment amount is not negative )
-        if ( ! $payment->is_a_refund()) {
-            $registration_query_where_params['REG_final_price']  = array('!=', 0);
-            $registration_query_where_params['REG_final_price*'] = array('!=', 'REG_paid', true);
-        }
-        //EEH_Debug_Tools::printr( $registration_query_where_params, '$registration_query_where_params', __FILE__, __LINE__ );
-        $registrations = $transaction->registrations(array($registration_query_where_params));
-        if ( ! empty($registrations)) {
-            /** @type EE_Payment_Processor $payment_processor */
-            $payment_processor = EE_Registry::instance()->load_core('Payment_Processor');
-            $payment_processor->process_registration_payments($transaction, $payment, $registrations);
-        }
-    }
-
-
-    /**
-     * _process_registration_status_change
-     *
-     * This processes requested registration status changes for all the registrations
-     * on a given transaction and (optionally) sends out notifications for the changes.
-     *
-     * @param  EE_Transaction $transaction
-     * @param array           $REG_IDs
-     *
-     * @return bool
-     */
-    protected function _process_registration_status_change(EE_Transaction $transaction, $REG_IDs = array())
-    {
-        // first if there is no change in status then we get out.
-        if (
-            ! isset($this->_req_data['txn_reg_status_change'], $this->_req_data['txn_reg_status_change']['reg_status'])
-            || $this->_req_data['txn_reg_status_change']['reg_status'] == 'NAN'
-        ) {
-            //no error message, no change requested, just nothing to do man.
-            return false;
-        }
-        /** @type EE_Transaction_Processor $transaction_processor */
-        $transaction_processor = EE_Registry::instance()->load_class('Transaction_Processor');
-
-        // made it here dude?  Oh WOW.  K, let's take care of changing the statuses
-        return $transaction_processor->manually_update_registration_statuses(
-            $transaction,
-            sanitize_text_field($this->_req_data['txn_reg_status_change']['reg_status']),
-            array(array('REG_ID' => array('IN', $REG_IDs)))
-        );
-    }
-
-
-    /**
-     * _build_payment_json_response
-     *
-     * @access public
-     *
-     * @param \EE_Payment $payment
-     * @param array       $REG_IDs
-     * @param bool | null $delete_txn_reg_status_change
-     *
-     * @return array
-     */
-    protected function _build_payment_json_response(
-        EE_Payment $payment,
-        $REG_IDs = array(),
-        $delete_txn_reg_status_change = null
-    ) {
-        // was the payment deleted ?
-        if (is_bool($delete_txn_reg_status_change)) {
-            return array(
-                'PAY_ID'                       => $payment->ID(),
-                'amount'                       => $payment->amount(),
-                'total_paid'                   => $payment->transaction()->paid(),
-                'txn_status'                   => $payment->transaction()->status_ID(),
-                'pay_status'                   => $payment->STS_ID(),
-                'registrations'                => $this->_registration_payment_data_array($REG_IDs),
-                'delete_txn_reg_status_change' => $delete_txn_reg_status_change,
-            );
-        } else {
-            $this->_get_payment_status_array();
-
-            return array(
-                'amount'           => $payment->amount(),
-                'total_paid'       => $payment->transaction()->paid(),
-                'txn_status'       => $payment->transaction()->status_ID(),
-                'pay_status'       => $payment->STS_ID(),
-                'PAY_ID'           => $payment->ID(),
-                'STS_ID'           => $payment->STS_ID(),
-                'status'           => self::$_pay_status[$payment->STS_ID()],
-                'date'             => $payment->timestamp('Y-m-d', 'h:i a'),
-                'method'           => strtoupper($payment->source()),
-                'PM_ID'            => $payment->payment_method() ? $payment->payment_method()->ID() : 1,
-                'gateway'          => $payment->payment_method() ? $payment->payment_method()->admin_name() : esc_html__("Unknown",
-                    'event_espresso'),
-                'gateway_response' => $payment->gateway_response(),
-                'txn_id_chq_nmbr'  => $payment->txn_id_chq_nmbr(),
-                'po_number'        => $payment->po_number(),
-                'extra_accntng'    => $payment->extra_accntng(),
-                'registrations'    => $this->_registration_payment_data_array($REG_IDs),
-            );
-        }
-    }
-
-
-    /**
-     * delete_payment
-     *    delete a payment or refund made towards a transaction
-     *
-     * @access public
-     * @return void
-     */
-    public function delete_payment()
-    {
-        $json_response_data = array('return_data' => false);
-        $PAY_ID             = isset($this->_req_data['delete_txn_admin_payment'], $this->_req_data['delete_txn_admin_payment']['PAY_ID']) ? absint($this->_req_data['delete_txn_admin_payment']['PAY_ID']) : 0;
-        if ($PAY_ID) {
-            $delete_txn_reg_status_change = isset($this->_req_data['delete_txn_reg_status_change']) ? $this->_req_data['delete_txn_reg_status_change'] : false;
-            $payment                      = EEM_Payment::instance()->get_one_by_ID($PAY_ID);
-            if ($payment instanceof EE_Payment) {
-                $REG_IDs = $this->_get_existing_reg_payment_REG_IDs($payment);
-                /** @type EE_Transaction_Payments $transaction_payments */
-                $transaction_payments = EE_Registry::instance()->load_class('Transaction_Payments');
-                if ($transaction_payments->delete_payment_and_update_transaction($payment)) {
-                    $json_response_data['return_data'] = $this->_build_payment_json_response($payment, $REG_IDs,
-                        $delete_txn_reg_status_change);
-                    if ($delete_txn_reg_status_change) {
-                        $this->_req_data['txn_reg_status_change'] = $delete_txn_reg_status_change;
-                        //MAKE sure we also add the delete_txn_req_status_change to the
-                        //$_REQUEST global because that's how messages will be looking for it.
-                        $_REQUEST['txn_reg_status_change'] = $delete_txn_reg_status_change;
-                        $this->_maybe_send_notifications();
-                        $this->_process_registration_status_change($payment->transaction(), $REG_IDs);
-                    }
-                }
-            } else {
-                EE_Error::add_error(
-                    esc_html__('Valid Payment data could not be retrieved from the database.', 'event_espresso'),
-                    __FILE__, __FUNCTION__, __LINE__
-                );
-            }
-        } else {
-            EE_Error::add_error(
-                esc_html__('A valid Payment ID was not received, therefore payment form data could not be loaded.',
-                    'event_espresso'),
-                __FILE__, __FUNCTION__, __LINE__
-            );
-        }
-        $notices              = EE_Error::get_notices(false, false, false);
-        $this->_template_args = array(
-            'data'      => $json_response_data,
-            'success'   => $notices['success'],
-            'error'     => $notices['errors'],
-            'attention' => $notices['attention']
-        );
-        $this->_return_json();
-    }
-
-
-    /**
-     * _registration_payment_data_array
-     * adds info for 'owing' and 'paid' for each registration to the json response
-     *
-     * @access protected
-     *
-     * @param array $REG_IDs
-     *
-     * @return array
-     */
-    protected function _registration_payment_data_array($REG_IDs)
-    {
-        $registration_payment_data = array();
-        //if non empty reg_ids lets get an array of registrations and update the values for the apply_payment/refund rows.
-        if ( ! empty($REG_IDs)) {
-            $registrations = EEM_Registration::instance()->get_all(array(array('REG_ID' => array('IN', $REG_IDs))));
-            foreach ($registrations as $registration) {
-                if ($registration instanceof EE_Registration) {
-                    $registration_payment_data[$registration->ID()] = array(
-                        'paid'  => $registration->pretty_paid(),
-                        'owing' => EEH_Template::format_currency($registration->final_price() - $registration->paid()),
-                    );
-                }
-            }
-        }
-
-        return $registration_payment_data;
-    }
-
-
-    /**
-     * _maybe_send_notifications
-     *
-     * determines whether or not the admin has indicated that notifications should be sent.
-     * If so, will toggle a filter switch for delivering registration notices.
-     * If passed an EE_Payment object, then it will trigger payment notifications instead.
-     *
-     * @access protected
-     *
-     * @param \EE_Payment | null $payment
-     */
-    protected function _maybe_send_notifications($payment = null)
-    {
-        switch ($payment instanceof EE_Payment) {
-            // payment notifications
-            case true :
-                if (
-                    isset(
-                        $this->_req_data['txn_payments'],
-                        $this->_req_data['txn_payments']['send_notifications']
-                    ) &&
-                    filter_var($this->_req_data['txn_payments']['send_notifications'], FILTER_VALIDATE_BOOLEAN)
-                ) {
-                    $this->_process_payment_notification($payment);
-                }
-                break;
-            // registration notifications
-            case false :
-                if (
-                    isset(
-                        $this->_req_data['txn_reg_status_change'],
-                        $this->_req_data['txn_reg_status_change']['send_notifications']
-                    ) &&
-                    filter_var($this->_req_data['txn_reg_status_change']['send_notifications'], FILTER_VALIDATE_BOOLEAN)
-                ) {
-                    add_filter('FHEE__EED_Messages___maybe_registration__deliver_notifications', '__return_true');
-                }
-                break;
-        }
-    }
-
-
-    /**
-     * _send_payment_reminder
-     *    generates HTML for the View Transaction Details Admin page
-     *
-     * @access protected
-     * @return void
-     */
-    protected function _send_payment_reminder()
-    {
-        $TXN_ID      = ( ! empty($this->_req_data['TXN_ID'])) ? absint($this->_req_data['TXN_ID']) : false;
-        $transaction = EEM_Transaction::instance()->get_one_by_ID($TXN_ID);
-        $query_args  = isset($this->_req_data['redirect_to']) ? array(
-            'action' => $this->_req_data['redirect_to'],
-            'TXN_ID' => $this->_req_data['TXN_ID']
-        ) : array();
-        do_action('AHEE__Transactions_Admin_Page___send_payment_reminder__process_admin_payment_reminder',
-            $transaction);
-        $this->_redirect_after_action(false, esc_html__('payment reminder', 'event_espresso'),
-            esc_html__('sent', 'event_espresso'), $query_args, true);
-    }
-
-
-    /**
-     *  get_transactions
-     *    get transactions for given parameters (used by list table)
-     *
-     * @param  int     $perpage how many transactions displayed per page
-     * @param  boolean $count   return the count or objects
-     * @param string   $view
-     *
-     * @return mixed int = count || array of transaction objects
-     */
-    public function get_transactions($perpage, $count = false, $view = '')
-    {
-
-        $TXN = EEM_Transaction::instance();
-
-        $start_date = isset($this->_req_data['txn-filter-start-date']) ? wp_strip_all_tags($this->_req_data['txn-filter-start-date']) : date('m/d/Y',
-            strtotime('-10 year'));
-        $end_date   = isset($this->_req_data['txn-filter-end-date']) ? wp_strip_all_tags($this->_req_data['txn-filter-end-date']) : date('m/d/Y');
-
-        //make sure our timestamps start and end right at the boundaries for each day
-        $start_date = date('Y-m-d', strtotime($start_date)) . ' 00:00:00';
-        $end_date   = date('Y-m-d', strtotime($end_date)) . ' 23:59:59';
-
-
-        //convert to timestamps
-        $start_date = strtotime($start_date);
-        $end_date   = strtotime($end_date);
-
-        //makes sure start date is the lowest value and vice versa
-        $start_date = min($start_date, $end_date);
-        $end_date   = max($start_date, $end_date);
-
-        //convert to correct format for query
-        $start_date = EEM_Transaction::instance()->convert_datetime_for_query('TXN_timestamp',
-            date('Y-m-d H:i:s', $start_date), 'Y-m-d H:i:s');
-        $end_date   = EEM_Transaction::instance()->convert_datetime_for_query('TXN_timestamp',
-            date('Y-m-d H:i:s', $end_date), 'Y-m-d H:i:s');
-
-
-        //set orderby
-        $this->_req_data['orderby'] = ! empty($this->_req_data['orderby']) ? $this->_req_data['orderby'] : '';
-
-        switch ($this->_req_data['orderby']) {
-            case 'TXN_ID':
-                $orderby = 'TXN_ID';
-                break;
-            case 'ATT_fname':
-                $orderby = 'Registration.Attendee.ATT_fname';
-                break;
-            case 'event_name':
-                $orderby = 'Registration.Event.EVT_name';
-                break;
-            default: //'TXN_timestamp'
-                $orderby = 'TXN_timestamp';
-        }
-
-        $sort         = (isset($this->_req_data['order']) && ! empty($this->_req_data['order'])) ? $this->_req_data['order'] : 'DESC';
-        $current_page = isset($this->_req_data['paged']) && ! empty($this->_req_data['paged']) ? $this->_req_data['paged'] : 1;
-        $per_page     = isset($perpage) && ! empty($perpage) ? $perpage : 10;
-        $per_page     = isset($this->_req_data['perpage']) && ! empty($this->_req_data['perpage']) ? $this->_req_data['perpage'] : $per_page;
-
-        $offset = ($current_page - 1) * $per_page;
-        $limit  = array($offset, $per_page);
-
-        $_where = array(
-            'TXN_timestamp'          => array('BETWEEN', array($start_date, $end_date)),
-            'Registration.REG_count' => 1
-        );
-
-        if (isset($this->_req_data['EVT_ID'])) {
-            $_where['Registration.EVT_ID'] = $this->_req_data['EVT_ID'];
-        }
-
-        if (isset($this->_req_data['s'])) {
-            $search_string = '%' . $this->_req_data['s'] . '%';
-            $_where['OR']  = array(
-                'Registration.Event.EVT_name'         => array('LIKE', $search_string),
-                'Registration.Event.EVT_desc'         => array('LIKE', $search_string),
-                'Registration.Event.EVT_short_desc'   => array('LIKE', $search_string),
-                'Registration.Attendee.ATT_full_name' => array('LIKE', $search_string),
-                'Registration.Attendee.ATT_fname'     => array('LIKE', $search_string),
-                'Registration.Attendee.ATT_lname'     => array('LIKE', $search_string),
-                'Registration.Attendee.ATT_short_bio' => array('LIKE', $search_string),
-                'Registration.Attendee.ATT_email'     => array('LIKE', $search_string),
-                'Registration.Attendee.ATT_address'   => array('LIKE', $search_string),
-                'Registration.Attendee.ATT_address2'  => array('LIKE', $search_string),
-                'Registration.Attendee.ATT_city'      => array('LIKE', $search_string),
-                'Registration.REG_final_price'        => array('LIKE', $search_string),
-                'Registration.REG_code'               => array('LIKE', $search_string),
-                'Registration.REG_count'              => array('LIKE', $search_string),
-                'Registration.REG_group_size'         => array('LIKE', $search_string),
-                'Registration.Ticket.TKT_name'        => array('LIKE', $search_string),
-                'Registration.Ticket.TKT_description' => array('LIKE', $search_string),
-                'Payment.PAY_source'                  => array('LIKE', $search_string),
-                'Payment.Payment_Method.PMD_name'     => array('LIKE', $search_string),
-                'TXN_session_data'                    => array('LIKE', $search_string),
-                'Payment.PAY_txn_id_chq_nmbr'         => array('LIKE', $search_string)
-            );
-        }
-
-        //failed transactions
-        $failed    = ( ! empty($this->_req_data['status']) && $this->_req_data['status'] == 'failed' && ! $count) || ($count && $view == 'failed') ? true : false;
-        $abandoned = ( ! empty($this->_req_data['status']) && $this->_req_data['status'] == 'abandoned' && ! $count) || ($count && $view == 'abandoned') ? true : false;
-
-        if ($failed) {
-            $_where['STS_ID'] = EEM_Transaction::failed_status_code;
-        } else if ($abandoned) {
-            $_where['STS_ID'] = EEM_Transaction::abandoned_status_code;
-        } else {
-            $_where['STS_ID']  = array('!=', EEM_Transaction::failed_status_code);
-            $_where['STS_ID*'] = array('!=', EEM_Transaction::abandoned_status_code);
-        }
-
-        $query_params = array(
-            $_where,
-            'order_by' => array($orderby => $sort),
-            'limit' => $limit,
-            'default_where_conditions' => EEM_Base::default_where_conditions_this_only
-        );
-
-        $transactions = $count ? $TXN->count(array($_where), 'TXN_ID', true) : $TXN->get_all($query_params);
-
-
-        return $transactions;
-
-    }
+		// process payment details
+		$payments = $this->_transaction->get_many_related('Payment');
+		if ( ! empty($payments)) {
+			$this->_template_args['payments']              = $payments;
+			$this->_template_args['existing_reg_payments'] = $this->_get_registration_payment_IDs($payments);
+		} else {
+			$this->_template_args['payments']              = false;
+			$this->_template_args['existing_reg_payments'] = array();
+		}
+
+		$this->_template_args['edit_payment_url']   = add_query_arg(array('action' => 'edit_payment'), TXN_ADMIN_URL);
+		$this->_template_args['delete_payment_url'] = add_query_arg(array('action' => 'espresso_delete_payment'),
+			TXN_ADMIN_URL);
+
+		if (isset($txn_details['invoice_number'])) {
+			$this->_template_args['txn_details']['invoice_number']['value'] = $this->_template_args['REG_code'];
+			$this->_template_args['txn_details']['invoice_number']['label'] = esc_html__('Invoice Number',
+				'event_espresso');
+		}
+
+		$this->_template_args['txn_details']['registration_session']['value'] = $this->_transaction->get_first_related('Registration')->get('REG_session');
+		$this->_template_args['txn_details']['registration_session']['label'] = esc_html__('Registration Session',
+			'event_espresso');
+
+		$this->_template_args['txn_details']['ip_address']['value'] = isset($this->_session['ip_address']) ? $this->_session['ip_address'] : '';
+		$this->_template_args['txn_details']['ip_address']['label'] = esc_html__('Transaction placed from IP',
+			'event_espresso');
+
+		$this->_template_args['txn_details']['user_agent']['value'] = isset($this->_session['user_agent']) ? $this->_session['user_agent'] : '';
+		$this->_template_args['txn_details']['user_agent']['label'] = esc_html__('Registrant User Agent',
+			'event_espresso');
+
+		$reg_steps = '<ul>';
+		foreach ($this->_transaction->reg_steps() as $reg_step => $reg_step_status) {
+			if ($reg_step_status === true) {
+				$reg_steps .= '<li style="color:#70cc50">' . sprintf(esc_html__('%1$s : Completed', 'event_espresso'),
+						ucwords(str_replace('_', ' ', $reg_step))) . '</li>';
+			} else if (is_numeric($reg_step_status) && $reg_step_status !== false) {
+				$reg_steps .= '<li style="color:#2EA2CC">' . sprintf(
+						esc_html__('%1$s : Initiated %2$s', 'event_espresso'),
+						ucwords(str_replace('_', ' ', $reg_step)),
+						date(get_option('date_format') . ' ' . get_option('time_format'),
+							($reg_step_status + (get_option('gmt_offset') * HOUR_IN_SECONDS)))
+					) . '</li>';
+			} else {
+				$reg_steps .= '<li style="color:#E76700">' . sprintf(esc_html__('%1$s : Never Initiated',
+						'event_espresso'), ucwords(str_replace('_', ' ', $reg_step))) . '</li>';
+			}
+		}
+		$reg_steps .= '</ul>';
+		$this->_template_args['txn_details']['reg_steps']['value'] = $reg_steps;
+		$this->_template_args['txn_details']['reg_steps']['label'] = esc_html__('Registration Step Progress',
+			'event_espresso');
+
+
+		$this->_get_registrations_to_apply_payment_to();
+		$this->_get_payment_methods($payments);
+		$this->_get_payment_status_array();
+		$this->_get_reg_status_selection(); //sets up the template args for the reg status array for the transaction.
+
+		$this->_template_args['transaction_form_url']    = add_query_arg(array(
+			'action'  => 'edit_transaction',
+			'process' => 'transaction'
+		), TXN_ADMIN_URL);
+		$this->_template_args['apply_payment_form_url']  = add_query_arg(array(
+			'page'   => 'espresso_transactions',
+			'action' => 'espresso_apply_payment'
+		), WP_AJAX_URL);
+		$this->_template_args['delete_payment_form_url'] = add_query_arg(array(
+			'page'   => 'espresso_transactions',
+			'action' => 'espresso_delete_payment'
+		), WP_AJAX_URL);
+
+		// 'espresso_delete_payment_nonce'
+
+		$template_path = TXN_TEMPLATE_PATH . 'txn_admin_details_main_meta_box_txn_details.template.php';
+		echo EEH_Template::display_template($template_path, $this->_template_args, true);
+
+	}
+
+
+	/**
+	 * _get_registration_payment_IDs
+	 *
+	 *    generates an array of Payment IDs and their corresponding Registration IDs
+	 *
+	 * @access protected
+	 *
+	 * @param EE_Payment[] $payments
+	 *
+	 * @return array
+	 */
+	protected function _get_registration_payment_IDs($payments = array())
+	{
+		$existing_reg_payments = array();
+		// get all reg payments for these payments
+		$reg_payments = EEM_Registration_Payment::instance()->get_all(array(
+			array(
+				'PAY_ID' => array(
+					'IN',
+					array_keys($payments)
+				)
+			)
+		));
+		if ( ! empty($reg_payments)) {
+			foreach ($payments as $payment) {
+				if ( ! $payment instanceof EE_Payment) {
+					continue;
+				} else if ( ! isset($existing_reg_payments[$payment->ID()])) {
+					$existing_reg_payments[$payment->ID()] = array();
+				}
+				foreach ($reg_payments as $reg_payment) {
+					if ($reg_payment instanceof EE_Registration_Payment && $reg_payment->payment_ID() === $payment->ID()) {
+						$existing_reg_payments[$payment->ID()][] = $reg_payment->registration_ID();
+					}
+				}
+			}
+		}
+
+		return $existing_reg_payments;
+	}
+
+
+	/**
+	 * _get_registrations_to_apply_payment_to
+	 *    generates HTML for displaying a series of checkboxes in the admin payment modal window
+	 * which allows the admin to only apply the payment to the specific registrations
+	 *
+	 * @access protected
+	 * @return void
+	 * @throws \EE_Error
+	 */
+	protected function _get_registrations_to_apply_payment_to()
+	{
+		// we want any registration with an active status (ie: not deleted or cancelled)
+		$query_params                      = array(
+			array(
+				'STS_ID' => array(
+					'IN',
+					array(
+						EEM_Registration::status_id_approved,
+						EEM_Registration::status_id_pending_payment,
+						EEM_Registration::status_id_not_approved,
+					)
+				)
+			)
+		);
+		$registrations_to_apply_payment_to = EEH_HTML::br() . EEH_HTML::div(
+				'', 'txn-admin-apply-payment-to-registrations-dv', '', 'clear: both; margin: 1.5em 0 0; display: none;'
+			);
+		$registrations_to_apply_payment_to .= EEH_HTML::br() . EEH_HTML::div('', '', 'admin-primary-mbox-tbl-wrap');
+		$registrations_to_apply_payment_to .= EEH_HTML::table('', '', 'admin-primary-mbox-tbl');
+		$registrations_to_apply_payment_to .= EEH_HTML::thead(
+			EEH_HTML::tr(
+				EEH_HTML::th(esc_html__('ID', 'event_espresso')) .
+				EEH_HTML::th(esc_html__('Registrant', 'event_espresso')) .
+				EEH_HTML::th(esc_html__('Ticket', 'event_espresso')) .
+				EEH_HTML::th(esc_html__('Event', 'event_espresso')) .
+				EEH_HTML::th(esc_html__('Paid', 'event_espresso'), '', 'txn-admin-payment-paid-td jst-cntr') .
+				EEH_HTML::th(esc_html__('Owing', 'event_espresso'), '', 'txn-admin-payment-owing-td jst-cntr') .
+				EEH_HTML::th(esc_html__('Apply', 'event_espresso'), '', 'jst-cntr')
+			)
+		);
+		$registrations_to_apply_payment_to .= EEH_HTML::tbody();
+		// get registrations for TXN
+		$registrations = $this->_transaction->registrations($query_params);
+		foreach ($registrations as $registration) {
+			if ($registration instanceof EE_Registration) {
+				$attendee_name = $registration->attendee() instanceof EE_Attendee
+					? $registration->attendee()->full_name()
+					: esc_html__('Unknown Attendee', 'event_espresso');
+				$owing         = $registration->final_price() - $registration->paid();
+				$taxable       = $registration->ticket()->taxable()
+					? ' <span class="smaller-text lt-grey-text"> ' . esc_html__('+ tax', 'event_espresso') . '</span>'
+					: '';
+				$checked       = empty($existing_reg_payments) || in_array($registration->ID(), $existing_reg_payments)
+					? ' checked="checked"'
+					: '';
+				$disabled      = $registration->final_price() > 0 ? '' : ' disabled';
+				$registrations_to_apply_payment_to .= EEH_HTML::tr(
+					EEH_HTML::td($registration->ID()) .
+					EEH_HTML::td($attendee_name) .
+					EEH_HTML::td(
+						$registration->ticket()->name() . ' : ' . $registration->ticket()->pretty_price() . $taxable
+					) .
+					EEH_HTML::td($registration->event_name()) .
+					EEH_HTML::td($registration->pretty_paid(), '', 'txn-admin-payment-paid-td jst-cntr') .
+					EEH_HTML::td(EEH_Template::format_currency($owing), '', 'txn-admin-payment-owing-td jst-cntr') .
+					EEH_HTML::td(
+						'<input type="checkbox" value="' . $registration->ID()
+						. '" name="txn_admin_payment[registrations]"'
+						. $checked . $disabled . '>',
+						'', 'jst-cntr'
+					),
+					'apply-payment-registration-row-' . $registration->ID()
+				);
+			}
+		}
+		$registrations_to_apply_payment_to .= EEH_HTML::tbodyx();
+		$registrations_to_apply_payment_to .= EEH_HTML::tablex();
+		$registrations_to_apply_payment_to .= EEH_HTML::divx();
+		$registrations_to_apply_payment_to .= EEH_HTML::p(
+			esc_html__(
+				'The payment will only be applied to the registrations that have a check mark in their corresponding check box. Checkboxes for free registrations have been disabled.',
+				'event_espresso'
+			),
+			'', 'clear description'
+		);
+		$registrations_to_apply_payment_to .= EEH_HTML::divx();
+		$this->_template_args['registrations_to_apply_payment_to'] = $registrations_to_apply_payment_to;
+	}
+
+
+	/**
+	 * _get_reg_status_selection
+	 *
+	 * @todo   this will need to be adjusted either once MER comes along OR we move default reg status to tickets
+	 *         instead of events.
+	 * @access protected
+	 * @return void
+	 */
+	protected function _get_reg_status_selection()
+	{
+		//first get all possible statuses
+		$statuses = EEM_Registration::reg_status_array(array(), true);
+		//let's add a "don't change" option.
+		$status_array['NAN']                                 = esc_html__('Leave the Same', 'event_espresso');
+		$status_array                                        = array_merge($status_array, $statuses);
+		$this->_template_args['status_change_select']        = EEH_Form_Fields::select_input('txn_reg_status_change[reg_status]',
+			$status_array, 'NAN', 'id="txn-admin-payment-reg-status-inp"', 'txn-reg-status-change-reg-status');
+		$this->_template_args['delete_status_change_select'] = EEH_Form_Fields::select_input('delete_txn_reg_status_change[reg_status]',
+			$status_array, 'NAN', 'delete-txn-admin-payment-reg-status-inp', 'delete-txn-reg-status-change-reg-status');
+
+	}
+
+
+	/**
+	 *    _get_payment_methods
+	 * Gets all the payment methods available generally, or the ones that are already
+	 * selected on these payments (in case their payment methods are no longer active).
+	 * Has the side-effect of updating the template args' payment_methods item
+	 * @access private
+	 *
+	 * @param EE_Payment[] to show on this page
+	 *
+	 * @return void
+	 */
+	private function _get_payment_methods($payments = array())
+	{
+		$payment_methods_of_payments = array();
+		foreach ($payments as $payment) {
+			if ($payment instanceof EE_Payment) {
+				$payment_methods_of_payments[] = $payment->get('PMD_ID');
+			}
+		}
+		if ($payment_methods_of_payments) {
+			$query_args = array(
+				array(
+					'OR*payment_method_for_payment' => array(
+						'PMD_ID'    => array('IN', $payment_methods_of_payments),
+						'PMD_scope' => array('LIKE', '%' . EEM_Payment_Method::scope_admin . '%')
+					)
+				)
+			);
+		} else {
+			$query_args = array(array('PMD_scope' => array('LIKE', '%' . EEM_Payment_Method::scope_admin . '%')));
+		}
+		$this->_template_args['payment_methods'] = EEM_Payment_Method::instance()->get_all($query_args);
+	}
+
+
+	/**
+	 * txn_attendees_meta_box
+	 *    generates HTML for the Attendees Transaction main meta box
+	 *
+	 * @access public
+	 *
+	 * @param WP_Post $post
+	 * @param array   $metabox
+	 *
+	 * @return void
+	 */
+	public function txn_attendees_meta_box($post, $metabox = array('args' => array()))
+	{
+
+		extract($metabox['args']);
+		$this->_template_args['post']            = $post;
+		$this->_template_args['event_attendees'] = array();
+		// process items in cart
+		$line_items = $this->_transaction->get_many_related('Line_Item', array(array('LIN_type' => 'line-item')));
+		if ( ! empty($line_items)) {
+			foreach ($line_items as $item) {
+				if ($item instanceof EE_Line_Item) {
+					switch ($item->OBJ_type()) {
+
+						case 'Event' :
+							break;
+
+						case 'Ticket' :
+							$ticket = $item->ticket();
+							//right now we're only handling tickets here.  Cause its expected that only tickets will have attendees right?
+							if ( ! $ticket instanceof EE_Ticket) {
+								continue;
+							}
+							try {
+								$event_name = $ticket->get_event_name();
+							} catch (Exception $e) {
+								EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
+								$event_name = esc_html__('Unknown Event', 'event_espresso');
+							}
+							$event_name .= ' - ' . $item->get('LIN_name');
+							$ticket_price = EEH_Template::format_currency($item->get('LIN_unit_price'));
+							// now get all of the registrations for this transaction that use this ticket
+							$registrations = $ticket->get_many_related('Registration',
+								array(array('TXN_ID' => $this->_transaction->ID())));
+							foreach ($registrations as $registration) {
+								if ( ! $registration instanceof EE_Registration) {
+									continue;
+								}
+								$this->_template_args['event_attendees'][$registration->ID()]['STS_ID']            = $registration->status_ID();
+								$this->_template_args['event_attendees'][$registration->ID()]['att_num']           = $registration->count();
+								$this->_template_args['event_attendees'][$registration->ID()]['event_ticket_name'] = $event_name;
+								$this->_template_args['event_attendees'][$registration->ID()]['ticket_price']      = $ticket_price;
+								// attendee info
+								$attendee = $registration->get_first_related('Attendee');
+								if ($attendee instanceof EE_Attendee) {
+									$this->_template_args['event_attendees'][$registration->ID()]['att_id']   = $attendee->ID();
+									$this->_template_args['event_attendees'][$registration->ID()]['attendee'] = $attendee->full_name();
+									$this->_template_args['event_attendees'][$registration->ID()]['email']    = '<a href="mailto:' . $attendee->email() . '?subject=' . $event_name . esc_html__(' Event',
+											'event_espresso') . '">' . $attendee->email() . '</a>';
+									$this->_template_args['event_attendees'][$registration->ID()]['address']  = EEH_Address::format($attendee,
+										'inline', false, false);
+								} else {
+									$this->_template_args['event_attendees'][$registration->ID()]['att_id']   = '';
+									$this->_template_args['event_attendees'][$registration->ID()]['attendee'] = '';
+									$this->_template_args['event_attendees'][$registration->ID()]['email']    = '';
+									$this->_template_args['event_attendees'][$registration->ID()]['address']  = '';
+								}
+							}
+							break;
+
+					}
+				}
+			}
+
+			$this->_template_args['transaction_form_url'] = add_query_arg(array(
+				'action'  => 'edit_transaction',
+				'process' => 'attendees'
+			), TXN_ADMIN_URL);
+			echo EEH_Template::display_template(TXN_TEMPLATE_PATH . 'txn_admin_details_main_meta_box_attendees.template.php',
+				$this->_template_args, true);
+
+		} else {
+			echo sprintf(
+				esc_html__('%1$sFor some reason, there are no attendees registered for this transaction. Likely the registration was abandoned in process.%2$s',
+					'event_espresso'),
+				'<p class="important-notice">',
+				'</p>'
+			);
+		}
+	}
+
+
+	/**
+	 * txn_registrant_side_meta_box
+	 * generates HTML for the Edit Transaction side meta box
+	 *
+	 * @access public
+	 * @throws \EE_Error
+	 * @return void
+	 */
+	public function txn_registrant_side_meta_box()
+	{
+		$primary_att = $this->_transaction->primary_registration() instanceof EE_Registration ? $this->_transaction->primary_registration()->get_first_related('Attendee') : null;
+		if ( ! $primary_att instanceof EE_Attendee) {
+			$this->_template_args['no_attendee_message'] = esc_html__('There is no attached contact for this transaction.  The transaction either failed due to an error or was abandoned.',
+				'event_espresso');
+			$primary_att                                 = EEM_Attendee::instance()->create_default_object();
+		}
+		$this->_template_args['ATT_ID']            = $primary_att->ID();
+		$this->_template_args['prime_reg_fname']   = $primary_att->fname();
+		$this->_template_args['prime_reg_lname']   = $primary_att->lname();
+		$this->_template_args['prime_reg_email']   = $primary_att->email();
+		$this->_template_args['prime_reg_phone']   = $primary_att->phone();
+		$this->_template_args['edit_attendee_url'] = EE_Admin_Page::add_query_args_and_nonce(array(
+			'action' => 'edit_attendee',
+			'post'   => $primary_att->ID()
+		), REG_ADMIN_URL);
+		// get formatted address for registrant
+		$this->_template_args['formatted_address'] = EEH_Address::format($primary_att);
+		echo EEH_Template::display_template(TXN_TEMPLATE_PATH . 'txn_admin_details_side_meta_box_registrant.template.php',
+			$this->_template_args, true);
+	}
+
+
+	/**
+	 * txn_billing_info_side_meta_box
+	 *    generates HTML for the Edit Transaction side meta box
+	 *
+	 * @access public
+	 * @return void
+	 */
+	public function txn_billing_info_side_meta_box()
+	{
+
+		$this->_template_args['billing_form']     = $this->_transaction->billing_info();
+		$this->_template_args['billing_form_url'] = add_query_arg(
+			array('action' => 'edit_transaction', 'process' => 'billing'),
+			TXN_ADMIN_URL
+		);
+
+		$template_path = TXN_TEMPLATE_PATH . 'txn_admin_details_side_meta_box_billing_info.template.php';
+		echo EEH_Template::display_template($template_path, $this->_template_args, true);/**/
+	}
+
+
+	/**
+	 * apply_payments_or_refunds
+	 *    registers a payment or refund made towards a transaction
+	 *
+	 * @access public
+	 * @return void
+	 */
+	public function apply_payments_or_refunds()
+	{
+		$json_response_data = array('return_data' => false);
+		$valid_data         = $this->_validate_payment_request_data();
+		if ( ! empty($valid_data)) {
+			$PAY_ID = $valid_data['PAY_ID'];
+			//save  the new payment
+			$payment = $this->_create_payment_from_request_data($valid_data);
+			// get the TXN for this payment
+			$transaction = $payment->transaction();
+			// verify transaction
+			if ($transaction instanceof EE_Transaction) {
+				// calculate_total_payments_and_update_status
+				$this->_process_transaction_payments($transaction);
+				$REG_IDs = $this->_get_REG_IDs_to_apply_payment_to($payment);
+				$this->_remove_existing_registration_payments($payment, $PAY_ID);
+				// apply payment to registrations (if applicable)
+				if ( ! empty($REG_IDs)) {
+					$this->_update_registration_payments($transaction, $payment, $REG_IDs);
+					$this->_maybe_send_notifications();
+					// now process status changes for the same registrations
+					$this->_process_registration_status_change($transaction, $REG_IDs);
+				}
+				$this->_maybe_send_notifications($payment);
+				//prepare to render page
+				$json_response_data['return_data'] = $this->_build_payment_json_response($payment, $REG_IDs);
+				do_action('AHEE__Transactions_Admin_Page__apply_payments_or_refund__after_recording', $transaction,
+					$payment);
+			} else {
+				EE_Error::add_error(
+					esc_html__('A valid Transaction for this payment could not be retrieved.', 'event_espresso'),
+					__FILE__, __FUNCTION__, __LINE__
+				);
+			}
+		} else {
+			EE_Error::add_error(esc_html__('The payment form data could not be processed. Please try again.',
+				'event_espresso'), __FILE__, __FUNCTION__, __LINE__);
+		}
+
+		$notices              = EE_Error::get_notices(false, false, false);
+		$this->_template_args = array(
+			'data'    => $json_response_data,
+			'error'   => $notices['errors'],
+			'success' => $notices['success']
+		);
+		$this->_return_json();
+	}
+
+
+	/**
+	 * _validate_payment_request_data
+	 *
+	 * @return array
+	 */
+	protected function _validate_payment_request_data()
+	{
+		if ( ! isset($this->_req_data['txn_admin_payment'])) {
+			return false;
+		}
+		$payment_form = $this->_generate_payment_form_section();
+		try {
+			if ($payment_form->was_submitted()) {
+				$payment_form->receive_form_submission();
+				if ( ! $payment_form->is_valid()) {
+					$submission_error_messages = array();
+					foreach ($payment_form->get_validation_errors_accumulated() as $validation_error) {
+						if ($validation_error instanceof EE_Validation_Error) {
+							$submission_error_messages[] = sprintf(
+								_x('%s : %s', 'Form Section Name : Form Validation Error', 'event_espresso'),
+								$validation_error->get_form_section()->html_label_text(),
+								$validation_error->getMessage()
+							);
+						}
+					}
+					EE_Error::add_error(join('<br />', $submission_error_messages), __FILE__, __FUNCTION__, __LINE__);
+
+					return array();
+				}
+			}
+		} catch (EE_Error $e) {
+			EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
+
+			return array();
+		}
+
+		return $payment_form->valid_data();
+	}
+
+
+	/**
+	 * _generate_payment_form_section
+	 *
+	 * @return EE_Form_Section_Proper
+	 */
+	protected function _generate_payment_form_section()
+	{
+		return new EE_Form_Section_Proper(
+			array(
+				'name'        => 'txn_admin_payment',
+				'subsections' => array(
+					'PAY_ID'          => new EE_Text_Input(
+						array(
+							'default'               => 0,
+							'required'              => false,
+							'html_label_text'       => esc_html__('Payment ID', 'event_espresso'),
+							'validation_strategies' => array(new EE_Int_Normalization())
+						)
+					),
+					'TXN_ID'          => new EE_Text_Input(
+						array(
+							'default'               => 0,
+							'required'              => true,
+							'html_label_text'       => esc_html__('Transaction ID', 'event_espresso'),
+							'validation_strategies' => array(new EE_Int_Normalization())
+						)
+					),
+					'type'            => new EE_Text_Input(
+						array(
+							'default'               => 1,
+							'required'              => true,
+							'html_label_text'       => esc_html__('Payment or Refund', 'event_espresso'),
+							'validation_strategies' => array(new EE_Int_Normalization())
+						)
+					),
+					'amount'          => new EE_Text_Input(
+						array(
+							'default'               => 0,
+							'required'              => true,
+							'html_label_text'       => esc_html__('Payment amount', 'event_espresso'),
+							'validation_strategies' => array(new EE_Float_Normalization())
+						)
+					),
+					'status'          => new EE_Text_Input(
+						array(
+							'default'         => EEM_Payment::status_id_approved,
+							'required'        => true,
+							'html_label_text' => esc_html__('Payment status', 'event_espresso'),
+						)
+					),
+					'PMD_ID'          => new EE_Text_Input(
+						array(
+							'default'               => 2,
+							'required'              => true,
+							'html_label_text'       => esc_html__('Payment Method', 'event_espresso'),
+							'validation_strategies' => array(new EE_Int_Normalization())
+						)
+					),
+					'date'            => new EE_Text_Input(
+						array(
+							'default'         => time(),
+							'required'        => true,
+							'html_label_text' => esc_html__('Payment date', 'event_espresso'),
+						)
+					),
+					'txn_id_chq_nmbr' => new EE_Text_Input(
+						array(
+							'default'               => '',
+							'required'              => false,
+							'html_label_text'       => esc_html__('Transaction or Cheque Number', 'event_espresso'),
+							'validation_strategies' => array(
+								new EE_Max_Length_Validation_Strategy(esc_html__('Input too long', 'event_espresso'),
+									100),
+							)
+						)
+					),
+					'po_number'       => new EE_Text_Input(
+						array(
+							'default'               => '',
+							'required'              => false,
+							'html_label_text'       => esc_html__('Purchase Order Number', 'event_espresso'),
+							'validation_strategies' => array(
+								new EE_Max_Length_Validation_Strategy(esc_html__('Input too long', 'event_espresso'),
+									100),
+							)
+						)
+					),
+					'accounting'      => new EE_Text_Input(
+						array(
+							'default'               => '',
+							'required'              => false,
+							'html_label_text'       => esc_html__('Extra Field for Accounting', 'event_espresso'),
+							'validation_strategies' => array(
+								new EE_Max_Length_Validation_Strategy(esc_html__('Input too long', 'event_espresso'),
+									100),
+							)
+						)
+					),
+				)
+			)
+		);
+	}
+
+
+	/**
+	 * _create_payment_from_request_data
+	 *
+	 * @param array $valid_data
+	 *
+	 * @return EE_Payment
+	 */
+	protected function _create_payment_from_request_data($valid_data)
+	{
+		$PAY_ID = $valid_data['PAY_ID'];
+		// get payment amount
+		$amount = $valid_data['amount'] ? abs($valid_data['amount']) : 0;
+		// payments have a type value of 1 and refunds have a type value of -1
+		// so multiplying amount by type will give a positive value for payments, and negative values for refunds
+		$amount = $valid_data['type'] < 0 ? $amount * -1 : $amount;
+		// for some reason the date string coming in has extra spaces between the date and time.  This fixes that.
+		$date    = $valid_data['date'] ? preg_replace('/\s+/', ' ', $valid_data['date']) : date('Y-m-d g:i a',
+			current_time('timestamp'));
+		$payment = EE_Payment::new_instance(
+			array(
+				'TXN_ID'              => $valid_data['TXN_ID'],
+				'STS_ID'              => $valid_data['status'],
+				'PAY_timestamp'       => $date,
+				'PAY_source'          => EEM_Payment_Method::scope_admin,
+				'PMD_ID'              => $valid_data['PMD_ID'],
+				'PAY_amount'          => $amount,
+				'PAY_txn_id_chq_nmbr' => $valid_data['txn_id_chq_nmbr'],
+				'PAY_po_number'       => $valid_data['po_number'],
+				'PAY_extra_accntng'   => $valid_data['accounting'],
+				'PAY_details'         => $valid_data,
+				'PAY_ID'              => $PAY_ID
+			),
+			'',
+			array('Y-m-d', 'g:i a')
+		);
+
+		if ( ! $payment->save()) {
+			EE_Error::add_error(
+				sprintf(
+					esc_html__('Payment %1$d has not been successfully saved to the database.', 'event_espresso'),
+					$payment->ID()
+				),
+				__FILE__, __FUNCTION__, __LINE__
+			);
+		}
+
+		return $payment;
+	}
+
+
+	/**
+	 * _process_transaction_payments
+	 *
+	 * @param \EE_Transaction $transaction
+	 *
+	 * @return array
+	 */
+	protected function _process_transaction_payments(EE_Transaction $transaction)
+	{
+		/** @type EE_Transaction_Payments $transaction_payments */
+		$transaction_payments = EE_Registry::instance()->load_class('Transaction_Payments');
+		//update the transaction with this payment
+		if ($transaction_payments->calculate_total_payments_and_update_status($transaction)) {
+			EE_Error::add_success(esc_html__('The payment has been processed successfully.', 'event_espresso'),
+				__FILE__, __FUNCTION__, __LINE__);
+		} else {
+			EE_Error::add_error(
+				esc_html__('The payment was processed successfully but the amount paid for the transaction was not updated.',
+					'event_espresso')
+				, __FILE__, __FUNCTION__, __LINE__
+			);
+		}
+	}
+
+
+	/**
+	 * _get_REG_IDs_to_apply_payment_to
+	 *
+	 * returns a list of registration IDs that the payment will apply to
+	 *
+	 * @param \EE_Payment $payment
+	 *
+	 * @return array
+	 */
+	protected function _get_REG_IDs_to_apply_payment_to(EE_Payment $payment)
+	{
+		$REG_IDs = array();
+		// grab array of IDs for specific registrations to apply changes to
+		if (isset($this->_req_data['txn_admin_payment']['registrations'])) {
+			$REG_IDs = (array)$this->_req_data['txn_admin_payment']['registrations'];
+		}
+		//nothing specified ? then get all reg IDs
+		if (empty($REG_IDs)) {
+			$registrations = $payment->transaction()->registrations();
+			$REG_IDs       = ! empty($registrations) ? array_keys($registrations) : $this->_get_existing_reg_payment_REG_IDs($payment);
+		}
+
+		// ensure that REG_IDs are integers and NOT strings
+		return array_map('intval', $REG_IDs);
+	}
+
+
+	/**
+	 * @return array
+	 */
+	public function existing_reg_payment_REG_IDs()
+	{
+		return $this->_existing_reg_payment_REG_IDs;
+	}
+
+
+	/**
+	 * @param array $existing_reg_payment_REG_IDs
+	 */
+	public function set_existing_reg_payment_REG_IDs($existing_reg_payment_REG_IDs = null)
+	{
+		$this->_existing_reg_payment_REG_IDs = $existing_reg_payment_REG_IDs;
+	}
+
+
+	/**
+	 * _get_existing_reg_payment_REG_IDs
+	 *
+	 * returns a list of registration IDs that the payment is currently related to
+	 * as recorded in the database
+	 *
+	 * @param \EE_Payment $payment
+	 *
+	 * @return array
+	 */
+	protected function _get_existing_reg_payment_REG_IDs(EE_Payment $payment)
+	{
+		if ($this->existing_reg_payment_REG_IDs() === null) {
+			// let's get any existing reg payment records for this payment
+			$existing_reg_payment_REG_IDs = $payment->get_many_related('Registration');
+			// but we only want the REG IDs, so grab the array keys
+			$existing_reg_payment_REG_IDs = ! empty($existing_reg_payment_REG_IDs) ? array_keys($existing_reg_payment_REG_IDs) : array();
+			$this->set_existing_reg_payment_REG_IDs($existing_reg_payment_REG_IDs);
+		}
+
+		return $this->existing_reg_payment_REG_IDs();
+	}
+
+
+	/**
+	 * _remove_existing_registration_payments
+	 *
+	 * this calculates the difference between existing relations
+	 * to the supplied payment and the new list registration IDs,
+	 * removes any related registrations that no longer apply,
+	 * and then updates the registration paid fields
+	 *
+	 * @param \EE_Payment $payment
+	 * @param int         $PAY_ID
+	 *
+	 * @return bool;
+	 */
+	protected function _remove_existing_registration_payments(EE_Payment $payment, $PAY_ID = 0)
+	{
+		// newly created payments will have nothing recorded for $PAY_ID
+		if ($PAY_ID == 0) {
+			return false;
+		}
+		$existing_reg_payment_REG_IDs = $this->_get_existing_reg_payment_REG_IDs($payment);
+		if (empty($existing_reg_payment_REG_IDs)) {
+			return false;
+		}
+		/** @type EE_Transaction_Payments $transaction_payments */
+		$transaction_payments = EE_Registry::instance()->load_class('Transaction_Payments');
+
+		return $transaction_payments->delete_registration_payments_and_update_registrations(
+			$payment,
+			array(
+				array(
+					'PAY_ID' => $payment->ID(),
+					'REG_ID' => array('IN', $existing_reg_payment_REG_IDs),
+				)
+			)
+		);
+	}
+
+
+	/**
+	 * _update_registration_payments
+	 *
+	 * this applies the payments to the selected registrations
+	 * but only if they have not already been paid for
+	 *
+	 * @param  EE_Transaction $transaction
+	 * @param \EE_Payment     $payment
+	 * @param array           $REG_IDs
+	 *
+	 * @return bool
+	 */
+	protected function _update_registration_payments(
+		EE_Transaction $transaction,
+		EE_Payment $payment,
+		$REG_IDs = array()
+	) {
+		// we can pass our own custom set of registrations to EE_Payment_Processor::process_registration_payments()
+		// so let's do that using our set of REG_IDs from the form
+		$registration_query_where_params = array(
+			'REG_ID' => array('IN', $REG_IDs)
+		);
+		// but add in some conditions regarding payment,
+		// so that we don't apply payments to registrations that are free or have already been paid for
+		// but ONLY if the payment is NOT a refund ( ie: the payment amount is not negative )
+		if ( ! $payment->is_a_refund()) {
+			$registration_query_where_params['REG_final_price']  = array('!=', 0);
+			$registration_query_where_params['REG_final_price*'] = array('!=', 'REG_paid', true);
+		}
+		//EEH_Debug_Tools::printr( $registration_query_where_params, '$registration_query_where_params', __FILE__, __LINE__ );
+		$registrations = $transaction->registrations(array($registration_query_where_params));
+		if ( ! empty($registrations)) {
+			/** @type EE_Payment_Processor $payment_processor */
+			$payment_processor = EE_Registry::instance()->load_core('Payment_Processor');
+			$payment_processor->process_registration_payments($transaction, $payment, $registrations);
+		}
+	}
+
+
+	/**
+	 * _process_registration_status_change
+	 *
+	 * This processes requested registration status changes for all the registrations
+	 * on a given transaction and (optionally) sends out notifications for the changes.
+	 *
+	 * @param  EE_Transaction $transaction
+	 * @param array           $REG_IDs
+	 *
+	 * @return bool
+	 */
+	protected function _process_registration_status_change(EE_Transaction $transaction, $REG_IDs = array())
+	{
+		// first if there is no change in status then we get out.
+		if (
+			! isset($this->_req_data['txn_reg_status_change'], $this->_req_data['txn_reg_status_change']['reg_status'])
+			|| $this->_req_data['txn_reg_status_change']['reg_status'] == 'NAN'
+		) {
+			//no error message, no change requested, just nothing to do man.
+			return false;
+		}
+		/** @type EE_Transaction_Processor $transaction_processor */
+		$transaction_processor = EE_Registry::instance()->load_class('Transaction_Processor');
+
+		// made it here dude?  Oh WOW.  K, let's take care of changing the statuses
+		return $transaction_processor->manually_update_registration_statuses(
+			$transaction,
+			sanitize_text_field($this->_req_data['txn_reg_status_change']['reg_status']),
+			array(array('REG_ID' => array('IN', $REG_IDs)))
+		);
+	}
+
+
+	/**
+	 * _build_payment_json_response
+	 *
+	 * @access public
+	 *
+	 * @param \EE_Payment $payment
+	 * @param array       $REG_IDs
+	 * @param bool | null $delete_txn_reg_status_change
+	 *
+	 * @return array
+	 */
+	protected function _build_payment_json_response(
+		EE_Payment $payment,
+		$REG_IDs = array(),
+		$delete_txn_reg_status_change = null
+	) {
+		// was the payment deleted ?
+		if (is_bool($delete_txn_reg_status_change)) {
+			return array(
+				'PAY_ID'                       => $payment->ID(),
+				'amount'                       => $payment->amount(),
+				'total_paid'                   => $payment->transaction()->paid(),
+				'txn_status'                   => $payment->transaction()->status_ID(),
+				'pay_status'                   => $payment->STS_ID(),
+				'registrations'                => $this->_registration_payment_data_array($REG_IDs),
+				'delete_txn_reg_status_change' => $delete_txn_reg_status_change,
+			);
+		} else {
+			$this->_get_payment_status_array();
+
+			return array(
+				'amount'           => $payment->amount(),
+				'total_paid'       => $payment->transaction()->paid(),
+				'txn_status'       => $payment->transaction()->status_ID(),
+				'pay_status'       => $payment->STS_ID(),
+				'PAY_ID'           => $payment->ID(),
+				'STS_ID'           => $payment->STS_ID(),
+				'status'           => self::$_pay_status[$payment->STS_ID()],
+				'date'             => $payment->timestamp('Y-m-d', 'h:i a'),
+				'method'           => strtoupper($payment->source()),
+				'PM_ID'            => $payment->payment_method() ? $payment->payment_method()->ID() : 1,
+				'gateway'          => $payment->payment_method() ? $payment->payment_method()->admin_name() : esc_html__("Unknown",
+					'event_espresso'),
+				'gateway_response' => $payment->gateway_response(),
+				'txn_id_chq_nmbr'  => $payment->txn_id_chq_nmbr(),
+				'po_number'        => $payment->po_number(),
+				'extra_accntng'    => $payment->extra_accntng(),
+				'registrations'    => $this->_registration_payment_data_array($REG_IDs),
+			);
+		}
+	}
+
+
+	/**
+	 * delete_payment
+	 *    delete a payment or refund made towards a transaction
+	 *
+	 * @access public
+	 * @return void
+	 */
+	public function delete_payment()
+	{
+		$json_response_data = array('return_data' => false);
+		$PAY_ID             = isset($this->_req_data['delete_txn_admin_payment'], $this->_req_data['delete_txn_admin_payment']['PAY_ID']) ? absint($this->_req_data['delete_txn_admin_payment']['PAY_ID']) : 0;
+		if ($PAY_ID) {
+			$delete_txn_reg_status_change = isset($this->_req_data['delete_txn_reg_status_change']) ? $this->_req_data['delete_txn_reg_status_change'] : false;
+			$payment                      = EEM_Payment::instance()->get_one_by_ID($PAY_ID);
+			if ($payment instanceof EE_Payment) {
+				$REG_IDs = $this->_get_existing_reg_payment_REG_IDs($payment);
+				/** @type EE_Transaction_Payments $transaction_payments */
+				$transaction_payments = EE_Registry::instance()->load_class('Transaction_Payments');
+				if ($transaction_payments->delete_payment_and_update_transaction($payment)) {
+					$json_response_data['return_data'] = $this->_build_payment_json_response($payment, $REG_IDs,
+						$delete_txn_reg_status_change);
+					if ($delete_txn_reg_status_change) {
+						$this->_req_data['txn_reg_status_change'] = $delete_txn_reg_status_change;
+						//MAKE sure we also add the delete_txn_req_status_change to the
+						//$_REQUEST global because that's how messages will be looking for it.
+						$_REQUEST['txn_reg_status_change'] = $delete_txn_reg_status_change;
+						$this->_maybe_send_notifications();
+						$this->_process_registration_status_change($payment->transaction(), $REG_IDs);
+					}
+				}
+			} else {
+				EE_Error::add_error(
+					esc_html__('Valid Payment data could not be retrieved from the database.', 'event_espresso'),
+					__FILE__, __FUNCTION__, __LINE__
+				);
+			}
+		} else {
+			EE_Error::add_error(
+				esc_html__('A valid Payment ID was not received, therefore payment form data could not be loaded.',
+					'event_espresso'),
+				__FILE__, __FUNCTION__, __LINE__
+			);
+		}
+		$notices              = EE_Error::get_notices(false, false, false);
+		$this->_template_args = array(
+			'data'      => $json_response_data,
+			'success'   => $notices['success'],
+			'error'     => $notices['errors'],
+			'attention' => $notices['attention']
+		);
+		$this->_return_json();
+	}
+
+
+	/**
+	 * _registration_payment_data_array
+	 * adds info for 'owing' and 'paid' for each registration to the json response
+	 *
+	 * @access protected
+	 *
+	 * @param array $REG_IDs
+	 *
+	 * @return array
+	 */
+	protected function _registration_payment_data_array($REG_IDs)
+	{
+		$registration_payment_data = array();
+		//if non empty reg_ids lets get an array of registrations and update the values for the apply_payment/refund rows.
+		if ( ! empty($REG_IDs)) {
+			$registrations = EEM_Registration::instance()->get_all(array(array('REG_ID' => array('IN', $REG_IDs))));
+			foreach ($registrations as $registration) {
+				if ($registration instanceof EE_Registration) {
+					$registration_payment_data[$registration->ID()] = array(
+						'paid'  => $registration->pretty_paid(),
+						'owing' => EEH_Template::format_currency($registration->final_price() - $registration->paid()),
+					);
+				}
+			}
+		}
+
+		return $registration_payment_data;
+	}
+
+
+	/**
+	 * _maybe_send_notifications
+	 *
+	 * determines whether or not the admin has indicated that notifications should be sent.
+	 * If so, will toggle a filter switch for delivering registration notices.
+	 * If passed an EE_Payment object, then it will trigger payment notifications instead.
+	 *
+	 * @access protected
+	 *
+	 * @param \EE_Payment | null $payment
+	 */
+	protected function _maybe_send_notifications($payment = null)
+	{
+		switch ($payment instanceof EE_Payment) {
+			// payment notifications
+			case true :
+				if (
+					isset(
+						$this->_req_data['txn_payments'],
+						$this->_req_data['txn_payments']['send_notifications']
+					) &&
+					filter_var($this->_req_data['txn_payments']['send_notifications'], FILTER_VALIDATE_BOOLEAN)
+				) {
+					$this->_process_payment_notification($payment);
+				}
+				break;
+			// registration notifications
+			case false :
+				if (
+					isset(
+						$this->_req_data['txn_reg_status_change'],
+						$this->_req_data['txn_reg_status_change']['send_notifications']
+					) &&
+					filter_var($this->_req_data['txn_reg_status_change']['send_notifications'], FILTER_VALIDATE_BOOLEAN)
+				) {
+					add_filter('FHEE__EED_Messages___maybe_registration__deliver_notifications', '__return_true');
+				}
+				break;
+		}
+	}
+
+
+	/**
+	 * _send_payment_reminder
+	 *    generates HTML for the View Transaction Details Admin page
+	 *
+	 * @access protected
+	 * @return void
+	 */
+	protected function _send_payment_reminder()
+	{
+		$TXN_ID      = ( ! empty($this->_req_data['TXN_ID'])) ? absint($this->_req_data['TXN_ID']) : false;
+		$transaction = EEM_Transaction::instance()->get_one_by_ID($TXN_ID);
+		$query_args  = isset($this->_req_data['redirect_to']) ? array(
+			'action' => $this->_req_data['redirect_to'],
+			'TXN_ID' => $this->_req_data['TXN_ID']
+		) : array();
+		do_action('AHEE__Transactions_Admin_Page___send_payment_reminder__process_admin_payment_reminder',
+			$transaction);
+		$this->_redirect_after_action(false, esc_html__('payment reminder', 'event_espresso'),
+			esc_html__('sent', 'event_espresso'), $query_args, true);
+	}
+
+
+	/**
+	 *  get_transactions
+	 *    get transactions for given parameters (used by list table)
+	 *
+	 * @param  int     $perpage how many transactions displayed per page
+	 * @param  boolean $count   return the count or objects
+	 * @param string   $view
+	 *
+	 * @return mixed int = count || array of transaction objects
+	 */
+	public function get_transactions($perpage, $count = false, $view = '')
+	{
+
+		$TXN = EEM_Transaction::instance();
+
+		$start_date = isset($this->_req_data['txn-filter-start-date']) ? wp_strip_all_tags($this->_req_data['txn-filter-start-date']) : date('m/d/Y',
+			strtotime('-10 year'));
+		$end_date   = isset($this->_req_data['txn-filter-end-date']) ? wp_strip_all_tags($this->_req_data['txn-filter-end-date']) : date('m/d/Y');
+
+		//make sure our timestamps start and end right at the boundaries for each day
+		$start_date = date('Y-m-d', strtotime($start_date)) . ' 00:00:00';
+		$end_date   = date('Y-m-d', strtotime($end_date)) . ' 23:59:59';
+
+
+		//convert to timestamps
+		$start_date = strtotime($start_date);
+		$end_date   = strtotime($end_date);
+
+		//makes sure start date is the lowest value and vice versa
+		$start_date = min($start_date, $end_date);
+		$end_date   = max($start_date, $end_date);
+
+		//convert to correct format for query
+		$start_date = EEM_Transaction::instance()->convert_datetime_for_query('TXN_timestamp',
+			date('Y-m-d H:i:s', $start_date), 'Y-m-d H:i:s');
+		$end_date   = EEM_Transaction::instance()->convert_datetime_for_query('TXN_timestamp',
+			date('Y-m-d H:i:s', $end_date), 'Y-m-d H:i:s');
+
+
+		//set orderby
+		$this->_req_data['orderby'] = ! empty($this->_req_data['orderby']) ? $this->_req_data['orderby'] : '';
+
+		switch ($this->_req_data['orderby']) {
+			case 'TXN_ID':
+				$orderby = 'TXN_ID';
+				break;
+			case 'ATT_fname':
+				$orderby = 'Registration.Attendee.ATT_fname';
+				break;
+			case 'event_name':
+				$orderby = 'Registration.Event.EVT_name';
+				break;
+			default: //'TXN_timestamp'
+				$orderby = 'TXN_timestamp';
+		}
+
+		$sort         = (isset($this->_req_data['order']) && ! empty($this->_req_data['order'])) ? $this->_req_data['order'] : 'DESC';
+		$current_page = isset($this->_req_data['paged']) && ! empty($this->_req_data['paged']) ? $this->_req_data['paged'] : 1;
+		$per_page     = isset($perpage) && ! empty($perpage) ? $perpage : 10;
+		$per_page     = isset($this->_req_data['perpage']) && ! empty($this->_req_data['perpage']) ? $this->_req_data['perpage'] : $per_page;
+
+		$offset = ($current_page - 1) * $per_page;
+		$limit  = array($offset, $per_page);
+
+		$_where = array(
+			'TXN_timestamp'          => array('BETWEEN', array($start_date, $end_date)),
+			'Registration.REG_count' => 1
+		);
+
+		if (isset($this->_req_data['EVT_ID'])) {
+			$_where['Registration.EVT_ID'] = $this->_req_data['EVT_ID'];
+		}
+
+		if (isset($this->_req_data['s'])) {
+			$search_string = '%' . $this->_req_data['s'] . '%';
+			$_where['OR']  = array(
+				'Registration.Event.EVT_name'         => array('LIKE', $search_string),
+				'Registration.Event.EVT_desc'         => array('LIKE', $search_string),
+				'Registration.Event.EVT_short_desc'   => array('LIKE', $search_string),
+				'Registration.Attendee.ATT_full_name' => array('LIKE', $search_string),
+				'Registration.Attendee.ATT_fname'     => array('LIKE', $search_string),
+				'Registration.Attendee.ATT_lname'     => array('LIKE', $search_string),
+				'Registration.Attendee.ATT_short_bio' => array('LIKE', $search_string),
+				'Registration.Attendee.ATT_email'     => array('LIKE', $search_string),
+				'Registration.Attendee.ATT_address'   => array('LIKE', $search_string),
+				'Registration.Attendee.ATT_address2'  => array('LIKE', $search_string),
+				'Registration.Attendee.ATT_city'      => array('LIKE', $search_string),
+				'Registration.REG_final_price'        => array('LIKE', $search_string),
+				'Registration.REG_code'               => array('LIKE', $search_string),
+				'Registration.REG_count'              => array('LIKE', $search_string),
+				'Registration.REG_group_size'         => array('LIKE', $search_string),
+				'Registration.Ticket.TKT_name'        => array('LIKE', $search_string),
+				'Registration.Ticket.TKT_description' => array('LIKE', $search_string),
+				'Payment.PAY_source'                  => array('LIKE', $search_string),
+				'Payment.Payment_Method.PMD_name'     => array('LIKE', $search_string),
+				'TXN_session_data'                    => array('LIKE', $search_string),
+				'Payment.PAY_txn_id_chq_nmbr'         => array('LIKE', $search_string)
+			);
+		}
+
+		//failed transactions
+		$failed    = ( ! empty($this->_req_data['status']) && $this->_req_data['status'] == 'failed' && ! $count) || ($count && $view == 'failed') ? true : false;
+		$abandoned = ( ! empty($this->_req_data['status']) && $this->_req_data['status'] == 'abandoned' && ! $count) || ($count && $view == 'abandoned') ? true : false;
+
+		if ($failed) {
+			$_where['STS_ID'] = EEM_Transaction::failed_status_code;
+		} else if ($abandoned) {
+			$_where['STS_ID'] = EEM_Transaction::abandoned_status_code;
+		} else {
+			$_where['STS_ID']  = array('!=', EEM_Transaction::failed_status_code);
+			$_where['STS_ID*'] = array('!=', EEM_Transaction::abandoned_status_code);
+		}
+
+		$query_params = array(
+			$_where,
+			'order_by' => array($orderby => $sort),
+			'limit' => $limit,
+			'default_where_conditions' => EEM_Base::default_where_conditions_this_only
+		);
+
+		$transactions = $count ? $TXN->count(array($_where), 'TXN_ID', true) : $TXN->get_all($query_params);
+
+
+		return $transactions;
+
+	}
 
 
 }

modules/messages/EED_Messages.module.php

Indentation +1080 added lines, -1080 removed lines

@@ -13,1095 +13,1095 @@
 class EED_Messages extends EED_Module
 {
 
-    /**
-     * This holds the EE_messages controller
-     *
-     * @deprecated 4.9.0
-     * @var EE_messages $_EEMSG
-     */
-    protected static $_EEMSG;
-
-    /**
-     * @type EE_Message_Resource_Manager $_message_resource_manager
-     */
-    protected static $_message_resource_manager;
-
-    /**
-     * This holds the EE_Messages_Processor business class.
-     *
-     * @type EE_Messages_Processor
-     */
-    protected static $_MSG_PROCESSOR;
-
-    /**
-     * holds all the paths for various messages components.
-     * Utilized by autoloader registry
-     *
-     * @var array
-     */
-    protected static $_MSG_PATHS;
-
-
-    /**
-     * This will hold an array of messages template packs that are registered in the messages system.
-     * Format is:
-     * array(
-     *    'template_pack_dbref' => EE_Messages_Template_Pack (instance)
-     * )
-     *
-     * @var EE_Messages_Template_Pack[]
-     */
-    protected static $_TMP_PACKS = array();
-
-
-    /**
-     * @return EED_Messages
-     */
-    public static function instance()
-    {
-        return parent::get_instance(__CLASS__);
-    }
-
-
-    /**
-     *  set_hooks - for hooking into EE Core, other modules, etc
-     *
-     * @since 4.5.0
-     * @return    void
-     */
-    public static function set_hooks()
-    {
-        //actions
-        add_action('AHEE__EE_Payment_Processor__update_txn_based_on_payment', array('EED_Messages', 'payment'), 10, 2);
-        add_action('AHEE__EE_Registration_Processor__trigger_registration_update_notifications',
-            array('EED_Messages', 'maybe_registration'), 10, 2);
-        //filters
-        add_filter('FHEE__EE_Registration__receipt_url__receipt_url',
-            array('EED_Messages', 'registration_message_trigger_url'), 10, 4);
-        add_filter('FHEE__EE_Registration__invoice_url__invoice_url',
-            array('EED_Messages', 'registration_message_trigger_url'), 10, 4);
-        //register routes
-        self::_register_routes();
-    }
-
-    /**
-     *    set_hooks_admin - for hooking into EE Admin Core, other modules, etc
-     *
-     * @access    public
-     * @return    void
-     */
-    public static function set_hooks_admin()
-    {
-        //actions
-        add_action('AHEE__EE_Payment_Processor__update_txn_based_on_payment', array('EED_Messages', 'payment'), 10, 2);
-        add_action('AHEE__Transactions_Admin_Page___send_payment_reminder__process_admin_payment_reminder',
-            array('EED_Messages', 'payment_reminder'), 10);
-        add_action('AHEE__EE_Registration_Processor__trigger_registration_update_notifications',
-            array('EED_Messages', 'maybe_registration'), 10, 3);
-        add_action('AHEE__Extend_Registrations_Admin_Page___newsletter_selected_send__with_registrations',
-            array('EED_Messages', 'send_newsletter_message'), 10, 2);
-        add_action('AHEE__EES_Espresso_Cancelled__process_shortcode__transaction',
-            array('EED_Messages', 'cancelled_registration'), 10);
-        add_action('AHEE__EE_Admin_Page___process_admin_payment_notification',
-            array('EED_Messages', 'process_admin_payment'), 10, 1);
-        //filters
-        add_filter('FHEE__EE_Admin_Page___process_resend_registration__success',
-            array('EED_Messages', 'process_resend'), 10, 2);
-        add_filter('FHEE__EE_Registration__receipt_url__receipt_url',
-            array('EED_Messages', 'registration_message_trigger_url'), 10, 4);
-        add_filter('FHEE__EE_Registration__invoice_url__invoice_url',
-            array('EED_Messages', 'registration_message_trigger_url'), 10, 4);
-    }
-
-
-    /**
-     * All the message triggers done by route go in here.
-     *
-     * @since 4.5.0
-     * @return void
-     */
-    protected static function _register_routes()
-    {
-        EE_Config::register_route('msg_url_trigger', 'Messages', 'run');
-        EE_Config::register_route('msg_cron_trigger', 'Messages', 'execute_batch_request');
-        EE_Config::register_route('msg_browser_trigger', 'Messages', 'browser_trigger');
-        EE_Config::register_route('msg_browser_error_trigger', 'Messages', 'browser_error_trigger');
-        do_action('AHEE__EED_Messages___register_routes');
-    }
-
-
-    /**
-     * This is called when a browser display trigger is executed.
-     * The browser display trigger is typically used when a already generated message is displayed directly in the
-     * browser.
-     *
-     * @since 4.9.0
-     * @param WP $WP
-     */
-    public function browser_trigger($WP)
-    {
-        //ensure controller is loaded
-        self::_load_controller();
-        $token = EE_Registry::instance()->REQ->get('token');
-        try {
-            $mtg = new EE_Message_Generated_From_Token($token, 'html', self::$_message_resource_manager);
-            self::$_MSG_PROCESSOR->generate_and_send_now($mtg);
-        } catch (EE_Error $e) {
-            $error_msg = __('Please note that a system message failed to send due to a technical issue.',
-                'event_espresso');
-            // add specific message for developers if WP_DEBUG in on
-            $error_msg .= '||' . $e->getMessage();
-            EE_Error::add_error($error_msg, __FILE__, __FUNCTION__, __LINE__);
-        }
-    }
-
-
-    /**
-     * This is called when a browser error trigger is executed.
-     * When triggered this will grab the EE_Message matching the token in the request and use that to get the error
-     * message and display it.
-     *
-     * @since 4.9.0
-     * @param $WP
-     */
-    public function browser_error_trigger($WP)
-    {
-        $token = EE_Registry::instance()->REQ->get('token');
-        if ($token) {
-            $message = EEM_Message::instance()->get_one_by_token($token);
-            if ($message instanceof EE_Message) {
-                header('HTTP/1.1 200 OK');
-                $error_msg = nl2br($message->error_message());
-                ?>
+	/**
+	 * This holds the EE_messages controller
+	 *
+	 * @deprecated 4.9.0
+	 * @var EE_messages $_EEMSG
+	 */
+	protected static $_EEMSG;
+
+	/**
+	 * @type EE_Message_Resource_Manager $_message_resource_manager
+	 */
+	protected static $_message_resource_manager;
+
+	/**
+	 * This holds the EE_Messages_Processor business class.
+	 *
+	 * @type EE_Messages_Processor
+	 */
+	protected static $_MSG_PROCESSOR;
+
+	/**
+	 * holds all the paths for various messages components.
+	 * Utilized by autoloader registry
+	 *
+	 * @var array
+	 */
+	protected static $_MSG_PATHS;
+
+
+	/**
+	 * This will hold an array of messages template packs that are registered in the messages system.
+	 * Format is:
+	 * array(
+	 *    'template_pack_dbref' => EE_Messages_Template_Pack (instance)
+	 * )
+	 *
+	 * @var EE_Messages_Template_Pack[]
+	 */
+	protected static $_TMP_PACKS = array();
+
+
+	/**
+	 * @return EED_Messages
+	 */
+	public static function instance()
+	{
+		return parent::get_instance(__CLASS__);
+	}
+
+
+	/**
+	 *  set_hooks - for hooking into EE Core, other modules, etc
+	 *
+	 * @since 4.5.0
+	 * @return    void
+	 */
+	public static function set_hooks()
+	{
+		//actions
+		add_action('AHEE__EE_Payment_Processor__update_txn_based_on_payment', array('EED_Messages', 'payment'), 10, 2);
+		add_action('AHEE__EE_Registration_Processor__trigger_registration_update_notifications',
+			array('EED_Messages', 'maybe_registration'), 10, 2);
+		//filters
+		add_filter('FHEE__EE_Registration__receipt_url__receipt_url',
+			array('EED_Messages', 'registration_message_trigger_url'), 10, 4);
+		add_filter('FHEE__EE_Registration__invoice_url__invoice_url',
+			array('EED_Messages', 'registration_message_trigger_url'), 10, 4);
+		//register routes
+		self::_register_routes();
+	}
+
+	/**
+	 *    set_hooks_admin - for hooking into EE Admin Core, other modules, etc
+	 *
+	 * @access    public
+	 * @return    void
+	 */
+	public static function set_hooks_admin()
+	{
+		//actions
+		add_action('AHEE__EE_Payment_Processor__update_txn_based_on_payment', array('EED_Messages', 'payment'), 10, 2);
+		add_action('AHEE__Transactions_Admin_Page___send_payment_reminder__process_admin_payment_reminder',
+			array('EED_Messages', 'payment_reminder'), 10);
+		add_action('AHEE__EE_Registration_Processor__trigger_registration_update_notifications',
+			array('EED_Messages', 'maybe_registration'), 10, 3);
+		add_action('AHEE__Extend_Registrations_Admin_Page___newsletter_selected_send__with_registrations',
+			array('EED_Messages', 'send_newsletter_message'), 10, 2);
+		add_action('AHEE__EES_Espresso_Cancelled__process_shortcode__transaction',
+			array('EED_Messages', 'cancelled_registration'), 10);
+		add_action('AHEE__EE_Admin_Page___process_admin_payment_notification',
+			array('EED_Messages', 'process_admin_payment'), 10, 1);
+		//filters
+		add_filter('FHEE__EE_Admin_Page___process_resend_registration__success',
+			array('EED_Messages', 'process_resend'), 10, 2);
+		add_filter('FHEE__EE_Registration__receipt_url__receipt_url',
+			array('EED_Messages', 'registration_message_trigger_url'), 10, 4);
+		add_filter('FHEE__EE_Registration__invoice_url__invoice_url',
+			array('EED_Messages', 'registration_message_trigger_url'), 10, 4);
+	}
+
+
+	/**
+	 * All the message triggers done by route go in here.
+	 *
+	 * @since 4.5.0
+	 * @return void
+	 */
+	protected static function _register_routes()
+	{
+		EE_Config::register_route('msg_url_trigger', 'Messages', 'run');
+		EE_Config::register_route('msg_cron_trigger', 'Messages', 'execute_batch_request');
+		EE_Config::register_route('msg_browser_trigger', 'Messages', 'browser_trigger');
+		EE_Config::register_route('msg_browser_error_trigger', 'Messages', 'browser_error_trigger');
+		do_action('AHEE__EED_Messages___register_routes');
+	}
+
+
+	/**
+	 * This is called when a browser display trigger is executed.
+	 * The browser display trigger is typically used when a already generated message is displayed directly in the
+	 * browser.
+	 *
+	 * @since 4.9.0
+	 * @param WP $WP
+	 */
+	public function browser_trigger($WP)
+	{
+		//ensure controller is loaded
+		self::_load_controller();
+		$token = EE_Registry::instance()->REQ->get('token');
+		try {
+			$mtg = new EE_Message_Generated_From_Token($token, 'html', self::$_message_resource_manager);
+			self::$_MSG_PROCESSOR->generate_and_send_now($mtg);
+		} catch (EE_Error $e) {
+			$error_msg = __('Please note that a system message failed to send due to a technical issue.',
+				'event_espresso');
+			// add specific message for developers if WP_DEBUG in on
+			$error_msg .= '||' . $e->getMessage();
+			EE_Error::add_error($error_msg, __FILE__, __FUNCTION__, __LINE__);
+		}
+	}
+
+
+	/**
+	 * This is called when a browser error trigger is executed.
+	 * When triggered this will grab the EE_Message matching the token in the request and use that to get the error
+	 * message and display it.
+	 *
+	 * @since 4.9.0
+	 * @param $WP
+	 */
+	public function browser_error_trigger($WP)
+	{
+		$token = EE_Registry::instance()->REQ->get('token');
+		if ($token) {
+			$message = EEM_Message::instance()->get_one_by_token($token);
+			if ($message instanceof EE_Message) {
+				header('HTTP/1.1 200 OK');
+				$error_msg = nl2br($message->error_message());
+				?>
                 <!DOCTYPE html>
                 <html>
                 <head></head>
                 <body>
                 <?php echo empty($error_msg)
-                    ? esc_html__('Unfortunately, we were unable to capture the error message for this message.',
-                        'event_espresso')
-                    : wp_kses(
-                        $error_msg,
-                        array(
-                            'a'      => array(
-                                'href'  => array(),
-                                'title' => array(),
-                            ),
-                            'span'   => array(),
-                            'div'    => array(),
-                            'p'      => array(),
-                            'strong' => array(),
-                            'em'     => array(),
-                            'br'     => array(),
-                        )
-                    ); ?>
+					? esc_html__('Unfortunately, we were unable to capture the error message for this message.',
+						'event_espresso')
+					: wp_kses(
+						$error_msg,
+						array(
+							'a'      => array(
+								'href'  => array(),
+								'title' => array(),
+							),
+							'span'   => array(),
+							'div'    => array(),
+							'p'      => array(),
+							'strong' => array(),
+							'em'     => array(),
+							'br'     => array(),
+						)
+					); ?>
                 </body>
                 </html>
                 <?php
-                exit;
-            }
-        }
-        return;
-    }
-
-
-    /**
-     *  This runs when the msg_url_trigger route has initiated.
-     *
-     * @since 4.5.0
-     * @param WP $WP
-     * @throws EE_Error
-     * @return    void
-     */
-    public function run($WP)
-    {
-        //ensure controller is loaded
-        self::_load_controller();
-        // attempt to process message
-        try {
-            /** @type EE_Message_To_Generate_From_Request $message_to_generate */
-            $message_to_generate = EE_Registry::instance()->load_lib('Message_To_Generate_From_Request');
-            self::$_MSG_PROCESSOR->generate_and_send_now($message_to_generate);
-        } catch (EE_Error $e) {
-            $error_msg = __('Please note that a system message failed to send due to a technical issue.',
-                'event_espresso');
-            // add specific message for developers if WP_DEBUG in on
-            $error_msg .= '||' . $e->getMessage();
-            EE_Error::add_error($error_msg, __FILE__, __FUNCTION__, __LINE__);
-        }
-    }
-
-
-    /**
-     * This is triggered by the 'msg_cron_trigger' route.
-     *
-     * @param WP $WP
-     */
-    public function execute_batch_request($WP)
-    {
-        $this->run_cron();
-        header('HTTP/1.1 200 OK');
-        exit();
-    }
-
-
-    /**
-     * This gets executed on wp_cron jobs or when a batch request is initiated on its own separate non regular wp
-     * request.
-     */
-    public function run_cron()
-    {
-        self::_load_controller();
-        //get required vars
-        $cron_type     = EE_Registry::instance()->REQ->get('type');
-        $transient_key = EE_Registry::instance()->REQ->get('key');
-
-        //now let's verify transient, if not valid exit immediately
-        if (! get_transient($transient_key)) {
-            /**
-             * trigger error so this gets in the error logs.  This is important because it happens on a non-user request.
-             */
-            trigger_error(esc_attr__('Invalid Request (Transient does not exist)', 'event_espresso'));
-        }
-
-        //if made it here, lets' delete the transient to keep the db clean
-        delete_transient($transient_key);
-
-        if (apply_filters('FHEE__EED_Messages__run_cron__use_wp_cron', true)) {
-
-            $method = 'batch_' . $cron_type . '_from_queue';
-            if (method_exists(self::$_MSG_PROCESSOR, $method)) {
-                self::$_MSG_PROCESSOR->$method();
-            } else {
-                //no matching task
-                /**
-                 * trigger error so this gets in the error logs.  This is important because it happens on a non user request.
-                 */
-                trigger_error(esc_attr(sprintf(__('There is no task corresponding to this route %s', 'event_espresso'),
-                    $cron_type)));
-            }
-        }
-
-        do_action('FHEE__EED_Messages__run_cron__end');
-    }
-
-
-    /**
-     * This is used to retrieve the template pack for the given name.
-     * Retrieved packs are cached on the static $_TMP_PACKS array.  If there is no class matching the given name then
-     * the default template pack is returned.
-     *
-     * @deprecated 4.9.0  @see EEH_MSG_Template::get_template_pack()
-     * @param string $template_pack_name This should correspond to the dbref of the template pack (which is also used
-     *                                   in generating the Pack class name).
-     * @return EE_Messages_Template_Pack
-     */
-    public static function get_template_pack($template_pack_name)
-    {
-        EE_Registry::instance()->load_helper('MSG_Template');
-        return EEH_MSG_Template::get_template_pack($template_pack_name);
-    }
-
-
-    /**
-     * Retrieves an array of all template packs.
-     * Array is in the format array( 'dbref' => EE_Messages_Template_Pack )
-     *
-     * @deprecated 4.9.0  @see EEH_MSG_Template_Pack::get_template_pack_collection
-     * @return EE_Messages_Template_Pack[]
-     */
-    public static function get_template_packs()
-    {
-        EE_Registry::instance()->load_helper('MSG_Template');
-
-        //for backward compat, let's make sure this returns in the same format as originally.
-        $template_pack_collection = EEH_MSG_Template::get_template_pack_collection();
-        $template_pack_collection->rewind();
-        $template_packs = array();
-        while ($template_pack_collection->valid()) {
-            $template_packs[$template_pack_collection->current()->dbref] = $template_pack_collection->current();
-            $template_pack_collection->next();
-        }
-        return $template_packs;
-    }
-
-
-    /**
-     * This simply makes sure the autoloaders are registered for the EE_messages system.
-     *
-     * @since 4.5.0
-     * @return void
-     */
-    public static function set_autoloaders()
-    {
-        if (empty(self::$_MSG_PATHS)) {
-            self::_set_messages_paths();
-            foreach (self::$_MSG_PATHS as $path) {
-                EEH_Autoloader::register_autoloaders_for_each_file_in_folder($path);
-            }
-            // add aliases
-            EEH_Autoloader::add_alias('EE_messages', 'EE_messages');
-            EEH_Autoloader::add_alias('EE_messenger', 'EE_messenger');
-        }
-    }
-
-
-    /**
-     * Take care of adding all the paths for the messages components to the $_MSG_PATHS property
-     * for use by the Messages Autoloaders
-     *
-     * @since 4.5.0
-     * @return void.
-     */
-    protected static function _set_messages_paths()
-    {
-        $dir_ref = array(
-            'messages/message_type',
-            'messages/messenger',
-            'messages/defaults',
-            'messages/defaults/email',
-            'messages/data_class',
-            'messages/validators',
-            'messages/validators/email',
-            'messages/validators/html',
-            'shortcodes',
-        );
-        $paths   = array();
-        foreach ($dir_ref as $index => $dir) {
-            $paths[$index] = EE_LIBRARIES . $dir;
-        }
-        self::$_MSG_PATHS = apply_filters('FHEE__EED_Messages___set_messages_paths___MSG_PATHS', $paths);
-    }
-
-
-    /**
-     * Takes care of loading dependencies
-     *
-     * @since 4.5.0
-     * @return void
-     */
-    protected static function _load_controller()
-    {
-        if (! self::$_MSG_PROCESSOR instanceof EE_Messages_Processor) {
-            EE_Registry::instance()->load_core('Request_Handler');
-            self::set_autoloaders();
-            self::$_EEMSG                    = EE_Registry::instance()->load_lib('messages');
-            self::$_MSG_PROCESSOR            = EE_Registry::instance()->load_lib('Messages_Processor');
-            self::$_message_resource_manager = EE_Registry::instance()->load_lib('Message_Resource_Manager');
-        }
-    }
-
-
-    /**
-     * @param EE_Transaction $transaction
-     */
-    public static function payment_reminder(EE_Transaction $transaction)
-    {
-        self::_load_controller();
-        $data = array($transaction, null);
-        self::$_MSG_PROCESSOR->generate_for_all_active_messengers('payment_reminder', $data);
-    }
-
-
-    /**
-     * Any messages triggers for after successful gateway payments should go in here.
-     *
-     * @param  EE_Transaction object
-     * @param  EE_Payment     object
-     * @return void
-     */
-    public static function payment(EE_Transaction $transaction, EE_Payment $payment)
-    {
-        self::_load_controller();
-        $data = array($transaction, $payment);
-        EE_Registry::instance()->load_helper('MSG_Template');
-        $message_type = EEH_MSG_Template::convert_payment_status_to_message_type($payment->STS_ID());
-        //if payment amount is less than 0 then switch to payment_refund message type.
-        $message_type = $payment->amount() < 0 ? 'payment_refund' : $message_type;
-        self::$_MSG_PROCESSOR->generate_for_all_active_messengers($message_type, $data);
-    }
-
-
-    /**
-     * @param EE_Transaction $transaction
-     */
-    public static function cancelled_registration(EE_Transaction $transaction)
-    {
-        self::_load_controller();
-        $data = array($transaction, null);
-        self::$_MSG_PROCESSOR->generate_for_all_active_messengers('cancelled_registration', $data);
-    }
-
-
-    /**
-     * Trigger for Registration messages
-     * Note that what registration message type is sent depends on what the reg status is for the registrations on the
-     * incoming transaction.
-     *
-     * @param EE_Registration $registration
-     * @param array           $extra_details
-     * @return void
-     */
-    public static function maybe_registration(EE_Registration $registration, $extra_details = array())
-    {
-
-        if (! self::_verify_registration_notification_send($registration, $extra_details)) {
-            //no messages please
-            return;
-        }
-
-
-        //get all registrations so we make sure we send messages for the right status.
-        $all_registrations = $registration->transaction()->registrations();
-
-        //cached array of statuses so we only trigger messages once per status.
-        $statuses_sent = array();
-        self::_load_controller();
-        $mtgs = array();
-
-        //loop through registrations and trigger messages once per status.
-        foreach ($all_registrations as $reg) {
-
-            //already triggered?
-            if (in_array($reg->status_ID(), $statuses_sent)) {
-                continue;
-            }
-
-            $message_type    = EEH_MSG_Template::convert_reg_status_to_message_type($reg->status_ID());
-            $mtgs            = array_merge(
-                    $mtgs,
-                    self::$_MSG_PROCESSOR->setup_mtgs_for_all_active_messengers(
-                            $message_type,
-                            array($registration->transaction(), null, $reg->status_ID())
-                    )
-            );
-            $statuses_sent[] = $reg->status_ID();
-        }
-
-        if (count($statuses_sent) > 1) {
-            $mtgs = array_merge(
-                $mtgs,
-                self::$_MSG_PROCESSOR->setup_mtgs_for_all_active_messengers(
-                    'registration_summary',
-                    array($registration->transaction(), null)
-                )
-            );
-        }
-
-        //batch queue and initiate request
-        self::$_MSG_PROCESSOR->batch_queue_for_generation_and_persist($mtgs);
-        self::$_MSG_PROCESSOR->get_queue()->initiate_request_by_priority();
-    }
-
-
-    /**
-     * This is a helper method used to very whether a registration notification should be sent or
-     * not.  Prevents duplicate notifications going out for registration context notifications.
-     *
-     * @param EE_Registration $registration  [description]
-     * @param array           $extra_details [description]
-     * @return bool          true = send away, false = nope halt the presses.
-     */
-    protected static function _verify_registration_notification_send(
-        EE_Registration $registration,
-        $extra_details = array()
-    ) {
-        //self::log(
-        //	__CLASS__, __FUNCTION__, __LINE__,
-        //	$registration->transaction(),
-        //	array( '$extra_details' => $extra_details )
-        //);
-        // currently only using this to send messages for the primary registrant
-        if (! $registration->is_primary_registrant()) {
-            return false;
-        }
-        // first we check if we're in admin and not doing front ajax
-        if (is_admin() && ! EE_FRONT_AJAX) {
-            //make sure appropriate admin params are set for sending messages
-            if (empty($_REQUEST['txn_reg_status_change']['send_notifications']) || ! absint($_REQUEST['txn_reg_status_change']['send_notifications'])) {
-                //no messages sent please.
-                return false;
-            }
-        } else {
-            // frontend request (either regular or via AJAX)
-            // TXN is NOT finalized ?
-            if (! isset($extra_details['finalized']) || $extra_details['finalized'] === false) {
-                return false;
-            }
-            // return visit but nothing changed ???
-            if (
-                isset($extra_details['revisit'], $extra_details['status_updates']) &&
-                $extra_details['revisit'] && ! $extra_details['status_updates']
-            ) {
-                return false;
-            }
-            // NOT sending messages && reg status is something other than "Not-Approved"
-            if (
-                ! apply_filters('FHEE__EED_Messages___maybe_registration__deliver_notifications', false) &&
-                $registration->status_ID() !== EEM_Registration::status_id_not_approved
-            ) {
-                return false;
-            }
-        }
-        // release the kraken
-        return true;
-    }
-
-
-    /**
-     * Simply returns an array indexed by Registration Status ID and the related message_type name associated with that
-     * status id.
-     *
-     * @deprecated 4.9.0  Use EEH_MSG_Template::reg_status_to_message_type_array()
-     *                    or EEH_MSG_Template::convert_reg_status_to_message_type
-     * @param string $reg_status
-     * @return array
-     */
-    protected static function _get_reg_status_array($reg_status = '')
-    {
-        EE_Registry::instance()->load_helper('MSG_Template');
-        return EEH_MSG_Template::convert_reg_status_to_message_type($reg_status)
-            ? EEH_MSG_Template::convert_reg_status_to_message_type($reg_status)
-            : EEH_MSG_Template::reg_status_to_message_type_array();
-    }
-
-
-    /**
-     * Simply returns the payment message type for the given payment status.
-     *
-     * @deprecated 4.9.0 Use EEH_MSG_Template::payment_status_to_message_type_array
-     *                   or EEH_MSG_Template::convert_payment_status_to_message_type
-     * @param string $payment_status The payment status being matched.
-     * @return string|bool The payment message type slug matching the status or false if no match.
-     */
-    protected static function _get_payment_message_type($payment_status)
-    {
-        EE_Registry::instance()->load_helper('MSG_Template');
-        return EEH_MSG_Template::convert_payment_status_to_message_type($payment_status)
-            ? EEH_MSG_Template::convert_payment_status_to_message_type($payment_status)
-            : false;
-    }
-
-
-    /**
-     * Message triggers for a resending already sent message(s) (via EE_Message list table)
-     *
-     * @access public
-     * @param array $req_data This is the $_POST & $_GET data sent from EE_Admin Pages
-     * @return bool          success/fail
-     */
-    public static function process_resend($req_data)
-    {
-        self::_load_controller();
-
-        //if $msgID in this request then skip to the new resend_message
-        if (EE_Registry::instance()->REQ->get('MSG_ID')) {
-            return self::resend_message();
-        }
-
-        //make sure any incoming request data is set on the REQ so that it gets picked up later.
-        $req_data = (array)$req_data;
-        foreach ($req_data as $request_key => $request_value) {
-            EE_Registry::instance()->REQ->set($request_key, $request_value);
-        }
-
-        if (! $messages_to_send = self::$_MSG_PROCESSOR->setup_messages_to_generate_from_registration_ids_in_request()) {
-            return false;
-        }
-
-        try {
-            self::$_MSG_PROCESSOR->batch_queue_for_generation_and_persist($messages_to_send);
-            self::$_MSG_PROCESSOR->get_queue()->initiate_request_by_priority();
-        } catch (EE_Error $e) {
-            EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
-            return false;
-        }
-        EE_Error::add_success(
-            __('Messages have been successfully queued for generation and sending.', 'event_espresso')
-        );
-        return true; //everything got queued.
-    }
-
-
-    /**
-     * Message triggers for a resending already sent message(s) (via EE_Message list table)
-     *
-     * @return bool
-     */
-    public static function resend_message()
-    {
-        self::_load_controller();
-
-        $msgID = EE_Registry::instance()->REQ->get('MSG_ID');
-        if (! $msgID) {
-            EE_Error::add_error(__('Something went wrong because there is no "MSG_ID" value in the request',
-                'event_espresso'), __FILE__, __FUNCTION__, __LINE__);
-            return false;
-        }
-
-        self::$_MSG_PROCESSOR->setup_messages_from_ids_and_send((array)$msgID);
-
-        //setup success message.
-        $count_ready_for_resend = self::$_MSG_PROCESSOR->get_queue()->count_STS_in_queue(EEM_Message::status_resend);
-        EE_Error::add_success(sprintf(
-            _n(
-                'There was %d message queued for resending.',
-                'There were %d messages queued for resending.',
-                $count_ready_for_resend,
-                'event_espresso'
-            ),
-            $count_ready_for_resend
-        ));
-        return true;
-    }
-
-
-    /**
-     * Message triggers for manual payment applied by admin
-     *
-     * @param  EE_Payment $payment EE_payment object
-     * @return bool              success/fail
-     */
-    public static function process_admin_payment(EE_Payment $payment)
-    {
-        EE_Registry::instance()->load_helper('MSG_Template');
-        //we need to get the transaction object
-        $transaction = $payment->transaction();
-        if ($transaction instanceof EE_Transaction) {
-            $data         = array($transaction, $payment);
-            $message_type = EEH_MSG_Template::convert_payment_status_to_message_type($payment->STS_ID());
-
-            //if payment amount is less than 0 then switch to payment_refund message type.
-            $message_type = $payment->amount() < 0 ? 'payment_refund' : $message_type;
-
-            //if payment_refund is selected, but the status is NOT accepted.  Then change message type to false so NO message notification goes out.
-            $message_type = $message_type == 'payment_refund' && $payment->STS_ID() != EEM_Payment::status_id_approved ? false : $message_type;
-
-            self::_load_controller();
-
-            self::$_MSG_PROCESSOR->generate_for_all_active_messengers($message_type, $data);
-
-            //get count of queued for generation
-            $count_to_generate = self::$_MSG_PROCESSOR->get_queue()->count_STS_in_queue(array(
-                EEM_Message::status_incomplete,
-                EEM_Message::status_idle,
-            ));
-
-            if ($count_to_generate > 0 && self::$_MSG_PROCESSOR->get_queue()->get_message_repository()->count() !== 0) {
-                add_filter('FHEE__EE_Admin_Page___process_admin_payment_notification__success', '__return_true');
-                return true;
-            } else {
-                $count_failed = self::$_MSG_PROCESSOR->get_queue()->count_STS_in_queue(EEM_Message::instance()->stati_indicating_failed_sending());
-                /**
-                 * Verify that there are actually errors.  If not then we return a success message because the queue might have been emptied due to successful
-                 * IMMEDIATE generation.
-                 */
-                if ($count_failed > 0) {
-                    EE_Error::add_error(sprintf(
-                        _n(
-                            'The payment notification generation failed.',
-                            '%d payment notifications failed being sent.',
-                            $count_failed,
-                            'event_espresso'
-                        ),
-                        $count_failed
-                    ), __FILE__, __FUNCTION__, __LINE__);
-
-                    return false;
-                } else {
-                    add_filter('FHEE__EE_Admin_Page___process_admin_payment_notification__success', '__return_true');
-                    return true;
-                }
-            }
-        } else {
-            EE_Error::add_error(
-                'Unable to generate the payment notification because the given value for the transaction is invalid.',
-                'event_espresso'
-            );
-            return false;
-        }
-    }
-
-
-    /**
-     * Callback for AHEE__Extend_Registrations_Admin_Page___newsletter_selected_send_with_registrations trigger
-     *
-     * @since   4.3.0
-     * @param  EE_Registration[] $registrations an array of EE_Registration objects
-     * @param  int               $grp_id        a specific message template group id.
-     * @return void
-     */
-    public static function send_newsletter_message($registrations, $grp_id)
-    {
-        //make sure mtp is id and set it in the EE_Request Handler later messages setup.
-        EE_Registry::instance()->REQ->set('GRP_ID', (int)$grp_id);
-        self::_load_controller();
-        self::$_MSG_PROCESSOR->generate_for_all_active_messengers('newsletter', $registrations);
-    }
-
-
-    /**
-     * Callback for FHEE__EE_Registration__invoice_url__invoice_url or FHEE__EE_Registration__receipt_url__receipt_url
-     *
-     * @since   4.3.0
-     * @param    string          $registration_message_trigger_url
-     * @param    EE_Registration $registration
-     * @param string             $messenger
-     * @param string             $message_type
-     * @return    string
-     */
-    public static function registration_message_trigger_url(
-        $registration_message_trigger_url,
-        EE_Registration $registration,
-        $messenger = 'html',
-        $message_type = 'invoice'
-    ) {
-        // whitelist $messenger
-        switch ($messenger) {
-            case 'pdf' :
-                $sending_messenger    = 'pdf';
-                $generating_messenger = 'html';
-                break;
-            case 'html' :
-            default :
-                $sending_messenger    = 'html';
-                $generating_messenger = 'html';
-                break;
-        }
-        // whitelist $message_type
-        switch ($message_type) {
-            case 'receipt' :
-                $message_type = 'receipt';
-                break;
-            case 'invoice' :
-            default :
-                $message_type = 'invoice';
-                break;
-        }
-        // verify that both the messenger AND the message type are active
-        if (EEH_MSG_Template::is_messenger_active($sending_messenger) && EEH_MSG_Template::is_mt_active($message_type)) {
-            //need to get the correct message template group for this (i.e. is there a custom invoice for the event this registration is registered for?)
-            $template_query_params = array(
-                'MTP_is_active'    => true,
-                'MTP_messenger'    => $generating_messenger,
-                'MTP_message_type' => $message_type,
-                'Event.EVT_ID'     => $registration->event_ID(),
-            );
-            //get the message template group.
-            $msg_template_group = EEM_Message_Template_Group::instance()->get_one(array($template_query_params));
-            //if we don't have an EE_Message_Template_Group then return
-            if (! $msg_template_group instanceof EE_Message_Template_Group) {
-                // remove EVT_ID from query params so that global templates get picked up
-                unset($template_query_params['Event.EVT_ID']);
-                //get global template as the fallback
-                $msg_template_group = EEM_Message_Template_Group::instance()->get_one(array($template_query_params));
-            }
-            //if we don't have an EE_Message_Template_Group then return
-            if (! $msg_template_group instanceof EE_Message_Template_Group) {
-                return '';
-            }
-            // generate the URL
-            $registration_message_trigger_url = EEH_MSG_Template::generate_url_trigger(
-                $sending_messenger,
-                $generating_messenger,
-                'purchaser',
-                $message_type,
-                $registration,
-                $msg_template_group->ID(),
-                $registration->transaction_ID()
-            );
-
-        }
-        return $registration_message_trigger_url;
-    }
-
-
-    /**
-     * Use to generate and return a message preview!
-     *
-     * @param  string $type      This should correspond with a valid message type
-     * @param  string $context   This should correspond with a valid context for the message type
-     * @param  string $messenger This should correspond with a valid messenger.
-     * @param bool    $send      true we will do a test send using the messenger delivery, false we just do a regular
-     *                           preview
-     * @return bool|string The body of the message or if send is requested, sends.
-     * @throws EE_Error
-     */
-    public static function preview_message($type, $context, $messenger, $send = false)
-    {
-        self::_load_controller();
-        $mtg                     = new EE_Message_To_Generate(
-            $messenger,
-            $type,
-            array(),
-            $context,
-            true
-        );
-        $generated_preview_queue = self::$_MSG_PROCESSOR->generate_for_preview($mtg, $send);
-        if ($generated_preview_queue instanceof EE_Messages_Queue) {
-            //loop through all content for the preview and remove any persisted records.
-            $content = '';
-            foreach ($generated_preview_queue->get_message_repository() as $message) {
-                $content = $message->content();
-                if ($message->ID() > 0 && $message->STS_ID() !== EEM_Message::status_failed) {
-                    $message->delete();
-                }
-            }
-            return $content;
-        } else {
-            return $generated_preview_queue;
-        }
-    }
-
-
-    /**
-     * This is a method that allows for sending a message using a messenger matching the string given and the provided
-     * EE_Message_Queue object.  The EE_Message_Queue object is used to create a single aggregate EE_Message via the
-     * content found in the EE_Message objects in the queue.
-     *
-     * @since 4.9.0
-     * @param string            $messenger            a string matching a valid active messenger in the system
-     * @param string            $message_type         Although it seems contrary to the name of the method, a message
-     *                                                type name is still required to send along the message type to the
-     *                                                messenger because this is used for determining what specific
-     *                                                variations might be loaded for the generated message.
-     * @param EE_Messages_Queue $queue
-     * @param string            $custom_subject       Can be used to set what the custom subject string will be on the
-     *                                                aggregate EE_Message object.
-     * @return bool          success or fail.
-     */
-    public static function send_message_with_messenger_only(
-        $messenger,
-        $message_type,
-        EE_Messages_Queue $queue,
-        $custom_subject = ''
-    ) {
-        self::_load_controller();
-        /** @type EE_Message_To_Generate_From_Queue $message_to_generate */
-        $message_to_generate = EE_Registry::instance()->load_lib(
-            'Message_To_Generate_From_Queue',
-            array(
-                $messenger,
-                $message_type,
-                $queue,
-                $custom_subject,
-            )
-        );
-        return self::$_MSG_PROCESSOR->queue_for_sending($message_to_generate);
-    }
-
-
-    /**
-     * Generates Messages immediately for EE_Message IDs (but only for the correct status for generation)
-     *
-     * @since 4.9.0
-     * @param array $message_ids An array of message ids
-     * @return bool | EE_Messages_Queue     false if nothing was generated, EE_Messages_Queue containing generated
-     *              messages.
-     */
-    public static function generate_now($message_ids)
-    {
-        self::_load_controller();
-        $messages        = EEM_Message::instance()->get_all(
-            array(
-                0 => array(
-                    'MSG_ID' => array('IN', $message_ids),
-                    'STS_ID' => EEM_Message::status_incomplete,
-                ),
-            )
-        );
-        $generated_queue = false;
-        if ($messages) {
-            $generated_queue = self::$_MSG_PROCESSOR->batch_generate_from_queue($messages);
-        }
-
-        if (! $generated_queue instanceof EE_Messages_Queue) {
-            EE_Error::add_error(
-                __('The messages were not generated. This could mean there is already a batch being generated on a separate request, or because the selected messages are not ready for generation. Please wait a minute or two and try again.',
-                    'event_espresso'),
-                __FILE__, __FUNCTION__, __LINE__
-            );
-        }
-        return $generated_queue;
-    }
-
-
-    /**
-     * Sends messages immediately for the incoming message_ids that have the status of EEM_Message::status_resend or,
-     * EEM_Message::status_idle
-     *
-     * @since 4.9.0
-     * @param $message_ids
-     * @return bool | EE_Messages_Queue  false if no messages sent.
-     */
-    public static function send_now($message_ids)
-    {
-        self::_load_controller();
-        $messages   = EEM_Message::instance()->get_all(
-            array(
-                0 => array(
-                    'MSG_ID' => array('IN', $message_ids),
-                    'STS_ID' => array(
-                        'IN',
-                        array(EEM_Message::status_idle, EEM_Message::status_resend, EEM_Message::status_retry),
-                    ),
-                ),
-            )
-        );
-        $sent_queue = false;
-        if ($messages) {
-            $sent_queue = self::$_MSG_PROCESSOR->batch_send_from_queue($messages);
-        }
-
-        if (! $sent_queue instanceof EE_Messages_Queue) {
-            EE_Error::add_error(
-                __('The messages were not sent. This could mean there is already a batch being sent on a separate request, or because the selected messages are not sendable. Please wait a minute or two and try again.',
-                    'event_espresso'),
-                __FILE__, __FUNCTION__, __LINE__
-            );
-        } else {
-            //can count how many sent by using the messages in the queue
-            $sent_count = $sent_queue->count_STS_in_queue(EEM_Message::instance()->stati_indicating_sent());
-            if ($sent_count > 0) {
-                EE_Error::add_success(
-                    sprintf(
-                        _n(
-                            'There was %d message successfully sent.',
-                            'There were %d messages successfully sent.',
-                            $sent_count,
-                            'event_espresso'
-                        ),
-                        $sent_count
-                    )
-                );
-            } else {
-                EE_Error::overwrite_errors();
-                EE_Error::add_error(
-                    __('No message was sent because of problems with sending. Either all the messages you selected were not a sendable message, they were ALREADY sent on a different scheduled task, or there was an error.
+				exit;
+			}
+		}
+		return;
+	}
+
+
+	/**
+	 *  This runs when the msg_url_trigger route has initiated.
+	 *
+	 * @since 4.5.0
+	 * @param WP $WP
+	 * @throws EE_Error
+	 * @return    void
+	 */
+	public function run($WP)
+	{
+		//ensure controller is loaded
+		self::_load_controller();
+		// attempt to process message
+		try {
+			/** @type EE_Message_To_Generate_From_Request $message_to_generate */
+			$message_to_generate = EE_Registry::instance()->load_lib('Message_To_Generate_From_Request');
+			self::$_MSG_PROCESSOR->generate_and_send_now($message_to_generate);
+		} catch (EE_Error $e) {
+			$error_msg = __('Please note that a system message failed to send due to a technical issue.',
+				'event_espresso');
+			// add specific message for developers if WP_DEBUG in on
+			$error_msg .= '||' . $e->getMessage();
+			EE_Error::add_error($error_msg, __FILE__, __FUNCTION__, __LINE__);
+		}
+	}
+
+
+	/**
+	 * This is triggered by the 'msg_cron_trigger' route.
+	 *
+	 * @param WP $WP
+	 */
+	public function execute_batch_request($WP)
+	{
+		$this->run_cron();
+		header('HTTP/1.1 200 OK');
+		exit();
+	}
+
+
+	/**
+	 * This gets executed on wp_cron jobs or when a batch request is initiated on its own separate non regular wp
+	 * request.
+	 */
+	public function run_cron()
+	{
+		self::_load_controller();
+		//get required vars
+		$cron_type     = EE_Registry::instance()->REQ->get('type');
+		$transient_key = EE_Registry::instance()->REQ->get('key');
+
+		//now let's verify transient, if not valid exit immediately
+		if (! get_transient($transient_key)) {
+			/**
+			 * trigger error so this gets in the error logs.  This is important because it happens on a non-user request.
+			 */
+			trigger_error(esc_attr__('Invalid Request (Transient does not exist)', 'event_espresso'));
+		}
+
+		//if made it here, lets' delete the transient to keep the db clean
+		delete_transient($transient_key);
+
+		if (apply_filters('FHEE__EED_Messages__run_cron__use_wp_cron', true)) {
+
+			$method = 'batch_' . $cron_type . '_from_queue';
+			if (method_exists(self::$_MSG_PROCESSOR, $method)) {
+				self::$_MSG_PROCESSOR->$method();
+			} else {
+				//no matching task
+				/**
+				 * trigger error so this gets in the error logs.  This is important because it happens on a non user request.
+				 */
+				trigger_error(esc_attr(sprintf(__('There is no task corresponding to this route %s', 'event_espresso'),
+					$cron_type)));
+			}
+		}
+
+		do_action('FHEE__EED_Messages__run_cron__end');
+	}
+
+
+	/**
+	 * This is used to retrieve the template pack for the given name.
+	 * Retrieved packs are cached on the static $_TMP_PACKS array.  If there is no class matching the given name then
+	 * the default template pack is returned.
+	 *
+	 * @deprecated 4.9.0  @see EEH_MSG_Template::get_template_pack()
+	 * @param string $template_pack_name This should correspond to the dbref of the template pack (which is also used
+	 *                                   in generating the Pack class name).
+	 * @return EE_Messages_Template_Pack
+	 */
+	public static function get_template_pack($template_pack_name)
+	{
+		EE_Registry::instance()->load_helper('MSG_Template');
+		return EEH_MSG_Template::get_template_pack($template_pack_name);
+	}
+
+
+	/**
+	 * Retrieves an array of all template packs.
+	 * Array is in the format array( 'dbref' => EE_Messages_Template_Pack )
+	 *
+	 * @deprecated 4.9.0  @see EEH_MSG_Template_Pack::get_template_pack_collection
+	 * @return EE_Messages_Template_Pack[]
+	 */
+	public static function get_template_packs()
+	{
+		EE_Registry::instance()->load_helper('MSG_Template');
+
+		//for backward compat, let's make sure this returns in the same format as originally.
+		$template_pack_collection = EEH_MSG_Template::get_template_pack_collection();
+		$template_pack_collection->rewind();
+		$template_packs = array();
+		while ($template_pack_collection->valid()) {
+			$template_packs[$template_pack_collection->current()->dbref] = $template_pack_collection->current();
+			$template_pack_collection->next();
+		}
+		return $template_packs;
+	}
+
+
+	/**
+	 * This simply makes sure the autoloaders are registered for the EE_messages system.
+	 *
+	 * @since 4.5.0
+	 * @return void
+	 */
+	public static function set_autoloaders()
+	{
+		if (empty(self::$_MSG_PATHS)) {
+			self::_set_messages_paths();
+			foreach (self::$_MSG_PATHS as $path) {
+				EEH_Autoloader::register_autoloaders_for_each_file_in_folder($path);
+			}
+			// add aliases
+			EEH_Autoloader::add_alias('EE_messages', 'EE_messages');
+			EEH_Autoloader::add_alias('EE_messenger', 'EE_messenger');
+		}
+	}
+
+
+	/**
+	 * Take care of adding all the paths for the messages components to the $_MSG_PATHS property
+	 * for use by the Messages Autoloaders
+	 *
+	 * @since 4.5.0
+	 * @return void.
+	 */
+	protected static function _set_messages_paths()
+	{
+		$dir_ref = array(
+			'messages/message_type',
+			'messages/messenger',
+			'messages/defaults',
+			'messages/defaults/email',
+			'messages/data_class',
+			'messages/validators',
+			'messages/validators/email',
+			'messages/validators/html',
+			'shortcodes',
+		);
+		$paths   = array();
+		foreach ($dir_ref as $index => $dir) {
+			$paths[$index] = EE_LIBRARIES . $dir;
+		}
+		self::$_MSG_PATHS = apply_filters('FHEE__EED_Messages___set_messages_paths___MSG_PATHS', $paths);
+	}
+
+
+	/**
+	 * Takes care of loading dependencies
+	 *
+	 * @since 4.5.0
+	 * @return void
+	 */
+	protected static function _load_controller()
+	{
+		if (! self::$_MSG_PROCESSOR instanceof EE_Messages_Processor) {
+			EE_Registry::instance()->load_core('Request_Handler');
+			self::set_autoloaders();
+			self::$_EEMSG                    = EE_Registry::instance()->load_lib('messages');
+			self::$_MSG_PROCESSOR            = EE_Registry::instance()->load_lib('Messages_Processor');
+			self::$_message_resource_manager = EE_Registry::instance()->load_lib('Message_Resource_Manager');
+		}
+	}
+
+
+	/**
+	 * @param EE_Transaction $transaction
+	 */
+	public static function payment_reminder(EE_Transaction $transaction)
+	{
+		self::_load_controller();
+		$data = array($transaction, null);
+		self::$_MSG_PROCESSOR->generate_for_all_active_messengers('payment_reminder', $data);
+	}
+
+
+	/**
+	 * Any messages triggers for after successful gateway payments should go in here.
+	 *
+	 * @param  EE_Transaction object
+	 * @param  EE_Payment     object
+	 * @return void
+	 */
+	public static function payment(EE_Transaction $transaction, EE_Payment $payment)
+	{
+		self::_load_controller();
+		$data = array($transaction, $payment);
+		EE_Registry::instance()->load_helper('MSG_Template');
+		$message_type = EEH_MSG_Template::convert_payment_status_to_message_type($payment->STS_ID());
+		//if payment amount is less than 0 then switch to payment_refund message type.
+		$message_type = $payment->amount() < 0 ? 'payment_refund' : $message_type;
+		self::$_MSG_PROCESSOR->generate_for_all_active_messengers($message_type, $data);
+	}
+
+
+	/**
+	 * @param EE_Transaction $transaction
+	 */
+	public static function cancelled_registration(EE_Transaction $transaction)
+	{
+		self::_load_controller();
+		$data = array($transaction, null);
+		self::$_MSG_PROCESSOR->generate_for_all_active_messengers('cancelled_registration', $data);
+	}
+
+
+	/**
+	 * Trigger for Registration messages
+	 * Note that what registration message type is sent depends on what the reg status is for the registrations on the
+	 * incoming transaction.
+	 *
+	 * @param EE_Registration $registration
+	 * @param array           $extra_details
+	 * @return void
+	 */
+	public static function maybe_registration(EE_Registration $registration, $extra_details = array())
+	{
+
+		if (! self::_verify_registration_notification_send($registration, $extra_details)) {
+			//no messages please
+			return;
+		}
+
+
+		//get all registrations so we make sure we send messages for the right status.
+		$all_registrations = $registration->transaction()->registrations();
+
+		//cached array of statuses so we only trigger messages once per status.
+		$statuses_sent = array();
+		self::_load_controller();
+		$mtgs = array();
+
+		//loop through registrations and trigger messages once per status.
+		foreach ($all_registrations as $reg) {
+
+			//already triggered?
+			if (in_array($reg->status_ID(), $statuses_sent)) {
+				continue;
+			}
+
+			$message_type    = EEH_MSG_Template::convert_reg_status_to_message_type($reg->status_ID());
+			$mtgs            = array_merge(
+					$mtgs,
+					self::$_MSG_PROCESSOR->setup_mtgs_for_all_active_messengers(
+							$message_type,
+							array($registration->transaction(), null, $reg->status_ID())
+					)
+			);
+			$statuses_sent[] = $reg->status_ID();
+		}
+
+		if (count($statuses_sent) > 1) {
+			$mtgs = array_merge(
+				$mtgs,
+				self::$_MSG_PROCESSOR->setup_mtgs_for_all_active_messengers(
+					'registration_summary',
+					array($registration->transaction(), null)
+				)
+			);
+		}
+
+		//batch queue and initiate request
+		self::$_MSG_PROCESSOR->batch_queue_for_generation_and_persist($mtgs);
+		self::$_MSG_PROCESSOR->get_queue()->initiate_request_by_priority();
+	}
+
+
+	/**
+	 * This is a helper method used to very whether a registration notification should be sent or
+	 * not.  Prevents duplicate notifications going out for registration context notifications.
+	 *
+	 * @param EE_Registration $registration  [description]
+	 * @param array           $extra_details [description]
+	 * @return bool          true = send away, false = nope halt the presses.
+	 */
+	protected static function _verify_registration_notification_send(
+		EE_Registration $registration,
+		$extra_details = array()
+	) {
+		//self::log(
+		//	__CLASS__, __FUNCTION__, __LINE__,
+		//	$registration->transaction(),
+		//	array( '$extra_details' => $extra_details )
+		//);
+		// currently only using this to send messages for the primary registrant
+		if (! $registration->is_primary_registrant()) {
+			return false;
+		}
+		// first we check if we're in admin and not doing front ajax
+		if (is_admin() && ! EE_FRONT_AJAX) {
+			//make sure appropriate admin params are set for sending messages
+			if (empty($_REQUEST['txn_reg_status_change']['send_notifications']) || ! absint($_REQUEST['txn_reg_status_change']['send_notifications'])) {
+				//no messages sent please.
+				return false;
+			}
+		} else {
+			// frontend request (either regular or via AJAX)
+			// TXN is NOT finalized ?
+			if (! isset($extra_details['finalized']) || $extra_details['finalized'] === false) {
+				return false;
+			}
+			// return visit but nothing changed ???
+			if (
+				isset($extra_details['revisit'], $extra_details['status_updates']) &&
+				$extra_details['revisit'] && ! $extra_details['status_updates']
+			) {
+				return false;
+			}
+			// NOT sending messages && reg status is something other than "Not-Approved"
+			if (
+				! apply_filters('FHEE__EED_Messages___maybe_registration__deliver_notifications', false) &&
+				$registration->status_ID() !== EEM_Registration::status_id_not_approved
+			) {
+				return false;
+			}
+		}
+		// release the kraken
+		return true;
+	}
+
+
+	/**
+	 * Simply returns an array indexed by Registration Status ID and the related message_type name associated with that
+	 * status id.
+	 *
+	 * @deprecated 4.9.0  Use EEH_MSG_Template::reg_status_to_message_type_array()
+	 *                    or EEH_MSG_Template::convert_reg_status_to_message_type
+	 * @param string $reg_status
+	 * @return array
+	 */
+	protected static function _get_reg_status_array($reg_status = '')
+	{
+		EE_Registry::instance()->load_helper('MSG_Template');
+		return EEH_MSG_Template::convert_reg_status_to_message_type($reg_status)
+			? EEH_MSG_Template::convert_reg_status_to_message_type($reg_status)
+			: EEH_MSG_Template::reg_status_to_message_type_array();
+	}
+
+
+	/**
+	 * Simply returns the payment message type for the given payment status.
+	 *
+	 * @deprecated 4.9.0 Use EEH_MSG_Template::payment_status_to_message_type_array
+	 *                   or EEH_MSG_Template::convert_payment_status_to_message_type
+	 * @param string $payment_status The payment status being matched.
+	 * @return string|bool The payment message type slug matching the status or false if no match.
+	 */
+	protected static function _get_payment_message_type($payment_status)
+	{
+		EE_Registry::instance()->load_helper('MSG_Template');
+		return EEH_MSG_Template::convert_payment_status_to_message_type($payment_status)
+			? EEH_MSG_Template::convert_payment_status_to_message_type($payment_status)
+			: false;
+	}
+
+
+	/**
+	 * Message triggers for a resending already sent message(s) (via EE_Message list table)
+	 *
+	 * @access public
+	 * @param array $req_data This is the $_POST & $_GET data sent from EE_Admin Pages
+	 * @return bool          success/fail
+	 */
+	public static function process_resend($req_data)
+	{
+		self::_load_controller();
+
+		//if $msgID in this request then skip to the new resend_message
+		if (EE_Registry::instance()->REQ->get('MSG_ID')) {
+			return self::resend_message();
+		}
+
+		//make sure any incoming request data is set on the REQ so that it gets picked up later.
+		$req_data = (array)$req_data;
+		foreach ($req_data as $request_key => $request_value) {
+			EE_Registry::instance()->REQ->set($request_key, $request_value);
+		}
+
+		if (! $messages_to_send = self::$_MSG_PROCESSOR->setup_messages_to_generate_from_registration_ids_in_request()) {
+			return false;
+		}
+
+		try {
+			self::$_MSG_PROCESSOR->batch_queue_for_generation_and_persist($messages_to_send);
+			self::$_MSG_PROCESSOR->get_queue()->initiate_request_by_priority();
+		} catch (EE_Error $e) {
+			EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
+			return false;
+		}
+		EE_Error::add_success(
+			__('Messages have been successfully queued for generation and sending.', 'event_espresso')
+		);
+		return true; //everything got queued.
+	}
+
+
+	/**
+	 * Message triggers for a resending already sent message(s) (via EE_Message list table)
+	 *
+	 * @return bool
+	 */
+	public static function resend_message()
+	{
+		self::_load_controller();
+
+		$msgID = EE_Registry::instance()->REQ->get('MSG_ID');
+		if (! $msgID) {
+			EE_Error::add_error(__('Something went wrong because there is no "MSG_ID" value in the request',
+				'event_espresso'), __FILE__, __FUNCTION__, __LINE__);
+			return false;
+		}
+
+		self::$_MSG_PROCESSOR->setup_messages_from_ids_and_send((array)$msgID);
+
+		//setup success message.
+		$count_ready_for_resend = self::$_MSG_PROCESSOR->get_queue()->count_STS_in_queue(EEM_Message::status_resend);
+		EE_Error::add_success(sprintf(
+			_n(
+				'There was %d message queued for resending.',
+				'There were %d messages queued for resending.',
+				$count_ready_for_resend,
+				'event_espresso'
+			),
+			$count_ready_for_resend
+		));
+		return true;
+	}
+
+
+	/**
+	 * Message triggers for manual payment applied by admin
+	 *
+	 * @param  EE_Payment $payment EE_payment object
+	 * @return bool              success/fail
+	 */
+	public static function process_admin_payment(EE_Payment $payment)
+	{
+		EE_Registry::instance()->load_helper('MSG_Template');
+		//we need to get the transaction object
+		$transaction = $payment->transaction();
+		if ($transaction instanceof EE_Transaction) {
+			$data         = array($transaction, $payment);
+			$message_type = EEH_MSG_Template::convert_payment_status_to_message_type($payment->STS_ID());
+
+			//if payment amount is less than 0 then switch to payment_refund message type.
+			$message_type = $payment->amount() < 0 ? 'payment_refund' : $message_type;
+
+			//if payment_refund is selected, but the status is NOT accepted.  Then change message type to false so NO message notification goes out.
+			$message_type = $message_type == 'payment_refund' && $payment->STS_ID() != EEM_Payment::status_id_approved ? false : $message_type;
+
+			self::_load_controller();
+
+			self::$_MSG_PROCESSOR->generate_for_all_active_messengers($message_type, $data);
+
+			//get count of queued for generation
+			$count_to_generate = self::$_MSG_PROCESSOR->get_queue()->count_STS_in_queue(array(
+				EEM_Message::status_incomplete,
+				EEM_Message::status_idle,
+			));
+
+			if ($count_to_generate > 0 && self::$_MSG_PROCESSOR->get_queue()->get_message_repository()->count() !== 0) {
+				add_filter('FHEE__EE_Admin_Page___process_admin_payment_notification__success', '__return_true');
+				return true;
+			} else {
+				$count_failed = self::$_MSG_PROCESSOR->get_queue()->count_STS_in_queue(EEM_Message::instance()->stati_indicating_failed_sending());
+				/**
+				 * Verify that there are actually errors.  If not then we return a success message because the queue might have been emptied due to successful
+				 * IMMEDIATE generation.
+				 */
+				if ($count_failed > 0) {
+					EE_Error::add_error(sprintf(
+						_n(
+							'The payment notification generation failed.',
+							'%d payment notifications failed being sent.',
+							$count_failed,
+							'event_espresso'
+						),
+						$count_failed
+					), __FILE__, __FUNCTION__, __LINE__);
+
+					return false;
+				} else {
+					add_filter('FHEE__EE_Admin_Page___process_admin_payment_notification__success', '__return_true');
+					return true;
+				}
+			}
+		} else {
+			EE_Error::add_error(
+				'Unable to generate the payment notification because the given value for the transaction is invalid.',
+				'event_espresso'
+			);
+			return false;
+		}
+	}
+
+
+	/**
+	 * Callback for AHEE__Extend_Registrations_Admin_Page___newsletter_selected_send_with_registrations trigger
+	 *
+	 * @since   4.3.0
+	 * @param  EE_Registration[] $registrations an array of EE_Registration objects
+	 * @param  int               $grp_id        a specific message template group id.
+	 * @return void
+	 */
+	public static function send_newsletter_message($registrations, $grp_id)
+	{
+		//make sure mtp is id and set it in the EE_Request Handler later messages setup.
+		EE_Registry::instance()->REQ->set('GRP_ID', (int)$grp_id);
+		self::_load_controller();
+		self::$_MSG_PROCESSOR->generate_for_all_active_messengers('newsletter', $registrations);
+	}
+
+
+	/**
+	 * Callback for FHEE__EE_Registration__invoice_url__invoice_url or FHEE__EE_Registration__receipt_url__receipt_url
+	 *
+	 * @since   4.3.0
+	 * @param    string          $registration_message_trigger_url
+	 * @param    EE_Registration $registration
+	 * @param string             $messenger
+	 * @param string             $message_type
+	 * @return    string
+	 */
+	public static function registration_message_trigger_url(
+		$registration_message_trigger_url,
+		EE_Registration $registration,
+		$messenger = 'html',
+		$message_type = 'invoice'
+	) {
+		// whitelist $messenger
+		switch ($messenger) {
+			case 'pdf' :
+				$sending_messenger    = 'pdf';
+				$generating_messenger = 'html';
+				break;
+			case 'html' :
+			default :
+				$sending_messenger    = 'html';
+				$generating_messenger = 'html';
+				break;
+		}
+		// whitelist $message_type
+		switch ($message_type) {
+			case 'receipt' :
+				$message_type = 'receipt';
+				break;
+			case 'invoice' :
+			default :
+				$message_type = 'invoice';
+				break;
+		}
+		// verify that both the messenger AND the message type are active
+		if (EEH_MSG_Template::is_messenger_active($sending_messenger) && EEH_MSG_Template::is_mt_active($message_type)) {
+			//need to get the correct message template group for this (i.e. is there a custom invoice for the event this registration is registered for?)
+			$template_query_params = array(
+				'MTP_is_active'    => true,
+				'MTP_messenger'    => $generating_messenger,
+				'MTP_message_type' => $message_type,
+				'Event.EVT_ID'     => $registration->event_ID(),
+			);
+			//get the message template group.
+			$msg_template_group = EEM_Message_Template_Group::instance()->get_one(array($template_query_params));
+			//if we don't have an EE_Message_Template_Group then return
+			if (! $msg_template_group instanceof EE_Message_Template_Group) {
+				// remove EVT_ID from query params so that global templates get picked up
+				unset($template_query_params['Event.EVT_ID']);
+				//get global template as the fallback
+				$msg_template_group = EEM_Message_Template_Group::instance()->get_one(array($template_query_params));
+			}
+			//if we don't have an EE_Message_Template_Group then return
+			if (! $msg_template_group instanceof EE_Message_Template_Group) {
+				return '';
+			}
+			// generate the URL
+			$registration_message_trigger_url = EEH_MSG_Template::generate_url_trigger(
+				$sending_messenger,
+				$generating_messenger,
+				'purchaser',
+				$message_type,
+				$registration,
+				$msg_template_group->ID(),
+				$registration->transaction_ID()
+			);
+
+		}
+		return $registration_message_trigger_url;
+	}
+
+
+	/**
+	 * Use to generate and return a message preview!
+	 *
+	 * @param  string $type      This should correspond with a valid message type
+	 * @param  string $context   This should correspond with a valid context for the message type
+	 * @param  string $messenger This should correspond with a valid messenger.
+	 * @param bool    $send      true we will do a test send using the messenger delivery, false we just do a regular
+	 *                           preview
+	 * @return bool|string The body of the message or if send is requested, sends.
+	 * @throws EE_Error
+	 */
+	public static function preview_message($type, $context, $messenger, $send = false)
+	{
+		self::_load_controller();
+		$mtg                     = new EE_Message_To_Generate(
+			$messenger,
+			$type,
+			array(),
+			$context,
+			true
+		);
+		$generated_preview_queue = self::$_MSG_PROCESSOR->generate_for_preview($mtg, $send);
+		if ($generated_preview_queue instanceof EE_Messages_Queue) {
+			//loop through all content for the preview and remove any persisted records.
+			$content = '';
+			foreach ($generated_preview_queue->get_message_repository() as $message) {
+				$content = $message->content();
+				if ($message->ID() > 0 && $message->STS_ID() !== EEM_Message::status_failed) {
+					$message->delete();
+				}
+			}
+			return $content;
+		} else {
+			return $generated_preview_queue;
+		}
+	}
+
+
+	/**
+	 * This is a method that allows for sending a message using a messenger matching the string given and the provided
+	 * EE_Message_Queue object.  The EE_Message_Queue object is used to create a single aggregate EE_Message via the
+	 * content found in the EE_Message objects in the queue.
+	 *
+	 * @since 4.9.0
+	 * @param string            $messenger            a string matching a valid active messenger in the system
+	 * @param string            $message_type         Although it seems contrary to the name of the method, a message
+	 *                                                type name is still required to send along the message type to the
+	 *                                                messenger because this is used for determining what specific
+	 *                                                variations might be loaded for the generated message.
+	 * @param EE_Messages_Queue $queue
+	 * @param string            $custom_subject       Can be used to set what the custom subject string will be on the
+	 *                                                aggregate EE_Message object.
+	 * @return bool          success or fail.
+	 */
+	public static function send_message_with_messenger_only(
+		$messenger,
+		$message_type,
+		EE_Messages_Queue $queue,
+		$custom_subject = ''
+	) {
+		self::_load_controller();
+		/** @type EE_Message_To_Generate_From_Queue $message_to_generate */
+		$message_to_generate = EE_Registry::instance()->load_lib(
+			'Message_To_Generate_From_Queue',
+			array(
+				$messenger,
+				$message_type,
+				$queue,
+				$custom_subject,
+			)
+		);
+		return self::$_MSG_PROCESSOR->queue_for_sending($message_to_generate);
+	}
+
+
+	/**
+	 * Generates Messages immediately for EE_Message IDs (but only for the correct status for generation)
+	 *
+	 * @since 4.9.0
+	 * @param array $message_ids An array of message ids
+	 * @return bool | EE_Messages_Queue     false if nothing was generated, EE_Messages_Queue containing generated
+	 *              messages.
+	 */
+	public static function generate_now($message_ids)
+	{
+		self::_load_controller();
+		$messages        = EEM_Message::instance()->get_all(
+			array(
+				0 => array(
+					'MSG_ID' => array('IN', $message_ids),
+					'STS_ID' => EEM_Message::status_incomplete,
+				),
+			)
+		);
+		$generated_queue = false;
+		if ($messages) {
+			$generated_queue = self::$_MSG_PROCESSOR->batch_generate_from_queue($messages);
+		}
+
+		if (! $generated_queue instanceof EE_Messages_Queue) {
+			EE_Error::add_error(
+				__('The messages were not generated. This could mean there is already a batch being generated on a separate request, or because the selected messages are not ready for generation. Please wait a minute or two and try again.',
+					'event_espresso'),
+				__FILE__, __FUNCTION__, __LINE__
+			);
+		}
+		return $generated_queue;
+	}
+
+
+	/**
+	 * Sends messages immediately for the incoming message_ids that have the status of EEM_Message::status_resend or,
+	 * EEM_Message::status_idle
+	 *
+	 * @since 4.9.0
+	 * @param $message_ids
+	 * @return bool | EE_Messages_Queue  false if no messages sent.
+	 */
+	public static function send_now($message_ids)
+	{
+		self::_load_controller();
+		$messages   = EEM_Message::instance()->get_all(
+			array(
+				0 => array(
+					'MSG_ID' => array('IN', $message_ids),
+					'STS_ID' => array(
+						'IN',
+						array(EEM_Message::status_idle, EEM_Message::status_resend, EEM_Message::status_retry),
+					),
+				),
+			)
+		);
+		$sent_queue = false;
+		if ($messages) {
+			$sent_queue = self::$_MSG_PROCESSOR->batch_send_from_queue($messages);
+		}
+
+		if (! $sent_queue instanceof EE_Messages_Queue) {
+			EE_Error::add_error(
+				__('The messages were not sent. This could mean there is already a batch being sent on a separate request, or because the selected messages are not sendable. Please wait a minute or two and try again.',
+					'event_espresso'),
+				__FILE__, __FUNCTION__, __LINE__
+			);
+		} else {
+			//can count how many sent by using the messages in the queue
+			$sent_count = $sent_queue->count_STS_in_queue(EEM_Message::instance()->stati_indicating_sent());
+			if ($sent_count > 0) {
+				EE_Error::add_success(
+					sprintf(
+						_n(
+							'There was %d message successfully sent.',
+							'There were %d messages successfully sent.',
+							$sent_count,
+							'event_espresso'
+						),
+						$sent_count
+					)
+				);
+			} else {
+				EE_Error::overwrite_errors();
+				EE_Error::add_error(
+					__('No message was sent because of problems with sending. Either all the messages you selected were not a sendable message, they were ALREADY sent on a different scheduled task, or there was an error.
 					If there was an error, you can look at the messages in the message activity list table for any error messages.',
-                        'event_espresso'),
-                    __FILE__, __FUNCTION__, __LINE__
-                );
-            }
-        }
-        return $sent_queue;
-    }
-
-
-    /**
-     * This will queue the incoming message ids for resending.
-     * Note, only message_ids corresponding to messages with the status of EEM_Message::sent will be queued.
-     *
-     * @since 4.9.0
-     * @param array $message_ids An array of EE_Message IDs
-     * @return bool  true means messages were successfully queued for resending, false means none were queued for
-     *               resending.
-     */
-    public static function queue_for_resending($message_ids)
-    {
-        self::_load_controller();
-        self::$_MSG_PROCESSOR->setup_messages_from_ids_and_send($message_ids);
-
-        //get queue and count
-        $queue_count = self::$_MSG_PROCESSOR->get_queue()->count_STS_in_queue(EEM_Message::status_resend);
-
-        if (
-            $queue_count > 0
-        ) {
-            EE_Error::add_success(
-                sprintf(
-                    _n(
-                        '%d message successfully queued for resending.',
-                        '%d messages successfully queued for resending.',
-                        $queue_count,
-                        'event_espresso'
-                    ),
-                    $queue_count
-                )
-            );
-            /**
-             * @see filter usage in EE_Messages_Queue::initiate_request_by_priority
-             */
-        } elseif (
-            apply_filters('FHEE__EE_Messages_Processor__initiate_request_by_priority__do_immediate_processing', true)
-            || EE_Registry::instance()->NET_CFG->core->do_messages_on_same_request
-        ) {
-            $queue_count = self::$_MSG_PROCESSOR->get_queue()->count_STS_in_queue(EEM_Message::status_sent);
-            if ($queue_count > 0) {
-                EE_Error::add_success(
-                    sprintf(
-                        _n(
-                            '%d message successfully sent.',
-                            '%d messages successfully sent.',
-                            $queue_count,
-                            'event_espresso'
-                        ),
-                        $queue_count
-                    )
-                );
-            } else {
-                EE_Error::add_error(
-                    __('No messages were queued for resending. This usually only happens when all the messages flagged for resending are not a status that can be resent.',
-                        'event_espresso'),
-                    __FILE__, __FUNCTION__, __LINE__
-                );
-            }
-        } else {
-            EE_Error::add_error(
-                __('No messages were queued for resending. This usually only happens when all the messages flagged for resending are not a status that can be resent.',
-                    'event_espresso'),
-                __FILE__, __FUNCTION__, __LINE__
-            );
-        }
-        return (bool)$queue_count;
-    }
-
-
-    /**
-     * debug
-     *
-     * @param string          $class
-     * @param string          $func
-     * @param string          $line
-     * @param \EE_Transaction $transaction
-     * @param array           $info
-     * @param bool            $display_request
-     */
-    protected static function log(
-        $class = '',
-        $func = '',
-        $line = '',
-        EE_Transaction $transaction,
-        $info = array(),
-        $display_request = false
-    ) {
-        if (WP_DEBUG && false) {
-            if ($transaction instanceof EE_Transaction) {
-                // don't serialize objects
-                $info                  = EEH_Debug_Tools::strip_objects($info);
-                $info['TXN_status']    = $transaction->status_ID();
-                $info['TXN_reg_steps'] = $transaction->reg_steps();
-                if ($transaction->ID()) {
-                    $index = 'EE_Transaction: ' . $transaction->ID();
-                    EEH_Debug_Tools::log($class, $func, $line, $info, $display_request, $index);
-                }
-            }
-        }
-
-    }
-
-
-    /**
-     *  Resets all the static properties in this class when called.
-     */
-    public static function reset()
-    {
-        self::$_EEMSG                    = null;
-        self::$_message_resource_manager = null;
-        self::$_MSG_PROCESSOR            = null;
-        self::$_MSG_PATHS                = null;
-        self::$_TMP_PACKS                = array();
-    }
+						'event_espresso'),
+					__FILE__, __FUNCTION__, __LINE__
+				);
+			}
+		}
+		return $sent_queue;
+	}
+
+
+	/**
+	 * This will queue the incoming message ids for resending.
+	 * Note, only message_ids corresponding to messages with the status of EEM_Message::sent will be queued.
+	 *
+	 * @since 4.9.0
+	 * @param array $message_ids An array of EE_Message IDs
+	 * @return bool  true means messages were successfully queued for resending, false means none were queued for
+	 *               resending.
+	 */
+	public static function queue_for_resending($message_ids)
+	{
+		self::_load_controller();
+		self::$_MSG_PROCESSOR->setup_messages_from_ids_and_send($message_ids);
+
+		//get queue and count
+		$queue_count = self::$_MSG_PROCESSOR->get_queue()->count_STS_in_queue(EEM_Message::status_resend);
+
+		if (
+			$queue_count > 0
+		) {
+			EE_Error::add_success(
+				sprintf(
+					_n(
+						'%d message successfully queued for resending.',
+						'%d messages successfully queued for resending.',
+						$queue_count,
+						'event_espresso'
+					),
+					$queue_count
+				)
+			);
+			/**
+			 * @see filter usage in EE_Messages_Queue::initiate_request_by_priority
+			 */
+		} elseif (
+			apply_filters('FHEE__EE_Messages_Processor__initiate_request_by_priority__do_immediate_processing', true)
+			|| EE_Registry::instance()->NET_CFG->core->do_messages_on_same_request
+		) {
+			$queue_count = self::$_MSG_PROCESSOR->get_queue()->count_STS_in_queue(EEM_Message::status_sent);
+			if ($queue_count > 0) {
+				EE_Error::add_success(
+					sprintf(
+						_n(
+							'%d message successfully sent.',
+							'%d messages successfully sent.',
+							$queue_count,
+							'event_espresso'
+						),
+						$queue_count
+					)
+				);
+			} else {
+				EE_Error::add_error(
+					__('No messages were queued for resending. This usually only happens when all the messages flagged for resending are not a status that can be resent.',
+						'event_espresso'),
+					__FILE__, __FUNCTION__, __LINE__
+				);
+			}
+		} else {
+			EE_Error::add_error(
+				__('No messages were queued for resending. This usually only happens when all the messages flagged for resending are not a status that can be resent.',
+					'event_espresso'),
+				__FILE__, __FUNCTION__, __LINE__
+			);
+		}
+		return (bool)$queue_count;
+	}
+
+
+	/**
+	 * debug
+	 *
+	 * @param string          $class
+	 * @param string          $func
+	 * @param string          $line
+	 * @param \EE_Transaction $transaction
+	 * @param array           $info
+	 * @param bool            $display_request
+	 */
+	protected static function log(
+		$class = '',
+		$func = '',
+		$line = '',
+		EE_Transaction $transaction,
+		$info = array(),
+		$display_request = false
+	) {
+		if (WP_DEBUG && false) {
+			if ($transaction instanceof EE_Transaction) {
+				// don't serialize objects
+				$info                  = EEH_Debug_Tools::strip_objects($info);
+				$info['TXN_status']    = $transaction->status_ID();
+				$info['TXN_reg_steps'] = $transaction->reg_steps();
+				if ($transaction->ID()) {
+					$index = 'EE_Transaction: ' . $transaction->ID();
+					EEH_Debug_Tools::log($class, $func, $line, $info, $display_request, $index);
+				}
+			}
+		}
+
+	}
+
+
+	/**
+	 *  Resets all the static properties in this class when called.
+	 */
+	public static function reset()
+	{
+		self::$_EEMSG                    = null;
+		self::$_message_resource_manager = null;
+		self::$_MSG_PROCESSOR            = null;
+		self::$_MSG_PATHS                = null;
+		self::$_TMP_PACKS                = array();
+	}
 
 }
 // End of file EED_Messages.module.php

core/db_classes/EE_Base_Class.class.php

Indentation +2713 added lines, -2713 removed lines

@@ -1,5 +1,5 @@ 
 <?php if ( ! defined('EVENT_ESPRESSO_VERSION')) {
-    exit('No direct script access allowed');
+	exit('No direct script access allowed');
 }
 do_action('AHEE_log', __FILE__, ' FILE LOADED', '');
 
@@ -25,2718 +25,2718 @@ 
 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;
-
-
-
-    /**
-     * 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 EE_Error
-     */
-    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);
-        // EEH_Debug_Tools::printr( $fieldValues, '$fieldValues  <br /><span style="font-size:10px;font-weight:normal;">' . __FILE__ . '<br />line no: ' . __LINE__ . '</span>', 'auto' );
-        // 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(__("Invalid field (%s) passed to constructor of %s. Allowed fields are :%s",
-                    "event_espresso"), $field_name, get_class($this), implode(", ", array_keys($model_fields))));
-            }
-        }
-        // EEH_Debug_Tools::printr( $model_fields, '$model_fields  <br /><span style="font-size:10px;font-weight:normal;">' . __FILE__ . '<br />line no: ' . __LINE__ . '</span>', 'auto' );
-        $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 \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]);
-        } else {
-            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 \EE_Error
-     */
-    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(__("A valid EE_Model_Field_Base could not be found for the given field name: %s",
-                "event_espresso"), $field_name));
-        }
-    }
-
-
-
-    /**
-     * 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 \EE_Error
-     */
-    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;
-        } else {
-            //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 \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 \EE_Error
-     */
-    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) {
-                    $this->_fields[$field_name]->setTimezone(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 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(__('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 \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 \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
-     */
-    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 \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 \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 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(
-                    __("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) {
-                        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) {
-                    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],
-                $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 \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...
-            } elseif (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);
-        } else {
-            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 \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(
-                        __(
-                            '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 \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 \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 \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 \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 \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 \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 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).
-     */
-    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(
-                    __(
-                        '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 $this->_fields[$field_name];
-    }
-
-
-
-    /**
-     * 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 \EE_Error
-     */
-    public function e($field_name, $extra_cache_ref = null)
-    {
-        echo $this->get_pretty($field_name, $extra_cache_ref);
-    }
-
-
-
-    /**
-     * Exactly like e(), echoes out the field, but sets its schema to 'form_input', so that it
-     * can be easily used as the value of form input.
-     *
-     * @param string $field_name
-     * @return void
-     * @throws \EE_Error
-     */
-    public function f($field_name)
-    {
-        $this->e($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 \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 \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 \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 \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 \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 \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 \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 \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 \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 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;
-        } else {
-            throw new EE_Error(sprintf(__('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 \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 \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 \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]
-                );
-                break;
-            case 'D' :
-                $this->_fields[$fieldname] = $field->prepare_for_set_with_new_date(
-                    $datetime_value,
-                    $this->_fields[$fieldname]
-                );
-                break;
-            case 'B' :
-                $this->_fields[$fieldname] = $field->prepare_for_set($datetime_value);
-                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 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(
-                    __(
-                        '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 \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 \EE_Error
-     */
-    protected function _delete()
-    {
-        return $this->delete_permanently();
-    }
-
-
-
-    /**
-     * Deletes this model object permanently from db (but keep in mind related models my block the delete and return an
-     * error)
-     *
-     * @return bool | int
-     * @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 \EE_Error
-     */
-    public function refresh_cache_of_related_objects()
-    {
-        $model = $this->get_model();
-        foreach ($model->relation_settings() as $relation_name => $relation_obj) {
-            if ( ! empty($this->_model_relations[$relation_name])) {
-                $related_objects = $this->_model_relations[$relation_name];
-                if ($relation_obj instanceof EE_Belongs_To_Relation) {
-                    //this relation only stores a single model object, not an array
-                    //but let's make it consistent
-                    $related_objects = array($related_objects);
-                }
-                foreach ($related_objects as $related_object) {
-                    //only refresh their cache if they're in memory
-                    if ($related_object instanceof EE_Base_Class) {
-                        $related_object->clear_cache($model->get_this_model_name(), $this);
-                    }
-                }
-            }
-        }
-    }
-
-
-
-    /**
-     *        Saves this object to the database. An array may be supplied to set some values on this
-     * object just before saving.
-     *
-     * @access public
-     * @param array $set_cols_n_values keys are field names, values are their new values,
-     *                                 if provided during the save() method (often client code will change the fields'
-     *                                 values before calling save)
-     * @throws \EE_Error
-     * @return int , 1 on a successful update, the ID of the new entry on insert; 0 on failure or if the model object
-     *                                 isn't allowed to persist (as determined by EE_Base_Class::allow_persist())
-     */
-    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(
-                                __('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 \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 \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)?
-                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
-                    /* @var $related_model_obj EE_Base_Class */
-                    $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
-     */
-    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 \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 \EE_Error
-     */
-    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;
-        } else {
-            return false;
-        }
-    }
-
-
-
-    /**
-     * Gets the EEM_*_Model for this class
-     *
-     * @access public now, as this is more convenient
-     * @param      $classname
-     * @param null $timezone
-     * @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(
-                    __(
-                        "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
-     */
-    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 EE_Error
-     * @return string
-     */
-    protected static function _get_primary_key_name($classname = null)
-    {
-        if ( ! $classname) {
-            throw new EE_Error(
-                sprintf(
-                    __("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 \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()];
-        } else {
-            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 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(
-                    __('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)
-                ));
-            } else {
-                $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 a NEW row is
-     *                created in the join table.
-     * @return EE_Base_Class the relation was removed from
-     * @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 like EEM_Base::get_all's $query_params[0] (where conditions)
-     * @return EE_Base_Class
-     * @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 like EEM_Base::get_all
-     * @return EE_Base_Class[] Results not necessarily indexed by IDs, because some results might not have primary keys
-     * @throws \EE_Error
-     *                             or might not be saved yet. Consider using EEM_Base::get_IDs() on these results if
-     *                             you want IDs
-     */
-    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   like EEM_Base::get_all's
-     * @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
-     */
-    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  like EEM_Base::get_all's
-     * @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
-     */
-    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 like EEM_Base::get_all
-     * @return EE_Base_Class (not an array, a single object)
-     * @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 like EEM_Base::get_all's
-     * @return int how many deleted
-     * @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 like EEM_Base::get_all's
-     * @return int how many deleted (including those soft deleted)
-     * @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(
-                        __(
-                            '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 \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(
-                    __(
-                        "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)
-     * @throws \EE_Error
-     * NOTE: if the values haven't changed, returns 0
-     */
-    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 \EE_Error
-     */
-    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 \EE_Error
-     */
-    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 \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 \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 \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());
-        } else {
-            $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 \EE_Error
-     */
-    public function in_entity_map()
-    {
-        if ($this->ID() && $this->get_model()->get_from_entity_map($this->ID()) === $this) {
-            //well, if we looked, did we find it in the entity map?
-            return true;
-        } else {
-            return false;
-        }
-    }
-
-
-
-    /**
-     * refresh_from_db
-     * Makes sure the fields and values on this model object are in-sync with what's in the database.
-     *
-     * @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(
-                        __('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()'
-                    )
-                );
-            }
-        }
-    }
-
-
-
-    /**
-     * 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 \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;
-    }
+	/**
+	 * 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;
+
+
+
+	/**
+	 * 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 EE_Error
+	 */
+	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);
+		// EEH_Debug_Tools::printr( $fieldValues, '$fieldValues  <br /><span style="font-size:10px;font-weight:normal;">' . __FILE__ . '<br />line no: ' . __LINE__ . '</span>', 'auto' );
+		// 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(__("Invalid field (%s) passed to constructor of %s. Allowed fields are :%s",
+					"event_espresso"), $field_name, get_class($this), implode(", ", array_keys($model_fields))));
+			}
+		}
+		// EEH_Debug_Tools::printr( $model_fields, '$model_fields  <br /><span style="font-size:10px;font-weight:normal;">' . __FILE__ . '<br />line no: ' . __LINE__ . '</span>', 'auto' );
+		$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 \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]);
+		} else {
+			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 \EE_Error
+	 */
+	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(__("A valid EE_Model_Field_Base could not be found for the given field name: %s",
+				"event_espresso"), $field_name));
+		}
+	}
+
+
+
+	/**
+	 * 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 \EE_Error
+	 */
+	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;
+		} else {
+			//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 \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 \EE_Error
+	 */
+	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) {
+					$this->_fields[$field_name]->setTimezone(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 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(__('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 \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 \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
+	 */
+	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 \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 \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 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(
+					__("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) {
+						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) {
+					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],
+				$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 \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...
+			} elseif (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);
+		} else {
+			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 \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(
+						__(
+							'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 \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 \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 \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 \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 \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 \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 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).
+	 */
+	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(
+					__(
+						'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 $this->_fields[$field_name];
+	}
+
+
+
+	/**
+	 * 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 \EE_Error
+	 */
+	public function e($field_name, $extra_cache_ref = null)
+	{
+		echo $this->get_pretty($field_name, $extra_cache_ref);
+	}
+
+
+
+	/**
+	 * Exactly like e(), echoes out the field, but sets its schema to 'form_input', so that it
+	 * can be easily used as the value of form input.
+	 *
+	 * @param string $field_name
+	 * @return void
+	 * @throws \EE_Error
+	 */
+	public function f($field_name)
+	{
+		$this->e($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 \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 \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 \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 \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 \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 \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 \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 \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 \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 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;
+		} else {
+			throw new EE_Error(sprintf(__('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 \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 \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 \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]
+				);
+				break;
+			case 'D' :
+				$this->_fields[$fieldname] = $field->prepare_for_set_with_new_date(
+					$datetime_value,
+					$this->_fields[$fieldname]
+				);
+				break;
+			case 'B' :
+				$this->_fields[$fieldname] = $field->prepare_for_set($datetime_value);
+				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 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(
+					__(
+						'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 \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 \EE_Error
+	 */
+	protected function _delete()
+	{
+		return $this->delete_permanently();
+	}
+
+
+
+	/**
+	 * Deletes this model object permanently from db (but keep in mind related models my block the delete and return an
+	 * error)
+	 *
+	 * @return bool | int
+	 * @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 \EE_Error
+	 */
+	public function refresh_cache_of_related_objects()
+	{
+		$model = $this->get_model();
+		foreach ($model->relation_settings() as $relation_name => $relation_obj) {
+			if ( ! empty($this->_model_relations[$relation_name])) {
+				$related_objects = $this->_model_relations[$relation_name];
+				if ($relation_obj instanceof EE_Belongs_To_Relation) {
+					//this relation only stores a single model object, not an array
+					//but let's make it consistent
+					$related_objects = array($related_objects);
+				}
+				foreach ($related_objects as $related_object) {
+					//only refresh their cache if they're in memory
+					if ($related_object instanceof EE_Base_Class) {
+						$related_object->clear_cache($model->get_this_model_name(), $this);
+					}
+				}
+			}
+		}
+	}
+
+
+
+	/**
+	 *        Saves this object to the database. An array may be supplied to set some values on this
+	 * object just before saving.
+	 *
+	 * @access public
+	 * @param array $set_cols_n_values keys are field names, values are their new values,
+	 *                                 if provided during the save() method (often client code will change the fields'
+	 *                                 values before calling save)
+	 * @throws \EE_Error
+	 * @return int , 1 on a successful update, the ID of the new entry on insert; 0 on failure or if the model object
+	 *                                 isn't allowed to persist (as determined by EE_Base_Class::allow_persist())
+	 */
+	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(
+								__('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 \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 \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)?
+				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
+					/* @var $related_model_obj EE_Base_Class */
+					$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
+	 */
+	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 \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 \EE_Error
+	 */
+	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;
+		} else {
+			return false;
+		}
+	}
+
+
+
+	/**
+	 * Gets the EEM_*_Model for this class
+	 *
+	 * @access public now, as this is more convenient
+	 * @param      $classname
+	 * @param null $timezone
+	 * @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(
+					__(
+						"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
+	 */
+	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 EE_Error
+	 * @return string
+	 */
+	protected static function _get_primary_key_name($classname = null)
+	{
+		if ( ! $classname) {
+			throw new EE_Error(
+				sprintf(
+					__("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 \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()];
+		} else {
+			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 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(
+					__('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)
+				));
+			} else {
+				$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 a NEW row is
+	 *                created in the join table.
+	 * @return EE_Base_Class the relation was removed from
+	 * @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 like EEM_Base::get_all's $query_params[0] (where conditions)
+	 * @return EE_Base_Class
+	 * @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 like EEM_Base::get_all
+	 * @return EE_Base_Class[] Results not necessarily indexed by IDs, because some results might not have primary keys
+	 * @throws \EE_Error
+	 *                             or might not be saved yet. Consider using EEM_Base::get_IDs() on these results if
+	 *                             you want IDs
+	 */
+	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   like EEM_Base::get_all's
+	 * @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
+	 */
+	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  like EEM_Base::get_all's
+	 * @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
+	 */
+	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 like EEM_Base::get_all
+	 * @return EE_Base_Class (not an array, a single object)
+	 * @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 like EEM_Base::get_all's
+	 * @return int how many deleted
+	 * @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 like EEM_Base::get_all's
+	 * @return int how many deleted (including those soft deleted)
+	 * @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(
+						__(
+							'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 \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(
+					__(
+						"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)
+	 * @throws \EE_Error
+	 * NOTE: if the values haven't changed, returns 0
+	 */
+	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 \EE_Error
+	 */
+	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 \EE_Error
+	 */
+	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 \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 \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 \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());
+		} else {
+			$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 \EE_Error
+	 */
+	public function in_entity_map()
+	{
+		if ($this->ID() && $this->get_model()->get_from_entity_map($this->ID()) === $this) {
+			//well, if we looked, did we find it in the entity map?
+			return true;
+		} else {
+			return false;
+		}
+	}
+
+
+
+	/**
+	 * refresh_from_db
+	 * Makes sure the fields and values on this model object are in-sync with what's in the database.
+	 *
+	 * @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(
+						__('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()'
+					)
+				);
+			}
+		}
+	}
+
+
+
+	/**
+	 * 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 \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;
+	}
 
 
 

core/libraries/form_sections/strategies/layout/EE_Form_Section_Layout_Base.strategy.php

Indentation +253 added lines, -253 removed lines

@@ -15,257 +15,257 @@
 abstract class EE_Form_Section_Layout_Base
 {
 
-    /**
-     * Form form section to lay out
-     *
-     * @var EE_Form_Section_Proper
-     */
-    protected $_form_section;
-
-
-
-    /**
-     *  __construct
-     */
-    public function __construct()
-    {
-    }
-
-
-
-    /**
-     * The form section on which this strategy is to perform
-     *
-     * @param EE_Form_Section_Proper $form
-     */
-    public function _construct_finalize(EE_Form_Section_Proper $form)
-    {
-        $this->_form_section = $form;
-    }
-
-
-
-    /**
-     * @return EE_Form_Section_Proper
-     */
-    public function form_section()
-    {
-        return $this->_form_section;
-    }
-
-
-
-    /**
-     * Also has teh side effect of enqueuing any needed JS and CSS for
-     * this form.
-     * Creates all the HTML necessary for displaying this form, its inputs, and
-     * proper subsections.
-     * Returns the HTML
-     *
-     * @return string HTML for displaying
-     * @throws EE_Error
-     */
-    public function layout_form()
-    {
-        $html = '';
-        // layout_form_begin
-        $html .= apply_filters(
-            'FHEE__EE_Form_Section_Layout_Base__layout_form__start__for_' . $this->_form_section->name(),
-            $this->layout_form_begin(),
-            $this->_form_section
-        );
-        // layout_form_loop
-        $html .= apply_filters(
-            'FHEE__EE_Form_Section_Layout_Base__layout_form__loop__for_' . $this->_form_section->name(),
-            $this->layout_form_loop(),
-            $this->_form_section
-        );
-        // layout_form_end
-        $html .= apply_filters(
-            'FHEE__EE_Form_Section_Layout_Base__layout_form__end__for_' . $this->_form_section->name(),
-            $this->layout_form_end(),
-            $this->_form_section
-        );
-        $html = $this->add_form_section_hooks_and_filters($html);
-        return $html;
-    }
-
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     */
-    public function layout_form_loop()
-    {
-        $html = '';
-        foreach ($this->_form_section->subsections() as $name => $subsection) {
-            if ($subsection instanceof EE_Form_Input_Base) {
-                $html .= apply_filters(
-                    'FHEE__EE_Form_Section_Layout_Base__layout_form__loop_for_input_'
-                    . $name . '__in_' . $this->_form_section->name(),
-                    $this->layout_input($subsection),
-                    $this->_form_section,
-                    $subsection
-                );
-            } elseif ($subsection instanceof EE_Form_Section_Base) {
-                $html .= apply_filters(
-                    'FHEE__EE_Form_Section_Layout_Base__layout_form__loop_for_non_input_'
-                    . $name . '__in_' . $this->_form_section->name(),
-                    $this->layout_subsection($subsection),
-                    $this->_form_section,
-                    $subsection
-                );
-            }
-        }
-        return $html;
-    }
-
-
-
-    /**
-     * Should be used to start teh form section (Eg a table tag, or a div tag, etc.)
-     *
-     * @return string
-     */
-    abstract public function layout_form_begin();
-
-
-
-    /**
-     * Should be used to end the form section (eg a /table tag, or a /div tag, etc)
-     *
-     * @return string
-     */
-    abstract public function layout_form_end();
-
-
-
-    /**
-     * Should be used internally by layout_form() to layout each input (eg, if this layout
-     * is putting each input in a row of its own, this should probably be called by a
-     *  foreach loop in layout_form() (WITHOUT adding any content directly within layout_form()'s foreach loop.
-     * Eg, this method should add the tr and td tags). This method is exposed in case you want to completely
-     * customize the form's layout, but would like to make use of it for laying out
-     * 'easy-to-layout' inputs
-     *
-     * @param EE_Form_Input_Base $input
-     * @return string html
-     */
-    abstract public function layout_input($input);
-
-
-
-    /**
-     * Similar to layout_input(), should be used internally by layout_form() within a
-     * loop to layout each proper subsection. Unlike layout_input(), however, it is assumed
-     * that the proper subsection will layout its container, label, etc on its own.
-     *
-     * @param EE_Form_Section_Base $subsection
-     * @return string html
-     */
-    abstract public function layout_subsection($subsection);
-
-
-
-    /**
-     * Gets the HTML for the label tag and its contents for the input
-     *
-     * @param EE_Form_Input_Base $input
-     * @return string
-     */
-    public function display_label($input)
-    {
-        $class = $input->required()
-            ? 'ee-required-label ' . $input->html_label_class()
-            : $input->html_label_class();
-        $label_text = $input->required()
-            ? $input->html_label_text() . '<span class="ee-asterisk">*</span>'
-            : $input->html_label_text();
-        return '<label id="'
-               . $input->html_label_id()
-               . '" class="'
-               . $class
-               . '" style="'
-               . $input->html_label_style()
-               . '" for="' . $input->html_name()
-               . '">'
-               . $label_text
-               . '</label>';
-    }
-
-
-
-    /**
-     * returns the HTML for the server-side validation errors for the specified input
-     * Note that if JS is enabled, it should remove these and instead
-     * populate the form's errors in the jquery validate fashion
-     * using the localized data provided to the JS
-     *
-     * @param EE_Form_Input_Base $input
-     * @return string
-     */
-    public function display_errors($input)
-    {
-        if ($input->get_validation_errors()) {
-            return "<label  id='"
-                   . $input->html_id()
-                   . "-error' class='error' for='{$input->html_name()}'>"
-                   . $input->get_validation_error_string()
-                   . '</label>';
-        }
-        return '';
-    }
-
-
-
-    /**
-     * Displays the help span for the specified input
-     *
-     * @param EE_Form_Input_Base $input
-     * @return string
-     */
-    public function display_help_text($input)
-    {
-        if ($input->html_help_text() !== '') {
-            $tag = is_admin() ? 'p' : 'span';
-            return '<'
-                   . $tag
-                   . ' id="'
-                   . $input->html_id()
-                   . '-help" class="'
-                   . $input->html_help_class()
-                   . '" style="'
-                   . $input->html_help_style()
-                   . '">'
-                   . $input->html_help_text()
-                   . '</'
-                   . $tag
-                   . '>';
-        }
-        return '';
-    }
-
-
-
-    /**
-     * Does an action and hook onto the end of teh form
-     *
-     * @param string $html
-     * @return string
-     */
-    public function add_form_section_hooks_and_filters($html)
-    {
-        // replace dashes and spaces with underscores
-        $hook_name = str_replace(array('-', ' '), '_', $this->_form_section->html_id());
-        do_action('AHEE__Form_Section_Layout__' . $hook_name, $this->_form_section);
-        $html = (string) apply_filters(
-            'AFEE__Form_Section_Layout__' . $hook_name . '__html',
-            $html,
-            $this->_form_section
-        );
-        $html .= EEH_HTML::nl() . '<!-- AHEE__Form_Section_Layout__' . $hook_name . '__html -->';
-        $html .= EEH_HTML::nl() . '<!-- AFEE__Form_Section_Layout__' . $hook_name . ' -->';
-        return $html;
-    }
+	/**
+	 * Form form section to lay out
+	 *
+	 * @var EE_Form_Section_Proper
+	 */
+	protected $_form_section;
+
+
+
+	/**
+	 *  __construct
+	 */
+	public function __construct()
+	{
+	}
+
+
+
+	/**
+	 * The form section on which this strategy is to perform
+	 *
+	 * @param EE_Form_Section_Proper $form
+	 */
+	public function _construct_finalize(EE_Form_Section_Proper $form)
+	{
+		$this->_form_section = $form;
+	}
+
+
+
+	/**
+	 * @return EE_Form_Section_Proper
+	 */
+	public function form_section()
+	{
+		return $this->_form_section;
+	}
+
+
+
+	/**
+	 * Also has teh side effect of enqueuing any needed JS and CSS for
+	 * this form.
+	 * Creates all the HTML necessary for displaying this form, its inputs, and
+	 * proper subsections.
+	 * Returns the HTML
+	 *
+	 * @return string HTML for displaying
+	 * @throws EE_Error
+	 */
+	public function layout_form()
+	{
+		$html = '';
+		// layout_form_begin
+		$html .= apply_filters(
+			'FHEE__EE_Form_Section_Layout_Base__layout_form__start__for_' . $this->_form_section->name(),
+			$this->layout_form_begin(),
+			$this->_form_section
+		);
+		// layout_form_loop
+		$html .= apply_filters(
+			'FHEE__EE_Form_Section_Layout_Base__layout_form__loop__for_' . $this->_form_section->name(),
+			$this->layout_form_loop(),
+			$this->_form_section
+		);
+		// layout_form_end
+		$html .= apply_filters(
+			'FHEE__EE_Form_Section_Layout_Base__layout_form__end__for_' . $this->_form_section->name(),
+			$this->layout_form_end(),
+			$this->_form_section
+		);
+		$html = $this->add_form_section_hooks_and_filters($html);
+		return $html;
+	}
+
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function layout_form_loop()
+	{
+		$html = '';
+		foreach ($this->_form_section->subsections() as $name => $subsection) {
+			if ($subsection instanceof EE_Form_Input_Base) {
+				$html .= apply_filters(
+					'FHEE__EE_Form_Section_Layout_Base__layout_form__loop_for_input_'
+					. $name . '__in_' . $this->_form_section->name(),
+					$this->layout_input($subsection),
+					$this->_form_section,
+					$subsection
+				);
+			} elseif ($subsection instanceof EE_Form_Section_Base) {
+				$html .= apply_filters(
+					'FHEE__EE_Form_Section_Layout_Base__layout_form__loop_for_non_input_'
+					. $name . '__in_' . $this->_form_section->name(),
+					$this->layout_subsection($subsection),
+					$this->_form_section,
+					$subsection
+				);
+			}
+		}
+		return $html;
+	}
+
+
+
+	/**
+	 * Should be used to start teh form section (Eg a table tag, or a div tag, etc.)
+	 *
+	 * @return string
+	 */
+	abstract public function layout_form_begin();
+
+
+
+	/**
+	 * Should be used to end the form section (eg a /table tag, or a /div tag, etc)
+	 *
+	 * @return string
+	 */
+	abstract public function layout_form_end();
+
+
+
+	/**
+	 * Should be used internally by layout_form() to layout each input (eg, if this layout
+	 * is putting each input in a row of its own, this should probably be called by a
+	 *  foreach loop in layout_form() (WITHOUT adding any content directly within layout_form()'s foreach loop.
+	 * Eg, this method should add the tr and td tags). This method is exposed in case you want to completely
+	 * customize the form's layout, but would like to make use of it for laying out
+	 * 'easy-to-layout' inputs
+	 *
+	 * @param EE_Form_Input_Base $input
+	 * @return string html
+	 */
+	abstract public function layout_input($input);
+
+
+
+	/**
+	 * Similar to layout_input(), should be used internally by layout_form() within a
+	 * loop to layout each proper subsection. Unlike layout_input(), however, it is assumed
+	 * that the proper subsection will layout its container, label, etc on its own.
+	 *
+	 * @param EE_Form_Section_Base $subsection
+	 * @return string html
+	 */
+	abstract public function layout_subsection($subsection);
+
+
+
+	/**
+	 * Gets the HTML for the label tag and its contents for the input
+	 *
+	 * @param EE_Form_Input_Base $input
+	 * @return string
+	 */
+	public function display_label($input)
+	{
+		$class = $input->required()
+			? 'ee-required-label ' . $input->html_label_class()
+			: $input->html_label_class();
+		$label_text = $input->required()
+			? $input->html_label_text() . '<span class="ee-asterisk">*</span>'
+			: $input->html_label_text();
+		return '<label id="'
+			   . $input->html_label_id()
+			   . '" class="'
+			   . $class
+			   . '" style="'
+			   . $input->html_label_style()
+			   . '" for="' . $input->html_name()
+			   . '">'
+			   . $label_text
+			   . '</label>';
+	}
+
+
+
+	/**
+	 * returns the HTML for the server-side validation errors for the specified input
+	 * Note that if JS is enabled, it should remove these and instead
+	 * populate the form's errors in the jquery validate fashion
+	 * using the localized data provided to the JS
+	 *
+	 * @param EE_Form_Input_Base $input
+	 * @return string
+	 */
+	public function display_errors($input)
+	{
+		if ($input->get_validation_errors()) {
+			return "<label  id='"
+				   . $input->html_id()
+				   . "-error' class='error' for='{$input->html_name()}'>"
+				   . $input->get_validation_error_string()
+				   . '</label>';
+		}
+		return '';
+	}
+
+
+
+	/**
+	 * Displays the help span for the specified input
+	 *
+	 * @param EE_Form_Input_Base $input
+	 * @return string
+	 */
+	public function display_help_text($input)
+	{
+		if ($input->html_help_text() !== '') {
+			$tag = is_admin() ? 'p' : 'span';
+			return '<'
+				   . $tag
+				   . ' id="'
+				   . $input->html_id()
+				   . '-help" class="'
+				   . $input->html_help_class()
+				   . '" style="'
+				   . $input->html_help_style()
+				   . '">'
+				   . $input->html_help_text()
+				   . '</'
+				   . $tag
+				   . '>';
+		}
+		return '';
+	}
+
+
+
+	/**
+	 * Does an action and hook onto the end of teh form
+	 *
+	 * @param string $html
+	 * @return string
+	 */
+	public function add_form_section_hooks_and_filters($html)
+	{
+		// replace dashes and spaces with underscores
+		$hook_name = str_replace(array('-', ' '), '_', $this->_form_section->html_id());
+		do_action('AHEE__Form_Section_Layout__' . $hook_name, $this->_form_section);
+		$html = (string) apply_filters(
+			'AFEE__Form_Section_Layout__' . $hook_name . '__html',
+			$html,
+			$this->_form_section
+		);
+		$html .= EEH_HTML::nl() . '<!-- AHEE__Form_Section_Layout__' . $hook_name . '__html -->';
+		$html .= EEH_HTML::nl() . '<!-- AFEE__Form_Section_Layout__' . $hook_name . ' -->';
+		return $html;
+	}
 }

Spacing +12 added lines, -12 removed lines

@@ -70,19 +70,19 @@ 
         $html = '';
         // layout_form_begin
         $html .= apply_filters(
-            'FHEE__EE_Form_Section_Layout_Base__layout_form__start__for_' . $this->_form_section->name(),
+            'FHEE__EE_Form_Section_Layout_Base__layout_form__start__for_'.$this->_form_section->name(),
             $this->layout_form_begin(),
             $this->_form_section
         );
         // layout_form_loop
         $html .= apply_filters(
-            'FHEE__EE_Form_Section_Layout_Base__layout_form__loop__for_' . $this->_form_section->name(),
+            'FHEE__EE_Form_Section_Layout_Base__layout_form__loop__for_'.$this->_form_section->name(),
             $this->layout_form_loop(),
             $this->_form_section
         );
         // layout_form_end
         $html .= apply_filters(
-            'FHEE__EE_Form_Section_Layout_Base__layout_form__end__for_' . $this->_form_section->name(),
+            'FHEE__EE_Form_Section_Layout_Base__layout_form__end__for_'.$this->_form_section->name(),
             $this->layout_form_end(),
             $this->_form_section
         );
@@ -103,7 +103,7 @@ 
             if ($subsection instanceof EE_Form_Input_Base) {
                 $html .= apply_filters(
                     'FHEE__EE_Form_Section_Layout_Base__layout_form__loop_for_input_'
-                    . $name . '__in_' . $this->_form_section->name(),
+                    . $name.'__in_'.$this->_form_section->name(),
                     $this->layout_input($subsection),
                     $this->_form_section,
                     $subsection
@@ -111,7 +111,7 @@ 
             } elseif ($subsection instanceof EE_Form_Section_Base) {
                 $html .= apply_filters(
                     'FHEE__EE_Form_Section_Layout_Base__layout_form__loop_for_non_input_'
-                    . $name . '__in_' . $this->_form_section->name(),
+                    . $name.'__in_'.$this->_form_section->name(),
                     $this->layout_subsection($subsection),
                     $this->_form_section,
                     $subsection
@@ -177,10 +177,10 @@ 
     public function display_label($input)
     {
         $class = $input->required()
-            ? 'ee-required-label ' . $input->html_label_class()
+            ? 'ee-required-label '.$input->html_label_class()
             : $input->html_label_class();
         $label_text = $input->required()
-            ? $input->html_label_text() . '<span class="ee-asterisk">*</span>'
+            ? $input->html_label_text().'<span class="ee-asterisk">*</span>'
             : $input->html_label_text();
         return '<label id="'
                . $input->html_label_id()
@@ -188,7 +188,7 @@ 
                . $class
                . '" style="'
                . $input->html_label_style()
-               . '" for="' . $input->html_name()
+               . '" for="'.$input->html_name()
                . '">'
                . $label_text
                . '</label>';
@@ -258,14 +258,14 @@ 
     {
         // replace dashes and spaces with underscores
         $hook_name = str_replace(array('-', ' '), '_', $this->_form_section->html_id());
-        do_action('AHEE__Form_Section_Layout__' . $hook_name, $this->_form_section);
+        do_action('AHEE__Form_Section_Layout__'.$hook_name, $this->_form_section);
         $html = (string) apply_filters(
-            'AFEE__Form_Section_Layout__' . $hook_name . '__html',
+            'AFEE__Form_Section_Layout__'.$hook_name.'__html',
             $html,
             $this->_form_section
         );
-        $html .= EEH_HTML::nl() . '<!-- AHEE__Form_Section_Layout__' . $hook_name . '__html -->';
-        $html .= EEH_HTML::nl() . '<!-- AFEE__Form_Section_Layout__' . $hook_name . ' -->';
+        $html .= EEH_HTML::nl().'<!-- AHEE__Form_Section_Layout__'.$hook_name.'__html -->';
+        $html .= EEH_HTML::nl().'<!-- AFEE__Form_Section_Layout__'.$hook_name.' -->';
         return $html;
     }
 }

core/libraries/form_sections/strategies/filter/VsprintfFilter.php

Indentation +43 added lines, -43 removed lines

@@ -24,49 +24,49 @@
 class VsprintfFilter extends FormHtmlFilter
 {
 
-    /**
-     * @var string $format
-     */
-    protected $format = '';
-
-
-    /**
-     * @var array $args
-     */
-    protected $args = array();
-
-
-
-    /**
-     * VsprintfFilter constructor.
-     *
-     * @param string $format
-     * @param array  $args
-     */
-    public function __construct($format, array $args)
-    {
-        $this->format = $format;
-        $this->args   = $args;
-    }
-
-
-
-    /**
-     * @param                             $html
-     * @param EE_Form_Section_Validatable $form_section
-     * @return string
-     */
-    public function filterHtml($html, EE_Form_Section_Validatable $form_section)
-    {
-        $this->args[] = $html;
-        if ($form_section instanceof EE_Form_Section_Proper) {
-            $subsections = $form_section->subsections();
-            foreach ((array)$subsections as $subsection) {
-                $this->args[] = $subsection->get_html();
-            }
-        }
-        return vsprintf($this->format, $this->args);
-    }
+	/**
+	 * @var string $format
+	 */
+	protected $format = '';
+
+
+	/**
+	 * @var array $args
+	 */
+	protected $args = array();
+
+
+
+	/**
+	 * VsprintfFilter constructor.
+	 *
+	 * @param string $format
+	 * @param array  $args
+	 */
+	public function __construct($format, array $args)
+	{
+		$this->format = $format;
+		$this->args   = $args;
+	}
+
+
+
+	/**
+	 * @param                             $html
+	 * @param EE_Form_Section_Validatable $form_section
+	 * @return string
+	 */
+	public function filterHtml($html, EE_Form_Section_Validatable $form_section)
+	{
+		$this->args[] = $html;
+		if ($form_section instanceof EE_Form_Section_Proper) {
+			$subsections = $form_section->subsections();
+			foreach ((array)$subsections as $subsection) {
+				$this->args[] = $subsection->get_html();
+			}
+		}
+		return vsprintf($this->format, $this->args);
+	}