eventespresso / event-espresso-core

core/services/formatters/CurrencyFormatter.php

Indentation +334 added lines, -334 removed lines

@@ -8,338 +8,338 @@
 
 class CurrencyFormatter extends LocaleFloatFormatter
 {
-    /**
-     * non-localized number no symbol or code: '123456.123456'
-     */
-    const FORMAT_PRECISION_FLOAT = 0;
-
-    /**
-     * localized number no symbol or code: '123,456.12'
-     */
-    const FORMAT_LOCALIZED_FLOAT = 1;
-
-    /**
-     * localized number with currency symbol: '$123,456.12'
-     */
-    const FORMAT_LOCALIZED_CURRENCY = 2;
-
-    /**
-     * localized number with currency symbol and code: '$123,456.12 USD'
-     */
-    const FORMAT_LOCALIZED_CURRENCY_RAW_CODE = 3;
-
-    /**
-     * localized number with currency symbol and code wrapped in span: '$123,456.12 <span>USD</span>'
-     */
-    const FORMAT_LOCALIZED_CURRENCY_HTML_CODE = 4;
-
-    /**
-     * @var EE_Currency_Config
-     */
-    protected $currency_config;
-
-
-    /**
-     * LocaleFloatFormatter constructor.
-     *
-     * @param EE_Currency_Config $currency_config
-     * @param Locales            $locales
-     */
-    public function __construct(EE_Currency_Config $currency_config, Locales $locales)
-    {
-        $this->currency_config = $currency_config;
-        parent::__construct($locales);
-    }
-
-
-    /**
-     * formats the provided amount for the selected locale (defaults to site locale) and returns a string
-     *
-     * @param Locale   $locale
-     * @param float    $amount    unformatted number value, ex: 1234.56789
-     * @param int      $format    one of the CurrencyFormatter::FORMAT_* constants
-     * @param int|null $precision the number of decimal places to round to
-     * @return string             formatted amount, ex: '1,234.57'
-     */
-    protected function format(
-        Locale $locale,
-        float $amount,
-        int $format = CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY,
-        ?int $precision = null
-    ): string {
-        // if a specific decimal precision has been requested then use that, otherwise set it for the locale
-        $precision = $precision !== null ? absint($precision) : $locale->decimalPrecision();
-        // BUT... if a specific decimal precision has been requested with no extra locale formatting
-        // then bump the precision up to our max internal value
-        $precision = $format === CurrencyFormatter::FORMAT_PRECISION_FLOAT && $precision === $locale->decimalPrecision()
-            ? LocaleFloatFormatter::DECIMAL_PRECISION
-            : $precision;
-
-        // if only a float is requested then just return now
-        if ($format < CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY) {
-            return $format === CurrencyFormatter::FORMAT_PRECISION_FLOAT
-                ? $this->precisionRound($amount)
-                : $this->roundForLocale($amount);
-        }
-        // inserts symbols for the locale's decimal and thousands separator at the appropriate places
-        $formatted_amount = $this->formatGroupings(
-            $amount,
-            absint($precision),
-            $locale->currencyDecimalPoint(),
-            $locale->currencyGrouping(),
-            $locale->currencyThousandsSeparator()
-        );
-
-        // inserts the locale's currency symbol, negative sign, and spaces at the appropriate places
-        $formatted_amount = $this->formatSymbolAndSignPositions(
-            $locale,
-            $formatted_amount,
-            $amount < 0, // negative
-            $locale->currencySymbol()
-        );
-        return $this->appendCurrencyIsoCode($locale, $formatted_amount, $format);
-    }
-
-
-    /**
-     * @param Locale $locale
-     * @param string $amount
-     * @param int    $format one of the CurrencyFormatter::FORMAT_* constants
-     * @return string        fully formatted amount with ISO code, ex: '$ 1,234.57 USD'
-     */
-    protected function appendCurrencyIsoCode(Locale $locale, string $amount, int $format): string
-    {
-        switch ($format) {
-            case CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY_RAW_CODE:
-                $iso_code = "&nbsp;{$locale->currencyIsoCode()}";
-                break;
-            case CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY_HTML_CODE:
-                $iso_code = "&nbsp;<span class=\"currency-code\">({$locale->currencyIsoCode()})</span>";
-                break;
-            default:
-                $iso_code = '';
-        }
-        // filter to allow global setting of display_code
-        $display_code = apply_filters(
-            'FHEE__EEH_Template__format_currency__display_code',
-            $format > CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY
-        );
-        $iso_code     = $display_code
-            ? $iso_code
-            : '';
-        return "{$amount}{$iso_code}";
-    }
-
-
-    /**
-     * inserts the locale's currency symbol, negative sign, and spaces at the appropriate places
-     *
-     * @param Locale $locale
-     * @param string $number
-     * @param bool   $is_negative
-     * @param string $currency_symbol
-     * @return string partially formatted amount, ex: '$ 1,234.57'
-     */
-    protected function formatSymbolAndSignPositions(
-        Locale $locale,
-        string $number,
-        bool $is_negative,
-        string $currency_symbol
-    ): string {
-        // format for positive or negative values
-        if ($is_negative) {
-            $add_spacer  = $locale->currencySymbolSpaceB4Negative();
-            $currency_b4 = $locale->currencySymbolB4Negative();
-            $position    = $locale->negativeSignPosition();
-            $sign        = $locale->negativeSign();
-        } else {
-            $add_spacer  = $locale->currencySymbolSpaceB4Positive();
-            $currency_b4 = $locale->currencySymbolB4Positive();
-            $position    = $locale->positiveSignPosition();
-            $sign        = $locale->positiveSign();
-        }
-        $spacer = $add_spacer
-            ? '&nbsp;'
-            : '';
-        switch ($position) {
-            case LocaleFloatFormatter::PARENTHESES:
-                return $currency_b4
-                    ? "({$currency_symbol}{$spacer}{$number})"
-                    : "({$number}{$spacer}{$currency_symbol})";
-            case LocaleFloatFormatter::SIGN_BEFORE_ALL:
-                return $currency_b4
-                    ? "{$sign}{$currency_symbol}{$spacer}{$number}"
-                    : "{$sign}{$number}{$spacer}{$currency_symbol}";
-            case LocaleFloatFormatter::SIGN_AFTER_ALL:
-                return $currency_b4
-                    ? "{$currency_symbol}{$spacer}{$number} {$sign}"
-                    : "{$number}{$spacer}{$currency_symbol} {$sign}";
-            case LocaleFloatFormatter::SIGN_BEFORE_CURRENCY:
-                return $currency_b4
-                    ? "{$sign}{$currency_symbol}{$spacer}{$number}"
-                    : "{$number}{$spacer}{$sign}{$currency_symbol}";
-            case LocaleFloatFormatter::SIGN_AFTER_CURRENCY:
-                return $currency_b4
-                    ? "{$currency_symbol}{$sign}{$spacer}{$number}"
-                    : "{$number}{$spacer}{$currency_symbol}{$sign}";
-        }
-        return $number;
-    }
-
-
-    /**
-     * formats the provided number for the selected locale (defaults to site locale) and returns a string
-     *
-     * @param float  $number       unformatted number value, ex: 1234.56789
-     * @param string $currency_ISO ex: "USD"
-     * @param int    $format       one of the CurrencyFormatter::FORMAT_* constants
-     * @return string              formatted value, ex: '1,234.57'
-     */
-    public function formatForCurrencyISO(
-        float $number,
-        string $currency_ISO,
-        int $format = CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY
-    ): string {
-        $locale = $this->getLocaleForCurrencyISO($currency_ISO);
-        return $this->format($locale, $number, $format);
-    }
-
-
-    /**
-     * formats the provided number for the selected locale (defaults to site locale) and returns a string
-     *
-     * @param float|int|string   $number unformatted number value, ex: 1234.56789
-     * @param int|null           $format one of the CurrencyFormatter::FORMAT_* constants
-     * @param int|null           $precision the number of decimal places to round to
-     * @param string|Locale|null $locale ex: "en_US" or Locale object
-     * @return string            formatted value, ex: '1,234.57'
-     */
-    public function formatForLocale(
-        $number,
-        ?int $format = CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY,
-        ?int $precision = null,
-        $locale = ''
-    ): string {
-        $locale = $this->getLocale($locale);
-        return $this->format($locale, (float) $number, $format, $precision);
-    }
-
-
-    /**
-     * @param string|Locale $locale locale name ex: en_US or Locale object
-     * @return string ex: 'USD'
-     */
-    public function getCurrencyIsoCodeForLocale($locale = ''): string
-    {
-        $locale = $this->getLocale($locale);
-        return $locale->currencyIsoCode();
-    }
-
-
-    /**
-     * @param string|Locale $locale locale name ex: en_US or Locale object
-     * @return string ex: '$'
-     */
-    public function getCurrencySymbolForLocale($locale = ''): string
-    {
-        $locale = $this->getLocale($locale);
-        return $locale->currencySymbol();
-    }
-
-
-    /**
-     * Schemas:
-     *    'precision_float': "1,234.567890"
-     *    'localized_float': "1,234.57"
-     *    'no_currency_code': "$1,234.57"
-     *    null: "$1,234.57<span>USD</span>"
-     *
-     * @param string $schema
-     * @param bool|null   $allow_fractional_subunits
-     * @return int
-     */
-    public function getFormatFromLegacySchema(string $schema, ?bool $allow_fractional_subunits = true): int
-    {
-        switch ($schema) {
-            case 'precision_float':
-                // return a localized float if fractional subunits are not allowed
-                return $allow_fractional_subunits
-                    ? CurrencyFormatter::FORMAT_PRECISION_FLOAT
-                    : CurrencyFormatter::FORMAT_LOCALIZED_FLOAT;
-            case 'localized_float':
-                return CurrencyFormatter::FORMAT_LOCALIZED_FLOAT;
-            case 'localized':
-            case 'localized_currency':
-            case 'no_currency_code':
-                return CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY;
-            default:
-                return CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY_HTML_CODE;
-        }
-    }
-
-
-    /**
-     * @param string|Locale $locale locale name ex: en_US or Locale object
-     * @return Locale
-     */
-    public function getLocale($locale = ''): Locale
-    {
-        $locale = $locale ?: $this->currency_config->locale();
-        return $this->locales->getLocale($locale);
-    }
-
-
-    /**
-     * @param string $currency_ISO              ex: USD
-     * @param bool   $fallback_to_site_locale   [optional] if true, will return the site locale
-     *                                          if a locale can not be identified for the supplied currency ISO
-     * @return Locale
-     */
-    public function getLocaleForCurrencyISO(string $currency_ISO, bool $fallback_to_site_locale = false): Locale
-    {
-        return $this->locales->getLocaleForCurrencyISO($currency_ISO, $fallback_to_site_locale);
-    }
-
-
-    /**
-     * @return Locale
-     */
-    public function getSiteLocale(): Locale
-    {
-        return $this->locales->getSiteLocale();
-    }
-
-
-    /**
-     * This removes all localized formatting from the incoming value and returns a float
-     *
-     * @param float|int|string $number formatted numeric value as string, ex: '1,234,567.89'
-     * @param string|Locale    $locale locale name ex: en_US or Locale object
-     * @return float                   unformatted number value, ex: 1234567.89
-     */
-    public function parseForLocale($number, $locale = ''): float
-    {
-        // just return the value if it's not a string
-        if (! is_string($number)) {
-            return (float) $number;
-        }
-        $locale = $this->getLocale($locale);
-        return $this->filterNumericValue(
-            str_replace(
-                [
-                    $locale->currencyIsoCode(),
-                    $locale->currencySymbol(),
-                    $locale->currencyThousandsSeparator(),
-                    $locale->currencyDecimalPoint(),
-                ],
-                [
-                    '',  // remove currency code
-                    '',  // remove currency symbol
-                    '',  // remove thousands separator
-                    '.', // convert decimal mark to what PHP expects
-                ],
-                $number
-            )
-        );
-    }
+	/**
+	 * non-localized number no symbol or code: '123456.123456'
+	 */
+	const FORMAT_PRECISION_FLOAT = 0;
+
+	/**
+	 * localized number no symbol or code: '123,456.12'
+	 */
+	const FORMAT_LOCALIZED_FLOAT = 1;
+
+	/**
+	 * localized number with currency symbol: '$123,456.12'
+	 */
+	const FORMAT_LOCALIZED_CURRENCY = 2;
+
+	/**
+	 * localized number with currency symbol and code: '$123,456.12 USD'
+	 */
+	const FORMAT_LOCALIZED_CURRENCY_RAW_CODE = 3;
+
+	/**
+	 * localized number with currency symbol and code wrapped in span: '$123,456.12 <span>USD</span>'
+	 */
+	const FORMAT_LOCALIZED_CURRENCY_HTML_CODE = 4;
+
+	/**
+	 * @var EE_Currency_Config
+	 */
+	protected $currency_config;
+
+
+	/**
+	 * LocaleFloatFormatter constructor.
+	 *
+	 * @param EE_Currency_Config $currency_config
+	 * @param Locales            $locales
+	 */
+	public function __construct(EE_Currency_Config $currency_config, Locales $locales)
+	{
+		$this->currency_config = $currency_config;
+		parent::__construct($locales);
+	}
+
+
+	/**
+	 * formats the provided amount for the selected locale (defaults to site locale) and returns a string
+	 *
+	 * @param Locale   $locale
+	 * @param float    $amount    unformatted number value, ex: 1234.56789
+	 * @param int      $format    one of the CurrencyFormatter::FORMAT_* constants
+	 * @param int|null $precision the number of decimal places to round to
+	 * @return string             formatted amount, ex: '1,234.57'
+	 */
+	protected function format(
+		Locale $locale,
+		float $amount,
+		int $format = CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY,
+		?int $precision = null
+	): string {
+		// if a specific decimal precision has been requested then use that, otherwise set it for the locale
+		$precision = $precision !== null ? absint($precision) : $locale->decimalPrecision();
+		// BUT... if a specific decimal precision has been requested with no extra locale formatting
+		// then bump the precision up to our max internal value
+		$precision = $format === CurrencyFormatter::FORMAT_PRECISION_FLOAT && $precision === $locale->decimalPrecision()
+			? LocaleFloatFormatter::DECIMAL_PRECISION
+			: $precision;
+
+		// if only a float is requested then just return now
+		if ($format < CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY) {
+			return $format === CurrencyFormatter::FORMAT_PRECISION_FLOAT
+				? $this->precisionRound($amount)
+				: $this->roundForLocale($amount);
+		}
+		// inserts symbols for the locale's decimal and thousands separator at the appropriate places
+		$formatted_amount = $this->formatGroupings(
+			$amount,
+			absint($precision),
+			$locale->currencyDecimalPoint(),
+			$locale->currencyGrouping(),
+			$locale->currencyThousandsSeparator()
+		);
+
+		// inserts the locale's currency symbol, negative sign, and spaces at the appropriate places
+		$formatted_amount = $this->formatSymbolAndSignPositions(
+			$locale,
+			$formatted_amount,
+			$amount < 0, // negative
+			$locale->currencySymbol()
+		);
+		return $this->appendCurrencyIsoCode($locale, $formatted_amount, $format);
+	}
+
+
+	/**
+	 * @param Locale $locale
+	 * @param string $amount
+	 * @param int    $format one of the CurrencyFormatter::FORMAT_* constants
+	 * @return string        fully formatted amount with ISO code, ex: '$ 1,234.57 USD'
+	 */
+	protected function appendCurrencyIsoCode(Locale $locale, string $amount, int $format): string
+	{
+		switch ($format) {
+			case CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY_RAW_CODE:
+				$iso_code = "&nbsp;{$locale->currencyIsoCode()}";
+				break;
+			case CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY_HTML_CODE:
+				$iso_code = "&nbsp;<span class=\"currency-code\">({$locale->currencyIsoCode()})</span>";
+				break;
+			default:
+				$iso_code = '';
+		}
+		// filter to allow global setting of display_code
+		$display_code = apply_filters(
+			'FHEE__EEH_Template__format_currency__display_code',
+			$format > CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY
+		);
+		$iso_code     = $display_code
+			? $iso_code
+			: '';
+		return "{$amount}{$iso_code}";
+	}
+
+
+	/**
+	 * inserts the locale's currency symbol, negative sign, and spaces at the appropriate places
+	 *
+	 * @param Locale $locale
+	 * @param string $number
+	 * @param bool   $is_negative
+	 * @param string $currency_symbol
+	 * @return string partially formatted amount, ex: '$ 1,234.57'
+	 */
+	protected function formatSymbolAndSignPositions(
+		Locale $locale,
+		string $number,
+		bool $is_negative,
+		string $currency_symbol
+	): string {
+		// format for positive or negative values
+		if ($is_negative) {
+			$add_spacer  = $locale->currencySymbolSpaceB4Negative();
+			$currency_b4 = $locale->currencySymbolB4Negative();
+			$position    = $locale->negativeSignPosition();
+			$sign        = $locale->negativeSign();
+		} else {
+			$add_spacer  = $locale->currencySymbolSpaceB4Positive();
+			$currency_b4 = $locale->currencySymbolB4Positive();
+			$position    = $locale->positiveSignPosition();
+			$sign        = $locale->positiveSign();
+		}
+		$spacer = $add_spacer
+			? '&nbsp;'
+			: '';
+		switch ($position) {
+			case LocaleFloatFormatter::PARENTHESES:
+				return $currency_b4
+					? "({$currency_symbol}{$spacer}{$number})"
+					: "({$number}{$spacer}{$currency_symbol})";
+			case LocaleFloatFormatter::SIGN_BEFORE_ALL:
+				return $currency_b4
+					? "{$sign}{$currency_symbol}{$spacer}{$number}"
+					: "{$sign}{$number}{$spacer}{$currency_symbol}";
+			case LocaleFloatFormatter::SIGN_AFTER_ALL:
+				return $currency_b4
+					? "{$currency_symbol}{$spacer}{$number} {$sign}"
+					: "{$number}{$spacer}{$currency_symbol} {$sign}";
+			case LocaleFloatFormatter::SIGN_BEFORE_CURRENCY:
+				return $currency_b4
+					? "{$sign}{$currency_symbol}{$spacer}{$number}"
+					: "{$number}{$spacer}{$sign}{$currency_symbol}";
+			case LocaleFloatFormatter::SIGN_AFTER_CURRENCY:
+				return $currency_b4
+					? "{$currency_symbol}{$sign}{$spacer}{$number}"
+					: "{$number}{$spacer}{$currency_symbol}{$sign}";
+		}
+		return $number;
+	}
+
+
+	/**
+	 * formats the provided number for the selected locale (defaults to site locale) and returns a string
+	 *
+	 * @param float  $number       unformatted number value, ex: 1234.56789
+	 * @param string $currency_ISO ex: "USD"
+	 * @param int    $format       one of the CurrencyFormatter::FORMAT_* constants
+	 * @return string              formatted value, ex: '1,234.57'
+	 */
+	public function formatForCurrencyISO(
+		float $number,
+		string $currency_ISO,
+		int $format = CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY
+	): string {
+		$locale = $this->getLocaleForCurrencyISO($currency_ISO);
+		return $this->format($locale, $number, $format);
+	}
+
+
+	/**
+	 * formats the provided number for the selected locale (defaults to site locale) and returns a string
+	 *
+	 * @param float|int|string   $number unformatted number value, ex: 1234.56789
+	 * @param int|null           $format one of the CurrencyFormatter::FORMAT_* constants
+	 * @param int|null           $precision the number of decimal places to round to
+	 * @param string|Locale|null $locale ex: "en_US" or Locale object
+	 * @return string            formatted value, ex: '1,234.57'
+	 */
+	public function formatForLocale(
+		$number,
+		?int $format = CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY,
+		?int $precision = null,
+		$locale = ''
+	): string {
+		$locale = $this->getLocale($locale);
+		return $this->format($locale, (float) $number, $format, $precision);
+	}
+
+
+	/**
+	 * @param string|Locale $locale locale name ex: en_US or Locale object
+	 * @return string ex: 'USD'
+	 */
+	public function getCurrencyIsoCodeForLocale($locale = ''): string
+	{
+		$locale = $this->getLocale($locale);
+		return $locale->currencyIsoCode();
+	}
+
+
+	/**
+	 * @param string|Locale $locale locale name ex: en_US or Locale object
+	 * @return string ex: '$'
+	 */
+	public function getCurrencySymbolForLocale($locale = ''): string
+	{
+		$locale = $this->getLocale($locale);
+		return $locale->currencySymbol();
+	}
+
+
+	/**
+	 * Schemas:
+	 *    'precision_float': "1,234.567890"
+	 *    'localized_float': "1,234.57"
+	 *    'no_currency_code': "$1,234.57"
+	 *    null: "$1,234.57<span>USD</span>"
+	 *
+	 * @param string $schema
+	 * @param bool|null   $allow_fractional_subunits
+	 * @return int
+	 */
+	public function getFormatFromLegacySchema(string $schema, ?bool $allow_fractional_subunits = true): int
+	{
+		switch ($schema) {
+			case 'precision_float':
+				// return a localized float if fractional subunits are not allowed
+				return $allow_fractional_subunits
+					? CurrencyFormatter::FORMAT_PRECISION_FLOAT
+					: CurrencyFormatter::FORMAT_LOCALIZED_FLOAT;
+			case 'localized_float':
+				return CurrencyFormatter::FORMAT_LOCALIZED_FLOAT;
+			case 'localized':
+			case 'localized_currency':
+			case 'no_currency_code':
+				return CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY;
+			default:
+				return CurrencyFormatter::FORMAT_LOCALIZED_CURRENCY_HTML_CODE;
+		}
+	}
+
+
+	/**
+	 * @param string|Locale $locale locale name ex: en_US or Locale object
+	 * @return Locale
+	 */
+	public function getLocale($locale = ''): Locale
+	{
+		$locale = $locale ?: $this->currency_config->locale();
+		return $this->locales->getLocale($locale);
+	}
+
+
+	/**
+	 * @param string $currency_ISO              ex: USD
+	 * @param bool   $fallback_to_site_locale   [optional] if true, will return the site locale
+	 *                                          if a locale can not be identified for the supplied currency ISO
+	 * @return Locale
+	 */
+	public function getLocaleForCurrencyISO(string $currency_ISO, bool $fallback_to_site_locale = false): Locale
+	{
+		return $this->locales->getLocaleForCurrencyISO($currency_ISO, $fallback_to_site_locale);
+	}
+
+
+	/**
+	 * @return Locale
+	 */
+	public function getSiteLocale(): Locale
+	{
+		return $this->locales->getSiteLocale();
+	}
+
+
+	/**
+	 * This removes all localized formatting from the incoming value and returns a float
+	 *
+	 * @param float|int|string $number formatted numeric value as string, ex: '1,234,567.89'
+	 * @param string|Locale    $locale locale name ex: en_US or Locale object
+	 * @return float                   unformatted number value, ex: 1234567.89
+	 */
+	public function parseForLocale($number, $locale = ''): float
+	{
+		// just return the value if it's not a string
+		if (! is_string($number)) {
+			return (float) $number;
+		}
+		$locale = $this->getLocale($locale);
+		return $this->filterNumericValue(
+			str_replace(
+				[
+					$locale->currencyIsoCode(),
+					$locale->currencySymbol(),
+					$locale->currencyThousandsSeparator(),
+					$locale->currencyDecimalPoint(),
+				],
+				[
+					'',  // remove currency code
+					'',  // remove currency symbol
+					'',  // remove thousands separator
+					'.', // convert decimal mark to what PHP expects
+				],
+				$number
+			)
+		);
+	}
 }

core/services/formatters/LocaleFloatFormatter.php

Indentation +151 added lines, -151 removed lines

@@ -15,159 +15,159 @@
  */
 abstract class LocaleFloatFormatter implements LocaleFloatFormatterInterface, InterminableInterface
 {
-    /**
-     * number of decimal places used for high precision internal calculations and storage
-     */
-    const DECIMAL_PRECISION = 6;
+	/**
+	 * number of decimal places used for high precision internal calculations and storage
+	 */
+	const DECIMAL_PRECISION = 6;
 
-    /*
+	/*
      * the following constants represent the values returned for 'n_sign_posn' && 'p_sign_posn'
      */
 
-    /**
-     * 0 - Parentheses surround the quantity and currency_symbol
-     */
-    const PARENTHESES = 0;
-
-    /**
-     * 1 - The sign string precedes the quantity and currency_symbol
-     */
-    const SIGN_BEFORE_ALL = 1;
-
-    /**
-     * 2 - The sign string follows the quantity and currency_symbol
-     */
-    const SIGN_AFTER_ALL = 2;
-
-    /**
-     * 3 - The sign string immediately precedes the currency_symbol
-     */
-    const SIGN_BEFORE_CURRENCY = 3;
-
-    /**
-     * 4 - The sign string immediately follows the currency_symbol
-     */
-    const SIGN_AFTER_CURRENCY = 4;
-
-    /**
-     * @var Locales
-     */
-    protected $locales;
-
-
-    /**
-     * LocaleFloatFormatter constructor.
-     *
-     * @param Locales $locales
-     */
-    public function __construct(Locales $locales)
-    {
-        $this->locales = $locales;
-    }
-
-
-    /**
-     * inserts symbols for the locale's decimal and thousands separator at the appropriate places
-     *
-     * @param float  $number
-     * @param int    $precision
-     * @param string $decimal_point
-     * @param int    $grouping
-     * @param string $thousands_separator
-     * @return string
-     */
-    protected function formatGroupings(
-        float $number,
-        int $precision,
-        string $decimal_point,
-        int $grouping,
-        string $thousands_separator
-    ): string {
-        // remove sign (+-), cast to string, then break apart at the decimal place
-        $parts = explode('.', (string) abs($number));
-        // separate the integer and decimal portions of the number into separate variables
-        [$integer, $decimal] = $parts + [0, 0];
-        // ok this gets a bit crazy, but we need to insert the locale's thousand separator
-        // at the correct intervals for the locale, so 123456789 can be something like "123,456,879" or "1.23.45.67.89"
-        // so we're first going to reverse the string, then use chunk_split() to give us something like "987,654,321"
-        // why reverse the number first? cuz otherwise something like "1234" would become "123,4" not "1,234"
-        $formatted_number = chunk_split(strrev($integer), $grouping, $thousands_separator);
-        // so THEN we reverse the string again and remove any extra separators
-        $formatted_number = ltrim(strrev($formatted_number), $thousands_separator);
-        if ($precision === 0) {
-            return $formatted_number;
-        }
-        // now let's deal with the decimal places, by first adding a decimal to an otherwise non-decimal number
-        $decimal = "0.$decimal";
-        // then type cast the string to a float and round to the appropriate precision for the locale
-        $decimal = round((float) $decimal, $precision);
-        // now type cast back to a string, and remove the first two characters ( the "0." added earlier )
-        $decimal = substr((string) $decimal, 2, $precision);
-        // now add any extra zeros to the correct precision
-        $decimal = str_pad($decimal, $precision, '0');
-        // the final fully formatted result is as simple as stringing it all together
-        return $formatted_number . $decimal_point . $decimal;
-    }
-
-
-    /**
-     * Removes all characters except digits, +- and .
-     *
-     * @param float|int|string $number
-     * @return float
-     */
-    public function filterNumericValue($number): float
-    {
-        return (float) filter_var($number, FILTER_SANITIZE_NUMBER_FLOAT, FILTER_FLAG_ALLOW_FRACTION);
-    }
-
-
-    /**
-     * formats the provided number to 6 decimal places using the site locale and returns a string
-     *
-     * @param float|int|string $number unformatted float, ex: 1.23456789
-     * @return string                  formatted number value, ex: '1.234568'
-     */
-    public function precisionFormat($number): string
-    {
-        $locale = $this->locales->getLocale($this->locales->getSiteLocaleName());
-        return $this->format($locale, $number, LocaleFloatFormatter::DECIMAL_PRECISION);
-    }
-
-
-    /**
-     * strips formatting using the site locale, then rounds the provided number to 6 decimal places and returns a float
-     *
-     * @param float|int|string $number    unformatted number value, ex: 1234.5678956789
-     * @param int|null         $precision the number of decimal places to round to
-     * @param int              $mode      one of the PHP_ROUND_* constants for round up, round down, etc
-     * @return float                      rounded value, ex: 1,234.567896
-     */
-    public function precisionRound(
-        $number,
-        ?int $precision = LocaleFloatFormatter::DECIMAL_PRECISION,
-        int $mode = PHP_ROUND_HALF_UP
-    ): float {
-        return round(
-            $this->filterNumericValue($number),
-            $precision,
-            $mode
-        );
-    }
-
-
-    /**
-     * strips formatting for the provided locale (defaults to site locale),
-     * then rounds the provided number and returns a float
-     *
-     * @param float|int|string $number unformatted number value, ex: 1234.56789
-     * @param string|Locale    $locale ex: 'en_US' or Locale object
-     * @param int              $mode   one of the PHP_ROUND_* constants for round up, round down, etc
-     * @return float                   rounded value, ex: 1,234.57
-     */
-    public function roundForLocale($number, $locale = '', int $mode = PHP_ROUND_HALF_UP): float
-    {
-        $locale = $this->locales->getLocale($locale);
-        return round($this->filterNumericValue($number), $locale->decimalPrecision(), $mode);
-    }
+	/**
+	 * 0 - Parentheses surround the quantity and currency_symbol
+	 */
+	const PARENTHESES = 0;
+
+	/**
+	 * 1 - The sign string precedes the quantity and currency_symbol
+	 */
+	const SIGN_BEFORE_ALL = 1;
+
+	/**
+	 * 2 - The sign string follows the quantity and currency_symbol
+	 */
+	const SIGN_AFTER_ALL = 2;
+
+	/**
+	 * 3 - The sign string immediately precedes the currency_symbol
+	 */
+	const SIGN_BEFORE_CURRENCY = 3;
+
+	/**
+	 * 4 - The sign string immediately follows the currency_symbol
+	 */
+	const SIGN_AFTER_CURRENCY = 4;
+
+	/**
+	 * @var Locales
+	 */
+	protected $locales;
+
+
+	/**
+	 * LocaleFloatFormatter constructor.
+	 *
+	 * @param Locales $locales
+	 */
+	public function __construct(Locales $locales)
+	{
+		$this->locales = $locales;
+	}
+
+
+	/**
+	 * inserts symbols for the locale's decimal and thousands separator at the appropriate places
+	 *
+	 * @param float  $number
+	 * @param int    $precision
+	 * @param string $decimal_point
+	 * @param int    $grouping
+	 * @param string $thousands_separator
+	 * @return string
+	 */
+	protected function formatGroupings(
+		float $number,
+		int $precision,
+		string $decimal_point,
+		int $grouping,
+		string $thousands_separator
+	): string {
+		// remove sign (+-), cast to string, then break apart at the decimal place
+		$parts = explode('.', (string) abs($number));
+		// separate the integer and decimal portions of the number into separate variables
+		[$integer, $decimal] = $parts + [0, 0];
+		// ok this gets a bit crazy, but we need to insert the locale's thousand separator
+		// at the correct intervals for the locale, so 123456789 can be something like "123,456,879" or "1.23.45.67.89"
+		// so we're first going to reverse the string, then use chunk_split() to give us something like "987,654,321"
+		// why reverse the number first? cuz otherwise something like "1234" would become "123,4" not "1,234"
+		$formatted_number = chunk_split(strrev($integer), $grouping, $thousands_separator);
+		// so THEN we reverse the string again and remove any extra separators
+		$formatted_number = ltrim(strrev($formatted_number), $thousands_separator);
+		if ($precision === 0) {
+			return $formatted_number;
+		}
+		// now let's deal with the decimal places, by first adding a decimal to an otherwise non-decimal number
+		$decimal = "0.$decimal";
+		// then type cast the string to a float and round to the appropriate precision for the locale
+		$decimal = round((float) $decimal, $precision);
+		// now type cast back to a string, and remove the first two characters ( the "0." added earlier )
+		$decimal = substr((string) $decimal, 2, $precision);
+		// now add any extra zeros to the correct precision
+		$decimal = str_pad($decimal, $precision, '0');
+		// the final fully formatted result is as simple as stringing it all together
+		return $formatted_number . $decimal_point . $decimal;
+	}
+
+
+	/**
+	 * Removes all characters except digits, +- and .
+	 *
+	 * @param float|int|string $number
+	 * @return float
+	 */
+	public function filterNumericValue($number): float
+	{
+		return (float) filter_var($number, FILTER_SANITIZE_NUMBER_FLOAT, FILTER_FLAG_ALLOW_FRACTION);
+	}
+
+
+	/**
+	 * formats the provided number to 6 decimal places using the site locale and returns a string
+	 *
+	 * @param float|int|string $number unformatted float, ex: 1.23456789
+	 * @return string                  formatted number value, ex: '1.234568'
+	 */
+	public function precisionFormat($number): string
+	{
+		$locale = $this->locales->getLocale($this->locales->getSiteLocaleName());
+		return $this->format($locale, $number, LocaleFloatFormatter::DECIMAL_PRECISION);
+	}
+
+
+	/**
+	 * strips formatting using the site locale, then rounds the provided number to 6 decimal places and returns a float
+	 *
+	 * @param float|int|string $number    unformatted number value, ex: 1234.5678956789
+	 * @param int|null         $precision the number of decimal places to round to
+	 * @param int              $mode      one of the PHP_ROUND_* constants for round up, round down, etc
+	 * @return float                      rounded value, ex: 1,234.567896
+	 */
+	public function precisionRound(
+		$number,
+		?int $precision = LocaleFloatFormatter::DECIMAL_PRECISION,
+		int $mode = PHP_ROUND_HALF_UP
+	): float {
+		return round(
+			$this->filterNumericValue($number),
+			$precision,
+			$mode
+		);
+	}
+
+
+	/**
+	 * strips formatting for the provided locale (defaults to site locale),
+	 * then rounds the provided number and returns a float
+	 *
+	 * @param float|int|string $number unformatted number value, ex: 1234.56789
+	 * @param string|Locale    $locale ex: 'en_US' or Locale object
+	 * @param int              $mode   one of the PHP_ROUND_* constants for round up, round down, etc
+	 * @return float                   rounded value, ex: 1,234.57
+	 */
+	public function roundForLocale($number, $locale = '', int $mode = PHP_ROUND_HALF_UP): float
+	{
+		$locale = $this->locales->getLocale($locale);
+		return round($this->filterNumericValue($number), $locale->decimalPrecision(), $mode);
+	}
 }

core/services/address/formatters/AddressFormatter.php

Indentation +34 added lines, -34 removed lines

@@ -12,38 +12,38 @@
  */
 class AddressFormatter
 {
-    // phpcs:disable PSR1.Methods.CamelCapsMethodName.NotCamelCaps
-    /**
-     * @param string $address
-     * @param string $address2
-     * @param string $city
-     * @param string $state
-     * @param string $zip
-     * @param string $country
-     * @param string $formatted_address
-     * @param string $sub
-     * @return string
-     */
-    protected function parse_formatted_address(
-        string $address,
-        string $address2,
-        string $city,
-        string $state,
-        string $zip,
-        string $country,
-        string $formatted_address,
-        string $sub
-    ): string {
-        // swap address part placeholders for the real text
-        $formatted_address = str_replace(
-            // find
-            array('{address}', '{address2}', '{city}', '{state}', '{zip}', '{country}'),
-            // replace
-            array($address, $address2, $city, $state, $zip, $country),
-            // string
-            $formatted_address
-        );
-        // remove placeholder from start and end, reduce repeating placeholders to singles, then replace with HTML line breaks
-        return preg_replace('/%+/', $sub, trim($formatted_address, '%'));
-    }
+	// phpcs:disable PSR1.Methods.CamelCapsMethodName.NotCamelCaps
+	/**
+	 * @param string $address
+	 * @param string $address2
+	 * @param string $city
+	 * @param string $state
+	 * @param string $zip
+	 * @param string $country
+	 * @param string $formatted_address
+	 * @param string $sub
+	 * @return string
+	 */
+	protected function parse_formatted_address(
+		string $address,
+		string $address2,
+		string $city,
+		string $state,
+		string $zip,
+		string $country,
+		string $formatted_address,
+		string $sub
+	): string {
+		// swap address part placeholders for the real text
+		$formatted_address = str_replace(
+			// find
+			array('{address}', '{address2}', '{city}', '{state}', '{zip}', '{country}'),
+			// replace
+			array($address, $address2, $city, $state, $zip, $country),
+			// string
+			$formatted_address
+		);
+		// remove placeholder from start and end, reduce repeating placeholders to singles, then replace with HTML line breaks
+		return preg_replace('/%+/', $sub, trim($formatted_address, '%'));
+	}
 }

core/domain/services/validation/email/EmailValidationService.php

Indentation +133 added lines, -133 removed lines

@@ -19,137 +19,137 @@
  */
 class EmailValidationService implements EmailValidatorInterface
 {
-    public const VALIDATION_LEVEL_BASIC      = 'basic';
-
-    public const VALIDATION_LEVEL_I18N       = 'i18n';
-
-    public const VALIDATION_LEVEL_I18N_DNS   = 'i18n_dns';
-
-    public const VALIDATION_LEVEL_WP_DEFAULT = 'wp_default';
-
-
-    /**
-     * @var EE_Registration_Config
-     */
-    protected $registration_config;
-
-    /**
-     * @var Loader
-     */
-    protected $loader;
-
-    /**
-     * @var Basic
-     */
-    private $validator_basic;
-
-    /**
-     * @var International
-     */
-    private $validator_i18n;
-
-    /**
-     * @var InternationalDNS
-     */
-    private $validator_i18n_dns;
-
-    /**
-     * @var WordPress
-     */
-    private $validator_wordpress;
-
-
-
-    /**
-     * EmailValidationService constructor.
-     * Accepts an \EE_Config as an argument.
-     *
-     * @param EE_Registration_Config $config
-     * @param Loader                 $loader
-     */
-    public function __construct(EE_Registration_Config $config, Loader $loader)
-    {
-        $this->registration_config = $config;
-        $this->loader = $loader;
-    }
-
-
-    /**
-     * Validates the email address. If it's invalid, an EmailValidationException
-     * is thrown that describes why its invalid.
-     *
-     * @param string|null $email_address
-     * @return boolean
-     */
-    public function validate(?string $email_address): bool
-    {
-        // pick the correct validator according to the config
-        switch ($this->registration_config->email_validation_level) {
-            case EmailValidationService::VALIDATION_LEVEL_BASIC:
-                return $this->basicValidator()->validate($email_address);
-            case EmailValidationService::VALIDATION_LEVEL_I18N:
-                return $this->i18nValidator()->validate($email_address);
-            case EmailValidationService::VALIDATION_LEVEL_I18N_DNS:
-                return $this->i18nDnsValidator()->validate($email_address);
-            case EmailValidationService::VALIDATION_LEVEL_WP_DEFAULT:
-            default:
-                return $this->wordpressValidator()->validate($email_address);
-        }
-    }
-
-
-    /**
-     * @return Basic
-     */
-    public function basicValidator(): Basic
-    {
-        if (! $this->validator_basic instanceof Basic) {
-            $this->validator_basic = $this->loader->getShared(
-                'EventEspresso\core\domain\services\validation\email\strategies\Basic'
-            );
-        }
-        return $this->validator_basic;
-    }
-
-
-    /**
-     * @return International
-     */
-    public function i18nValidator(): International
-    {
-        if (! $this->validator_i18n instanceof Basic) {
-            $this->validator_i18n = $this->loader->getShared(
-                'EventEspresso\core\domain\services\validation\email\strategies\International'
-            );
-        }
-        return $this->validator_i18n;
-    }
-
-
-    /**
-     * @return InternationalDNS
-     */
-    public function i18nDnsValidator(): InternationalDNS
-    {
-        if (! $this->validator_i18n_dns instanceof Basic) {
-            $this->validator_i18n_dns = $this->loader->getShared(
-                'EventEspresso\core\domain\services\validation\email\strategies\InternationalDNS'
-            );
-        }
-        return $this->validator_i18n_dns;
-    }
-
-
-    /**
-     * @return WordPress
-     */
-    public function wordpressValidator(): WordPress
-    {
-        if (! $this->validator_wordpress instanceof Basic) {
-            $this->validator_wordpress = $this->loader->getShared(
-                'EventEspresso\core\domain\services\validation\email\strategies\WordPress'
-            );
-        }
-        return $this->validator_wordpress;
-    }
+	public const VALIDATION_LEVEL_BASIC      = 'basic';
+
+	public const VALIDATION_LEVEL_I18N       = 'i18n';
+
+	public const VALIDATION_LEVEL_I18N_DNS   = 'i18n_dns';
+
+	public const VALIDATION_LEVEL_WP_DEFAULT = 'wp_default';
+
+
+	/**
+	 * @var EE_Registration_Config
+	 */
+	protected $registration_config;
+
+	/**
+	 * @var Loader
+	 */
+	protected $loader;
+
+	/**
+	 * @var Basic
+	 */
+	private $validator_basic;
+
+	/**
+	 * @var International
+	 */
+	private $validator_i18n;
+
+	/**
+	 * @var InternationalDNS
+	 */
+	private $validator_i18n_dns;
+
+	/**
+	 * @var WordPress
+	 */
+	private $validator_wordpress;
+
+
+
+	/**
+	 * EmailValidationService constructor.
+	 * Accepts an \EE_Config as an argument.
+	 *
+	 * @param EE_Registration_Config $config
+	 * @param Loader                 $loader
+	 */
+	public function __construct(EE_Registration_Config $config, Loader $loader)
+	{
+		$this->registration_config = $config;
+		$this->loader = $loader;
+	}
+
+
+	/**
+	 * Validates the email address. If it's invalid, an EmailValidationException
+	 * is thrown that describes why its invalid.
+	 *
+	 * @param string|null $email_address
+	 * @return boolean
+	 */
+	public function validate(?string $email_address): bool
+	{
+		// pick the correct validator according to the config
+		switch ($this->registration_config->email_validation_level) {
+			case EmailValidationService::VALIDATION_LEVEL_BASIC:
+				return $this->basicValidator()->validate($email_address);
+			case EmailValidationService::VALIDATION_LEVEL_I18N:
+				return $this->i18nValidator()->validate($email_address);
+			case EmailValidationService::VALIDATION_LEVEL_I18N_DNS:
+				return $this->i18nDnsValidator()->validate($email_address);
+			case EmailValidationService::VALIDATION_LEVEL_WP_DEFAULT:
+			default:
+				return $this->wordpressValidator()->validate($email_address);
+		}
+	}
+
+
+	/**
+	 * @return Basic
+	 */
+	public function basicValidator(): Basic
+	{
+		if (! $this->validator_basic instanceof Basic) {
+			$this->validator_basic = $this->loader->getShared(
+				'EventEspresso\core\domain\services\validation\email\strategies\Basic'
+			);
+		}
+		return $this->validator_basic;
+	}
+
+
+	/**
+	 * @return International
+	 */
+	public function i18nValidator(): International
+	{
+		if (! $this->validator_i18n instanceof Basic) {
+			$this->validator_i18n = $this->loader->getShared(
+				'EventEspresso\core\domain\services\validation\email\strategies\International'
+			);
+		}
+		return $this->validator_i18n;
+	}
+
+
+	/**
+	 * @return InternationalDNS
+	 */
+	public function i18nDnsValidator(): InternationalDNS
+	{
+		if (! $this->validator_i18n_dns instanceof Basic) {
+			$this->validator_i18n_dns = $this->loader->getShared(
+				'EventEspresso\core\domain\services\validation\email\strategies\InternationalDNS'
+			);
+		}
+		return $this->validator_i18n_dns;
+	}
+
+
+	/**
+	 * @return WordPress
+	 */
+	public function wordpressValidator(): WordPress
+	{
+		if (! $this->validator_wordpress instanceof Basic) {
+			$this->validator_wordpress = $this->loader->getShared(
+				'EventEspresso\core\domain\services\validation\email\strategies\WordPress'
+			);
+		}
+		return $this->validator_wordpress;
+	}
 }

core/db_models/fields/EE_Money_Field.php

Indentation +162 added lines, -162 removed lines

@@ -9,166 +9,166 @@
  */
 class EE_Money_Field extends EE_Float_Field
 {
-    /**
-     * if true, then money values will be accurate to 6 decimal places
-     * if false, then money values will be rounded to the correct number of subunits for the site's currency
-     *
-     * @var   bool
-     * @since $VID:$
-     */
-    protected $allow_fractional_subunits;
-
-    /**
-     * @var CurrencyFormatter
-     * @since $VID:$
-     */
-    protected $currency_formatter;
-
-
-    /**
-     * @param string     $table_column
-     * @param string     $nice_name
-     * @param bool|null  $nullable
-     * @param float|null $default_value
-     * @param bool|null  $allow_fractional_subunits
-     */
-    public function __construct(
-        string $table_column,
-        string $nice_name,
-        ?bool $nullable = false,
-        ?float $default_value = 0,
-        ?bool $allow_fractional_subunits = true
-    ) {
-        parent::__construct($table_column, $nice_name, $nullable, $default_value);
-        $this->allow_fractional_subunits = $allow_fractional_subunits;
-        // in a better world this would have been injected upon construction
-        if (! $this->currency_formatter instanceof CurrencyFormatter) {
-            $this->currency_formatter = LoaderFactory::getLoader()->getShared(CurrencyFormatter::class);
-        }
-        $this->setSchemaType('object');
-    }
-
-
-    /**
-     * Returns whether or not this money field allows partial penny amounts
-     *
-     * @return boolean
-     */
-    public function allowFractionalSubunits(): ?bool
-    {
-        return $this->allow_fractional_subunits;
-    }
-
-
-    /**
-     * Schemas:
-     *    'localized_float': '3,023.00'
-     *    'no_currency_code': '$3,023.00'
-     *    null: '$3,023.00<span>USD</span>'
-     *
-     * @param float|int|string $amount
-     * @param string|null      $schema
-     * @return string
-     * @since $VID:$
-     */
-    public function prepare_for_get($amount, ?string $schema = 'precision_float'): string
-    {
-        $schema = $schema ? $schema : 'precision_float';
-        return $this->currency_formatter->formatForLocale(
-            (float) $amount,
-            $this->currency_formatter->getFormatFromLegacySchema($schema, $this->allow_fractional_subunits)
-        );
-    }
-
-
-    /**
-     * Schemas:
-     *    'localized_float': "3,023.00"
-     *    'no_currency_code': "$3,023.00"
-     *    null: "$3,023.00<span>USD</span>"
-     *
-     * @param float|int|string $amount
-     * @param string|null      $schema
-     * @return string
-     */
-    public function prepare_for_pretty_echoing($amount, ?string $schema = 'localized_currency'): string
-    {
-        $schema = $schema ?? 'localized_currency';
-        return $this->currency_formatter->formatForLocale(
-            (float) $amount,
-            $this->currency_formatter->getFormatFromLegacySchema($schema, $this->allow_fractional_subunits)
-        );
-    }
-
-
-    /**
-     * Converts periods and commas according to the country's currency settings.
-     * Strips out money-related formatting to turn it into a proper float.
-     * If fractional subunits are not allowed,
-     * it rounds the float to the correct number of decimal places for this country's currency.
-     *
-     * @param float|int|string $amount
-     * @param string|null      $schema
-     * @return float
-     */
-    public function prepare_for_set($amount, $schema = ''): float
-    {
-        $amount = $this->currency_formatter->parseForLocale($amount);
-        return $this->prepare_for_set_from_db($amount);
-    }
-
-
-    /**
-     * @param float $amount
-     * @return float
-     */
-    public function prepare_for_set_from_db($amount): float
-    {
-        return $this->allowFractionalSubunits()
-            ? $this->currency_formatter->precisionRound($amount)
-            : $this->currency_formatter->roundForLocale($amount);
-    }
-
-
-    /**
-     * @return array[]
-     */
-    public function getSchemaProperties(): array
-    {
-        return [
-            'raw'    => [
-                'description' => sprintf(
-                    esc_html__(
-                        '%s - the raw value as it exists in the database as a simple float.',
-                        'event_espresso'
-                    ),
-                    $this->get_nicename()
-                ),
-                'type'        => 'number',
-            ],
-            'pretty' => [
-                'description' => sprintf(
-                    esc_html__(
-                        '%s - formatted for display in the set currency and decimal places.',
-                        'event_espresso'
-                    ),
-                    $this->get_nicename()
-                ),
-                'type'        => 'string',
-                'format'      => 'money',
-            ],
-        ];
-    }
-
-
-    /**
-     * Returns whether or not this money field allows partial penny amounts
-     *
-     * @deprecatd $VID:$
-     * @return boolean
-     */
-    public function whole_pennies_only(): ?bool
-    {
-        return $this->allow_fractional_subunits;
-    }
+	/**
+	 * if true, then money values will be accurate to 6 decimal places
+	 * if false, then money values will be rounded to the correct number of subunits for the site's currency
+	 *
+	 * @var   bool
+	 * @since $VID:$
+	 */
+	protected $allow_fractional_subunits;
+
+	/**
+	 * @var CurrencyFormatter
+	 * @since $VID:$
+	 */
+	protected $currency_formatter;
+
+
+	/**
+	 * @param string     $table_column
+	 * @param string     $nice_name
+	 * @param bool|null  $nullable
+	 * @param float|null $default_value
+	 * @param bool|null  $allow_fractional_subunits
+	 */
+	public function __construct(
+		string $table_column,
+		string $nice_name,
+		?bool $nullable = false,
+		?float $default_value = 0,
+		?bool $allow_fractional_subunits = true
+	) {
+		parent::__construct($table_column, $nice_name, $nullable, $default_value);
+		$this->allow_fractional_subunits = $allow_fractional_subunits;
+		// in a better world this would have been injected upon construction
+		if (! $this->currency_formatter instanceof CurrencyFormatter) {
+			$this->currency_formatter = LoaderFactory::getLoader()->getShared(CurrencyFormatter::class);
+		}
+		$this->setSchemaType('object');
+	}
+
+
+	/**
+	 * Returns whether or not this money field allows partial penny amounts
+	 *
+	 * @return boolean
+	 */
+	public function allowFractionalSubunits(): ?bool
+	{
+		return $this->allow_fractional_subunits;
+	}
+
+
+	/**
+	 * Schemas:
+	 *    'localized_float': '3,023.00'
+	 *    'no_currency_code': '$3,023.00'
+	 *    null: '$3,023.00<span>USD</span>'
+	 *
+	 * @param float|int|string $amount
+	 * @param string|null      $schema
+	 * @return string
+	 * @since $VID:$
+	 */
+	public function prepare_for_get($amount, ?string $schema = 'precision_float'): string
+	{
+		$schema = $schema ? $schema : 'precision_float';
+		return $this->currency_formatter->formatForLocale(
+			(float) $amount,
+			$this->currency_formatter->getFormatFromLegacySchema($schema, $this->allow_fractional_subunits)
+		);
+	}
+
+
+	/**
+	 * Schemas:
+	 *    'localized_float': "3,023.00"
+	 *    'no_currency_code': "$3,023.00"
+	 *    null: "$3,023.00<span>USD</span>"
+	 *
+	 * @param float|int|string $amount
+	 * @param string|null      $schema
+	 * @return string
+	 */
+	public function prepare_for_pretty_echoing($amount, ?string $schema = 'localized_currency'): string
+	{
+		$schema = $schema ?? 'localized_currency';
+		return $this->currency_formatter->formatForLocale(
+			(float) $amount,
+			$this->currency_formatter->getFormatFromLegacySchema($schema, $this->allow_fractional_subunits)
+		);
+	}
+
+
+	/**
+	 * Converts periods and commas according to the country's currency settings.
+	 * Strips out money-related formatting to turn it into a proper float.
+	 * If fractional subunits are not allowed,
+	 * it rounds the float to the correct number of decimal places for this country's currency.
+	 *
+	 * @param float|int|string $amount
+	 * @param string|null      $schema
+	 * @return float
+	 */
+	public function prepare_for_set($amount, $schema = ''): float
+	{
+		$amount = $this->currency_formatter->parseForLocale($amount);
+		return $this->prepare_for_set_from_db($amount);
+	}
+
+
+	/**
+	 * @param float $amount
+	 * @return float
+	 */
+	public function prepare_for_set_from_db($amount): float
+	{
+		return $this->allowFractionalSubunits()
+			? $this->currency_formatter->precisionRound($amount)
+			: $this->currency_formatter->roundForLocale($amount);
+	}
+
+
+	/**
+	 * @return array[]
+	 */
+	public function getSchemaProperties(): array
+	{
+		return [
+			'raw'    => [
+				'description' => sprintf(
+					esc_html__(
+						'%s - the raw value as it exists in the database as a simple float.',
+						'event_espresso'
+					),
+					$this->get_nicename()
+				),
+				'type'        => 'number',
+			],
+			'pretty' => [
+				'description' => sprintf(
+					esc_html__(
+						'%s - formatted for display in the set currency and decimal places.',
+						'event_espresso'
+					),
+					$this->get_nicename()
+				),
+				'type'        => 'string',
+				'format'      => 'money',
+			],
+		];
+	}
+
+
+	/**
+	 * Returns whether or not this money field allows partial penny amounts
+	 *
+	 * @deprecatd $VID:$
+	 * @return boolean
+	 */
+	public function whole_pennies_only(): ?bool
+	{
+		return $this->allow_fractional_subunits;
+	}
 }

core/db_models/fields/EE_Integer_Field.php

Indentation +59 added lines, -59 removed lines

@@ -9,72 +9,72 @@
  */
 class EE_Integer_Field extends EE_Model_Field_Base
 {
-    /**
-     * @var NumberFormatter
-     * @since $VID:$
-     */
-    protected $number_formatter;
+	/**
+	 * @var NumberFormatter
+	 * @since $VID:$
+	 */
+	protected $number_formatter;
 
-    /**
-     * @param string $table_column
-     * @param string $nicename
-     * @param bool   $nullable
-     * @param null   $default_value
-     */
-    public function __construct($table_column, $nicename, $nullable, $default_value = null)
-    {
-        parent::__construct($table_column, $nicename, $nullable, $default_value);
-        if (! $this->number_formatter instanceof NumberFormatter) {
-            $this->number_formatter = LoaderFactory::getLoader()->getShared(NumberFormatter::class);
-        }
-        $this->setSchemaType('integer');
-    }
+	/**
+	 * @param string $table_column
+	 * @param string $nicename
+	 * @param bool   $nullable
+	 * @param null   $default_value
+	 */
+	public function __construct($table_column, $nicename, $nullable, $default_value = null)
+	{
+		parent::__construct($table_column, $nicename, $nullable, $default_value);
+		if (! $this->number_formatter instanceof NumberFormatter) {
+			$this->number_formatter = LoaderFactory::getLoader()->getShared(NumberFormatter::class);
+		}
+		$this->setSchemaType('integer');
+	}
 
 
-    /**
-     * @param float|int|string $amount
-     * @return int
-     * @since $VID:$
-     */
-    public function prepare_for_get($amount)
-    {
-        return (int) $this->number_formatter->filterNumericValue($amount);
-    }
+	/**
+	 * @param float|int|string $amount
+	 * @return int
+	 * @since $VID:$
+	 */
+	public function prepare_for_get($amount)
+	{
+		return (int) $this->number_formatter->filterNumericValue($amount);
+	}
 
 
-    /**
-     * Returns the number formatted according to local custom (set by the country of the blog).
-     *
-     * @param float        $value
-     * @param null|string  $schema
-     * @return string
-     */
-    public function prepare_for_pretty_echoing($value, $schema = null)
-    {
-        return $this->number_formatter->formatForLocale($value);
-    }
+	/**
+	 * Returns the number formatted according to local custom (set by the country of the blog).
+	 *
+	 * @param float        $value
+	 * @param null|string  $schema
+	 * @return string
+	 */
+	public function prepare_for_pretty_echoing($value, $schema = null)
+	{
+		return $this->number_formatter->formatForLocale($value);
+	}
 
 
-    /**
-     * If provided a string, strips out number-related formatting, like commas, periods, spaces, other junk, etc.
-     * However, treats commas and periods as thousand-separators or decimal marks, as per the currency's config.
-     *
-     * @param float|int|string $value
-     * @return int
-     */
-    public function prepare_for_set($value)
-    {
-        $value = $this->number_formatter->parseForLocale($value);
-        return (int) $this->prepare_for_set_from_db($value);
-    }
+	/**
+	 * If provided a string, strips out number-related formatting, like commas, periods, spaces, other junk, etc.
+	 * However, treats commas and periods as thousand-separators or decimal marks, as per the currency's config.
+	 *
+	 * @param float|int|string $value
+	 * @return int
+	 */
+	public function prepare_for_set($value)
+	{
+		$value = $this->number_formatter->parseForLocale($value);
+		return (int) $this->prepare_for_set_from_db($value);
+	}
 
 
-    /**
-     * @param float $value
-     * @return int
-     */
-    public function prepare_for_set_from_db($value)
-    {
-        return (int) $this->number_formatter->precisionRound($value, 0);
-    }
+	/**
+	 * @param float $value
+	 * @return int
+	 */
+	public function prepare_for_set_from_db($value)
+	{
+		return (int) $this->number_formatter->precisionRound($value, 0);
+	}
 }

core/libraries/form_sections/inputs/EE_Locale_Select_Input.php

Indentation +83 added lines, -83 removed lines

@@ -16,102 +16,102 @@
  */
 class EE_Locale_Select_Input extends EE_Select_Input
 {
-    /**
-     * @var array
-     */
-    private $available_languages;
+	/**
+	 * @var array
+	 */
+	private $available_languages;
 
-    /**
-     * @var string
-     */
-    private $selected;
+	/**
+	 * @var string
+	 */
+	private $selected;
 
-    /**
-     * @var array
-     */
-    private $translations;
+	/**
+	 * @var array
+	 */
+	private $translations;
 
-    /**
-     * @param array $input_settings
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public function __construct($input_settings = [])
-    {
-        require_once ABSPATH . 'wp-admin/includes/translation-install.php';
-        $this->available_languages = get_available_languages();
-        $this->translations        = wp_get_available_translations();
+	/**
+	 * @param array $input_settings
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public function __construct($input_settings = [])
+	{
+		require_once ABSPATH . 'wp-admin/includes/translation-install.php';
+		$this->available_languages = get_available_languages();
+		$this->translations        = wp_get_available_translations();
 
-        $lang = get_site_option('WPLANG');
-        $this->selected = in_array($lang, $this->available_languages, true) ? $lang : 'en_US';
+		$lang = get_site_option('WPLANG');
+		$this->selected = in_array($lang, $this->available_languages, true) ? $lang : 'en_US';
 
-        $input_settings['default'] = $input_settings['default'] ?? $this->selected;
-        $input_settings['html_class'] = isset($input_settings['html_class'])
-            ? $input_settings['html_class'] . ' ee-locale-select-js'
-            : 'ee-locale-select-js';
-        parent::__construct($this->getLocaleOptions(), $input_settings);
-    }
+		$input_settings['default'] = $input_settings['default'] ?? $this->selected;
+		$input_settings['html_class'] = isset($input_settings['html_class'])
+			? $input_settings['html_class'] . ' ee-locale-select-js'
+			: 'ee-locale-select-js';
+		parent::__construct($this->getLocaleOptions(), $input_settings);
+	}
 
 
-    /**
-     * @return array
-     */
-    private function getLocaleOptions(): array
-    {
-        /*
+	/**
+	 * @return array
+	 */
+	private function getLocaleOptions(): array
+	{
+		/*
          * $this->available_languages should only contain the locales.
          * Find the locale in $translations to get the native name. Fall back to locale.
          */
-        $languages = [];
-        foreach ($this->available_languages as $locale) {
-            if (isset($this->translations[ $locale ])) {
-                $languages[] = [
-                    'locale'      => $this->translations[ $locale ]['language'],
-                    'native_name' => $this->translations[ $locale ]['native_name'],
-                    'language'    => current($this->translations[ $locale ]['iso']),
-                ];
-            } else {
-                $languages[] = [
-                    'locale'      => $locale,
-                    'native_name' => $locale,
-                    'language'    => '',
-                ];
-            }
-        }
+		$languages = [];
+		foreach ($this->available_languages as $locale) {
+			if (isset($this->translations[ $locale ])) {
+				$languages[] = [
+					'locale'      => $this->translations[ $locale ]['language'],
+					'native_name' => $this->translations[ $locale ]['native_name'],
+					'language'    => current($this->translations[ $locale ]['iso']),
+				];
+			} else {
+				$languages[] = [
+					'locale'      => $locale,
+					'native_name' => $locale,
+					'language'    => '',
+				];
+			}
+		}
 
-        // default.
-        $options = [
-            'en' => ['en_US' => 'en_US : English (United States)']
-        ];
+		// default.
+		$options = [
+			'en' => ['en_US' => 'en_US : English (United States)']
+		];
 
-        // List installed languages.
-        foreach ($languages as $language_data) {
-            $language = $language_data['language'];
+		// List installed languages.
+		foreach ($languages as $language_data) {
+			$language = $language_data['language'];
 
-            $locale = $language_data['locale'];
-            $locale = WordPressLocales::hasLocaleForLanguage($locale)
-                ? WordPressLocales::getLocaleForLanguage($locale)
-                : $locale;
-            $locale = esc_attr($locale);
+			$locale = $language_data['locale'];
+			$locale = WordPressLocales::hasLocaleForLanguage($locale)
+				? WordPressLocales::getLocaleForLanguage($locale)
+				: $locale;
+			$locale = esc_attr($locale);
 
-            if (WordPressLocales::hasExtraLocalesForLanguage($locale)) {
-                $extra_locales = WordPressLocales::getExtraLocalesForLanguage($locale);
-                foreach ($extra_locales as $extra_locale => $native_name) {
-                    $options[ $language ][ $extra_locale ] = $extra_locale . ' : ' . esc_html($native_name);
-                }
-            } else {
-                $options[ $language ][ $locale ] = $locale . ' : ' . esc_html($language_data['native_name']);
-            }
-        }
+			if (WordPressLocales::hasExtraLocalesForLanguage($locale)) {
+				$extra_locales = WordPressLocales::getExtraLocalesForLanguage($locale);
+				foreach ($extra_locales as $extra_locale => $native_name) {
+					$options[ $language ][ $extra_locale ] = $extra_locale . ' : ' . esc_html($native_name);
+				}
+			} else {
+				$options[ $language ][ $locale ] = $locale . ' : ' . esc_html($language_data['native_name']);
+			}
+		}
 
-        // now sort it
-        ksort($options, SORT_NATURAL | SORT_FLAG_CASE);
-        foreach ($options as $key => $option) {
-            if (is_array($option)) {
-                ksort($option, SORT_NATURAL | SORT_FLAG_CASE);
-                $options[ $key ] = $option;
-            }
-        }
-        return $options;
-    }
+		// now sort it
+		ksort($options, SORT_NATURAL | SORT_FLAG_CASE);
+		foreach ($options as $key => $option) {
+			if (is_array($option)) {
+				ksort($option, SORT_NATURAL | SORT_FLAG_CASE);
+				$options[ $key ] = $option;
+			}
+		}
+		return $options;
+	}
 }

core/libraries/rest_api/ModelDataTranslator.php

Indentation +657 added lines, -657 removed lines

@@ -39,661 +39,661 @@
  */
 class ModelDataTranslator
 {
-    /**
-     * We used to use -1 for infinity in the rest api, but that's ambiguous for
-     * fields that COULD contain -1; so we use null
-     */
-    const EE_INF_IN_REST = null;
-
-
-    /**
-     * Prepares a possible array of input values from JSON for use by the models
-     *
-     * @param EE_Model_Field_Base $field_obj
-     * @param mixed               $original_value
-     * @param string              $requested_version
-     * @param string              $timezone_string treat values as being in this timezone
-     * @return mixed
-     * @throws RestException
-     * @throws EE_Error
-     */
-    public static function prepareFieldValuesFromJson(
-        $field_obj,
-        $original_value,
-        $requested_version,
-        $timezone_string = 'UTC'
-    ) {
-        if (is_array($original_value) && ! $field_obj instanceof EE_Serialized_Text_Field) {
-            $new_value = [];
-            foreach ($original_value as $array_key => $array_item) {
-                $new_value[ $array_key ] = ModelDataTranslator::prepareFieldValueFromJson(
-                    $field_obj,
-                    $array_item,
-                    $requested_version,
-                    $timezone_string
-                );
-            }
-        } else {
-            $new_value = ModelDataTranslator::prepareFieldValueFromJson(
-                $field_obj,
-                $original_value,
-                $requested_version,
-                $timezone_string
-            );
-        }
-        return $new_value;
-    }
-
-
-    /**
-     * Prepares an array of field values FOR use in JSON/REST API
-     *
-     * @param EE_Model_Field_Base $field_obj
-     * @param mixed               $original_value
-     * @param string              $request_version (eg 4.8.36)
-     * @return array
-     * @throws EE_Error
-     */
-    public static function prepareFieldValuesForJson($field_obj, $original_value, $request_version)
-    {
-        if (is_array($original_value)) {
-            $new_value = [];
-            foreach ($original_value as $key => $value) {
-                $new_value[ $key ] = ModelDataTranslator::prepareFieldValuesForJson(
-                    $field_obj,
-                    $value,
-                    $request_version
-                );
-            }
-        } else {
-            $new_value = ModelDataTranslator::prepareFieldValueForJson(
-                $field_obj,
-                $original_value,
-                $request_version
-            );
-        }
-        return $new_value;
-    }
-
-
-    /**
-     * Prepares incoming data from the json or request parameters for the models'
-     * "$query_params".
-     *
-     * @param EE_Model_Field_Base $field_obj
-     * @param mixed               $original_value
-     * @param string              $requested_version
-     * @param string              $timezone_string treat values as being in this timezone
-     * @return mixed
-     * @throws RestException
-     * @throws DomainException
-     * @throws EE_Error
-     */
-    public static function prepareFieldValueFromJson(
-        $field_obj,
-        $original_value,
-        $requested_version,
-        $timezone_string = 'UTC'
-    ) {
-        // check if they accidentally submitted an error value. If so throw an exception
-        if (
-            is_array($original_value)
-            && isset($original_value['error_code'], $original_value['error_message'])
-        ) {
-            throw new RestException(
-                'rest_submitted_error_value',
-                sprintf(
-                    esc_html__(
-                        'You tried to submit a JSON error object as a value for %1$s. That\'s not allowed.',
-                        'event_espresso'
-                    ),
-                    $field_obj->get_name()
-                ),
-                [
-                    'status' => 400,
-                ]
-            );
-        }
-        $timezone_string = EEH_DTT_Helper::get_valid_timezone_string($timezone_string);
-        $new_value = null;
-        // double-check for serialized PHP. We never accept serialized PHP. No way Jose.
-        ModelDataTranslator::throwExceptionIfContainsSerializedData($original_value);
-        $timezone_string = $timezone_string !== ''
-            ? $timezone_string
-            : get_option('timezone_string', '');
-        // walk through the submitted data and double-check for serialized PHP.
-        // We never accept serialized PHP. No way Jose.
-        ModelDataTranslator::throwExceptionIfContainsSerializedData($original_value);
-        if (
-            $field_obj instanceof EE_Infinite_Integer_Field
-            && in_array($original_value, [null, ''], true)
-        ) {
-            $new_value = EE_INF;
-        } elseif ($field_obj instanceof EE_Datetime_Field) {
-            $new_value = self::getTimestampWithTimezoneOffset($original_value, $field_obj, $timezone_string);
-            $new_value = rest_parse_date($new_value);
-            if ($new_value === false) {
-                throw new RestException(
-                    'invalid_format_for_timestamp',
-                    sprintf(
-                        esc_html__(
-                            'Timestamps received on a request as the value for Date and Time fields must be in %1$s/%2$s format.  The timestamp provided (%3$s) is not that format.',
-                            'event_espresso'
-                        ),
-                        'RFC3339',
-                        'ISO8601',
-                        $original_value
-                    ),
-                    [
-                        'status' => 400,
-                    ]
-                );
-            }
-        } elseif ($field_obj instanceof EE_Boolean_Field) {
-            // Interpreted the strings "false", "true", "on", "off" appropriately.
-            $new_value = filter_var($original_value, FILTER_VALIDATE_BOOLEAN);
-        } else {
-            $new_value = $original_value;
-        }
-        return $new_value;
-    }
-
-
-    /**
-     * This checks if the incoming timestamp has timezone information already on it and if it doesn't then adds timezone
-     * information via details obtained from the host site.
-     *
-     * @param string            $original_timestamp
-     * @param EE_Datetime_Field $datetime_field
-     * @param                   $timezone_string
-     * @return string
-     * @throws DomainException
-     */
-    private static function getTimestampWithTimezoneOffset(
-        $original_timestamp,
-        EE_Datetime_Field $datetime_field,
-        $timezone_string
-    ) {
-        // already have timezone information?
-        if (preg_match('/Z|([+-])(\d{2}:\d{2})/', $original_timestamp)) {
-            // yes, we're ignoring the timezone.
-            return $original_timestamp;
-        }
-        // need to append timezone
-        list($offset_sign, $offset_secs) = self::parseTimezoneOffset(
-            $datetime_field->get_timezone_offset(
-                new DateTimeZone($timezone_string),
-                $original_timestamp
-            )
-        );
-        $offset_string =
-            str_pad(
-                floor($offset_secs / HOUR_IN_SECONDS),
-                2,
-                '0',
-                STR_PAD_LEFT
-            )
-            . ':'
-            . str_pad(
-                ($offset_secs % HOUR_IN_SECONDS) / MINUTE_IN_SECONDS,
-                2,
-                '0',
-                STR_PAD_LEFT
-            );
-        return $original_timestamp . $offset_sign . $offset_string;
-    }
-
-
-    /**
-     * Throws an exception if $data is a serialized PHP string (or somehow an actually PHP object, although I don't
-     * think that can happen). If $data is an array, recurses into its keys and values
-     *
-     * @param mixed $data
-     * @return void
-     * @throws RestException
-     */
-    public static function throwExceptionIfContainsSerializedData($data)
-    {
-        if (is_array($data)) {
-            foreach ($data as $key => $value) {
-                ModelDataTranslator::throwExceptionIfContainsSerializedData($key);
-                ModelDataTranslator::throwExceptionIfContainsSerializedData($value);
-            }
-        } else {
-            if (is_serialized($data) || is_object($data)) {
-                throw new RestException(
-                    'serialized_data_submission_prohibited',
-                    esc_html__(
-                    // @codingStandardsIgnoreStart
-                        'You tried to submit a string of serialized text. Serialized PHP is prohibited over the EE4 REST API.',
-                        // @codingStandardsIgnoreEnd
-                        'event_espresso'
-                    )
-                );
-            }
-        }
-    }
-
-
-    /**
-     * determines what's going on with them timezone strings
-     *
-     * @param int $timezone_offset
-     * @return array
-     */
-    private static function parseTimezoneOffset($timezone_offset)
-    {
-        $first_char = substr((string) $timezone_offset, 0, 1);
-        if ($first_char === '+' || $first_char === '-') {
-            $offset_sign = $first_char;
-            $offset_secs = substr((string) $timezone_offset, 1);
-        } else {
-            $offset_sign = '+';
-            $offset_secs = $timezone_offset;
-        }
-        return [$offset_sign, $offset_secs];
-    }
-
-
-    /**
-     * Prepares a field's value for display in the API
-     *
-     * @param EE_Model_Field_Base $field_obj
-     * @param mixed               $original_value
-     * @param string              $requested_version
-     * @return mixed
-     * @throws EE_Error
-     */
-    public static function prepareFieldValueForJson($field_obj, $original_value, $requested_version)
-    {
-        if ($original_value === EE_INF) {
-            $new_value = ModelDataTranslator::EE_INF_IN_REST;
-        } elseif ($field_obj instanceof EE_Datetime_Field) {
-            if (is_string($original_value)) {
-                // did they submit a string of a unix timestamp?
-                if (is_numeric($original_value)) {
-                    $datetime_obj = new DateTime();
-                    $datetime_obj->setTimestamp((int) $original_value);
-                } else {
-                    // first, check if its a MySQL timestamp in GMT
-                    $datetime_obj = DateTime::createFromFormat('Y-m-d H:i:s', $original_value);
-                }
-                if (! $datetime_obj instanceof DateTime) {
-                    // so it's not a unix timestamp or a MySQL timestamp. Maybe its in the field's date/time format?
-                    $datetime_obj = $field_obj->prepare_for_set($original_value);
-                }
-                $original_value = $datetime_obj;
-            }
-            if ($original_value instanceof DateTime) {
-                $new_value = $original_value->format('Y-m-d H:i:s');
-            } elseif (is_int($original_value) || is_float($original_value)) {
-                $new_value = date('Y-m-d H:i:s', $original_value);
-            } elseif ($original_value === null || $original_value === '') {
-                $new_value = null;
-            } else {
-                // so it's not a datetime object, unix timestamp (as string or int),
-                // MySQL timestamp, or even a string in the field object's format. So no idea what it is
-                throw new EE_Error(
-                    sprintf(
-                        esc_html__(
-                        // @codingStandardsIgnoreStart
-                            'The value "%1$s" for the field "%2$s" on model "%3$s" could not be understood. It should be a PHP DateTime, unix timestamp, MySQL date, or string in the format "%4$s".',
-                            // @codingStandardsIgnoreEnd
-                            'event_espresso'
-                        ),
-                        $original_value,
-                        $field_obj->get_name(),
-                        $field_obj->get_model_name(),
-                        $field_obj->get_time_format() . ' ' . $field_obj->get_time_format()
-                    )
-                );
-            }
-            if ($new_value !== null) {
-                // phpcs:disable PHPCompatibility.Extensions.RemovedExtensions.mysql_DeprecatedRemoved
-                $new_value = mysql_to_rfc3339($new_value);
-                // phpcs:enable
-            }
-        } else {
-            $new_value = $original_value;
-        }
-        // are we about to send an object? just don't. We have no good way to represent it in JSON.
-        // can't just check using is_object() because that missed PHP incomplete objects
-        if (! ModelDataTranslator::isRepresentableInJson($new_value)) {
-            $new_value = [
-                'error_code'    => 'php_object_not_return',
-                'error_message' => esc_html__(
-                    'The value of this field in the database is a PHP object, which can\'t be represented in JSON.',
-                    'event_espresso'
-                ),
-            ];
-        }
-        return apply_filters(
-            'FHEE__EventEspresso\core\libraries\rest_api\Model_Data_Translator__prepare_field_for_rest_api',
-            $new_value,
-            $field_obj,
-            $original_value,
-            $requested_version
-        );
-    }
-
-
-    /**
-     * Prepares condition-query-parameters (like what's in where and having) from
-     * the format expected in the API to use in the models
-     *
-     * @param array    $inputted_query_params_of_this_type
-     * @param EEM_Base $model
-     * @param string   $requested_version
-     * @param boolean  $writing whether this data will be written to the DB, or if we're just building a query.
-     *                          If we're writing to the DB, we don't expect any operators, or any logic query
-     *                          parameters, and we also won't accept serialized data unless the current user has
-     *                          unfiltered_html.
-     * @return array
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws RestException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     */
-    public static function prepareConditionsQueryParamsForModels(
-        $inputted_query_params_of_this_type,
-        EEM_Base $model,
-        $requested_version,
-        $writing = false
-    ) {
-        $query_param_for_models = [];
-        $context                = new RestIncomingQueryParamContext($model, $requested_version, $writing);
-        foreach ($inputted_query_params_of_this_type as $query_param_key => $query_param_value) {
-            $query_param_meta = new RestIncomingQueryParamMetadata($query_param_key, $query_param_value, $context);
-            if ($query_param_meta->getField() instanceof EE_Model_Field_Base) {
-                $translated_value = $query_param_meta->determineConditionsQueryParameterValue();
-                if (
-                    $translated_value === null
-                    || (
-                        isset($query_param_for_models[ $query_param_meta->getQueryParamKey() ])
-                        && $query_param_meta->isGmtField()
-                    )
-                ) {
-                    // they have already provided a non-gmt field, ignore the gmt one. That's what WP core
-                    // currently does (they might change it though). See https://core.trac.wordpress.org/ticket/39954
-                    // OR we couldn't create a translated value from their input
-                    continue;
-                }
-                $query_param_for_models[ $query_param_meta->getQueryParamKey() ] = $translated_value;
-            } else {
-                $nested_query_params = $query_param_meta->determineNestedConditionQueryParameters();
-                if ($nested_query_params) {
-                    $query_param_for_models[ $query_param_meta->getQueryParamKey() ] = $nested_query_params;
-                }
-            }
-        }
-        return $query_param_for_models;
-    }
-
-
-    /**
-     * Mostly checks if the last 4 characters are "_gmt", indicating its a
-     * gmt date field name
-     *
-     * @param string $field_name
-     * @return boolean
-     */
-    public static function isGmtDateFieldName($field_name)
-    {
-        return substr(
-            ModelDataTranslator::removeStarsAndAnythingAfterFromConditionQueryParamKey($field_name),
-            -4,
-            4
-        ) === '_gmt';
-    }
-
-
-    /**
-     * Removes the last "_gmt" part of a field name (and if there is no "_gmt" at the end, leave it alone)
-     *
-     * @param string $field_name
-     * @return string
-     */
-    public static function removeGmtFromFieldName($field_name)
-    {
-        if (! ModelDataTranslator::isGmtDateFieldName($field_name)) {
-            return $field_name;
-        }
-        $query_param_sans_stars              =
-            ModelDataTranslator::removeStarsAndAnythingAfterFromConditionQueryParamKey(
-                $field_name
-            );
-        $query_param_sans_gmt_and_sans_stars = substr(
-            $query_param_sans_stars,
-            0,
-            strrpos(
-                $field_name,
-                '_gmt'
-            )
-        );
-        return str_replace($query_param_sans_stars, $query_param_sans_gmt_and_sans_stars, $field_name);
-    }
-
-
-    /**
-     * Takes a field name from the REST API and prepares it for the model querying
-     *
-     * @param string $field_name
-     * @return string
-     */
-    public static function prepareFieldNameFromJson($field_name)
-    {
-        if (ModelDataTranslator::isGmtDateFieldName($field_name)) {
-            return ModelDataTranslator::removeGmtFromFieldName($field_name);
-        }
-        return $field_name;
-    }
-
-
-    /**
-     * Takes array of field names from REST API and prepares for models
-     *
-     * @param array $field_names
-     * @return array of field names (possibly include model prefixes)
-     */
-    public static function prepareFieldNamesFromJson(array $field_names)
-    {
-        $new_array = [];
-        foreach ($field_names as $key => $field_name) {
-            $new_array[ $key ] = ModelDataTranslator::prepareFieldNameFromJson($field_name);
-        }
-        return $new_array;
-    }
-
-
-    /**
-     * Takes array where array keys are field names (possibly with model path prefixes)
-     * from the REST API and prepares them for model querying
-     *
-     * @param array $field_names_as_keys
-     * @return array
-     */
-    public static function prepareFieldNamesInArrayKeysFromJson(array $field_names_as_keys)
-    {
-        $new_array = [];
-        foreach ($field_names_as_keys as $field_name => $value) {
-            $new_array[ ModelDataTranslator::prepareFieldNameFromJson($field_name) ] = $value;
-        }
-        return $new_array;
-    }
-
-
-    /**
-     * Prepares an array of model query params for use in the REST API
-     *
-     * @param array    $model_query_params
-     * @param EEM_Base $model
-     * @param string   $requested_version  eg "4.8.36". If null is provided, defaults to the latest release of the EE4
-     *                                     REST API
-     * @return array which can be passed into the EE4 REST API when querying a model resource
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function prepareQueryParamsForRestApi(
-        array $model_query_params,
-        EEM_Base $model,
-        $requested_version = null
-    ) {
-        if ($requested_version === null) {
-            $requested_version = EED_Core_Rest_Api::latest_rest_api_version();
-        }
-        $rest_query_params = $model_query_params;
-        if (isset($model_query_params[0])) {
-            $rest_query_params['where'] = ModelDataTranslator::prepareConditionsQueryParamsForRestApi(
-                $model_query_params[0],
-                $model,
-                $requested_version
-            );
-            unset($rest_query_params[0]);
-        }
-        if (isset($model_query_params['having'])) {
-            $rest_query_params['having'] = ModelDataTranslator::prepareConditionsQueryParamsForRestApi(
-                $model_query_params['having'],
-                $model,
-                $requested_version
-            );
-        }
-        return apply_filters(
-            'FHEE__EventEspresso\core\libraries\rest_api\Model_Data_Translator__prepare_query_params_for_rest_api',
-            $rest_query_params,
-            $model_query_params,
-            $model,
-            $requested_version
-        );
-    }
-
-
-    /**
-     * Prepares all the sub-conditions query parameters (eg having or where conditions) for use in the rest api
-     *
-     * @param array    $inputted_query_params_of_this_type  eg like the "where" or "having" conditions query params
-     * @param EEM_Base $model
-     * @param string   $requested_version                   eg "4.8.36"
-     * @return array ready for use in the rest api query params
-     * @throws EE_Error
-     * @throws ObjectDetectedException if somehow a PHP object were in the query params' values,
-     * @throws ReflectionException
-     *                                                      (which would be really unusual)
-     * @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions
-     */
-    public static function prepareConditionsQueryParamsForRestApi(
-        $inputted_query_params_of_this_type,
-        EEM_Base $model,
-        $requested_version
-    ) {
-        $query_param_for_models = [];
-        foreach ($inputted_query_params_of_this_type as $query_param_key => $query_param_value) {
-            $field = ModelDataTranslator::deduceFieldFromQueryParam(
-                ModelDataTranslator::removeStarsAndAnythingAfterFromConditionQueryParamKey($query_param_key),
-                $model
-            );
-            if ($field instanceof EE_Model_Field_Base) {
-                // did they specify an operator?
-                if (is_array($query_param_value)) {
-                    $op               = $query_param_value[0];
-                    $translated_value = [$op];
-                    if (isset($query_param_value[1])) {
-                        $value               = $query_param_value[1];
-                        $translated_value[1] = ModelDataTranslator::prepareFieldValuesForJson(
-                            $field,
-                            $value,
-                            $requested_version
-                        );
-                    }
-                } else {
-                    $translated_value = ModelDataTranslator::prepareFieldValueForJson(
-                        $field,
-                        $query_param_value,
-                        $requested_version
-                    );
-                }
-                $query_param_for_models[ $query_param_key ] = $translated_value;
-            } else {
-                // so it's not for a field, assume it's a logic query param key
-                $query_param_for_models[ $query_param_key ] =
-                    ModelDataTranslator::prepareConditionsQueryParamsForRestApi(
-                        $query_param_value,
-                        $model,
-                        $requested_version
-                    );
-            }
-        }
-        return $query_param_for_models;
-    }
-
-
-    /**
-     * @param $condition_query_param_key
-     * @return string
-     */
-    public static function removeStarsAndAnythingAfterFromConditionQueryParamKey($condition_query_param_key)
-    {
-        $pos_of_star = strpos($condition_query_param_key, '*');
-        if ($pos_of_star === false) {
-            return $condition_query_param_key;
-        }
-        return substr($condition_query_param_key, 0, $pos_of_star);
-    }
-
-
-    /**
-     * Takes the input parameter and finds the model field that it indicates.
-     *
-     * @param string   $query_param_name like Registration.Transaction.TXN_ID, Event.Datetime.start_time, or REG_ID
-     * @param EEM_Base $model
-     * @return EE_Model_Field_Base
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function deduceFieldFromQueryParam($query_param_name, EEM_Base $model)
-    {
-        // ok, now proceed with deducing which part is the model's name, and which is the field's name
-        // which will help us find the database table and column
-        $query_param_parts = explode('.', $query_param_name);
-        if (empty($query_param_parts)) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        '_extract_column_name is empty when trying to extract column and table name from %s',
-                        'event_espresso'
-                    ),
-                    $query_param_name
-                )
-            );
-        }
-        $number_of_parts       = count($query_param_parts);
-        $last_query_param_part = $query_param_parts[ count($query_param_parts) - 1 ];
-        $field_name            = $last_query_param_part;
-        if ($number_of_parts !== 1) {
-            // the last part is the column name, and there are only 2parts. therefore...
-            $model = EE_Registry::instance()->load_model($query_param_parts[ $number_of_parts - 2 ]);
-        }
-        try {
-            return $model->field_settings_for($field_name, false);
-        } catch (EE_Error $e) {
-            return null;
-        }
-    }
-
-
-    /**
-     * Returns true if $data can be easily represented in JSON.
-     * Basically, objects and resources can't be represented in JSON easily.
-     *
-     * @param mixed $data
-     * @return bool
-     */
-    protected static function isRepresentableInJson($data)
-    {
-        return is_scalar($data)
-               || is_array($data)
-               || is_null($data);
-    }
+	/**
+	 * We used to use -1 for infinity in the rest api, but that's ambiguous for
+	 * fields that COULD contain -1; so we use null
+	 */
+	const EE_INF_IN_REST = null;
+
+
+	/**
+	 * Prepares a possible array of input values from JSON for use by the models
+	 *
+	 * @param EE_Model_Field_Base $field_obj
+	 * @param mixed               $original_value
+	 * @param string              $requested_version
+	 * @param string              $timezone_string treat values as being in this timezone
+	 * @return mixed
+	 * @throws RestException
+	 * @throws EE_Error
+	 */
+	public static function prepareFieldValuesFromJson(
+		$field_obj,
+		$original_value,
+		$requested_version,
+		$timezone_string = 'UTC'
+	) {
+		if (is_array($original_value) && ! $field_obj instanceof EE_Serialized_Text_Field) {
+			$new_value = [];
+			foreach ($original_value as $array_key => $array_item) {
+				$new_value[ $array_key ] = ModelDataTranslator::prepareFieldValueFromJson(
+					$field_obj,
+					$array_item,
+					$requested_version,
+					$timezone_string
+				);
+			}
+		} else {
+			$new_value = ModelDataTranslator::prepareFieldValueFromJson(
+				$field_obj,
+				$original_value,
+				$requested_version,
+				$timezone_string
+			);
+		}
+		return $new_value;
+	}
+
+
+	/**
+	 * Prepares an array of field values FOR use in JSON/REST API
+	 *
+	 * @param EE_Model_Field_Base $field_obj
+	 * @param mixed               $original_value
+	 * @param string              $request_version (eg 4.8.36)
+	 * @return array
+	 * @throws EE_Error
+	 */
+	public static function prepareFieldValuesForJson($field_obj, $original_value, $request_version)
+	{
+		if (is_array($original_value)) {
+			$new_value = [];
+			foreach ($original_value as $key => $value) {
+				$new_value[ $key ] = ModelDataTranslator::prepareFieldValuesForJson(
+					$field_obj,
+					$value,
+					$request_version
+				);
+			}
+		} else {
+			$new_value = ModelDataTranslator::prepareFieldValueForJson(
+				$field_obj,
+				$original_value,
+				$request_version
+			);
+		}
+		return $new_value;
+	}
+
+
+	/**
+	 * Prepares incoming data from the json or request parameters for the models'
+	 * "$query_params".
+	 *
+	 * @param EE_Model_Field_Base $field_obj
+	 * @param mixed               $original_value
+	 * @param string              $requested_version
+	 * @param string              $timezone_string treat values as being in this timezone
+	 * @return mixed
+	 * @throws RestException
+	 * @throws DomainException
+	 * @throws EE_Error
+	 */
+	public static function prepareFieldValueFromJson(
+		$field_obj,
+		$original_value,
+		$requested_version,
+		$timezone_string = 'UTC'
+	) {
+		// check if they accidentally submitted an error value. If so throw an exception
+		if (
+			is_array($original_value)
+			&& isset($original_value['error_code'], $original_value['error_message'])
+		) {
+			throw new RestException(
+				'rest_submitted_error_value',
+				sprintf(
+					esc_html__(
+						'You tried to submit a JSON error object as a value for %1$s. That\'s not allowed.',
+						'event_espresso'
+					),
+					$field_obj->get_name()
+				),
+				[
+					'status' => 400,
+				]
+			);
+		}
+		$timezone_string = EEH_DTT_Helper::get_valid_timezone_string($timezone_string);
+		$new_value = null;
+		// double-check for serialized PHP. We never accept serialized PHP. No way Jose.
+		ModelDataTranslator::throwExceptionIfContainsSerializedData($original_value);
+		$timezone_string = $timezone_string !== ''
+			? $timezone_string
+			: get_option('timezone_string', '');
+		// walk through the submitted data and double-check for serialized PHP.
+		// We never accept serialized PHP. No way Jose.
+		ModelDataTranslator::throwExceptionIfContainsSerializedData($original_value);
+		if (
+			$field_obj instanceof EE_Infinite_Integer_Field
+			&& in_array($original_value, [null, ''], true)
+		) {
+			$new_value = EE_INF;
+		} elseif ($field_obj instanceof EE_Datetime_Field) {
+			$new_value = self::getTimestampWithTimezoneOffset($original_value, $field_obj, $timezone_string);
+			$new_value = rest_parse_date($new_value);
+			if ($new_value === false) {
+				throw new RestException(
+					'invalid_format_for_timestamp',
+					sprintf(
+						esc_html__(
+							'Timestamps received on a request as the value for Date and Time fields must be in %1$s/%2$s format.  The timestamp provided (%3$s) is not that format.',
+							'event_espresso'
+						),
+						'RFC3339',
+						'ISO8601',
+						$original_value
+					),
+					[
+						'status' => 400,
+					]
+				);
+			}
+		} elseif ($field_obj instanceof EE_Boolean_Field) {
+			// Interpreted the strings "false", "true", "on", "off" appropriately.
+			$new_value = filter_var($original_value, FILTER_VALIDATE_BOOLEAN);
+		} else {
+			$new_value = $original_value;
+		}
+		return $new_value;
+	}
+
+
+	/**
+	 * This checks if the incoming timestamp has timezone information already on it and if it doesn't then adds timezone
+	 * information via details obtained from the host site.
+	 *
+	 * @param string            $original_timestamp
+	 * @param EE_Datetime_Field $datetime_field
+	 * @param                   $timezone_string
+	 * @return string
+	 * @throws DomainException
+	 */
+	private static function getTimestampWithTimezoneOffset(
+		$original_timestamp,
+		EE_Datetime_Field $datetime_field,
+		$timezone_string
+	) {
+		// already have timezone information?
+		if (preg_match('/Z|([+-])(\d{2}:\d{2})/', $original_timestamp)) {
+			// yes, we're ignoring the timezone.
+			return $original_timestamp;
+		}
+		// need to append timezone
+		list($offset_sign, $offset_secs) = self::parseTimezoneOffset(
+			$datetime_field->get_timezone_offset(
+				new DateTimeZone($timezone_string),
+				$original_timestamp
+			)
+		);
+		$offset_string =
+			str_pad(
+				floor($offset_secs / HOUR_IN_SECONDS),
+				2,
+				'0',
+				STR_PAD_LEFT
+			)
+			. ':'
+			. str_pad(
+				($offset_secs % HOUR_IN_SECONDS) / MINUTE_IN_SECONDS,
+				2,
+				'0',
+				STR_PAD_LEFT
+			);
+		return $original_timestamp . $offset_sign . $offset_string;
+	}
+
+
+	/**
+	 * Throws an exception if $data is a serialized PHP string (or somehow an actually PHP object, although I don't
+	 * think that can happen). If $data is an array, recurses into its keys and values
+	 *
+	 * @param mixed $data
+	 * @return void
+	 * @throws RestException
+	 */
+	public static function throwExceptionIfContainsSerializedData($data)
+	{
+		if (is_array($data)) {
+			foreach ($data as $key => $value) {
+				ModelDataTranslator::throwExceptionIfContainsSerializedData($key);
+				ModelDataTranslator::throwExceptionIfContainsSerializedData($value);
+			}
+		} else {
+			if (is_serialized($data) || is_object($data)) {
+				throw new RestException(
+					'serialized_data_submission_prohibited',
+					esc_html__(
+					// @codingStandardsIgnoreStart
+						'You tried to submit a string of serialized text. Serialized PHP is prohibited over the EE4 REST API.',
+						// @codingStandardsIgnoreEnd
+						'event_espresso'
+					)
+				);
+			}
+		}
+	}
+
+
+	/**
+	 * determines what's going on with them timezone strings
+	 *
+	 * @param int $timezone_offset
+	 * @return array
+	 */
+	private static function parseTimezoneOffset($timezone_offset)
+	{
+		$first_char = substr((string) $timezone_offset, 0, 1);
+		if ($first_char === '+' || $first_char === '-') {
+			$offset_sign = $first_char;
+			$offset_secs = substr((string) $timezone_offset, 1);
+		} else {
+			$offset_sign = '+';
+			$offset_secs = $timezone_offset;
+		}
+		return [$offset_sign, $offset_secs];
+	}
+
+
+	/**
+	 * Prepares a field's value for display in the API
+	 *
+	 * @param EE_Model_Field_Base $field_obj
+	 * @param mixed               $original_value
+	 * @param string              $requested_version
+	 * @return mixed
+	 * @throws EE_Error
+	 */
+	public static function prepareFieldValueForJson($field_obj, $original_value, $requested_version)
+	{
+		if ($original_value === EE_INF) {
+			$new_value = ModelDataTranslator::EE_INF_IN_REST;
+		} elseif ($field_obj instanceof EE_Datetime_Field) {
+			if (is_string($original_value)) {
+				// did they submit a string of a unix timestamp?
+				if (is_numeric($original_value)) {
+					$datetime_obj = new DateTime();
+					$datetime_obj->setTimestamp((int) $original_value);
+				} else {
+					// first, check if its a MySQL timestamp in GMT
+					$datetime_obj = DateTime::createFromFormat('Y-m-d H:i:s', $original_value);
+				}
+				if (! $datetime_obj instanceof DateTime) {
+					// so it's not a unix timestamp or a MySQL timestamp. Maybe its in the field's date/time format?
+					$datetime_obj = $field_obj->prepare_for_set($original_value);
+				}
+				$original_value = $datetime_obj;
+			}
+			if ($original_value instanceof DateTime) {
+				$new_value = $original_value->format('Y-m-d H:i:s');
+			} elseif (is_int($original_value) || is_float($original_value)) {
+				$new_value = date('Y-m-d H:i:s', $original_value);
+			} elseif ($original_value === null || $original_value === '') {
+				$new_value = null;
+			} else {
+				// so it's not a datetime object, unix timestamp (as string or int),
+				// MySQL timestamp, or even a string in the field object's format. So no idea what it is
+				throw new EE_Error(
+					sprintf(
+						esc_html__(
+						// @codingStandardsIgnoreStart
+							'The value "%1$s" for the field "%2$s" on model "%3$s" could not be understood. It should be a PHP DateTime, unix timestamp, MySQL date, or string in the format "%4$s".',
+							// @codingStandardsIgnoreEnd
+							'event_espresso'
+						),
+						$original_value,
+						$field_obj->get_name(),
+						$field_obj->get_model_name(),
+						$field_obj->get_time_format() . ' ' . $field_obj->get_time_format()
+					)
+				);
+			}
+			if ($new_value !== null) {
+				// phpcs:disable PHPCompatibility.Extensions.RemovedExtensions.mysql_DeprecatedRemoved
+				$new_value = mysql_to_rfc3339($new_value);
+				// phpcs:enable
+			}
+		} else {
+			$new_value = $original_value;
+		}
+		// are we about to send an object? just don't. We have no good way to represent it in JSON.
+		// can't just check using is_object() because that missed PHP incomplete objects
+		if (! ModelDataTranslator::isRepresentableInJson($new_value)) {
+			$new_value = [
+				'error_code'    => 'php_object_not_return',
+				'error_message' => esc_html__(
+					'The value of this field in the database is a PHP object, which can\'t be represented in JSON.',
+					'event_espresso'
+				),
+			];
+		}
+		return apply_filters(
+			'FHEE__EventEspresso\core\libraries\rest_api\Model_Data_Translator__prepare_field_for_rest_api',
+			$new_value,
+			$field_obj,
+			$original_value,
+			$requested_version
+		);
+	}
+
+
+	/**
+	 * Prepares condition-query-parameters (like what's in where and having) from
+	 * the format expected in the API to use in the models
+	 *
+	 * @param array    $inputted_query_params_of_this_type
+	 * @param EEM_Base $model
+	 * @param string   $requested_version
+	 * @param boolean  $writing whether this data will be written to the DB, or if we're just building a query.
+	 *                          If we're writing to the DB, we don't expect any operators, or any logic query
+	 *                          parameters, and we also won't accept serialized data unless the current user has
+	 *                          unfiltered_html.
+	 * @return array
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws RestException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 */
+	public static function prepareConditionsQueryParamsForModels(
+		$inputted_query_params_of_this_type,
+		EEM_Base $model,
+		$requested_version,
+		$writing = false
+	) {
+		$query_param_for_models = [];
+		$context                = new RestIncomingQueryParamContext($model, $requested_version, $writing);
+		foreach ($inputted_query_params_of_this_type as $query_param_key => $query_param_value) {
+			$query_param_meta = new RestIncomingQueryParamMetadata($query_param_key, $query_param_value, $context);
+			if ($query_param_meta->getField() instanceof EE_Model_Field_Base) {
+				$translated_value = $query_param_meta->determineConditionsQueryParameterValue();
+				if (
+					$translated_value === null
+					|| (
+						isset($query_param_for_models[ $query_param_meta->getQueryParamKey() ])
+						&& $query_param_meta->isGmtField()
+					)
+				) {
+					// they have already provided a non-gmt field, ignore the gmt one. That's what WP core
+					// currently does (they might change it though). See https://core.trac.wordpress.org/ticket/39954
+					// OR we couldn't create a translated value from their input
+					continue;
+				}
+				$query_param_for_models[ $query_param_meta->getQueryParamKey() ] = $translated_value;
+			} else {
+				$nested_query_params = $query_param_meta->determineNestedConditionQueryParameters();
+				if ($nested_query_params) {
+					$query_param_for_models[ $query_param_meta->getQueryParamKey() ] = $nested_query_params;
+				}
+			}
+		}
+		return $query_param_for_models;
+	}
+
+
+	/**
+	 * Mostly checks if the last 4 characters are "_gmt", indicating its a
+	 * gmt date field name
+	 *
+	 * @param string $field_name
+	 * @return boolean
+	 */
+	public static function isGmtDateFieldName($field_name)
+	{
+		return substr(
+			ModelDataTranslator::removeStarsAndAnythingAfterFromConditionQueryParamKey($field_name),
+			-4,
+			4
+		) === '_gmt';
+	}
+
+
+	/**
+	 * Removes the last "_gmt" part of a field name (and if there is no "_gmt" at the end, leave it alone)
+	 *
+	 * @param string $field_name
+	 * @return string
+	 */
+	public static function removeGmtFromFieldName($field_name)
+	{
+		if (! ModelDataTranslator::isGmtDateFieldName($field_name)) {
+			return $field_name;
+		}
+		$query_param_sans_stars              =
+			ModelDataTranslator::removeStarsAndAnythingAfterFromConditionQueryParamKey(
+				$field_name
+			);
+		$query_param_sans_gmt_and_sans_stars = substr(
+			$query_param_sans_stars,
+			0,
+			strrpos(
+				$field_name,
+				'_gmt'
+			)
+		);
+		return str_replace($query_param_sans_stars, $query_param_sans_gmt_and_sans_stars, $field_name);
+	}
+
+
+	/**
+	 * Takes a field name from the REST API and prepares it for the model querying
+	 *
+	 * @param string $field_name
+	 * @return string
+	 */
+	public static function prepareFieldNameFromJson($field_name)
+	{
+		if (ModelDataTranslator::isGmtDateFieldName($field_name)) {
+			return ModelDataTranslator::removeGmtFromFieldName($field_name);
+		}
+		return $field_name;
+	}
+
+
+	/**
+	 * Takes array of field names from REST API and prepares for models
+	 *
+	 * @param array $field_names
+	 * @return array of field names (possibly include model prefixes)
+	 */
+	public static function prepareFieldNamesFromJson(array $field_names)
+	{
+		$new_array = [];
+		foreach ($field_names as $key => $field_name) {
+			$new_array[ $key ] = ModelDataTranslator::prepareFieldNameFromJson($field_name);
+		}
+		return $new_array;
+	}
+
+
+	/**
+	 * Takes array where array keys are field names (possibly with model path prefixes)
+	 * from the REST API and prepares them for model querying
+	 *
+	 * @param array $field_names_as_keys
+	 * @return array
+	 */
+	public static function prepareFieldNamesInArrayKeysFromJson(array $field_names_as_keys)
+	{
+		$new_array = [];
+		foreach ($field_names_as_keys as $field_name => $value) {
+			$new_array[ ModelDataTranslator::prepareFieldNameFromJson($field_name) ] = $value;
+		}
+		return $new_array;
+	}
+
+
+	/**
+	 * Prepares an array of model query params for use in the REST API
+	 *
+	 * @param array    $model_query_params
+	 * @param EEM_Base $model
+	 * @param string   $requested_version  eg "4.8.36". If null is provided, defaults to the latest release of the EE4
+	 *                                     REST API
+	 * @return array which can be passed into the EE4 REST API when querying a model resource
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function prepareQueryParamsForRestApi(
+		array $model_query_params,
+		EEM_Base $model,
+		$requested_version = null
+	) {
+		if ($requested_version === null) {
+			$requested_version = EED_Core_Rest_Api::latest_rest_api_version();
+		}
+		$rest_query_params = $model_query_params;
+		if (isset($model_query_params[0])) {
+			$rest_query_params['where'] = ModelDataTranslator::prepareConditionsQueryParamsForRestApi(
+				$model_query_params[0],
+				$model,
+				$requested_version
+			);
+			unset($rest_query_params[0]);
+		}
+		if (isset($model_query_params['having'])) {
+			$rest_query_params['having'] = ModelDataTranslator::prepareConditionsQueryParamsForRestApi(
+				$model_query_params['having'],
+				$model,
+				$requested_version
+			);
+		}
+		return apply_filters(
+			'FHEE__EventEspresso\core\libraries\rest_api\Model_Data_Translator__prepare_query_params_for_rest_api',
+			$rest_query_params,
+			$model_query_params,
+			$model,
+			$requested_version
+		);
+	}
+
+
+	/**
+	 * Prepares all the sub-conditions query parameters (eg having or where conditions) for use in the rest api
+	 *
+	 * @param array    $inputted_query_params_of_this_type  eg like the "where" or "having" conditions query params
+	 * @param EEM_Base $model
+	 * @param string   $requested_version                   eg "4.8.36"
+	 * @return array ready for use in the rest api query params
+	 * @throws EE_Error
+	 * @throws ObjectDetectedException if somehow a PHP object were in the query params' values,
+	 * @throws ReflectionException
+	 *                                                      (which would be really unusual)
+	 * @see https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions
+	 */
+	public static function prepareConditionsQueryParamsForRestApi(
+		$inputted_query_params_of_this_type,
+		EEM_Base $model,
+		$requested_version
+	) {
+		$query_param_for_models = [];
+		foreach ($inputted_query_params_of_this_type as $query_param_key => $query_param_value) {
+			$field = ModelDataTranslator::deduceFieldFromQueryParam(
+				ModelDataTranslator::removeStarsAndAnythingAfterFromConditionQueryParamKey($query_param_key),
+				$model
+			);
+			if ($field instanceof EE_Model_Field_Base) {
+				// did they specify an operator?
+				if (is_array($query_param_value)) {
+					$op               = $query_param_value[0];
+					$translated_value = [$op];
+					if (isset($query_param_value[1])) {
+						$value               = $query_param_value[1];
+						$translated_value[1] = ModelDataTranslator::prepareFieldValuesForJson(
+							$field,
+							$value,
+							$requested_version
+						);
+					}
+				} else {
+					$translated_value = ModelDataTranslator::prepareFieldValueForJson(
+						$field,
+						$query_param_value,
+						$requested_version
+					);
+				}
+				$query_param_for_models[ $query_param_key ] = $translated_value;
+			} else {
+				// so it's not for a field, assume it's a logic query param key
+				$query_param_for_models[ $query_param_key ] =
+					ModelDataTranslator::prepareConditionsQueryParamsForRestApi(
+						$query_param_value,
+						$model,
+						$requested_version
+					);
+			}
+		}
+		return $query_param_for_models;
+	}
+
+
+	/**
+	 * @param $condition_query_param_key
+	 * @return string
+	 */
+	public static function removeStarsAndAnythingAfterFromConditionQueryParamKey($condition_query_param_key)
+	{
+		$pos_of_star = strpos($condition_query_param_key, '*');
+		if ($pos_of_star === false) {
+			return $condition_query_param_key;
+		}
+		return substr($condition_query_param_key, 0, $pos_of_star);
+	}
+
+
+	/**
+	 * Takes the input parameter and finds the model field that it indicates.
+	 *
+	 * @param string   $query_param_name like Registration.Transaction.TXN_ID, Event.Datetime.start_time, or REG_ID
+	 * @param EEM_Base $model
+	 * @return EE_Model_Field_Base
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function deduceFieldFromQueryParam($query_param_name, EEM_Base $model)
+	{
+		// ok, now proceed with deducing which part is the model's name, and which is the field's name
+		// which will help us find the database table and column
+		$query_param_parts = explode('.', $query_param_name);
+		if (empty($query_param_parts)) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'_extract_column_name is empty when trying to extract column and table name from %s',
+						'event_espresso'
+					),
+					$query_param_name
+				)
+			);
+		}
+		$number_of_parts       = count($query_param_parts);
+		$last_query_param_part = $query_param_parts[ count($query_param_parts) - 1 ];
+		$field_name            = $last_query_param_part;
+		if ($number_of_parts !== 1) {
+			// the last part is the column name, and there are only 2parts. therefore...
+			$model = EE_Registry::instance()->load_model($query_param_parts[ $number_of_parts - 2 ]);
+		}
+		try {
+			return $model->field_settings_for($field_name, false);
+		} catch (EE_Error $e) {
+			return null;
+		}
+	}
+
+
+	/**
+	 * Returns true if $data can be easily represented in JSON.
+	 * Basically, objects and resources can't be represented in JSON easily.
+	 *
+	 * @param mixed $data
+	 * @return bool
+	 */
+	protected static function isRepresentableInJson($data)
+	{
+		return is_scalar($data)
+			   || is_array($data)
+			   || is_null($data);
+	}
 }

core/libraries/rest_api/RestIncomingQueryParamMetadata.php

Indentation +787 added lines, -787 removed lines

@@ -29,793 +29,793 @@
  */
 class RestIncomingQueryParamMetadata
 {
-    private $query_param_key;
-
-    private $query_param_value;
-
-    /**
-     * @var RestIncomingQueryParamContext
-     */
-    private $context;
-
-    /**
-     * @var EE_Model_Field_Base|null
-     */
-    private $field;
-
-    /**
-     * @var string same as $query_param_key but has the * and anything after it removed
-     */
-    private $query_param_key_sans_stars;
-
-    /**
-     * @var string for timezone or timezone offset
-     */
-    private $timezone;
-
-    /**
-     * @var boolean if the field in $query_param_key is for a GMT field (eg `EVT_modified_gmt`)
-     */
-    private $is_gmt_field = false;
-
-
-    /**
-     * RestIncomingQueryParamMetadata constructor.
-     * You probably want to call
-     *
-     * @param string                        $query_param_key
-     * @param string                        $query_param_value
-     * @param RestIncomingQueryParamContext $context
-     * @throws EE_Error
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function __construct($query_param_key, $query_param_value, RestIncomingQueryParamContext $context)
-    {
-        $this->query_param_key   = $query_param_key;
-        $this->query_param_value = $query_param_value;
-        $this->context           = $context;
-        $this->determineFieldAndTimezone();
-    }
-
-
-    /**
-     * Gets the query parameter key. This may have been modified (see setQueryParamValue())
-     *
-     * @return string
-     */
-    public function getQueryParamKey()
-    {
-        return $this->query_param_key;
-    }
-
-
-    /**
-     * Modifies the query parameter key passed in (Eg this is done when rewriting the simplified specified operator REST
-     * query parameters into the legacy structure)
-     *
-     * @param string|array|int|float $query_param_value
-     */
-    private function setQueryParamValue($query_param_value)
-    {
-        $this->query_param_value = $query_param_value;
-    }
-
-
-    /**
-     * Gets the original query parameter value passed in.
-     *
-     * @return array|string
-     */
-    public function getQueryParamValue()
-    {
-        return $this->query_param_value;
-    }
-
-
-    /**
-     * Gets the context object.
-     *
-     * @return RestIncomingQueryParamContext
-     */
-    public function getContext()
-    {
-        return $this->context;
-    }
-
-
-    /**
-     * Sets the query parameter key. This may be used to rewrite a key into its non-GMT alternative.
-     *
-     * @param string $query_param_key
-     */
-    private function setQueryParamKey($query_param_key)
-    {
-        $this->query_param_key = $query_param_key;
-    }
-
-
-    /**
-     * Gets the field the query parameter key indicated. This may be null (in cases where the query parameter key
-     * did not indicate a field, eg if it were `OR`).
-     *
-     * @return EE_Model_Field_Base|null
-     */
-    public function getField()
-    {
-        return $this->field;
-    }
-
-
-    /**
-     * Gets the query parameter key (with the star and everything afterwards removed).
-     *
-     * @return string
-     */
-    public function getQueryParamKeySansStars()
-    {
-        return $this->query_param_key_sans_stars;
-    }
-
-
-    /**
-     * Gets the timezone associated with this model (the site timezone, except for GMT datetime fields).
-     *
-     * @return string
-     */
-    public function getTimezone()
-    {
-        return $this->timezone;
-    }
-
-
-    /**
-     * Returns whether or not this is a GMT field
-     *
-     * @return boolean
-     */
-    public function isGmtField()
-    {
-        return $this->is_gmt_field;
-    }
-
-
-    /**
-     * Sets the field indicated by the query parameter key (might be null).
-     *
-     * @param EE_Model_Field_Base|null $field
-     */
-    private function setField(EE_Model_Field_Base $field = null)
-    {
-        $this->field = $field;
-    }
-
-
-    /**
-     * Sets the query parameter key-with-stars-removed.
-     *
-     * @param string $query_param_key_sans_stars
-     */
-    private function setQueryParamKeySansStars($query_param_key_sans_stars)
-    {
-        $this->query_param_key_sans_stars = $query_param_key_sans_stars;
-    }
-
-
-    /**
-     * Sets the timezone (this could be a timezone offset string).
-     *
-     * @param string $timezone
-     */
-    private function setTimezone($timezone)
-    {
-        $this->timezone = $timezone;
-    }
-
-
-    /**
-     * @param mixed $is_gmt_field
-     */
-    private function setIsGmtField($is_gmt_field)
-    {
-        $this->is_gmt_field = $is_gmt_field;
-    }
-
-
-    /**
-     * Determines what field, query param name, and query param name without stars, and timezone to use.
-     *
-     * @return void {
-     * @throws EE_Error
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws InvalidArgumentException
-     * @throws ReflectionException
-     * @since 4.9.72.p
-     */
-    private function determineFieldAndTimezone()
-    {
-        $this->setQueryParamKeySansStars(
-            ModelDataTranslator::removeStarsAndAnythingAfterFromConditionQueryParamKey(
-                $this->getQueryParamKey()
-            )
-        );
-        $this->setField(
-            ModelDataTranslator::deduceFieldFromQueryParam(
-                $this->getQueryParamKeySansStars(),
-                $this->getContext()->getModel()
-            )
-        );
-        // double-check is it a *_gmt field?
-        if (
-            ! $this->getField() instanceof EE_Model_Field_Base
-            && ModelDataTranslator::isGmtDateFieldName($this->getQueryParamKeySansStars())
-        ) {
-            // yep, take off '_gmt', and find the field
-            $this->setQueryParamKey(ModelDataTranslator::removeGmtFromFieldName($this->getQueryParamKeySansStars()));
-            $this->setField(
-                ModelDataTranslator::deduceFieldFromQueryParam(
-                    $this->getQueryParamKey(),
-                    $this->context->getModel()
-                )
-            );
-            $this->setTimezone('UTC');
-            $this->setIsGmtField(true);
-        } elseif ($this->getField() instanceof EE_Datetime_Field) {
-            // so it's not a GMT field. Set the timezone on the model to the default
-            $this->setTimezone(EEH_DTT_Helper::get_valid_timezone_string());
-        } else {
-            // just keep using what's already set for the timezone
-            $this->setTimezone($this->context->getModel()->get_timezone());
-        }
-        $this->assertOnlyAdminCanReadPasswordFields();
-    }
-
-
-    /**
-     * Throws an exception if a non-admin is trying to query by password.
-     *
-     * @throws RestException
-     * @since 4.9.74.p
-     */
-    private function assertOnlyAdminCanReadPasswordFields()
-    {
-        if (
-            $this->getField() instanceof EE_Password_Field
-            && ! current_user_can(EE_Restriction_Generator_Base::get_default_restrictions_cap())
-        ) {
-            // only full admins can query by password. sorry bub!
-            throw new RestException(
-                'only_admins_can_query_by_password',
-                // @codingStandardsIgnoreStart
-                esc_html__(
-                    'You attempted to filter by a password field without the needed privileges. Only a full admin is allowed to do that.',
-                    'event_espresso'
-                ),
-                // @codingStandardsIgnoreEnd
-                [
-                    'status' => 403,
-                ]
-            );
-        }
-    }
-
-
-    /**
-     * Given a ton of input, determines the value to use for the models.
-     *
-     * @return array|null
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws RestException
-     * @throws DomainException
-     * @since 4.9.72.p
-     */
-    public function determineConditionsQueryParameterValue()
-    {
-        if ($this->valueIsArrayDuringRead()) {
-            return $this->determineModelValueGivenRestInputArray();
-        }
-        return $this->prepareValuesFromJson($this->getQueryParamValue());
-    }
-
-
-    /**
-     * Given that the array value provided was itself an array, handles finding the correct value to pass to the model.
-     *
-     * @return array|null
-     * @throws RestException
-     * @throws EE_Error
-     * @since 4.9.72.p
-     */
-    private function determineModelValueGivenRestInputArray()
-    {
-        $this->transformSimplifiedSpecifiedOperatorSyntaxIntoStandardSyntax();
-        // did they specify an operator?
-        if ($this->valueIsLegacySpecifiedOperator()) {
-            $query_param_value = $this->getQueryParamValue();
-            $sub_array_key     = $query_param_value[0];
-            $translated_value  = [$sub_array_key];
-            if ($this->operatorIsNAry($sub_array_key)) {
-                $translated_value[] = $this->prepareValuesFromJson($query_param_value[1]);
-            } elseif ($this->operatorIsTernary($sub_array_key)) {
-                $translated_value[] = [
-                    $this->prepareValuesFromJson($query_param_value[1][0]),
-                    $this->prepareValuesFromJson($query_param_value[1][1]),
-                ];
-            } elseif ($this->operatorIsLike($sub_array_key)) {
-                // we want to leave this value mostly-as-is (eg don't force it to be a float
-                // or a boolean or an enum value. Leave it as-is with wildcards etc)
-                // but do verify it at least doesn't have any serialized data
-                ModelDataTranslator::throwExceptionIfContainsSerializedData($query_param_value[1]);
-                $translated_value[] = $query_param_value[1];
-            } elseif ($this->operatorIsUnary($sub_array_key)) {
-                // no arguments should have been provided, so don't look for any
-            } elseif ($this->operatorIsBinary($sub_array_key)) {
-                // it's a valid operator, but none of the exceptions. Treat it normally.
-                $translated_value[] = $this->prepareValuesFromJson($query_param_value[1]);
-            } else {
-                // so they provided a valid operator, but wrong number of arguments
-                $this->throwWrongNumberOfArgsExceptionIfDebugging($sub_array_key);
-                $translated_value = null;
-            }
-        } else {
-            // so they didn't provide a valid operator
-            // if we aren't in debug mode, then just try our best to fulfill the user's request
-            $this->throwInvalidOperatorExceptionIfDebugging();
-            $translated_value = null;
-        }
-        return $translated_value;
-    }
-
-
-    /**
-     * Returns if this request is a "read" request and the value provided was an array.
-     * This will indicate is such things as `array('<', 123)` and `array('IN', array(1,2,3))` are acceptable or not.
-     *
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function valueIsArrayDuringRead()
-    {
-        return ! $this->getContext()->isWriting() && is_array($this->getQueryParamValue());
-    }
-
-
-    /**
-     * Returns if the value provided was an associative array (we should have already verified it's an array of some
-     * sort). If the value is an associative array, it had better be in the simplified specified operator structure.
-     *
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function valueIsAssociativeArray()
-    {
-        return ! EEH_Array::is_array_numerically_and_sequentially_indexed($this->getQueryParamValue());
-    }
-
-
-    /**
-     * Checks if the array value is itself an array that fits into the simplified specified operator structure
-     * (eg `array('!=' => 123)`).
-     *
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function valueIsSimplifiedSpecifiedOperator()
-    {
-        return count($this->getQueryParamValue()) === 1
-               && array_key_exists(
-                   key($this->getQueryParamValue()),
-                   $this->getContext()->getModel()->valid_operators()
-               );
-    }
-
-
-    /**
-     * Throws an exception if the sub-value is an array (eg `array('!=' => array())`). It needs to just be a string,
-     * of either comma-separated-values, or a JSON array.
-     *
-     * @param $sub_array_key
-     * @param $sub_array_value
-     * @throws RestException
-     * @since 4.9.72.p
-     */
-    private function assertSubValueIsNotArray($sub_array_key, $sub_array_value)
-    {
-        if (is_array($sub_array_value) && EED_Core_Rest_Api::debugMode()) {
-            throw new RestException(
-                'csv_or_json_string_only',
-                sprintf(
-                /* translators: 1: variable name*/
-                    esc_html__(
-                        'The value provided for the operator "%1$s" should be comma-separated value string or a JSON array.',
-                        'event_espresso'
-                    ),
-                    $sub_array_key
-                ),
-                [
-                    'status' => 400,
-                ]
-            );
-        }
-    }
-
-
-    /**
-     * Determines if the sub-array key is an operator taking 3 or more operators.
-     *
-     * @param $sub_array_key
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function subArrayKeyIsNonBinaryOperator($sub_array_key)
-    {
-        return array_key_exists(
-            $sub_array_key,
-            array_merge(
-                $this->getContext()->getModel()->valid_in_style_operators(),
-                $this->getContext()->getModel()->valid_between_style_operators()
-            )
-        );
-    }
-
-
-    /**
-     * Given that the $sub_array_key is a string, checks if it's an operator taking only 1 argument.
-     *
-     * @param string $sub_array_key
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function subArrayKeyIsUnaryOperator($sub_array_key)
-    {
-        return array_key_exists(
-            $sub_array_key,
-            $this->getContext()->getModel()->valid_null_style_operators()
-        );
-    }
-
-
-    /**
-     * Parses the $sub_array_value string into an array (given it could either be a comma-separated-list or a JSON
-     * array). eg `"1,2,3"` or `"[1,2,3]"` into `array(1,2,3)`.
-     *
-     * @param $sub_array_value
-     * @return array|mixed|object
-     * @since 4.9.72.p
-     */
-    private function extractQuickStyleSpecifiedOperatorValue($sub_array_value)
-    {
-        // the value should be JSON or CSV
-        $values = json_decode($sub_array_value);
-        if (! is_array($values)) {
-            $values = array_filter(
-                array_map(
-                    'trim',
-                    explode(
-                        ',',
-                        $sub_array_value
-                    )
-                )
-            );
-        }
-        return $values;
-    }
-
-
-    /**
-     * Throws an exception if the value isn't a simplified specified operator (only called when we expect that).
-     *
-     * @throws RestException
-     * @since 4.9.72.p
-     */
-    private function assertSimplifiedSpecifiedOperator()
-    {
-        if (! $this->valueIsSimplifiedSpecifiedOperator() && EED_Core_Rest_Api::debugMode()) {
-            throw new RestException(
-                'numerically_indexed_array_of_values_only',
-                sprintf(
-                /* translators: 1: variable name*/
-                    esc_html__(
-                        'The array provided for the parameter "%1$s" should be numerically indexed.',
-                        'event_espresso'
-                    ),
-                    $this->getQueryParamKey()
-                ),
-                [
-                    'status' => 400,
-                ]
-            );
-        }
-    }
-
-
-    /**
-     * If query_param_value were in the simplified specific operator structure, change it into the legacy structure.
-     *
-     * @throws RestException
-     * @since 4.9.72.p
-     */
-    private function transformSimplifiedSpecifiedOperatorSyntaxIntoStandardSyntax()
-    {
-        if ($this->valueIsAssociativeArray()) {
-            $this->assertSimplifiedSpecifiedOperator();
-            $query_param_value = $this->getQueryParamValue();
-            $sub_array_value   = reset($query_param_value);
-            $sub_array_key     = key($query_param_value);
-            $this->assertSubValueIsNotArray($sub_array_key, $sub_array_value);
-            // they're doing something like "&where[EVT_ID][IN]=1,2,3" or "&where[EVT_ID][>]=5"
-            if ($this->subArrayKeyIsNonBinaryOperator($sub_array_key)) {
-                $this->setQueryParamValue(
-                    [
-                        $sub_array_key,
-                        $this->extractQuickStyleSpecifiedOperatorValue($sub_array_value),
-                    ]
-                );
-            } elseif ($this->subArrayKeyIsUnaryOperator($sub_array_key)) {
-                $this->setQueryParamValue([$sub_array_key]);
-            } else {
-                $this->setQueryParamValue([$sub_array_key, $sub_array_value]);
-            }
-        }
-    }
-
-
-    /**
-     * Returns true is the value is an array using the legacy structure to specify the operator. Eg `array('!=',123)`.
-     *
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function valueIsLegacySpecifiedOperator()
-    {
-        $valid_operators   = $this->getContext()->getModel()->valid_operators();
-        $query_param_value = $this->getQueryParamValue();
-        return isset($query_param_value[0])
-               && isset($valid_operators[ $query_param_value[0] ]);
-    }
-
-
-    /**
-     * Returns true if the value specified operator accepts arbitrary number of arguments, like "IN".
-     *
-     * @param $operator
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function operatorIsNAry($operator)
-    {
-        $valueArray = $this->getQueryParamValue();
-        return array_key_exists(
-            $operator,
-            $this->getContext()->getModel()->valid_in_style_operators()
-        )
-               && isset($valueArray[1])
-               && is_array($valueArray[1])
-               && ! isset($valueArray[2]);
-    }
-
-
-    /**
-     * Returns true if the operator accepts 3 arguments (eg "BETWEEN").
-     * So we're looking for a value that looks like
-     * `array('BETWEEN', array('2015-01-01T00:00:00', '2016-01-01T00:00:00'))`.
-     *
-     * @param $operator
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function operatorIsTernary($operator)
-    {
-        $query_param_value = $this->getQueryParamValue();
-        return array_key_exists($operator, $this->getContext()->getModel()->valid_between_style_operators())
-               && isset($query_param_value[1])
-               && is_array($query_param_value[1])
-               && isset($query_param_value[1][0], $query_param_value[1][1])
-               && ! isset($query_param_value[1][2])
-               && ! isset($query_param_value[2]);
-    }
-
-
-    /**
-     * Returns true if the operator is a similar to LIKE, indicating the value may have wildcards we should leave alone.
-     *
-     * @param $operator
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function operatorIsLike($operator)
-    {
-        $query_param_value = $this->getQueryParamValue();
-        return array_key_exists($operator, $this->getContext()->getModel()->valid_like_style_operators())
-               && isset($query_param_value[1])
-               && ! isset($query_param_value[2]);
-    }
-
-
-    /**
-     * Returns true if the operator only takes one argument (eg it's like `IS NULL`).
-     *
-     * @param $operator
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function operatorIsUnary($operator)
-    {
-        $query_param_value = $this->getQueryParamValue();
-        return array_key_exists($operator, $this->getContext()->getModel()->valid_null_style_operators())
-               && ! isset($query_param_value[1]);
-    }
-
-
-    /**
-     * Returns true if the operator specified is a binary operator (eg `=`, `!=`)
-     *
-     * @param $operator
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function operatorIsBinary($operator)
-    {
-        $query_param_value = $this->getQueryParamValue();
-        $model             = $this->getContext()->getModel();
-        return isset($query_param_value[1])
-               && ! isset($query_param_value[2])
-               && ! array_key_exists(
-                   $operator,
-                   array_merge(
-                       $model->valid_in_style_operators(),
-                       $model->valid_null_style_operators(),
-                       $model->valid_like_style_operators(),
-                       $model->valid_between_style_operators()
-                   )
-               );
-    }
-
-
-    /**
-     * If we're debugging, throws an exception saying that the wrong number of arguments was provided.
-     *
-     * @param $operator
-     * @throws RestException
-     * @since 4.9.72.p
-     */
-    private function throwWrongNumberOfArgsExceptionIfDebugging($operator)
-    {
-        if (EED_Core_Rest_Api::debugMode()) {
-            throw new RestException(
-                'wrong_number_of_arguments',
-                sprintf(
-                    esc_html__(
-                        'The operator you provided, "%1$s" had the wrong number of arguments',
-                        'event_espresso'
-                    ),
-                    $operator
-                ),
-                [
-                    'status' => 400,
-                ]
-            );
-        }
-    }
-
-
-    /**
-     * Wrapper for ModelDataTranslator::prepareFieldValuesFromJson(), just a tad more DRY.
-     *
-     * @param $value
-     * @return mixed
-     * @throws EE_Error
-     * @throws RestException
-     * @since 4.9.72.p
-     */
-    private function prepareValuesFromJson($value)
-    {
-        return ModelDataTranslator::prepareFieldValuesFromJson(
-            $this->getField(),
-            $value,
-            $this->getContext()->getRequestedVersion(),
-            $this->getTimezone()
-        );
-    }
-
-
-    /**
-     * Throws an exception if an invalid operator was specified and we're debugging.
-     *
-     * @throws RestException
-     * @since 4.9.72.p
-     */
-    private function throwInvalidOperatorExceptionIfDebugging()
-    {
-        // so they didn't provide a valid operator
-        if (EED_Core_Rest_Api::debugMode()) {
-            throw new RestException(
-                'invalid_operator',
-                sprintf(
-                    esc_html__(
-                        'You provided an invalid parameter, with key "%1$s" and value "%2$s"',
-                        'event_espresso'
-                    ),
-                    $this->getQueryParamKey(),
-                    $this->getQueryParamValue()
-                ),
-                [
-                    'status' => 400,
-                ]
-            );
-        }
-    }
-
-
-    /**
-     * Returns true if the query_param_key was a logic query parameter, eg `OR`, `AND`, `NOT`, `OR*`, etc.
-     *
-     * @return boolean
-     * @since 4.9.72.p
-     */
-    private function isLogicQueryParam()
-    {
-        return in_array($this->getQueryParamKeySansStars(), $this->getContext()->getModel()->logic_query_param_keys());
-    }
-
-
-    /**
-     * If the query param isn't for a field, it must be a nested query parameter which requires different logic.
-     *
-     * @return array
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws RestException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws InvalidArgumentException
-     * @since 4.9.72.p
-     */
-    public function determineNestedConditionQueryParameters()
-    {
-        // so this param doesn't correspond to a field eh?
-        if ($this->getContext()->isWriting()) {
-            // always tell API clients about invalid parameters when they're creating data. Otherwise,
-            // they are probably going to create invalid data
-            throw new RestException(
-                'invalid_field',
-                sprintf(
-                /* translators: 1: variable name */
-                    esc_html__('You have provided an invalid parameter: "%1$s"', 'event_espresso'),
-                    $this->getQueryParamKey()
-                )
-            );
-        }
-        // so it's not for a field, is it a logic query param key?
-        if ($this->isLogicQueryParam()) {
-            return ModelDataTranslator::prepareConditionsQueryParamsForModels(
-                $this->getQueryParamValue(),
-                $this->getContext()->getModel(),
-                $this->getContext()->getRequestedVersion()
-            );
-        }
-        if (EED_Core_Rest_Api::debugMode()) {
-            // only tell API clients they got it wrong if we're in debug mode
-            // otherwise try our best ot fulfill their request by ignoring this invalid data
-            throw new RestException(
-                'invalid_parameter',
-                sprintf(
-                /* translators: 1: variable name */
-                    esc_html__(
-                        'You provided an invalid parameter, with key "%1$s"',
-                        'event_espresso'
-                    ),
-                    $this->getQueryParamKey()
-                ),
-                [
-                    'status' => 400,
-                ]
-            );
-        }
-        return null;
-    }
+	private $query_param_key;
+
+	private $query_param_value;
+
+	/**
+	 * @var RestIncomingQueryParamContext
+	 */
+	private $context;
+
+	/**
+	 * @var EE_Model_Field_Base|null
+	 */
+	private $field;
+
+	/**
+	 * @var string same as $query_param_key but has the * and anything after it removed
+	 */
+	private $query_param_key_sans_stars;
+
+	/**
+	 * @var string for timezone or timezone offset
+	 */
+	private $timezone;
+
+	/**
+	 * @var boolean if the field in $query_param_key is for a GMT field (eg `EVT_modified_gmt`)
+	 */
+	private $is_gmt_field = false;
+
+
+	/**
+	 * RestIncomingQueryParamMetadata constructor.
+	 * You probably want to call
+	 *
+	 * @param string                        $query_param_key
+	 * @param string                        $query_param_value
+	 * @param RestIncomingQueryParamContext $context
+	 * @throws EE_Error
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function __construct($query_param_key, $query_param_value, RestIncomingQueryParamContext $context)
+	{
+		$this->query_param_key   = $query_param_key;
+		$this->query_param_value = $query_param_value;
+		$this->context           = $context;
+		$this->determineFieldAndTimezone();
+	}
+
+
+	/**
+	 * Gets the query parameter key. This may have been modified (see setQueryParamValue())
+	 *
+	 * @return string
+	 */
+	public function getQueryParamKey()
+	{
+		return $this->query_param_key;
+	}
+
+
+	/**
+	 * Modifies the query parameter key passed in (Eg this is done when rewriting the simplified specified operator REST
+	 * query parameters into the legacy structure)
+	 *
+	 * @param string|array|int|float $query_param_value
+	 */
+	private function setQueryParamValue($query_param_value)
+	{
+		$this->query_param_value = $query_param_value;
+	}
+
+
+	/**
+	 * Gets the original query parameter value passed in.
+	 *
+	 * @return array|string
+	 */
+	public function getQueryParamValue()
+	{
+		return $this->query_param_value;
+	}
+
+
+	/**
+	 * Gets the context object.
+	 *
+	 * @return RestIncomingQueryParamContext
+	 */
+	public function getContext()
+	{
+		return $this->context;
+	}
+
+
+	/**
+	 * Sets the query parameter key. This may be used to rewrite a key into its non-GMT alternative.
+	 *
+	 * @param string $query_param_key
+	 */
+	private function setQueryParamKey($query_param_key)
+	{
+		$this->query_param_key = $query_param_key;
+	}
+
+
+	/**
+	 * Gets the field the query parameter key indicated. This may be null (in cases where the query parameter key
+	 * did not indicate a field, eg if it were `OR`).
+	 *
+	 * @return EE_Model_Field_Base|null
+	 */
+	public function getField()
+	{
+		return $this->field;
+	}
+
+
+	/**
+	 * Gets the query parameter key (with the star and everything afterwards removed).
+	 *
+	 * @return string
+	 */
+	public function getQueryParamKeySansStars()
+	{
+		return $this->query_param_key_sans_stars;
+	}
+
+
+	/**
+	 * Gets the timezone associated with this model (the site timezone, except for GMT datetime fields).
+	 *
+	 * @return string
+	 */
+	public function getTimezone()
+	{
+		return $this->timezone;
+	}
+
+
+	/**
+	 * Returns whether or not this is a GMT field
+	 *
+	 * @return boolean
+	 */
+	public function isGmtField()
+	{
+		return $this->is_gmt_field;
+	}
+
+
+	/**
+	 * Sets the field indicated by the query parameter key (might be null).
+	 *
+	 * @param EE_Model_Field_Base|null $field
+	 */
+	private function setField(EE_Model_Field_Base $field = null)
+	{
+		$this->field = $field;
+	}
+
+
+	/**
+	 * Sets the query parameter key-with-stars-removed.
+	 *
+	 * @param string $query_param_key_sans_stars
+	 */
+	private function setQueryParamKeySansStars($query_param_key_sans_stars)
+	{
+		$this->query_param_key_sans_stars = $query_param_key_sans_stars;
+	}
+
+
+	/**
+	 * Sets the timezone (this could be a timezone offset string).
+	 *
+	 * @param string $timezone
+	 */
+	private function setTimezone($timezone)
+	{
+		$this->timezone = $timezone;
+	}
+
+
+	/**
+	 * @param mixed $is_gmt_field
+	 */
+	private function setIsGmtField($is_gmt_field)
+	{
+		$this->is_gmt_field = $is_gmt_field;
+	}
+
+
+	/**
+	 * Determines what field, query param name, and query param name without stars, and timezone to use.
+	 *
+	 * @return void {
+	 * @throws EE_Error
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidArgumentException
+	 * @throws ReflectionException
+	 * @since 4.9.72.p
+	 */
+	private function determineFieldAndTimezone()
+	{
+		$this->setQueryParamKeySansStars(
+			ModelDataTranslator::removeStarsAndAnythingAfterFromConditionQueryParamKey(
+				$this->getQueryParamKey()
+			)
+		);
+		$this->setField(
+			ModelDataTranslator::deduceFieldFromQueryParam(
+				$this->getQueryParamKeySansStars(),
+				$this->getContext()->getModel()
+			)
+		);
+		// double-check is it a *_gmt field?
+		if (
+			! $this->getField() instanceof EE_Model_Field_Base
+			&& ModelDataTranslator::isGmtDateFieldName($this->getQueryParamKeySansStars())
+		) {
+			// yep, take off '_gmt', and find the field
+			$this->setQueryParamKey(ModelDataTranslator::removeGmtFromFieldName($this->getQueryParamKeySansStars()));
+			$this->setField(
+				ModelDataTranslator::deduceFieldFromQueryParam(
+					$this->getQueryParamKey(),
+					$this->context->getModel()
+				)
+			);
+			$this->setTimezone('UTC');
+			$this->setIsGmtField(true);
+		} elseif ($this->getField() instanceof EE_Datetime_Field) {
+			// so it's not a GMT field. Set the timezone on the model to the default
+			$this->setTimezone(EEH_DTT_Helper::get_valid_timezone_string());
+		} else {
+			// just keep using what's already set for the timezone
+			$this->setTimezone($this->context->getModel()->get_timezone());
+		}
+		$this->assertOnlyAdminCanReadPasswordFields();
+	}
+
+
+	/**
+	 * Throws an exception if a non-admin is trying to query by password.
+	 *
+	 * @throws RestException
+	 * @since 4.9.74.p
+	 */
+	private function assertOnlyAdminCanReadPasswordFields()
+	{
+		if (
+			$this->getField() instanceof EE_Password_Field
+			&& ! current_user_can(EE_Restriction_Generator_Base::get_default_restrictions_cap())
+		) {
+			// only full admins can query by password. sorry bub!
+			throw new RestException(
+				'only_admins_can_query_by_password',
+				// @codingStandardsIgnoreStart
+				esc_html__(
+					'You attempted to filter by a password field without the needed privileges. Only a full admin is allowed to do that.',
+					'event_espresso'
+				),
+				// @codingStandardsIgnoreEnd
+				[
+					'status' => 403,
+				]
+			);
+		}
+	}
+
+
+	/**
+	 * Given a ton of input, determines the value to use for the models.
+	 *
+	 * @return array|null
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws RestException
+	 * @throws DomainException
+	 * @since 4.9.72.p
+	 */
+	public function determineConditionsQueryParameterValue()
+	{
+		if ($this->valueIsArrayDuringRead()) {
+			return $this->determineModelValueGivenRestInputArray();
+		}
+		return $this->prepareValuesFromJson($this->getQueryParamValue());
+	}
+
+
+	/**
+	 * Given that the array value provided was itself an array, handles finding the correct value to pass to the model.
+	 *
+	 * @return array|null
+	 * @throws RestException
+	 * @throws EE_Error
+	 * @since 4.9.72.p
+	 */
+	private function determineModelValueGivenRestInputArray()
+	{
+		$this->transformSimplifiedSpecifiedOperatorSyntaxIntoStandardSyntax();
+		// did they specify an operator?
+		if ($this->valueIsLegacySpecifiedOperator()) {
+			$query_param_value = $this->getQueryParamValue();
+			$sub_array_key     = $query_param_value[0];
+			$translated_value  = [$sub_array_key];
+			if ($this->operatorIsNAry($sub_array_key)) {
+				$translated_value[] = $this->prepareValuesFromJson($query_param_value[1]);
+			} elseif ($this->operatorIsTernary($sub_array_key)) {
+				$translated_value[] = [
+					$this->prepareValuesFromJson($query_param_value[1][0]),
+					$this->prepareValuesFromJson($query_param_value[1][1]),
+				];
+			} elseif ($this->operatorIsLike($sub_array_key)) {
+				// we want to leave this value mostly-as-is (eg don't force it to be a float
+				// or a boolean or an enum value. Leave it as-is with wildcards etc)
+				// but do verify it at least doesn't have any serialized data
+				ModelDataTranslator::throwExceptionIfContainsSerializedData($query_param_value[1]);
+				$translated_value[] = $query_param_value[1];
+			} elseif ($this->operatorIsUnary($sub_array_key)) {
+				// no arguments should have been provided, so don't look for any
+			} elseif ($this->operatorIsBinary($sub_array_key)) {
+				// it's a valid operator, but none of the exceptions. Treat it normally.
+				$translated_value[] = $this->prepareValuesFromJson($query_param_value[1]);
+			} else {
+				// so they provided a valid operator, but wrong number of arguments
+				$this->throwWrongNumberOfArgsExceptionIfDebugging($sub_array_key);
+				$translated_value = null;
+			}
+		} else {
+			// so they didn't provide a valid operator
+			// if we aren't in debug mode, then just try our best to fulfill the user's request
+			$this->throwInvalidOperatorExceptionIfDebugging();
+			$translated_value = null;
+		}
+		return $translated_value;
+	}
+
+
+	/**
+	 * Returns if this request is a "read" request and the value provided was an array.
+	 * This will indicate is such things as `array('<', 123)` and `array('IN', array(1,2,3))` are acceptable or not.
+	 *
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function valueIsArrayDuringRead()
+	{
+		return ! $this->getContext()->isWriting() && is_array($this->getQueryParamValue());
+	}
+
+
+	/**
+	 * Returns if the value provided was an associative array (we should have already verified it's an array of some
+	 * sort). If the value is an associative array, it had better be in the simplified specified operator structure.
+	 *
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function valueIsAssociativeArray()
+	{
+		return ! EEH_Array::is_array_numerically_and_sequentially_indexed($this->getQueryParamValue());
+	}
+
+
+	/**
+	 * Checks if the array value is itself an array that fits into the simplified specified operator structure
+	 * (eg `array('!=' => 123)`).
+	 *
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function valueIsSimplifiedSpecifiedOperator()
+	{
+		return count($this->getQueryParamValue()) === 1
+			   && array_key_exists(
+				   key($this->getQueryParamValue()),
+				   $this->getContext()->getModel()->valid_operators()
+			   );
+	}
+
+
+	/**
+	 * Throws an exception if the sub-value is an array (eg `array('!=' => array())`). It needs to just be a string,
+	 * of either comma-separated-values, or a JSON array.
+	 *
+	 * @param $sub_array_key
+	 * @param $sub_array_value
+	 * @throws RestException
+	 * @since 4.9.72.p
+	 */
+	private function assertSubValueIsNotArray($sub_array_key, $sub_array_value)
+	{
+		if (is_array($sub_array_value) && EED_Core_Rest_Api::debugMode()) {
+			throw new RestException(
+				'csv_or_json_string_only',
+				sprintf(
+				/* translators: 1: variable name*/
+					esc_html__(
+						'The value provided for the operator "%1$s" should be comma-separated value string or a JSON array.',
+						'event_espresso'
+					),
+					$sub_array_key
+				),
+				[
+					'status' => 400,
+				]
+			);
+		}
+	}
+
+
+	/**
+	 * Determines if the sub-array key is an operator taking 3 or more operators.
+	 *
+	 * @param $sub_array_key
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function subArrayKeyIsNonBinaryOperator($sub_array_key)
+	{
+		return array_key_exists(
+			$sub_array_key,
+			array_merge(
+				$this->getContext()->getModel()->valid_in_style_operators(),
+				$this->getContext()->getModel()->valid_between_style_operators()
+			)
+		);
+	}
+
+
+	/**
+	 * Given that the $sub_array_key is a string, checks if it's an operator taking only 1 argument.
+	 *
+	 * @param string $sub_array_key
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function subArrayKeyIsUnaryOperator($sub_array_key)
+	{
+		return array_key_exists(
+			$sub_array_key,
+			$this->getContext()->getModel()->valid_null_style_operators()
+		);
+	}
+
+
+	/**
+	 * Parses the $sub_array_value string into an array (given it could either be a comma-separated-list or a JSON
+	 * array). eg `"1,2,3"` or `"[1,2,3]"` into `array(1,2,3)`.
+	 *
+	 * @param $sub_array_value
+	 * @return array|mixed|object
+	 * @since 4.9.72.p
+	 */
+	private function extractQuickStyleSpecifiedOperatorValue($sub_array_value)
+	{
+		// the value should be JSON or CSV
+		$values = json_decode($sub_array_value);
+		if (! is_array($values)) {
+			$values = array_filter(
+				array_map(
+					'trim',
+					explode(
+						',',
+						$sub_array_value
+					)
+				)
+			);
+		}
+		return $values;
+	}
+
+
+	/**
+	 * Throws an exception if the value isn't a simplified specified operator (only called when we expect that).
+	 *
+	 * @throws RestException
+	 * @since 4.9.72.p
+	 */
+	private function assertSimplifiedSpecifiedOperator()
+	{
+		if (! $this->valueIsSimplifiedSpecifiedOperator() && EED_Core_Rest_Api::debugMode()) {
+			throw new RestException(
+				'numerically_indexed_array_of_values_only',
+				sprintf(
+				/* translators: 1: variable name*/
+					esc_html__(
+						'The array provided for the parameter "%1$s" should be numerically indexed.',
+						'event_espresso'
+					),
+					$this->getQueryParamKey()
+				),
+				[
+					'status' => 400,
+				]
+			);
+		}
+	}
+
+
+	/**
+	 * If query_param_value were in the simplified specific operator structure, change it into the legacy structure.
+	 *
+	 * @throws RestException
+	 * @since 4.9.72.p
+	 */
+	private function transformSimplifiedSpecifiedOperatorSyntaxIntoStandardSyntax()
+	{
+		if ($this->valueIsAssociativeArray()) {
+			$this->assertSimplifiedSpecifiedOperator();
+			$query_param_value = $this->getQueryParamValue();
+			$sub_array_value   = reset($query_param_value);
+			$sub_array_key     = key($query_param_value);
+			$this->assertSubValueIsNotArray($sub_array_key, $sub_array_value);
+			// they're doing something like "&where[EVT_ID][IN]=1,2,3" or "&where[EVT_ID][>]=5"
+			if ($this->subArrayKeyIsNonBinaryOperator($sub_array_key)) {
+				$this->setQueryParamValue(
+					[
+						$sub_array_key,
+						$this->extractQuickStyleSpecifiedOperatorValue($sub_array_value),
+					]
+				);
+			} elseif ($this->subArrayKeyIsUnaryOperator($sub_array_key)) {
+				$this->setQueryParamValue([$sub_array_key]);
+			} else {
+				$this->setQueryParamValue([$sub_array_key, $sub_array_value]);
+			}
+		}
+	}
+
+
+	/**
+	 * Returns true is the value is an array using the legacy structure to specify the operator. Eg `array('!=',123)`.
+	 *
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function valueIsLegacySpecifiedOperator()
+	{
+		$valid_operators   = $this->getContext()->getModel()->valid_operators();
+		$query_param_value = $this->getQueryParamValue();
+		return isset($query_param_value[0])
+			   && isset($valid_operators[ $query_param_value[0] ]);
+	}
+
+
+	/**
+	 * Returns true if the value specified operator accepts arbitrary number of arguments, like "IN".
+	 *
+	 * @param $operator
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function operatorIsNAry($operator)
+	{
+		$valueArray = $this->getQueryParamValue();
+		return array_key_exists(
+			$operator,
+			$this->getContext()->getModel()->valid_in_style_operators()
+		)
+			   && isset($valueArray[1])
+			   && is_array($valueArray[1])
+			   && ! isset($valueArray[2]);
+	}
+
+
+	/**
+	 * Returns true if the operator accepts 3 arguments (eg "BETWEEN").
+	 * So we're looking for a value that looks like
+	 * `array('BETWEEN', array('2015-01-01T00:00:00', '2016-01-01T00:00:00'))`.
+	 *
+	 * @param $operator
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function operatorIsTernary($operator)
+	{
+		$query_param_value = $this->getQueryParamValue();
+		return array_key_exists($operator, $this->getContext()->getModel()->valid_between_style_operators())
+			   && isset($query_param_value[1])
+			   && is_array($query_param_value[1])
+			   && isset($query_param_value[1][0], $query_param_value[1][1])
+			   && ! isset($query_param_value[1][2])
+			   && ! isset($query_param_value[2]);
+	}
+
+
+	/**
+	 * Returns true if the operator is a similar to LIKE, indicating the value may have wildcards we should leave alone.
+	 *
+	 * @param $operator
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function operatorIsLike($operator)
+	{
+		$query_param_value = $this->getQueryParamValue();
+		return array_key_exists($operator, $this->getContext()->getModel()->valid_like_style_operators())
+			   && isset($query_param_value[1])
+			   && ! isset($query_param_value[2]);
+	}
+
+
+	/**
+	 * Returns true if the operator only takes one argument (eg it's like `IS NULL`).
+	 *
+	 * @param $operator
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function operatorIsUnary($operator)
+	{
+		$query_param_value = $this->getQueryParamValue();
+		return array_key_exists($operator, $this->getContext()->getModel()->valid_null_style_operators())
+			   && ! isset($query_param_value[1]);
+	}
+
+
+	/**
+	 * Returns true if the operator specified is a binary operator (eg `=`, `!=`)
+	 *
+	 * @param $operator
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function operatorIsBinary($operator)
+	{
+		$query_param_value = $this->getQueryParamValue();
+		$model             = $this->getContext()->getModel();
+		return isset($query_param_value[1])
+			   && ! isset($query_param_value[2])
+			   && ! array_key_exists(
+				   $operator,
+				   array_merge(
+					   $model->valid_in_style_operators(),
+					   $model->valid_null_style_operators(),
+					   $model->valid_like_style_operators(),
+					   $model->valid_between_style_operators()
+				   )
+			   );
+	}
+
+
+	/**
+	 * If we're debugging, throws an exception saying that the wrong number of arguments was provided.
+	 *
+	 * @param $operator
+	 * @throws RestException
+	 * @since 4.9.72.p
+	 */
+	private function throwWrongNumberOfArgsExceptionIfDebugging($operator)
+	{
+		if (EED_Core_Rest_Api::debugMode()) {
+			throw new RestException(
+				'wrong_number_of_arguments',
+				sprintf(
+					esc_html__(
+						'The operator you provided, "%1$s" had the wrong number of arguments',
+						'event_espresso'
+					),
+					$operator
+				),
+				[
+					'status' => 400,
+				]
+			);
+		}
+	}
+
+
+	/**
+	 * Wrapper for ModelDataTranslator::prepareFieldValuesFromJson(), just a tad more DRY.
+	 *
+	 * @param $value
+	 * @return mixed
+	 * @throws EE_Error
+	 * @throws RestException
+	 * @since 4.9.72.p
+	 */
+	private function prepareValuesFromJson($value)
+	{
+		return ModelDataTranslator::prepareFieldValuesFromJson(
+			$this->getField(),
+			$value,
+			$this->getContext()->getRequestedVersion(),
+			$this->getTimezone()
+		);
+	}
+
+
+	/**
+	 * Throws an exception if an invalid operator was specified and we're debugging.
+	 *
+	 * @throws RestException
+	 * @since 4.9.72.p
+	 */
+	private function throwInvalidOperatorExceptionIfDebugging()
+	{
+		// so they didn't provide a valid operator
+		if (EED_Core_Rest_Api::debugMode()) {
+			throw new RestException(
+				'invalid_operator',
+				sprintf(
+					esc_html__(
+						'You provided an invalid parameter, with key "%1$s" and value "%2$s"',
+						'event_espresso'
+					),
+					$this->getQueryParamKey(),
+					$this->getQueryParamValue()
+				),
+				[
+					'status' => 400,
+				]
+			);
+		}
+	}
+
+
+	/**
+	 * Returns true if the query_param_key was a logic query parameter, eg `OR`, `AND`, `NOT`, `OR*`, etc.
+	 *
+	 * @return boolean
+	 * @since 4.9.72.p
+	 */
+	private function isLogicQueryParam()
+	{
+		return in_array($this->getQueryParamKeySansStars(), $this->getContext()->getModel()->logic_query_param_keys());
+	}
+
+
+	/**
+	 * If the query param isn't for a field, it must be a nested query parameter which requires different logic.
+	 *
+	 * @return array
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws RestException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidArgumentException
+	 * @since 4.9.72.p
+	 */
+	public function determineNestedConditionQueryParameters()
+	{
+		// so this param doesn't correspond to a field eh?
+		if ($this->getContext()->isWriting()) {
+			// always tell API clients about invalid parameters when they're creating data. Otherwise,
+			// they are probably going to create invalid data
+			throw new RestException(
+				'invalid_field',
+				sprintf(
+				/* translators: 1: variable name */
+					esc_html__('You have provided an invalid parameter: "%1$s"', 'event_espresso'),
+					$this->getQueryParamKey()
+				)
+			);
+		}
+		// so it's not for a field, is it a logic query param key?
+		if ($this->isLogicQueryParam()) {
+			return ModelDataTranslator::prepareConditionsQueryParamsForModels(
+				$this->getQueryParamValue(),
+				$this->getContext()->getModel(),
+				$this->getContext()->getRequestedVersion()
+			);
+		}
+		if (EED_Core_Rest_Api::debugMode()) {
+			// only tell API clients they got it wrong if we're in debug mode
+			// otherwise try our best ot fulfill their request by ignoring this invalid data
+			throw new RestException(
+				'invalid_parameter',
+				sprintf(
+				/* translators: 1: variable name */
+					esc_html__(
+						'You provided an invalid parameter, with key "%1$s"',
+						'event_espresso'
+					),
+					$this->getQueryParamKey()
+				),
+				[
+					'status' => 400,
+				]
+			);
+		}
+		return null;
+	}
 }
 // End of file RestQueryParamMetadata.php
 // Location: EventEspresso\core\libraries\rest_api/RestQueryParamMetadata.php