eventespresso / event-espresso-core

core/services/request/CurrentPage.php

Indentation +316 added lines, -316 removed lines

@@ -23,320 +23,320 @@
  */
 class CurrentPage
 {
-    /**
-     * @var EE_CPT_Strategy
-     */
-    private $cpt_strategy;
-
-    /**
-     * @var bool
-     */
-    private $initialized;
-
-    /**
-     * @var bool
-     */
-    private $is_espresso_page;
-
-    /**
-     * @var int
-     */
-    private $post_id = 0;
-
-    /**
-     * @var string|null
-     */
-    private $post_name = '';
-
-    /**
-     * @var array
-     */
-    private $post_type = [];
-
-    /**
-     * @var RequestInterface $request
-     */
-    private $request;
-
-
-    /**
-     * CurrentPage constructor.
-     *
-     * @param EE_CPT_Strategy  $cpt_strategy
-     * @param RequestInterface $request
-     */
-    public function __construct(EE_CPT_Strategy $cpt_strategy, RequestInterface $request)
-    {
-        $this->cpt_strategy = $cpt_strategy;
-        $this->request      = $request;
-        $this->initialized  = is_admin();
-        // analyse the incoming WP request
-        add_action('parse_request', [$this, 'parseQueryVars'], 2, 1);
-    }
-
-
-    /**
-     * @param WP|null $WP
-     * @return void
-     */
-    public function parseQueryVars(WP $WP = null)
-    {
-        if ($this->initialized) {
-            return;
-        }
-        // if somebody forgot to provide us with WP, that's ok because its global
-        if (! $WP instanceof WP) {
-            global $WP;
-        }
-        $this->post_id   = $this->getPostId($WP);
-        $this->post_name = $this->getPostName($WP);
-        $this->post_type = $this->getPostType($WP);
-        // true or false ? is this page being used by EE ?
-        $this->setEspressoPage();
-        remove_action('parse_request', [$this, 'parseRequest'], 2);
-        $this->initialized = true;
-    }
-
-
-    /**
-     * Just a helper method for getting the url for the displayed page.
-     *
-     * @param WP|null $WP
-     * @return string
-     */
-    public function getPermalink(WP $WP = null): string
-    {
-        $post_id = $this->post_id ?: $this->getPostId($WP);
-        if ($post_id) {
-            return get_permalink($post_id);
-        }
-        if (! $WP instanceof WP) {
-            global $WP;
-        }
-        if ($WP instanceof WP && $WP->request) {
-            return site_url($WP->request);
-        }
-        return esc_url_raw(site_url($_SERVER['REQUEST_URI']));
-    }
-
-
-    /**
-     * @return array
-     */
-    public function espressoPostType(): array
-    {
-        return array_filter(
-            $this->post_type,
-            function ($post_type) {
-                return strpos($post_type, 'espresso_') === 0;
-            }
-        );
-    }
-
-
-    /**
-     * pokes and prods the WP object query_vars in an attempt to shake out a page/post ID
-     *
-     * @param WP|null $WP $WP
-     * @return int
-     */
-    private function getPostId(WP $WP = null): ?int
-    {
-        $post_id = 0;
-        if ($WP instanceof WP) {
-            // look for the post ID in the aptly named 'p' query var
-            if (isset($WP->query_vars['p'])) {
-                $post_id = $WP->query_vars['p'];
-            }
-            // not a post? what about a page?
-            if (! $post_id && isset($WP->query_vars['page_id'])) {
-                $post_id = $WP->query_vars['page_id'];
-            }
-            // ok... maybe pretty permalinks are off and the ID is set in the raw request...
-            // but hasn't been processed yet ie: this method is being called too early :\
-            if (! $post_id && $WP->request !== null && is_numeric(basename($WP->request))) {
-                $post_id = basename($WP->request);
-            }
-        }
-        // none of the above? ok what about an explicit "post_id" URL parameter?
-        if (! $post_id && $this->request->requestParamIsSet('post_id')) {
-            $post_id = $this->request->getRequestParam('post_id', 0, DataType::INT);
-        }
-        return (int) $post_id;
-    }
-
-
-    /**
-     * similar to getPostId() above but attempts to obtain the "name" for the current page/post
-     *
-     * @param WP|null $WP $WP
-     * @return string|null
-     */
-    private function getPostName(WP $WP = null): ?string
-    {
-        global $wpdb;
-        $post_name = '';
-        if ($WP instanceof WP) {
-            // if this is a post, then is the post name set?
-            if (isset($WP->query_vars['name']) && ! empty($WP->query_vars['name'])) {
-                $post_name = is_array($WP->query_vars['name']) ? $WP->query_vars['name'][0] : $WP->query_vars['name'];
-            }
-            // what about the page name?
-            if (! $post_name && isset($WP->query_vars['pagename']) && ! empty($WP->query_vars['pagename'])) {
-                $post_name = is_array($WP->query_vars['pagename']) ? $WP->query_vars['pagename'][0]
-                    : $WP->query_vars['pagename'];
-            }
-            // this stinks but let's run a query to try and get the post name from the URL
-            // (assuming pretty permalinks are on)
-            if (! $post_name && ! empty($WP->request)) {
-                $possible_post_name = basename($WP->request);
-                if (! is_numeric($possible_post_name)) {
-                    $SQL                = "SELECT ID from {$wpdb->posts}";
-                    $SQL                .= " WHERE post_status NOT IN ('auto-draft', 'inherit', 'trash')";
-                    $SQL                .= ' AND post_name=%s';
-                    $possible_post_name = $wpdb->get_var($wpdb->prepare($SQL, $possible_post_name));
-                    if ($possible_post_name) {
-                        $post_name = $possible_post_name;
-                    }
-                }
-            }
-        }
-        // ug... ok... nothing yet... but do we have a post ID?
-        // if so then... sigh... run a query to get the post name :\
-        if (! $post_name && $this->post_id) {
-            $SQL                = "SELECT post_name from {$wpdb->posts}";
-            $SQL                .= " WHERE post_status NOT IN ('auto-draft', 'inherit', 'trash')";
-            $SQL                .= ' AND ID=%d';
-            $possible_post_name = $wpdb->get_var($wpdb->prepare($SQL, $this->post_id));
-            if ($possible_post_name) {
-                $post_name = $possible_post_name;
-            }
-        }
-        // still nothing? ok what about an explicit 'post_name' URL parameter?
-        if (! $post_name && $this->request->requestParamIsSet('post_name')) {
-            $post_name = $this->request->getRequestParam('post_name');
-        }
-        return $post_name;
-    }
-
-
-    /**
-     * also similar to getPostId() and getPostName() above but not as insane
-     *
-     * @param WP|null $WP $WP
-     * @return array
-     */
-    private function getPostType(WP $WP = null): array
-    {
-        $post_types = [];
-        if ($WP instanceof WP) {
-            $post_types = isset($WP->query_vars['post_type'])
-                ? (array) $WP->query_vars['post_type']
-                : [];
-        }
-        if (empty($post_types) && $this->request->requestParamIsSet('post_type')) {
-            $post_types = $this->request->getRequestParam('post_type', [], DataType::STRING, true);
-        }
-        return (array) $post_types;
-    }
-
-
-    /**
-     * if TRUE, then the current page is somehow utilizing EE logic
-     *
-     * @return bool
-     */
-    public function isEspressoPage(): bool
-    {
-        if ($this->is_espresso_page === null) {
-            $this->setEspressoPage();
-        }
-        return $this->is_espresso_page;
-    }
-
-
-    /**
-     * @return int
-     */
-    public function postId(): int
-    {
-        return $this->post_id;
-    }
-
-
-    /**
-     * @return string|null
-     */
-    public function postName(): ?string
-    {
-        return $this->post_name;
-    }
-
-
-    /**
-     * @return array
-     */
-    public function postType(): array
-    {
-        return $this->post_type;
-    }
-
-
-    /**
-     * for manually indicating the current page will utilize EE logic
-     *
-     * @param bool|int|string|null $value
-     * @return void
-     */
-    public function setEspressoPage($value = null)
-    {
-        $this->is_espresso_page = $value !== null
-            ? filter_var($value, FILTER_VALIDATE_BOOLEAN)
-            : $this->testForEspressoPage();
-    }
-
-
-    /**
-     * attempts to determine if the current page/post is an EE related page/post
-     * because it utilizes one of our CPT taxonomies, endpoints, or post types
-     *
-     * @return bool
-     */
-    private function testForEspressoPage(): bool
-    {
-        // in case it has already been set
-        if ($this->is_espresso_page) {
-            return true;
-        }
-        global $WP;
-        $espresso_CPT_taxonomies = $this->cpt_strategy->get_CPT_taxonomies();
-        if (is_array($espresso_CPT_taxonomies)) {
-            foreach ($espresso_CPT_taxonomies as $espresso_CPT_taxonomy => $details) {
-                if (isset($WP->query_vars, $WP->query_vars[ $espresso_CPT_taxonomy ])) {
-                    return true;
-                }
-            }
-        }
-        // load espresso CPT endpoints
-        $espresso_CPT_endpoints  = $this->cpt_strategy->get_CPT_endpoints();
-        $post_type_CPT_endpoints = array_flip($espresso_CPT_endpoints);
-        foreach ($this->post_type as $post_type) {
-            // was a post name passed ?
-            if (isset($post_type_CPT_endpoints[ $post_type ])) {
-                // kk we know this is an espresso page, but is it a specific post ?
-                if (! $this->post_name) {
-                    $espresso_post_type = $this->request->getRequestParam('post_type');
-                    // there's no specific post name set, so maybe it's one of our endpoints like www.domain.com/events
-                    // this essentially sets the post_name to "events" (or whatever EE CPT)
-                    $post_name = $post_type_CPT_endpoints[ $espresso_post_type ] ?? '';
-                    // if the post type matches one of ours then set the post name to the endpoint
-                    if ($post_name) {
-                        $this->post_name = $post_name;
-                    }
-                }
-                return true;
-            }
-        }
-        return false;
-    }
+	/**
+	 * @var EE_CPT_Strategy
+	 */
+	private $cpt_strategy;
+
+	/**
+	 * @var bool
+	 */
+	private $initialized;
+
+	/**
+	 * @var bool
+	 */
+	private $is_espresso_page;
+
+	/**
+	 * @var int
+	 */
+	private $post_id = 0;
+
+	/**
+	 * @var string|null
+	 */
+	private $post_name = '';
+
+	/**
+	 * @var array
+	 */
+	private $post_type = [];
+
+	/**
+	 * @var RequestInterface $request
+	 */
+	private $request;
+
+
+	/**
+	 * CurrentPage constructor.
+	 *
+	 * @param EE_CPT_Strategy  $cpt_strategy
+	 * @param RequestInterface $request
+	 */
+	public function __construct(EE_CPT_Strategy $cpt_strategy, RequestInterface $request)
+	{
+		$this->cpt_strategy = $cpt_strategy;
+		$this->request      = $request;
+		$this->initialized  = is_admin();
+		// analyse the incoming WP request
+		add_action('parse_request', [$this, 'parseQueryVars'], 2, 1);
+	}
+
+
+	/**
+	 * @param WP|null $WP
+	 * @return void
+	 */
+	public function parseQueryVars(WP $WP = null)
+	{
+		if ($this->initialized) {
+			return;
+		}
+		// if somebody forgot to provide us with WP, that's ok because its global
+		if (! $WP instanceof WP) {
+			global $WP;
+		}
+		$this->post_id   = $this->getPostId($WP);
+		$this->post_name = $this->getPostName($WP);
+		$this->post_type = $this->getPostType($WP);
+		// true or false ? is this page being used by EE ?
+		$this->setEspressoPage();
+		remove_action('parse_request', [$this, 'parseRequest'], 2);
+		$this->initialized = true;
+	}
+
+
+	/**
+	 * Just a helper method for getting the url for the displayed page.
+	 *
+	 * @param WP|null $WP
+	 * @return string
+	 */
+	public function getPermalink(WP $WP = null): string
+	{
+		$post_id = $this->post_id ?: $this->getPostId($WP);
+		if ($post_id) {
+			return get_permalink($post_id);
+		}
+		if (! $WP instanceof WP) {
+			global $WP;
+		}
+		if ($WP instanceof WP && $WP->request) {
+			return site_url($WP->request);
+		}
+		return esc_url_raw(site_url($_SERVER['REQUEST_URI']));
+	}
+
+
+	/**
+	 * @return array
+	 */
+	public function espressoPostType(): array
+	{
+		return array_filter(
+			$this->post_type,
+			function ($post_type) {
+				return strpos($post_type, 'espresso_') === 0;
+			}
+		);
+	}
+
+
+	/**
+	 * pokes and prods the WP object query_vars in an attempt to shake out a page/post ID
+	 *
+	 * @param WP|null $WP $WP
+	 * @return int
+	 */
+	private function getPostId(WP $WP = null): ?int
+	{
+		$post_id = 0;
+		if ($WP instanceof WP) {
+			// look for the post ID in the aptly named 'p' query var
+			if (isset($WP->query_vars['p'])) {
+				$post_id = $WP->query_vars['p'];
+			}
+			// not a post? what about a page?
+			if (! $post_id && isset($WP->query_vars['page_id'])) {
+				$post_id = $WP->query_vars['page_id'];
+			}
+			// ok... maybe pretty permalinks are off and the ID is set in the raw request...
+			// but hasn't been processed yet ie: this method is being called too early :\
+			if (! $post_id && $WP->request !== null && is_numeric(basename($WP->request))) {
+				$post_id = basename($WP->request);
+			}
+		}
+		// none of the above? ok what about an explicit "post_id" URL parameter?
+		if (! $post_id && $this->request->requestParamIsSet('post_id')) {
+			$post_id = $this->request->getRequestParam('post_id', 0, DataType::INT);
+		}
+		return (int) $post_id;
+	}
+
+
+	/**
+	 * similar to getPostId() above but attempts to obtain the "name" for the current page/post
+	 *
+	 * @param WP|null $WP $WP
+	 * @return string|null
+	 */
+	private function getPostName(WP $WP = null): ?string
+	{
+		global $wpdb;
+		$post_name = '';
+		if ($WP instanceof WP) {
+			// if this is a post, then is the post name set?
+			if (isset($WP->query_vars['name']) && ! empty($WP->query_vars['name'])) {
+				$post_name = is_array($WP->query_vars['name']) ? $WP->query_vars['name'][0] : $WP->query_vars['name'];
+			}
+			// what about the page name?
+			if (! $post_name && isset($WP->query_vars['pagename']) && ! empty($WP->query_vars['pagename'])) {
+				$post_name = is_array($WP->query_vars['pagename']) ? $WP->query_vars['pagename'][0]
+					: $WP->query_vars['pagename'];
+			}
+			// this stinks but let's run a query to try and get the post name from the URL
+			// (assuming pretty permalinks are on)
+			if (! $post_name && ! empty($WP->request)) {
+				$possible_post_name = basename($WP->request);
+				if (! is_numeric($possible_post_name)) {
+					$SQL                = "SELECT ID from {$wpdb->posts}";
+					$SQL                .= " WHERE post_status NOT IN ('auto-draft', 'inherit', 'trash')";
+					$SQL                .= ' AND post_name=%s';
+					$possible_post_name = $wpdb->get_var($wpdb->prepare($SQL, $possible_post_name));
+					if ($possible_post_name) {
+						$post_name = $possible_post_name;
+					}
+				}
+			}
+		}
+		// ug... ok... nothing yet... but do we have a post ID?
+		// if so then... sigh... run a query to get the post name :\
+		if (! $post_name && $this->post_id) {
+			$SQL                = "SELECT post_name from {$wpdb->posts}";
+			$SQL                .= " WHERE post_status NOT IN ('auto-draft', 'inherit', 'trash')";
+			$SQL                .= ' AND ID=%d';
+			$possible_post_name = $wpdb->get_var($wpdb->prepare($SQL, $this->post_id));
+			if ($possible_post_name) {
+				$post_name = $possible_post_name;
+			}
+		}
+		// still nothing? ok what about an explicit 'post_name' URL parameter?
+		if (! $post_name && $this->request->requestParamIsSet('post_name')) {
+			$post_name = $this->request->getRequestParam('post_name');
+		}
+		return $post_name;
+	}
+
+
+	/**
+	 * also similar to getPostId() and getPostName() above but not as insane
+	 *
+	 * @param WP|null $WP $WP
+	 * @return array
+	 */
+	private function getPostType(WP $WP = null): array
+	{
+		$post_types = [];
+		if ($WP instanceof WP) {
+			$post_types = isset($WP->query_vars['post_type'])
+				? (array) $WP->query_vars['post_type']
+				: [];
+		}
+		if (empty($post_types) && $this->request->requestParamIsSet('post_type')) {
+			$post_types = $this->request->getRequestParam('post_type', [], DataType::STRING, true);
+		}
+		return (array) $post_types;
+	}
+
+
+	/**
+	 * if TRUE, then the current page is somehow utilizing EE logic
+	 *
+	 * @return bool
+	 */
+	public function isEspressoPage(): bool
+	{
+		if ($this->is_espresso_page === null) {
+			$this->setEspressoPage();
+		}
+		return $this->is_espresso_page;
+	}
+
+
+	/**
+	 * @return int
+	 */
+	public function postId(): int
+	{
+		return $this->post_id;
+	}
+
+
+	/**
+	 * @return string|null
+	 */
+	public function postName(): ?string
+	{
+		return $this->post_name;
+	}
+
+
+	/**
+	 * @return array
+	 */
+	public function postType(): array
+	{
+		return $this->post_type;
+	}
+
+
+	/**
+	 * for manually indicating the current page will utilize EE logic
+	 *
+	 * @param bool|int|string|null $value
+	 * @return void
+	 */
+	public function setEspressoPage($value = null)
+	{
+		$this->is_espresso_page = $value !== null
+			? filter_var($value, FILTER_VALIDATE_BOOLEAN)
+			: $this->testForEspressoPage();
+	}
+
+
+	/**
+	 * attempts to determine if the current page/post is an EE related page/post
+	 * because it utilizes one of our CPT taxonomies, endpoints, or post types
+	 *
+	 * @return bool
+	 */
+	private function testForEspressoPage(): bool
+	{
+		// in case it has already been set
+		if ($this->is_espresso_page) {
+			return true;
+		}
+		global $WP;
+		$espresso_CPT_taxonomies = $this->cpt_strategy->get_CPT_taxonomies();
+		if (is_array($espresso_CPT_taxonomies)) {
+			foreach ($espresso_CPT_taxonomies as $espresso_CPT_taxonomy => $details) {
+				if (isset($WP->query_vars, $WP->query_vars[ $espresso_CPT_taxonomy ])) {
+					return true;
+				}
+			}
+		}
+		// load espresso CPT endpoints
+		$espresso_CPT_endpoints  = $this->cpt_strategy->get_CPT_endpoints();
+		$post_type_CPT_endpoints = array_flip($espresso_CPT_endpoints);
+		foreach ($this->post_type as $post_type) {
+			// was a post name passed ?
+			if (isset($post_type_CPT_endpoints[ $post_type ])) {
+				// kk we know this is an espresso page, but is it a specific post ?
+				if (! $this->post_name) {
+					$espresso_post_type = $this->request->getRequestParam('post_type');
+					// there's no specific post name set, so maybe it's one of our endpoints like www.domain.com/events
+					// this essentially sets the post_name to "events" (or whatever EE CPT)
+					$post_name = $post_type_CPT_endpoints[ $espresso_post_type ] ?? '';
+					// if the post type matches one of ours then set the post name to the endpoint
+					if ($post_name) {
+						$this->post_name = $post_name;
+					}
+				}
+				return true;
+			}
+		}
+		return false;
+	}
 }

core/services/converters/date_time_formats/PhpToUnicode.php

Indentation +87 added lines, -87 removed lines

@@ -4,99 +4,99 @@
 
 class PhpToUnicode
 {
-    /**
-     * array where keys are PHP date format parameters
-     * and values are Unicode Date Format substitutions
-     */
-    public static array $date_formats = [
-        // YEAR
-        'y'  => 'yy',    // 00, 01, ..., 99
-        'Y'  => 'yyyy',  // 2000, 2001, ..., 2099
-        'o'  => 'GGGG',  // ISO "week-numbering year" 2000, 2001, ..., 2099
-        // MONTH
-        'M'  => 'MMM',   // Jan, Feb, ..., Dec
-        'n'  => 'M',     // 1, 2, ..., 12
-        'm'  => 'MM',    // 01, 02, ..., 12
-        'F'  => 'MMMM',  // January, February, ..., December
-        // DAY
-        'd'  => 'dd',    // 01, 02, ..., 31
-        'D'  => 'eee',   // Sun, Mon, ..., Sat
-        'jS' => 'do',   // 1st, 2nd, ..., 31st
-        'j'  => 'd',     // 1, 2, ..., 31
-        'l'  => 'eeee',  // Sunday, Monday, ..., Saturday
-        'N'  => 'e',     // Day of week 0, 1, ..., 6
-        'w'  => 'i',     // ISO Day of week 1, 2, ..., 7
-        'z'  => 'D',   // day of the year 0 - 365 to 1 - 366
-        // WEEK
-        'W'  => 'w',
-        // CHARACTERS
-        '|'  => '',
-    ];
+	/**
+	 * array where keys are PHP date format parameters
+	 * and values are Unicode Date Format substitutions
+	 */
+	public static array $date_formats = [
+		// YEAR
+		'y'  => 'yy',    // 00, 01, ..., 99
+		'Y'  => 'yyyy',  // 2000, 2001, ..., 2099
+		'o'  => 'GGGG',  // ISO "week-numbering year" 2000, 2001, ..., 2099
+		// MONTH
+		'M'  => 'MMM',   // Jan, Feb, ..., Dec
+		'n'  => 'M',     // 1, 2, ..., 12
+		'm'  => 'MM',    // 01, 02, ..., 12
+		'F'  => 'MMMM',  // January, February, ..., December
+		// DAY
+		'd'  => 'dd',    // 01, 02, ..., 31
+		'D'  => 'eee',   // Sun, Mon, ..., Sat
+		'jS' => 'do',   // 1st, 2nd, ..., 31st
+		'j'  => 'd',     // 1, 2, ..., 31
+		'l'  => 'eeee',  // Sunday, Monday, ..., Saturday
+		'N'  => 'e',     // Day of week 0, 1, ..., 6
+		'w'  => 'i',     // ISO Day of week 1, 2, ..., 7
+		'z'  => 'D',   // day of the year 0 - 365 to 1 - 366
+		// WEEK
+		'W'  => 'w',
+		// CHARACTERS
+		'|'  => '',
+	];
 
 
-    /**
-     * array where keys are PHP time format parameters
-     * and values are Unicode Time Format substitutions
-     */
-    public static array $time_formats = [
-        // 'a' => 'a', // am, pm, no specific JS alternative
-        'A' => 'a', // AM, PM
-        // HOUR
-        // convert "g" to an intermediary format
-        // to avoid its result getting replaced by "h"
-        'g' => '@',     // 1, 2, ..., 12
-        'h' => 'hh',    // 01, 02, ..., 12
-        '@' => 'h',     // 1, 2, ..., 12
-        'G' => '#',     // 0, 1, ... 23
-        'H' => 'HH',    // 00, 01, ... 23
-        '#' => 'H',     // 0, 1, ... 23
-        // MINUTES & SECONDS
-        'i' => 'mm',    // minutes 00, 01, ..., 59
-        's' => 'ss',    // seconds 00, 01, ..., 59
-        'v' => 'SSS',   // milliseconds 000, 001, ..., 999
-        'u' => 'SSS',   // microseconds (not in unicode) 000, 001, ..., 999
-    ];
+	/**
+	 * array where keys are PHP time format parameters
+	 * and values are Unicode Time Format substitutions
+	 */
+	public static array $time_formats = [
+		// 'a' => 'a', // am, pm, no specific JS alternative
+		'A' => 'a', // AM, PM
+		// HOUR
+		// convert "g" to an intermediary format
+		// to avoid its result getting replaced by "h"
+		'g' => '@',     // 1, 2, ..., 12
+		'h' => 'hh',    // 01, 02, ..., 12
+		'@' => 'h',     // 1, 2, ..., 12
+		'G' => '#',     // 0, 1, ... 23
+		'H' => 'HH',    // 00, 01, ... 23
+		'#' => 'H',     // 0, 1, ... 23
+		// MINUTES & SECONDS
+		'i' => 'mm',    // minutes 00, 01, ..., 59
+		's' => 'ss',    // seconds 00, 01, ..., 59
+		'v' => 'SSS',   // milliseconds 000, 001, ..., 999
+		'u' => 'SSS',   // microseconds (not in unicode) 000, 001, ..., 999
+	];
 
 
-    /**
-     * array where keys are PHP timezone format parameters
-     * and values are Unicode Timezone Format substitutions
-     */
-    public static array $timezone_formats = [
-        'Z' => 'xx',    // -0100, +0000, ..., +1200
-        'e' => 'xxx',     // Timezone identifier UTC, GMT, Atlantic/Azores to -01:00, +00:00, ... +12:00
-        'T' => 'xxx',     // Timezone abbreviation EST, MDT to -01:00, +00:00, ... +12:00
-        'P' => 'xxx',     // -01:00, +00:00, ... +12:00
-        'O' => 'xx',    // -0100, +0000, ..., +1200
-    ];
+	/**
+	 * array where keys are PHP timezone format parameters
+	 * and values are Unicode Timezone Format substitutions
+	 */
+	public static array $timezone_formats = [
+		'Z' => 'xx',    // -0100, +0000, ..., +1200
+		'e' => 'xxx',     // Timezone identifier UTC, GMT, Atlantic/Azores to -01:00, +00:00, ... +12:00
+		'T' => 'xxx',     // Timezone abbreviation EST, MDT to -01:00, +00:00, ... +12:00
+		'P' => 'xxx',     // -01:00, +00:00, ... +12:00
+		'O' => 'xx',    // -0100, +0000, ..., +1200
+	];
 
 
-    /**
-     * @param string $date_format
-     * @return string
-     */
-    public function convertDateFormat(string $date_format): string
-    {
-        foreach (PhpToUnicode::$date_formats as $find => $replace) {
-            $date_format = (string) str_replace($find, $replace, $date_format);
-        }
-        return trim($date_format);
-    }
+	/**
+	 * @param string $date_format
+	 * @return string
+	 */
+	public function convertDateFormat(string $date_format): string
+	{
+		foreach (PhpToUnicode::$date_formats as $find => $replace) {
+			$date_format = (string) str_replace($find, $replace, $date_format);
+		}
+		return trim($date_format);
+	}
 
 
-    /**
-     * @param string $time_format
-     * @return string
-     */
-    public function convertTimeFormat(string $time_format): string
-    {
-        foreach (PhpToUnicode::$time_formats as $find => $replace) {
-            $time_format = (string) str_replace($find, $replace, $time_format);
-        }
-        // and just in case the timezone has been added
-        foreach (PhpToUnicode::$timezone_formats as $find => $replace) {
-            $time_format = (string) str_replace($find, $replace, $time_format);
-        }
-        return trim($time_format);
-    }
+	/**
+	 * @param string $time_format
+	 * @return string
+	 */
+	public function convertTimeFormat(string $time_format): string
+	{
+		foreach (PhpToUnicode::$time_formats as $find => $replace) {
+			$time_format = (string) str_replace($find, $replace, $time_format);
+		}
+		// and just in case the timezone has been added
+		foreach (PhpToUnicode::$timezone_formats as $find => $replace) {
+			$time_format = (string) str_replace($find, $replace, $time_format);
+		}
+		return trim($time_format);
+	}
 }

Spacing +30 added lines, -30 removed lines

@@ -10,23 +10,23 @@ 
      */
     public static array $date_formats = [
         // YEAR
-        'y'  => 'yy',    // 00, 01, ..., 99
-        'Y'  => 'yyyy',  // 2000, 2001, ..., 2099
-        'o'  => 'GGGG',  // ISO "week-numbering year" 2000, 2001, ..., 2099
+        'y'  => 'yy', // 00, 01, ..., 99
+        'Y'  => 'yyyy', // 2000, 2001, ..., 2099
+        'o'  => 'GGGG', // ISO "week-numbering year" 2000, 2001, ..., 2099
         // MONTH
-        'M'  => 'MMM',   // Jan, Feb, ..., Dec
-        'n'  => 'M',     // 1, 2, ..., 12
-        'm'  => 'MM',    // 01, 02, ..., 12
-        'F'  => 'MMMM',  // January, February, ..., December
+        'M'  => 'MMM', // Jan, Feb, ..., Dec
+        'n'  => 'M', // 1, 2, ..., 12
+        'm'  => 'MM', // 01, 02, ..., 12
+        'F'  => 'MMMM', // January, February, ..., December
         // DAY
-        'd'  => 'dd',    // 01, 02, ..., 31
-        'D'  => 'eee',   // Sun, Mon, ..., Sat
-        'jS' => 'do',   // 1st, 2nd, ..., 31st
-        'j'  => 'd',     // 1, 2, ..., 31
-        'l'  => 'eeee',  // Sunday, Monday, ..., Saturday
-        'N'  => 'e',     // Day of week 0, 1, ..., 6
-        'w'  => 'i',     // ISO Day of week 1, 2, ..., 7
-        'z'  => 'D',   // day of the year 0 - 365 to 1 - 366
+        'd'  => 'dd', // 01, 02, ..., 31
+        'D'  => 'eee', // Sun, Mon, ..., Sat
+        'jS' => 'do', // 1st, 2nd, ..., 31st
+        'j'  => 'd', // 1, 2, ..., 31
+        'l'  => 'eeee', // Sunday, Monday, ..., Saturday
+        'N'  => 'e', // Day of week 0, 1, ..., 6
+        'w'  => 'i', // ISO Day of week 1, 2, ..., 7
+        'z'  => 'D', // day of the year 0 - 365 to 1 - 366
         // WEEK
         'W'  => 'w',
         // CHARACTERS
@@ -44,17 +44,17 @@ 
         // HOUR
         // convert "g" to an intermediary format
         // to avoid its result getting replaced by "h"
-        'g' => '@',     // 1, 2, ..., 12
-        'h' => 'hh',    // 01, 02, ..., 12
-        '@' => 'h',     // 1, 2, ..., 12
-        'G' => '#',     // 0, 1, ... 23
-        'H' => 'HH',    // 00, 01, ... 23
-        '#' => 'H',     // 0, 1, ... 23
+        'g' => '@', // 1, 2, ..., 12
+        'h' => 'hh', // 01, 02, ..., 12
+        '@' => 'h', // 1, 2, ..., 12
+        'G' => '#', // 0, 1, ... 23
+        'H' => 'HH', // 00, 01, ... 23
+        '#' => 'H', // 0, 1, ... 23
         // MINUTES & SECONDS
-        'i' => 'mm',    // minutes 00, 01, ..., 59
-        's' => 'ss',    // seconds 00, 01, ..., 59
-        'v' => 'SSS',   // milliseconds 000, 001, ..., 999
-        'u' => 'SSS',   // microseconds (not in unicode) 000, 001, ..., 999
+        'i' => 'mm', // minutes 00, 01, ..., 59
+        's' => 'ss', // seconds 00, 01, ..., 59
+        'v' => 'SSS', // milliseconds 000, 001, ..., 999
+        'u' => 'SSS', // microseconds (not in unicode) 000, 001, ..., 999
     ];
 
 
@@ -63,11 +63,11 @@ 
      * and values are Unicode Timezone Format substitutions
      */
     public static array $timezone_formats = [
-        'Z' => 'xx',    // -0100, +0000, ..., +1200
-        'e' => 'xxx',     // Timezone identifier UTC, GMT, Atlantic/Azores to -01:00, +00:00, ... +12:00
-        'T' => 'xxx',     // Timezone abbreviation EST, MDT to -01:00, +00:00, ... +12:00
-        'P' => 'xxx',     // -01:00, +00:00, ... +12:00
-        'O' => 'xx',    // -0100, +0000, ..., +1200
+        'Z' => 'xx', // -0100, +0000, ..., +1200
+        'e' => 'xxx', // Timezone identifier UTC, GMT, Atlantic/Azores to -01:00, +00:00, ... +12:00
+        'T' => 'xxx', // Timezone abbreviation EST, MDT to -01:00, +00:00, ... +12:00
+        'P' => 'xxx', // -01:00, +00:00, ... +12:00
+        'O' => 'xx', // -0100, +0000, ..., +1200
     ];
 
 

core/services/admin/AdminListTableFilters.php

Indentation +105 added lines, -105 removed lines

@@ -12,74 +12,74 @@ 
  */
 class AdminListTableFilters
 {
-    /**
-     * @var RequestInterface
-     */
-    protected RequestInterface $request;
-
-    protected string           $search_term;
-
-    protected ?string          $orderby;
-
-    protected ?string          $order;
-
-    protected ?string          $detached;
-
-    protected ?string          $post_mime_type;
-
-
-    public function __construct(RequestInterface $request)
-    {
-        $this->request = $request;
-        // add_action('admin_enqueue_scripts', [$this, 'loadScriptsStyles']);
-    }
-
-
-    public function loadScriptsStyles()
-    {
-        wp_enqueue_script(EspressoLegacyAdminAssetManager::JS_HANDLE_EE_ADMIN);
-    }
-
-
-    /**
-     * Sets the parameters from request
-     *
-     * @return void
-     */
-    private function setRequestParams(): void
-    {
-        $this->search_term    = $this->request->getRequestParam('s', '');
-        $this->orderby        = $this->request->getRequestParam('orderby');
-        $this->order          = $this->request->getRequestParam('order');
-        $this->post_mime_type = $this->request->getRequestParam('post_mime_type');
-        $this->detached       = $this->request->getRequestParam('detached');
-    }
-
-
-    /**
-     * Displays the search box with reset button
-     *
-     * @param string $text     The 'submit' button label.
-     * @param string $input_id ID attribute value for the search input field.
-     * @param string $url      Reset URL
-     * @return void
-     */
-    public function searchBox(string $text, string $input_id, string $url): void
-    {
-        $this->setRequestParams();
-        if (! empty($this->orderby)) {
-            echo '<input type="hidden" name="orderby" value="' . esc_attr($this->orderby) . '" />';
-        }
-        if (! empty($this->order)) {
-            echo '<input type="hidden" name="order" value="' . esc_attr($this->order) . '" />';
-        }
-        if (! empty($this->post_mime_type)) {
-            echo '<input type="hidden" name="post_mime_type" value="' . esc_attr($this->post_mime_type) . '" />';
-        }
-        if (! empty($this->detached)) {
-            echo '<input type="hidden" name="detached" value="' . esc_attr($this->detached) . '" />';
-        }
-        ?>
+	/**
+	 * @var RequestInterface
+	 */
+	protected RequestInterface $request;
+
+	protected string           $search_term;
+
+	protected ?string          $orderby;
+
+	protected ?string          $order;
+
+	protected ?string          $detached;
+
+	protected ?string          $post_mime_type;
+
+
+	public function __construct(RequestInterface $request)
+	{
+		$this->request = $request;
+		// add_action('admin_enqueue_scripts', [$this, 'loadScriptsStyles']);
+	}
+
+
+	public function loadScriptsStyles()
+	{
+		wp_enqueue_script(EspressoLegacyAdminAssetManager::JS_HANDLE_EE_ADMIN);
+	}
+
+
+	/**
+	 * Sets the parameters from request
+	 *
+	 * @return void
+	 */
+	private function setRequestParams(): void
+	{
+		$this->search_term    = $this->request->getRequestParam('s', '');
+		$this->orderby        = $this->request->getRequestParam('orderby');
+		$this->order          = $this->request->getRequestParam('order');
+		$this->post_mime_type = $this->request->getRequestParam('post_mime_type');
+		$this->detached       = $this->request->getRequestParam('detached');
+	}
+
+
+	/**
+	 * Displays the search box with reset button
+	 *
+	 * @param string $text     The 'submit' button label.
+	 * @param string $input_id ID attribute value for the search input field.
+	 * @param string $url      Reset URL
+	 * @return void
+	 */
+	public function searchBox(string $text, string $input_id, string $url): void
+	{
+		$this->setRequestParams();
+		if (! empty($this->orderby)) {
+			echo '<input type="hidden" name="orderby" value="' . esc_attr($this->orderby) . '" />';
+		}
+		if (! empty($this->order)) {
+			echo '<input type="hidden" name="order" value="' . esc_attr($this->order) . '" />';
+		}
+		if (! empty($this->post_mime_type)) {
+			echo '<input type="hidden" name="post_mime_type" value="' . esc_attr($this->post_mime_type) . '" />';
+		}
+		if (! empty($this->detached)) {
+			echo '<input type="hidden" name="detached" value="' . esc_attr($this->detached) . '" />';
+		}
+		?>
         <p class="search-box">
             <label class="screen-reader-text" for="<?php echo esc_attr($input_id); ?>"><?php echo $text; ?>:</label>
             <input type="search"
@@ -94,36 +94,36 @@ 
             </button>
             <?php //submit_button($text, '', '', false, ['id' => 'search-submit']); ?>
             <?php
-            if (! empty($this->search_term)) {
-                echo wp_kses($this->generateResetButton($url), AllowedTags::getAllowedTags());
-            }
-            ?>
+			if (! empty($this->search_term)) {
+				echo wp_kses($this->generateResetButton($url), AllowedTags::getAllowedTags());
+			}
+			?>
         </p>
         <?php
-    }
-
-
-    /**
-     * filters
-     * This receives the filters array from children _get_table_filters() and assembles the string including the filter
-     * button.
-     *
-     * @param string[] $filters
-     * @param string   $url Reset URL
-     * @return void  echos html showing filters
-     */
-    public function filters(array $filters, string $url): void
-    {
-        $use_filters = $this->request->getRequestParam('use_filters', false, DataType::BOOL);
-        $use_filters = $use_filters ? 'yes' : 'no';
-
-        $filters_html = '';
-        foreach ($filters as $filter) {
-            $filters_html .= wp_kses($filter, AllowedTags::getWithFormTags());
-        }
-        $filter_submit_btn_text = esc_html__('Filter', 'event_espresso');
-
-        echo "
+	}
+
+
+	/**
+	 * filters
+	 * This receives the filters array from children _get_table_filters() and assembles the string including the filter
+	 * button.
+	 *
+	 * @param string[] $filters
+	 * @param string   $url Reset URL
+	 * @return void  echos html showing filters
+	 */
+	public function filters(array $filters, string $url): void
+	{
+		$use_filters = $this->request->getRequestParam('use_filters', false, DataType::BOOL);
+		$use_filters = $use_filters ? 'yes' : 'no';
+
+		$filters_html = '';
+		foreach ($filters as $filter) {
+			$filters_html .= wp_kses($filter, AllowedTags::getWithFormTags());
+		}
+		$filter_submit_btn_text = esc_html__('Filter', 'event_espresso');
+
+		echo "
         <div id='ee-list-table-filters-dv' class='ee-list-table-filters actions alignleft'>
            $filters_html
             <span class='ee-list-table-filters__submit-buttons'>
@@ -146,20 +146,20 @@ 
             <span class='ee-list-table-filters-toggle-text'>" . esc_html__('show filters', 'event_espresso') . "</span>
         </button>
         ";
-    }
+	}
 
 
-    /**
-     * @param string $url Reset URL
-     * @return string
-     */
-    private function generateResetButton(string $url): string
-    {
-        return '<a class="ee-aria-tooltip button button--icon-only"
+	/**
+	 * @param string $url Reset URL
+	 * @return string
+	 */
+	private function generateResetButton(string $url): string
+	{
+		return '<a class="ee-aria-tooltip button button--icon-only"
             href="' . esc_url_raw($url) . '"
             aria-label="' . esc_attr__('Reset Filters', 'event_espresso') . '"
         >
             <span class="dashicons dashicons-update"></span>
         </a>';
-    }
+	}
 }

Spacing +15 added lines, -15 removed lines

@@ -67,17 +67,17 @@ 
     public function searchBox(string $text, string $input_id, string $url): void
     {
         $this->setRequestParams();
-        if (! empty($this->orderby)) {
-            echo '<input type="hidden" name="orderby" value="' . esc_attr($this->orderby) . '" />';
+        if ( ! empty($this->orderby)) {
+            echo '<input type="hidden" name="orderby" value="'.esc_attr($this->orderby).'" />';
         }
-        if (! empty($this->order)) {
-            echo '<input type="hidden" name="order" value="' . esc_attr($this->order) . '" />';
+        if ( ! empty($this->order)) {
+            echo '<input type="hidden" name="order" value="'.esc_attr($this->order).'" />';
         }
-        if (! empty($this->post_mime_type)) {
-            echo '<input type="hidden" name="post_mime_type" value="' . esc_attr($this->post_mime_type) . '" />';
+        if ( ! empty($this->post_mime_type)) {
+            echo '<input type="hidden" name="post_mime_type" value="'.esc_attr($this->post_mime_type).'" />';
         }
-        if (! empty($this->detached)) {
-            echo '<input type="hidden" name="detached" value="' . esc_attr($this->detached) . '" />';
+        if ( ! empty($this->detached)) {
+            echo '<input type="hidden" name="detached" value="'.esc_attr($this->detached).'" />';
         }
         ?>
         <p class="search-box">
@@ -94,7 +94,7 @@ 
             </button>
             <?php //submit_button($text, '', '', false, ['id' => 'search-submit']); ?>
             <?php
-            if (! empty($this->search_term)) {
+            if ( ! empty($this->search_term)) {
                 echo wp_kses($this->generateResetButton($url), AllowedTags::getAllowedTags());
             }
             ?>
@@ -133,17 +133,17 @@ 
                        value='$filter_submit_btn_text'
                 />
                 <input type='hidden' id='ee-list-table-use-filters' name='use_filters' value='$use_filters' />
-                " . wp_kses($this->generateResetButton($url), AllowedTags::getAllowedTags()) . "
+                ".wp_kses($this->generateResetButton($url), AllowedTags::getAllowedTags())."
             </span>
         </div>
         <button id='ee-list-table-filters-toggle'
             class='button button--secondary button--small'
             data-target='ee-list-table-filters'
-            data-hide-text='" . esc_html__('hide filters', 'event_espresso') . "'
-            data-show-text='" . esc_html__('show filters', 'event_espresso') . "'
+            data-hide-text='" . esc_html__('hide filters', 'event_espresso')."'
+            data-show-text='" . esc_html__('show filters', 'event_espresso')."'
         >
             <span class='dashicons dashicons-filter'></span>
-            <span class='ee-list-table-filters-toggle-text'>" . esc_html__('show filters', 'event_espresso') . "</span>
+            <span class='ee-list-table-filters-toggle-text'>" . esc_html__('show filters', 'event_espresso')."</span>
         </button>
         ";
     }
@@ -156,8 +156,8 @@ 
     private function generateResetButton(string $url): string
     {
         return '<a class="ee-aria-tooltip button button--icon-only"
-            href="' . esc_url_raw($url) . '"
-            aria-label="' . esc_attr__('Reset Filters', 'event_espresso') . '"
+            href="' . esc_url_raw($url).'"
+            aria-label="' . esc_attr__('Reset Filters', 'event_espresso').'"
         >
             <span class="dashicons dashicons-update"></span>
         </a>';

core/services/routing/Router.php

Indentation +225 added lines, -225 removed lines

@@ -14,229 +14,229 @@
  */
 class Router
 {
-    protected EE_Dependency_Map $dependency_map;
-
-    protected LoaderInterface   $loader;
-
-    protected RouteHandler      $route_handler;
-
-    protected string            $route_request_type;
-
-    protected array             $routes_loaded;
-
-
-    /**
-     * RoutingSwitch constructor.
-     *
-     * @param EE_Dependency_Map $dependency_map
-     * @param LoaderInterface   $loader
-     * @param RouteHandler      $router
-     */
-    public function __construct(EE_Dependency_Map $dependency_map, LoaderInterface $loader, RouteHandler $router)
-    {
-        $this->dependency_map = $dependency_map;
-        $this->loader         = $loader;
-        $this->route_handler  = $router;
-    }
-
-
-    /**
-     * @throws Exception
-     */
-    public function loadPrimaryRoutes()
-    {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
-            return;
-        }
-        $this->dependency_map->registerDependencies(
-            'EventEspresso\core\domain\entities\routing\handlers\admin\ActivationRequests',
-            Route::getFullDependencies()
-        );
-        $this->dependency_map->registerDependencies(
-            'EventEspresso\core\domain\entities\routing\handlers\shared\RegularRequests',
-            Route::getFullDependencies()
-        );
-        // now load and prep all primary Routes
-        $this->route_handler->addRoute('EventEspresso\core\domain\entities\routing\handlers\admin\ActivationRequests');
-        $this->route_handler->addRoute('EventEspresso\core\domain\entities\routing\handlers\shared\RegularRequests');
-        $this->route_request_type = $this->route_handler->getRouteRequestType();
-        do_action(
-            'AHEE__EventEspresso_core_services_routing_Router__loadPrimaryRoutes',
-            $this->route_handler,
-            $this->route_request_type,
-            $this->dependency_map
-        );
-        $this->routes_loaded[ __FUNCTION__ ] = true;
-    }
-
-
-    /**
-     * @throws Exception
-     */
-    public function registerShortcodesModulesAndWidgets()
-    {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
-            return;
-        }
-        do_action(
-            'AHEE__EventEspresso_core_services_routing_Router__registerShortcodesModulesAndWidgets',
-            $this->route_handler,
-            $this->route_request_type,
-            $this->dependency_map
-        );
-        switch ($this->route_request_type) {
-            case PrimaryRoute::ROUTE_REQUEST_TYPE_ACTIVATION:
-                break;
-            case PrimaryRoute::ROUTE_REQUEST_TYPE_REGULAR:
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\frontend\ShortcodeRequests'
-                );
-                break;
-        }
-        $this->routes_loaded[ __FUNCTION__ ] = true;
-    }
-
-
-    /**
-     * @throws Exception
-     */
-    public function brewEspresso()
-    {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
-            return;
-        }
-        do_action(
-            'AHEE__EventEspresso_core_services_routing_Router__brewEspresso',
-            $this->route_handler,
-            $this->route_request_type,
-            $this->dependency_map
-        );
-        switch ($this->route_request_type) {
-            case PrimaryRoute::ROUTE_REQUEST_TYPE_ACTIVATION:
-                break;
-            case PrimaryRoute::ROUTE_REQUEST_TYPE_REGULAR:
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\shared\GQLRequests'
-                );
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\shared\RestApiRequests'
-                );
-                break;
-        }
-        $this->routes_loaded[ __FUNCTION__ ] = true;
-    }
-
-
-    /**
-     * @throws Exception
-     */
-    public function loadControllers()
-    {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
-            return;
-        }
-        do_action(
-            'AHEE__EventEspresso_core_services_routing_Router__loadControllers',
-            $this->route_handler,
-            $this->route_request_type,
-            $this->dependency_map
-        );
-        $this->route_handler->addRoute(
-            'EventEspresso\core\domain\entities\routing\handlers\admin\AdminRoute'
-        );
-        switch ($this->route_request_type) {
-            case PrimaryRoute::ROUTE_REQUEST_TYPE_ACTIVATION:
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\admin\WordPressPluginsPage'
-                );
-                break;
-            case PrimaryRoute::ROUTE_REQUEST_TYPE_REGULAR:
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\frontend\FrontendRequests'
-                );
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\admin\EspressoLegacyAdmin'
-                );
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\admin\EspressoEventsAdmin'
-                );
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\admin\EspressoEventEditor'
-                );
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\admin\GutenbergEditor'
-                );
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\admin\NonEspressoAdminAjax'
-                );
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\admin\WordPressPluginsPage'
-                );
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\admin\WordPressProfilePage'
-                );
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\shared\WordPressHeartbeat'
-                );
-                break;
-        }
-        $this->routes_loaded[ __FUNCTION__ ] = true;
-    }
-
-
-    /**
-     * @throws Exception
-     */
-    public function coreLoadedAndReady()
-    {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
-            return;
-        }
-        do_action(
-            'AHEE__EventEspresso_core_services_routing_Router__coreLoadedAndReady',
-            $this->route_handler,
-            $this->route_request_type,
-            $this->dependency_map
-        );
-        switch ($this->route_request_type) {
-            case PrimaryRoute::ROUTE_REQUEST_TYPE_ACTIVATION:
-                break;
-            case PrimaryRoute::ROUTE_REQUEST_TYPE_REGULAR:
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\shared\AssetRequests'
-                );
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\shared\SessionRequests'
-                );
-                break;
-        }
-        $this->routes_loaded[ __FUNCTION__ ] = true;
-    }
-
-
-    /**
-     * @throws Exception
-     */
-    public function initializeLast()
-    {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
-            return;
-        }
-        do_action(
-            'AHEE__EventEspresso_core_services_routing_Router__initializeLast',
-            $this->route_handler,
-            $this->route_request_type,
-            $this->dependency_map
-        );
-        switch ($this->route_request_type) {
-            case PrimaryRoute::ROUTE_REQUEST_TYPE_ACTIVATION:
-                break;
-            case PrimaryRoute::ROUTE_REQUEST_TYPE_REGULAR:
-                $this->route_handler->addRoute(
-                    'EventEspresso\core\domain\entities\routing\handlers\admin\PersonalDataRequests'
-                );
-                break;
-        }
-        $this->routes_loaded[ __FUNCTION__ ] = true;
-    }
+	protected EE_Dependency_Map $dependency_map;
+
+	protected LoaderInterface   $loader;
+
+	protected RouteHandler      $route_handler;
+
+	protected string            $route_request_type;
+
+	protected array             $routes_loaded;
+
+
+	/**
+	 * RoutingSwitch constructor.
+	 *
+	 * @param EE_Dependency_Map $dependency_map
+	 * @param LoaderInterface   $loader
+	 * @param RouteHandler      $router
+	 */
+	public function __construct(EE_Dependency_Map $dependency_map, LoaderInterface $loader, RouteHandler $router)
+	{
+		$this->dependency_map = $dependency_map;
+		$this->loader         = $loader;
+		$this->route_handler  = $router;
+	}
+
+
+	/**
+	 * @throws Exception
+	 */
+	public function loadPrimaryRoutes()
+	{
+		if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+			return;
+		}
+		$this->dependency_map->registerDependencies(
+			'EventEspresso\core\domain\entities\routing\handlers\admin\ActivationRequests',
+			Route::getFullDependencies()
+		);
+		$this->dependency_map->registerDependencies(
+			'EventEspresso\core\domain\entities\routing\handlers\shared\RegularRequests',
+			Route::getFullDependencies()
+		);
+		// now load and prep all primary Routes
+		$this->route_handler->addRoute('EventEspresso\core\domain\entities\routing\handlers\admin\ActivationRequests');
+		$this->route_handler->addRoute('EventEspresso\core\domain\entities\routing\handlers\shared\RegularRequests');
+		$this->route_request_type = $this->route_handler->getRouteRequestType();
+		do_action(
+			'AHEE__EventEspresso_core_services_routing_Router__loadPrimaryRoutes',
+			$this->route_handler,
+			$this->route_request_type,
+			$this->dependency_map
+		);
+		$this->routes_loaded[ __FUNCTION__ ] = true;
+	}
+
+
+	/**
+	 * @throws Exception
+	 */
+	public function registerShortcodesModulesAndWidgets()
+	{
+		if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+			return;
+		}
+		do_action(
+			'AHEE__EventEspresso_core_services_routing_Router__registerShortcodesModulesAndWidgets',
+			$this->route_handler,
+			$this->route_request_type,
+			$this->dependency_map
+		);
+		switch ($this->route_request_type) {
+			case PrimaryRoute::ROUTE_REQUEST_TYPE_ACTIVATION:
+				break;
+			case PrimaryRoute::ROUTE_REQUEST_TYPE_REGULAR:
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\frontend\ShortcodeRequests'
+				);
+				break;
+		}
+		$this->routes_loaded[ __FUNCTION__ ] = true;
+	}
+
+
+	/**
+	 * @throws Exception
+	 */
+	public function brewEspresso()
+	{
+		if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+			return;
+		}
+		do_action(
+			'AHEE__EventEspresso_core_services_routing_Router__brewEspresso',
+			$this->route_handler,
+			$this->route_request_type,
+			$this->dependency_map
+		);
+		switch ($this->route_request_type) {
+			case PrimaryRoute::ROUTE_REQUEST_TYPE_ACTIVATION:
+				break;
+			case PrimaryRoute::ROUTE_REQUEST_TYPE_REGULAR:
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\shared\GQLRequests'
+				);
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\shared\RestApiRequests'
+				);
+				break;
+		}
+		$this->routes_loaded[ __FUNCTION__ ] = true;
+	}
+
+
+	/**
+	 * @throws Exception
+	 */
+	public function loadControllers()
+	{
+		if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+			return;
+		}
+		do_action(
+			'AHEE__EventEspresso_core_services_routing_Router__loadControllers',
+			$this->route_handler,
+			$this->route_request_type,
+			$this->dependency_map
+		);
+		$this->route_handler->addRoute(
+			'EventEspresso\core\domain\entities\routing\handlers\admin\AdminRoute'
+		);
+		switch ($this->route_request_type) {
+			case PrimaryRoute::ROUTE_REQUEST_TYPE_ACTIVATION:
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\admin\WordPressPluginsPage'
+				);
+				break;
+			case PrimaryRoute::ROUTE_REQUEST_TYPE_REGULAR:
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\frontend\FrontendRequests'
+				);
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\admin\EspressoLegacyAdmin'
+				);
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\admin\EspressoEventsAdmin'
+				);
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\admin\EspressoEventEditor'
+				);
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\admin\GutenbergEditor'
+				);
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\admin\NonEspressoAdminAjax'
+				);
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\admin\WordPressPluginsPage'
+				);
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\admin\WordPressProfilePage'
+				);
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\shared\WordPressHeartbeat'
+				);
+				break;
+		}
+		$this->routes_loaded[ __FUNCTION__ ] = true;
+	}
+
+
+	/**
+	 * @throws Exception
+	 */
+	public function coreLoadedAndReady()
+	{
+		if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+			return;
+		}
+		do_action(
+			'AHEE__EventEspresso_core_services_routing_Router__coreLoadedAndReady',
+			$this->route_handler,
+			$this->route_request_type,
+			$this->dependency_map
+		);
+		switch ($this->route_request_type) {
+			case PrimaryRoute::ROUTE_REQUEST_TYPE_ACTIVATION:
+				break;
+			case PrimaryRoute::ROUTE_REQUEST_TYPE_REGULAR:
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\shared\AssetRequests'
+				);
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\shared\SessionRequests'
+				);
+				break;
+		}
+		$this->routes_loaded[ __FUNCTION__ ] = true;
+	}
+
+
+	/**
+	 * @throws Exception
+	 */
+	public function initializeLast()
+	{
+		if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+			return;
+		}
+		do_action(
+			'AHEE__EventEspresso_core_services_routing_Router__initializeLast',
+			$this->route_handler,
+			$this->route_request_type,
+			$this->dependency_map
+		);
+		switch ($this->route_request_type) {
+			case PrimaryRoute::ROUTE_REQUEST_TYPE_ACTIVATION:
+				break;
+			case PrimaryRoute::ROUTE_REQUEST_TYPE_REGULAR:
+				$this->route_handler->addRoute(
+					'EventEspresso\core\domain\entities\routing\handlers\admin\PersonalDataRequests'
+				);
+				break;
+		}
+		$this->routes_loaded[ __FUNCTION__ ] = true;
+	}
 }

Spacing +12 added lines, -12 removed lines

@@ -45,7 +45,7 @@ 
      */
     public function loadPrimaryRoutes()
     {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+        if (isset($this->routes_loaded[__FUNCTION__])) {
             return;
         }
         $this->dependency_map->registerDependencies(
@@ -66,7 +66,7 @@ 
             $this->route_request_type,
             $this->dependency_map
         );
-        $this->routes_loaded[ __FUNCTION__ ] = true;
+        $this->routes_loaded[__FUNCTION__] = true;
     }
 
 
@@ -75,7 +75,7 @@ 
      */
     public function registerShortcodesModulesAndWidgets()
     {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+        if (isset($this->routes_loaded[__FUNCTION__])) {
             return;
         }
         do_action(
@@ -93,7 +93,7 @@ 
                 );
                 break;
         }
-        $this->routes_loaded[ __FUNCTION__ ] = true;
+        $this->routes_loaded[__FUNCTION__] = true;
     }
 
 
@@ -102,7 +102,7 @@ 
      */
     public function brewEspresso()
     {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+        if (isset($this->routes_loaded[__FUNCTION__])) {
             return;
         }
         do_action(
@@ -123,7 +123,7 @@ 
                 );
                 break;
         }
-        $this->routes_loaded[ __FUNCTION__ ] = true;
+        $this->routes_loaded[__FUNCTION__] = true;
     }
 
 
@@ -132,7 +132,7 @@ 
      */
     public function loadControllers()
     {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+        if (isset($this->routes_loaded[__FUNCTION__])) {
             return;
         }
         do_action(
@@ -180,7 +180,7 @@ 
                 );
                 break;
         }
-        $this->routes_loaded[ __FUNCTION__ ] = true;
+        $this->routes_loaded[__FUNCTION__] = true;
     }
 
 
@@ -189,7 +189,7 @@ 
      */
     public function coreLoadedAndReady()
     {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+        if (isset($this->routes_loaded[__FUNCTION__])) {
             return;
         }
         do_action(
@@ -210,7 +210,7 @@ 
                 );
                 break;
         }
-        $this->routes_loaded[ __FUNCTION__ ] = true;
+        $this->routes_loaded[__FUNCTION__] = true;
     }
 
 
@@ -219,7 +219,7 @@ 
      */
     public function initializeLast()
     {
-        if (isset($this->routes_loaded[ __FUNCTION__ ])) {
+        if (isset($this->routes_loaded[__FUNCTION__])) {
             return;
         }
         do_action(
@@ -237,6 +237,6 @@ 
                 );
                 break;
         }
-        $this->routes_loaded[ __FUNCTION__ ] = true;
+        $this->routes_loaded[__FUNCTION__] = true;
     }
 }

core/services/shortcodes/LegacyShortcodesManager.php

Indentation +454 added lines, -454 removed lines

@@ -26,458 +26,458 @@
  */
 class LegacyShortcodesManager
 {
-    /**
-     * @var string
-     */
-    public const SHORTCODE_PREFIX = 'EES_';
-
-    protected CurrentPage $current_page;
-
-    private EE_Registry $registry;
-
-
-    /**
-     * LegacyShortcodesManager constructor.
-     *
-     * @param EE_Registry $registry
-     * @param CurrentPage $current_page
-     */
-    public function __construct(EE_Registry $registry, CurrentPage $current_page)
-    {
-        $this->registry     = $registry;
-        $this->current_page = $current_page;
-    }
-
-
-    /**
-     * @return EE_Registry
-     */
-    public function registry(): EE_Registry
-    {
-        return $this->registry;
-    }
-
-
-    /**
-     * registerShortcodes
-     *
-     * @return void
-     */
-    public function registerShortcodes()
-    {
-        $this->registry->shortcodes = $this->getShortcodes();
-    }
-
-
-    /**
-     * getShortcodes
-     *
-     * @return array|RegistryContainer
-     */
-    public function getShortcodes()
-    {
-        // previously this method would glob the shortcodes directory
-        // then filter that list of shortcodes to register,
-        // but now we are going to just supply an empty array.
-        // this allows any shortcodes that have not yet been converted to the new system
-        // to still get loaded and processed, albeit using the same legacy logic as before
-        $shortcodes_to_register = apply_filters(
-            'FHEE__EE_Config__register_shortcodes__shortcodes_to_register',
-            []
-        );
-        if (! empty($shortcodes_to_register)) {
-            // cycle thru shortcode folders
-            foreach ($shortcodes_to_register as $shortcode_path) {
-                // add to list of installed shortcode modules
-                $this->registerShortcode($shortcode_path);
-            }
-        }
-        // filter list of installed modules
-        return apply_filters(
-            'FHEE__EE_Config___register_shortcodes__installed_shortcodes',
-            ! empty($this->registry->shortcodes)
-                ? $this->registry->shortcodes
-                : []
-        );
-    }
-
-
-    /**
-     * register_shortcode - makes core aware of this shortcode
-     *
-     * @param string|null $shortcode_path - full path up to and including shortcode folder
-     * @return    bool
-     */
-    public function registerShortcode(string $shortcode_path = ''): bool
-    {
-        do_action('AHEE__EE_Config__register_shortcode__begin', $shortcode_path);
-        $shortcode_ext = '.shortcode.php';
-        // make all separators match
-        $shortcode_path = str_replace(['\\', '/'], '/', $shortcode_path);
-        // does the file path INCLUDE the actual file name as part of the path ?
-        if (strpos($shortcode_path, $shortcode_ext) !== false) {
-            // grab shortcode file name from directory name and break apart at dots
-            $shortcode_file = explode('.', basename($shortcode_path));
-            // take first segment from file name pieces and remove class prefix if it exists
-            $shortcode = LegacyShortcodesManager::stripShortcodeClassPrefix($shortcode_file[0]);
-            // sanitize shortcode directory name
-            $shortcode = sanitize_key($shortcode);
-            // now we need to rebuild the shortcode path
-            $shortcode_path = explode('/', $shortcode_path);
-            // remove last segment
-            array_pop($shortcode_path);
-            // glue it back together
-            $shortcode_path = implode('/', $shortcode_path) . '/';
-        } else {
-            // we need to generate the filename based off of the folder name
-            // grab and sanitize shortcode directory name
-            $shortcode      = sanitize_key(basename($shortcode_path));
-            $shortcode_path = rtrim($shortcode_path, '/') . '/';
-        }
-        // create classname from shortcode directory or file name
-        $shortcode = str_replace(' ', '_', ucwords(str_replace('_', ' ', $shortcode)));
-        // add class prefix
-        $shortcode_class = LegacyShortcodesManager::addShortcodeClassPrefix($shortcode);
-        // does the shortcode exist ?
-        if (! is_readable($shortcode_path . '/' . $shortcode_class . $shortcode_ext)) {
-            $msg = sprintf(
-                esc_html__(
-                    'The requested %1$s shortcode file could not be found or is not readable due to file permissions. It should be in %2$s',
-                    'event_espresso'
-                ),
-                $shortcode_class,
-                $shortcode_path . '/' . $shortcode_class . $shortcode_ext
-            );
-            EE_Error::add_error($msg . '||' . $msg, __FILE__, __FUNCTION__, __LINE__);
-            return false;
-        }
-        // load the shortcode class file
-        require_once($shortcode_path . $shortcode_class . $shortcode_ext);
-        // verify that class exists
-        if (! class_exists($shortcode_class)) {
-            $msg = sprintf(
-                esc_html__('The requested %s shortcode class does not exist.', 'event_espresso'),
-                $shortcode_class
-            );
-            EE_Error::add_error($msg . '||' . $msg, __FILE__, __FUNCTION__, __LINE__);
-            return false;
-        }
-        $shortcode = strtoupper($shortcode);
-        // add to array of registered shortcodes
-        $this->registry->shortcodes->{$shortcode} = $shortcode_path . $shortcode_class . $shortcode_ext;
-        return true;
-    }
-
-
-    /**
-     *    _initialize_shortcodes
-     *    allow shortcodes to set hooks for the rest of the system
-     *
-     * @return void
-     */
-    public function addShortcodes()
-    {
-        // cycle thru shortcode folders
-        foreach ($this->registry->shortcodes as $shortcode => $shortcode_path) {
-            // add class prefix
-            $shortcode_class = LegacyShortcodesManager::addShortcodeClassPrefix($shortcode);
-            // fire the shortcode class's set_hooks methods in case it needs to hook into other parts of the system
-            // which set hooks ?
-            if (is_admin()) {
-                // fire immediately
-                call_user_func([$shortcode_class, 'set_hooks_admin']);
-            } else {
-                // delay until other systems are online
-                add_action(
-                    'AHEE__EE_System__set_hooks_for_shortcodes_modules_and_addons',
-                    [$shortcode_class, 'set_hooks']
-                );
-                // convert classname to UPPERCASE and create WP shortcode.
-                $shortcode_tag = strtoupper($shortcode);
-                // but first check if the shortcode has already
-                // been added before assigning 'fallback_shortcode_processor'
-                if (! shortcode_exists($shortcode_tag)) {
-                    // NOTE: this shortcode declaration will get overridden if the shortcode
-                    // is successfully detected in the post content in initializeShortcode()
-                    add_shortcode($shortcode_tag, [$shortcode_class, 'fallback_shortcode_processor']);
-                }
-            }
-        }
-    }
-
-
-    /**
-     * callback for the WP "get_header" hook point
-     * checks posts for EE shortcodes, and initializes them,
-     * then toggles filter switch that loads core default assets
-     *
-     * @param WP_Query $wp_query
-     * @return void
-     * @throws ReflectionException
-     */
-    public function initializeShortcodes(WP_Query $wp_query)
-    {
-        if (
-            empty($this->registry->shortcodes)
-            || defined('EE_TESTS_DIR')
-            || ! $wp_query->is_main_query()
-            || is_admin()
-        ) {
-            return;
-        }
-        // in case shortcode is loaded unexpectedly and deps haven't been set up correctly
-        EE_Dependency_Map::register_dependencies(
-            'EE_Front_Controller',
-            [
-                'EE_Registry'                                     => EE_Dependency_Map::load_from_cache,
-                'EventEspresso\core\services\request\CurrentPage' => EE_Dependency_Map::load_from_cache,
-                'EE_Module_Request_Router'                        => EE_Dependency_Map::load_from_cache,
-            ]
-        );
-        global $wp;
-        /** @var EE_Front_controller $Front_Controller */
-        $Front_Controller = LoaderFactory::getLoader()->getShared('EE_Front_Controller');
-        do_action('AHEE__EE_Front_Controller__initialize_shortcodes__begin', $wp, $Front_Controller);
-        $this->current_page->parseQueryVars();
-        // grab post_name from request
-        $current_post  = apply_filters(
-            'FHEE__EE_Front_Controller__initialize_shortcodes__current_post_name',
-            $this->current_page->postName()
-        );
-        $show_on_front = get_option('show_on_front');
-        // if it's not set, then check if frontpage is blog
-        if (empty($current_post)) {
-            // yup.. this is the posts page, prepare to load all shortcode modules
-            $current_post = 'posts';
-            // unless..
-            if ($show_on_front === 'page') {
-                // some other page is set as the homepage
-                $page_on_front = get_option('page_on_front');
-                if ($page_on_front) {
-                    // k now we need to find the post_name for this page
-                    global $wpdb;
-                    $page_on_front = $wpdb->get_var(
-                        $wpdb->prepare(
-                            "SELECT post_name from $wpdb->posts WHERE post_type='page' AND post_status NOT IN ('auto-draft', 'inherit', 'trash') AND ID=%d",
-                            $page_on_front
-                        )
-                    );
-                    // set the current post slug to what it actually is
-                    $current_post = $page_on_front ?: $current_post;
-                }
-            }
-        }
-        // in case $current_post is hierarchical like: /parent-page/current-page
-        $current_post = basename($current_post);
-        if (
-            // is current page/post the "blog" page ?
-            $current_post === EE_Config::get_page_for_posts()
-            // or are we on a category page?
-            || (
-                is_array(term_exists($current_post, 'category'))
-                || array_key_exists('category_name', $wp->query_vars)
-            )
-        ) {
-            // initialize all legacy shortcodes
-            $load_assets = $this->parseContentForShortcodes('', true);
-        } else {
-            global $post;
-            if ($post instanceof WP_Post) {
-                $post_content = $post->post_content;
-            } else {
-                global $wpdb;
-                $post_content = $wpdb->get_var(
-                    $wpdb->prepare(
-                        "SELECT post_content from $wpdb->posts WHERE post_status NOT IN ('auto-draft', 'inherit', 'trash') AND post_name=%s",
-                        $current_post
-                    )
-                );
-            }
-            $load_assets = $this->parseContentForShortcodes($post_content);
-        }
-        if ($load_assets) {
-            $this->current_page->setEspressoPage(true);
-            add_filter('FHEE_load_css', '__return_true');
-            add_filter('FHEE_load_js', '__return_true');
-        }
-        do_action('AHEE__EE_Front_Controller__initialize_shortcodes__end', $Front_Controller);
-    }
-
-
-    /**
-     * checks supplied content against list of legacy shortcodes,
-     * then initializes any found shortcodes, and returns true.
-     * returns false if no shortcodes found.
-     *
-     * @param string|null $content
-     * @param bool $load_all if true, then ALL active legacy shortcodes will be initialized
-     * @return bool
-     * @throws ReflectionException
-     */
-    public function parseContentForShortcodes(?string $content = '', bool $load_all = false): bool
-    {
-        $content = $content ?? '';
-        $has_shortcode = false;
-        foreach ($this->registry->shortcodes as $shortcode_class => $shortcode) {
-            if ($load_all || has_shortcode($content, $shortcode_class)) {
-                // load up the shortcode
-                $this->initializeShortcode($shortcode_class);
-                $has_shortcode = true;
-            }
-        }
-        // one last test for an [espresso_*] shortcode
-        if (! $has_shortcode) {
-            $has_shortcode = strpos($content, '[espresso_') !== false;
-        }
-        return $has_shortcode;
-    }
-
-
-    /**
-     * given a shortcode name, will instantiate the shortcode and call it's run() method
-     *
-     * @param string  $shortcode_class
-     * @param WP|null $wp
-     * @throws ReflectionException
-     */
-    public function initializeShortcode(string $shortcode_class = '', WP $wp = null): void
-    {
-        // don't do anything if shortcode is already initialized
-        if (
-            empty($this->registry->shortcodes->{$shortcode_class})
-            || ! is_string($this->registry->shortcodes->{$shortcode_class})
-        ) {
-            return;
-        }
-        // let's pause to reflect on this...
-        $sc_reflector = new ReflectionClass(LegacyShortcodesManager::addShortcodeClassPrefix($shortcode_class));
-        // ensure that class is actually a shortcode
-        if (
-            defined('WP_DEBUG')
-            && WP_DEBUG === true
-            && ! $sc_reflector->isSubclassOf('EES_Shortcode')
-        ) {
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'The requested %s shortcode is not of the class "EES_Shortcode". Please check your files.',
-                        'event_espresso'
-                    ),
-                    $shortcode_class
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            add_filter('FHEE_run_EE_the_content', '__return_true');
-            return;
-        }
-        global $wp;
-        // and pass the request object to the run method
-        $this->registry->shortcodes->{$shortcode_class} = $sc_reflector->newInstance();
-        // fire the shortcode class's run method, so that it can activate resources
-        $this->registry->shortcodes->{$shortcode_class}->run($wp);
-    }
-
-
-    /**
-     * get classname, remove EES_prefix, and convert to UPPERCASE
-     *
-     * @param string $class_name
-     * @return string
-     */
-    public static function generateShortcodeTagFromClassName(string $class_name): string
-    {
-        return strtoupper(LegacyShortcodesManager::stripShortcodeClassPrefix(strtoupper($class_name)));
-    }
-
-
-    /**
-     * add EES_prefix and Capitalize words
-     *
-     * @param string $tag
-     * @return string
-     */
-    public static function generateShortcodeClassNameFromTag(string $tag): string
-    {
-        // order of operation runs from inside to out
-        // 5) maybe add prefix
-        return LegacyShortcodesManager::addShortcodeClassPrefix(
-        // 4) find spaces, replace with underscores
-            str_replace(
-                ' ',
-                '_',
-                // 3) capitalize first letter of each word
-                ucwords(
-                // 2) also change to lowercase so ucwords() will work
-                    strtolower(
-                    // 1) find underscores, replace with spaces so ucwords() will work
-                        str_replace(
-                            '_',
-                            ' ',
-                            $tag
-                        )
-                    )
-                )
-            )
-        );
-    }
-
-
-    /**
-     * maybe add EES_ prefix
-     *
-     * @param string $class_name
-     * @return string
-     */
-    public static function addShortcodeClassPrefix(string $class_name): string
-    {
-        return strpos($class_name, LegacyShortcodesManager::SHORTCODE_PREFIX) === 0
-            ? $class_name
-            : LegacyShortcodesManager::SHORTCODE_PREFIX . $class_name;
-    }
-
-
-    /**
-     * maybe remove EES_ prefix
-     *
-     * @param string $class_name
-     * @return string
-     */
-    public static function stripShortcodeClassPrefix(string $class_name): string
-    {
-        return strpos($class_name, LegacyShortcodesManager::SHORTCODE_PREFIX) === 0
-            ? substr($class_name, 4)
-            : $class_name;
-    }
-
-
-    /**
-     * @return array
-     */
-    public function getEspressoShortcodeTags(): array
-    {
-        static $shortcode_tags = [];
-        if (empty($shortcode_tags)) {
-            $shortcode_tags = array_keys((array) $this->registry->shortcodes);
-        }
-        return $shortcode_tags;
-    }
-
-
-    /**
-     * @param string $content
-     * @return string
-     * @throws ReflectionException
-     */
-    public function doShortcode(string $content): string
-    {
-        foreach ($this->getEspressoShortcodeTags() as $shortcode_tag) {
-            if (strpos($content, $shortcode_tag) !== false) {
-                $shortcode_class = LegacyShortcodesManager::generateShortcodeClassNameFromTag($shortcode_tag);
-                $this->initializeShortcode($shortcode_class);
-            }
-        }
-        return do_shortcode($content);
-    }
+	/**
+	 * @var string
+	 */
+	public const SHORTCODE_PREFIX = 'EES_';
+
+	protected CurrentPage $current_page;
+
+	private EE_Registry $registry;
+
+
+	/**
+	 * LegacyShortcodesManager constructor.
+	 *
+	 * @param EE_Registry $registry
+	 * @param CurrentPage $current_page
+	 */
+	public function __construct(EE_Registry $registry, CurrentPage $current_page)
+	{
+		$this->registry     = $registry;
+		$this->current_page = $current_page;
+	}
+
+
+	/**
+	 * @return EE_Registry
+	 */
+	public function registry(): EE_Registry
+	{
+		return $this->registry;
+	}
+
+
+	/**
+	 * registerShortcodes
+	 *
+	 * @return void
+	 */
+	public function registerShortcodes()
+	{
+		$this->registry->shortcodes = $this->getShortcodes();
+	}
+
+
+	/**
+	 * getShortcodes
+	 *
+	 * @return array|RegistryContainer
+	 */
+	public function getShortcodes()
+	{
+		// previously this method would glob the shortcodes directory
+		// then filter that list of shortcodes to register,
+		// but now we are going to just supply an empty array.
+		// this allows any shortcodes that have not yet been converted to the new system
+		// to still get loaded and processed, albeit using the same legacy logic as before
+		$shortcodes_to_register = apply_filters(
+			'FHEE__EE_Config__register_shortcodes__shortcodes_to_register',
+			[]
+		);
+		if (! empty($shortcodes_to_register)) {
+			// cycle thru shortcode folders
+			foreach ($shortcodes_to_register as $shortcode_path) {
+				// add to list of installed shortcode modules
+				$this->registerShortcode($shortcode_path);
+			}
+		}
+		// filter list of installed modules
+		return apply_filters(
+			'FHEE__EE_Config___register_shortcodes__installed_shortcodes',
+			! empty($this->registry->shortcodes)
+				? $this->registry->shortcodes
+				: []
+		);
+	}
+
+
+	/**
+	 * register_shortcode - makes core aware of this shortcode
+	 *
+	 * @param string|null $shortcode_path - full path up to and including shortcode folder
+	 * @return    bool
+	 */
+	public function registerShortcode(string $shortcode_path = ''): bool
+	{
+		do_action('AHEE__EE_Config__register_shortcode__begin', $shortcode_path);
+		$shortcode_ext = '.shortcode.php';
+		// make all separators match
+		$shortcode_path = str_replace(['\\', '/'], '/', $shortcode_path);
+		// does the file path INCLUDE the actual file name as part of the path ?
+		if (strpos($shortcode_path, $shortcode_ext) !== false) {
+			// grab shortcode file name from directory name and break apart at dots
+			$shortcode_file = explode('.', basename($shortcode_path));
+			// take first segment from file name pieces and remove class prefix if it exists
+			$shortcode = LegacyShortcodesManager::stripShortcodeClassPrefix($shortcode_file[0]);
+			// sanitize shortcode directory name
+			$shortcode = sanitize_key($shortcode);
+			// now we need to rebuild the shortcode path
+			$shortcode_path = explode('/', $shortcode_path);
+			// remove last segment
+			array_pop($shortcode_path);
+			// glue it back together
+			$shortcode_path = implode('/', $shortcode_path) . '/';
+		} else {
+			// we need to generate the filename based off of the folder name
+			// grab and sanitize shortcode directory name
+			$shortcode      = sanitize_key(basename($shortcode_path));
+			$shortcode_path = rtrim($shortcode_path, '/') . '/';
+		}
+		// create classname from shortcode directory or file name
+		$shortcode = str_replace(' ', '_', ucwords(str_replace('_', ' ', $shortcode)));
+		// add class prefix
+		$shortcode_class = LegacyShortcodesManager::addShortcodeClassPrefix($shortcode);
+		// does the shortcode exist ?
+		if (! is_readable($shortcode_path . '/' . $shortcode_class . $shortcode_ext)) {
+			$msg = sprintf(
+				esc_html__(
+					'The requested %1$s shortcode file could not be found or is not readable due to file permissions. It should be in %2$s',
+					'event_espresso'
+				),
+				$shortcode_class,
+				$shortcode_path . '/' . $shortcode_class . $shortcode_ext
+			);
+			EE_Error::add_error($msg . '||' . $msg, __FILE__, __FUNCTION__, __LINE__);
+			return false;
+		}
+		// load the shortcode class file
+		require_once($shortcode_path . $shortcode_class . $shortcode_ext);
+		// verify that class exists
+		if (! class_exists($shortcode_class)) {
+			$msg = sprintf(
+				esc_html__('The requested %s shortcode class does not exist.', 'event_espresso'),
+				$shortcode_class
+			);
+			EE_Error::add_error($msg . '||' . $msg, __FILE__, __FUNCTION__, __LINE__);
+			return false;
+		}
+		$shortcode = strtoupper($shortcode);
+		// add to array of registered shortcodes
+		$this->registry->shortcodes->{$shortcode} = $shortcode_path . $shortcode_class . $shortcode_ext;
+		return true;
+	}
+
+
+	/**
+	 *    _initialize_shortcodes
+	 *    allow shortcodes to set hooks for the rest of the system
+	 *
+	 * @return void
+	 */
+	public function addShortcodes()
+	{
+		// cycle thru shortcode folders
+		foreach ($this->registry->shortcodes as $shortcode => $shortcode_path) {
+			// add class prefix
+			$shortcode_class = LegacyShortcodesManager::addShortcodeClassPrefix($shortcode);
+			// fire the shortcode class's set_hooks methods in case it needs to hook into other parts of the system
+			// which set hooks ?
+			if (is_admin()) {
+				// fire immediately
+				call_user_func([$shortcode_class, 'set_hooks_admin']);
+			} else {
+				// delay until other systems are online
+				add_action(
+					'AHEE__EE_System__set_hooks_for_shortcodes_modules_and_addons',
+					[$shortcode_class, 'set_hooks']
+				);
+				// convert classname to UPPERCASE and create WP shortcode.
+				$shortcode_tag = strtoupper($shortcode);
+				// but first check if the shortcode has already
+				// been added before assigning 'fallback_shortcode_processor'
+				if (! shortcode_exists($shortcode_tag)) {
+					// NOTE: this shortcode declaration will get overridden if the shortcode
+					// is successfully detected in the post content in initializeShortcode()
+					add_shortcode($shortcode_tag, [$shortcode_class, 'fallback_shortcode_processor']);
+				}
+			}
+		}
+	}
+
+
+	/**
+	 * callback for the WP "get_header" hook point
+	 * checks posts for EE shortcodes, and initializes them,
+	 * then toggles filter switch that loads core default assets
+	 *
+	 * @param WP_Query $wp_query
+	 * @return void
+	 * @throws ReflectionException
+	 */
+	public function initializeShortcodes(WP_Query $wp_query)
+	{
+		if (
+			empty($this->registry->shortcodes)
+			|| defined('EE_TESTS_DIR')
+			|| ! $wp_query->is_main_query()
+			|| is_admin()
+		) {
+			return;
+		}
+		// in case shortcode is loaded unexpectedly and deps haven't been set up correctly
+		EE_Dependency_Map::register_dependencies(
+			'EE_Front_Controller',
+			[
+				'EE_Registry'                                     => EE_Dependency_Map::load_from_cache,
+				'EventEspresso\core\services\request\CurrentPage' => EE_Dependency_Map::load_from_cache,
+				'EE_Module_Request_Router'                        => EE_Dependency_Map::load_from_cache,
+			]
+		);
+		global $wp;
+		/** @var EE_Front_controller $Front_Controller */
+		$Front_Controller = LoaderFactory::getLoader()->getShared('EE_Front_Controller');
+		do_action('AHEE__EE_Front_Controller__initialize_shortcodes__begin', $wp, $Front_Controller);
+		$this->current_page->parseQueryVars();
+		// grab post_name from request
+		$current_post  = apply_filters(
+			'FHEE__EE_Front_Controller__initialize_shortcodes__current_post_name',
+			$this->current_page->postName()
+		);
+		$show_on_front = get_option('show_on_front');
+		// if it's not set, then check if frontpage is blog
+		if (empty($current_post)) {
+			// yup.. this is the posts page, prepare to load all shortcode modules
+			$current_post = 'posts';
+			// unless..
+			if ($show_on_front === 'page') {
+				// some other page is set as the homepage
+				$page_on_front = get_option('page_on_front');
+				if ($page_on_front) {
+					// k now we need to find the post_name for this page
+					global $wpdb;
+					$page_on_front = $wpdb->get_var(
+						$wpdb->prepare(
+							"SELECT post_name from $wpdb->posts WHERE post_type='page' AND post_status NOT IN ('auto-draft', 'inherit', 'trash') AND ID=%d",
+							$page_on_front
+						)
+					);
+					// set the current post slug to what it actually is
+					$current_post = $page_on_front ?: $current_post;
+				}
+			}
+		}
+		// in case $current_post is hierarchical like: /parent-page/current-page
+		$current_post = basename($current_post);
+		if (
+			// is current page/post the "blog" page ?
+			$current_post === EE_Config::get_page_for_posts()
+			// or are we on a category page?
+			|| (
+				is_array(term_exists($current_post, 'category'))
+				|| array_key_exists('category_name', $wp->query_vars)
+			)
+		) {
+			// initialize all legacy shortcodes
+			$load_assets = $this->parseContentForShortcodes('', true);
+		} else {
+			global $post;
+			if ($post instanceof WP_Post) {
+				$post_content = $post->post_content;
+			} else {
+				global $wpdb;
+				$post_content = $wpdb->get_var(
+					$wpdb->prepare(
+						"SELECT post_content from $wpdb->posts WHERE post_status NOT IN ('auto-draft', 'inherit', 'trash') AND post_name=%s",
+						$current_post
+					)
+				);
+			}
+			$load_assets = $this->parseContentForShortcodes($post_content);
+		}
+		if ($load_assets) {
+			$this->current_page->setEspressoPage(true);
+			add_filter('FHEE_load_css', '__return_true');
+			add_filter('FHEE_load_js', '__return_true');
+		}
+		do_action('AHEE__EE_Front_Controller__initialize_shortcodes__end', $Front_Controller);
+	}
+
+
+	/**
+	 * checks supplied content against list of legacy shortcodes,
+	 * then initializes any found shortcodes, and returns true.
+	 * returns false if no shortcodes found.
+	 *
+	 * @param string|null $content
+	 * @param bool $load_all if true, then ALL active legacy shortcodes will be initialized
+	 * @return bool
+	 * @throws ReflectionException
+	 */
+	public function parseContentForShortcodes(?string $content = '', bool $load_all = false): bool
+	{
+		$content = $content ?? '';
+		$has_shortcode = false;
+		foreach ($this->registry->shortcodes as $shortcode_class => $shortcode) {
+			if ($load_all || has_shortcode($content, $shortcode_class)) {
+				// load up the shortcode
+				$this->initializeShortcode($shortcode_class);
+				$has_shortcode = true;
+			}
+		}
+		// one last test for an [espresso_*] shortcode
+		if (! $has_shortcode) {
+			$has_shortcode = strpos($content, '[espresso_') !== false;
+		}
+		return $has_shortcode;
+	}
+
+
+	/**
+	 * given a shortcode name, will instantiate the shortcode and call it's run() method
+	 *
+	 * @param string  $shortcode_class
+	 * @param WP|null $wp
+	 * @throws ReflectionException
+	 */
+	public function initializeShortcode(string $shortcode_class = '', WP $wp = null): void
+	{
+		// don't do anything if shortcode is already initialized
+		if (
+			empty($this->registry->shortcodes->{$shortcode_class})
+			|| ! is_string($this->registry->shortcodes->{$shortcode_class})
+		) {
+			return;
+		}
+		// let's pause to reflect on this...
+		$sc_reflector = new ReflectionClass(LegacyShortcodesManager::addShortcodeClassPrefix($shortcode_class));
+		// ensure that class is actually a shortcode
+		if (
+			defined('WP_DEBUG')
+			&& WP_DEBUG === true
+			&& ! $sc_reflector->isSubclassOf('EES_Shortcode')
+		) {
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'The requested %s shortcode is not of the class "EES_Shortcode". Please check your files.',
+						'event_espresso'
+					),
+					$shortcode_class
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			add_filter('FHEE_run_EE_the_content', '__return_true');
+			return;
+		}
+		global $wp;
+		// and pass the request object to the run method
+		$this->registry->shortcodes->{$shortcode_class} = $sc_reflector->newInstance();
+		// fire the shortcode class's run method, so that it can activate resources
+		$this->registry->shortcodes->{$shortcode_class}->run($wp);
+	}
+
+
+	/**
+	 * get classname, remove EES_prefix, and convert to UPPERCASE
+	 *
+	 * @param string $class_name
+	 * @return string
+	 */
+	public static function generateShortcodeTagFromClassName(string $class_name): string
+	{
+		return strtoupper(LegacyShortcodesManager::stripShortcodeClassPrefix(strtoupper($class_name)));
+	}
+
+
+	/**
+	 * add EES_prefix and Capitalize words
+	 *
+	 * @param string $tag
+	 * @return string
+	 */
+	public static function generateShortcodeClassNameFromTag(string $tag): string
+	{
+		// order of operation runs from inside to out
+		// 5) maybe add prefix
+		return LegacyShortcodesManager::addShortcodeClassPrefix(
+		// 4) find spaces, replace with underscores
+			str_replace(
+				' ',
+				'_',
+				// 3) capitalize first letter of each word
+				ucwords(
+				// 2) also change to lowercase so ucwords() will work
+					strtolower(
+					// 1) find underscores, replace with spaces so ucwords() will work
+						str_replace(
+							'_',
+							' ',
+							$tag
+						)
+					)
+				)
+			)
+		);
+	}
+
+
+	/**
+	 * maybe add EES_ prefix
+	 *
+	 * @param string $class_name
+	 * @return string
+	 */
+	public static function addShortcodeClassPrefix(string $class_name): string
+	{
+		return strpos($class_name, LegacyShortcodesManager::SHORTCODE_PREFIX) === 0
+			? $class_name
+			: LegacyShortcodesManager::SHORTCODE_PREFIX . $class_name;
+	}
+
+
+	/**
+	 * maybe remove EES_ prefix
+	 *
+	 * @param string $class_name
+	 * @return string
+	 */
+	public static function stripShortcodeClassPrefix(string $class_name): string
+	{
+		return strpos($class_name, LegacyShortcodesManager::SHORTCODE_PREFIX) === 0
+			? substr($class_name, 4)
+			: $class_name;
+	}
+
+
+	/**
+	 * @return array
+	 */
+	public function getEspressoShortcodeTags(): array
+	{
+		static $shortcode_tags = [];
+		if (empty($shortcode_tags)) {
+			$shortcode_tags = array_keys((array) $this->registry->shortcodes);
+		}
+		return $shortcode_tags;
+	}
+
+
+	/**
+	 * @param string $content
+	 * @return string
+	 * @throws ReflectionException
+	 */
+	public function doShortcode(string $content): string
+	{
+		foreach ($this->getEspressoShortcodeTags() as $shortcode_tag) {
+			if (strpos($content, $shortcode_tag) !== false) {
+				$shortcode_class = LegacyShortcodesManager::generateShortcodeClassNameFromTag($shortcode_tag);
+				$this->initializeShortcode($shortcode_class);
+			}
+		}
+		return do_shortcode($content);
+	}
 }

core/services/graphql/types/TypeBase.php

Indentation +252 added lines, -252 removed lines

@@ -36,256 +36,256 @@
  */
 abstract class TypeBase implements TypeInterface
 {
-    /**
-     * The graphql namespace/prefix.
-     */
-    protected string    $namespace   = 'Espresso';
-
-    protected ?EEM_Base $model       = null;
-
-    protected string    $name        = '';
-
-    protected string    $description = '';
-
-    /**
-     * @var GraphQLFieldInterface[] $fields
-     */
-    protected array         $fields              = [];
-
-    protected FieldResolver $field_resolver;
-
-    protected bool          $is_custom_post_type = false;
-
-
-    /**
-     * TypeBase constructor.
-     *
-     * @param EEM_Base|null $model
-     */
-    public function __construct(EEM_Base $model = null)
-    {
-        $this->model = $model;
-        $this->setFields($this->getFields());
-        $this->field_resolver = new FieldResolver(
-            $this->model,
-            $this->getFieldsForResolver()
-        );
-    }
-
-
-    /**
-     * @return GraphQLFieldInterface[]
-     * @since 5.0.0.p
-     */
-    abstract protected function getFields(): array;
-
-
-    /**
-     * @return string
-     */
-    public function name(): string
-    {
-        return $this->name;
-    }
-
-
-    /**
-     * @param string $name
-     */
-    protected function setName(string $name)
-    {
-        $this->name = $name;
-    }
-
-
-    /**
-     * @return string
-     */
-    public function description(): string
-    {
-        return $this->description;
-    }
-
-
-    /**
-     * @param string $description
-     */
-    protected function setDescription(string $description)
-    {
-        $this->description = $description;
-    }
-
-
-    /**
-     * @return GraphQLFieldInterface[]
-     * @since 5.0.0.p
-     */
-    public function fields(): array
-    {
-        return $this->fields;
-    }
-
-
-    /**
-     * @param GraphQLFieldInterface[] $fields
-     */
-    protected function setFields(array $fields)
-    {
-        foreach ($fields as $field) {
-            if ($field instanceof GraphQLField) {
-                $this->fields[] = $field;
-            }
-        }
-    }
-
-
-    /**
-     * Creates a key map for internal resolver.
-     *
-     * @return array
-     * @since 5.0.0.p
-     */
-    public function getFieldsForResolver(): array
-    {
-        $fields = [];
-        foreach ($this->fields() as $field) {
-            if ($field->useForOutput()) {
-                $fields[ $field->name() ] = $field;
-            }
-        }
-        return $fields;
-    }
-
-
-    /**
-     * @return bool
-     */
-    public function isCustomPostType(): bool
-    {
-        return $this->is_custom_post_type;
-    }
-
-
-    /**
-     * @param bool $is_custom_post_type
-     */
-    protected function setIsCustomPostType(bool $is_custom_post_type)
-    {
-        $this->is_custom_post_type = filter_var($is_custom_post_type, FILTER_VALIDATE_BOOLEAN);
-    }
-
-
-    /**
-     * @param int|float $value
-     * @return int
-     * @since 5.0.0.p
-     */
-    public function parseInfiniteValue($value): int
-    {
-        $value = trim((string) $value);
-        return $value === ''
-               || $value === '∞'
-               || $value === 'INF'
-               || $value === INF
-               || $value === EE_INF
-               || is_infinite((float) $value)
-            ? -1
-            : $value;
-    }
-
-
-    /**
-     * @param mixed $source
-     * @return EE_Base_Class|null
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    private function getModel($source): ?EE_Base_Class
-    {
-        // If it comes from a custom connection
-        // where the $source is already instantiated.
-        if ($source instanceof EE_Base_Class) {
-            return $source;
-        }
-        return $source instanceof Post
-            ? $this->model->get_one_by_ID($source->ID)
-            : null;
-    }
-
-
-    /**
-     * @param mixed       $source  The source that's passed down the GraphQL queries
-     * @param array       $args    The inputArgs on the field
-     * @param AppContext  $context The AppContext passed down the GraphQL tree
-     * @param ResolveInfo $info    The ResolveInfo passed down the GraphQL tree
-     * @return EE_Base_Class|Deferred|string|null
-     * @throws EE_Error
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws UnexpectedEntityException
-     * @throws UserError
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @since 5.0.0.p
-     */
-    public function resolveField($source, array $args, AppContext $context, ResolveInfo $info)
-    {
-        $source = $source instanceof RootQuery
-            ? $source
-            : $this->getModel($source);
-
-        return $this->field_resolver->resolve($source, $args, $context, $info);
-    }
-
-
-    /**
-     * @param mixed      $payload The payload returned after mutation
-     * @param array      $args    The inputArgs on the field
-     * @param AppContext $context The AppContext passed down the GraphQL tree
-     * @return EE_Base_Class|EE_Soft_Delete_Base_Class|null
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function resolveFromPayload($payload, array $args, AppContext $context)
-    {
-        if (empty($payload['id'])) {
-            return null;
-        }
-        return $this->model->get_one_by_ID($payload['id']);
-    }
-
-
-    /**
-     * Prepares a datetime value in ISO8601/RFC3339 format.
-     * It is assumed that the value of $datetime is in the format
-     * returned by EE_Base_Class::get_format().
-     *
-     * @param string        $datetime The datetime value.
-     * @param EE_Base_Class $source   The source object.
-     * @return string ISO8601/RFC3339 formatted datetime.
-     * @throws Exception
-     */
-    public function formatDatetime(string $datetime, EE_Base_Class $source): string
-    {
-        $format = $source->get_format();
-        // create date object based on local timezone
-        $datetime = DateTime::createFromFormat($format, $datetime, new DateTimeZone($source->get_timezone()));
-        // change the timezone to UTC
-        $datetime->setTimezone(new DateTimeZone('UTC'));
-
-        return $datetime->format(DateTimeInterface::RFC3339);
-    }
-
-
-    /**
-     * Converts an object to JSON. The object must have a "toJson" method.
-     *
-     * @param JsonableInterface $object The object/value.
-     * @param EE_Base_Class     $source The source object.
-     * @return string JSON representation of the object.
-     */
-    public function toJson(JsonableInterface $object, EE_Base_Class $source): string
-    {
-        return $object->toJson();
-    }
+	/**
+	 * The graphql namespace/prefix.
+	 */
+	protected string    $namespace   = 'Espresso';
+
+	protected ?EEM_Base $model       = null;
+
+	protected string    $name        = '';
+
+	protected string    $description = '';
+
+	/**
+	 * @var GraphQLFieldInterface[] $fields
+	 */
+	protected array         $fields              = [];
+
+	protected FieldResolver $field_resolver;
+
+	protected bool          $is_custom_post_type = false;
+
+
+	/**
+	 * TypeBase constructor.
+	 *
+	 * @param EEM_Base|null $model
+	 */
+	public function __construct(EEM_Base $model = null)
+	{
+		$this->model = $model;
+		$this->setFields($this->getFields());
+		$this->field_resolver = new FieldResolver(
+			$this->model,
+			$this->getFieldsForResolver()
+		);
+	}
+
+
+	/**
+	 * @return GraphQLFieldInterface[]
+	 * @since 5.0.0.p
+	 */
+	abstract protected function getFields(): array;
+
+
+	/**
+	 * @return string
+	 */
+	public function name(): string
+	{
+		return $this->name;
+	}
+
+
+	/**
+	 * @param string $name
+	 */
+	protected function setName(string $name)
+	{
+		$this->name = $name;
+	}
+
+
+	/**
+	 * @return string
+	 */
+	public function description(): string
+	{
+		return $this->description;
+	}
+
+
+	/**
+	 * @param string $description
+	 */
+	protected function setDescription(string $description)
+	{
+		$this->description = $description;
+	}
+
+
+	/**
+	 * @return GraphQLFieldInterface[]
+	 * @since 5.0.0.p
+	 */
+	public function fields(): array
+	{
+		return $this->fields;
+	}
+
+
+	/**
+	 * @param GraphQLFieldInterface[] $fields
+	 */
+	protected function setFields(array $fields)
+	{
+		foreach ($fields as $field) {
+			if ($field instanceof GraphQLField) {
+				$this->fields[] = $field;
+			}
+		}
+	}
+
+
+	/**
+	 * Creates a key map for internal resolver.
+	 *
+	 * @return array
+	 * @since 5.0.0.p
+	 */
+	public function getFieldsForResolver(): array
+	{
+		$fields = [];
+		foreach ($this->fields() as $field) {
+			if ($field->useForOutput()) {
+				$fields[ $field->name() ] = $field;
+			}
+		}
+		return $fields;
+	}
+
+
+	/**
+	 * @return bool
+	 */
+	public function isCustomPostType(): bool
+	{
+		return $this->is_custom_post_type;
+	}
+
+
+	/**
+	 * @param bool $is_custom_post_type
+	 */
+	protected function setIsCustomPostType(bool $is_custom_post_type)
+	{
+		$this->is_custom_post_type = filter_var($is_custom_post_type, FILTER_VALIDATE_BOOLEAN);
+	}
+
+
+	/**
+	 * @param int|float $value
+	 * @return int
+	 * @since 5.0.0.p
+	 */
+	public function parseInfiniteValue($value): int
+	{
+		$value = trim((string) $value);
+		return $value === ''
+			   || $value === '∞'
+			   || $value === 'INF'
+			   || $value === INF
+			   || $value === EE_INF
+			   || is_infinite((float) $value)
+			? -1
+			: $value;
+	}
+
+
+	/**
+	 * @param mixed $source
+	 * @return EE_Base_Class|null
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	private function getModel($source): ?EE_Base_Class
+	{
+		// If it comes from a custom connection
+		// where the $source is already instantiated.
+		if ($source instanceof EE_Base_Class) {
+			return $source;
+		}
+		return $source instanceof Post
+			? $this->model->get_one_by_ID($source->ID)
+			: null;
+	}
+
+
+	/**
+	 * @param mixed       $source  The source that's passed down the GraphQL queries
+	 * @param array       $args    The inputArgs on the field
+	 * @param AppContext  $context The AppContext passed down the GraphQL tree
+	 * @param ResolveInfo $info    The ResolveInfo passed down the GraphQL tree
+	 * @return EE_Base_Class|Deferred|string|null
+	 * @throws EE_Error
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws UnexpectedEntityException
+	 * @throws UserError
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @since 5.0.0.p
+	 */
+	public function resolveField($source, array $args, AppContext $context, ResolveInfo $info)
+	{
+		$source = $source instanceof RootQuery
+			? $source
+			: $this->getModel($source);
+
+		return $this->field_resolver->resolve($source, $args, $context, $info);
+	}
+
+
+	/**
+	 * @param mixed      $payload The payload returned after mutation
+	 * @param array      $args    The inputArgs on the field
+	 * @param AppContext $context The AppContext passed down the GraphQL tree
+	 * @return EE_Base_Class|EE_Soft_Delete_Base_Class|null
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function resolveFromPayload($payload, array $args, AppContext $context)
+	{
+		if (empty($payload['id'])) {
+			return null;
+		}
+		return $this->model->get_one_by_ID($payload['id']);
+	}
+
+
+	/**
+	 * Prepares a datetime value in ISO8601/RFC3339 format.
+	 * It is assumed that the value of $datetime is in the format
+	 * returned by EE_Base_Class::get_format().
+	 *
+	 * @param string        $datetime The datetime value.
+	 * @param EE_Base_Class $source   The source object.
+	 * @return string ISO8601/RFC3339 formatted datetime.
+	 * @throws Exception
+	 */
+	public function formatDatetime(string $datetime, EE_Base_Class $source): string
+	{
+		$format = $source->get_format();
+		// create date object based on local timezone
+		$datetime = DateTime::createFromFormat($format, $datetime, new DateTimeZone($source->get_timezone()));
+		// change the timezone to UTC
+		$datetime->setTimezone(new DateTimeZone('UTC'));
+
+		return $datetime->format(DateTimeInterface::RFC3339);
+	}
+
+
+	/**
+	 * Converts an object to JSON. The object must have a "toJson" method.
+	 *
+	 * @param JsonableInterface $object The object/value.
+	 * @param EE_Base_Class     $source The source object.
+	 * @return string JSON representation of the object.
+	 */
+	public function toJson(JsonableInterface $object, EE_Base_Class $source): string
+	{
+		return $object->toJson();
+	}
 }

Spacing +2 added lines, -2 removed lines

@@ -50,7 +50,7 @@ 
     /**
      * @var GraphQLFieldInterface[] $fields
      */
-    protected array         $fields              = [];
+    protected array         $fields = [];
 
     protected FieldResolver $field_resolver;
 
@@ -150,7 +150,7 @@ 
         $fields = [];
         foreach ($this->fields() as $field) {
             if ($field->useForOutput()) {
-                $fields[ $field->name() ] = $field;
+                $fields[$field->name()] = $field;
             }
         }
         return $fields;

core/db_classes/EE_Attendee.class.php

Indentation +737 added lines, -737 removed lines

@@ -15,741 +15,741 @@
  */
 class EE_Attendee extends EE_CPT_Base implements EEI_Contact, AddressInterface, EEI_Admin_Links, EEI_Attendee
 {
-    /**
-     * Sets some dynamic defaults
-     *
-     * @param array  $fieldValues
-     * @param bool   $bydb
-     * @param string $timezone
-     * @param array  $date_formats
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    protected function __construct($fieldValues = null, $bydb = false, $timezone = null, $date_formats = [])
-    {
-        if (! isset($fieldValues['ATT_full_name'])) {
-            $fname                        = $fieldValues['ATT_fname'] ?? '';
-            $lname                        = $fieldValues['ATT_lname'] ?? '';
-            $fieldValues['ATT_full_name'] = "$fname $lname";
-        }
-        if (! isset($fieldValues['ATT_slug'])) {
-            // $fieldValues['ATT_slug'] = sanitize_key(wp_generate_password(20));
-            $fieldValues['ATT_slug'] = sanitize_title($fieldValues['ATT_full_name']);
-        }
-        if (! isset($fieldValues['ATT_short_bio']) && isset($fieldValues['ATT_bio'])) {
-            $fieldValues['ATT_short_bio'] = substr($fieldValues['ATT_bio'], 0, 50);
-        }
-        parent::__construct($fieldValues, $bydb, $timezone, $date_formats);
-    }
-
-
-    /**
-     * @param array       $props_n_values     incoming values
-     * @param string|null $timezone           incoming timezone (if not set the timezone set for the website
-     *                                        will be
-     *                                        used.)
-     * @param array       $date_formats       incoming date_formats in an array where the first value is the
-     *                                        date_format and the second value is the time format
-     * @return EE_Attendee
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function new_instance(
-        array $props_n_values = [],
-        ?string $timezone = '',
-        array $date_formats = []
-    ): EE_Attendee {
-        $has_object = parent::_check_for_object($props_n_values, __CLASS__, $timezone, $date_formats);
-        return $has_object ?: new self($props_n_values, false, $timezone, $date_formats);
-    }
-
-
-    /**
-     * @param array       $props_n_values incoming values from the database
-     * @param string|null $timezone       incoming timezone as set by the model.
-     *                                    If not set, the timezone for the website will be used.
-     * @return EE_Attendee
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function new_instance_from_db(array $props_n_values = [], ?string $timezone = ''): EE_Attendee
-    {
-        return new self($props_n_values, true, $timezone);
-    }
-
-
-    /**
-     * @param string|null $fname
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_fname(?string $fname = '')
-    {
-        $this->set('ATT_fname', (string) $fname);
-    }
-
-
-    /**
-     * @param string|null $lname
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_lname(?string $lname = '')
-    {
-        $this->set('ATT_lname', (string) $lname);
-    }
-
-
-    /**
-     * @param string|null $address
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_address(?string $address = '')
-    {
-        $this->set('ATT_address', (string) $address);
-    }
-
-
-    /**
-     * @param string|null $address2
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_address2(?string $address2 = '')
-    {
-        $this->set('ATT_address2', (string) $address2);
-    }
-
-
-    /**
-     * @param string|null $city
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_city(?string $city = '')
-    {
-        $this->set('ATT_city', $city);
-    }
-
-
-    /**
-     * @param int|null $STA_ID
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_state(?int $STA_ID = 0)
-    {
-        $this->set('STA_ID', $STA_ID);
-    }
-
-
-    /**
-     * @param string|null $CNT_ISO
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_country(?string $CNT_ISO = '')
-    {
-        $this->set('CNT_ISO', $CNT_ISO);
-    }
-
-
-    /**
-     * @param string|null $zip
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_zip(?string $zip = '')
-    {
-        $this->set('ATT_zip', $zip);
-    }
-
-
-    /**
-     * @param string|null $email
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_email(?string $email = '')
-    {
-        $this->set('ATT_email', $email);
-    }
-
-
-    /**
-     * @param string|null $phone
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_phone(?string $phone = '')
-    {
-        $this->set('ATT_phone', $phone);
-    }
-
-
-    /**
-     * @param bool|int|string|null $ATT_deleted
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function set_deleted($ATT_deleted = false)
-    {
-        $this->set('ATT_deleted', $ATT_deleted);
-    }
-
-
-    /**
-     * Returns the value for the post_author id saved with the cpt
-     *
-     * @return int
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @since 4.5.0
-     */
-    public function wp_user(): int
-    {
-        return (int) $this->get('ATT_author');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function fname(): string
-    {
-        return (string) $this->get('ATT_fname');
-    }
-
-
-    /**
-     * echoes out the attendee's first name
-     *
-     * @return void
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function e_full_name()
-    {
-        echo esc_html($this->full_name());
-    }
-
-
-    /**
-     * Returns the first and last name concatenated together with a space.
-     *
-     * @param bool $apply_html_entities
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function full_name(bool $apply_html_entities = false): string
-    {
-        $full_name = [$this->fname(), $this->lname()];
-        $full_name = array_filter($full_name);
-        $full_name = implode(' ', $full_name);
-        return $apply_html_entities
-            ? htmlentities($full_name, ENT_QUOTES, 'UTF-8')
-            : $full_name;
-    }
-
-
-    /**
-     * This returns the value of the `ATT_full_name` field which is usually equivalent to calling `full_name()` unless
-     * the post_title field has been directly modified in the db for the post (espresso_attendees post type) for this
-     * attendee.
-     *
-     * @param bool $apply_html_entities
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function ATT_full_name(bool $apply_html_entities = false): string
-    {
-        return $apply_html_entities
-            ? htmlentities((string) $this->get('ATT_full_name'), ENT_QUOTES, 'UTF-8')
-            : (string) $this->get('ATT_full_name');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function lname(): string
-    {
-        return (string) $this->get('ATT_lname');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function bio(): string
-    {
-        return (string) $this->get('ATT_bio');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function short_bio(): string
-    {
-        return (string) $this->get('ATT_short_bio');
-    }
-
-
-    /**
-     * Gets the attendee's full address as an array so client code can decide hwo to display it
-     *
-     * @return array numerically indexed, with each part of the address that is known.
-     * Eg, if the user only responded to state and country,
-     * it would be array(0=>'Alabama',1=>'USA')
-     * @return array
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function full_address_as_array(): array
-    {
-        $full_address_array     = [];
-        $initial_address_fields = ['ATT_address', 'ATT_address2', 'ATT_city',];
-        foreach ($initial_address_fields as $address_field_name) {
-            $address_fields_value = $this->get($address_field_name);
-            if (! empty($address_fields_value)) {
-                $full_address_array[] = $address_fields_value;
-            }
-        }
-        // now handle state and country
-        $state_obj = $this->state_obj();
-        if ($state_obj instanceof EE_State) {
-            $full_address_array[] = $state_obj->name();
-        }
-        $country_obj = $this->country_obj();
-        if ($country_obj instanceof EE_Country) {
-            $full_address_array[] = $country_obj->name();
-        }
-        // lastly get the xip
-        $zip_value = $this->zip();
-        if (! empty($zip_value)) {
-            $full_address_array[] = $zip_value;
-        }
-        return $full_address_array;
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function address(): string
-    {
-        return (string) $this->get('ATT_address');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function address2(): string
-    {
-        return (string) $this->get('ATT_address2');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function city(): string
-    {
-        return (string) $this->get('ATT_city');
-    }
-
-
-    /**
-     * @return int
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function state_ID(): int
-    {
-        return (int) $this->get('STA_ID');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function state_abbrev(): string
-    {
-        return $this->state_obj() instanceof EE_State
-            ? $this->state_obj()->abbrev()
-            : '';
-    }
-
-
-    /**
-     * @return EE_State|null
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function state_obj(): ?EE_State
-    {
-        return $this->get_first_related('State');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function state_name(): string
-    {
-        return $this->state_obj() instanceof EE_State
-            ? $this->state_obj()->name()
-            : '';
-    }
-
-
-    /**
-     * either displays the state abbreviation or the state name, as determined
-     * by the "FHEE__EEI_Address__state__use_abbreviation" filter.
-     * defaults to abbreviation
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function state(): string
-    {
-        return apply_filters('FHEE__EEI_Address__state__use_abbreviation', true, $this->state_obj())
-            ? $this->state_abbrev()
-            : $this->state_name();
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function country_ID(): string
-    {
-        return (string) $this->get('CNT_ISO');
-    }
-
-
-    /**
-     * @return EE_Country|null
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function country_obj(): ?EE_Country
-    {
-        return $this->get_first_related('Country');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function country_name(): string
-    {
-        return $this->country_obj() instanceof EE_Country
-            ? $this->country_obj()->name()
-            : '';
-    }
-
-
-    /**
-     * either displays the country ISO2 code or the country name, as determined
-     * by the "FHEE__EEI_Address__country__use_abbreviation" filter.
-     * defaults to abbreviation
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function country(): string
-    {
-        return apply_filters('FHEE__EEI_Address__country__use_abbreviation', true, $this->country_obj())
-            ? $this->country_ID()
-            : $this->country_name();
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function zip(): string
-    {
-        return (string) $this->get('ATT_zip');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function email(): string
-    {
-        return (string) $this->get('ATT_email');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function phone(): string
-    {
-        return (string) $this->get('ATT_phone');
-    }
-
-
-    /**
-     * @return bool
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function deleted(): bool
-    {
-        return (bool) $this->get('ATT_deleted');
-    }
-
-
-    /**
-     * @param array $query_params
-     * @return EE_Registration[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function get_registrations(array $query_params = []): array
-    {
-        return $this->get_many_related('Registration', $query_params);
-    }
-
-
-    /**
-     * Gets the most recent registration of this attendee
-     *
-     * @return EE_Registration|null
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function get_most_recent_registration(): ?EE_Registration
-    {
-        return $this->get_first_related('Registration', ['order_by' => ['REG_date' => 'DESC']]);
-    }
-
-
-    /**
-     * Gets the most recent registration for this attend at this event
-     *
-     * @param int $event_id
-     * @return EE_Registration|null
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function get_most_recent_registration_for_event(int $event_id): ?EE_Registration
-    {
-        return $this->get_first_related(
-            'Registration',
-            [['EVT_ID' => $event_id], 'order_by' => ['REG_date' => 'DESC']]
-        );
-    }
-
-
-    /**
-     * returns any events attached to this attendee ($_Event property);
-     *
-     * @return EE_Event[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function events(): array
-    {
-        return $this->get_many_related('Event');
-    }
-
-
-    /**
-     * Gets the billing info array where keys match espresso_reg_page_billing_inputs(),
-     * and keys are their cleaned values. @param EE_Payment_Method $payment_method the _gateway_name property on the
-     * gateway class
-     *
-     * @return EE_Form_Section_Proper|null
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @see EE_Attendee::save_and_clean_billing_info_for_payment_method() which was used to save the billing info
-     */
-    public function billing_info_for_payment_method(EE_Payment_Method $payment_method): ?EE_Form_Section_Proper
-    {
-        $pm_type = $payment_method->type_obj();
-        if (! $pm_type instanceof EE_PMT_Base) {
-            return null;
-        }
-        $billing_info = $this->get_post_meta($this->get_billing_info_postmeta_name($payment_method), true);
-        if (! $billing_info) {
-            return null;
-        }
-        $billing_form = $pm_type->billing_form();
-        // double-check the form isn't totally hidden, in which case pretend there is no form
-        $form_totally_hidden = true;
-        foreach ($billing_form->inputs_in_subsections() as $input) {
-            if (! $input->get_display_strategy() instanceof EE_Hidden_Display_Strategy) {
-                $form_totally_hidden = false;
-                break;
-            }
-        }
-        if ($form_totally_hidden) {
-            return null;
-        }
-        if ($billing_form instanceof EE_Form_Section_Proper) {
-            $billing_form->receive_form_submission([$billing_form->name() => $billing_info], false);
-        }
-
-        return $billing_form;
-    }
-
-
-    /**
-     * Gets the postmeta key that holds this attendee's billing info for the
-     * specified payment method
-     *
-     * @param EE_Payment_Method $payment_method
-     * @return string
-     * @throws EE_Error
-     */
-    public function get_billing_info_postmeta_name(EE_Payment_Method $payment_method): string
-    {
-        return $payment_method->type_obj() instanceof EE_PMT_Base
-            ? 'billing_info_' . $payment_method->type_obj()->system_name()
-            : '';
-    }
-
-
-    /**
-     * Saves the billing info to the attendee.
-     *
-     * @param EE_Billing_Attendee_Info_Form|null $billing_form
-     * @param EE_Payment_Method                  $payment_method
-     * @return boolean
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @see EE_Attendee::billing_info_for_payment_method() which is used to retrieve it
-     */
-    public function save_and_clean_billing_info_for_payment_method(
-        ?EE_Billing_Attendee_Info_Form $billing_form,
-        EE_Payment_Method $payment_method
-    ): bool {
-        if (! $billing_form instanceof EE_Billing_Attendee_Info_Form) {
-            EE_Error::add_error(
-                esc_html__('Cannot save billing info because there is none.', 'event_espresso'),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-            return false;
-        }
-        $billing_form->clean_sensitive_data();
-        return update_post_meta(
-            $this->ID(),
-            $this->get_billing_info_postmeta_name($payment_method),
-            $billing_form->input_values(true)
-        );
-    }
-
-
-    /**
-     * Return the link to the admin details for the object.
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function get_admin_details_link(): string
-    {
-        return $this->get_admin_edit_link();
-    }
-
-
-    /**
-     * Returns the link to the editor for the object.  Sometimes this is the same as the details.
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public function get_admin_edit_link(): string
-    {
-        return EEH_URL::add_query_args_and_nonce(
-            [
-                'page'   => 'espresso_registrations',
-                'action' => 'edit_attendee',
-                'post'   => $this->ID(),
-            ],
-            admin_url('admin.php')
-        );
-    }
-
-
-    /**
-     * Returns the link to a settings page for the object.
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function get_admin_settings_link(): string
-    {
-        return $this->get_admin_edit_link();
-    }
-
-
-    /**
-     * Returns the link to the "overview" for the object (typically the "list table" view).
-     *
-     * @return string
-     */
-    public function get_admin_overview_link(): string
-    {
-        return EEH_URL::add_query_args_and_nonce(
-            [
-                'page'   => 'espresso_registrations',
-                'action' => 'contact_list',
-            ],
-            admin_url('admin.php')
-        );
-    }
+	/**
+	 * Sets some dynamic defaults
+	 *
+	 * @param array  $fieldValues
+	 * @param bool   $bydb
+	 * @param string $timezone
+	 * @param array  $date_formats
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	protected function __construct($fieldValues = null, $bydb = false, $timezone = null, $date_formats = [])
+	{
+		if (! isset($fieldValues['ATT_full_name'])) {
+			$fname                        = $fieldValues['ATT_fname'] ?? '';
+			$lname                        = $fieldValues['ATT_lname'] ?? '';
+			$fieldValues['ATT_full_name'] = "$fname $lname";
+		}
+		if (! isset($fieldValues['ATT_slug'])) {
+			// $fieldValues['ATT_slug'] = sanitize_key(wp_generate_password(20));
+			$fieldValues['ATT_slug'] = sanitize_title($fieldValues['ATT_full_name']);
+		}
+		if (! isset($fieldValues['ATT_short_bio']) && isset($fieldValues['ATT_bio'])) {
+			$fieldValues['ATT_short_bio'] = substr($fieldValues['ATT_bio'], 0, 50);
+		}
+		parent::__construct($fieldValues, $bydb, $timezone, $date_formats);
+	}
+
+
+	/**
+	 * @param array       $props_n_values     incoming values
+	 * @param string|null $timezone           incoming timezone (if not set the timezone set for the website
+	 *                                        will be
+	 *                                        used.)
+	 * @param array       $date_formats       incoming date_formats in an array where the first value is the
+	 *                                        date_format and the second value is the time format
+	 * @return EE_Attendee
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function new_instance(
+		array $props_n_values = [],
+		?string $timezone = '',
+		array $date_formats = []
+	): EE_Attendee {
+		$has_object = parent::_check_for_object($props_n_values, __CLASS__, $timezone, $date_formats);
+		return $has_object ?: new self($props_n_values, false, $timezone, $date_formats);
+	}
+
+
+	/**
+	 * @param array       $props_n_values incoming values from the database
+	 * @param string|null $timezone       incoming timezone as set by the model.
+	 *                                    If not set, the timezone for the website will be used.
+	 * @return EE_Attendee
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function new_instance_from_db(array $props_n_values = [], ?string $timezone = ''): EE_Attendee
+	{
+		return new self($props_n_values, true, $timezone);
+	}
+
+
+	/**
+	 * @param string|null $fname
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_fname(?string $fname = '')
+	{
+		$this->set('ATT_fname', (string) $fname);
+	}
+
+
+	/**
+	 * @param string|null $lname
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_lname(?string $lname = '')
+	{
+		$this->set('ATT_lname', (string) $lname);
+	}
+
+
+	/**
+	 * @param string|null $address
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_address(?string $address = '')
+	{
+		$this->set('ATT_address', (string) $address);
+	}
+
+
+	/**
+	 * @param string|null $address2
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_address2(?string $address2 = '')
+	{
+		$this->set('ATT_address2', (string) $address2);
+	}
+
+
+	/**
+	 * @param string|null $city
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_city(?string $city = '')
+	{
+		$this->set('ATT_city', $city);
+	}
+
+
+	/**
+	 * @param int|null $STA_ID
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_state(?int $STA_ID = 0)
+	{
+		$this->set('STA_ID', $STA_ID);
+	}
+
+
+	/**
+	 * @param string|null $CNT_ISO
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_country(?string $CNT_ISO = '')
+	{
+		$this->set('CNT_ISO', $CNT_ISO);
+	}
+
+
+	/**
+	 * @param string|null $zip
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_zip(?string $zip = '')
+	{
+		$this->set('ATT_zip', $zip);
+	}
+
+
+	/**
+	 * @param string|null $email
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_email(?string $email = '')
+	{
+		$this->set('ATT_email', $email);
+	}
+
+
+	/**
+	 * @param string|null $phone
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_phone(?string $phone = '')
+	{
+		$this->set('ATT_phone', $phone);
+	}
+
+
+	/**
+	 * @param bool|int|string|null $ATT_deleted
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function set_deleted($ATT_deleted = false)
+	{
+		$this->set('ATT_deleted', $ATT_deleted);
+	}
+
+
+	/**
+	 * Returns the value for the post_author id saved with the cpt
+	 *
+	 * @return int
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @since 4.5.0
+	 */
+	public function wp_user(): int
+	{
+		return (int) $this->get('ATT_author');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function fname(): string
+	{
+		return (string) $this->get('ATT_fname');
+	}
+
+
+	/**
+	 * echoes out the attendee's first name
+	 *
+	 * @return void
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function e_full_name()
+	{
+		echo esc_html($this->full_name());
+	}
+
+
+	/**
+	 * Returns the first and last name concatenated together with a space.
+	 *
+	 * @param bool $apply_html_entities
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function full_name(bool $apply_html_entities = false): string
+	{
+		$full_name = [$this->fname(), $this->lname()];
+		$full_name = array_filter($full_name);
+		$full_name = implode(' ', $full_name);
+		return $apply_html_entities
+			? htmlentities($full_name, ENT_QUOTES, 'UTF-8')
+			: $full_name;
+	}
+
+
+	/**
+	 * This returns the value of the `ATT_full_name` field which is usually equivalent to calling `full_name()` unless
+	 * the post_title field has been directly modified in the db for the post (espresso_attendees post type) for this
+	 * attendee.
+	 *
+	 * @param bool $apply_html_entities
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function ATT_full_name(bool $apply_html_entities = false): string
+	{
+		return $apply_html_entities
+			? htmlentities((string) $this->get('ATT_full_name'), ENT_QUOTES, 'UTF-8')
+			: (string) $this->get('ATT_full_name');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function lname(): string
+	{
+		return (string) $this->get('ATT_lname');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function bio(): string
+	{
+		return (string) $this->get('ATT_bio');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function short_bio(): string
+	{
+		return (string) $this->get('ATT_short_bio');
+	}
+
+
+	/**
+	 * Gets the attendee's full address as an array so client code can decide hwo to display it
+	 *
+	 * @return array numerically indexed, with each part of the address that is known.
+	 * Eg, if the user only responded to state and country,
+	 * it would be array(0=>'Alabama',1=>'USA')
+	 * @return array
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function full_address_as_array(): array
+	{
+		$full_address_array     = [];
+		$initial_address_fields = ['ATT_address', 'ATT_address2', 'ATT_city',];
+		foreach ($initial_address_fields as $address_field_name) {
+			$address_fields_value = $this->get($address_field_name);
+			if (! empty($address_fields_value)) {
+				$full_address_array[] = $address_fields_value;
+			}
+		}
+		// now handle state and country
+		$state_obj = $this->state_obj();
+		if ($state_obj instanceof EE_State) {
+			$full_address_array[] = $state_obj->name();
+		}
+		$country_obj = $this->country_obj();
+		if ($country_obj instanceof EE_Country) {
+			$full_address_array[] = $country_obj->name();
+		}
+		// lastly get the xip
+		$zip_value = $this->zip();
+		if (! empty($zip_value)) {
+			$full_address_array[] = $zip_value;
+		}
+		return $full_address_array;
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function address(): string
+	{
+		return (string) $this->get('ATT_address');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function address2(): string
+	{
+		return (string) $this->get('ATT_address2');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function city(): string
+	{
+		return (string) $this->get('ATT_city');
+	}
+
+
+	/**
+	 * @return int
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function state_ID(): int
+	{
+		return (int) $this->get('STA_ID');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function state_abbrev(): string
+	{
+		return $this->state_obj() instanceof EE_State
+			? $this->state_obj()->abbrev()
+			: '';
+	}
+
+
+	/**
+	 * @return EE_State|null
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function state_obj(): ?EE_State
+	{
+		return $this->get_first_related('State');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function state_name(): string
+	{
+		return $this->state_obj() instanceof EE_State
+			? $this->state_obj()->name()
+			: '';
+	}
+
+
+	/**
+	 * either displays the state abbreviation or the state name, as determined
+	 * by the "FHEE__EEI_Address__state__use_abbreviation" filter.
+	 * defaults to abbreviation
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function state(): string
+	{
+		return apply_filters('FHEE__EEI_Address__state__use_abbreviation', true, $this->state_obj())
+			? $this->state_abbrev()
+			: $this->state_name();
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function country_ID(): string
+	{
+		return (string) $this->get('CNT_ISO');
+	}
+
+
+	/**
+	 * @return EE_Country|null
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function country_obj(): ?EE_Country
+	{
+		return $this->get_first_related('Country');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function country_name(): string
+	{
+		return $this->country_obj() instanceof EE_Country
+			? $this->country_obj()->name()
+			: '';
+	}
+
+
+	/**
+	 * either displays the country ISO2 code or the country name, as determined
+	 * by the "FHEE__EEI_Address__country__use_abbreviation" filter.
+	 * defaults to abbreviation
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function country(): string
+	{
+		return apply_filters('FHEE__EEI_Address__country__use_abbreviation', true, $this->country_obj())
+			? $this->country_ID()
+			: $this->country_name();
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function zip(): string
+	{
+		return (string) $this->get('ATT_zip');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function email(): string
+	{
+		return (string) $this->get('ATT_email');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function phone(): string
+	{
+		return (string) $this->get('ATT_phone');
+	}
+
+
+	/**
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function deleted(): bool
+	{
+		return (bool) $this->get('ATT_deleted');
+	}
+
+
+	/**
+	 * @param array $query_params
+	 * @return EE_Registration[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function get_registrations(array $query_params = []): array
+	{
+		return $this->get_many_related('Registration', $query_params);
+	}
+
+
+	/**
+	 * Gets the most recent registration of this attendee
+	 *
+	 * @return EE_Registration|null
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function get_most_recent_registration(): ?EE_Registration
+	{
+		return $this->get_first_related('Registration', ['order_by' => ['REG_date' => 'DESC']]);
+	}
+
+
+	/**
+	 * Gets the most recent registration for this attend at this event
+	 *
+	 * @param int $event_id
+	 * @return EE_Registration|null
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function get_most_recent_registration_for_event(int $event_id): ?EE_Registration
+	{
+		return $this->get_first_related(
+			'Registration',
+			[['EVT_ID' => $event_id], 'order_by' => ['REG_date' => 'DESC']]
+		);
+	}
+
+
+	/**
+	 * returns any events attached to this attendee ($_Event property);
+	 *
+	 * @return EE_Event[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function events(): array
+	{
+		return $this->get_many_related('Event');
+	}
+
+
+	/**
+	 * Gets the billing info array where keys match espresso_reg_page_billing_inputs(),
+	 * and keys are their cleaned values. @param EE_Payment_Method $payment_method the _gateway_name property on the
+	 * gateway class
+	 *
+	 * @return EE_Form_Section_Proper|null
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @see EE_Attendee::save_and_clean_billing_info_for_payment_method() which was used to save the billing info
+	 */
+	public function billing_info_for_payment_method(EE_Payment_Method $payment_method): ?EE_Form_Section_Proper
+	{
+		$pm_type = $payment_method->type_obj();
+		if (! $pm_type instanceof EE_PMT_Base) {
+			return null;
+		}
+		$billing_info = $this->get_post_meta($this->get_billing_info_postmeta_name($payment_method), true);
+		if (! $billing_info) {
+			return null;
+		}
+		$billing_form = $pm_type->billing_form();
+		// double-check the form isn't totally hidden, in which case pretend there is no form
+		$form_totally_hidden = true;
+		foreach ($billing_form->inputs_in_subsections() as $input) {
+			if (! $input->get_display_strategy() instanceof EE_Hidden_Display_Strategy) {
+				$form_totally_hidden = false;
+				break;
+			}
+		}
+		if ($form_totally_hidden) {
+			return null;
+		}
+		if ($billing_form instanceof EE_Form_Section_Proper) {
+			$billing_form->receive_form_submission([$billing_form->name() => $billing_info], false);
+		}
+
+		return $billing_form;
+	}
+
+
+	/**
+	 * Gets the postmeta key that holds this attendee's billing info for the
+	 * specified payment method
+	 *
+	 * @param EE_Payment_Method $payment_method
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function get_billing_info_postmeta_name(EE_Payment_Method $payment_method): string
+	{
+		return $payment_method->type_obj() instanceof EE_PMT_Base
+			? 'billing_info_' . $payment_method->type_obj()->system_name()
+			: '';
+	}
+
+
+	/**
+	 * Saves the billing info to the attendee.
+	 *
+	 * @param EE_Billing_Attendee_Info_Form|null $billing_form
+	 * @param EE_Payment_Method                  $payment_method
+	 * @return boolean
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @see EE_Attendee::billing_info_for_payment_method() which is used to retrieve it
+	 */
+	public function save_and_clean_billing_info_for_payment_method(
+		?EE_Billing_Attendee_Info_Form $billing_form,
+		EE_Payment_Method $payment_method
+	): bool {
+		if (! $billing_form instanceof EE_Billing_Attendee_Info_Form) {
+			EE_Error::add_error(
+				esc_html__('Cannot save billing info because there is none.', 'event_espresso'),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+			return false;
+		}
+		$billing_form->clean_sensitive_data();
+		return update_post_meta(
+			$this->ID(),
+			$this->get_billing_info_postmeta_name($payment_method),
+			$billing_form->input_values(true)
+		);
+	}
+
+
+	/**
+	 * Return the link to the admin details for the object.
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function get_admin_details_link(): string
+	{
+		return $this->get_admin_edit_link();
+	}
+
+
+	/**
+	 * Returns the link to the editor for the object.  Sometimes this is the same as the details.
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public function get_admin_edit_link(): string
+	{
+		return EEH_URL::add_query_args_and_nonce(
+			[
+				'page'   => 'espresso_registrations',
+				'action' => 'edit_attendee',
+				'post'   => $this->ID(),
+			],
+			admin_url('admin.php')
+		);
+	}
+
+
+	/**
+	 * Returns the link to a settings page for the object.
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function get_admin_settings_link(): string
+	{
+		return $this->get_admin_edit_link();
+	}
+
+
+	/**
+	 * Returns the link to the "overview" for the object (typically the "list table" view).
+	 *
+	 * @return string
+	 */
+	public function get_admin_overview_link(): string
+	{
+		return EEH_URL::add_query_args_and_nonce(
+			[
+				'page'   => 'espresso_registrations',
+				'action' => 'contact_list',
+			],
+			admin_url('admin.php')
+		);
+	}
 }

core/db_classes/EE_Base_Class.class.php

Indentation +3358 added lines, -3358 removed lines

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

Spacing +121 added lines, -121 removed lines

@@ -150,7 +150,7 @@ 
         $this->_props_n_values_provided_in_constructor = $fieldValues;
         // verify client code has not passed any invalid field names
         foreach ($fieldValues as $field_name => $field_value) {
-            if (! isset($model_fields[ $field_name ])) {
+            if ( ! isset($model_fields[$field_name])) {
                 throw new EE_Error(
                     sprintf(
                         esc_html__(
@@ -168,7 +168,7 @@ 
         $date_format = null;
         $time_format = null;
         $this->_timezone = EEH_DTT_Helper::get_valid_timezone_string($timezone);
-        if (! empty($date_formats) && is_array($date_formats)) {
+        if ( ! empty($date_formats) && is_array($date_formats)) {
             [$date_format, $time_format] = $date_formats;
         }
         $this->set_date_format($date_format);
@@ -179,28 +179,28 @@ 
                 // client code has indicated these field values are from the database
                     $this->set_from_db(
                         $fieldName,
-                        $fieldValues[ $fieldName ] ?? null
+                        $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
                     $this->set(
                     $fieldName,
-                    $fieldValues[ $fieldName ] ?? null,
+                    $fieldValues[$fieldName] ?? null,
                     true
                 );
             }
         }
         // remember in entity mapper
-        if (! $bydb && $model->has_primary_key_field() && $this->ID()) {
+        if ( ! $bydb && $model->has_primary_key_field() && $this->ID()) {
             $model->add_to_entity_map($this);
         }
         // setup all the relations
         foreach ($model->relation_settings() as $relation_name => $relation_obj) {
             if ($relation_obj instanceof EE_Belongs_To_Relation) {
-                $this->_model_relations[ $relation_name ] = null;
+                $this->_model_relations[$relation_name] = null;
             } else {
-                $this->_model_relations[ $relation_name ] = array();
+                $this->_model_relations[$relation_name] = array();
             }
         }
         /**
@@ -252,10 +252,10 @@ 
     public function get_original($field_name)
     {
         if (
-            isset($this->_props_n_values_provided_in_constructor[ $field_name ])
+            isset($this->_props_n_values_provided_in_constructor[$field_name])
             && $field_settings = $this->get_model()->field_settings_for($field_name)
         ) {
-            return $field_settings->prepare_for_get($this->_props_n_values_provided_in_constructor[ $field_name ]);
+            return $field_settings->prepare_for_get($this->_props_n_values_provided_in_constructor[$field_name]);
         }
         return null;
     }
@@ -292,7 +292,7 @@ 
         // then don't do anything
         if (
             ! $use_default
-            && $this->_fields[ $field_name ] === $field_value
+            && $this->_fields[$field_name] === $field_value
             && $this->ID()
         ) {
             return;
@@ -300,7 +300,7 @@ 
         $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 ( ! $field_obj instanceof EE_Model_Field_Base) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -320,7 +320,7 @@ 
         $holder_of_value = $field_obj->prepare_for_set($field_value);
         // should the value be null?
         if (($field_value === null || $holder_of_value === null || $holder_of_value === '') && $use_default) {
-            $this->_fields[ $field_name ] = $field_obj->get_default_value();
+            $this->_fields[$field_name] = $field_obj->get_default_value();
             /**
              * To save having to refactor all the models, if a default value is used for a
              * EE_Datetime_Field, and that value is not null nor is it a DateTime
@@ -331,15 +331,15 @@ 
              */
             if (
                 $field_obj instanceof EE_Datetime_Field
-                && $this->_fields[ $field_name ] !== null
-                && ! $this->_fields[ $field_name ] instanceof DateTime
+                && $this->_fields[$field_name] !== null
+                && ! $this->_fields[$field_name] instanceof DateTime
             ) {
-                empty($this->_fields[ $field_name ])
+                empty($this->_fields[$field_name])
                     ? $this->set($field_name, time())
-                    : $this->set($field_name, $this->_fields[ $field_name ]);
+                    : $this->set($field_name, $this->_fields[$field_name]);
             }
         } else {
-            $this->_fields[ $field_name ] = $holder_of_value;
+            $this->_fields[$field_name] = $holder_of_value;
         }
         // if we're not in the constructor...
         // now check if what we set was a primary key
@@ -401,7 +401,7 @@ 
             } else {
                 $field_value = $field_obj->prepare_for_set_from_db($field_value_from_db);
             }
-            $this->_fields[ $field_name ] = $field_value;
+            $this->_fields[$field_name] = $field_value;
             $this->_clear_cached_property($field_name);
         }
     }
@@ -427,8 +427,8 @@ 
      */
     public function getCustomSelect($alias)
     {
-        return isset($this->custom_selection_results[ $alias ])
-            ? $this->custom_selection_results[ $alias ]
+        return isset($this->custom_selection_results[$alias])
+            ? $this->custom_selection_results[$alias]
             : null;
     }
 
@@ -515,8 +515,8 @@ 
         foreach ($model_fields as $field_name => $field_obj) {
             if ($field_obj instanceof EE_Datetime_Field) {
                 $field_obj->set_timezone($this->_timezone);
-                if (isset($this->_fields[ $field_name ]) && $this->_fields[ $field_name ] instanceof DateTime) {
-                    EEH_DTT_Helper::setTimezone($this->_fields[ $field_name ], new DateTimeZone($this->_timezone));
+                if (isset($this->_fields[$field_name]) && $this->_fields[$field_name] instanceof DateTime) {
+                    EEH_DTT_Helper::setTimezone($this->_fields[$field_name], new DateTimeZone($this->_timezone));
                 }
             }
         }
@@ -576,7 +576,7 @@ 
      */
     public function get_format($full = true)
     {
-        return $full ? $this->_dt_frmt . ' ' . $this->_tm_frmt : array($this->_dt_frmt, $this->_tm_frmt);
+        return $full ? $this->_dt_frmt.' '.$this->_tm_frmt : array($this->_dt_frmt, $this->_tm_frmt);
     }
 
 
@@ -602,11 +602,11 @@ 
     public function cache($relationName = '', $object_to_cache = null, $cache_id = null)
     {
         // its entirely possible that there IS no related object yet in which case there is nothing to cache.
-        if (! $object_to_cache instanceof EE_Base_Class) {
+        if ( ! $object_to_cache instanceof EE_Base_Class) {
             return false;
         }
         // also get "how" the object is related, or throw an error
-        if (! $relationship_to_model = $this->get_model()->related_settings_for($relationName)) {
+        if ( ! $relationship_to_model = $this->get_model()->related_settings_for($relationName)) {
             throw new EE_Error(
                 sprintf(
                     esc_html__('There is no relationship to %s on a %s. Cannot cache it', 'event_espresso'),
@@ -620,38 +620,38 @@ 
             // if it's a "belongs to" relationship, then there's only one related model object
             // eg, if this is a registration, there's only 1 attendee for it
             // so for these model objects just set it to be cached
-            $this->_model_relations[ $relationName ] = $object_to_cache;
+            $this->_model_relations[$relationName] = $object_to_cache;
             $return = true;
         } else {
             // otherwise, this is the "many" side of a one to many relationship,
             // so we'll add the object to the array of related objects for that type.
             // eg: if this is an event, there are many registrations for that event,
             // so we cache the registrations in an array
-            if (! is_array($this->_model_relations[ $relationName ])) {
+            if ( ! is_array($this->_model_relations[$relationName])) {
                 // if for some reason, the cached item is a model object,
                 // then stick that in the array, otherwise start with an empty array
-                $this->_model_relations[ $relationName ] = $this->_model_relations[ $relationName ]
+                $this->_model_relations[$relationName] = $this->_model_relations[$relationName]
                                                            instanceof
                                                            EE_Base_Class
-                    ? array($this->_model_relations[ $relationName ]) : array();
+                    ? array($this->_model_relations[$relationName]) : array();
             }
             // first check for a cache_id which is normally empty
-            if (! empty($cache_id)) {
+            if ( ! empty($cache_id)) {
                 // if the cache_id exists, then it means we are purposely trying to cache this
                 // with a known key that can then be used to retrieve the object later on
-                $this->_model_relations[ $relationName ][ $cache_id ] = $object_to_cache;
+                $this->_model_relations[$relationName][$cache_id] = $object_to_cache;
                 $return = $cache_id;
             } elseif ($object_to_cache->ID()) {
                 // OR the cached object originally came from the db, so let's just use it's PK for an ID
-                $this->_model_relations[ $relationName ][ $object_to_cache->ID() ] = $object_to_cache;
+                $this->_model_relations[$relationName][$object_to_cache->ID()] = $object_to_cache;
                 $return = $object_to_cache->ID();
             } else {
                 // OR it's a new object with no ID, so just throw it in the array with an auto-incremented ID
-                $this->_model_relations[ $relationName ][] = $object_to_cache;
+                $this->_model_relations[$relationName][] = $object_to_cache;
                 // move the internal pointer to the end of the array
-                end($this->_model_relations[ $relationName ]);
+                end($this->_model_relations[$relationName]);
                 // and grab the key so that we can return it
-                $return = key($this->_model_relations[ $relationName ]);
+                $return = key($this->_model_relations[$relationName]);
             }
         }
         return $return;
@@ -677,7 +677,7 @@ 
         // first make sure this property exists
         $this->get_model()->field_settings_for($fieldname);
         $cache_type = empty($cache_type) ? 'standard' : $cache_type;
-        $this->_cached_properties[ $fieldname ][ $cache_type ] = $value;
+        $this->_cached_properties[$fieldname][$cache_type] = $value;
     }
 
 
@@ -706,9 +706,9 @@ 
         $model = $this->get_model();
         $model->field_settings_for($fieldname);
         $cache_type = $pretty ? 'pretty' : 'standard';
-        $cache_type .= ! empty($extra_cache_ref) ? '_' . $extra_cache_ref : '';
-        if (isset($this->_cached_properties[ $fieldname ][ $cache_type ])) {
-            return $this->_cached_properties[ $fieldname ][ $cache_type ];
+        $cache_type .= ! empty($extra_cache_ref) ? '_'.$extra_cache_ref : '';
+        if (isset($this->_cached_properties[$fieldname][$cache_type])) {
+            return $this->_cached_properties[$fieldname][$cache_type];
         }
         $value = $this->_get_fresh_property($fieldname, $pretty, $extra_cache_ref);
         $this->_set_cached_property($fieldname, $value, $cache_type);
@@ -736,12 +736,12 @@ 
         if ($field_obj instanceof EE_Datetime_Field) {
             $this->_prepare_datetime_field($field_obj, $pretty, $extra_cache_ref);
         }
-        if (! isset($this->_fields[ $fieldname ])) {
-            $this->_fields[ $fieldname ] = null;
+        if ( ! isset($this->_fields[$fieldname])) {
+            $this->_fields[$fieldname] = null;
         }
         return $pretty
-            ? $field_obj->prepare_for_pretty_echoing($this->_fields[ $fieldname ], $extra_cache_ref)
-            : $field_obj->prepare_for_get($this->_fields[ $fieldname ]);
+            ? $field_obj->prepare_for_pretty_echoing($this->_fields[$fieldname], $extra_cache_ref)
+            : $field_obj->prepare_for_get($this->_fields[$fieldname]);
     }
 
 
@@ -797,8 +797,8 @@ 
      */
     protected function _clear_cached_property($property_name)
     {
-        if (isset($this->_cached_properties[ $property_name ])) {
-            unset($this->_cached_properties[ $property_name ]);
+        if (isset($this->_cached_properties[$property_name])) {
+            unset($this->_cached_properties[$property_name]);
         }
     }
 
@@ -850,7 +850,7 @@ 
     {
         $relationship_to_model = $this->get_model()->related_settings_for($relationName);
         $index_in_cache = '';
-        if (! $relationship_to_model) {
+        if ( ! $relationship_to_model) {
             throw new EE_Error(
                 sprintf(
                     esc_html__('There is no relationship to %s on a %s. Cannot clear that cache', 'event_espresso'),
@@ -861,10 +861,10 @@ 
         }
         if ($clear_all) {
             $obj_removed = true;
-            $this->_model_relations[ $relationName ] = null;
+            $this->_model_relations[$relationName] = null;
         } elseif ($relationship_to_model instanceof EE_Belongs_To_Relation) {
-            $obj_removed = $this->_model_relations[ $relationName ];
-            $this->_model_relations[ $relationName ] = null;
+            $obj_removed = $this->_model_relations[$relationName];
+            $this->_model_relations[$relationName] = null;
         } else {
             if (
                 $object_to_remove_or_index_into_array instanceof EE_Base_Class
@@ -872,12 +872,12 @@ 
             ) {
                 $index_in_cache = $object_to_remove_or_index_into_array->ID();
                 if (
-                    is_array($this->_model_relations[ $relationName ])
-                    && ! isset($this->_model_relations[ $relationName ][ $index_in_cache ])
+                    is_array($this->_model_relations[$relationName])
+                    && ! isset($this->_model_relations[$relationName][$index_in_cache])
                 ) {
                     $index_found_at = null;
                     // find this object in the array even though it has a different key
-                    foreach ($this->_model_relations[ $relationName ] as $index => $obj) {
+                    foreach ($this->_model_relations[$relationName] as $index => $obj) {
                         /** @noinspection TypeUnsafeComparisonInspection */
                         if (
                             $obj instanceof EE_Base_Class
@@ -911,9 +911,9 @@ 
             }
             // supposedly we've found it. But it could just be that the client code
             // provided a bad index/object
-            if (isset($this->_model_relations[ $relationName ][ $index_in_cache ])) {
-                $obj_removed = $this->_model_relations[ $relationName ][ $index_in_cache ];
-                unset($this->_model_relations[ $relationName ][ $index_in_cache ]);
+            if (isset($this->_model_relations[$relationName][$index_in_cache])) {
+                $obj_removed = $this->_model_relations[$relationName][$index_in_cache];
+                unset($this->_model_relations[$relationName][$index_in_cache]);
             } else {
                 // that thing was never cached anyways.
                 $obj_removed = null;
@@ -944,7 +944,7 @@ 
         $current_cache_id = ''
     ) {
         // verify that incoming object is of the correct type
-        $obj_class = 'EE_' . $relationName;
+        $obj_class = 'EE_'.$relationName;
         if ($newly_saved_object instanceof $obj_class) {
             /* @type EE_Base_Class $newly_saved_object */
             // now get the type of relation
@@ -952,18 +952,18 @@ 
             // if this is a 1:1 relationship
             if ($relationship_to_model instanceof EE_Belongs_To_Relation) {
                 // then just replace the cached object with the newly saved object
-                $this->_model_relations[ $relationName ] = $newly_saved_object;
+                $this->_model_relations[$relationName] = $newly_saved_object;
                 return true;
                 // or if it's some kind of sordid feral polyamorous relationship...
             }
             if (
-                is_array($this->_model_relations[ $relationName ])
-                && isset($this->_model_relations[ $relationName ][ $current_cache_id ])
+                is_array($this->_model_relations[$relationName])
+                && isset($this->_model_relations[$relationName][$current_cache_id])
             ) {
                 // then remove the current cached item
-                unset($this->_model_relations[ $relationName ][ $current_cache_id ]);
+                unset($this->_model_relations[$relationName][$current_cache_id]);
                 // and cache the newly saved object using it's new ID
-                $this->_model_relations[ $relationName ][ $newly_saved_object->ID() ] = $newly_saved_object;
+                $this->_model_relations[$relationName][$newly_saved_object->ID()] = $newly_saved_object;
                 return true;
             }
         }
@@ -980,8 +980,8 @@ 
      */
     public function get_one_from_cache($relationName)
     {
-        $cached_array_or_object = isset($this->_model_relations[ $relationName ])
-            ? $this->_model_relations[ $relationName ]
+        $cached_array_or_object = isset($this->_model_relations[$relationName])
+            ? $this->_model_relations[$relationName]
             : null;
         if (is_array($cached_array_or_object)) {
             return array_shift($cached_array_or_object);
@@ -1004,7 +1004,7 @@ 
      */
     public function get_all_from_cache($relationName)
     {
-        $objects = isset($this->_model_relations[ $relationName ]) ? $this->_model_relations[ $relationName ] : array();
+        $objects = isset($this->_model_relations[$relationName]) ? $this->_model_relations[$relationName] : array();
         // if the result is not an array, but exists, make it an array
         $objects = is_array($objects) ? $objects : array($objects);
         // bugfix for https://events.codebasehq.com/projects/event-espresso/tickets/7143
@@ -1192,9 +1192,9 @@ 
     public function get_raw($field_name)
     {
         $field_settings = $this->get_model()->field_settings_for($field_name);
-        return $field_settings instanceof EE_Datetime_Field && $this->_fields[ $field_name ] instanceof DateTime
-            ? $this->_fields[ $field_name ]->format('U')
-            : $this->_fields[ $field_name ];
+        return $field_settings instanceof EE_Datetime_Field && $this->_fields[$field_name] instanceof DateTime
+            ? $this->_fields[$field_name]->format('U')
+            : $this->_fields[$field_name];
     }
 
 
@@ -1216,7 +1216,7 @@ 
     public function get_DateTime_object($field_name)
     {
         $field_settings = $this->get_model()->field_settings_for($field_name);
-        if (! $field_settings instanceof EE_Datetime_Field) {
+        if ( ! $field_settings instanceof EE_Datetime_Field) {
             EE_Error::add_error(
                 sprintf(
                     esc_html__(
@@ -1231,8 +1231,8 @@ 
             );
             return false;
         }
-        return isset($this->_fields[ $field_name ]) && $this->_fields[ $field_name ] instanceof DateTime
-            ? clone $this->_fields[ $field_name ]
+        return isset($this->_fields[$field_name]) && $this->_fields[$field_name] instanceof DateTime
+            ? clone $this->_fields[$field_name]
             : null;
     }
 
@@ -1476,7 +1476,7 @@ 
      */
     public function get_i18n_datetime($field_name, $format = '')
     {
-        $format = empty($format) ? $this->_dt_frmt . ' ' . $this->_tm_frmt : $format;
+        $format = empty($format) ? $this->_dt_frmt.' '.$this->_tm_frmt : $format;
         return date_i18n(
             $format,
             EEH_DTT_Helper::get_timestamp_with_offset(
@@ -1588,21 +1588,21 @@ 
         $field->set_time_format($this->_tm_frmt);
         switch ($what) {
             case 'T':
-                $this->_fields[ $field_name ] = $field->prepare_for_set_with_new_time(
+                $this->_fields[$field_name] = $field->prepare_for_set_with_new_time(
                     $datetime_value,
-                    $this->_fields[ $field_name ]
+                    $this->_fields[$field_name]
                 );
                 $this->_has_changes = true;
                 break;
             case 'D':
-                $this->_fields[ $field_name ] = $field->prepare_for_set_with_new_date(
+                $this->_fields[$field_name] = $field->prepare_for_set_with_new_date(
                     $datetime_value,
-                    $this->_fields[ $field_name ]
+                    $this->_fields[$field_name]
                 );
                 $this->_has_changes = true;
                 break;
             case 'B':
-                $this->_fields[ $field_name ] = $field->prepare_for_set($datetime_value);
+                $this->_fields[$field_name] = $field->prepare_for_set($datetime_value);
                 $this->_has_changes = true;
                 break;
         }
@@ -1645,7 +1645,7 @@ 
         $this->set_timezone($timezone);
         $fn = (array) $field_name;
         $args = array_merge($fn, (array) $args);
-        if (! method_exists($this, $callback)) {
+        if ( ! method_exists($this, $callback)) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -1657,7 +1657,7 @@ 
             );
         }
         $args = (array) $args;
-        $return = $prepend . call_user_func_array(array($this, $callback), $args) . $append;
+        $return = $prepend.call_user_func_array(array($this, $callback), $args).$append;
         $this->set_timezone($original_timezone);
         return $return;
     }
@@ -1772,8 +1772,8 @@ 
     {
         $model = $this->get_model();
         foreach ($model->relation_settings() as $relation_name => $relation_obj) {
-            if (! empty($this->_model_relations[ $relation_name ])) {
-                $related_objects = $this->_model_relations[ $relation_name ];
+            if ( ! empty($this->_model_relations[$relation_name])) {
+                $related_objects = $this->_model_relations[$relation_name];
                 if ($relation_obj instanceof EE_Belongs_To_Relation) {
                     // this relation only stores a single model object, not an array
                     // but let's make it consistent
@@ -1832,7 +1832,7 @@ 
             $this->set($column, $value);
         }
         // no changes ? then don't do anything
-        if (! $this->_has_changes && $this->ID() && $model->get_primary_key_field()->is_auto_increment()) {
+        if ( ! $this->_has_changes && $this->ID() && $model->get_primary_key_field()->is_auto_increment()) {
             return 0;
         }
         /**
@@ -1842,7 +1842,7 @@ 
          * @param EE_Base_Class $model_object the model object about to be saved.
          */
         do_action('AHEE__EE_Base_Class__save__begin', $this);
-        if (! $this->allow_persist()) {
+        if ( ! $this->allow_persist()) {
             return 0;
         }
         // now get current attribute values
@@ -1857,10 +1857,10 @@ 
         if ($model->has_primary_key_field()) {
             if ($model->get_primary_key_field()->is_auto_increment()) {
                 // ok check if it's set, if so: update; if not, insert
-                if (! empty($save_cols_n_values[ $model->primary_key_name() ])) {
+                if ( ! empty($save_cols_n_values[$model->primary_key_name()])) {
                     $results = $model->update_by_ID($save_cols_n_values, $this->ID());
                 } else {
-                    unset($save_cols_n_values[ $model->primary_key_name() ]);
+                    unset($save_cols_n_values[$model->primary_key_name()]);
                     $results = $model->insert($save_cols_n_values);
                     if ($results) {
                         // if successful, set the primary key
@@ -1870,7 +1870,7 @@ 
                         // will get added to the mapper before we can add this one!
                         // but if we just avoid using the SET method, all that headache can be avoided
                         $pk_field_name = $model->primary_key_name();
-                        $this->_fields[ $pk_field_name ] = $results;
+                        $this->_fields[$pk_field_name] = $results;
                         $this->_clear_cached_property($pk_field_name);
                         $model->add_to_entity_map($this);
                         $this->_update_cached_related_model_objs_fks();
@@ -1887,8 +1887,8 @@ 
                                     'event_espresso'
                                 ),
                                 get_class($this),
-                                get_class($model) . '::instance()->add_to_entity_map()',
-                                get_class($model) . '::instance()->get_one_by_ID()',
+                                get_class($model).'::instance()->add_to_entity_map()',
+                                get_class($model).'::instance()->get_one_by_ID()',
                                 '<br />'
                             )
                         );
@@ -1990,27 +1990,27 @@ 
     public function save_new_cached_related_model_objs()
     {
         // make sure this has been saved
-        if (! $this->ID()) {
+        if ( ! $this->ID()) {
             $id = $this->save();
         } else {
             $id = $this->ID();
         }
         // now save all the NEW cached model objects  (ie they don't exist in the DB)
         foreach ($this->get_model()->relation_settings() as $relationName => $relationObj) {
-            if ($this->_model_relations[ $relationName ]) {
+            if ($this->_model_relations[$relationName]) {
                 // is this a relation where we should expect just ONE related object (ie, EE_Belongs_To_relation)
                 // or MANY related objects (ie, EE_HABTM_Relation or EE_Has_Many_Relation)?
                 /* @var $related_model_obj EE_Base_Class */
                 if ($relationObj instanceof EE_Belongs_To_Relation) {
                     // add a relation to that relation type (which saves the appropriate thing in the process)
                     // but ONLY if it DOES NOT exist in the DB
-                    $related_model_obj = $this->_model_relations[ $relationName ];
+                    $related_model_obj = $this->_model_relations[$relationName];
                     // if( ! $related_model_obj->ID()){
                     $this->_add_relation_to($related_model_obj, $relationName);
                     $related_model_obj->save_new_cached_related_model_objs();
                     // }
                 } else {
-                    foreach ($this->_model_relations[ $relationName ] as $related_model_obj) {
+                    foreach ($this->_model_relations[$relationName] as $related_model_obj) {
                         // add a relation to that relation type (which saves the appropriate thing in the process)
                         // but ONLY if it DOES NOT exist in the DB
                         // if( ! $related_model_obj->ID()){
@@ -2037,7 +2037,7 @@ 
      */
     public function get_model()
     {
-        if (! $this->_model) {
+        if ( ! $this->_model) {
             $modelName = self::_get_model_classname(get_class($this));
             $this->_model = self::_get_model_instance_with_name($modelName, $this->_timezone);
         } else {
@@ -2063,9 +2063,9 @@ 
         $primary_id_ref = self::_get_primary_key_name($classname);
         if (
             array_key_exists($primary_id_ref, $props_n_values)
-            && ! empty($props_n_values[ $primary_id_ref ])
+            && ! empty($props_n_values[$primary_id_ref])
         ) {
-            $id = $props_n_values[ $primary_id_ref ];
+            $id = $props_n_values[$primary_id_ref];
             return self::_get_model($classname)->get_from_entity_map($id);
         }
         return false;
@@ -2100,10 +2100,10 @@ 
             $primary_id_ref = self::_get_primary_key_name($classname);
             if (
                 array_key_exists($primary_id_ref, $props_n_values)
-                && ! empty($props_n_values[ $primary_id_ref ])
+                && ! empty($props_n_values[$primary_id_ref])
             ) {
                 $existing = $model->get_one_by_ID(
-                    $props_n_values[ $primary_id_ref ]
+                    $props_n_values[$primary_id_ref]
                 );
             }
         } elseif ($model->has_all_combined_primary_key_fields($props_n_values)) {
@@ -2115,7 +2115,7 @@ 
         }
         if ($existing) {
             // set date formats if present before setting values
-            if (! empty($date_formats) && is_array($date_formats)) {
+            if ( ! empty($date_formats) && is_array($date_formats)) {
                 $existing->set_date_format($date_formats[0]);
                 $existing->set_time_format($date_formats[1]);
             } else {
@@ -2148,7 +2148,7 @@ 
     protected static function _get_model($classname, $timezone = null)
     {
         // find model for this class
-        if (! $classname) {
+        if ( ! $classname) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -2196,7 +2196,7 @@ 
     {
         return strpos((string) $model_name, 'EE_') === 0
             ? str_replace('EE_', 'EEM_', $model_name)
-            : 'EEM_' . $model_name;
+            : 'EEM_'.$model_name;
     }
 
 
@@ -2213,7 +2213,7 @@ 
      */
     protected static function _get_primary_key_name($classname = null)
     {
-        if (! $classname) {
+        if ( ! $classname) {
             throw new EE_Error(
                 sprintf(
                     esc_html__('What were you thinking calling _get_primary_key_name(%s)', 'event_espresso'),
@@ -2243,7 +2243,7 @@ 
         $model = $this->get_model();
         // now that we know the name of the variable, use a variable variable to get its value and return its
         if ($model->has_primary_key_field()) {
-            return $this->_fields[ $model->primary_key_name() ];
+            return $this->_fields[$model->primary_key_name()];
         }
         return $model->get_index_primary_key_string($this->_fields);
     }
@@ -2317,7 +2317,7 @@ 
             }
         } else {
             // this thing doesn't exist in the DB,  so just cache it
-            if (! $otherObjectModelObjectOrID instanceof EE_Base_Class) {
+            if ( ! $otherObjectModelObjectOrID instanceof EE_Base_Class) {
                 throw new EE_Error(
                     sprintf(
                         esc_html__(
@@ -2482,7 +2482,7 @@ 
             } else {
                 // did we already cache the result of this query?
                 $cached_results = $this->get_all_from_cache($relationName);
-                if (! $cached_results) {
+                if ( ! $cached_results) {
                     $related_model_objects = $this->get_model()->get_all_related(
                         $this,
                         $relationName,
@@ -2593,7 +2593,7 @@ 
             } else {
                 // first, check if we've already cached the result of this query
                 $cached_result = $this->get_one_from_cache($relationName);
-                if (! $cached_result) {
+                if ( ! $cached_result) {
                     $related_model_object = $model->get_first_related(
                         $this,
                         $relationName,
@@ -2617,7 +2617,7 @@ 
             }
             // this doesn't exist in the DB and apparently the thing it belongs to doesn't either,
             // just get what's cached on this object
-            if (! $related_model_object) {
+            if ( ! $related_model_object) {
                 $related_model_object = $this->get_one_from_cache($relationName);
             }
         }
@@ -2699,7 +2699,7 @@ 
      */
     public function is_set($field_name)
     {
-        return isset($this->_fields[ $field_name ]);
+        return isset($this->_fields[$field_name]);
     }
 
 
@@ -2715,7 +2715,7 @@ 
     {
         foreach ((array) $properties as $property_name) {
             // first make sure this property exists
-            if (! $this->_fields[ $property_name ]) {
+            if ( ! $this->_fields[$property_name]) {
                 throw new EE_Error(
                     sprintf(
                         esc_html__(
@@ -2747,7 +2747,7 @@ 
         $properties = array();
         // remove prepended underscore
         foreach ($fields as $field_name => $settings) {
-            $properties[ $field_name ] = $this->get($field_name);
+            $properties[$field_name] = $this->get($field_name);
         }
         return $properties;
     }
@@ -2784,7 +2784,7 @@ 
     {
         $className = get_class($this);
         $tagName = "FHEE__{$className}__{$methodName}";
-        if (! has_filter($tagName)) {
+        if ( ! has_filter($tagName)) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -2829,7 +2829,7 @@ 
             $query_params[0]['EXM_value'] = $meta_value;
         }
         $existing_rows_like_that = EEM_Extra_Meta::instance()->get_all($query_params);
-        if (! $existing_rows_like_that) {
+        if ( ! $existing_rows_like_that) {
             return $this->add_extra_meta($meta_key, $meta_value);
         }
         foreach ($existing_rows_like_that as $existing_row) {
@@ -2928,7 +2928,7 @@ 
      */
     public function get_extra_meta(string $meta_key, bool $single = false, $default = null, ?array $extra_where = [])
     {
-        $query_params = [ $extra_where + ['EXM_key' => $meta_key] ];
+        $query_params = [$extra_where + ['EXM_key' => $meta_key]];
         if ($single) {
             $result = $this->get_first_related('Extra_Meta', $query_params);
             if ($result instanceof EE_Extra_Meta) {
@@ -2940,7 +2940,7 @@ 
                 $values = [];
                 foreach ($results as $result) {
                     if ($result instanceof EE_Extra_Meta) {
-                        $values[ $result->ID() ] = $result->value();
+                        $values[$result->ID()] = $result->value();
                     }
                 }
                 return $values;
@@ -2985,17 +2985,17 @@ 
             );
             foreach ($extra_meta_objs as $extra_meta_obj) {
                 if ($extra_meta_obj instanceof EE_Extra_Meta) {
-                    $return_array[ $extra_meta_obj->key() ] = $extra_meta_obj->value();
+                    $return_array[$extra_meta_obj->key()] = $extra_meta_obj->value();
                 }
             }
         } else {
             $extra_meta_objs = $this->get_many_related('Extra_Meta');
             foreach ($extra_meta_objs as $extra_meta_obj) {
                 if ($extra_meta_obj instanceof EE_Extra_Meta) {
-                    if (! isset($return_array[ $extra_meta_obj->key() ])) {
-                        $return_array[ $extra_meta_obj->key() ] = [];
+                    if ( ! isset($return_array[$extra_meta_obj->key()])) {
+                        $return_array[$extra_meta_obj->key()] = [];
                     }
-                    $return_array[ $extra_meta_obj->key() ][ $extra_meta_obj->ID() ] = $extra_meta_obj->value();
+                    $return_array[$extra_meta_obj->key()][$extra_meta_obj->ID()] = $extra_meta_obj->value();
                 }
             }
         }
@@ -3076,8 +3076,8 @@ 
                             'event_espresso'
                         ),
                         $this->ID(),
-                        get_class($this->get_model()) . '::instance()->add_to_entity_map()',
-                        get_class($this->get_model()) . '::instance()->refresh_entity_map()'
+                        get_class($this->get_model()).'::instance()->add_to_entity_map()',
+                        get_class($this->get_model()).'::instance()->refresh_entity_map()'
                     )
                 );
             }
@@ -3110,7 +3110,7 @@ 
     {
         // First make sure this model object actually exists in the DB. It would be silly to try to update it in the DB
         // if it wasn't even there to start off.
-        if (! $this->ID()) {
+        if ( ! $this->ID()) {
             $this->save();
         }
         global $wpdb;
@@ -3340,7 +3340,7 @@ 
         $model = $this->get_model();
         foreach ($model->relation_settings() as $relation_name => $relation_obj) {
             if ($relation_obj instanceof EE_Belongs_To_Relation) {
-                $classname = 'EE_' . $model->get_this_model_name();
+                $classname = 'EE_'.$model->get_this_model_name();
                 if (
                     $this->get_one_from_cache($relation_name) instanceof $classname
                     && $this->get_one_from_cache($relation_name)->ID()
@@ -3381,7 +3381,7 @@ 
         // handle DateTimes (this is handled in here because there's no one specific child class that uses datetimes).
         foreach ($this->_fields as $field => $value) {
             if ($value instanceof DateTime) {
-                $this->_fields[ $field ] = clone $value;
+                $this->_fields[$field] = clone $value;
             }
         }
     }

core/db_classes/EE_Line_Item.class.php

Indentation +1659 added lines, -1659 removed lines

@@ -15,1663 +15,1663 @@
  */
 class EE_Line_Item extends EE_Base_Class
 {
-    /**
-     * for children line items (currently not a normal relation)
-     *
-     * @type EE_Line_Item[]
-     */
-    protected $_children = array();
-
-    /**
-     * for the parent line item
-     *
-     * @var EE_Line_Item
-     */
-    protected $_parent;
-
-    /**
-     * @var LineItemCalculator
-     */
-    protected $calculator;
-
-
-    /**
-     * @param array  $props_n_values          incoming values
-     * @param string $timezone                incoming timezone (if not set the timezone set for the website will be
-     *                                        used.)
-     * @param array  $date_formats            incoming date_formats in an array where the first value is the
-     *                                        date_format and the second value is the time format
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function new_instance($props_n_values = array(), $timezone = null, $date_formats = array())
-    {
-        $has_object = parent::_check_for_object(
-            $props_n_values,
-            __CLASS__,
-            $timezone,
-            $date_formats
-        );
-        return $has_object
-            ? $has_object
-            : new self($props_n_values, false, $timezone);
-    }
-
-
-    /**
-     * @param array  $props_n_values  incoming values from the database
-     * @param string $timezone        incoming timezone as set by the model.  If not set the timezone for
-     *                                the website will be used.
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function new_instance_from_db($props_n_values = array(), $timezone = null)
-    {
-        return new self($props_n_values, true, $timezone);
-    }
-
-
-    /**
-     * Adds some defaults if they're not specified
-     *
-     * @param array  $fieldValues
-     * @param bool   $bydb
-     * @param string $timezone
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    protected function __construct($fieldValues = array(), $bydb = false, $timezone = '')
-    {
-        $this->calculator = LoaderFactory::getShared(LineItemCalculator::class);
-        parent::__construct($fieldValues, $bydb, $timezone);
-        if (! $this->get('LIN_code')) {
-            $this->set_code($this->generate_code());
-        }
-    }
-
-
-    public function __wakeup()
-    {
-        $this->calculator = LoaderFactory::getShared(LineItemCalculator::class);
-        parent::__wakeup();
-    }
-
-
-    /**
-     * Gets ID
-     *
-     * @return int
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function ID()
-    {
-        return $this->get('LIN_ID');
-    }
-
-
-    /**
-     * Gets TXN_ID
-     *
-     * @return int
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function TXN_ID()
-    {
-        return $this->get('TXN_ID');
-    }
-
-
-    /**
-     * Sets TXN_ID
-     *
-     * @param int $TXN_ID
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_TXN_ID($TXN_ID)
-    {
-        $this->set('TXN_ID', $TXN_ID);
-    }
-
-
-    /**
-     * Gets name
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function name()
-    {
-        $name = $this->get('LIN_name');
-        if (! $name) {
-            $name = ucwords(str_replace('-', ' ', $this->type()));
-        }
-        return $name;
-    }
-
-
-    /**
-     * Sets name
-     *
-     * @param string $name
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_name($name)
-    {
-        $this->set('LIN_name', $name);
-    }
-
-
-    /**
-     * Gets desc
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function desc()
-    {
-        return $this->get('LIN_desc');
-    }
-
-
-    /**
-     * Sets desc
-     *
-     * @param string $desc
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_desc($desc)
-    {
-        $this->set('LIN_desc', $desc);
-    }
-
-
-    /**
-     * Gets quantity
-     *
-     * @return int
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function quantity(): int
-    {
-        return (int) $this->get('LIN_quantity');
-    }
-
-
-    /**
-     * Sets quantity
-     *
-     * @param int $quantity
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_quantity($quantity)
-    {
-        $this->set('LIN_quantity', max($quantity, 0));
-    }
-
-
-    /**
-     * Gets item_id
-     *
-     * @return int
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function OBJ_ID()
-    {
-        return $this->get('OBJ_ID');
-    }
-
-
-    /**
-     * Sets item_id
-     *
-     * @param int $item_id
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_OBJ_ID($item_id)
-    {
-        $this->set('OBJ_ID', $item_id);
-    }
-
-
-    /**
-     * Gets item_type
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function OBJ_type()
-    {
-        return $this->get('OBJ_type');
-    }
-
-
-    /**
-     * Gets item_type
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function OBJ_type_i18n()
-    {
-        $obj_type = $this->OBJ_type();
-        switch ($obj_type) {
-            case EEM_Line_Item::OBJ_TYPE_EVENT:
-                $obj_type = esc_html__('Event', 'event_espresso');
-                break;
-            case EEM_Line_Item::OBJ_TYPE_PRICE:
-                $obj_type = esc_html__('Price', 'event_espresso');
-                break;
-            case EEM_Line_Item::OBJ_TYPE_PROMOTION:
-                $obj_type = esc_html__('Promotion', 'event_espresso');
-                break;
-            case EEM_Line_Item::OBJ_TYPE_TICKET:
-                $obj_type = esc_html__('Ticket', 'event_espresso');
-                break;
-            case EEM_Line_Item::OBJ_TYPE_TRANSACTION:
-                $obj_type = esc_html__('Transaction', 'event_espresso');
-                break;
-        }
-        return apply_filters('FHEE__EE_Line_Item__OBJ_type_i18n', $obj_type, $this);
-    }
-
-
-    /**
-     * Sets item_type
-     *
-     * @param string $OBJ_type
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_OBJ_type($OBJ_type)
-    {
-        $this->set('OBJ_type', $OBJ_type);
-    }
-
-
-    /**
-     * Gets unit_price
-     *
-     * @return float
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function unit_price()
-    {
-        return $this->get('LIN_unit_price');
-    }
-
-
-    /**
-     * Sets unit_price
-     *
-     * @param float $unit_price
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_unit_price($unit_price)
-    {
-        $this->set('LIN_unit_price', $unit_price);
-    }
-
-
-    /**
-     * Checks if this item is a percentage modifier or not
-     *
-     * @return boolean
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function is_percent()
-    {
-        if ($this->is_tax_sub_total()) {
-            // tax subtotals HAVE a percent on them, that percentage only applies
-            // to taxable items, so its' an exception. Treat it like a flat line item
-            return false;
-        }
-        $unit_price = abs($this->get('LIN_unit_price'));
-        $percent = abs($this->get('LIN_percent'));
-        if ($unit_price < .001 && $percent) {
-            return true;
-        }
-        if ($unit_price >= .001 && ! $percent) {
-            return false;
-        }
-        if ($unit_price >= .001 && $percent) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'A Line Item can not have a unit price of (%s) AND a percent (%s)!',
-                        'event_espresso'
-                    ),
-                    $unit_price,
-                    $percent
-                )
-            );
-        }
-        // if they're both 0, assume its not a percent item
-        return false;
-    }
-
-
-    /**
-     * Gets percent (between 100-.001)
-     *
-     * @return float
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function percent()
-    {
-        return $this->get('LIN_percent');
-    }
-
-
-    /**
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @since 5.0.0.p
-     */
-    public function prettyPercent(): string
-    {
-        return $this->get_pretty('LIN_percent');
-    }
-
-
-    /**
-     * Sets percent (between 100-0.01)
-     *
-     * @param float $percent
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_percent($percent)
-    {
-        $this->set('LIN_percent', $percent);
-    }
-
-
-    /**
-     * Gets total
-     *
-     * @return float
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function pretaxTotal(): float
-    {
-        return (float) $this->get('LIN_pretax');
-    }
-
-
-    /**
-     * Sets total
-     *
-     * @param float $pretax_total
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function setPretaxTotal(float $pretax_total)
-    {
-        $this->set('LIN_pretax', $pretax_total);
-    }
-
-
-    /**
-     * @return float
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @since  5.0.0.p
-     */
-    public function totalWithTax(): float
-    {
-        return (float) $this->get('LIN_total');
-    }
-
-
-    /**
-     * Sets total
-     *
-     * @param float $total
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @since  5.0.0.p
-     */
-    public function setTotalWithTax(float $total)
-    {
-        $this->set('LIN_total', $total);
-    }
-
-
-    /**
-     * Gets total
-     *
-     * @return float
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @deprecatd 5.0.0.p
-     */
-    public function total(): float
-    {
-        return $this->totalWithTax();
-    }
-
-
-    /**
-     * Sets total
-     *
-     * @param float $total
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @deprecatd 5.0.0.p
-     */
-    public function set_total($total)
-    {
-        $this->setTotalWithTax($total);
-    }
-
-
-    /**
-     * Gets order
-     *
-     * @return int
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function order()
-    {
-        return $this->get('LIN_order');
-    }
-
-
-    /**
-     * Sets order
-     *
-     * @param int $order
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_order($order)
-    {
-        $this->set('LIN_order', $order);
-    }
-
-
-    /**
-     * Gets parent
-     *
-     * @return int
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function parent_ID()
-    {
-        return $this->get('LIN_parent');
-    }
-
-
-    /**
-     * Sets parent
-     *
-     * @param int $parent
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_parent_ID($parent)
-    {
-        $this->set('LIN_parent', $parent);
-    }
-
-
-    /**
-     * Gets type
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function type()
-    {
-        return $this->get('LIN_type');
-    }
-
-
-    /**
-     * Sets type
-     *
-     * @param string $type
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_type($type)
-    {
-        $this->set('LIN_type', $type);
-    }
-
-
-    /**
-     * Gets the line item of which this item is a composite. Eg, if this is a subtotal, the parent might be a total\
-     * If this line item is saved to the DB, fetches the parent from the DB. However, if this line item isn't in the DB
-     * it uses its cached reference to its parent line item (which would have been set by `EE_Line_Item::set_parent()`
-     * or indirectly by `EE_Line_item::add_child_line_item()`)
-     *
-     * @return EE_Base_Class|EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function parent()
-    {
-        return $this->ID()
-            ? $this->get_model()->get_one_by_ID($this->parent_ID())
-            : $this->_parent;
-    }
-
-
-    /**
-     * Gets ALL the children of this line item (ie, all the parts that contribute towards this total).
-     *
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function children(array $query_params = []): array
-    {
-        if ($this->ID()) {
-            // ensure where params are an array
-            $query_params[0] = $query_params[0] ?? [];
-            // add defaults for line item parent and orderby
-            $query_params[0] += ['LIN_parent' => $this->ID()];
-            $query_params += ['order_by' => ['LIN_order' => 'ASC']];
-            return $this->get_model()->get_all($query_params);
-        }
-        if (! is_array($this->_children)) {
-            $this->_children = array();
-        }
-        return $this->_children;
-    }
-
-
-    /**
-     * Gets code
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function code()
-    {
-        return $this->get('LIN_code');
-    }
-
-
-    /**
-     * Sets code
-     *
-     * @param string $code
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_code($code)
-    {
-        $this->set('LIN_code', $code);
-    }
-
-
-    /**
-     * Gets is_taxable
-     *
-     * @return boolean
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function is_taxable()
-    {
-        return $this->get('LIN_is_taxable');
-    }
-
-
-    /**
-     * Sets is_taxable
-     *
-     * @param boolean $is_taxable
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_is_taxable($is_taxable)
-    {
-        $this->set('LIN_is_taxable', $is_taxable);
-    }
-
-
-    /**
-     * @param int $timestamp
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @since 5.0.0.p
-     */
-    public function setTimestamp(int $timestamp)
-    {
-        $this->set('LIN_timestamp', $timestamp);
-    }
-
-
-    /**
-     * Gets the object that this model-joins-to.
-     * returns one of the model objects that the field OBJ_ID can point to... see the 'OBJ_ID' field on
-     * EEM_Promotion_Object
-     *        Eg, if this line item join model object is for a ticket, this will return the EE_Ticket object
-     *
-     * @return EE_Base_Class | NULL
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function get_object()
-    {
-        $model_name_of_related_obj = $this->OBJ_type();
-        return $this->get_model()->has_relation($model_name_of_related_obj)
-            ? $this->get_first_related($model_name_of_related_obj)
-            : null;
-    }
-
-
-    /**
-     * Like EE_Line_Item::get_object(), but can only ever actually return an EE_Ticket.
-     * (IE, if this line item is for a price or something else, will return NULL)
-     *
-     * @param array $query_params
-     * @return EE_Base_Class|EE_Ticket
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function ticket($query_params = array())
-    {
-        // we're going to assume that when this method is called
-        // we always want to receive the attached ticket EVEN if that ticket is archived.
-        // This can be overridden via the incoming $query_params argument
-        $remove_defaults = array('default_where_conditions' => 'none');
-        $query_params = array_merge($remove_defaults, $query_params);
-        return $this->get_first_related(EEM_Line_Item::OBJ_TYPE_TICKET, $query_params);
-    }
-
-
-    /**
-     * Gets the EE_Datetime that's related to the ticket, IF this is for a ticket
-     *
-     * @return EE_Datetime | NULL
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function get_ticket_datetime()
-    {
-        if ($this->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET) {
-            $ticket = $this->ticket();
-            if ($ticket instanceof EE_Ticket) {
-                $datetime = $ticket->first_datetime();
-                if ($datetime instanceof EE_Datetime) {
-                    return $datetime;
-                }
-            }
-        }
-        return null;
-    }
-
-
-    /**
-     * Gets the event's name that's related to the ticket, if this is for
-     * a ticket
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function ticket_event_name()
-    {
-        $event_name = esc_html__('Unknown', 'event_espresso');
-        $event = $this->ticket_event();
-        if ($event instanceof EE_Event) {
-            $event_name = $event->name();
-        }
-        return $event_name;
-    }
-
-
-    /**
-     * Gets the event that's related to the ticket, if this line item represents a ticket.
-     *
-     * @return EE_Event|null
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function ticket_event()
-    {
-        $event = null;
-        $ticket = $this->ticket();
-        if ($ticket instanceof EE_Ticket) {
-            $datetime = $ticket->first_datetime();
-            if ($datetime instanceof EE_Datetime) {
-                $event = $datetime->event();
-            }
-        }
-        return $event;
-    }
-
-
-    /**
-     * Gets the first datetime for this lien item, assuming it's for a ticket
-     *
-     * @param string $date_format
-     * @param string $time_format
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function ticket_datetime_start($date_format = '', $time_format = '')
-    {
-        $first_datetime_string = esc_html__('Unknown', 'event_espresso');
-        $datetime = $this->get_ticket_datetime();
-        if ($datetime) {
-            $first_datetime_string = $datetime->start_date_and_time($date_format, $time_format);
-        }
-        return $first_datetime_string;
-    }
-
-
-    /**
-     * Adds the line item as a child to this line item. If there is another child line
-     * item with the same LIN_code, it is overwritten by this new one
-     *
-     * @param EE_Line_Item $line_item
-     * @param bool          $set_order
-     * @return bool success
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function add_child_line_item(EE_Line_Item $line_item, $set_order = true)
-    {
-        // should we calculate the LIN_order for this line item ?
-        if ($set_order || $line_item->order() === null) {
-            $line_item->set_order(count($this->children()));
-        }
-        if ($this->ID()) {
-            // check for any duplicate line items (with the same code), if so, this replaces it
-            $line_item_with_same_code = $this->get_child_line_item($line_item->code());
-            if ($line_item_with_same_code instanceof EE_Line_Item && $line_item_with_same_code !== $line_item) {
-                $this->delete_child_line_item($line_item_with_same_code->code());
-            }
-            $line_item->set_parent_ID($this->ID());
-            if ($this->TXN_ID()) {
-                $line_item->set_TXN_ID($this->TXN_ID());
-            }
-            return $line_item->save();
-        }
-        $this->_children[ $line_item->code() ] = $line_item;
-        if ($line_item->parent() !== $this) {
-            $line_item->set_parent($this);
-        }
-        return true;
-    }
-
-
-    /**
-     * Similar to EE_Base_Class::_add_relation_to, except this isn't a normal relation.
-     * If this line item is saved to the DB, this is just a wrapper for set_parent_ID() and save()
-     * However, if this line item is NOT saved to the DB, this just caches the parent on
-     * the EE_Line_Item::_parent property.
-     *
-     * @param EE_Line_Item $line_item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function set_parent($line_item)
-    {
-        if ($this->ID()) {
-            if (! $line_item->ID()) {
-                $line_item->save();
-            }
-            $this->set_parent_ID($line_item->ID());
-            $this->save();
-        } else {
-            $this->_parent = $line_item;
-            $this->set_parent_ID($line_item->ID());
-        }
-    }
-
-
-    /**
-     * Gets the child line item as specified by its code. Because this returns an object (by reference)
-     * you can modify this child line item and the parent (this object) can know about them
-     * because it also has a reference to that line item
-     *
-     * @param string $code
-     * @return EE_Base_Class|EE_Line_Item|EE_Soft_Delete_Base_Class|NULL
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function get_child_line_item($code)
-    {
-        if ($this->ID()) {
-            return $this->get_model()->get_one(
-                array(array('LIN_parent' => $this->ID(), 'LIN_code' => $code))
-            );
-        }
-        return isset($this->_children[ $code ])
-            ? $this->_children[ $code ]
-            : null;
-    }
-
-
-    /**
-     * Returns how many items are deleted (or, if this item has not been saved ot the DB yet, just how many it HAD
-     * cached on it)
-     *
-     * @return int
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function delete_children_line_items()
-    {
-        if ($this->ID()) {
-            return $this->get_model()->delete(array(array('LIN_parent' => $this->ID())));
-        }
-        $count = count($this->_children);
-        $this->_children = array();
-        return $count;
-    }
-
-
-    /**
-     * If this line item has been saved to the DB, deletes its child with LIN_code == $code. If this line
-     * HAS NOT been saved to the DB, removes the child line item with index $code.
-     * Also searches through the child's children for a matching line item. However, once a line item has been found
-     * and deleted, stops searching (so if there are line items with duplicate codes, only the first one found will be
-     * deleted)
-     *
-     * @param string $code
-     * @param bool   $stop_search_once_found
-     * @return int count of items deleted (or simply removed from the line item's cache, if not has not been saved to
-     *             the DB yet)
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function delete_child_line_item($code, $stop_search_once_found = true)
-    {
-        if ($this->ID()) {
-            $items_deleted = 0;
-            if ($this->code() === $code) {
-                $items_deleted += EEH_Line_Item::delete_all_child_items($this);
-                $items_deleted += (int) $this->delete();
-                if ($stop_search_once_found) {
-                    return $items_deleted;
-                }
-            }
-            foreach ($this->children() as $child_line_item) {
-                $items_deleted += $child_line_item->delete_child_line_item($code, $stop_search_once_found);
-            }
-            return $items_deleted;
-        }
-        if (isset($this->_children[ $code ])) {
-            unset($this->_children[ $code ]);
-            return 1;
-        }
-        return 0;
-    }
-
-
-    /**
-     * If this line item is in the database, is of the type subtotal, and
-     * has no children, why do we have it? It should be deleted so this function
-     * does that
-     *
-     * @return boolean
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function delete_if_childless_subtotal()
-    {
-        if ($this->ID() && $this->type() === EEM_Line_Item::type_sub_total && ! $this->children()) {
-            return $this->delete();
-        }
-        return false;
-    }
-
-
-    /**
-     * Creates a code and returns a string. doesn't assign the code to this model object
-     *
-     * @return string
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function generate_code()
-    {
-        // each line item in the cart requires a unique identifier
-        return md5($this->get('OBJ_type') . $this->get('OBJ_ID') . microtime());
-    }
-
-
-    /**
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function isGlobalTax(): bool
-    {
-        return $this->type() === EEM_Line_Item::type_tax;
-    }
-
-
-    /**
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function isSubTax(): bool
-    {
-        return $this->type() === EEM_Line_Item::type_sub_tax;
-    }
-
-
-    /**
-     * returns true if this is a line item with a direct descendent of the type sub-tax
-     *
-     * @return array
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function getSubTaxes(): array
-    {
-        if (! $this->is_line_item()) {
-            return [];
-        }
-        return EEH_Line_Item::get_descendants_of_type($this, EEM_Line_Item::type_sub_tax);
-    }
-
-
-    /**
-     * returns true if this is a line item with a direct descendent of the type sub-tax
-     *
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function hasSubTaxes(): bool
-    {
-        if (! $this->is_line_item()) {
-            return false;
-        }
-        $sub_taxes = $this->getSubTaxes();
-        return ! empty($sub_taxes);
-    }
-
-
-    /**
-     * @return bool
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @deprecated   5.0.0.p
-     */
-    public function is_tax(): bool
-    {
-        return $this->isGlobalTax();
-    }
-
-
-    /**
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function is_tax_sub_total()
-    {
-        return $this->type() === EEM_Line_Item::type_tax_sub_total;
-    }
-
-
-    /**
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function is_line_item()
-    {
-        return $this->type() === EEM_Line_Item::type_line_item;
-    }
-
-
-    /**
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function is_sub_line_item()
-    {
-        return $this->type() === EEM_Line_Item::type_sub_line_item;
-    }
-
-
-    /**
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function is_sub_total()
-    {
-        return $this->type() === EEM_Line_Item::type_sub_total;
-    }
-
-
-    /**
-     * Whether or not this line item is a cancellation line item
-     *
-     * @return boolean
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function is_cancellation()
-    {
-        return EEM_Line_Item::type_cancellation === $this->type();
-    }
-
-
-    /**
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function is_total()
-    {
-        return $this->type() === EEM_Line_Item::type_total;
-    }
-
-
-    /**
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function is_cancelled()
-    {
-        return $this->type() === EEM_Line_Item::type_cancellation;
-    }
-
-
-    /**
-     * @return string like '2, 004.00', formatted according to the localized currency
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function unit_price_no_code(): string
-    {
-        return $this->prettyUnitPrice();
-    }
-
-
-    /**
-     * @return string like '2, 004.00', formatted according to the localized currency
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @since 5.0.0.p
-     */
-    public function prettyUnitPrice(): string
-    {
-        return $this->get_pretty('LIN_unit_price', 'no_currency_code');
-    }
-
-
-    /**
-     * @return string like '2, 004.00', formatted according to the localized currency
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function total_no_code(): string
-    {
-        return $this->prettyTotal();
-    }
-
-
-    /**
-     * @return string like '2, 004.00', formatted according to the localized currency
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @since 5.0.0.p
-     */
-    public function prettyTotal(): string
-    {
-        return $this->get_pretty('LIN_total', 'no_currency_code');
-    }
-
-
-    /**
-     * Gets the final total on this item, taking taxes into account.
-     * Has the side-effect of setting the sub-total as it was just calculated.
-     * If this is used on a grand-total line item, also updates the transaction's
-     * TXN_total (provided this line item is allowed to persist, otherwise we don't
-     * want to change a persistable transaction with info from a non-persistent line item)
-     *
-     * @param bool $update_txn_status
-     * @return float
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @throws RuntimeException
-     */
-    public function recalculate_total_including_taxes(bool $update_txn_status = false): float
-    {
-        $grand_total_line_item = EEH_Line_Item::find_transaction_grand_total_for_line_item($this);
-        return $this->calculator->recalculateTotalIncludingTaxes($grand_total_line_item, $update_txn_status);
-    }
-
-
-    /**
-     * Recursively goes through all the children and recalculates sub-totals EXCEPT for
-     * tax-sub-totals (they're a an odd beast). Updates the 'total' on each line item according to either its
-     * unit price * quantity or the total of all its children EXCEPT when we're only calculating the taxable total and
-     * when this is called on the grand total
-     *
-     * @return float
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function recalculate_pre_tax_total(): float
-    {
-        $grand_total_line_item = EEH_Line_Item::find_transaction_grand_total_for_line_item($this);
-        [$total] = $this->calculator->recalculateLineItemTotals($grand_total_line_item);
-        return (float) $total;
-    }
-
-
-    /**
-     * Recalculates the total on each individual tax (based on a recalculation of the pre-tax total), sets
-     * the totals on each tax calculated, and returns the final tax total. Re-saves tax line items
-     * and tax sub-total if already in the DB
-     *
-     * @return float
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function recalculate_taxes_and_tax_total(): float
-    {
-        $grand_total_line_item = EEH_Line_Item::find_transaction_grand_total_for_line_item($this);
-        return $this->calculator->recalculateTaxesAndTaxTotal($grand_total_line_item);
-    }
-
-
-    /**
-     * Gets the total tax on this line item. Assumes taxes have already been calculated using
-     * recalculate_taxes_and_total
-     *
-     * @return float
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function get_total_tax()
-    {
-        $grand_total_line_item = EEH_Line_Item::find_transaction_grand_total_for_line_item($this);
-        return $this->calculator->recalculateTaxesAndTaxTotal($grand_total_line_item);
-    }
-
-
-    /**
-     * Gets the total for all the items purchased only
-     *
-     * @return float
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function get_items_total()
-    {
-        // by default, let's make sure we're consistent with the existing line item
-        if ($this->is_total()) {
-            return $this->pretaxTotal();
-        }
-        $total = 0;
-        foreach ($this->get_items() as $item) {
-            if ($item instanceof EE_Line_Item) {
-                $total += $item->pretaxTotal();
-            }
-        }
-        return $total;
-    }
-
-
-    /**
-     * Gets all the descendants (ie, children or children of children etc) that
-     * are of the type 'tax'
-     *
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     */
-    public function tax_descendants()
-    {
-        return EEH_Line_Item::get_tax_descendants($this);
-    }
-
-
-    /**
-     * Gets all the real items purchased which are children of this item
-     *
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     */
-    public function get_items()
-    {
-        return EEH_Line_Item::get_line_item_descendants($this);
-    }
-
-
-    /**
-     * Returns the amount taxable among this line item's children (or if it has no children,
-     * how much of it is taxable). Does not recalculate totals or subtotals.
-     * If the taxable total is negative, (eg, if none of the tickets were taxable,
-     * but there is a "Taxable" discount), returns 0.
-     *
-     * @return float
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function taxable_total(): float
-    {
-        return $this->calculator->taxableAmountForGlobalTaxes($this);
-    }
-
-
-    /**
-     * Gets the transaction for this line item
-     *
-     * @return EE_Base_Class|EE_Transaction
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function transaction()
-    {
-        return $this->get_first_related(EEM_Line_Item::OBJ_TYPE_TRANSACTION);
-    }
-
-
-    /**
-     * Saves this line item to the DB, and recursively saves its descendants.
-     * Because there currently is no proper parent-child relation on the model,
-     * save_this_and_cached() will NOT save the descendants.
-     * Also sets the transaction on this line item and all its descendants before saving
-     *
-     * @param int $txn_id if none is provided, assumes $this->TXN_ID()
-     * @return int count of items saved
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function save_this_and_descendants_to_txn($txn_id = null)
-    {
-        $count = 0;
-        if (! $txn_id) {
-            $txn_id = $this->TXN_ID();
-        }
-        $this->set_TXN_ID($txn_id);
-        $children = $this->children();
-        $count += $this->save()
-            ? 1
-            : 0;
-        foreach ($children as $child_line_item) {
-            if ($child_line_item instanceof EE_Line_Item) {
-                $child_line_item->set_parent_ID($this->ID());
-                $count += $child_line_item->save_this_and_descendants_to_txn($txn_id);
-            }
-        }
-        return $count;
-    }
-
-
-    /**
-     * Saves this line item to the DB, and recursively saves its descendants.
-     *
-     * @return int count of items saved
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function save_this_and_descendants()
-    {
-        $count = 0;
-        $children = $this->children();
-        $count += $this->save()
-            ? 1
-            : 0;
-        foreach ($children as $child_line_item) {
-            if ($child_line_item instanceof EE_Line_Item) {
-                $child_line_item->set_parent_ID($this->ID());
-                $count += $child_line_item->save_this_and_descendants();
-            }
-        }
-        return $count;
-    }
-
-
-    /**
-     * returns the cancellation line item if this item was cancelled
-     *
-     * @return EE_Line_Item[]
-     * @throws InvalidArgumentException
-     * @throws InvalidInterfaceException
-     * @throws InvalidDataTypeException
-     * @throws ReflectionException
-     * @throws EE_Error
-     */
-    public function get_cancellations()
-    {
-        return EEH_Line_Item::get_descendants_of_type($this, EEM_Line_Item::type_cancellation);
-    }
-
-
-    /**
-     * If this item has an ID, then this saves it again to update the db
-     *
-     * @return int count of items saved
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function maybe_save()
-    {
-        if ($this->ID()) {
-            return $this->save();
-        }
-        return false;
-    }
-
-
-    /**
-     * clears the cached children and parent from the line item
-     *
-     * @return void
-     */
-    public function clear_related_line_item_cache()
-    {
-        $this->_children = array();
-        $this->_parent = null;
-    }
-
-
-    /**
-     * @param bool $raw
-     * @return int
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function timestamp($raw = false)
-    {
-        return $raw
-            ? $this->get_raw('LIN_timestamp')
-            : $this->get('LIN_timestamp');
-    }
-
-
-
-
-    /************************* DEPRECATED *************************/
-    /**
-     * @deprecated 4.6.0
-     * @param string $type one of the constants on EEM_Line_Item
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     */
-    protected function _get_descendants_of_type($type)
-    {
-        EE_Error::doing_it_wrong(
-            'EE_Line_Item::_get_descendants_of_type()',
-            sprintf(
-                esc_html__('Method replaced with %1$s', 'event_espresso'),
-                'EEH_Line_Item::get_descendants_of_type()'
-            ),
-            '4.6.0'
-        );
-        return EEH_Line_Item::get_descendants_of_type($this, $type);
-    }
-
-
-    /**
-     * @deprecated 4.6.0
-     * @param string $type like one of the EEM_Line_Item::type_*
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public function get_nearest_descendant_of_type(string $type): EE_Line_Item
-    {
-        EE_Error::doing_it_wrong(
-            'EE_Line_Item::get_nearest_descendant_of_type()',
-            sprintf(
-                esc_html__('Method replaced with %1$s', 'event_espresso'),
-                'EEH_Line_Item::get_nearest_descendant_of_type()'
-            ),
-            '4.6.0'
-        );
-        return EEH_Line_Item::get_nearest_descendant_of_type($this, $type);
-    }
+	/**
+	 * for children line items (currently not a normal relation)
+	 *
+	 * @type EE_Line_Item[]
+	 */
+	protected $_children = array();
+
+	/**
+	 * for the parent line item
+	 *
+	 * @var EE_Line_Item
+	 */
+	protected $_parent;
+
+	/**
+	 * @var LineItemCalculator
+	 */
+	protected $calculator;
+
+
+	/**
+	 * @param array  $props_n_values          incoming values
+	 * @param string $timezone                incoming timezone (if not set the timezone set for the website will be
+	 *                                        used.)
+	 * @param array  $date_formats            incoming date_formats in an array where the first value is the
+	 *                                        date_format and the second value is the time format
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function new_instance($props_n_values = array(), $timezone = null, $date_formats = array())
+	{
+		$has_object = parent::_check_for_object(
+			$props_n_values,
+			__CLASS__,
+			$timezone,
+			$date_formats
+		);
+		return $has_object
+			? $has_object
+			: new self($props_n_values, false, $timezone);
+	}
+
+
+	/**
+	 * @param array  $props_n_values  incoming values from the database
+	 * @param string $timezone        incoming timezone as set by the model.  If not set the timezone for
+	 *                                the website will be used.
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function new_instance_from_db($props_n_values = array(), $timezone = null)
+	{
+		return new self($props_n_values, true, $timezone);
+	}
+
+
+	/**
+	 * Adds some defaults if they're not specified
+	 *
+	 * @param array  $fieldValues
+	 * @param bool   $bydb
+	 * @param string $timezone
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	protected function __construct($fieldValues = array(), $bydb = false, $timezone = '')
+	{
+		$this->calculator = LoaderFactory::getShared(LineItemCalculator::class);
+		parent::__construct($fieldValues, $bydb, $timezone);
+		if (! $this->get('LIN_code')) {
+			$this->set_code($this->generate_code());
+		}
+	}
+
+
+	public function __wakeup()
+	{
+		$this->calculator = LoaderFactory::getShared(LineItemCalculator::class);
+		parent::__wakeup();
+	}
+
+
+	/**
+	 * Gets ID
+	 *
+	 * @return int
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function ID()
+	{
+		return $this->get('LIN_ID');
+	}
+
+
+	/**
+	 * Gets TXN_ID
+	 *
+	 * @return int
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function TXN_ID()
+	{
+		return $this->get('TXN_ID');
+	}
+
+
+	/**
+	 * Sets TXN_ID
+	 *
+	 * @param int $TXN_ID
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_TXN_ID($TXN_ID)
+	{
+		$this->set('TXN_ID', $TXN_ID);
+	}
+
+
+	/**
+	 * Gets name
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function name()
+	{
+		$name = $this->get('LIN_name');
+		if (! $name) {
+			$name = ucwords(str_replace('-', ' ', $this->type()));
+		}
+		return $name;
+	}
+
+
+	/**
+	 * Sets name
+	 *
+	 * @param string $name
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_name($name)
+	{
+		$this->set('LIN_name', $name);
+	}
+
+
+	/**
+	 * Gets desc
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function desc()
+	{
+		return $this->get('LIN_desc');
+	}
+
+
+	/**
+	 * Sets desc
+	 *
+	 * @param string $desc
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_desc($desc)
+	{
+		$this->set('LIN_desc', $desc);
+	}
+
+
+	/**
+	 * Gets quantity
+	 *
+	 * @return int
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function quantity(): int
+	{
+		return (int) $this->get('LIN_quantity');
+	}
+
+
+	/**
+	 * Sets quantity
+	 *
+	 * @param int $quantity
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_quantity($quantity)
+	{
+		$this->set('LIN_quantity', max($quantity, 0));
+	}
+
+
+	/**
+	 * Gets item_id
+	 *
+	 * @return int
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function OBJ_ID()
+	{
+		return $this->get('OBJ_ID');
+	}
+
+
+	/**
+	 * Sets item_id
+	 *
+	 * @param int $item_id
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_OBJ_ID($item_id)
+	{
+		$this->set('OBJ_ID', $item_id);
+	}
+
+
+	/**
+	 * Gets item_type
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function OBJ_type()
+	{
+		return $this->get('OBJ_type');
+	}
+
+
+	/**
+	 * Gets item_type
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function OBJ_type_i18n()
+	{
+		$obj_type = $this->OBJ_type();
+		switch ($obj_type) {
+			case EEM_Line_Item::OBJ_TYPE_EVENT:
+				$obj_type = esc_html__('Event', 'event_espresso');
+				break;
+			case EEM_Line_Item::OBJ_TYPE_PRICE:
+				$obj_type = esc_html__('Price', 'event_espresso');
+				break;
+			case EEM_Line_Item::OBJ_TYPE_PROMOTION:
+				$obj_type = esc_html__('Promotion', 'event_espresso');
+				break;
+			case EEM_Line_Item::OBJ_TYPE_TICKET:
+				$obj_type = esc_html__('Ticket', 'event_espresso');
+				break;
+			case EEM_Line_Item::OBJ_TYPE_TRANSACTION:
+				$obj_type = esc_html__('Transaction', 'event_espresso');
+				break;
+		}
+		return apply_filters('FHEE__EE_Line_Item__OBJ_type_i18n', $obj_type, $this);
+	}
+
+
+	/**
+	 * Sets item_type
+	 *
+	 * @param string $OBJ_type
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_OBJ_type($OBJ_type)
+	{
+		$this->set('OBJ_type', $OBJ_type);
+	}
+
+
+	/**
+	 * Gets unit_price
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function unit_price()
+	{
+		return $this->get('LIN_unit_price');
+	}
+
+
+	/**
+	 * Sets unit_price
+	 *
+	 * @param float $unit_price
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_unit_price($unit_price)
+	{
+		$this->set('LIN_unit_price', $unit_price);
+	}
+
+
+	/**
+	 * Checks if this item is a percentage modifier or not
+	 *
+	 * @return boolean
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function is_percent()
+	{
+		if ($this->is_tax_sub_total()) {
+			// tax subtotals HAVE a percent on them, that percentage only applies
+			// to taxable items, so its' an exception. Treat it like a flat line item
+			return false;
+		}
+		$unit_price = abs($this->get('LIN_unit_price'));
+		$percent = abs($this->get('LIN_percent'));
+		if ($unit_price < .001 && $percent) {
+			return true;
+		}
+		if ($unit_price >= .001 && ! $percent) {
+			return false;
+		}
+		if ($unit_price >= .001 && $percent) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'A Line Item can not have a unit price of (%s) AND a percent (%s)!',
+						'event_espresso'
+					),
+					$unit_price,
+					$percent
+				)
+			);
+		}
+		// if they're both 0, assume its not a percent item
+		return false;
+	}
+
+
+	/**
+	 * Gets percent (between 100-.001)
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function percent()
+	{
+		return $this->get('LIN_percent');
+	}
+
+
+	/**
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @since 5.0.0.p
+	 */
+	public function prettyPercent(): string
+	{
+		return $this->get_pretty('LIN_percent');
+	}
+
+
+	/**
+	 * Sets percent (between 100-0.01)
+	 *
+	 * @param float $percent
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_percent($percent)
+	{
+		$this->set('LIN_percent', $percent);
+	}
+
+
+	/**
+	 * Gets total
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function pretaxTotal(): float
+	{
+		return (float) $this->get('LIN_pretax');
+	}
+
+
+	/**
+	 * Sets total
+	 *
+	 * @param float $pretax_total
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function setPretaxTotal(float $pretax_total)
+	{
+		$this->set('LIN_pretax', $pretax_total);
+	}
+
+
+	/**
+	 * @return float
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @since  5.0.0.p
+	 */
+	public function totalWithTax(): float
+	{
+		return (float) $this->get('LIN_total');
+	}
+
+
+	/**
+	 * Sets total
+	 *
+	 * @param float $total
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @since  5.0.0.p
+	 */
+	public function setTotalWithTax(float $total)
+	{
+		$this->set('LIN_total', $total);
+	}
+
+
+	/**
+	 * Gets total
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @deprecatd 5.0.0.p
+	 */
+	public function total(): float
+	{
+		return $this->totalWithTax();
+	}
+
+
+	/**
+	 * Sets total
+	 *
+	 * @param float $total
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @deprecatd 5.0.0.p
+	 */
+	public function set_total($total)
+	{
+		$this->setTotalWithTax($total);
+	}
+
+
+	/**
+	 * Gets order
+	 *
+	 * @return int
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function order()
+	{
+		return $this->get('LIN_order');
+	}
+
+
+	/**
+	 * Sets order
+	 *
+	 * @param int $order
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_order($order)
+	{
+		$this->set('LIN_order', $order);
+	}
+
+
+	/**
+	 * Gets parent
+	 *
+	 * @return int
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function parent_ID()
+	{
+		return $this->get('LIN_parent');
+	}
+
+
+	/**
+	 * Sets parent
+	 *
+	 * @param int $parent
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_parent_ID($parent)
+	{
+		$this->set('LIN_parent', $parent);
+	}
+
+
+	/**
+	 * Gets type
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function type()
+	{
+		return $this->get('LIN_type');
+	}
+
+
+	/**
+	 * Sets type
+	 *
+	 * @param string $type
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_type($type)
+	{
+		$this->set('LIN_type', $type);
+	}
+
+
+	/**
+	 * Gets the line item of which this item is a composite. Eg, if this is a subtotal, the parent might be a total\
+	 * If this line item is saved to the DB, fetches the parent from the DB. However, if this line item isn't in the DB
+	 * it uses its cached reference to its parent line item (which would have been set by `EE_Line_Item::set_parent()`
+	 * or indirectly by `EE_Line_item::add_child_line_item()`)
+	 *
+	 * @return EE_Base_Class|EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function parent()
+	{
+		return $this->ID()
+			? $this->get_model()->get_one_by_ID($this->parent_ID())
+			: $this->_parent;
+	}
+
+
+	/**
+	 * Gets ALL the children of this line item (ie, all the parts that contribute towards this total).
+	 *
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function children(array $query_params = []): array
+	{
+		if ($this->ID()) {
+			// ensure where params are an array
+			$query_params[0] = $query_params[0] ?? [];
+			// add defaults for line item parent and orderby
+			$query_params[0] += ['LIN_parent' => $this->ID()];
+			$query_params += ['order_by' => ['LIN_order' => 'ASC']];
+			return $this->get_model()->get_all($query_params);
+		}
+		if (! is_array($this->_children)) {
+			$this->_children = array();
+		}
+		return $this->_children;
+	}
+
+
+	/**
+	 * Gets code
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function code()
+	{
+		return $this->get('LIN_code');
+	}
+
+
+	/**
+	 * Sets code
+	 *
+	 * @param string $code
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_code($code)
+	{
+		$this->set('LIN_code', $code);
+	}
+
+
+	/**
+	 * Gets is_taxable
+	 *
+	 * @return boolean
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function is_taxable()
+	{
+		return $this->get('LIN_is_taxable');
+	}
+
+
+	/**
+	 * Sets is_taxable
+	 *
+	 * @param boolean $is_taxable
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_is_taxable($is_taxable)
+	{
+		$this->set('LIN_is_taxable', $is_taxable);
+	}
+
+
+	/**
+	 * @param int $timestamp
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @since 5.0.0.p
+	 */
+	public function setTimestamp(int $timestamp)
+	{
+		$this->set('LIN_timestamp', $timestamp);
+	}
+
+
+	/**
+	 * Gets the object that this model-joins-to.
+	 * returns one of the model objects that the field OBJ_ID can point to... see the 'OBJ_ID' field on
+	 * EEM_Promotion_Object
+	 *        Eg, if this line item join model object is for a ticket, this will return the EE_Ticket object
+	 *
+	 * @return EE_Base_Class | NULL
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function get_object()
+	{
+		$model_name_of_related_obj = $this->OBJ_type();
+		return $this->get_model()->has_relation($model_name_of_related_obj)
+			? $this->get_first_related($model_name_of_related_obj)
+			: null;
+	}
+
+
+	/**
+	 * Like EE_Line_Item::get_object(), but can only ever actually return an EE_Ticket.
+	 * (IE, if this line item is for a price or something else, will return NULL)
+	 *
+	 * @param array $query_params
+	 * @return EE_Base_Class|EE_Ticket
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function ticket($query_params = array())
+	{
+		// we're going to assume that when this method is called
+		// we always want to receive the attached ticket EVEN if that ticket is archived.
+		// This can be overridden via the incoming $query_params argument
+		$remove_defaults = array('default_where_conditions' => 'none');
+		$query_params = array_merge($remove_defaults, $query_params);
+		return $this->get_first_related(EEM_Line_Item::OBJ_TYPE_TICKET, $query_params);
+	}
+
+
+	/**
+	 * Gets the EE_Datetime that's related to the ticket, IF this is for a ticket
+	 *
+	 * @return EE_Datetime | NULL
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function get_ticket_datetime()
+	{
+		if ($this->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET) {
+			$ticket = $this->ticket();
+			if ($ticket instanceof EE_Ticket) {
+				$datetime = $ticket->first_datetime();
+				if ($datetime instanceof EE_Datetime) {
+					return $datetime;
+				}
+			}
+		}
+		return null;
+	}
+
+
+	/**
+	 * Gets the event's name that's related to the ticket, if this is for
+	 * a ticket
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function ticket_event_name()
+	{
+		$event_name = esc_html__('Unknown', 'event_espresso');
+		$event = $this->ticket_event();
+		if ($event instanceof EE_Event) {
+			$event_name = $event->name();
+		}
+		return $event_name;
+	}
+
+
+	/**
+	 * Gets the event that's related to the ticket, if this line item represents a ticket.
+	 *
+	 * @return EE_Event|null
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function ticket_event()
+	{
+		$event = null;
+		$ticket = $this->ticket();
+		if ($ticket instanceof EE_Ticket) {
+			$datetime = $ticket->first_datetime();
+			if ($datetime instanceof EE_Datetime) {
+				$event = $datetime->event();
+			}
+		}
+		return $event;
+	}
+
+
+	/**
+	 * Gets the first datetime for this lien item, assuming it's for a ticket
+	 *
+	 * @param string $date_format
+	 * @param string $time_format
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function ticket_datetime_start($date_format = '', $time_format = '')
+	{
+		$first_datetime_string = esc_html__('Unknown', 'event_espresso');
+		$datetime = $this->get_ticket_datetime();
+		if ($datetime) {
+			$first_datetime_string = $datetime->start_date_and_time($date_format, $time_format);
+		}
+		return $first_datetime_string;
+	}
+
+
+	/**
+	 * Adds the line item as a child to this line item. If there is another child line
+	 * item with the same LIN_code, it is overwritten by this new one
+	 *
+	 * @param EE_Line_Item $line_item
+	 * @param bool          $set_order
+	 * @return bool success
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function add_child_line_item(EE_Line_Item $line_item, $set_order = true)
+	{
+		// should we calculate the LIN_order for this line item ?
+		if ($set_order || $line_item->order() === null) {
+			$line_item->set_order(count($this->children()));
+		}
+		if ($this->ID()) {
+			// check for any duplicate line items (with the same code), if so, this replaces it
+			$line_item_with_same_code = $this->get_child_line_item($line_item->code());
+			if ($line_item_with_same_code instanceof EE_Line_Item && $line_item_with_same_code !== $line_item) {
+				$this->delete_child_line_item($line_item_with_same_code->code());
+			}
+			$line_item->set_parent_ID($this->ID());
+			if ($this->TXN_ID()) {
+				$line_item->set_TXN_ID($this->TXN_ID());
+			}
+			return $line_item->save();
+		}
+		$this->_children[ $line_item->code() ] = $line_item;
+		if ($line_item->parent() !== $this) {
+			$line_item->set_parent($this);
+		}
+		return true;
+	}
+
+
+	/**
+	 * Similar to EE_Base_Class::_add_relation_to, except this isn't a normal relation.
+	 * If this line item is saved to the DB, this is just a wrapper for set_parent_ID() and save()
+	 * However, if this line item is NOT saved to the DB, this just caches the parent on
+	 * the EE_Line_Item::_parent property.
+	 *
+	 * @param EE_Line_Item $line_item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function set_parent($line_item)
+	{
+		if ($this->ID()) {
+			if (! $line_item->ID()) {
+				$line_item->save();
+			}
+			$this->set_parent_ID($line_item->ID());
+			$this->save();
+		} else {
+			$this->_parent = $line_item;
+			$this->set_parent_ID($line_item->ID());
+		}
+	}
+
+
+	/**
+	 * Gets the child line item as specified by its code. Because this returns an object (by reference)
+	 * you can modify this child line item and the parent (this object) can know about them
+	 * because it also has a reference to that line item
+	 *
+	 * @param string $code
+	 * @return EE_Base_Class|EE_Line_Item|EE_Soft_Delete_Base_Class|NULL
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function get_child_line_item($code)
+	{
+		if ($this->ID()) {
+			return $this->get_model()->get_one(
+				array(array('LIN_parent' => $this->ID(), 'LIN_code' => $code))
+			);
+		}
+		return isset($this->_children[ $code ])
+			? $this->_children[ $code ]
+			: null;
+	}
+
+
+	/**
+	 * Returns how many items are deleted (or, if this item has not been saved ot the DB yet, just how many it HAD
+	 * cached on it)
+	 *
+	 * @return int
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function delete_children_line_items()
+	{
+		if ($this->ID()) {
+			return $this->get_model()->delete(array(array('LIN_parent' => $this->ID())));
+		}
+		$count = count($this->_children);
+		$this->_children = array();
+		return $count;
+	}
+
+
+	/**
+	 * If this line item has been saved to the DB, deletes its child with LIN_code == $code. If this line
+	 * HAS NOT been saved to the DB, removes the child line item with index $code.
+	 * Also searches through the child's children for a matching line item. However, once a line item has been found
+	 * and deleted, stops searching (so if there are line items with duplicate codes, only the first one found will be
+	 * deleted)
+	 *
+	 * @param string $code
+	 * @param bool   $stop_search_once_found
+	 * @return int count of items deleted (or simply removed from the line item's cache, if not has not been saved to
+	 *             the DB yet)
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function delete_child_line_item($code, $stop_search_once_found = true)
+	{
+		if ($this->ID()) {
+			$items_deleted = 0;
+			if ($this->code() === $code) {
+				$items_deleted += EEH_Line_Item::delete_all_child_items($this);
+				$items_deleted += (int) $this->delete();
+				if ($stop_search_once_found) {
+					return $items_deleted;
+				}
+			}
+			foreach ($this->children() as $child_line_item) {
+				$items_deleted += $child_line_item->delete_child_line_item($code, $stop_search_once_found);
+			}
+			return $items_deleted;
+		}
+		if (isset($this->_children[ $code ])) {
+			unset($this->_children[ $code ]);
+			return 1;
+		}
+		return 0;
+	}
+
+
+	/**
+	 * If this line item is in the database, is of the type subtotal, and
+	 * has no children, why do we have it? It should be deleted so this function
+	 * does that
+	 *
+	 * @return boolean
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function delete_if_childless_subtotal()
+	{
+		if ($this->ID() && $this->type() === EEM_Line_Item::type_sub_total && ! $this->children()) {
+			return $this->delete();
+		}
+		return false;
+	}
+
+
+	/**
+	 * Creates a code and returns a string. doesn't assign the code to this model object
+	 *
+	 * @return string
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function generate_code()
+	{
+		// each line item in the cart requires a unique identifier
+		return md5($this->get('OBJ_type') . $this->get('OBJ_ID') . microtime());
+	}
+
+
+	/**
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function isGlobalTax(): bool
+	{
+		return $this->type() === EEM_Line_Item::type_tax;
+	}
+
+
+	/**
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function isSubTax(): bool
+	{
+		return $this->type() === EEM_Line_Item::type_sub_tax;
+	}
+
+
+	/**
+	 * returns true if this is a line item with a direct descendent of the type sub-tax
+	 *
+	 * @return array
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function getSubTaxes(): array
+	{
+		if (! $this->is_line_item()) {
+			return [];
+		}
+		return EEH_Line_Item::get_descendants_of_type($this, EEM_Line_Item::type_sub_tax);
+	}
+
+
+	/**
+	 * returns true if this is a line item with a direct descendent of the type sub-tax
+	 *
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function hasSubTaxes(): bool
+	{
+		if (! $this->is_line_item()) {
+			return false;
+		}
+		$sub_taxes = $this->getSubTaxes();
+		return ! empty($sub_taxes);
+	}
+
+
+	/**
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @deprecated   5.0.0.p
+	 */
+	public function is_tax(): bool
+	{
+		return $this->isGlobalTax();
+	}
+
+
+	/**
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function is_tax_sub_total()
+	{
+		return $this->type() === EEM_Line_Item::type_tax_sub_total;
+	}
+
+
+	/**
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function is_line_item()
+	{
+		return $this->type() === EEM_Line_Item::type_line_item;
+	}
+
+
+	/**
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function is_sub_line_item()
+	{
+		return $this->type() === EEM_Line_Item::type_sub_line_item;
+	}
+
+
+	/**
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function is_sub_total()
+	{
+		return $this->type() === EEM_Line_Item::type_sub_total;
+	}
+
+
+	/**
+	 * Whether or not this line item is a cancellation line item
+	 *
+	 * @return boolean
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function is_cancellation()
+	{
+		return EEM_Line_Item::type_cancellation === $this->type();
+	}
+
+
+	/**
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function is_total()
+	{
+		return $this->type() === EEM_Line_Item::type_total;
+	}
+
+
+	/**
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function is_cancelled()
+	{
+		return $this->type() === EEM_Line_Item::type_cancellation;
+	}
+
+
+	/**
+	 * @return string like '2, 004.00', formatted according to the localized currency
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function unit_price_no_code(): string
+	{
+		return $this->prettyUnitPrice();
+	}
+
+
+	/**
+	 * @return string like '2, 004.00', formatted according to the localized currency
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @since 5.0.0.p
+	 */
+	public function prettyUnitPrice(): string
+	{
+		return $this->get_pretty('LIN_unit_price', 'no_currency_code');
+	}
+
+
+	/**
+	 * @return string like '2, 004.00', formatted according to the localized currency
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function total_no_code(): string
+	{
+		return $this->prettyTotal();
+	}
+
+
+	/**
+	 * @return string like '2, 004.00', formatted according to the localized currency
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @since 5.0.0.p
+	 */
+	public function prettyTotal(): string
+	{
+		return $this->get_pretty('LIN_total', 'no_currency_code');
+	}
+
+
+	/**
+	 * Gets the final total on this item, taking taxes into account.
+	 * Has the side-effect of setting the sub-total as it was just calculated.
+	 * If this is used on a grand-total line item, also updates the transaction's
+	 * TXN_total (provided this line item is allowed to persist, otherwise we don't
+	 * want to change a persistable transaction with info from a non-persistent line item)
+	 *
+	 * @param bool $update_txn_status
+	 * @return float
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @throws RuntimeException
+	 */
+	public function recalculate_total_including_taxes(bool $update_txn_status = false): float
+	{
+		$grand_total_line_item = EEH_Line_Item::find_transaction_grand_total_for_line_item($this);
+		return $this->calculator->recalculateTotalIncludingTaxes($grand_total_line_item, $update_txn_status);
+	}
+
+
+	/**
+	 * Recursively goes through all the children and recalculates sub-totals EXCEPT for
+	 * tax-sub-totals (they're a an odd beast). Updates the 'total' on each line item according to either its
+	 * unit price * quantity or the total of all its children EXCEPT when we're only calculating the taxable total and
+	 * when this is called on the grand total
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function recalculate_pre_tax_total(): float
+	{
+		$grand_total_line_item = EEH_Line_Item::find_transaction_grand_total_for_line_item($this);
+		[$total] = $this->calculator->recalculateLineItemTotals($grand_total_line_item);
+		return (float) $total;
+	}
+
+
+	/**
+	 * Recalculates the total on each individual tax (based on a recalculation of the pre-tax total), sets
+	 * the totals on each tax calculated, and returns the final tax total. Re-saves tax line items
+	 * and tax sub-total if already in the DB
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function recalculate_taxes_and_tax_total(): float
+	{
+		$grand_total_line_item = EEH_Line_Item::find_transaction_grand_total_for_line_item($this);
+		return $this->calculator->recalculateTaxesAndTaxTotal($grand_total_line_item);
+	}
+
+
+	/**
+	 * Gets the total tax on this line item. Assumes taxes have already been calculated using
+	 * recalculate_taxes_and_total
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function get_total_tax()
+	{
+		$grand_total_line_item = EEH_Line_Item::find_transaction_grand_total_for_line_item($this);
+		return $this->calculator->recalculateTaxesAndTaxTotal($grand_total_line_item);
+	}
+
+
+	/**
+	 * Gets the total for all the items purchased only
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function get_items_total()
+	{
+		// by default, let's make sure we're consistent with the existing line item
+		if ($this->is_total()) {
+			return $this->pretaxTotal();
+		}
+		$total = 0;
+		foreach ($this->get_items() as $item) {
+			if ($item instanceof EE_Line_Item) {
+				$total += $item->pretaxTotal();
+			}
+		}
+		return $total;
+	}
+
+
+	/**
+	 * Gets all the descendants (ie, children or children of children etc) that
+	 * are of the type 'tax'
+	 *
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 */
+	public function tax_descendants()
+	{
+		return EEH_Line_Item::get_tax_descendants($this);
+	}
+
+
+	/**
+	 * Gets all the real items purchased which are children of this item
+	 *
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 */
+	public function get_items()
+	{
+		return EEH_Line_Item::get_line_item_descendants($this);
+	}
+
+
+	/**
+	 * Returns the amount taxable among this line item's children (or if it has no children,
+	 * how much of it is taxable). Does not recalculate totals or subtotals.
+	 * If the taxable total is negative, (eg, if none of the tickets were taxable,
+	 * but there is a "Taxable" discount), returns 0.
+	 *
+	 * @return float
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function taxable_total(): float
+	{
+		return $this->calculator->taxableAmountForGlobalTaxes($this);
+	}
+
+
+	/**
+	 * Gets the transaction for this line item
+	 *
+	 * @return EE_Base_Class|EE_Transaction
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function transaction()
+	{
+		return $this->get_first_related(EEM_Line_Item::OBJ_TYPE_TRANSACTION);
+	}
+
+
+	/**
+	 * Saves this line item to the DB, and recursively saves its descendants.
+	 * Because there currently is no proper parent-child relation on the model,
+	 * save_this_and_cached() will NOT save the descendants.
+	 * Also sets the transaction on this line item and all its descendants before saving
+	 *
+	 * @param int $txn_id if none is provided, assumes $this->TXN_ID()
+	 * @return int count of items saved
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function save_this_and_descendants_to_txn($txn_id = null)
+	{
+		$count = 0;
+		if (! $txn_id) {
+			$txn_id = $this->TXN_ID();
+		}
+		$this->set_TXN_ID($txn_id);
+		$children = $this->children();
+		$count += $this->save()
+			? 1
+			: 0;
+		foreach ($children as $child_line_item) {
+			if ($child_line_item instanceof EE_Line_Item) {
+				$child_line_item->set_parent_ID($this->ID());
+				$count += $child_line_item->save_this_and_descendants_to_txn($txn_id);
+			}
+		}
+		return $count;
+	}
+
+
+	/**
+	 * Saves this line item to the DB, and recursively saves its descendants.
+	 *
+	 * @return int count of items saved
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function save_this_and_descendants()
+	{
+		$count = 0;
+		$children = $this->children();
+		$count += $this->save()
+			? 1
+			: 0;
+		foreach ($children as $child_line_item) {
+			if ($child_line_item instanceof EE_Line_Item) {
+				$child_line_item->set_parent_ID($this->ID());
+				$count += $child_line_item->save_this_and_descendants();
+			}
+		}
+		return $count;
+	}
+
+
+	/**
+	 * returns the cancellation line item if this item was cancelled
+	 *
+	 * @return EE_Line_Item[]
+	 * @throws InvalidArgumentException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidDataTypeException
+	 * @throws ReflectionException
+	 * @throws EE_Error
+	 */
+	public function get_cancellations()
+	{
+		return EEH_Line_Item::get_descendants_of_type($this, EEM_Line_Item::type_cancellation);
+	}
+
+
+	/**
+	 * If this item has an ID, then this saves it again to update the db
+	 *
+	 * @return int count of items saved
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function maybe_save()
+	{
+		if ($this->ID()) {
+			return $this->save();
+		}
+		return false;
+	}
+
+
+	/**
+	 * clears the cached children and parent from the line item
+	 *
+	 * @return void
+	 */
+	public function clear_related_line_item_cache()
+	{
+		$this->_children = array();
+		$this->_parent = null;
+	}
+
+
+	/**
+	 * @param bool $raw
+	 * @return int
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function timestamp($raw = false)
+	{
+		return $raw
+			? $this->get_raw('LIN_timestamp')
+			: $this->get('LIN_timestamp');
+	}
+
+
+
+
+	/************************* DEPRECATED *************************/
+	/**
+	 * @deprecated 4.6.0
+	 * @param string $type one of the constants on EEM_Line_Item
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 */
+	protected function _get_descendants_of_type($type)
+	{
+		EE_Error::doing_it_wrong(
+			'EE_Line_Item::_get_descendants_of_type()',
+			sprintf(
+				esc_html__('Method replaced with %1$s', 'event_espresso'),
+				'EEH_Line_Item::get_descendants_of_type()'
+			),
+			'4.6.0'
+		);
+		return EEH_Line_Item::get_descendants_of_type($this, $type);
+	}
+
+
+	/**
+	 * @deprecated 4.6.0
+	 * @param string $type like one of the EEM_Line_Item::type_*
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public function get_nearest_descendant_of_type(string $type): EE_Line_Item
+	{
+		EE_Error::doing_it_wrong(
+			'EE_Line_Item::get_nearest_descendant_of_type()',
+			sprintf(
+				esc_html__('Method replaced with %1$s', 'event_espresso'),
+				'EEH_Line_Item::get_nearest_descendant_of_type()'
+			),
+			'4.6.0'
+		);
+		return EEH_Line_Item::get_nearest_descendant_of_type($this, $type);
+	}
 }