eventespresso / event-espresso-core

core/helpers/EEH_Line_Item.helper.php

Indentation +2236 added lines, -2236 removed lines

@@ -21,2240 +21,2240 @@
  */
 class EEH_Line_Item
 {
-    /**
-     * @var EE_Line_Item[]|null
-     */
-    private static ?array $global_taxes = null;
-
-
-    /**
-     * Adds a simple item (unrelated to any other model object) to the provided PARENT line item.
-     * Does NOT automatically re-calculate the line item totals or update the related transaction.
-     * You should call recalculate_total_including_taxes() on the grant total line item after this
-     * to update the subtotals, and EE_Registration_Processor::calculate_reg_final_prices_per_line_item()
-     * to keep the registration final prices in-sync with the transaction's total.
-     *
-     * @param EE_Line_Item $parent_line_item
-     * @param string       $name
-     * @param float        $unit_price
-     * @param string       $description
-     * @param int          $quantity
-     * @param boolean      $taxable
-     * @param string|null  $code if set to a value, ensures there is only one line item with that code
-     * @param bool         $return_item
-     * @param bool         $recalculate_totals
-     * @return boolean|EE_Line_Item success
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function add_unrelated_item(
-        EE_Line_Item $parent_line_item,
-        string $name,
-        float $unit_price,
-        string $description = '',
-        int $quantity = 1,
-        bool $taxable = false,
-        ?string $code = null,
-        bool $return_item = false,
-        bool $recalculate_totals = true
-    ) {
-        $items_subtotal = self::get_pre_tax_subtotal($parent_line_item);
-        $line_item      = EE_Line_Item::new_instance(
-            [
-                'LIN_name'       => $name,
-                'LIN_desc'       => $description,
-                'LIN_unit_price' => $unit_price,
-                'LIN_quantity'   => $quantity,
-                'LIN_percent'    => null,
-                'LIN_is_taxable' => $taxable,
-                'LIN_order'      => count($items_subtotal->children()),
-                'LIN_total'      => $unit_price * $quantity,
-                'LIN_type'       => EEM_Line_Item::type_line_item,
-                'LIN_code'       => $code,
-            ]
-        );
-        $line_item      = apply_filters(
-            'FHEE__EEH_Line_Item__add_unrelated_item__line_item',
-            $line_item,
-            $parent_line_item
-        );
-        $added          = self::add_item($parent_line_item, $line_item, $recalculate_totals);
-        return $return_item ? $line_item : $added;
-    }
-
-
-    /**
-     * Adds a simple item ( unrelated to any other model object) to the total line item,
-     * in the correct spot in the line item tree. Does not automatically
-     * re-calculate the line item totals, nor update the related transaction, nor upgrade the transaction's
-     * registrations' final prices (which should probably change because of this).
-     * You should call recalculate_total_including_taxes() on the grand total line item, then
-     * update the transaction's total, and EE_Registration_Processor::update_registration_final_prices()
-     * after using this, to keep the registration final prices in-sync with the transaction's total.
-     *
-     * @param EE_Line_Item $parent_line_item
-     * @param string       $name
-     * @param float        $percentage_amount
-     * @param string       $description
-     * @param boolean      $taxable
-     * @param string|null  $code
-     * @param bool         $return_item
-     * @return boolean|EE_Line_Item success
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function add_percentage_based_item(
-        EE_Line_Item $parent_line_item,
-        string $name,
-        float $percentage_amount,
-        string $description = '',
-        bool $taxable = false,
-        ?string $code = null,
-        bool $return_item = false
-    ) {
-        $total     = $percentage_amount * $parent_line_item->total() / 100;
-        $line_item = EE_Line_Item::new_instance(
-            [
-                'LIN_name'       => $name,
-                'LIN_desc'       => $description,
-                'LIN_unit_price' => 0,
-                'LIN_percent'    => $percentage_amount,
-                'LIN_is_taxable' => $taxable,
-                'LIN_total'      => $total,
-                'LIN_type'       => EEM_Line_Item::type_line_item,
-                'LIN_parent'     => $parent_line_item->ID(),
-                'LIN_code'       => $code,
-                'TXN_ID'         => $parent_line_item->TXN_ID(),
-            ]
-        );
-        $line_item = apply_filters(
-            'FHEE__EEH_Line_Item__add_percentage_based_item__line_item',
-            $line_item
-        );
-        $added     = $parent_line_item->add_child_line_item($line_item, false);
-        return $return_item ? $line_item : $added;
-    }
-
-
-    /**
-     * Returns the new line item created by adding a purchase of the ticket
-     * ensures that ticket line item is saved, and that cart total has been recalculated.
-     * If this ticket has already been purchased, just increments its count.
-     * Automatically re-calculates the line item totals and updates the related transaction. But
-     * DOES NOT automatically upgrade the transaction's registrations' final prices (which
-     * should probably change because of this).
-     * You should call EE_Registration_Processor::calculate_reg_final_prices_per_line_item()
-     * after using this, to keep the registration final prices in-sync with the transaction's total.
-     *
-     * @param EE_Line_Item|null $total_line_item grand total line item of type EEM_Line_Item::type_total
-     * @param EE_Ticket         $ticket
-     * @param int               $qty
-     * @param bool              $recalculate_totals
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function add_ticket_purchase(
-        ?EE_Line_Item $total_line_item,
-        EE_Ticket $ticket,
-        int $qty = 1,
-        bool $recalculate_totals = true
-    ): ?EE_Line_Item {
-        if (! $total_line_item instanceof EE_Line_Item || ! $total_line_item->is_total()) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'A valid line item total is required in order to add tickets. A line item of type "%s" was passed.',
-                        'event_espresso'
-                    ),
-                    $ticket->ID(),
-                    $total_line_item->ID()
-                )
-            );
-        }
-        // either increment the qty for an existing ticket
-        $line_item = self::increment_ticket_qty_if_already_in_cart($total_line_item, $ticket, $qty);
-        // or add a new one
-        if (! $line_item instanceof EE_Line_Item) {
-            $line_item = self::create_ticket_line_item($total_line_item, $ticket, $qty);
-        }
-        if ($recalculate_totals) {
-            $total_line_item->recalculate_total_including_taxes();
-        }
-        return $line_item;
-    }
-
-
-    /**
-     * Returns the new line item created by adding a purchase of the ticket
-     *
-     * @param EE_Line_Item|null $total_line_item
-     * @param EE_Ticket         $ticket
-     * @param int               $qty
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function increment_ticket_qty_if_already_in_cart(
-        ?EE_Line_Item $total_line_item,
-        EE_Ticket $ticket,
-        int $qty = 1
-    ): ?EE_Line_Item {
-        $line_item = null;
-        if ($total_line_item instanceof EE_Line_Item && $total_line_item->is_total()) {
-            $ticket_line_items = EEH_Line_Item::get_ticket_line_items($total_line_item);
-            foreach ($ticket_line_items as $ticket_line_item) {
-                if (
-                    $ticket_line_item instanceof EE_Line_Item
-                    && $ticket_line_item->OBJ_ID() === $ticket->ID()
-                ) {
-                    $line_item = $ticket_line_item;
-                    break;
-                }
-            }
-        }
-        if ($line_item instanceof EE_Line_Item) {
-            EEH_Line_Item::increment_quantity($line_item, $qty);
-            return $line_item;
-        }
-        return null;
-    }
-
-
-    /**
-     * Increments the line item and all its children's quantity by $qty (but percent line items are unaffected).
-     * Does NOT save or recalculate other line items totals
-     *
-     * @param EE_Line_Item $line_item
-     * @param int          $qty
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function increment_quantity(EE_Line_Item $line_item, int $qty = 1)
-    {
-        if (! $line_item->is_percent()) {
-            $qty += $line_item->quantity();
-            $line_item->set_quantity($qty);
-            $line_item->set_total($line_item->unit_price() * $qty);
-            $line_item->save();
-        }
-        foreach ($line_item->children() as $child) {
-            if ($child->is_sub_line_item()) {
-                EEH_Line_Item::update_quantity($child, $qty);
-            }
-        }
-    }
-
-
-    /**
-     * Decrements the line item and all its children's quantity by $qty (but percent line items are unaffected).
-     * Does NOT save or recalculate other line items totals
-     *
-     * @param EE_Line_Item $line_item
-     * @param int          $qty
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function decrement_quantity(EE_Line_Item $line_item, int $qty = 1)
-    {
-        if (! $line_item->is_percent()) {
-            $qty = $line_item->quantity() - $qty;
-            $qty = max($qty, 0);
-            $line_item->set_quantity($qty);
-            $line_item->set_total($line_item->unit_price() * $qty);
-            $line_item->save();
-        }
-        foreach ($line_item->children() as $child) {
-            if ($child->is_sub_line_item()) {
-                EEH_Line_Item::update_quantity($child, $qty);
-            }
-        }
-    }
-
-
-    /**
-     * Updates the line item and its children's quantities to the specified number.
-     * Does NOT save them or recalculate totals.
-     *
-     * @param EE_Line_Item $line_item
-     * @param int          $new_quantity
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function update_quantity(EE_Line_Item $line_item, int $new_quantity)
-    {
-        if (! $line_item->is_percent()) {
-            $line_item->set_quantity($new_quantity);
-            $line_item->set_total($line_item->unit_price() * $new_quantity);
-            $line_item->save();
-        }
-        foreach ($line_item->children() as $child) {
-            if ($child->is_sub_line_item()) {
-                EEH_Line_Item::update_quantity($child, $new_quantity);
-            }
-        }
-    }
-
-
-    /**
-     * Returns the new line item created by adding a purchase of the ticket
-     *
-     * @param EE_Line_Item $total_line_item of type EEM_Line_Item::type_total
-     * @param EE_Ticket    $ticket
-     * @param int          $qty
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function create_ticket_line_item(
-        EE_Line_Item $total_line_item,
-        EE_Ticket $ticket,
-        int $qty = 1
-    ): EE_Line_Item {
-        $datetimes           = $ticket->datetimes();
-        $first_datetime      = reset($datetimes);
-        $first_datetime_name = esc_html__('Event', 'event_espresso');
-        if ($first_datetime instanceof EE_Datetime && $first_datetime->event() instanceof EE_Event) {
-            $first_datetime_name = $first_datetime->event()->name();
-        }
-        $event = sprintf(_x('(For %1$s)', '(For Event Name)', 'event_espresso'), $first_datetime_name);
-        // get event subtotal line
-        $events_sub_total = self::get_event_line_item_for_ticket($total_line_item, $ticket);
-        $taxes            = $ticket->tax_price_modifiers();
-        // add $ticket to cart
-        $line_item = EE_Line_Item::new_instance(
-            [
-                'LIN_name'       => $ticket->name(),
-                'LIN_desc'       => $ticket->description() !== '' ? $ticket->description() . ' ' . $event : $event,
-                'LIN_unit_price' => $ticket->price(),
-                'LIN_quantity'   => $qty,
-                'LIN_is_taxable' => empty($taxes) && $ticket->taxable(),
-                'LIN_order'      => count($events_sub_total->children()),
-                'LIN_total'      => $ticket->price() * $qty,
-                'LIN_type'       => EEM_Line_Item::type_line_item,
-                'OBJ_ID'         => $ticket->ID(),
-                'OBJ_type'       => EEM_Line_Item::OBJ_TYPE_TICKET,
-            ]
-        );
-        $line_item = apply_filters(
-            'FHEE__EEH_Line_Item__create_ticket_line_item__line_item',
-            $line_item
-        );
-        if (! $line_item instanceof EE_Line_Item) {
-            throw new DomainException(
-                esc_html__('Invalid EE_Line_Item received.', 'event_espresso')
-            );
-        }
-        $events_sub_total->add_child_line_item($line_item);
-        // now add the sub-line items
-        $running_pre_tax_total = 0;
-        $prices                = $ticket->prices();
-        if (empty($prices)) {
-            // WUT?!?! NO PRICES??? Well, just create a default price then.
-            $default_price = EEM_Price::instance()->get_new_price();
-            if ($default_price->amount() !== $ticket->price()) {
-                $default_price->set_amount($ticket->price());
-            }
-            $default_price->save();
-            $ticket->_add_relation_to($default_price, 'Price');
-            $ticket->save();
-            $prices = [$default_price];
-        }
-        foreach ($prices as $price) {
-            $sign = $price->is_discount() ? -1 : 1;
-            $price_amount = $price->amount();
-            if ($price->is_percent()) {
-                $price_total = $running_pre_tax_total * $price_amount / 100;
-                $percent    = $sign * $price_amount;
-                $unit_price = 0;
-            } else {
-                $price_total = $price_amount * $qty;
-                $percent    = 0;
-                $unit_price = $sign * $price_amount;
-            }
-
-            $price_desc = $price->desc();
-            $price_type = $price->type_obj();
-            $price_desc = $price_desc === '' && $price_type instanceof EE_Price_Type
-                ? $price_type->name()
-                : $price_desc;
-
-            $sub_line_item         = EE_Line_Item::new_instance(
-                [
-                    'LIN_name'       => $price->name(),
-                    'LIN_desc'       => $price_desc,
-                    'LIN_is_taxable' => false,
-                    'LIN_order'      => $price->order(),
-                    'LIN_total'      => $price_total,
-                    'LIN_pretax'     => 0,
-                    'LIN_unit_price' => $unit_price,
-                    'LIN_percent'    => $percent,
-                    'LIN_type'       => $price->is_tax()
-                        ? EEM_Line_Item::type_sub_tax
-                        : EEM_Line_Item::type_sub_line_item,
-                    'OBJ_ID'         => $price->ID(),
-                    'OBJ_type'       => EEM_Line_Item::OBJ_TYPE_PRICE,
-                ]
-            );
-            $sub_line_item         = apply_filters(
-                'FHEE__EEH_Line_Item__create_ticket_line_item__sub_line_item',
-                $sub_line_item
-            );
-            $running_pre_tax_total += ! $price->is_tax() ? $sign * $price_total : 0;
-            $line_item->add_child_line_item($sub_line_item);
-        }
-        $line_item->setPretaxTotal($running_pre_tax_total);
-        return $line_item;
-    }
-
-
-    /**
-     * Adds the specified item under the pre-tax-sub-total line item. Automatically
-     * re-calculates the line item totals and updates the related transaction. But
-     * DOES NOT automatically upgrade the transaction's registrations' final prices (which
-     * should probably change because of this).
-     * You should call EE_Registration_Processor::calculate_reg_final_prices_per_line_item()
-     * after using this, to keep the registration final prices in-sync with the transaction's total.
-     *
-     * @param EE_Line_Item $total_line_item
-     * @param EE_Line_Item $item to be added
-     * @param bool         $recalculate_totals
-     * @return boolean
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function add_item(
-        EE_Line_Item $total_line_item,
-        EE_Line_Item $item,
-        bool $recalculate_totals = true
-    ): bool {
-        $pre_tax_subtotal = self::get_pre_tax_subtotal($total_line_item);
-        $success          = $pre_tax_subtotal->add_child_line_item($item);
-        if ($recalculate_totals) {
-            $total_line_item->recalculate_total_including_taxes();
-        }
-        return $success;
-    }
-
-
-    /**
-     * cancels an existing ticket line item,
-     * by decrementing its quantity by 1 and adding a new "type_cancellation" sub-line-item.
-     * ALL totals and subtotals will NEED TO BE UPDATED after performing this action
-     *
-     * @param EE_Line_Item $ticket_line_item
-     * @param int          $qty
-     * @return bool success
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function cancel_ticket_line_item(EE_Line_Item $ticket_line_item, int $qty = 1): bool
-    {
-        // validate incoming line_item
-        if ($ticket_line_item->OBJ_type() !== EEM_Line_Item::OBJ_TYPE_TICKET) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'The supplied line item must have an Object Type of "Ticket", not %1$s.',
-                        'event_espresso'
-                    ),
-                    $ticket_line_item->type()
-                )
-            );
-        }
-        if ($ticket_line_item->quantity() < $qty) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'Can not cancel %1$d ticket(s) because the supplied line item has a quantity of %2$d.',
-                        'event_espresso'
-                    ),
-                    $qty,
-                    $ticket_line_item->quantity()
-                )
-            );
-        }
-        // decrement ticket quantity; don't rely on auto-fixing when recalculating totals to do this
-        $ticket_line_item->set_quantity($ticket_line_item->quantity() - $qty);
-        foreach ($ticket_line_item->children() as $child_line_item) {
-            if (
-                $child_line_item->is_sub_line_item()
-                && ! $child_line_item->is_percent()
-                && ! $child_line_item->is_cancellation()
-            ) {
-                $child_line_item->set_quantity($child_line_item->quantity() - $qty);
-            }
-        }
-        // get cancellation sub line item
-        $cancellation_line_item = EEH_Line_Item::get_descendants_of_type(
-            $ticket_line_item,
-            EEM_Line_Item::type_cancellation
-        );
-        $cancellation_line_item = reset($cancellation_line_item);
-        // verify that this ticket was indeed previously cancelled
-        if ($cancellation_line_item instanceof EE_Line_Item) {
-            // increment cancelled quantity
-            $cancellation_line_item->set_quantity($cancellation_line_item->quantity() + $qty);
-        } else {
-            // create cancellation sub line item
-            $cancellation_line_item = EE_Line_Item::new_instance(
-                [
-                    'LIN_name'       => esc_html__('Cancellation', 'event_espresso'),
-                    'LIN_desc'       => sprintf(
-                        esc_html_x(
-                            'Cancelled %1$s : %2$s',
-                            'Cancelled Ticket Name : 2015-01-01 11:11',
-                            'event_espresso'
-                        ),
-                        $ticket_line_item->name(),
-                        current_time(get_option('date_format') . ' ' . get_option('time_format'))
-                    ),
-                    'LIN_total'      => 0,
-                    'LIN_unit_price' => 0,
-                    'LIN_quantity'   => $qty,
-                    'LIN_is_taxable' => $ticket_line_item->is_taxable(),
-                    'LIN_order'      => count($ticket_line_item->children()),
-                    'LIN_type'       => EEM_Line_Item::type_cancellation,
-                ]
-            );
-            $ticket_line_item->add_child_line_item($cancellation_line_item);
-        }
-        if ($ticket_line_item->save_this_and_descendants() > 0) {
-            // decrement parent line item quantity
-            $event_line_item = $ticket_line_item->parent();
-            if (
-                $event_line_item instanceof EE_Line_Item
-                && $event_line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_EVENT
-            ) {
-                $event_line_item->set_quantity($event_line_item->quantity() - $qty);
-                $event_line_item->save();
-            }
-            EEH_Line_Item::get_grand_total_and_recalculate_everything($ticket_line_item);
-            return true;
-        }
-        return false;
-    }
-
-
-    /**
-     * reinstates (un-cancels?) a previously canceled ticket line item,
-     * by incrementing its quantity by 1, and decrementing its "type_cancellation" sub-line-item.
-     * ALL totals and subtotals will NEED TO BE UPDATED after performing this action
-     *
-     * @param EE_Line_Item $ticket_line_item
-     * @param int          $qty
-     * @return bool success
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function reinstate_canceled_ticket_line_item(EE_Line_Item $ticket_line_item, int $qty = 1): bool
-    {
-        // validate incoming line_item
-        if ($ticket_line_item->OBJ_type() !== EEM_Line_Item::OBJ_TYPE_TICKET) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'The supplied line item must have an Object Type of "Ticket", not %1$s.',
-                        'event_espresso'
-                    ),
-                    $ticket_line_item->type()
-                )
-            );
-        }
-        // get cancellation sub line item
-        $cancellation_line_item = EEH_Line_Item::get_descendants_of_type(
-            $ticket_line_item,
-            EEM_Line_Item::type_cancellation
-        );
-        $cancellation_line_item = reset($cancellation_line_item);
-        // verify that this ticket was indeed previously cancelled
-        if (! $cancellation_line_item instanceof EE_Line_Item) {
-            return false;
-        }
-        if ($cancellation_line_item->quantity() > $qty) {
-            // decrement cancelled quantity
-            $cancellation_line_item->set_quantity($cancellation_line_item->quantity() - $qty);
-        } elseif ($cancellation_line_item->quantity() === $qty) {
-            // decrement cancelled quantity in case anyone still has the object kicking around
-            $cancellation_line_item->set_quantity($cancellation_line_item->quantity() - $qty);
-            // delete because quantity will end up as 0
-            $cancellation_line_item->delete();
-            // and attempt to destroy the object,
-            // even though PHP won't actually destroy it until it needs the memory
-            unset($cancellation_line_item);
-        } else {
-            // what ?!?! negative quantity ?!?!
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'Can not reinstate %1$d cancelled ticket(s) because the cancelled ticket quantity is only %2$d.',
-                        'event_espresso'
-                    ),
-                    $qty,
-                    $cancellation_line_item->quantity()
-                )
-            );
-        }
-        // increment ticket quantity
-        $ticket_line_item->set_quantity($ticket_line_item->quantity() + $qty);
-        if ($ticket_line_item->save_this_and_descendants() > 0) {
-            // increment parent line item quantity
-            $event_line_item = $ticket_line_item->parent();
-            if (
-                $event_line_item instanceof EE_Line_Item
-                && $event_line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_EVENT
-            ) {
-                $event_line_item->set_quantity($event_line_item->quantity() + $qty);
-            }
-            EEH_Line_Item::get_grand_total_and_recalculate_everything($ticket_line_item);
-            return true;
-        }
-        return false;
-    }
-
-
-    /**
-     * calls EEH_Line_Item::find_transaction_grand_total_for_line_item()
-     * then EE_Line_Item::recalculate_total_including_taxes() on the result
-     *
-     * @param EE_Line_Item $line_item
-     * @return float
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function get_grand_total_and_recalculate_everything(EE_Line_Item $line_item): float
-    {
-        $grand_total_line_item = EEH_Line_Item::find_transaction_grand_total_for_line_item($line_item);
-        return $grand_total_line_item->recalculate_total_including_taxes();
-    }
-
-
-    /**
-     * Gets the line item which contains the subtotal of all the items
-     *
-     * @param EE_Line_Item $total_line_item of type EEM_Line_Item::type_total
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function get_pre_tax_subtotal(EE_Line_Item $total_line_item): EE_Line_Item
-    {
-        $pre_tax_subtotal = $total_line_item->get_child_line_item('pre-tax-subtotal');
-        return $pre_tax_subtotal instanceof EE_Line_Item
-            ? $pre_tax_subtotal
-            : self::create_pre_tax_subtotal($total_line_item);
-    }
-
-
-    /**
-     * Gets the line item for the taxes subtotal
-     *
-     * @param EE_Line_Item $total_line_item of type EEM_Line_Item::type_total
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function get_taxes_subtotal(EE_Line_Item $total_line_item): EE_Line_Item
-    {
-        $taxes = $total_line_item->get_child_line_item('taxes');
-        return $taxes ?: self::create_taxes_subtotal($total_line_item);
-    }
-
-
-    /**
-     * sets the TXN ID on an EE_Line_Item if passed a valid EE_Transaction object
-     *
-     * @param EE_Line_Item        $line_item
-     * @param EE_Transaction|null $transaction
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function set_TXN_ID(EE_Line_Item $line_item, ?EE_Transaction $transaction = null)
-    {
-        if ($transaction) {
-            /** @type EEM_Transaction $EEM_Transaction */
-            $EEM_Transaction = EE_Registry::instance()->load_model('Transaction');
-            $TXN_ID          = $EEM_Transaction->ensure_is_ID($transaction);
-            $line_item->set_TXN_ID($TXN_ID);
-        }
-    }
-
-
-    /**
-     * Creates a new default total line item for the transaction,
-     * and its tickets subtotal and taxes subtotal line items (and adds the
-     * existing taxes as children of the taxes subtotal line item)
-     *
-     * @param EE_Transaction|null $transaction
-     * @return EE_Line_Item of type total
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function create_total_line_item(?EE_Transaction $transaction = null): EE_Line_Item
-    {
-        $total_line_item = EE_Line_Item::new_instance(
-            [
-                'LIN_code' => 'total',
-                'LIN_name' => esc_html__('Grand Total', 'event_espresso'),
-                'LIN_type' => EEM_Line_Item::type_total,
-                'OBJ_type' => EEM_Line_Item::OBJ_TYPE_TRANSACTION,
-            ]
-        );
-        $total_line_item = apply_filters(
-            'FHEE__EEH_Line_Item__create_total_line_item__total_line_item',
-            $total_line_item
-        );
-        self::set_TXN_ID($total_line_item, $transaction);
-        self::create_pre_tax_subtotal($total_line_item, $transaction);
-        self::create_taxes_subtotal($total_line_item, $transaction);
-        return $total_line_item;
-    }
-
-
-    /**
-     * Creates a default items subtotal line item
-     *
-     * @param EE_Line_Item        $total_line_item
-     * @param EE_Transaction|null $transaction
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    protected static function create_pre_tax_subtotal(
-        EE_Line_Item $total_line_item,
-        ?EE_Transaction $transaction = null
-    ): EE_Line_Item {
-        $pre_tax_line_item = EE_Line_Item::new_instance(
-            [
-                'LIN_code' => 'pre-tax-subtotal',
-                'LIN_name' => esc_html__('Pre-Tax Subtotal', 'event_espresso'),
-                'LIN_type' => EEM_Line_Item::type_sub_total,
-            ]
-        );
-        $pre_tax_line_item = apply_filters(
-            'FHEE__EEH_Line_Item__create_pre_tax_subtotal__pre_tax_line_item',
-            $pre_tax_line_item
-        );
-        self::set_TXN_ID($pre_tax_line_item, $transaction);
-        $total_line_item->add_child_line_item($pre_tax_line_item);
-        self::create_event_subtotal($pre_tax_line_item, $transaction);
-        return $pre_tax_line_item;
-    }
-
-
-    /**
-     * Creates a line item for the taxes subtotal and finds all the tax prices
-     * and applies taxes to it
-     *
-     * @param EE_Line_Item        $total_line_item of type EEM_Line_Item::type_total
-     * @param EE_Transaction|null $transaction
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    protected static function create_taxes_subtotal(
-        EE_Line_Item $total_line_item,
-        ?EE_Transaction $transaction = null
-    ): EE_Line_Item {
-        $tax_line_item = EE_Line_Item::new_instance(
-            [
-                'LIN_code'  => 'taxes',
-                'LIN_name'  => esc_html__('Taxes', 'event_espresso'),
-                'LIN_type'  => EEM_Line_Item::type_tax_sub_total,
-                'LIN_order' => 1000,// this should always come last
-            ]
-        );
-        $tax_line_item = apply_filters(
-            'FHEE__EEH_Line_Item__create_taxes_subtotal__tax_line_item',
-            $tax_line_item
-        );
-        self::set_TXN_ID($tax_line_item, $transaction);
-        $total_line_item->add_child_line_item($tax_line_item);
-        // and lastly, add the actual taxes
-        self::apply_taxes($total_line_item);
-        return $tax_line_item;
-    }
-
-
-    /**
-     * Creates a default items subtotal line item
-     *
-     * @param EE_Line_Item        $pre_tax_line_item
-     * @param EE_Transaction|null $transaction
-     * @param EE_Event|null       $event
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function create_event_subtotal(
-        EE_Line_Item $pre_tax_line_item,
-        ?EE_Transaction $transaction = null,
-        ?EE_Event $event = null
-    ): EE_Line_Item {
-        // first check if this line item already exists
-        $event_line_item = EEM_Line_Item::instance()->get_one(
-            [
-                [
-                    'LIN_type' => EEM_Line_Item::type_sub_total,
-                    'OBJ_type' => EEM_Line_Item::OBJ_TYPE_EVENT,
-                    'OBJ_ID'   => $event instanceof EE_Event ? $event->ID() : 0,
-                    'TXN_ID'   => $transaction instanceof EE_Transaction ? $transaction->ID() : 0,
-                ],
-            ]
-        );
-        if ($event_line_item instanceof EE_Line_Item) {
-            return $event_line_item;
-        }
-
-        $event_line_item = EE_Line_Item::new_instance(
-            [
-                'LIN_code' => self::get_event_code($event),
-                'LIN_name' => self::get_event_name($event),
-                'LIN_desc' => self::get_event_desc($event),
-                'LIN_type' => EEM_Line_Item::type_sub_total,
-                'OBJ_type' => EEM_Line_Item::OBJ_TYPE_EVENT,
-                'OBJ_ID'   => $event instanceof EE_Event ? $event->ID() : 0,
-            ]
-        );
-        $event_line_item = apply_filters(
-            'FHEE__EEH_Line_Item__create_event_subtotal__event_line_item',
-            $event_line_item
-        );
-        self::set_TXN_ID($event_line_item, $transaction);
-        $pre_tax_line_item->add_child_line_item($event_line_item);
-        return $event_line_item;
-    }
-
-
-    /**
-     * Gets what the event ticket's code SHOULD be
-     *
-     * @param EE_Event|null $event
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function get_event_code(?EE_Event $event = null): string
-    {
-        return 'event-' . ($event instanceof EE_Event ? $event->ID() : '0');
-    }
-
-
-    /**
-     * Gets the event name
-     *
-     * @param EE_Event|null $event
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function get_event_name(?EE_Event $event = null): string
-    {
-        return $event instanceof EE_Event
-            ? mb_substr($event->name(), 0, 245)
-            : esc_html__('Event', 'event_espresso');
-    }
-
-
-    /**
-     * Gets the event excerpt
-     *
-     * @param EE_Event|null $event
-     * @return string
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function get_event_desc(?EE_Event $event = null): string
-    {
-        return $event instanceof EE_Event ? $event->short_description() : '';
-    }
-
-
-    /**
-     * Given the grand total line item and a ticket, finds the event sub-total
-     * line item the ticket's purchase should be added onto
-     *
-     * @access public
-     * @param EE_Line_Item $grand_total the grand total line item
-     * @param EE_Ticket    $ticket
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function get_event_line_item_for_ticket(EE_Line_Item $grand_total, EE_Ticket $ticket): EE_Line_Item
-    {
-        $first_datetime = $ticket->first_datetime();
-        if (! $first_datetime instanceof EE_Datetime) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__('The supplied ticket (ID %d) has no datetimes', 'event_espresso'),
-                    $ticket->ID()
-                )
-            );
-        }
-        $event = $first_datetime->event();
-        if (! $event instanceof EE_Event) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'The supplied ticket (ID %d) has no event data associated with it.',
-                        'event_espresso'
-                    ),
-                    $ticket->ID()
-                )
-            );
-        }
-        $events_sub_total = EEH_Line_Item::get_event_line_item($grand_total, $event);
-        if (! $events_sub_total instanceof EE_Line_Item) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'There is no events sub-total for ticket %s on total line item %d',
-                        'event_espresso'
-                    ),
-                    $ticket->ID(),
-                    $grand_total->ID()
-                )
-            );
-        }
-        return $events_sub_total;
-    }
-
-
-    /**
-     * Gets the event line item
-     *
-     * @param EE_Line_Item  $total_line_item
-     * @param EE_Event|null $event
-     * @return EE_Line_Item for the event subtotal which is a child of $grand_total
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function get_event_line_item(EE_Line_Item $total_line_item, ?EE_Event $event = null): ?EE_Line_Item
-    {
-        /** @type EE_Event $event */
-        $event           = EEM_Event::instance()->ensure_is_obj($event, true);
-        $event_line_item = null;
-        $event_line_items = EEH_Line_Item::get_event_subtotals($total_line_item);
-        foreach ($event_line_items as $event_line_item) {
-            // default event subtotal, we should only ever find this the first time this method is called
-            $OBJ_ID = $event_line_item->OBJ_ID();
-            if ($OBJ_ID === $event->ID()) {
-                // found existing line item for this event in the cart, so break out of loop and use this one
-                break;
-            }
-            if (! $OBJ_ID) {
-                // let's use this! but first... set the event details
-                EEH_Line_Item::set_event_subtotal_details($event_line_item, $event);
-                break;
-            }
-        }
-        if (! $event_line_item instanceof EE_Line_Item) {
-            // there is no event sub-total yet, so add it
-            $pre_tax_subtotal = EEH_Line_Item::get_pre_tax_subtotal($total_line_item);
-            // a new "event" subtotal SHOULD have been created
-            $event_subtotals = EEH_Line_Item::get_event_subtotals($total_line_item);
-            $event_line_item = reset($event_subtotals);
-            // but in ccase one wasn't created for some reason...
-            if (! $event_line_item instanceof EE_Line_Item) {
-                // create a new "event" subtotal
-                $txn = $total_line_item->transaction();
-                $event_line_item = EEH_Line_Item::create_event_subtotal($pre_tax_subtotal, $txn, $event);
-            }
-            // and set the event details
-            EEH_Line_Item::set_event_subtotal_details($event_line_item, $event);
-        }
-        return $event_line_item;
-    }
-
-
-    /**
-     * Creates a default items subtotal line item
-     *
-     * @param EE_Line_Item        $event_line_item
-     * @param EE_Event|null       $event
-     * @param EE_Transaction|null $transaction
-     * @return void
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function set_event_subtotal_details(
-        EE_Line_Item $event_line_item,
-        EE_Event $event = null,
-        ?EE_Transaction $transaction = null
-    ) {
-        if ($event instanceof EE_Event) {
-            $event_line_item->set_code(self::get_event_code($event));
-            $event_line_item->set_name(self::get_event_name($event));
-            $event_line_item->set_desc(self::get_event_desc($event));
-            $event_line_item->set_OBJ_ID($event->ID());
-        }
-        self::set_TXN_ID($event_line_item, $transaction);
-    }
-
-
-    /**
-     * Finds what taxes should apply, adds them as tax line items under the taxes sub-total,
-     * and recalculates the taxes sub-total and the grand total. Resets the taxes, so
-     * any old taxes are removed
-     *
-     * @param EE_Line_Item $total_line_item of type EEM_Line_Item::type_total
-     * @param bool         $update_txn_status
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @throws RuntimeException
-     */
-    public static function apply_taxes(EE_Line_Item $total_line_item, bool $update_txn_status = false): bool
-    {
-        $total_line_item       = EEH_Line_Item::find_transaction_grand_total_for_line_item($total_line_item);
-        $taxes_line_item       = self::get_taxes_subtotal($total_line_item);
-        $existing_global_taxes = $taxes_line_item->tax_descendants();
-        $updates               = false;
-        // loop thru taxes
-        $global_taxes = EEH_Line_Item::getGlobalTaxes();
-        foreach ($global_taxes as $order => $taxes) {
-            foreach ($taxes as $tax) {
-                if ($tax instanceof EE_Price) {
-                    $found = false;
-                    // check if this is already an existing tax
-                    foreach ($existing_global_taxes as $existing_global_tax) {
-                        if ($tax->ID() === $existing_global_tax->OBJ_ID()) {
-                            // maybe update the tax rate in case it has changed
-                            if ($existing_global_tax->percent() !== $tax->amount()) {
-                                $existing_global_tax->set_percent($tax->amount());
-                                $existing_global_tax->save();
-                                $updates = true;
-                            }
-                            $found = true;
-                            break;
-                        }
-                    }
-                    if (! $found) {
-                        // add a new line item for this global tax
-                        $tax_line_item = apply_filters(
-                            'FHEE__EEH_Line_Item__apply_taxes__tax_line_item',
-                            EE_Line_Item::new_instance(
-                                [
-                                    'LIN_name'       => $tax->name(),
-                                    'LIN_desc'       => $tax->desc(),
-                                    'LIN_percent'    => $tax->amount(),
-                                    'LIN_is_taxable' => false,
-                                    'LIN_order'      => $order,
-                                    'LIN_total'      => 0,
-                                    'LIN_type'       => EEM_Line_Item::type_tax,
-                                    'OBJ_type'       => EEM_Line_Item::OBJ_TYPE_PRICE,
-                                    'OBJ_ID'         => $tax->ID(),
-                                ]
-                            )
-                        );
-                        $updates       = $taxes_line_item->add_child_line_item($tax_line_item) ? true : $updates;
-                    }
-                }
-            }
-        }
-        // only recalculate totals if something changed
-        if ($updates || $update_txn_status) {
-            $total_line_item->recalculate_total_including_taxes($update_txn_status);
-            return true;
-        }
-        return false;
-    }
-
-
-    /**
-     * Ensures that taxes have been applied to the order, if not applies them.
-     * Returns the total amount of tax
-     *
-     * @param EE_Line_Item|null $total_line_item of type EEM_Line_Item::type_total
-     * @return float
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function ensure_taxes_applied(?EE_Line_Item $total_line_item): float
-    {
-        $taxes_subtotal = self::get_taxes_subtotal($total_line_item);
-        if (! $taxes_subtotal->children()) {
-            self::apply_taxes($total_line_item);
-        }
-        return $taxes_subtotal->total();
-    }
-
-
-    /**
-     * Deletes ALL children of the passed line item
-     *
-     * @param EE_Line_Item $parent_line_item
-     * @return bool
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function delete_all_child_items(EE_Line_Item $parent_line_item)
-    {
-        $deleted = 0;
-        foreach ($parent_line_item->children() as $child_line_item) {
-            if ($child_line_item instanceof EE_Line_Item) {
-                $deleted += EEH_Line_Item::delete_all_child_items($child_line_item);
-                if ($child_line_item->ID()) {
-                    $child_line_item->delete();
-                    unset($child_line_item);
-                } else {
-                    $parent_line_item->delete_child_line_item($child_line_item->code());
-                }
-                $deleted++;
-            }
-        }
-        return $deleted;
-    }
-
-
-    /**
-     * Deletes the line items as indicated by the line item code(s) provided,
-     * regardless of where they're found in the line item tree. Automatically
-     * re-calculates the line item totals and updates the related transaction. But
-     * DOES NOT automatically upgrade the transaction's registrations' final prices (which
-     * should probably change because of this).
-     * You should call EE_Registration_Processor::calculate_reg_final_prices_per_line_item()
-     * after using this, to keep the registration final prices in-sync with the transaction's total.
-     *
-     * @param EE_Line_Item      $total_line_item of type EEM_Line_Item::type_total
-     * @param array|bool|string $line_item_codes
-     * @return int number of items successfully removed
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function delete_items(EE_Line_Item $total_line_item, $line_item_codes = false)
-    {
-        if ($total_line_item->type() !== EEM_Line_Item::type_total) {
-            EE_Error::doing_it_wrong(
-                'EEH_Line_Item::delete_items',
-                esc_html__(
-                    'This static method should only be called with a TOTAL line item, otherwise we won\'t recalculate the totals correctly',
-                    'event_espresso'
-                ),
-                '4.6.18'
-            );
-        }
-
-        // check if only a single line_item_id was passed
-        if (! empty($line_item_codes) && ! is_array($line_item_codes)) {
-            // place single line_item_id in an array to appear as multiple line_item_ids
-            $line_item_codes = [$line_item_codes];
-        }
-        $removals = 0;
-        // cycle thru line_item_ids
-        foreach ($line_item_codes as $line_item_id) {
-            $removals += $total_line_item->delete_child_line_item($line_item_id);
-        }
-
-        if ($removals > 0) {
-            $total_line_item->recalculate_taxes_and_tax_total();
-            return $removals;
-        } else {
-            return false;
-        }
-    }
-
-
-    /**
-     * Overwrites the previous tax by clearing out the old taxes, and creates a new
-     * tax and updates the total line item accordingly
-     *
-     * @param EE_Line_Item $total_line_item
-     * @param float        $amount
-     * @param string       $name
-     * @param string       $description
-     * @param string       $code
-     * @param boolean      $add_to_existing_line_item
-     *                          if true, and a duplicate line item with the same code is found,
-     *                          $amount will be added onto it; otherwise will simply set the taxes to match $amount
-     * @return EE_Line_Item the new tax line item created
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function set_total_tax_to(
-        EE_Line_Item $total_line_item,
-        float $amount,
-        string $name = '',
-        string $description = '',
-        string $code = '',
-        bool $add_to_existing_line_item = false
-    ): EE_Line_Item {
-        $tax_subtotal  = self::get_taxes_subtotal($total_line_item);
-        $taxable_total = $total_line_item->taxable_total();
-
-        if ($add_to_existing_line_item) {
-            $new_tax = $tax_subtotal->get_child_line_item($code);
-            EEM_Line_Item::instance()->delete(
-                [['LIN_code' => ['!=', $code], 'LIN_parent' => $tax_subtotal->ID()]]
-            );
-        } else {
-            $new_tax = null;
-            $tax_subtotal->delete_children_line_items();
-        }
-        if ($new_tax) {
-            $new_tax->set_total($new_tax->total() + $amount);
-            $new_tax->set_percent($taxable_total ? $new_tax->total() / $taxable_total * 100 : 0);
-        } else {
-            // no existing tax item. Create it
-            $new_tax = EE_Line_Item::new_instance(
-                [
-                    'TXN_ID'      => $total_line_item->TXN_ID(),
-                    'LIN_name'    => $name ?: esc_html__('Tax', 'event_espresso'),
-                    'LIN_desc'    => $description ?: '',
-                    'LIN_percent' => $taxable_total ? ($amount / $taxable_total * 100) : 0,
-                    'LIN_total'   => $amount,
-                    'LIN_parent'  => $tax_subtotal->ID(),
-                    'LIN_type'    => EEM_Line_Item::type_tax,
-                    'LIN_code'    => $code,
-                ]
-            );
-        }
-
-        $new_tax = apply_filters(
-            'FHEE__EEH_Line_Item__set_total_tax_to__new_tax_subtotal',
-            $new_tax,
-            $total_line_item
-        );
-        $new_tax->save();
-        $tax_subtotal->set_total($new_tax->total());
-        $tax_subtotal->save();
-        $total_line_item->recalculate_total_including_taxes();
-        return $new_tax;
-    }
-
-
-    /**
-     * Makes all the line items which are children of $line_item taxable (or not).
-     * Does NOT save the line items
-     *
-     * @param EE_Line_Item $line_item
-     * @param boolean      $taxable
-     * @param string|null  $code_substring_for_whitelist if this string is part of the line item's code
-     *                                                   it will be whitelisted (ie, except from becoming taxable)
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function set_line_items_taxable(
-        EE_Line_Item $line_item,
-        bool $taxable = true,
-        ?string $code_substring_for_whitelist = null
-    ) {
-        $whitelisted = false;
-        if ($code_substring_for_whitelist !== null) {
-            $whitelisted = strpos($line_item->code(), $code_substring_for_whitelist) !== false;
-        }
-        if (! $whitelisted && $line_item->is_line_item()) {
-            $line_item->set_is_taxable($taxable);
-        }
-        foreach ($line_item->children() as $child_line_item) {
-            EEH_Line_Item::set_line_items_taxable(
-                $child_line_item,
-                $taxable,
-                $code_substring_for_whitelist
-            );
-        }
-    }
-
-
-    /**
-     * Gets all descendants that are event subtotals
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @uses  EEH_Line_Item::get_subtotals_of_object_type()
-     */
-    public static function get_event_subtotals(EE_Line_Item $parent_line_item): array
-    {
-        return self::get_subtotals_of_object_type($parent_line_item, EEM_Line_Item::OBJ_TYPE_EVENT);
-    }
-
-
-    /**
-     * Gets all descendants subtotals that match the supplied object type
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @param string       $obj_type
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @uses  EEH_Line_Item::_get_descendants_by_type_and_object_type()
-     */
-    public static function get_subtotals_of_object_type(EE_Line_Item $parent_line_item, string $obj_type = ''): array
-    {
-        return self::_get_descendants_by_type_and_object_type(
-            $parent_line_item,
-            EEM_Line_Item::type_sub_total,
-            $obj_type
-        );
-    }
-
-
-    /**
-     * Gets all descendants that are tickets
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @uses  EEH_Line_Item::get_line_items_of_object_type()
-     */
-    public static function get_ticket_line_items(EE_Line_Item $parent_line_item): array
-    {
-        return self::get_line_items_of_object_type(
-            $parent_line_item,
-            EEM_Line_Item::OBJ_TYPE_TICKET
-        );
-    }
-
-
-    /**
-     * Gets all descendants subtotals that match the supplied object type
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @param string       $obj_type
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @uses  EEH_Line_Item::_get_descendants_by_type_and_object_type()
-     */
-    public static function get_line_items_of_object_type(EE_Line_Item $parent_line_item, string $obj_type = ''): array
-    {
-        return self::_get_descendants_by_type_and_object_type(
-            $parent_line_item,
-            EEM_Line_Item::type_line_item,
-            $obj_type
-        );
-    }
-
-
-    /**
-     * Gets all the descendants (ie, children or children of children etc) that are of the type 'tax'
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @uses  EEH_Line_Item::get_descendants_of_type()
-     */
-    public static function get_tax_descendants(EE_Line_Item $parent_line_item): array
-    {
-        return EEH_Line_Item::get_descendants_of_type(
-            $parent_line_item,
-            EEM_Line_Item::type_tax
-        );
-    }
-
-
-    /**
-     * Gets all the real items purchased which are children of this item
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @uses  EEH_Line_Item::get_descendants_of_type()
-     */
-    public static function get_line_item_descendants(EE_Line_Item $parent_line_item): array
-    {
-        return EEH_Line_Item::get_descendants_of_type(
-            $parent_line_item,
-            EEM_Line_Item::type_line_item
-        );
-    }
-
-
-    /**
-     * Gets all descendants of supplied line item that match the supplied line item type
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @param string       $line_item_type   one of the EEM_Line_Item constants
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @uses  EEH_Line_Item::_get_descendants_by_type_and_object_type()
-     */
-    public static function get_descendants_of_type(EE_Line_Item $parent_line_item, string $line_item_type): array
-    {
-        return self::_get_descendants_by_type_and_object_type(
-            $parent_line_item,
-            $line_item_type
-        );
-    }
-
-
-    /**
-     * Gets all descendants of supplied line item that match the supplied line item type and possibly the object type
-     * as well
-     *
-     * @param EE_Line_Item $parent_line_item  - the line item to find descendants of
-     * @param string       $line_item_type    one of the EEM_Line_Item constants
-     * @param string|null  $obj_type          object model class name (minus prefix) or NULL to ignore object type when
-     *                                        searching
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    protected static function _get_descendants_by_type_and_object_type(
-        EE_Line_Item $parent_line_item,
-        string $line_item_type,
-        ?string $obj_type = null
-    ): array {
-        $objects = [];
-        foreach ($parent_line_item->children() as $child_line_item) {
-            if ($child_line_item instanceof EE_Line_Item) {
-                if (
-                    $child_line_item->type() === $line_item_type
-                    && (
-                        $child_line_item->OBJ_type() === $obj_type || $obj_type === null
-                    )
-                ) {
-                    $objects[] = $child_line_item;
-                } else {
-                    // go-through-all-its children looking for more matches
-                    $objects = array_merge(
-                        $objects,
-                        self::_get_descendants_by_type_and_object_type(
-                            $child_line_item,
-                            $line_item_type,
-                            $obj_type
-                        )
-                    );
-                }
-            }
-        }
-        return $objects;
-    }
-
-
-    /**
-     * Gets all descendants subtotals that match the supplied object type
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @param string       $OBJ_type         object type (like Event)
-     * @param array        $OBJ_IDs          array of OBJ_IDs
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @uses  EEH_Line_Item::_get_descendants_by_type_and_object_type()
-     */
-    public static function get_line_items_by_object_type_and_IDs(
-        EE_Line_Item $parent_line_item,
-        string $OBJ_type = '',
-        array $OBJ_IDs = []
-    ): array {
-        return self::_get_descendants_by_object_type_and_object_ID(
-            $parent_line_item,
-            $OBJ_type,
-            $OBJ_IDs
-        );
-    }
-
-
-    /**
-     * Gets all descendants of supplied line item that match the supplied line item type and possibly the object type
-     * as well
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @param string       $OBJ_type         object type (like Event)
-     * @param array        $OBJ_IDs          array of OBJ_IDs
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    protected static function _get_descendants_by_object_type_and_object_ID(
-        EE_Line_Item $parent_line_item,
-        string $OBJ_type,
-        array $OBJ_IDs
-    ): array {
-        $objects = [];
-        foreach ($parent_line_item->children() as $child_line_item) {
-            if ($child_line_item instanceof EE_Line_Item) {
-                if (
-                    $child_line_item->OBJ_type() === $OBJ_type
-                    && in_array($child_line_item->OBJ_ID(), $OBJ_IDs)
-                ) {
-                    $objects[] = $child_line_item;
-                } else {
-                    // go-through-all-its children looking for more matches
-                    $objects = array_merge(
-                        $objects,
-                        self::_get_descendants_by_object_type_and_object_ID(
-                            $child_line_item,
-                            $OBJ_type,
-                            $OBJ_IDs
-                        )
-                    );
-                }
-            }
-        }
-        return $objects;
-    }
-
-
-    /**
-     * Uses a breadth-first-search in order to find the nearest descendant of
-     * the specified type and returns it, else NULL
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @param string       $type             like one of the EEM_Line_Item::type_*
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @uses  EEH_Line_Item::_get_nearest_descendant()
-     */
-    public static function get_nearest_descendant_of_type(EE_Line_Item $parent_line_item, string $type): ?EE_Line_Item
-    {
-        return self::_get_nearest_descendant($parent_line_item, 'LIN_type', $type);
-    }
-
-
-    /**
-     * Uses a breadth-first-search in order to find the nearest descendant
-     * having the specified LIN_code and returns it, else NULL
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @param string       $code             any value used for LIN_code
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @uses  EEH_Line_Item::_get_nearest_descendant()
-     */
-    public static function get_nearest_descendant_having_code(
-        EE_Line_Item $parent_line_item,
-        string $code
-    ): ?EE_Line_Item {
-        return self::_get_nearest_descendant($parent_line_item, 'LIN_code', $code);
-    }
-
-
-    /**
-     * Uses a breadth-first-search in order to find the nearest descendant
-     * having the specified LIN_code and returns it, else NULL
-     *
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @param string       $search_field     name of EE_Line_Item property
-     * @param mixed        $value            any value stored in $search_field
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    protected static function _get_nearest_descendant(
-        EE_Line_Item $parent_line_item,
-        string $search_field,
-        $value
-    ): ?EE_Line_Item {
-        foreach ($parent_line_item->children() as $child) {
-            if ($child->get($search_field) == $value) {
-                return $child;
-            }
-        }
-        foreach ($parent_line_item->children() as $child) {
-            $descendant_found = self::_get_nearest_descendant(
-                $child,
-                $search_field,
-                $value
-            );
-            if ($descendant_found) {
-                return $descendant_found;
-            }
-        }
-        return null;
-    }
-
-
-    /**
-     * if passed line item has a TXN ID, uses that to jump directly to the grand total line item for the transaction,
-     * else recursively walks up the line item tree until a parent of type total is found,
-     *
-     * @param EE_Line_Item $line_item
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function find_transaction_grand_total_for_line_item(EE_Line_Item $line_item): EE_Line_Item
-    {
-        if ($line_item->is_total()) {
-            return $line_item;
-        }
-        if ($line_item->TXN_ID()) {
-            $total_line_item = $line_item->transaction()->total_line_item(false);
-            if ($total_line_item instanceof EE_Line_Item) {
-                return $total_line_item;
-            }
-        } else {
-            $line_item_parent = $line_item->parent();
-            if ($line_item_parent instanceof EE_Line_Item) {
-                if ($line_item_parent->is_total()) {
-                    return $line_item_parent;
-                }
-                return EEH_Line_Item::find_transaction_grand_total_for_line_item($line_item_parent);
-            }
-        }
-        throw new EE_Error(
-            sprintf(
-                esc_html__(
-                    'A valid grand total for line item %1$d was not found.',
-                    'event_espresso'
-                ),
-                $line_item->ID()
-            )
-        );
-    }
-
-
-    /**
-     * Prints out a representation of the line item tree
-     *
-     * @param EE_Line_Item $line_item
-     * @param int          $indentation
-     * @param bool         $top_level
-     * @return void
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public static function visualize(EE_Line_Item $line_item, int $indentation = 0, bool $top_level = true)
-    {
-        if (! defined('WP_DEBUG') || ! WP_DEBUG) {
-            return;
-        }
-        $testing  = defined('EE_TESTS_DIR');
-        $new_line = $testing ? "\n" : '<br />';
-        if ($top_level && ! $testing) {
-            echo '<div style="position: relative; z-index: 9999; margin: 2rem;">';
-            echo '<pre style="padding: 2rem 3rem; color: #00CCFF; background: #363636;">';
-        }
-        if ($top_level || $indentation) {
-            // echo $top_level ? "$new_line$new_line" : $new_line;
-            echo $new_line;
-        }
-        echo str_repeat('. ', $indentation);
-        $breakdown = '';
-        if ($line_item->is_line_item() || $line_item->is_sub_line_item() || $line_item->isTax()) {
-            if ($line_item->is_percent()) {
-                $breakdown = "{$line_item->percent()}%";
-            } else {
-                $breakdown = "\${$line_item->unit_price()} x {$line_item->quantity()}";
-            }
-        }
-        echo wp_kses($line_item->name(), AllowedTags::getAllowedTags());
-        echo " [ ID:{$line_item->ID()} · qty:{$line_item->quantity()} ] {$line_item->type()}";
-        echo " · \${$line_item->total()} · \${$line_item->pretaxTotal()}";
-        if ($breakdown) {
-            echo " ( $breakdown )";
-        }
-        if ($line_item->is_taxable()) {
-            echo '  * taxable';
-        }
-        $children = $line_item->children();
-        if ($children) {
-            foreach ($children as $child) {
-                self::visualize($child, $indentation + 1, false);
-            }
-        }
-        if ($top_level) {
-            echo $testing ? $new_line : "$new_line</pre></div>$new_line";
-        }
-    }
-
-
-    /**
-     * Calculates the registration's final price, taking into account that they
-     * need to not only help pay for their OWN ticket, but also any transaction-wide surcharges and taxes,
-     * and receive a portion of any transaction-wide discounts.
-     * eg1, if I buy a $1 ticket and brent buys a $9 ticket, and we receive a $5 discount
-     * then I'll get 1/10 of that $5 discount, which is $0.50, and brent will get
-     * 9/10ths of that $5 discount, which is $4.50. So my final price should be $0.50
-     * and brent's final price should be $5.50.
-     * In order to do this, we basically need to traverse the line item tree calculating
-     * the running totals (just as if we were recalculating the total), but when we identify
-     * regular line items, we need to keep track of their share of the grand total.
-     * Also, we need to keep track of the TAXABLE total for each ticket purchase, so
-     * we can know how to apply taxes to it. (Note: "taxable total" does not equal the "pretax total"
-     * when there are non-taxable items; otherwise they would be the same)
-     *
-     * @param EE_Line_Item $line_item
-     * @param array        $billable_ticket_quantities          array of EE_Ticket IDs and their corresponding quantity
-     *                                                          that can be included in price calculations at this
-     *                                                          moment
-     * @return array        keys are line items for tickets IDs and values are their share of the running total,
-     *                                                          plus the key 'total', and 'taxable' which also has keys
-     *                                                          of all the ticket IDs. Eg array(
-     *                                                          12 => 4.3
-     *                                                          23 => 8.0
-     *                                                          'total' => 16.6,
-     *                                                          'taxable' => array(
-     *                                                          12 => 10,
-     *                                                          23 => 4
-     *                                                          ).
-     *                                                          So to find which registrations have which final price,
-     *                                                          we need to find which line item is theirs, which can be
-     *                                                          done with
-     *                                                          `EEM_Line_Item::instance()->get_line_item_for_registration(
-     *                                                          $registration );`
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function calculate_reg_final_prices_per_line_item(
-        EE_Line_Item $line_item,
-        array $billable_ticket_quantities = []
-    ): array {
-        $running_totals = [
-            'total'   => 0,
-            'taxable' => ['total' => 0],
-        ];
-        foreach ($line_item->children() as $child_line_item) {
-            switch ($child_line_item->type()) {
-                case EEM_Line_Item::type_sub_total:
-                    $running_totals_from_subtotal = EEH_Line_Item::calculate_reg_final_prices_per_line_item(
-                        $child_line_item,
-                        $billable_ticket_quantities
-                    );
-                    // combine arrays but preserve numeric keys
-                    $running_totals                     = array_replace_recursive(
-                        $running_totals_from_subtotal,
-                        $running_totals
-                    );
-                    $running_totals['total']            += $running_totals_from_subtotal['total'];
-                    $running_totals['taxable']['total'] += $running_totals_from_subtotal['taxable']['total'];
-                    break;
-
-                case EEM_Line_Item::type_tax_sub_total:
-                    // find how much the taxes percentage is
-                    if ($child_line_item->percent() !== 0.0) {
-                        $tax_percent_decimal = $child_line_item->percent() / 100;
-                    } else {
-                        $tax_percent_decimal = EE_Taxes::get_total_taxes_percentage() / 100;
-                    }
-                    // and apply to all the taxable totals, and add to the pretax totals
-                    foreach ($running_totals as $line_item_id => $this_running_total) {
-                        // "total" and "taxable" array key is an exception
-                        if ($line_item_id === 'taxable') {
-                            continue;
-                        }
-                        $taxable_total                   = $running_totals['taxable'][ $line_item_id ];
-                        $running_totals[ $line_item_id ] += ($taxable_total * $tax_percent_decimal);
-                    }
-                    break;
-
-                case EEM_Line_Item::type_line_item:
-                    // ticket line items or ????
-                    if ($child_line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET) {
-                        // kk it's a ticket
-                        if (isset($running_totals[ $child_line_item->ID() ])) {
-                            // huh? that shouldn't happen.
-                            $running_totals['total'] += $child_line_item->total();
-                        } else {
-                            // it's not in our running totals yet. great.
-                            if ($child_line_item->is_taxable()) {
-                                $taxable_amount = $child_line_item->unit_price();
-                            } else {
-                                $taxable_amount = 0;
-                            }
-                            // are we only calculating totals for some tickets?
-                            if (isset($billable_ticket_quantities[ $child_line_item->OBJ_ID() ])) {
-                                $quantity = $billable_ticket_quantities[ $child_line_item->OBJ_ID() ];
-
-                                $running_totals[ $child_line_item->ID() ]            = $quantity
-                                    ? $child_line_item->unit_price()
-                                    : 0;
-                                $running_totals['taxable'][ $child_line_item->ID() ] = $quantity
-                                    ? $taxable_amount
-                                    : 0;
-                            } else {
-                                $quantity                                            = $child_line_item->quantity();
-                                $running_totals[ $child_line_item->ID() ]            = $child_line_item->unit_price();
-                                $running_totals['taxable'][ $child_line_item->ID() ] = $taxable_amount;
-                            }
-                            $running_totals['taxable']['total'] += $taxable_amount * $quantity;
-                            $running_totals['total']            += $child_line_item->unit_price() * $quantity;
-                        }
-                    } else {
-                        // it's some other type of item added to the cart
-                        // it should affect the running totals
-                        // basically we want to convert it into a PERCENT modifier. Because
-                        // more clearly affect all registration's final price equally
-                        $line_items_percent_of_running_total = $running_totals['total'] > 0
-                            ? ($child_line_item->total() / $running_totals['total']) + 1
-                            : 1;
-                        foreach ($running_totals as $line_item_id => $this_running_total) {
-                            // the "taxable" array key is an exception
-                            if ($line_item_id === 'taxable') {
-                                continue;
-                            }
-                            // update the running totals
-                            // yes this actually even works for the running grand total!
-                            $running_totals[ $line_item_id ] =
-                                $line_items_percent_of_running_total * $this_running_total;
-
-                            if ($child_line_item->is_taxable()) {
-                                $running_totals['taxable'][ $line_item_id ] =
-                                    $line_items_percent_of_running_total * $running_totals['taxable'][ $line_item_id ];
-                            }
-                        }
-                    }
-                    break;
-            }
-        }
-        return $running_totals;
-    }
-
-
-    /**
-     * @param EE_Line_Item $total_line_item
-     * @param EE_Line_Item $ticket_line_item
-     * @return float | null
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws OutOfRangeException
-     * @throws ReflectionException
-     */
-    public static function calculate_final_price_for_ticket_line_item(
-        EE_Line_Item $total_line_item,
-        EE_Line_Item $ticket_line_item
-    ): ?float {
-        static $final_prices_per_ticket_line_item = [];
-        if (
-            empty($final_prices_per_ticket_line_item)
-            || empty($final_prices_per_ticket_line_item[ $total_line_item->ID() ])
-        ) {
-            $final_prices_per_ticket_line_item[ $total_line_item->ID() ] =
-                EEH_Line_Item::calculate_reg_final_prices_per_line_item(
-                    $total_line_item
-                );
-        }
-        // ok now find this new registration's final price
-        if (isset($final_prices_per_ticket_line_item[ $total_line_item->ID() ][ $ticket_line_item->ID() ])) {
-            return $final_prices_per_ticket_line_item[ $total_line_item->ID() ][ $ticket_line_item->ID() ];
-        }
-        $message = sprintf(
-            esc_html__(
-                'The final price for the ticket line item (ID:%1$d) on the total line item (ID:%2$d) could not be calculated.',
-                'event_espresso'
-            ),
-            $ticket_line_item->ID(),
-            $total_line_item->ID()
-        );
-        if (WP_DEBUG) {
-            $message .= '<br>' . print_r($final_prices_per_ticket_line_item, true);
-            throw new OutOfRangeException($message);
-        }
-        EE_Log::instance()->log(__CLASS__, __FUNCTION__, $message);
-        return null;
-    }
-
-
-    /**
-     * Creates a duplicate of the line item tree, except only includes billable items
-     * and the portion of line items attributed to billable things
-     *
-     * @param EE_Line_Item      $line_item
-     * @param EE_Registration[] $registrations
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function billable_line_item_tree(EE_Line_Item $line_item, array $registrations): EE_Line_Item
-    {
-        $copy_li = EEH_Line_Item::billable_line_item($line_item, $registrations);
-        foreach ($line_item->children() as $child_li) {
-            $copy_li->add_child_line_item(
-                EEH_Line_Item::billable_line_item_tree($child_li, $registrations)
-            );
-        }
-        // if this is the grand total line item, make sure the totals all add up
-        // (we could have duplicated this logic AS we copied the line items, but
-        // it seems DRYer this way)
-        if ($copy_li->type() === EEM_Line_Item::type_total) {
-            $copy_li->recalculate_total_including_taxes();
-        }
-        return $copy_li;
-    }
-
-
-    /**
-     * Creates a new, unsaved line item from $line_item that factors in the
-     * number of billable registrations on $registrations.
-     *
-     * @param EE_Line_Item      $line_item
-     * @param EE_Registration[] $registrations
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function billable_line_item(EE_Line_Item $line_item, array $registrations): EE_Line_Item
-    {
-        $new_li_fields = $line_item->model_field_array();
-        if (
-            $line_item->type() === EEM_Line_Item::type_line_item &&
-            $line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET
-        ) {
-            $count = 0;
-            foreach ($registrations as $registration) {
-                if (
-                    $line_item->OBJ_ID() === $registration->ticket_ID() &&
-                    in_array(
-                        $registration->status_ID(),
-                        EEM_Registration::reg_statuses_that_allow_payment(),
-                        true
-                    )
-                ) {
-                    $count++;
-                }
-            }
-            $new_li_fields['LIN_quantity'] = $count;
-        }
-        // don't set the total. We'll leave that up to the code that calculates it
-        unset($new_li_fields['LIN_ID'], $new_li_fields['LIN_parent'], $new_li_fields['LIN_total']);
-        return EE_Line_Item::new_instance($new_li_fields);
-    }
-
-
-    /**
-     * Returns a modified line item tree where all the subtotals which have a total of 0
-     * are removed, and line items with a quantity of 0
-     *
-     * @param EE_Line_Item $line_item |null
-     * @return EE_Line_Item|null
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function non_empty_line_items(EE_Line_Item $line_item): ?EE_Line_Item
-    {
-        $copied_li = EEH_Line_Item::non_empty_line_item($line_item);
-        if ($copied_li === null) {
-            return null;
-        }
-        // if this is an event subtotal, we want to only include it if it
-        // has a non-zero total and at least one ticket line item child
-        $ticket_children = 0;
-        foreach ($line_item->children() as $child_li) {
-            $child_li_copy = EEH_Line_Item::non_empty_line_items($child_li);
-            if ($child_li_copy !== null) {
-                $copied_li->add_child_line_item($child_li_copy);
-                if (
-                    $child_li_copy->type() === EEM_Line_Item::type_line_item &&
-                    $child_li_copy->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET
-                ) {
-                    $ticket_children++;
-                }
-            }
-        }
-        // if this is an event subtotal with NO ticket children
-        // we basically want to ignore it
-        if (
-            $ticket_children === 0
-            && $line_item->type() === EEM_Line_Item::type_sub_total
-            && $line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_EVENT
-            && $line_item->total() === 0.0
-        ) {
-            return null;
-        }
-        return $copied_li;
-    }
-
-
-    /**
-     * Creates a new, unsaved line item, but if it's a ticket line item
-     * with a total of 0, or a subtotal of 0, returns null instead
-     *
-     * @param EE_Line_Item $line_item
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function non_empty_line_item(EE_Line_Item $line_item): ?EE_Line_Item
-    {
-        if (
-            $line_item->type() === EEM_Line_Item::type_line_item
-            && $line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET
-            && $line_item->quantity() === 0
-        ) {
-            return null;
-        }
-        $new_li_fields = $line_item->model_field_array();
-        // don't set the total. We'll leave that up to the code that calculates it
-        unset($new_li_fields['LIN_ID'], $new_li_fields['LIN_parent']);
-        return EE_Line_Item::new_instance($new_li_fields);
-    }
-
-
-    /**
-     * Cycles through all the ticket line items for the supplied total line item
-     * and ensures that the line item's "is_taxable" field matches that of its corresponding ticket
-     *
-     * @param EE_Line_Item $total_line_item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @since 4.9.79.p
-     */
-    public static function resetIsTaxableForTickets(EE_Line_Item $total_line_item)
-    {
-        $ticket_line_items = self::get_ticket_line_items($total_line_item);
-        foreach ($ticket_line_items as $ticket_line_item) {
-            if (
-                $ticket_line_item instanceof EE_Line_Item
-                && $ticket_line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET
-            ) {
-                $ticket = $ticket_line_item->ticket();
-                if ($ticket instanceof EE_Ticket && $ticket->taxable() !== $ticket_line_item->is_taxable()) {
-                    $ticket_line_item->set_is_taxable($ticket->taxable());
-                    $ticket_line_item->save();
-                }
-            }
-        }
-    }
-
-
-    /**
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @since   5.0.0.p
-     */
-    private static function getGlobalTaxes(): array
-    {
-        if (EEH_Line_Item::$global_taxes === null) {
-            /** @type EEM_Price $EEM_Price */
-            $EEM_Price = EE_Registry::instance()->load_model('Price');
-            // get array of taxes via Price Model
-            EEH_Line_Item::$global_taxes = $EEM_Price->get_all_prices_that_are_taxes();
-            ksort(EEH_Line_Item::$global_taxes);
-        }
-        return EEH_Line_Item::$global_taxes;
-    }
-
-
-
-    /**************************************** @DEPRECATED METHODS *************************************** */
-    /**
-     * @param EE_Line_Item $total_line_item
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @deprecated
-     */
-    public static function get_items_subtotal(EE_Line_Item $total_line_item): EE_Line_Item
-    {
-        EE_Error::doing_it_wrong(
-            'EEH_Line_Item::get_items_subtotal()',
-            sprintf(
-                esc_html__('Method replaced with %1$s', 'event_espresso'),
-                'EEH_Line_Item::get_pre_tax_subtotal()'
-            ),
-            '4.6.0'
-        );
-        return self::get_pre_tax_subtotal($total_line_item);
-    }
-
-
-    /**
-     * @param EE_Transaction|null $transaction
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @deprecated
-     */
-    public static function create_default_total_line_item(?EE_Transaction $transaction = null): EE_Line_Item
-    {
-        EE_Error::doing_it_wrong(
-            'EEH_Line_Item::create_default_total_line_item()',
-            sprintf(
-                esc_html__('Method replaced with %1$s', 'event_espresso'),
-                'EEH_Line_Item::create_total_line_item()'
-            ),
-            '4.6.0'
-        );
-        return self::create_total_line_item($transaction);
-    }
-
-
-    /**
-     * @param EE_Line_Item        $total_line_item
-     * @param EE_Transaction|null $transaction
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @deprecated
-     */
-    public static function create_default_tickets_subtotal(
-        EE_Line_Item $total_line_item,
-        ?EE_Transaction $transaction = null
-    ): EE_Line_Item {
-        EE_Error::doing_it_wrong(
-            'EEH_Line_Item::create_default_tickets_subtotal()',
-            sprintf(
-                esc_html__('Method replaced with %1$s', 'event_espresso'),
-                'EEH_Line_Item::create_pre_tax_subtotal()'
-            ),
-            '4.6.0'
-        );
-        return self::create_pre_tax_subtotal($total_line_item, $transaction);
-    }
-
-
-    /**
-     * @param EE_Line_Item        $total_line_item
-     * @param EE_Transaction|null $transaction
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @deprecated
-     */
-    public static function create_default_taxes_subtotal(
-        EE_Line_Item $total_line_item,
-        ?EE_Transaction $transaction = null
-    ): EE_Line_Item {
-        EE_Error::doing_it_wrong(
-            'EEH_Line_Item::create_default_taxes_subtotal()',
-            sprintf(
-                esc_html__('Method replaced with %1$s', 'event_espresso'),
-                'EEH_Line_Item::create_taxes_subtotal()'
-            ),
-            '4.6.0'
-        );
-        return self::create_taxes_subtotal($total_line_item, $transaction);
-    }
-
-
-    /**
-     * @param EE_Line_Item        $total_line_item
-     * @param EE_Transaction|null $transaction
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @deprecated
-     */
-    public static function create_default_event_subtotal(
-        EE_Line_Item $total_line_item,
-        ?EE_Transaction $transaction = null
-    ): EE_Line_Item {
-        EE_Error::doing_it_wrong(
-            'EEH_Line_Item::create_default_event_subtotal()',
-            sprintf(
-                esc_html__('Method replaced with %1$s', 'event_espresso'),
-                'EEH_Line_Item::create_event_subtotal()'
-            ),
-            '4.6.0'
-        );
-        return self::create_event_subtotal($total_line_item, $transaction);
-    }
+	/**
+	 * @var EE_Line_Item[]|null
+	 */
+	private static ?array $global_taxes = null;
+
+
+	/**
+	 * Adds a simple item (unrelated to any other model object) to the provided PARENT line item.
+	 * Does NOT automatically re-calculate the line item totals or update the related transaction.
+	 * You should call recalculate_total_including_taxes() on the grant total line item after this
+	 * to update the subtotals, and EE_Registration_Processor::calculate_reg_final_prices_per_line_item()
+	 * to keep the registration final prices in-sync with the transaction's total.
+	 *
+	 * @param EE_Line_Item $parent_line_item
+	 * @param string       $name
+	 * @param float        $unit_price
+	 * @param string       $description
+	 * @param int          $quantity
+	 * @param boolean      $taxable
+	 * @param string|null  $code if set to a value, ensures there is only one line item with that code
+	 * @param bool         $return_item
+	 * @param bool         $recalculate_totals
+	 * @return boolean|EE_Line_Item success
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function add_unrelated_item(
+		EE_Line_Item $parent_line_item,
+		string $name,
+		float $unit_price,
+		string $description = '',
+		int $quantity = 1,
+		bool $taxable = false,
+		?string $code = null,
+		bool $return_item = false,
+		bool $recalculate_totals = true
+	) {
+		$items_subtotal = self::get_pre_tax_subtotal($parent_line_item);
+		$line_item      = EE_Line_Item::new_instance(
+			[
+				'LIN_name'       => $name,
+				'LIN_desc'       => $description,
+				'LIN_unit_price' => $unit_price,
+				'LIN_quantity'   => $quantity,
+				'LIN_percent'    => null,
+				'LIN_is_taxable' => $taxable,
+				'LIN_order'      => count($items_subtotal->children()),
+				'LIN_total'      => $unit_price * $quantity,
+				'LIN_type'       => EEM_Line_Item::type_line_item,
+				'LIN_code'       => $code,
+			]
+		);
+		$line_item      = apply_filters(
+			'FHEE__EEH_Line_Item__add_unrelated_item__line_item',
+			$line_item,
+			$parent_line_item
+		);
+		$added          = self::add_item($parent_line_item, $line_item, $recalculate_totals);
+		return $return_item ? $line_item : $added;
+	}
+
+
+	/**
+	 * Adds a simple item ( unrelated to any other model object) to the total line item,
+	 * in the correct spot in the line item tree. Does not automatically
+	 * re-calculate the line item totals, nor update the related transaction, nor upgrade the transaction's
+	 * registrations' final prices (which should probably change because of this).
+	 * You should call recalculate_total_including_taxes() on the grand total line item, then
+	 * update the transaction's total, and EE_Registration_Processor::update_registration_final_prices()
+	 * after using this, to keep the registration final prices in-sync with the transaction's total.
+	 *
+	 * @param EE_Line_Item $parent_line_item
+	 * @param string       $name
+	 * @param float        $percentage_amount
+	 * @param string       $description
+	 * @param boolean      $taxable
+	 * @param string|null  $code
+	 * @param bool         $return_item
+	 * @return boolean|EE_Line_Item success
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function add_percentage_based_item(
+		EE_Line_Item $parent_line_item,
+		string $name,
+		float $percentage_amount,
+		string $description = '',
+		bool $taxable = false,
+		?string $code = null,
+		bool $return_item = false
+	) {
+		$total     = $percentage_amount * $parent_line_item->total() / 100;
+		$line_item = EE_Line_Item::new_instance(
+			[
+				'LIN_name'       => $name,
+				'LIN_desc'       => $description,
+				'LIN_unit_price' => 0,
+				'LIN_percent'    => $percentage_amount,
+				'LIN_is_taxable' => $taxable,
+				'LIN_total'      => $total,
+				'LIN_type'       => EEM_Line_Item::type_line_item,
+				'LIN_parent'     => $parent_line_item->ID(),
+				'LIN_code'       => $code,
+				'TXN_ID'         => $parent_line_item->TXN_ID(),
+			]
+		);
+		$line_item = apply_filters(
+			'FHEE__EEH_Line_Item__add_percentage_based_item__line_item',
+			$line_item
+		);
+		$added     = $parent_line_item->add_child_line_item($line_item, false);
+		return $return_item ? $line_item : $added;
+	}
+
+
+	/**
+	 * Returns the new line item created by adding a purchase of the ticket
+	 * ensures that ticket line item is saved, and that cart total has been recalculated.
+	 * If this ticket has already been purchased, just increments its count.
+	 * Automatically re-calculates the line item totals and updates the related transaction. But
+	 * DOES NOT automatically upgrade the transaction's registrations' final prices (which
+	 * should probably change because of this).
+	 * You should call EE_Registration_Processor::calculate_reg_final_prices_per_line_item()
+	 * after using this, to keep the registration final prices in-sync with the transaction's total.
+	 *
+	 * @param EE_Line_Item|null $total_line_item grand total line item of type EEM_Line_Item::type_total
+	 * @param EE_Ticket         $ticket
+	 * @param int               $qty
+	 * @param bool              $recalculate_totals
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function add_ticket_purchase(
+		?EE_Line_Item $total_line_item,
+		EE_Ticket $ticket,
+		int $qty = 1,
+		bool $recalculate_totals = true
+	): ?EE_Line_Item {
+		if (! $total_line_item instanceof EE_Line_Item || ! $total_line_item->is_total()) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'A valid line item total is required in order to add tickets. A line item of type "%s" was passed.',
+						'event_espresso'
+					),
+					$ticket->ID(),
+					$total_line_item->ID()
+				)
+			);
+		}
+		// either increment the qty for an existing ticket
+		$line_item = self::increment_ticket_qty_if_already_in_cart($total_line_item, $ticket, $qty);
+		// or add a new one
+		if (! $line_item instanceof EE_Line_Item) {
+			$line_item = self::create_ticket_line_item($total_line_item, $ticket, $qty);
+		}
+		if ($recalculate_totals) {
+			$total_line_item->recalculate_total_including_taxes();
+		}
+		return $line_item;
+	}
+
+
+	/**
+	 * Returns the new line item created by adding a purchase of the ticket
+	 *
+	 * @param EE_Line_Item|null $total_line_item
+	 * @param EE_Ticket         $ticket
+	 * @param int               $qty
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function increment_ticket_qty_if_already_in_cart(
+		?EE_Line_Item $total_line_item,
+		EE_Ticket $ticket,
+		int $qty = 1
+	): ?EE_Line_Item {
+		$line_item = null;
+		if ($total_line_item instanceof EE_Line_Item && $total_line_item->is_total()) {
+			$ticket_line_items = EEH_Line_Item::get_ticket_line_items($total_line_item);
+			foreach ($ticket_line_items as $ticket_line_item) {
+				if (
+					$ticket_line_item instanceof EE_Line_Item
+					&& $ticket_line_item->OBJ_ID() === $ticket->ID()
+				) {
+					$line_item = $ticket_line_item;
+					break;
+				}
+			}
+		}
+		if ($line_item instanceof EE_Line_Item) {
+			EEH_Line_Item::increment_quantity($line_item, $qty);
+			return $line_item;
+		}
+		return null;
+	}
+
+
+	/**
+	 * Increments the line item and all its children's quantity by $qty (but percent line items are unaffected).
+	 * Does NOT save or recalculate other line items totals
+	 *
+	 * @param EE_Line_Item $line_item
+	 * @param int          $qty
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function increment_quantity(EE_Line_Item $line_item, int $qty = 1)
+	{
+		if (! $line_item->is_percent()) {
+			$qty += $line_item->quantity();
+			$line_item->set_quantity($qty);
+			$line_item->set_total($line_item->unit_price() * $qty);
+			$line_item->save();
+		}
+		foreach ($line_item->children() as $child) {
+			if ($child->is_sub_line_item()) {
+				EEH_Line_Item::update_quantity($child, $qty);
+			}
+		}
+	}
+
+
+	/**
+	 * Decrements the line item and all its children's quantity by $qty (but percent line items are unaffected).
+	 * Does NOT save or recalculate other line items totals
+	 *
+	 * @param EE_Line_Item $line_item
+	 * @param int          $qty
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function decrement_quantity(EE_Line_Item $line_item, int $qty = 1)
+	{
+		if (! $line_item->is_percent()) {
+			$qty = $line_item->quantity() - $qty;
+			$qty = max($qty, 0);
+			$line_item->set_quantity($qty);
+			$line_item->set_total($line_item->unit_price() * $qty);
+			$line_item->save();
+		}
+		foreach ($line_item->children() as $child) {
+			if ($child->is_sub_line_item()) {
+				EEH_Line_Item::update_quantity($child, $qty);
+			}
+		}
+	}
+
+
+	/**
+	 * Updates the line item and its children's quantities to the specified number.
+	 * Does NOT save them or recalculate totals.
+	 *
+	 * @param EE_Line_Item $line_item
+	 * @param int          $new_quantity
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function update_quantity(EE_Line_Item $line_item, int $new_quantity)
+	{
+		if (! $line_item->is_percent()) {
+			$line_item->set_quantity($new_quantity);
+			$line_item->set_total($line_item->unit_price() * $new_quantity);
+			$line_item->save();
+		}
+		foreach ($line_item->children() as $child) {
+			if ($child->is_sub_line_item()) {
+				EEH_Line_Item::update_quantity($child, $new_quantity);
+			}
+		}
+	}
+
+
+	/**
+	 * Returns the new line item created by adding a purchase of the ticket
+	 *
+	 * @param EE_Line_Item $total_line_item of type EEM_Line_Item::type_total
+	 * @param EE_Ticket    $ticket
+	 * @param int          $qty
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function create_ticket_line_item(
+		EE_Line_Item $total_line_item,
+		EE_Ticket $ticket,
+		int $qty = 1
+	): EE_Line_Item {
+		$datetimes           = $ticket->datetimes();
+		$first_datetime      = reset($datetimes);
+		$first_datetime_name = esc_html__('Event', 'event_espresso');
+		if ($first_datetime instanceof EE_Datetime && $first_datetime->event() instanceof EE_Event) {
+			$first_datetime_name = $first_datetime->event()->name();
+		}
+		$event = sprintf(_x('(For %1$s)', '(For Event Name)', 'event_espresso'), $first_datetime_name);
+		// get event subtotal line
+		$events_sub_total = self::get_event_line_item_for_ticket($total_line_item, $ticket);
+		$taxes            = $ticket->tax_price_modifiers();
+		// add $ticket to cart
+		$line_item = EE_Line_Item::new_instance(
+			[
+				'LIN_name'       => $ticket->name(),
+				'LIN_desc'       => $ticket->description() !== '' ? $ticket->description() . ' ' . $event : $event,
+				'LIN_unit_price' => $ticket->price(),
+				'LIN_quantity'   => $qty,
+				'LIN_is_taxable' => empty($taxes) && $ticket->taxable(),
+				'LIN_order'      => count($events_sub_total->children()),
+				'LIN_total'      => $ticket->price() * $qty,
+				'LIN_type'       => EEM_Line_Item::type_line_item,
+				'OBJ_ID'         => $ticket->ID(),
+				'OBJ_type'       => EEM_Line_Item::OBJ_TYPE_TICKET,
+			]
+		);
+		$line_item = apply_filters(
+			'FHEE__EEH_Line_Item__create_ticket_line_item__line_item',
+			$line_item
+		);
+		if (! $line_item instanceof EE_Line_Item) {
+			throw new DomainException(
+				esc_html__('Invalid EE_Line_Item received.', 'event_espresso')
+			);
+		}
+		$events_sub_total->add_child_line_item($line_item);
+		// now add the sub-line items
+		$running_pre_tax_total = 0;
+		$prices                = $ticket->prices();
+		if (empty($prices)) {
+			// WUT?!?! NO PRICES??? Well, just create a default price then.
+			$default_price = EEM_Price::instance()->get_new_price();
+			if ($default_price->amount() !== $ticket->price()) {
+				$default_price->set_amount($ticket->price());
+			}
+			$default_price->save();
+			$ticket->_add_relation_to($default_price, 'Price');
+			$ticket->save();
+			$prices = [$default_price];
+		}
+		foreach ($prices as $price) {
+			$sign = $price->is_discount() ? -1 : 1;
+			$price_amount = $price->amount();
+			if ($price->is_percent()) {
+				$price_total = $running_pre_tax_total * $price_amount / 100;
+				$percent    = $sign * $price_amount;
+				$unit_price = 0;
+			} else {
+				$price_total = $price_amount * $qty;
+				$percent    = 0;
+				$unit_price = $sign * $price_amount;
+			}
+
+			$price_desc = $price->desc();
+			$price_type = $price->type_obj();
+			$price_desc = $price_desc === '' && $price_type instanceof EE_Price_Type
+				? $price_type->name()
+				: $price_desc;
+
+			$sub_line_item         = EE_Line_Item::new_instance(
+				[
+					'LIN_name'       => $price->name(),
+					'LIN_desc'       => $price_desc,
+					'LIN_is_taxable' => false,
+					'LIN_order'      => $price->order(),
+					'LIN_total'      => $price_total,
+					'LIN_pretax'     => 0,
+					'LIN_unit_price' => $unit_price,
+					'LIN_percent'    => $percent,
+					'LIN_type'       => $price->is_tax()
+						? EEM_Line_Item::type_sub_tax
+						: EEM_Line_Item::type_sub_line_item,
+					'OBJ_ID'         => $price->ID(),
+					'OBJ_type'       => EEM_Line_Item::OBJ_TYPE_PRICE,
+				]
+			);
+			$sub_line_item         = apply_filters(
+				'FHEE__EEH_Line_Item__create_ticket_line_item__sub_line_item',
+				$sub_line_item
+			);
+			$running_pre_tax_total += ! $price->is_tax() ? $sign * $price_total : 0;
+			$line_item->add_child_line_item($sub_line_item);
+		}
+		$line_item->setPretaxTotal($running_pre_tax_total);
+		return $line_item;
+	}
+
+
+	/**
+	 * Adds the specified item under the pre-tax-sub-total line item. Automatically
+	 * re-calculates the line item totals and updates the related transaction. But
+	 * DOES NOT automatically upgrade the transaction's registrations' final prices (which
+	 * should probably change because of this).
+	 * You should call EE_Registration_Processor::calculate_reg_final_prices_per_line_item()
+	 * after using this, to keep the registration final prices in-sync with the transaction's total.
+	 *
+	 * @param EE_Line_Item $total_line_item
+	 * @param EE_Line_Item $item to be added
+	 * @param bool         $recalculate_totals
+	 * @return boolean
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function add_item(
+		EE_Line_Item $total_line_item,
+		EE_Line_Item $item,
+		bool $recalculate_totals = true
+	): bool {
+		$pre_tax_subtotal = self::get_pre_tax_subtotal($total_line_item);
+		$success          = $pre_tax_subtotal->add_child_line_item($item);
+		if ($recalculate_totals) {
+			$total_line_item->recalculate_total_including_taxes();
+		}
+		return $success;
+	}
+
+
+	/**
+	 * cancels an existing ticket line item,
+	 * by decrementing its quantity by 1 and adding a new "type_cancellation" sub-line-item.
+	 * ALL totals and subtotals will NEED TO BE UPDATED after performing this action
+	 *
+	 * @param EE_Line_Item $ticket_line_item
+	 * @param int          $qty
+	 * @return bool success
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function cancel_ticket_line_item(EE_Line_Item $ticket_line_item, int $qty = 1): bool
+	{
+		// validate incoming line_item
+		if ($ticket_line_item->OBJ_type() !== EEM_Line_Item::OBJ_TYPE_TICKET) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'The supplied line item must have an Object Type of "Ticket", not %1$s.',
+						'event_espresso'
+					),
+					$ticket_line_item->type()
+				)
+			);
+		}
+		if ($ticket_line_item->quantity() < $qty) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'Can not cancel %1$d ticket(s) because the supplied line item has a quantity of %2$d.',
+						'event_espresso'
+					),
+					$qty,
+					$ticket_line_item->quantity()
+				)
+			);
+		}
+		// decrement ticket quantity; don't rely on auto-fixing when recalculating totals to do this
+		$ticket_line_item->set_quantity($ticket_line_item->quantity() - $qty);
+		foreach ($ticket_line_item->children() as $child_line_item) {
+			if (
+				$child_line_item->is_sub_line_item()
+				&& ! $child_line_item->is_percent()
+				&& ! $child_line_item->is_cancellation()
+			) {
+				$child_line_item->set_quantity($child_line_item->quantity() - $qty);
+			}
+		}
+		// get cancellation sub line item
+		$cancellation_line_item = EEH_Line_Item::get_descendants_of_type(
+			$ticket_line_item,
+			EEM_Line_Item::type_cancellation
+		);
+		$cancellation_line_item = reset($cancellation_line_item);
+		// verify that this ticket was indeed previously cancelled
+		if ($cancellation_line_item instanceof EE_Line_Item) {
+			// increment cancelled quantity
+			$cancellation_line_item->set_quantity($cancellation_line_item->quantity() + $qty);
+		} else {
+			// create cancellation sub line item
+			$cancellation_line_item = EE_Line_Item::new_instance(
+				[
+					'LIN_name'       => esc_html__('Cancellation', 'event_espresso'),
+					'LIN_desc'       => sprintf(
+						esc_html_x(
+							'Cancelled %1$s : %2$s',
+							'Cancelled Ticket Name : 2015-01-01 11:11',
+							'event_espresso'
+						),
+						$ticket_line_item->name(),
+						current_time(get_option('date_format') . ' ' . get_option('time_format'))
+					),
+					'LIN_total'      => 0,
+					'LIN_unit_price' => 0,
+					'LIN_quantity'   => $qty,
+					'LIN_is_taxable' => $ticket_line_item->is_taxable(),
+					'LIN_order'      => count($ticket_line_item->children()),
+					'LIN_type'       => EEM_Line_Item::type_cancellation,
+				]
+			);
+			$ticket_line_item->add_child_line_item($cancellation_line_item);
+		}
+		if ($ticket_line_item->save_this_and_descendants() > 0) {
+			// decrement parent line item quantity
+			$event_line_item = $ticket_line_item->parent();
+			if (
+				$event_line_item instanceof EE_Line_Item
+				&& $event_line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_EVENT
+			) {
+				$event_line_item->set_quantity($event_line_item->quantity() - $qty);
+				$event_line_item->save();
+			}
+			EEH_Line_Item::get_grand_total_and_recalculate_everything($ticket_line_item);
+			return true;
+		}
+		return false;
+	}
+
+
+	/**
+	 * reinstates (un-cancels?) a previously canceled ticket line item,
+	 * by incrementing its quantity by 1, and decrementing its "type_cancellation" sub-line-item.
+	 * ALL totals and subtotals will NEED TO BE UPDATED after performing this action
+	 *
+	 * @param EE_Line_Item $ticket_line_item
+	 * @param int          $qty
+	 * @return bool success
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function reinstate_canceled_ticket_line_item(EE_Line_Item $ticket_line_item, int $qty = 1): bool
+	{
+		// validate incoming line_item
+		if ($ticket_line_item->OBJ_type() !== EEM_Line_Item::OBJ_TYPE_TICKET) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'The supplied line item must have an Object Type of "Ticket", not %1$s.',
+						'event_espresso'
+					),
+					$ticket_line_item->type()
+				)
+			);
+		}
+		// get cancellation sub line item
+		$cancellation_line_item = EEH_Line_Item::get_descendants_of_type(
+			$ticket_line_item,
+			EEM_Line_Item::type_cancellation
+		);
+		$cancellation_line_item = reset($cancellation_line_item);
+		// verify that this ticket was indeed previously cancelled
+		if (! $cancellation_line_item instanceof EE_Line_Item) {
+			return false;
+		}
+		if ($cancellation_line_item->quantity() > $qty) {
+			// decrement cancelled quantity
+			$cancellation_line_item->set_quantity($cancellation_line_item->quantity() - $qty);
+		} elseif ($cancellation_line_item->quantity() === $qty) {
+			// decrement cancelled quantity in case anyone still has the object kicking around
+			$cancellation_line_item->set_quantity($cancellation_line_item->quantity() - $qty);
+			// delete because quantity will end up as 0
+			$cancellation_line_item->delete();
+			// and attempt to destroy the object,
+			// even though PHP won't actually destroy it until it needs the memory
+			unset($cancellation_line_item);
+		} else {
+			// what ?!?! negative quantity ?!?!
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'Can not reinstate %1$d cancelled ticket(s) because the cancelled ticket quantity is only %2$d.',
+						'event_espresso'
+					),
+					$qty,
+					$cancellation_line_item->quantity()
+				)
+			);
+		}
+		// increment ticket quantity
+		$ticket_line_item->set_quantity($ticket_line_item->quantity() + $qty);
+		if ($ticket_line_item->save_this_and_descendants() > 0) {
+			// increment parent line item quantity
+			$event_line_item = $ticket_line_item->parent();
+			if (
+				$event_line_item instanceof EE_Line_Item
+				&& $event_line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_EVENT
+			) {
+				$event_line_item->set_quantity($event_line_item->quantity() + $qty);
+			}
+			EEH_Line_Item::get_grand_total_and_recalculate_everything($ticket_line_item);
+			return true;
+		}
+		return false;
+	}
+
+
+	/**
+	 * calls EEH_Line_Item::find_transaction_grand_total_for_line_item()
+	 * then EE_Line_Item::recalculate_total_including_taxes() on the result
+	 *
+	 * @param EE_Line_Item $line_item
+	 * @return float
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function get_grand_total_and_recalculate_everything(EE_Line_Item $line_item): float
+	{
+		$grand_total_line_item = EEH_Line_Item::find_transaction_grand_total_for_line_item($line_item);
+		return $grand_total_line_item->recalculate_total_including_taxes();
+	}
+
+
+	/**
+	 * Gets the line item which contains the subtotal of all the items
+	 *
+	 * @param EE_Line_Item $total_line_item of type EEM_Line_Item::type_total
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function get_pre_tax_subtotal(EE_Line_Item $total_line_item): EE_Line_Item
+	{
+		$pre_tax_subtotal = $total_line_item->get_child_line_item('pre-tax-subtotal');
+		return $pre_tax_subtotal instanceof EE_Line_Item
+			? $pre_tax_subtotal
+			: self::create_pre_tax_subtotal($total_line_item);
+	}
+
+
+	/**
+	 * Gets the line item for the taxes subtotal
+	 *
+	 * @param EE_Line_Item $total_line_item of type EEM_Line_Item::type_total
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function get_taxes_subtotal(EE_Line_Item $total_line_item): EE_Line_Item
+	{
+		$taxes = $total_line_item->get_child_line_item('taxes');
+		return $taxes ?: self::create_taxes_subtotal($total_line_item);
+	}
+
+
+	/**
+	 * sets the TXN ID on an EE_Line_Item if passed a valid EE_Transaction object
+	 *
+	 * @param EE_Line_Item        $line_item
+	 * @param EE_Transaction|null $transaction
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function set_TXN_ID(EE_Line_Item $line_item, ?EE_Transaction $transaction = null)
+	{
+		if ($transaction) {
+			/** @type EEM_Transaction $EEM_Transaction */
+			$EEM_Transaction = EE_Registry::instance()->load_model('Transaction');
+			$TXN_ID          = $EEM_Transaction->ensure_is_ID($transaction);
+			$line_item->set_TXN_ID($TXN_ID);
+		}
+	}
+
+
+	/**
+	 * Creates a new default total line item for the transaction,
+	 * and its tickets subtotal and taxes subtotal line items (and adds the
+	 * existing taxes as children of the taxes subtotal line item)
+	 *
+	 * @param EE_Transaction|null $transaction
+	 * @return EE_Line_Item of type total
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function create_total_line_item(?EE_Transaction $transaction = null): EE_Line_Item
+	{
+		$total_line_item = EE_Line_Item::new_instance(
+			[
+				'LIN_code' => 'total',
+				'LIN_name' => esc_html__('Grand Total', 'event_espresso'),
+				'LIN_type' => EEM_Line_Item::type_total,
+				'OBJ_type' => EEM_Line_Item::OBJ_TYPE_TRANSACTION,
+			]
+		);
+		$total_line_item = apply_filters(
+			'FHEE__EEH_Line_Item__create_total_line_item__total_line_item',
+			$total_line_item
+		);
+		self::set_TXN_ID($total_line_item, $transaction);
+		self::create_pre_tax_subtotal($total_line_item, $transaction);
+		self::create_taxes_subtotal($total_line_item, $transaction);
+		return $total_line_item;
+	}
+
+
+	/**
+	 * Creates a default items subtotal line item
+	 *
+	 * @param EE_Line_Item        $total_line_item
+	 * @param EE_Transaction|null $transaction
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	protected static function create_pre_tax_subtotal(
+		EE_Line_Item $total_line_item,
+		?EE_Transaction $transaction = null
+	): EE_Line_Item {
+		$pre_tax_line_item = EE_Line_Item::new_instance(
+			[
+				'LIN_code' => 'pre-tax-subtotal',
+				'LIN_name' => esc_html__('Pre-Tax Subtotal', 'event_espresso'),
+				'LIN_type' => EEM_Line_Item::type_sub_total,
+			]
+		);
+		$pre_tax_line_item = apply_filters(
+			'FHEE__EEH_Line_Item__create_pre_tax_subtotal__pre_tax_line_item',
+			$pre_tax_line_item
+		);
+		self::set_TXN_ID($pre_tax_line_item, $transaction);
+		$total_line_item->add_child_line_item($pre_tax_line_item);
+		self::create_event_subtotal($pre_tax_line_item, $transaction);
+		return $pre_tax_line_item;
+	}
+
+
+	/**
+	 * Creates a line item for the taxes subtotal and finds all the tax prices
+	 * and applies taxes to it
+	 *
+	 * @param EE_Line_Item        $total_line_item of type EEM_Line_Item::type_total
+	 * @param EE_Transaction|null $transaction
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	protected static function create_taxes_subtotal(
+		EE_Line_Item $total_line_item,
+		?EE_Transaction $transaction = null
+	): EE_Line_Item {
+		$tax_line_item = EE_Line_Item::new_instance(
+			[
+				'LIN_code'  => 'taxes',
+				'LIN_name'  => esc_html__('Taxes', 'event_espresso'),
+				'LIN_type'  => EEM_Line_Item::type_tax_sub_total,
+				'LIN_order' => 1000,// this should always come last
+			]
+		);
+		$tax_line_item = apply_filters(
+			'FHEE__EEH_Line_Item__create_taxes_subtotal__tax_line_item',
+			$tax_line_item
+		);
+		self::set_TXN_ID($tax_line_item, $transaction);
+		$total_line_item->add_child_line_item($tax_line_item);
+		// and lastly, add the actual taxes
+		self::apply_taxes($total_line_item);
+		return $tax_line_item;
+	}
+
+
+	/**
+	 * Creates a default items subtotal line item
+	 *
+	 * @param EE_Line_Item        $pre_tax_line_item
+	 * @param EE_Transaction|null $transaction
+	 * @param EE_Event|null       $event
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function create_event_subtotal(
+		EE_Line_Item $pre_tax_line_item,
+		?EE_Transaction $transaction = null,
+		?EE_Event $event = null
+	): EE_Line_Item {
+		// first check if this line item already exists
+		$event_line_item = EEM_Line_Item::instance()->get_one(
+			[
+				[
+					'LIN_type' => EEM_Line_Item::type_sub_total,
+					'OBJ_type' => EEM_Line_Item::OBJ_TYPE_EVENT,
+					'OBJ_ID'   => $event instanceof EE_Event ? $event->ID() : 0,
+					'TXN_ID'   => $transaction instanceof EE_Transaction ? $transaction->ID() : 0,
+				],
+			]
+		);
+		if ($event_line_item instanceof EE_Line_Item) {
+			return $event_line_item;
+		}
+
+		$event_line_item = EE_Line_Item::new_instance(
+			[
+				'LIN_code' => self::get_event_code($event),
+				'LIN_name' => self::get_event_name($event),
+				'LIN_desc' => self::get_event_desc($event),
+				'LIN_type' => EEM_Line_Item::type_sub_total,
+				'OBJ_type' => EEM_Line_Item::OBJ_TYPE_EVENT,
+				'OBJ_ID'   => $event instanceof EE_Event ? $event->ID() : 0,
+			]
+		);
+		$event_line_item = apply_filters(
+			'FHEE__EEH_Line_Item__create_event_subtotal__event_line_item',
+			$event_line_item
+		);
+		self::set_TXN_ID($event_line_item, $transaction);
+		$pre_tax_line_item->add_child_line_item($event_line_item);
+		return $event_line_item;
+	}
+
+
+	/**
+	 * Gets what the event ticket's code SHOULD be
+	 *
+	 * @param EE_Event|null $event
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function get_event_code(?EE_Event $event = null): string
+	{
+		return 'event-' . ($event instanceof EE_Event ? $event->ID() : '0');
+	}
+
+
+	/**
+	 * Gets the event name
+	 *
+	 * @param EE_Event|null $event
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function get_event_name(?EE_Event $event = null): string
+	{
+		return $event instanceof EE_Event
+			? mb_substr($event->name(), 0, 245)
+			: esc_html__('Event', 'event_espresso');
+	}
+
+
+	/**
+	 * Gets the event excerpt
+	 *
+	 * @param EE_Event|null $event
+	 * @return string
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function get_event_desc(?EE_Event $event = null): string
+	{
+		return $event instanceof EE_Event ? $event->short_description() : '';
+	}
+
+
+	/**
+	 * Given the grand total line item and a ticket, finds the event sub-total
+	 * line item the ticket's purchase should be added onto
+	 *
+	 * @access public
+	 * @param EE_Line_Item $grand_total the grand total line item
+	 * @param EE_Ticket    $ticket
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function get_event_line_item_for_ticket(EE_Line_Item $grand_total, EE_Ticket $ticket): EE_Line_Item
+	{
+		$first_datetime = $ticket->first_datetime();
+		if (! $first_datetime instanceof EE_Datetime) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__('The supplied ticket (ID %d) has no datetimes', 'event_espresso'),
+					$ticket->ID()
+				)
+			);
+		}
+		$event = $first_datetime->event();
+		if (! $event instanceof EE_Event) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'The supplied ticket (ID %d) has no event data associated with it.',
+						'event_espresso'
+					),
+					$ticket->ID()
+				)
+			);
+		}
+		$events_sub_total = EEH_Line_Item::get_event_line_item($grand_total, $event);
+		if (! $events_sub_total instanceof EE_Line_Item) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'There is no events sub-total for ticket %s on total line item %d',
+						'event_espresso'
+					),
+					$ticket->ID(),
+					$grand_total->ID()
+				)
+			);
+		}
+		return $events_sub_total;
+	}
+
+
+	/**
+	 * Gets the event line item
+	 *
+	 * @param EE_Line_Item  $total_line_item
+	 * @param EE_Event|null $event
+	 * @return EE_Line_Item for the event subtotal which is a child of $grand_total
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function get_event_line_item(EE_Line_Item $total_line_item, ?EE_Event $event = null): ?EE_Line_Item
+	{
+		/** @type EE_Event $event */
+		$event           = EEM_Event::instance()->ensure_is_obj($event, true);
+		$event_line_item = null;
+		$event_line_items = EEH_Line_Item::get_event_subtotals($total_line_item);
+		foreach ($event_line_items as $event_line_item) {
+			// default event subtotal, we should only ever find this the first time this method is called
+			$OBJ_ID = $event_line_item->OBJ_ID();
+			if ($OBJ_ID === $event->ID()) {
+				// found existing line item for this event in the cart, so break out of loop and use this one
+				break;
+			}
+			if (! $OBJ_ID) {
+				// let's use this! but first... set the event details
+				EEH_Line_Item::set_event_subtotal_details($event_line_item, $event);
+				break;
+			}
+		}
+		if (! $event_line_item instanceof EE_Line_Item) {
+			// there is no event sub-total yet, so add it
+			$pre_tax_subtotal = EEH_Line_Item::get_pre_tax_subtotal($total_line_item);
+			// a new "event" subtotal SHOULD have been created
+			$event_subtotals = EEH_Line_Item::get_event_subtotals($total_line_item);
+			$event_line_item = reset($event_subtotals);
+			// but in ccase one wasn't created for some reason...
+			if (! $event_line_item instanceof EE_Line_Item) {
+				// create a new "event" subtotal
+				$txn = $total_line_item->transaction();
+				$event_line_item = EEH_Line_Item::create_event_subtotal($pre_tax_subtotal, $txn, $event);
+			}
+			// and set the event details
+			EEH_Line_Item::set_event_subtotal_details($event_line_item, $event);
+		}
+		return $event_line_item;
+	}
+
+
+	/**
+	 * Creates a default items subtotal line item
+	 *
+	 * @param EE_Line_Item        $event_line_item
+	 * @param EE_Event|null       $event
+	 * @param EE_Transaction|null $transaction
+	 * @return void
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function set_event_subtotal_details(
+		EE_Line_Item $event_line_item,
+		EE_Event $event = null,
+		?EE_Transaction $transaction = null
+	) {
+		if ($event instanceof EE_Event) {
+			$event_line_item->set_code(self::get_event_code($event));
+			$event_line_item->set_name(self::get_event_name($event));
+			$event_line_item->set_desc(self::get_event_desc($event));
+			$event_line_item->set_OBJ_ID($event->ID());
+		}
+		self::set_TXN_ID($event_line_item, $transaction);
+	}
+
+
+	/**
+	 * Finds what taxes should apply, adds them as tax line items under the taxes sub-total,
+	 * and recalculates the taxes sub-total and the grand total. Resets the taxes, so
+	 * any old taxes are removed
+	 *
+	 * @param EE_Line_Item $total_line_item of type EEM_Line_Item::type_total
+	 * @param bool         $update_txn_status
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @throws RuntimeException
+	 */
+	public static function apply_taxes(EE_Line_Item $total_line_item, bool $update_txn_status = false): bool
+	{
+		$total_line_item       = EEH_Line_Item::find_transaction_grand_total_for_line_item($total_line_item);
+		$taxes_line_item       = self::get_taxes_subtotal($total_line_item);
+		$existing_global_taxes = $taxes_line_item->tax_descendants();
+		$updates               = false;
+		// loop thru taxes
+		$global_taxes = EEH_Line_Item::getGlobalTaxes();
+		foreach ($global_taxes as $order => $taxes) {
+			foreach ($taxes as $tax) {
+				if ($tax instanceof EE_Price) {
+					$found = false;
+					// check if this is already an existing tax
+					foreach ($existing_global_taxes as $existing_global_tax) {
+						if ($tax->ID() === $existing_global_tax->OBJ_ID()) {
+							// maybe update the tax rate in case it has changed
+							if ($existing_global_tax->percent() !== $tax->amount()) {
+								$existing_global_tax->set_percent($tax->amount());
+								$existing_global_tax->save();
+								$updates = true;
+							}
+							$found = true;
+							break;
+						}
+					}
+					if (! $found) {
+						// add a new line item for this global tax
+						$tax_line_item = apply_filters(
+							'FHEE__EEH_Line_Item__apply_taxes__tax_line_item',
+							EE_Line_Item::new_instance(
+								[
+									'LIN_name'       => $tax->name(),
+									'LIN_desc'       => $tax->desc(),
+									'LIN_percent'    => $tax->amount(),
+									'LIN_is_taxable' => false,
+									'LIN_order'      => $order,
+									'LIN_total'      => 0,
+									'LIN_type'       => EEM_Line_Item::type_tax,
+									'OBJ_type'       => EEM_Line_Item::OBJ_TYPE_PRICE,
+									'OBJ_ID'         => $tax->ID(),
+								]
+							)
+						);
+						$updates       = $taxes_line_item->add_child_line_item($tax_line_item) ? true : $updates;
+					}
+				}
+			}
+		}
+		// only recalculate totals if something changed
+		if ($updates || $update_txn_status) {
+			$total_line_item->recalculate_total_including_taxes($update_txn_status);
+			return true;
+		}
+		return false;
+	}
+
+
+	/**
+	 * Ensures that taxes have been applied to the order, if not applies them.
+	 * Returns the total amount of tax
+	 *
+	 * @param EE_Line_Item|null $total_line_item of type EEM_Line_Item::type_total
+	 * @return float
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function ensure_taxes_applied(?EE_Line_Item $total_line_item): float
+	{
+		$taxes_subtotal = self::get_taxes_subtotal($total_line_item);
+		if (! $taxes_subtotal->children()) {
+			self::apply_taxes($total_line_item);
+		}
+		return $taxes_subtotal->total();
+	}
+
+
+	/**
+	 * Deletes ALL children of the passed line item
+	 *
+	 * @param EE_Line_Item $parent_line_item
+	 * @return bool
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function delete_all_child_items(EE_Line_Item $parent_line_item)
+	{
+		$deleted = 0;
+		foreach ($parent_line_item->children() as $child_line_item) {
+			if ($child_line_item instanceof EE_Line_Item) {
+				$deleted += EEH_Line_Item::delete_all_child_items($child_line_item);
+				if ($child_line_item->ID()) {
+					$child_line_item->delete();
+					unset($child_line_item);
+				} else {
+					$parent_line_item->delete_child_line_item($child_line_item->code());
+				}
+				$deleted++;
+			}
+		}
+		return $deleted;
+	}
+
+
+	/**
+	 * Deletes the line items as indicated by the line item code(s) provided,
+	 * regardless of where they're found in the line item tree. Automatically
+	 * re-calculates the line item totals and updates the related transaction. But
+	 * DOES NOT automatically upgrade the transaction's registrations' final prices (which
+	 * should probably change because of this).
+	 * You should call EE_Registration_Processor::calculate_reg_final_prices_per_line_item()
+	 * after using this, to keep the registration final prices in-sync with the transaction's total.
+	 *
+	 * @param EE_Line_Item      $total_line_item of type EEM_Line_Item::type_total
+	 * @param array|bool|string $line_item_codes
+	 * @return int number of items successfully removed
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function delete_items(EE_Line_Item $total_line_item, $line_item_codes = false)
+	{
+		if ($total_line_item->type() !== EEM_Line_Item::type_total) {
+			EE_Error::doing_it_wrong(
+				'EEH_Line_Item::delete_items',
+				esc_html__(
+					'This static method should only be called with a TOTAL line item, otherwise we won\'t recalculate the totals correctly',
+					'event_espresso'
+				),
+				'4.6.18'
+			);
+		}
+
+		// check if only a single line_item_id was passed
+		if (! empty($line_item_codes) && ! is_array($line_item_codes)) {
+			// place single line_item_id in an array to appear as multiple line_item_ids
+			$line_item_codes = [$line_item_codes];
+		}
+		$removals = 0;
+		// cycle thru line_item_ids
+		foreach ($line_item_codes as $line_item_id) {
+			$removals += $total_line_item->delete_child_line_item($line_item_id);
+		}
+
+		if ($removals > 0) {
+			$total_line_item->recalculate_taxes_and_tax_total();
+			return $removals;
+		} else {
+			return false;
+		}
+	}
+
+
+	/**
+	 * Overwrites the previous tax by clearing out the old taxes, and creates a new
+	 * tax and updates the total line item accordingly
+	 *
+	 * @param EE_Line_Item $total_line_item
+	 * @param float        $amount
+	 * @param string       $name
+	 * @param string       $description
+	 * @param string       $code
+	 * @param boolean      $add_to_existing_line_item
+	 *                          if true, and a duplicate line item with the same code is found,
+	 *                          $amount will be added onto it; otherwise will simply set the taxes to match $amount
+	 * @return EE_Line_Item the new tax line item created
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function set_total_tax_to(
+		EE_Line_Item $total_line_item,
+		float $amount,
+		string $name = '',
+		string $description = '',
+		string $code = '',
+		bool $add_to_existing_line_item = false
+	): EE_Line_Item {
+		$tax_subtotal  = self::get_taxes_subtotal($total_line_item);
+		$taxable_total = $total_line_item->taxable_total();
+
+		if ($add_to_existing_line_item) {
+			$new_tax = $tax_subtotal->get_child_line_item($code);
+			EEM_Line_Item::instance()->delete(
+				[['LIN_code' => ['!=', $code], 'LIN_parent' => $tax_subtotal->ID()]]
+			);
+		} else {
+			$new_tax = null;
+			$tax_subtotal->delete_children_line_items();
+		}
+		if ($new_tax) {
+			$new_tax->set_total($new_tax->total() + $amount);
+			$new_tax->set_percent($taxable_total ? $new_tax->total() / $taxable_total * 100 : 0);
+		} else {
+			// no existing tax item. Create it
+			$new_tax = EE_Line_Item::new_instance(
+				[
+					'TXN_ID'      => $total_line_item->TXN_ID(),
+					'LIN_name'    => $name ?: esc_html__('Tax', 'event_espresso'),
+					'LIN_desc'    => $description ?: '',
+					'LIN_percent' => $taxable_total ? ($amount / $taxable_total * 100) : 0,
+					'LIN_total'   => $amount,
+					'LIN_parent'  => $tax_subtotal->ID(),
+					'LIN_type'    => EEM_Line_Item::type_tax,
+					'LIN_code'    => $code,
+				]
+			);
+		}
+
+		$new_tax = apply_filters(
+			'FHEE__EEH_Line_Item__set_total_tax_to__new_tax_subtotal',
+			$new_tax,
+			$total_line_item
+		);
+		$new_tax->save();
+		$tax_subtotal->set_total($new_tax->total());
+		$tax_subtotal->save();
+		$total_line_item->recalculate_total_including_taxes();
+		return $new_tax;
+	}
+
+
+	/**
+	 * Makes all the line items which are children of $line_item taxable (or not).
+	 * Does NOT save the line items
+	 *
+	 * @param EE_Line_Item $line_item
+	 * @param boolean      $taxable
+	 * @param string|null  $code_substring_for_whitelist if this string is part of the line item's code
+	 *                                                   it will be whitelisted (ie, except from becoming taxable)
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function set_line_items_taxable(
+		EE_Line_Item $line_item,
+		bool $taxable = true,
+		?string $code_substring_for_whitelist = null
+	) {
+		$whitelisted = false;
+		if ($code_substring_for_whitelist !== null) {
+			$whitelisted = strpos($line_item->code(), $code_substring_for_whitelist) !== false;
+		}
+		if (! $whitelisted && $line_item->is_line_item()) {
+			$line_item->set_is_taxable($taxable);
+		}
+		foreach ($line_item->children() as $child_line_item) {
+			EEH_Line_Item::set_line_items_taxable(
+				$child_line_item,
+				$taxable,
+				$code_substring_for_whitelist
+			);
+		}
+	}
+
+
+	/**
+	 * Gets all descendants that are event subtotals
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @uses  EEH_Line_Item::get_subtotals_of_object_type()
+	 */
+	public static function get_event_subtotals(EE_Line_Item $parent_line_item): array
+	{
+		return self::get_subtotals_of_object_type($parent_line_item, EEM_Line_Item::OBJ_TYPE_EVENT);
+	}
+
+
+	/**
+	 * Gets all descendants subtotals that match the supplied object type
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @param string       $obj_type
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @uses  EEH_Line_Item::_get_descendants_by_type_and_object_type()
+	 */
+	public static function get_subtotals_of_object_type(EE_Line_Item $parent_line_item, string $obj_type = ''): array
+	{
+		return self::_get_descendants_by_type_and_object_type(
+			$parent_line_item,
+			EEM_Line_Item::type_sub_total,
+			$obj_type
+		);
+	}
+
+
+	/**
+	 * Gets all descendants that are tickets
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @uses  EEH_Line_Item::get_line_items_of_object_type()
+	 */
+	public static function get_ticket_line_items(EE_Line_Item $parent_line_item): array
+	{
+		return self::get_line_items_of_object_type(
+			$parent_line_item,
+			EEM_Line_Item::OBJ_TYPE_TICKET
+		);
+	}
+
+
+	/**
+	 * Gets all descendants subtotals that match the supplied object type
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @param string       $obj_type
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @uses  EEH_Line_Item::_get_descendants_by_type_and_object_type()
+	 */
+	public static function get_line_items_of_object_type(EE_Line_Item $parent_line_item, string $obj_type = ''): array
+	{
+		return self::_get_descendants_by_type_and_object_type(
+			$parent_line_item,
+			EEM_Line_Item::type_line_item,
+			$obj_type
+		);
+	}
+
+
+	/**
+	 * Gets all the descendants (ie, children or children of children etc) that are of the type 'tax'
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @uses  EEH_Line_Item::get_descendants_of_type()
+	 */
+	public static function get_tax_descendants(EE_Line_Item $parent_line_item): array
+	{
+		return EEH_Line_Item::get_descendants_of_type(
+			$parent_line_item,
+			EEM_Line_Item::type_tax
+		);
+	}
+
+
+	/**
+	 * Gets all the real items purchased which are children of this item
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @uses  EEH_Line_Item::get_descendants_of_type()
+	 */
+	public static function get_line_item_descendants(EE_Line_Item $parent_line_item): array
+	{
+		return EEH_Line_Item::get_descendants_of_type(
+			$parent_line_item,
+			EEM_Line_Item::type_line_item
+		);
+	}
+
+
+	/**
+	 * Gets all descendants of supplied line item that match the supplied line item type
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @param string       $line_item_type   one of the EEM_Line_Item constants
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @uses  EEH_Line_Item::_get_descendants_by_type_and_object_type()
+	 */
+	public static function get_descendants_of_type(EE_Line_Item $parent_line_item, string $line_item_type): array
+	{
+		return self::_get_descendants_by_type_and_object_type(
+			$parent_line_item,
+			$line_item_type
+		);
+	}
+
+
+	/**
+	 * Gets all descendants of supplied line item that match the supplied line item type and possibly the object type
+	 * as well
+	 *
+	 * @param EE_Line_Item $parent_line_item  - the line item to find descendants of
+	 * @param string       $line_item_type    one of the EEM_Line_Item constants
+	 * @param string|null  $obj_type          object model class name (minus prefix) or NULL to ignore object type when
+	 *                                        searching
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	protected static function _get_descendants_by_type_and_object_type(
+		EE_Line_Item $parent_line_item,
+		string $line_item_type,
+		?string $obj_type = null
+	): array {
+		$objects = [];
+		foreach ($parent_line_item->children() as $child_line_item) {
+			if ($child_line_item instanceof EE_Line_Item) {
+				if (
+					$child_line_item->type() === $line_item_type
+					&& (
+						$child_line_item->OBJ_type() === $obj_type || $obj_type === null
+					)
+				) {
+					$objects[] = $child_line_item;
+				} else {
+					// go-through-all-its children looking for more matches
+					$objects = array_merge(
+						$objects,
+						self::_get_descendants_by_type_and_object_type(
+							$child_line_item,
+							$line_item_type,
+							$obj_type
+						)
+					);
+				}
+			}
+		}
+		return $objects;
+	}
+
+
+	/**
+	 * Gets all descendants subtotals that match the supplied object type
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @param string       $OBJ_type         object type (like Event)
+	 * @param array        $OBJ_IDs          array of OBJ_IDs
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @uses  EEH_Line_Item::_get_descendants_by_type_and_object_type()
+	 */
+	public static function get_line_items_by_object_type_and_IDs(
+		EE_Line_Item $parent_line_item,
+		string $OBJ_type = '',
+		array $OBJ_IDs = []
+	): array {
+		return self::_get_descendants_by_object_type_and_object_ID(
+			$parent_line_item,
+			$OBJ_type,
+			$OBJ_IDs
+		);
+	}
+
+
+	/**
+	 * Gets all descendants of supplied line item that match the supplied line item type and possibly the object type
+	 * as well
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @param string       $OBJ_type         object type (like Event)
+	 * @param array        $OBJ_IDs          array of OBJ_IDs
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	protected static function _get_descendants_by_object_type_and_object_ID(
+		EE_Line_Item $parent_line_item,
+		string $OBJ_type,
+		array $OBJ_IDs
+	): array {
+		$objects = [];
+		foreach ($parent_line_item->children() as $child_line_item) {
+			if ($child_line_item instanceof EE_Line_Item) {
+				if (
+					$child_line_item->OBJ_type() === $OBJ_type
+					&& in_array($child_line_item->OBJ_ID(), $OBJ_IDs)
+				) {
+					$objects[] = $child_line_item;
+				} else {
+					// go-through-all-its children looking for more matches
+					$objects = array_merge(
+						$objects,
+						self::_get_descendants_by_object_type_and_object_ID(
+							$child_line_item,
+							$OBJ_type,
+							$OBJ_IDs
+						)
+					);
+				}
+			}
+		}
+		return $objects;
+	}
+
+
+	/**
+	 * Uses a breadth-first-search in order to find the nearest descendant of
+	 * the specified type and returns it, else NULL
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @param string       $type             like one of the EEM_Line_Item::type_*
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @uses  EEH_Line_Item::_get_nearest_descendant()
+	 */
+	public static function get_nearest_descendant_of_type(EE_Line_Item $parent_line_item, string $type): ?EE_Line_Item
+	{
+		return self::_get_nearest_descendant($parent_line_item, 'LIN_type', $type);
+	}
+
+
+	/**
+	 * Uses a breadth-first-search in order to find the nearest descendant
+	 * having the specified LIN_code and returns it, else NULL
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @param string       $code             any value used for LIN_code
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @uses  EEH_Line_Item::_get_nearest_descendant()
+	 */
+	public static function get_nearest_descendant_having_code(
+		EE_Line_Item $parent_line_item,
+		string $code
+	): ?EE_Line_Item {
+		return self::_get_nearest_descendant($parent_line_item, 'LIN_code', $code);
+	}
+
+
+	/**
+	 * Uses a breadth-first-search in order to find the nearest descendant
+	 * having the specified LIN_code and returns it, else NULL
+	 *
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @param string       $search_field     name of EE_Line_Item property
+	 * @param mixed        $value            any value stored in $search_field
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	protected static function _get_nearest_descendant(
+		EE_Line_Item $parent_line_item,
+		string $search_field,
+		$value
+	): ?EE_Line_Item {
+		foreach ($parent_line_item->children() as $child) {
+			if ($child->get($search_field) == $value) {
+				return $child;
+			}
+		}
+		foreach ($parent_line_item->children() as $child) {
+			$descendant_found = self::_get_nearest_descendant(
+				$child,
+				$search_field,
+				$value
+			);
+			if ($descendant_found) {
+				return $descendant_found;
+			}
+		}
+		return null;
+	}
+
+
+	/**
+	 * if passed line item has a TXN ID, uses that to jump directly to the grand total line item for the transaction,
+	 * else recursively walks up the line item tree until a parent of type total is found,
+	 *
+	 * @param EE_Line_Item $line_item
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function find_transaction_grand_total_for_line_item(EE_Line_Item $line_item): EE_Line_Item
+	{
+		if ($line_item->is_total()) {
+			return $line_item;
+		}
+		if ($line_item->TXN_ID()) {
+			$total_line_item = $line_item->transaction()->total_line_item(false);
+			if ($total_line_item instanceof EE_Line_Item) {
+				return $total_line_item;
+			}
+		} else {
+			$line_item_parent = $line_item->parent();
+			if ($line_item_parent instanceof EE_Line_Item) {
+				if ($line_item_parent->is_total()) {
+					return $line_item_parent;
+				}
+				return EEH_Line_Item::find_transaction_grand_total_for_line_item($line_item_parent);
+			}
+		}
+		throw new EE_Error(
+			sprintf(
+				esc_html__(
+					'A valid grand total for line item %1$d was not found.',
+					'event_espresso'
+				),
+				$line_item->ID()
+			)
+		);
+	}
+
+
+	/**
+	 * Prints out a representation of the line item tree
+	 *
+	 * @param EE_Line_Item $line_item
+	 * @param int          $indentation
+	 * @param bool         $top_level
+	 * @return void
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public static function visualize(EE_Line_Item $line_item, int $indentation = 0, bool $top_level = true)
+	{
+		if (! defined('WP_DEBUG') || ! WP_DEBUG) {
+			return;
+		}
+		$testing  = defined('EE_TESTS_DIR');
+		$new_line = $testing ? "\n" : '<br />';
+		if ($top_level && ! $testing) {
+			echo '<div style="position: relative; z-index: 9999; margin: 2rem;">';
+			echo '<pre style="padding: 2rem 3rem; color: #00CCFF; background: #363636;">';
+		}
+		if ($top_level || $indentation) {
+			// echo $top_level ? "$new_line$new_line" : $new_line;
+			echo $new_line;
+		}
+		echo str_repeat('. ', $indentation);
+		$breakdown = '';
+		if ($line_item->is_line_item() || $line_item->is_sub_line_item() || $line_item->isTax()) {
+			if ($line_item->is_percent()) {
+				$breakdown = "{$line_item->percent()}%";
+			} else {
+				$breakdown = "\${$line_item->unit_price()} x {$line_item->quantity()}";
+			}
+		}
+		echo wp_kses($line_item->name(), AllowedTags::getAllowedTags());
+		echo " [ ID:{$line_item->ID()} · qty:{$line_item->quantity()} ] {$line_item->type()}";
+		echo " · \${$line_item->total()} · \${$line_item->pretaxTotal()}";
+		if ($breakdown) {
+			echo " ( $breakdown )";
+		}
+		if ($line_item->is_taxable()) {
+			echo '  * taxable';
+		}
+		$children = $line_item->children();
+		if ($children) {
+			foreach ($children as $child) {
+				self::visualize($child, $indentation + 1, false);
+			}
+		}
+		if ($top_level) {
+			echo $testing ? $new_line : "$new_line</pre></div>$new_line";
+		}
+	}
+
+
+	/**
+	 * Calculates the registration's final price, taking into account that they
+	 * need to not only help pay for their OWN ticket, but also any transaction-wide surcharges and taxes,
+	 * and receive a portion of any transaction-wide discounts.
+	 * eg1, if I buy a $1 ticket and brent buys a $9 ticket, and we receive a $5 discount
+	 * then I'll get 1/10 of that $5 discount, which is $0.50, and brent will get
+	 * 9/10ths of that $5 discount, which is $4.50. So my final price should be $0.50
+	 * and brent's final price should be $5.50.
+	 * In order to do this, we basically need to traverse the line item tree calculating
+	 * the running totals (just as if we were recalculating the total), but when we identify
+	 * regular line items, we need to keep track of their share of the grand total.
+	 * Also, we need to keep track of the TAXABLE total for each ticket purchase, so
+	 * we can know how to apply taxes to it. (Note: "taxable total" does not equal the "pretax total"
+	 * when there are non-taxable items; otherwise they would be the same)
+	 *
+	 * @param EE_Line_Item $line_item
+	 * @param array        $billable_ticket_quantities          array of EE_Ticket IDs and their corresponding quantity
+	 *                                                          that can be included in price calculations at this
+	 *                                                          moment
+	 * @return array        keys are line items for tickets IDs and values are their share of the running total,
+	 *                                                          plus the key 'total', and 'taxable' which also has keys
+	 *                                                          of all the ticket IDs. Eg array(
+	 *                                                          12 => 4.3
+	 *                                                          23 => 8.0
+	 *                                                          'total' => 16.6,
+	 *                                                          'taxable' => array(
+	 *                                                          12 => 10,
+	 *                                                          23 => 4
+	 *                                                          ).
+	 *                                                          So to find which registrations have which final price,
+	 *                                                          we need to find which line item is theirs, which can be
+	 *                                                          done with
+	 *                                                          `EEM_Line_Item::instance()->get_line_item_for_registration(
+	 *                                                          $registration );`
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function calculate_reg_final_prices_per_line_item(
+		EE_Line_Item $line_item,
+		array $billable_ticket_quantities = []
+	): array {
+		$running_totals = [
+			'total'   => 0,
+			'taxable' => ['total' => 0],
+		];
+		foreach ($line_item->children() as $child_line_item) {
+			switch ($child_line_item->type()) {
+				case EEM_Line_Item::type_sub_total:
+					$running_totals_from_subtotal = EEH_Line_Item::calculate_reg_final_prices_per_line_item(
+						$child_line_item,
+						$billable_ticket_quantities
+					);
+					// combine arrays but preserve numeric keys
+					$running_totals                     = array_replace_recursive(
+						$running_totals_from_subtotal,
+						$running_totals
+					);
+					$running_totals['total']            += $running_totals_from_subtotal['total'];
+					$running_totals['taxable']['total'] += $running_totals_from_subtotal['taxable']['total'];
+					break;
+
+				case EEM_Line_Item::type_tax_sub_total:
+					// find how much the taxes percentage is
+					if ($child_line_item->percent() !== 0.0) {
+						$tax_percent_decimal = $child_line_item->percent() / 100;
+					} else {
+						$tax_percent_decimal = EE_Taxes::get_total_taxes_percentage() / 100;
+					}
+					// and apply to all the taxable totals, and add to the pretax totals
+					foreach ($running_totals as $line_item_id => $this_running_total) {
+						// "total" and "taxable" array key is an exception
+						if ($line_item_id === 'taxable') {
+							continue;
+						}
+						$taxable_total                   = $running_totals['taxable'][ $line_item_id ];
+						$running_totals[ $line_item_id ] += ($taxable_total * $tax_percent_decimal);
+					}
+					break;
+
+				case EEM_Line_Item::type_line_item:
+					// ticket line items or ????
+					if ($child_line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET) {
+						// kk it's a ticket
+						if (isset($running_totals[ $child_line_item->ID() ])) {
+							// huh? that shouldn't happen.
+							$running_totals['total'] += $child_line_item->total();
+						} else {
+							// it's not in our running totals yet. great.
+							if ($child_line_item->is_taxable()) {
+								$taxable_amount = $child_line_item->unit_price();
+							} else {
+								$taxable_amount = 0;
+							}
+							// are we only calculating totals for some tickets?
+							if (isset($billable_ticket_quantities[ $child_line_item->OBJ_ID() ])) {
+								$quantity = $billable_ticket_quantities[ $child_line_item->OBJ_ID() ];
+
+								$running_totals[ $child_line_item->ID() ]            = $quantity
+									? $child_line_item->unit_price()
+									: 0;
+								$running_totals['taxable'][ $child_line_item->ID() ] = $quantity
+									? $taxable_amount
+									: 0;
+							} else {
+								$quantity                                            = $child_line_item->quantity();
+								$running_totals[ $child_line_item->ID() ]            = $child_line_item->unit_price();
+								$running_totals['taxable'][ $child_line_item->ID() ] = $taxable_amount;
+							}
+							$running_totals['taxable']['total'] += $taxable_amount * $quantity;
+							$running_totals['total']            += $child_line_item->unit_price() * $quantity;
+						}
+					} else {
+						// it's some other type of item added to the cart
+						// it should affect the running totals
+						// basically we want to convert it into a PERCENT modifier. Because
+						// more clearly affect all registration's final price equally
+						$line_items_percent_of_running_total = $running_totals['total'] > 0
+							? ($child_line_item->total() / $running_totals['total']) + 1
+							: 1;
+						foreach ($running_totals as $line_item_id => $this_running_total) {
+							// the "taxable" array key is an exception
+							if ($line_item_id === 'taxable') {
+								continue;
+							}
+							// update the running totals
+							// yes this actually even works for the running grand total!
+							$running_totals[ $line_item_id ] =
+								$line_items_percent_of_running_total * $this_running_total;
+
+							if ($child_line_item->is_taxable()) {
+								$running_totals['taxable'][ $line_item_id ] =
+									$line_items_percent_of_running_total * $running_totals['taxable'][ $line_item_id ];
+							}
+						}
+					}
+					break;
+			}
+		}
+		return $running_totals;
+	}
+
+
+	/**
+	 * @param EE_Line_Item $total_line_item
+	 * @param EE_Line_Item $ticket_line_item
+	 * @return float | null
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws OutOfRangeException
+	 * @throws ReflectionException
+	 */
+	public static function calculate_final_price_for_ticket_line_item(
+		EE_Line_Item $total_line_item,
+		EE_Line_Item $ticket_line_item
+	): ?float {
+		static $final_prices_per_ticket_line_item = [];
+		if (
+			empty($final_prices_per_ticket_line_item)
+			|| empty($final_prices_per_ticket_line_item[ $total_line_item->ID() ])
+		) {
+			$final_prices_per_ticket_line_item[ $total_line_item->ID() ] =
+				EEH_Line_Item::calculate_reg_final_prices_per_line_item(
+					$total_line_item
+				);
+		}
+		// ok now find this new registration's final price
+		if (isset($final_prices_per_ticket_line_item[ $total_line_item->ID() ][ $ticket_line_item->ID() ])) {
+			return $final_prices_per_ticket_line_item[ $total_line_item->ID() ][ $ticket_line_item->ID() ];
+		}
+		$message = sprintf(
+			esc_html__(
+				'The final price for the ticket line item (ID:%1$d) on the total line item (ID:%2$d) could not be calculated.',
+				'event_espresso'
+			),
+			$ticket_line_item->ID(),
+			$total_line_item->ID()
+		);
+		if (WP_DEBUG) {
+			$message .= '<br>' . print_r($final_prices_per_ticket_line_item, true);
+			throw new OutOfRangeException($message);
+		}
+		EE_Log::instance()->log(__CLASS__, __FUNCTION__, $message);
+		return null;
+	}
+
+
+	/**
+	 * Creates a duplicate of the line item tree, except only includes billable items
+	 * and the portion of line items attributed to billable things
+	 *
+	 * @param EE_Line_Item      $line_item
+	 * @param EE_Registration[] $registrations
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function billable_line_item_tree(EE_Line_Item $line_item, array $registrations): EE_Line_Item
+	{
+		$copy_li = EEH_Line_Item::billable_line_item($line_item, $registrations);
+		foreach ($line_item->children() as $child_li) {
+			$copy_li->add_child_line_item(
+				EEH_Line_Item::billable_line_item_tree($child_li, $registrations)
+			);
+		}
+		// if this is the grand total line item, make sure the totals all add up
+		// (we could have duplicated this logic AS we copied the line items, but
+		// it seems DRYer this way)
+		if ($copy_li->type() === EEM_Line_Item::type_total) {
+			$copy_li->recalculate_total_including_taxes();
+		}
+		return $copy_li;
+	}
+
+
+	/**
+	 * Creates a new, unsaved line item from $line_item that factors in the
+	 * number of billable registrations on $registrations.
+	 *
+	 * @param EE_Line_Item      $line_item
+	 * @param EE_Registration[] $registrations
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function billable_line_item(EE_Line_Item $line_item, array $registrations): EE_Line_Item
+	{
+		$new_li_fields = $line_item->model_field_array();
+		if (
+			$line_item->type() === EEM_Line_Item::type_line_item &&
+			$line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET
+		) {
+			$count = 0;
+			foreach ($registrations as $registration) {
+				if (
+					$line_item->OBJ_ID() === $registration->ticket_ID() &&
+					in_array(
+						$registration->status_ID(),
+						EEM_Registration::reg_statuses_that_allow_payment(),
+						true
+					)
+				) {
+					$count++;
+				}
+			}
+			$new_li_fields['LIN_quantity'] = $count;
+		}
+		// don't set the total. We'll leave that up to the code that calculates it
+		unset($new_li_fields['LIN_ID'], $new_li_fields['LIN_parent'], $new_li_fields['LIN_total']);
+		return EE_Line_Item::new_instance($new_li_fields);
+	}
+
+
+	/**
+	 * Returns a modified line item tree where all the subtotals which have a total of 0
+	 * are removed, and line items with a quantity of 0
+	 *
+	 * @param EE_Line_Item $line_item |null
+	 * @return EE_Line_Item|null
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function non_empty_line_items(EE_Line_Item $line_item): ?EE_Line_Item
+	{
+		$copied_li = EEH_Line_Item::non_empty_line_item($line_item);
+		if ($copied_li === null) {
+			return null;
+		}
+		// if this is an event subtotal, we want to only include it if it
+		// has a non-zero total and at least one ticket line item child
+		$ticket_children = 0;
+		foreach ($line_item->children() as $child_li) {
+			$child_li_copy = EEH_Line_Item::non_empty_line_items($child_li);
+			if ($child_li_copy !== null) {
+				$copied_li->add_child_line_item($child_li_copy);
+				if (
+					$child_li_copy->type() === EEM_Line_Item::type_line_item &&
+					$child_li_copy->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET
+				) {
+					$ticket_children++;
+				}
+			}
+		}
+		// if this is an event subtotal with NO ticket children
+		// we basically want to ignore it
+		if (
+			$ticket_children === 0
+			&& $line_item->type() === EEM_Line_Item::type_sub_total
+			&& $line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_EVENT
+			&& $line_item->total() === 0.0
+		) {
+			return null;
+		}
+		return $copied_li;
+	}
+
+
+	/**
+	 * Creates a new, unsaved line item, but if it's a ticket line item
+	 * with a total of 0, or a subtotal of 0, returns null instead
+	 *
+	 * @param EE_Line_Item $line_item
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function non_empty_line_item(EE_Line_Item $line_item): ?EE_Line_Item
+	{
+		if (
+			$line_item->type() === EEM_Line_Item::type_line_item
+			&& $line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET
+			&& $line_item->quantity() === 0
+		) {
+			return null;
+		}
+		$new_li_fields = $line_item->model_field_array();
+		// don't set the total. We'll leave that up to the code that calculates it
+		unset($new_li_fields['LIN_ID'], $new_li_fields['LIN_parent']);
+		return EE_Line_Item::new_instance($new_li_fields);
+	}
+
+
+	/**
+	 * Cycles through all the ticket line items for the supplied total line item
+	 * and ensures that the line item's "is_taxable" field matches that of its corresponding ticket
+	 *
+	 * @param EE_Line_Item $total_line_item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @since 4.9.79.p
+	 */
+	public static function resetIsTaxableForTickets(EE_Line_Item $total_line_item)
+	{
+		$ticket_line_items = self::get_ticket_line_items($total_line_item);
+		foreach ($ticket_line_items as $ticket_line_item) {
+			if (
+				$ticket_line_item instanceof EE_Line_Item
+				&& $ticket_line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET
+			) {
+				$ticket = $ticket_line_item->ticket();
+				if ($ticket instanceof EE_Ticket && $ticket->taxable() !== $ticket_line_item->is_taxable()) {
+					$ticket_line_item->set_is_taxable($ticket->taxable());
+					$ticket_line_item->save();
+				}
+			}
+		}
+	}
+
+
+	/**
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @since   5.0.0.p
+	 */
+	private static function getGlobalTaxes(): array
+	{
+		if (EEH_Line_Item::$global_taxes === null) {
+			/** @type EEM_Price $EEM_Price */
+			$EEM_Price = EE_Registry::instance()->load_model('Price');
+			// get array of taxes via Price Model
+			EEH_Line_Item::$global_taxes = $EEM_Price->get_all_prices_that_are_taxes();
+			ksort(EEH_Line_Item::$global_taxes);
+		}
+		return EEH_Line_Item::$global_taxes;
+	}
+
+
+
+	/**************************************** @DEPRECATED METHODS *************************************** */
+	/**
+	 * @param EE_Line_Item $total_line_item
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @deprecated
+	 */
+	public static function get_items_subtotal(EE_Line_Item $total_line_item): EE_Line_Item
+	{
+		EE_Error::doing_it_wrong(
+			'EEH_Line_Item::get_items_subtotal()',
+			sprintf(
+				esc_html__('Method replaced with %1$s', 'event_espresso'),
+				'EEH_Line_Item::get_pre_tax_subtotal()'
+			),
+			'4.6.0'
+		);
+		return self::get_pre_tax_subtotal($total_line_item);
+	}
+
+
+	/**
+	 * @param EE_Transaction|null $transaction
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @deprecated
+	 */
+	public static function create_default_total_line_item(?EE_Transaction $transaction = null): EE_Line_Item
+	{
+		EE_Error::doing_it_wrong(
+			'EEH_Line_Item::create_default_total_line_item()',
+			sprintf(
+				esc_html__('Method replaced with %1$s', 'event_espresso'),
+				'EEH_Line_Item::create_total_line_item()'
+			),
+			'4.6.0'
+		);
+		return self::create_total_line_item($transaction);
+	}
+
+
+	/**
+	 * @param EE_Line_Item        $total_line_item
+	 * @param EE_Transaction|null $transaction
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @deprecated
+	 */
+	public static function create_default_tickets_subtotal(
+		EE_Line_Item $total_line_item,
+		?EE_Transaction $transaction = null
+	): EE_Line_Item {
+		EE_Error::doing_it_wrong(
+			'EEH_Line_Item::create_default_tickets_subtotal()',
+			sprintf(
+				esc_html__('Method replaced with %1$s', 'event_espresso'),
+				'EEH_Line_Item::create_pre_tax_subtotal()'
+			),
+			'4.6.0'
+		);
+		return self::create_pre_tax_subtotal($total_line_item, $transaction);
+	}
+
+
+	/**
+	 * @param EE_Line_Item        $total_line_item
+	 * @param EE_Transaction|null $transaction
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @deprecated
+	 */
+	public static function create_default_taxes_subtotal(
+		EE_Line_Item $total_line_item,
+		?EE_Transaction $transaction = null
+	): EE_Line_Item {
+		EE_Error::doing_it_wrong(
+			'EEH_Line_Item::create_default_taxes_subtotal()',
+			sprintf(
+				esc_html__('Method replaced with %1$s', 'event_espresso'),
+				'EEH_Line_Item::create_taxes_subtotal()'
+			),
+			'4.6.0'
+		);
+		return self::create_taxes_subtotal($total_line_item, $transaction);
+	}
+
+
+	/**
+	 * @param EE_Line_Item        $total_line_item
+	 * @param EE_Transaction|null $transaction
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @deprecated
+	 */
+	public static function create_default_event_subtotal(
+		EE_Line_Item $total_line_item,
+		?EE_Transaction $transaction = null
+	): EE_Line_Item {
+		EE_Error::doing_it_wrong(
+			'EEH_Line_Item::create_default_event_subtotal()',
+			sprintf(
+				esc_html__('Method replaced with %1$s', 'event_espresso'),
+				'EEH_Line_Item::create_event_subtotal()'
+			),
+			'4.6.0'
+		);
+		return self::create_event_subtotal($total_line_item, $transaction);
+	}
 }

Spacing +47 added lines, -47 removed lines

@@ -24,7 +24,7 @@ 
     /**
      * @var EE_Line_Item[]|null
      */
-    private static ?array $global_taxes = null;
+    private static ? array $global_taxes = null;
 
 
     /**
@@ -73,12 +73,12 @@ 
                 'LIN_code'       => $code,
             ]
         );
-        $line_item      = apply_filters(
+        $line_item = apply_filters(
             'FHEE__EEH_Line_Item__add_unrelated_item__line_item',
             $line_item,
             $parent_line_item
         );
-        $added          = self::add_item($parent_line_item, $line_item, $recalculate_totals);
+        $added = self::add_item($parent_line_item, $line_item, $recalculate_totals);
         return $return_item ? $line_item : $added;
     }
 
@@ -131,7 +131,7 @@ 
             'FHEE__EEH_Line_Item__add_percentage_based_item__line_item',
             $line_item
         );
-        $added     = $parent_line_item->add_child_line_item($line_item, false);
+        $added = $parent_line_item->add_child_line_item($line_item, false);
         return $return_item ? $line_item : $added;
     }
 
@@ -160,7 +160,7 @@ 
         int $qty = 1,
         bool $recalculate_totals = true
     ): ?EE_Line_Item {
-        if (! $total_line_item instanceof EE_Line_Item || ! $total_line_item->is_total()) {
+        if ( ! $total_line_item instanceof EE_Line_Item || ! $total_line_item->is_total()) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -175,7 +175,7 @@ 
         // either increment the qty for an existing ticket
         $line_item = self::increment_ticket_qty_if_already_in_cart($total_line_item, $ticket, $qty);
         // or add a new one
-        if (! $line_item instanceof EE_Line_Item) {
+        if ( ! $line_item instanceof EE_Line_Item) {
             $line_item = self::create_ticket_line_item($total_line_item, $ticket, $qty);
         }
         if ($recalculate_totals) {
@@ -239,7 +239,7 @@ 
      */
     public static function increment_quantity(EE_Line_Item $line_item, int $qty = 1)
     {
-        if (! $line_item->is_percent()) {
+        if ( ! $line_item->is_percent()) {
             $qty += $line_item->quantity();
             $line_item->set_quantity($qty);
             $line_item->set_total($line_item->unit_price() * $qty);
@@ -268,7 +268,7 @@ 
      */
     public static function decrement_quantity(EE_Line_Item $line_item, int $qty = 1)
     {
-        if (! $line_item->is_percent()) {
+        if ( ! $line_item->is_percent()) {
             $qty = $line_item->quantity() - $qty;
             $qty = max($qty, 0);
             $line_item->set_quantity($qty);
@@ -297,7 +297,7 @@ 
      */
     public static function update_quantity(EE_Line_Item $line_item, int $new_quantity)
     {
-        if (! $line_item->is_percent()) {
+        if ( ! $line_item->is_percent()) {
             $line_item->set_quantity($new_quantity);
             $line_item->set_total($line_item->unit_price() * $new_quantity);
             $line_item->save();
@@ -342,7 +342,7 @@ 
         $line_item = EE_Line_Item::new_instance(
             [
                 'LIN_name'       => $ticket->name(),
-                'LIN_desc'       => $ticket->description() !== '' ? $ticket->description() . ' ' . $event : $event,
+                'LIN_desc'       => $ticket->description() !== '' ? $ticket->description().' '.$event : $event,
                 'LIN_unit_price' => $ticket->price(),
                 'LIN_quantity'   => $qty,
                 'LIN_is_taxable' => empty($taxes) && $ticket->taxable(),
@@ -357,7 +357,7 @@ 
             'FHEE__EEH_Line_Item__create_ticket_line_item__line_item',
             $line_item
         );
-        if (! $line_item instanceof EE_Line_Item) {
+        if ( ! $line_item instanceof EE_Line_Item) {
             throw new DomainException(
                 esc_html__('Invalid EE_Line_Item received.', 'event_espresso')
             );
@@ -396,7 +396,7 @@ 
                 ? $price_type->name()
                 : $price_desc;
 
-            $sub_line_item         = EE_Line_Item::new_instance(
+            $sub_line_item = EE_Line_Item::new_instance(
                 [
                     'LIN_name'       => $price->name(),
                     'LIN_desc'       => $price_desc,
@@ -413,7 +413,7 @@ 
                     'OBJ_type'       => EEM_Line_Item::OBJ_TYPE_PRICE,
                 ]
             );
-            $sub_line_item         = apply_filters(
+            $sub_line_item = apply_filters(
                 'FHEE__EEH_Line_Item__create_ticket_line_item__sub_line_item',
                 $sub_line_item
             );
@@ -530,7 +530,7 @@ 
                             'event_espresso'
                         ),
                         $ticket_line_item->name(),
-                        current_time(get_option('date_format') . ' ' . get_option('time_format'))
+                        current_time(get_option('date_format').' '.get_option('time_format'))
                     ),
                     'LIN_total'      => 0,
                     'LIN_unit_price' => 0,
@@ -594,7 +594,7 @@ 
         );
         $cancellation_line_item = reset($cancellation_line_item);
         // verify that this ticket was indeed previously cancelled
-        if (! $cancellation_line_item instanceof EE_Line_Item) {
+        if ( ! $cancellation_line_item instanceof EE_Line_Item) {
             return false;
         }
         if ($cancellation_line_item->quantity() > $qty) {
@@ -809,7 +809,7 @@ 
                 'LIN_code'  => 'taxes',
                 'LIN_name'  => esc_html__('Taxes', 'event_espresso'),
                 'LIN_type'  => EEM_Line_Item::type_tax_sub_total,
-                'LIN_order' => 1000,// this should always come last
+                'LIN_order' => 1000, // this should always come last
             ]
         );
         $tax_line_item = apply_filters(
@@ -887,7 +887,7 @@ 
      */
     public static function get_event_code(?EE_Event $event = null): string
     {
-        return 'event-' . ($event instanceof EE_Event ? $event->ID() : '0');
+        return 'event-'.($event instanceof EE_Event ? $event->ID() : '0');
     }
 
 
@@ -938,7 +938,7 @@ 
     public static function get_event_line_item_for_ticket(EE_Line_Item $grand_total, EE_Ticket $ticket): EE_Line_Item
     {
         $first_datetime = $ticket->first_datetime();
-        if (! $first_datetime instanceof EE_Datetime) {
+        if ( ! $first_datetime instanceof EE_Datetime) {
             throw new EE_Error(
                 sprintf(
                     esc_html__('The supplied ticket (ID %d) has no datetimes', 'event_espresso'),
@@ -947,7 +947,7 @@ 
             );
         }
         $event = $first_datetime->event();
-        if (! $event instanceof EE_Event) {
+        if ( ! $event instanceof EE_Event) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -959,7 +959,7 @@ 
             );
         }
         $events_sub_total = EEH_Line_Item::get_event_line_item($grand_total, $event);
-        if (! $events_sub_total instanceof EE_Line_Item) {
+        if ( ! $events_sub_total instanceof EE_Line_Item) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -1000,20 +1000,20 @@ 
                 // found existing line item for this event in the cart, so break out of loop and use this one
                 break;
             }
-            if (! $OBJ_ID) {
+            if ( ! $OBJ_ID) {
                 // let's use this! but first... set the event details
                 EEH_Line_Item::set_event_subtotal_details($event_line_item, $event);
                 break;
             }
         }
-        if (! $event_line_item instanceof EE_Line_Item) {
+        if ( ! $event_line_item instanceof EE_Line_Item) {
             // there is no event sub-total yet, so add it
             $pre_tax_subtotal = EEH_Line_Item::get_pre_tax_subtotal($total_line_item);
             // a new "event" subtotal SHOULD have been created
             $event_subtotals = EEH_Line_Item::get_event_subtotals($total_line_item);
             $event_line_item = reset($event_subtotals);
             // but in ccase one wasn't created for some reason...
-            if (! $event_line_item instanceof EE_Line_Item) {
+            if ( ! $event_line_item instanceof EE_Line_Item) {
                 // create a new "event" subtotal
                 $txn = $total_line_item->transaction();
                 $event_line_item = EEH_Line_Item::create_event_subtotal($pre_tax_subtotal, $txn, $event);
@@ -1093,7 +1093,7 @@ 
                             break;
                         }
                     }
-                    if (! $found) {
+                    if ( ! $found) {
                         // add a new line item for this global tax
                         $tax_line_item = apply_filters(
                             'FHEE__EEH_Line_Item__apply_taxes__tax_line_item',
@@ -1111,7 +1111,7 @@ 
                                 ]
                             )
                         );
-                        $updates       = $taxes_line_item->add_child_line_item($tax_line_item) ? true : $updates;
+                        $updates = $taxes_line_item->add_child_line_item($tax_line_item) ? true : $updates;
                     }
                 }
             }
@@ -1140,7 +1140,7 @@ 
     public static function ensure_taxes_applied(?EE_Line_Item $total_line_item): float
     {
         $taxes_subtotal = self::get_taxes_subtotal($total_line_item);
-        if (! $taxes_subtotal->children()) {
+        if ( ! $taxes_subtotal->children()) {
             self::apply_taxes($total_line_item);
         }
         return $taxes_subtotal->total();
@@ -1206,7 +1206,7 @@ 
         }
 
         // check if only a single line_item_id was passed
-        if (! empty($line_item_codes) && ! is_array($line_item_codes)) {
+        if ( ! empty($line_item_codes) && ! is_array($line_item_codes)) {
             // place single line_item_id in an array to appear as multiple line_item_ids
             $line_item_codes = [$line_item_codes];
         }
@@ -1316,7 +1316,7 @@ 
         if ($code_substring_for_whitelist !== null) {
             $whitelisted = strpos($line_item->code(), $code_substring_for_whitelist) !== false;
         }
-        if (! $whitelisted && $line_item->is_line_item()) {
+        if ( ! $whitelisted && $line_item->is_line_item()) {
             $line_item->set_is_taxable($taxable);
         }
         foreach ($line_item->children() as $child_line_item) {
@@ -1698,7 +1698,7 @@ 
      */
     public static function visualize(EE_Line_Item $line_item, int $indentation = 0, bool $top_level = true)
     {
-        if (! defined('WP_DEBUG') || ! WP_DEBUG) {
+        if ( ! defined('WP_DEBUG') || ! WP_DEBUG) {
             return;
         }
         $testing  = defined('EE_TESTS_DIR');
@@ -1797,7 +1797,7 @@ 
                         $billable_ticket_quantities
                     );
                     // combine arrays but preserve numeric keys
-                    $running_totals                     = array_replace_recursive(
+                    $running_totals = array_replace_recursive(
                         $running_totals_from_subtotal,
                         $running_totals
                     );
@@ -1818,8 +1818,8 @@ 
                         if ($line_item_id === 'taxable') {
                             continue;
                         }
-                        $taxable_total                   = $running_totals['taxable'][ $line_item_id ];
-                        $running_totals[ $line_item_id ] += ($taxable_total * $tax_percent_decimal);
+                        $taxable_total = $running_totals['taxable'][$line_item_id];
+                        $running_totals[$line_item_id] += ($taxable_total * $tax_percent_decimal);
                     }
                     break;
 
@@ -1827,7 +1827,7 @@ 
                     // ticket line items or ????
                     if ($child_line_item->OBJ_type() === EEM_Line_Item::OBJ_TYPE_TICKET) {
                         // kk it's a ticket
-                        if (isset($running_totals[ $child_line_item->ID() ])) {
+                        if (isset($running_totals[$child_line_item->ID()])) {
                             // huh? that shouldn't happen.
                             $running_totals['total'] += $child_line_item->total();
                         } else {
@@ -1838,19 +1838,19 @@ 
                                 $taxable_amount = 0;
                             }
                             // are we only calculating totals for some tickets?
-                            if (isset($billable_ticket_quantities[ $child_line_item->OBJ_ID() ])) {
-                                $quantity = $billable_ticket_quantities[ $child_line_item->OBJ_ID() ];
+                            if (isset($billable_ticket_quantities[$child_line_item->OBJ_ID()])) {
+                                $quantity = $billable_ticket_quantities[$child_line_item->OBJ_ID()];
 
-                                $running_totals[ $child_line_item->ID() ]            = $quantity
+                                $running_totals[$child_line_item->ID()]            = $quantity
                                     ? $child_line_item->unit_price()
                                     : 0;
-                                $running_totals['taxable'][ $child_line_item->ID() ] = $quantity
+                                $running_totals['taxable'][$child_line_item->ID()] = $quantity
                                     ? $taxable_amount
                                     : 0;
                             } else {
                                 $quantity                                            = $child_line_item->quantity();
-                                $running_totals[ $child_line_item->ID() ]            = $child_line_item->unit_price();
-                                $running_totals['taxable'][ $child_line_item->ID() ] = $taxable_amount;
+                                $running_totals[$child_line_item->ID()]            = $child_line_item->unit_price();
+                                $running_totals['taxable'][$child_line_item->ID()] = $taxable_amount;
                             }
                             $running_totals['taxable']['total'] += $taxable_amount * $quantity;
                             $running_totals['total']            += $child_line_item->unit_price() * $quantity;
@@ -1870,12 +1870,12 @@ 
                             }
                             // update the running totals
                             // yes this actually even works for the running grand total!
-                            $running_totals[ $line_item_id ] =
+                            $running_totals[$line_item_id] =
                                 $line_items_percent_of_running_total * $this_running_total;
 
                             if ($child_line_item->is_taxable()) {
-                                $running_totals['taxable'][ $line_item_id ] =
-                                    $line_items_percent_of_running_total * $running_totals['taxable'][ $line_item_id ];
+                                $running_totals['taxable'][$line_item_id] =
+                                    $line_items_percent_of_running_total * $running_totals['taxable'][$line_item_id];
                             }
                         }
                     }
@@ -1904,16 +1904,16 @@ 
         static $final_prices_per_ticket_line_item = [];
         if (
             empty($final_prices_per_ticket_line_item)
-            || empty($final_prices_per_ticket_line_item[ $total_line_item->ID() ])
+            || empty($final_prices_per_ticket_line_item[$total_line_item->ID()])
         ) {
-            $final_prices_per_ticket_line_item[ $total_line_item->ID() ] =
+            $final_prices_per_ticket_line_item[$total_line_item->ID()] =
                 EEH_Line_Item::calculate_reg_final_prices_per_line_item(
                     $total_line_item
                 );
         }
         // ok now find this new registration's final price
-        if (isset($final_prices_per_ticket_line_item[ $total_line_item->ID() ][ $ticket_line_item->ID() ])) {
-            return $final_prices_per_ticket_line_item[ $total_line_item->ID() ][ $ticket_line_item->ID() ];
+        if (isset($final_prices_per_ticket_line_item[$total_line_item->ID()][$ticket_line_item->ID()])) {
+            return $final_prices_per_ticket_line_item[$total_line_item->ID()][$ticket_line_item->ID()];
         }
         $message = sprintf(
             esc_html__(
@@ -1924,7 +1924,7 @@ 
             $total_line_item->ID()
         );
         if (WP_DEBUG) {
-            $message .= '<br>' . print_r($final_prices_per_ticket_line_item, true);
+            $message .= '<br>'.print_r($final_prices_per_ticket_line_item, true);
             throw new OutOfRangeException($message);
         }
         EE_Log::instance()->log(__CLASS__, __FUNCTION__, $message);

core/helpers/EEH_Sideloader.helper.php

Indentation +337 added lines, -337 removed lines

@@ -13,341 +13,341 @@
  */
 class EEH_Sideloader extends EEH_Base
 {
-    /**
-     * @since   4.1.0
-     * @var     string
-     */
-    private $_upload_to;
-
-    /**
-     * @since   4.10.5.p
-     * @var     string
-     */
-    private $_download_from;
-
-    /**
-     * @since   4.1.0
-     * @var     int|string
-     */
-    private $_permissions;
-
-    /**
-     * @since   4.1.0
-     * @var     string
-     */
-    private $_new_file_name;
-
-
-    /**
-     * constructor allows the user to set the properties on the sideloader on construction.
-     * However, there are also setters for doing so.
-     *
-     * @param array $init array fo initializing the sideloader if keys match the properties.
-     * @since 4.1.0
-     */
-    public function __construct(array $init = [])
-    {
-        $this->_init($init);
-    }
-
-
-    /**
-     * sets the properties for class either to defaults or using incoming initialization array
-     *
-     * @param array $props values passed to setters
-     * @return void
-     * @since 4.1.0
-     */
-    private function _init(array $props)
-    {
-        $props += [
-            '_upload_to'     => $this->_get_wp_uploads_dir(),
-            '_download_from' => '',
-            '_permissions'   => 0644,
-            '_new_file_name' => 'EE_Sideloader_' . uniqid() . '.default',
-        ];
-
-        $this->set_upload_to($props['_upload_to']);
-        $this->set_download_from($props['_download_from']);
-        $this->set_permissions($props['_permissions']);
-        $this->set_new_file_name($props['_new_file_name']);
-
-        // make sure we include the required wp file for needed functions
-        require_once(ABSPATH . 'wp-admin/includes/file.php');
-    }
-
-
-    // utilities
-
-
-    /**
-     * @return string
-     * @since 4.1.0
-     */
-    private function _get_wp_uploads_dir(): string
-    {
-        $uploads = wp_upload_dir();
-        return $uploads['basedir'];
-    }
-
-    // setters
-
-
-    /**
-     * sets the _upload_to property to the directory to upload to.
-     *
-     * @param string $upload_to_folder
-     * @return void
-     * @since 4.1.0
-     */
-    public function set_upload_to(string $upload_to_folder)
-    {
-        $this->_upload_to = trailingslashit($upload_to_folder);
-    }
-
-
-    /**
-     * sets the _download_from property to the location we should download the file from.
-     *
-     * @param string $download_from The full path to the file we should sideload.
-     * @return void
-     * @since 4.10.5.p
-     */
-    public function set_download_from(string $download_from)
-    {
-        $this->_download_from = $download_from;
-    }
-
-
-    /**
-     * sets the _permissions property used on the sideloaded file.
-     *
-     * @param int|string $permissions
-     * @return void
-     * @since 4.1.0
-     */
-    public function set_permissions($permissions)
-    {
-        $this->_permissions = $permissions;
-    }
-
-
-    /**
-     * sets the _new_file_name property used on the sideloaded file.
-     *
-     * @param string $new_file_name
-     * @return void
-     * @since 4.1.0
-     */
-    public function set_new_file_name(string $new_file_name)
-    {
-        $this->_new_file_name = $new_file_name;
-    }
-
-    // getters
-
-
-    /**
-     * @return string
-     * @since 4.1.0
-     */
-    public function get_upload_to(): string
-    {
-        return $this->_upload_to;
-    }
-
-
-    /**
-     * @return string
-     * @since 4.10.5.p
-     */
-    public function get_download_from(): string
-    {
-        return $this->_download_from;
-    }
-
-
-    /**
-     * @return int|string
-     * @since 4.1.0
-     */
-    public function get_permissions()
-    {
-        return $this->_permissions;
-    }
-
-
-    /**
-     * @return string
-     * @since 4.1.0
-     */
-    public function get_new_file_name(): string
-    {
-        return $this->_new_file_name;
-    }
-
-
-    // upload methods
-
-
-    /**
-     * Downloads the file using the WordPress HTTP API.
-     *
-     * @return bool
-     * @since 4.1.0
-     */
-    public function sideload(): bool
-    {
-        try {
-            // setup temp dir
-            $temp_file = wp_tempnam($this->_download_from);
-
-            if (! $temp_file) {
-                throw new RuntimeException(
-                    esc_html__(
-                        'Something went wrong with the upload.  Unable to create a tmp file for the uploaded file on the server',
-                        'event_espresso'
-                    )
-                );
-            }
-
-            do_action('AHEE__EEH_Sideloader__sideload__before', $this, $temp_file);
-
-            $wp_remote_args = apply_filters(
-                'FHEE__EEH_Sideloader__sideload__wp_remote_args',
-                ['timeout' => 500, 'stream' => true, 'filename' => $temp_file],
-                $this,
-                $temp_file
-            );
-
-            $response = wp_safe_remote_get($this->_download_from, $wp_remote_args);
-
-            if ($this->isResponseError($response) || $this->isDownloadError($response)) {
-                EEH_File::delete($temp_file);
-                return false;
-            }
-
-            // possible md5 check
-            $content_md5 = wp_remote_retrieve_header($response, 'content-md5');
-            if ($content_md5) {
-                $md5_check = verify_file_md5($temp_file, $content_md5);
-                if ($this->isResponseError($md5_check)) {
-                    EEH_File::delete($temp_file);
-                    return false;
-                }
-            }
-
-            // now we have the file, let's get it in the right directory with the right name.
-            $path = apply_filters(
-                'FHEE__EEH_Sideloader__sideload__new_path',
-                $this->_upload_to . $this->_new_file_name,
-                $this
-            );
-            if (! EEH_File::move($temp_file, $path, true)) {
-                return false;
-            }
-
-            // set permissions
-            $permissions = apply_filters(
-                'FHEE__EEH_Sideloader__sideload__permissions_applied',
-                $this->_permissions,
-                $this
-            );
-            // verify permissions are an integer but don't actually modify the value
-            if (! absint($permissions)) {
-                EE_Error::add_error(
-                    esc_html__('Supplied permissions are invalid', 'event_espresso'),
-                    __FILE__,
-                    __FUNCTION__,
-                    __LINE__
-                );
-                return false;
-            }
-            EEH_File::chmod($path, $permissions);
-
-            // that's it.  let's allow for actions after file uploaded.
-            do_action('AHEE__EE_Sideloader__sideload_after', $this, $path);
-            return true;
-        } catch (Exception $exception) {
-            EE_Error::add_error($exception->getMessage(), __FILE__, __FUNCTION__, __LINE__);
-            return false;
-        }
-    }
-
-
-    /**
-     * returns TRUE if there IS an error, FALSE if there is NO ERROR
-     *
-     * @param array|WP_Error $response
-     * @return bool
-     * @throws RuntimeException
-     */
-    private function isResponseError($response): bool
-    {
-        if (! is_wp_error($response)) {
-            return false;
-        }
-        if (defined('WP_DEBUG') && WP_DEBUG) {
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'The following error occurred while attempting to download the file from "%1$s":',
-                        'event_espresso'
-                    ),
-                    $this->_download_from,
-                    $response->get_error_message()
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-        }
-        return true;
-    }
-
-
-    /**
-     * returns TRUE if there IS an error, FALSE if there is NO ERROR
-     *
-     * @param array $response
-     * @return bool
-     * @throws RuntimeException
-     */
-    private function isDownloadError(array $response): bool
-    {
-        $response_code = wp_remote_retrieve_response_code($response);
-        if ($response_code === 200) {
-            return false;
-        }
-        if (defined('WP_DEBUG') && WP_DEBUG && ! defined('EE_TESTS_DIR')) {
-            if ($response_code === 404) {
-                EE_Error::add_attention(
-                    sprintf(
-                        esc_html__(
-                            'Attempted to download a file from "%1$s" but encountered a "404 File Not Found" error.',
-                            'event_espresso'
-                        ),
-                        $this->_download_from
-                    ),
-                    __FILE__,
-                    __FUNCTION__,
-                    __LINE__
-                );
-            } else {
-                EE_Error::add_error(
-                    sprintf(
-                        esc_html__(
-                            'Unable to download the file. Either the path given is incorrect, or something else happened. Here is the path given: %s',
-                            'event_espresso'
-                        ),
-                        $this->_download_from
-                    ),
-                    __FILE__,
-                    __FUNCTION__,
-                    __LINE__
-                );
-            }
-        }
-        return true;
-    }
+	/**
+	 * @since   4.1.0
+	 * @var     string
+	 */
+	private $_upload_to;
+
+	/**
+	 * @since   4.10.5.p
+	 * @var     string
+	 */
+	private $_download_from;
+
+	/**
+	 * @since   4.1.0
+	 * @var     int|string
+	 */
+	private $_permissions;
+
+	/**
+	 * @since   4.1.0
+	 * @var     string
+	 */
+	private $_new_file_name;
+
+
+	/**
+	 * constructor allows the user to set the properties on the sideloader on construction.
+	 * However, there are also setters for doing so.
+	 *
+	 * @param array $init array fo initializing the sideloader if keys match the properties.
+	 * @since 4.1.0
+	 */
+	public function __construct(array $init = [])
+	{
+		$this->_init($init);
+	}
+
+
+	/**
+	 * sets the properties for class either to defaults or using incoming initialization array
+	 *
+	 * @param array $props values passed to setters
+	 * @return void
+	 * @since 4.1.0
+	 */
+	private function _init(array $props)
+	{
+		$props += [
+			'_upload_to'     => $this->_get_wp_uploads_dir(),
+			'_download_from' => '',
+			'_permissions'   => 0644,
+			'_new_file_name' => 'EE_Sideloader_' . uniqid() . '.default',
+		];
+
+		$this->set_upload_to($props['_upload_to']);
+		$this->set_download_from($props['_download_from']);
+		$this->set_permissions($props['_permissions']);
+		$this->set_new_file_name($props['_new_file_name']);
+
+		// make sure we include the required wp file for needed functions
+		require_once(ABSPATH . 'wp-admin/includes/file.php');
+	}
+
+
+	// utilities
+
+
+	/**
+	 * @return string
+	 * @since 4.1.0
+	 */
+	private function _get_wp_uploads_dir(): string
+	{
+		$uploads = wp_upload_dir();
+		return $uploads['basedir'];
+	}
+
+	// setters
+
+
+	/**
+	 * sets the _upload_to property to the directory to upload to.
+	 *
+	 * @param string $upload_to_folder
+	 * @return void
+	 * @since 4.1.0
+	 */
+	public function set_upload_to(string $upload_to_folder)
+	{
+		$this->_upload_to = trailingslashit($upload_to_folder);
+	}
+
+
+	/**
+	 * sets the _download_from property to the location we should download the file from.
+	 *
+	 * @param string $download_from The full path to the file we should sideload.
+	 * @return void
+	 * @since 4.10.5.p
+	 */
+	public function set_download_from(string $download_from)
+	{
+		$this->_download_from = $download_from;
+	}
+
+
+	/**
+	 * sets the _permissions property used on the sideloaded file.
+	 *
+	 * @param int|string $permissions
+	 * @return void
+	 * @since 4.1.0
+	 */
+	public function set_permissions($permissions)
+	{
+		$this->_permissions = $permissions;
+	}
+
+
+	/**
+	 * sets the _new_file_name property used on the sideloaded file.
+	 *
+	 * @param string $new_file_name
+	 * @return void
+	 * @since 4.1.0
+	 */
+	public function set_new_file_name(string $new_file_name)
+	{
+		$this->_new_file_name = $new_file_name;
+	}
+
+	// getters
+
+
+	/**
+	 * @return string
+	 * @since 4.1.0
+	 */
+	public function get_upload_to(): string
+	{
+		return $this->_upload_to;
+	}
+
+
+	/**
+	 * @return string
+	 * @since 4.10.5.p
+	 */
+	public function get_download_from(): string
+	{
+		return $this->_download_from;
+	}
+
+
+	/**
+	 * @return int|string
+	 * @since 4.1.0
+	 */
+	public function get_permissions()
+	{
+		return $this->_permissions;
+	}
+
+
+	/**
+	 * @return string
+	 * @since 4.1.0
+	 */
+	public function get_new_file_name(): string
+	{
+		return $this->_new_file_name;
+	}
+
+
+	// upload methods
+
+
+	/**
+	 * Downloads the file using the WordPress HTTP API.
+	 *
+	 * @return bool
+	 * @since 4.1.0
+	 */
+	public function sideload(): bool
+	{
+		try {
+			// setup temp dir
+			$temp_file = wp_tempnam($this->_download_from);
+
+			if (! $temp_file) {
+				throw new RuntimeException(
+					esc_html__(
+						'Something went wrong with the upload.  Unable to create a tmp file for the uploaded file on the server',
+						'event_espresso'
+					)
+				);
+			}
+
+			do_action('AHEE__EEH_Sideloader__sideload__before', $this, $temp_file);
+
+			$wp_remote_args = apply_filters(
+				'FHEE__EEH_Sideloader__sideload__wp_remote_args',
+				['timeout' => 500, 'stream' => true, 'filename' => $temp_file],
+				$this,
+				$temp_file
+			);
+
+			$response = wp_safe_remote_get($this->_download_from, $wp_remote_args);
+
+			if ($this->isResponseError($response) || $this->isDownloadError($response)) {
+				EEH_File::delete($temp_file);
+				return false;
+			}
+
+			// possible md5 check
+			$content_md5 = wp_remote_retrieve_header($response, 'content-md5');
+			if ($content_md5) {
+				$md5_check = verify_file_md5($temp_file, $content_md5);
+				if ($this->isResponseError($md5_check)) {
+					EEH_File::delete($temp_file);
+					return false;
+				}
+			}
+
+			// now we have the file, let's get it in the right directory with the right name.
+			$path = apply_filters(
+				'FHEE__EEH_Sideloader__sideload__new_path',
+				$this->_upload_to . $this->_new_file_name,
+				$this
+			);
+			if (! EEH_File::move($temp_file, $path, true)) {
+				return false;
+			}
+
+			// set permissions
+			$permissions = apply_filters(
+				'FHEE__EEH_Sideloader__sideload__permissions_applied',
+				$this->_permissions,
+				$this
+			);
+			// verify permissions are an integer but don't actually modify the value
+			if (! absint($permissions)) {
+				EE_Error::add_error(
+					esc_html__('Supplied permissions are invalid', 'event_espresso'),
+					__FILE__,
+					__FUNCTION__,
+					__LINE__
+				);
+				return false;
+			}
+			EEH_File::chmod($path, $permissions);
+
+			// that's it.  let's allow for actions after file uploaded.
+			do_action('AHEE__EE_Sideloader__sideload_after', $this, $path);
+			return true;
+		} catch (Exception $exception) {
+			EE_Error::add_error($exception->getMessage(), __FILE__, __FUNCTION__, __LINE__);
+			return false;
+		}
+	}
+
+
+	/**
+	 * returns TRUE if there IS an error, FALSE if there is NO ERROR
+	 *
+	 * @param array|WP_Error $response
+	 * @return bool
+	 * @throws RuntimeException
+	 */
+	private function isResponseError($response): bool
+	{
+		if (! is_wp_error($response)) {
+			return false;
+		}
+		if (defined('WP_DEBUG') && WP_DEBUG) {
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'The following error occurred while attempting to download the file from "%1$s":',
+						'event_espresso'
+					),
+					$this->_download_from,
+					$response->get_error_message()
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+		}
+		return true;
+	}
+
+
+	/**
+	 * returns TRUE if there IS an error, FALSE if there is NO ERROR
+	 *
+	 * @param array $response
+	 * @return bool
+	 * @throws RuntimeException
+	 */
+	private function isDownloadError(array $response): bool
+	{
+		$response_code = wp_remote_retrieve_response_code($response);
+		if ($response_code === 200) {
+			return false;
+		}
+		if (defined('WP_DEBUG') && WP_DEBUG && ! defined('EE_TESTS_DIR')) {
+			if ($response_code === 404) {
+				EE_Error::add_attention(
+					sprintf(
+						esc_html__(
+							'Attempted to download a file from "%1$s" but encountered a "404 File Not Found" error.',
+							'event_espresso'
+						),
+						$this->_download_from
+					),
+					__FILE__,
+					__FUNCTION__,
+					__LINE__
+				);
+			} else {
+				EE_Error::add_error(
+					sprintf(
+						esc_html__(
+							'Unable to download the file. Either the path given is incorrect, or something else happened. Here is the path given: %s',
+							'event_espresso'
+						),
+						$this->_download_from
+					),
+					__FILE__,
+					__FUNCTION__,
+					__LINE__
+				);
+			}
+		}
+		return true;
+	}
 }

core/EE_Maintenance_Mode.core.php

Indentation +512 added lines, -512 removed lines

@@ -19,524 +19,524 @@
  */
 class EE_Maintenance_Mode implements ResettableInterface
 {
-    /**
-     * constants available to client code for interpreting the values of EE_Maintenance_Mode::level().
-     * STATUS_OFF means the site is NOT in maintenance mode (so everything's normal)
-     */
-    public const STATUS_OFF = 0;
-
-
-    /**
-     * STATUS_PUBLIC_ONLY means that the site's frontend EE code should be completely disabled
-     * but the admin backend should be running as normal. Maybe an admin can view the frontend though
-     */
-    public const STATUS_PUBLIC_ONLY = 1;
-
-    /**
-     * STATUS_FULL_SITE means the frontend AND EE backend code are disabled. The only system running
-     * is the maintenance mode stuff, which will require users to update all addons, and then finish running all
-     * migration scripts before taking the site out of maintenance mode
-     */
-    public const STATUS_FULL_SITE = 2;
-
-    /**
-     * the name of the option which stores the current level of maintenance mode
-     */
-    private const OPTION_NAME = 'ee_maintenance_mode';
-
-
-    protected LoaderInterface $loader;
-
-    private RequestInterface $request;
-
-    private static ?EE_Maintenance_Mode $_instance = null;
-
-    /**
-     * @var int
-     * @since 5.0.12.p
-     */
-    private int $status;
-
-    /**
-     * @var int
-     * @since 5.0.12.p
-     */
-    private int $admin_status;
-
-    /**
-     * true if current_user_can('administrator')
-     *
-     * @var bool
-     * @since 5.0.12.p
-     */
-    private bool $current_user_is_admin;
-
-    /**
-     * used to control updates to the WP options setting in the database
-     *
-     * @var bool
-     * @since 5.0.12.p
-     */
-    private bool $update_db;
-
-
-    /**
-     * @singleton method used to instantiate class object
-     * @param LoaderInterface|null  $loader
-     * @param RequestInterface|null $request
-     * @return EE_Maintenance_Mode|null
-     */
-    public static function instance(
-        ?LoaderInterface $loader = null,
-        ?RequestInterface $request = null
-    ): ?EE_Maintenance_Mode {
-        // check if class object is instantiated
-        if (! self::$_instance instanceof EE_Maintenance_Mode) {
-            self::$_instance = new EE_Maintenance_Mode($loader, $request);
-        }
-        return self::$_instance;
-    }
-
-
-    /**
-     * Resets maintenance mode (mostly just re-checks whether we should be in maintenance mode)
-     *
-     * @return EE_Maintenance_Mode|null
-     * @throws EE_Error
-     */
-    public static function reset(): ?EE_Maintenance_Mode
-    {
-        self::instance()->set_maintenance_mode_if_db_old();
-        self::instance()->initialize();
-        return self::instance();
-    }
-
-
-    /**
-     *private constructor to prevent direct creation
-     */
-    private function __construct(LoaderInterface $loader, RequestInterface $request)
-    {
-        $this->loader                = $loader;
-        $this->request               = $request;
-        $this->initialize();
-
-        // if M-Mode level 2 is engaged, we still need basic assets loaded
-        add_action('wp_enqueue_scripts', [$this, 'load_assets_required_for_m_mode']);
-        // shut 'er down for maintenance ?
-        add_filter('the_content', [$this, 'the_content'], 2);
-        // redirect ee menus to maintenance page
-        add_action('admin_page_access_denied', [$this, 'redirect_to_maintenance']);
-        // add powered by EE msg
-        add_action('shutdown', [$this, 'display_maintenance_mode_notice']);
-    }
-
-
-    private function initialize(): void
-    {
-        $this->current_user_is_admin = current_user_can('administrator');
-        // now make sure the status is set correctly everywhere
-        // (but don't update the db else we'll get into an infinite loop of updates)
-        $this->update_db = false;
-        $this->set_maintenance_level($this->loadStatusFromDatabase());
-        $this->update_db = true;
-    }
-
-
-    private function loadStatusFromDatabase(): int
-    {
-        return (int) get_option(EE_Maintenance_Mode::OPTION_NAME, EE_Maintenance_Mode::STATUS_OFF);
-    }
-
-
-    /**
-     * changes the maintenance mode level to reflect whether the current user is an admin or not.
-     * Determines whether we're in maintenance mode and what level. However, while the site
-     * is in level 1 maintenance, and an admin visits the frontend, this function makes it appear
-     * to them as if the site isn't in maintenance mode.
-     *      EE_Maintenance_Mode::STATUS_OFF => not in maintenance mode (in normal mode)
-     *      EE_Maintenance_Mode::STATUS_PUBLIC_ONLY=> frontend-only maintenance mode
-     *      EE_Maintenance_Mode::STATUS_FULL_SITE => frontend and backend maintenance mode
-     *
-     * @param int $status
-     * @return void
-     * @since 5.0.12.p
-     */
-    private function setAdminStatus(int $status)
-    {
-        if (
-            $status === EE_Maintenance_Mode::STATUS_PUBLIC_ONLY
-            && $this->current_user_is_admin
-            && ($this->request->isAjax() || ! $this->request->isAdmin())
-        ) {
-            $status = EE_Maintenance_Mode::STATUS_OFF;
-        }
-        $this->admin_status = $status;
-    }
-
-
-    public function real_level(): int
-    {
-        return $this->status;
-    }
-
-
-    /**
-     * @return int
-     */
-    public function level(): int
-    {
-        return $this->admin_status;
-    }
-
-
-    /**
-     * Determines if we need to put EE in maintenance mode because the database needs updating
-     *
-     * @return boolean true if DB is old and maintenance mode was triggered; false otherwise
-     * @throws EE_Error
-     */
-    public function set_maintenance_mode_if_db_old(): bool
-    {
-        /** @var EE_Data_Migration_Manager $data_migration_manager */
-        $data_migration_manager = $this->loader->getShared(EE_Data_Migration_Manager::class );
-        $scripts_that_should_run = $data_migration_manager->check_for_applicable_data_migration_scripts();
-        if (! empty($scripts_that_should_run)) { //  && $this->status !== EE_Maintenance_Mode::STATUS_FULL_SITE
-            $this->activateFullSiteMaintenanceMode();
-            return true;
-        }
-        if ($this->status === EE_Maintenance_Mode::STATUS_FULL_SITE) {
-            // we also want to handle the opposite: if the site is mm2, but there aren't any migrations to run
-            // then we shouldn't be in mm2. (Maybe an addon got deactivated?)
-            $this->deactivateMaintenanceMode();
-        }
-        return false;
-    }
-
-
-    /**
-     * Updates the maintenance level on the site
-     *
-     * @param int $level
-     * @return void
-     */
-    public function set_maintenance_level(int $level): void
-    {
-        switch ($level) {
-            case EE_Maintenance_Mode::STATUS_OFF:
-                $this->deactivateMaintenanceMode();
-                return;
-            case EE_Maintenance_Mode::STATUS_PUBLIC_ONLY:
-                $this->activatePublicOnlyMaintenanceMode();
-                return;
-            case EE_Maintenance_Mode::STATUS_FULL_SITE:
-                $this->activateFullSiteMaintenanceMode();
-                return;
-        }
-        throw new DomainException(
-            sprintf(
-                esc_html__(
-                    '"%1$s" is not valid a EE maintenance mode level. Please choose from one of the following: %2$s',
-                    'event_espresso'
-                ),
-                $level,
-                'EE_Maintenance_Mode::STATUS_OFF, EE_Maintenance_Mode::STATUS_PUBLIC_ONLY, EE_Maintenance_Mode::STATUS_FULL_SITE',
-            )
-        );
-    }
-
-
-    /**
-     * sets database status to online
-     * sets maintenance mode status to public only, unless current user is an admin, then maintenance mode is disabled
-     *
-     * @return void
-     * @since 5.0.12.p
-     */
-    public function activatePublicOnlyMaintenanceMode()
-    {
-        DbStatus::setOnline();
-        // disable maintenance mode for admins, otherwise enable public only maintenance mode
-        if ($this->current_user_is_admin) {
-            MaintenanceStatus::disableMaintenanceMode();
-        } else {
-            MaintenanceStatus::setPublicOnlyMaintenanceMode();
-        }
-        $this->updateMaintenaceModeStatus(EE_Maintenance_Mode::STATUS_PUBLIC_ONLY);
-    }
-
-
-    /**
-     * sets database status to offline
-     * sets maintenance mode status to full site
-     *
-     * @return void
-     * @since 5.0.12.p
-     */
-    public function activateFullSiteMaintenanceMode()
-    {
-        DbStatus::setOffline();
-        MaintenanceStatus::setFullSiteMaintenanceMode();
-        $this->updateMaintenaceModeStatus(EE_Maintenance_Mode::STATUS_FULL_SITE);
-    }
-
-
-    /**
-     * sets database status to online
-     * turns maintenance mode off
-     *
-     * @return void
-     * @since 5.0.12.p
-     */
-    public function deactivateMaintenanceMode()
-    {
-        DbStatus::setOnline();
-        MaintenanceStatus::disableMaintenanceMode();
-        $this->updateMaintenaceModeStatus(EE_Maintenance_Mode::STATUS_OFF);
-    }
-
-
-    private function updateMaintenaceModeStatus(int $status)
-    {
-        $this->status = $status;
-        $this->setAdminStatus($status);
-        if (! $this->update_db) {
-            return;
-        }
-        do_action('AHEE__EE_Maintenance_Mode__set_maintenance_level', $status);
-        update_option(EE_Maintenance_Mode::OPTION_NAME, $status);
-    }
-
-
-    /**
-     * returns TRUE if M-Mode is engaged and the current request is not for the admin
-     *
-     * @return bool
-     */
-    public static function disable_frontend_for_maintenance(): bool
-    {
-        return ! is_admin() && MaintenanceStatus::isNotDisabled();
-    }
-
-
-    /**
-     * @return void
-     */
-    public function load_assets_required_for_m_mode(): void
-    {
-        if (
-            $this->status === EE_Maintenance_Mode::STATUS_FULL_SITE
-            && ! wp_script_is('espresso_core')
-        ) {
-            wp_register_style(
-                'espresso_default',
-                EE_GLOBAL_ASSETS_URL . 'css/espresso_default.css',
-                ['dashicons'],
-                EVENT_ESPRESSO_VERSION
-            );
-            wp_enqueue_style('espresso_default');
-            wp_register_script(
-                'espresso_core',
-                EE_GLOBAL_ASSETS_URL . 'scripts/espresso_core.js',
-                ['jquery'],
-                EVENT_ESPRESSO_VERSION,
-                true
-            );
-            wp_enqueue_script('espresso_core');
-        }
-    }
-
-
-    /**
-     * replacement EE CPT template that displays message notifying site visitors
-     * that EE has been temporarily placed into maintenance mode
-     * does NOT get called on non-EE-CPT requests
-     *
-     * @return    string
-     */
-    public static function template_include(): string
-    {
-        // shut 'er down for maintenance ? then don't use any of our templates for our endpoints
-        return get_template_directory() . '/index.php';
-    }
-
-
-    /**
-     * displays message notifying site visitors that EE has been temporarily
-     * placed into maintenance mode when post_type != EE CPT
-     *
-     * @param string $the_content
-     * @return string
-     */
-    public function the_content(string $the_content): string
-    {
-        // check if M-mode is engaged and for EE shortcode
-        if ($this->admin_status && strpos($the_content, '[ESPRESSO_') !== false) {
-            // this can eventually be moved to a template, or edited via admin. But for now...
-            $the_content = sprintf(
-                esc_html__(
-                    '%sMaintenance Mode%sEvent Registration has been temporarily closed while system maintenance is being performed. We\'re sorry for any inconveniences this may have caused. Please try back again later.%s',
-                    'event_espresso'
-                ),
-                '<h3>',
-                '</h3><p>',
-                '</p>'
-            );
-        }
-        return $the_content;
-    }
-
-
-    /**
-     * displays message on frontend of site notifying admin that EE has been temporarily placed into maintenance mode
-     */
-    public function display_maintenance_mode_notice()
-    {
-        if (
-            ! $this->current_user_is_admin
-            || $this->status === EE_Maintenance_Mode::STATUS_OFF
-            || $this->request->isAdmin()
-            || $this->request->isAjax()
-            || ! did_action('AHEE__EE_System__load_core_configuration__complete')
-        ) {
-            return;
-        }
-        /** @var CurrentPage $current_page */
-        $current_page = $this->loader->getShared(CurrentPage::class);
-        if ($current_page->isEspressoPage()) {
-            printf(
-                esc_html__(
-                    '%sclose%sEvent Registration is currently disabled because Event Espresso has been placed into Maintenance Mode. To change Maintenance Mode settings, click here %sEE Maintenance Mode Admin Page%s',
-                    'event_espresso'
-                ),
-                '<div id="ee-m-mode-admin-notice-dv" class="ee-really-important-notice-dv"><a class="close-espresso-notice" title="',
-                '"><span class="dashicons dashicons-no"></span></a><p>',
-                ' &raquo; <a href="' . add_query_arg(
-                    ['page' => 'espresso_maintenance_settings'],
-                    admin_url('admin.php')
-                ) . '">',
-                '</a></p></div>'
-            );
-        }
-    }
-    // espresso-notices important-notice ee-attention
-
-
-    /**
-     * Redirects EE admin menu requests to the maintenance page
-     */
-    public function redirect_to_maintenance()
-    {
-        global $pagenow;
-        $page = $this->request->getRequestParam('page', '', DataType::STRING);
-        if (
-            $pagenow == 'admin.php'
-            && $page !== 'espresso_maintenance_settings'
-            && strpos($page, 'espresso_') !== false
-            && $this->status == EE_Maintenance_Mode::STATUS_FULL_SITE
-        ) {
-            EEH_URL::safeRedirectAndExit('admin.php?page=espresso_maintenance_settings');
-        }
-    }
-
-
-    /**
-     * override magic methods
-     */
-    final public function __destruct()
-    {
-    }
-
-
-    final public function __call($a, $b)
-    {
-    }
-
-
-    final public function __get($a)
-    {
-    }
-
-
-    final public function __set($a, $b)
-    {
-    }
-
-
-    final public function __isset($a)
-    {
-    }
-
-
-    final public function __unset($a)
-    {
-    }
-
-
-    final public function __sleep()
-    {
-        return [];
-    }
-
-
-    final public function __wakeup()
-    {
-    }
-
-
-    final public function __invoke()
-    {
-    }
-
-
-    final public static function __set_state($a = null)
-    {
-        return EE_Maintenance_Mode::instance();
-    }
-
-
-    final public function __clone()
-    {
-    }
-
-
-    final public static function __callStatic($a, $b)
-    {
-    }
+	/**
+	 * constants available to client code for interpreting the values of EE_Maintenance_Mode::level().
+	 * STATUS_OFF means the site is NOT in maintenance mode (so everything's normal)
+	 */
+	public const STATUS_OFF = 0;
+
+
+	/**
+	 * STATUS_PUBLIC_ONLY means that the site's frontend EE code should be completely disabled
+	 * but the admin backend should be running as normal. Maybe an admin can view the frontend though
+	 */
+	public const STATUS_PUBLIC_ONLY = 1;
+
+	/**
+	 * STATUS_FULL_SITE means the frontend AND EE backend code are disabled. The only system running
+	 * is the maintenance mode stuff, which will require users to update all addons, and then finish running all
+	 * migration scripts before taking the site out of maintenance mode
+	 */
+	public const STATUS_FULL_SITE = 2;
+
+	/**
+	 * the name of the option which stores the current level of maintenance mode
+	 */
+	private const OPTION_NAME = 'ee_maintenance_mode';
+
+
+	protected LoaderInterface $loader;
+
+	private RequestInterface $request;
+
+	private static ?EE_Maintenance_Mode $_instance = null;
+
+	/**
+	 * @var int
+	 * @since 5.0.12.p
+	 */
+	private int $status;
+
+	/**
+	 * @var int
+	 * @since 5.0.12.p
+	 */
+	private int $admin_status;
+
+	/**
+	 * true if current_user_can('administrator')
+	 *
+	 * @var bool
+	 * @since 5.0.12.p
+	 */
+	private bool $current_user_is_admin;
+
+	/**
+	 * used to control updates to the WP options setting in the database
+	 *
+	 * @var bool
+	 * @since 5.0.12.p
+	 */
+	private bool $update_db;
+
+
+	/**
+	 * @singleton method used to instantiate class object
+	 * @param LoaderInterface|null  $loader
+	 * @param RequestInterface|null $request
+	 * @return EE_Maintenance_Mode|null
+	 */
+	public static function instance(
+		?LoaderInterface $loader = null,
+		?RequestInterface $request = null
+	): ?EE_Maintenance_Mode {
+		// check if class object is instantiated
+		if (! self::$_instance instanceof EE_Maintenance_Mode) {
+			self::$_instance = new EE_Maintenance_Mode($loader, $request);
+		}
+		return self::$_instance;
+	}
+
+
+	/**
+	 * Resets maintenance mode (mostly just re-checks whether we should be in maintenance mode)
+	 *
+	 * @return EE_Maintenance_Mode|null
+	 * @throws EE_Error
+	 */
+	public static function reset(): ?EE_Maintenance_Mode
+	{
+		self::instance()->set_maintenance_mode_if_db_old();
+		self::instance()->initialize();
+		return self::instance();
+	}
+
+
+	/**
+	 *private constructor to prevent direct creation
+	 */
+	private function __construct(LoaderInterface $loader, RequestInterface $request)
+	{
+		$this->loader                = $loader;
+		$this->request               = $request;
+		$this->initialize();
+
+		// if M-Mode level 2 is engaged, we still need basic assets loaded
+		add_action('wp_enqueue_scripts', [$this, 'load_assets_required_for_m_mode']);
+		// shut 'er down for maintenance ?
+		add_filter('the_content', [$this, 'the_content'], 2);
+		// redirect ee menus to maintenance page
+		add_action('admin_page_access_denied', [$this, 'redirect_to_maintenance']);
+		// add powered by EE msg
+		add_action('shutdown', [$this, 'display_maintenance_mode_notice']);
+	}
+
+
+	private function initialize(): void
+	{
+		$this->current_user_is_admin = current_user_can('administrator');
+		// now make sure the status is set correctly everywhere
+		// (but don't update the db else we'll get into an infinite loop of updates)
+		$this->update_db = false;
+		$this->set_maintenance_level($this->loadStatusFromDatabase());
+		$this->update_db = true;
+	}
+
+
+	private function loadStatusFromDatabase(): int
+	{
+		return (int) get_option(EE_Maintenance_Mode::OPTION_NAME, EE_Maintenance_Mode::STATUS_OFF);
+	}
+
+
+	/**
+	 * changes the maintenance mode level to reflect whether the current user is an admin or not.
+	 * Determines whether we're in maintenance mode and what level. However, while the site
+	 * is in level 1 maintenance, and an admin visits the frontend, this function makes it appear
+	 * to them as if the site isn't in maintenance mode.
+	 *      EE_Maintenance_Mode::STATUS_OFF => not in maintenance mode (in normal mode)
+	 *      EE_Maintenance_Mode::STATUS_PUBLIC_ONLY=> frontend-only maintenance mode
+	 *      EE_Maintenance_Mode::STATUS_FULL_SITE => frontend and backend maintenance mode
+	 *
+	 * @param int $status
+	 * @return void
+	 * @since 5.0.12.p
+	 */
+	private function setAdminStatus(int $status)
+	{
+		if (
+			$status === EE_Maintenance_Mode::STATUS_PUBLIC_ONLY
+			&& $this->current_user_is_admin
+			&& ($this->request->isAjax() || ! $this->request->isAdmin())
+		) {
+			$status = EE_Maintenance_Mode::STATUS_OFF;
+		}
+		$this->admin_status = $status;
+	}
+
+
+	public function real_level(): int
+	{
+		return $this->status;
+	}
+
+
+	/**
+	 * @return int
+	 */
+	public function level(): int
+	{
+		return $this->admin_status;
+	}
+
+
+	/**
+	 * Determines if we need to put EE in maintenance mode because the database needs updating
+	 *
+	 * @return boolean true if DB is old and maintenance mode was triggered; false otherwise
+	 * @throws EE_Error
+	 */
+	public function set_maintenance_mode_if_db_old(): bool
+	{
+		/** @var EE_Data_Migration_Manager $data_migration_manager */
+		$data_migration_manager = $this->loader->getShared(EE_Data_Migration_Manager::class );
+		$scripts_that_should_run = $data_migration_manager->check_for_applicable_data_migration_scripts();
+		if (! empty($scripts_that_should_run)) { //  && $this->status !== EE_Maintenance_Mode::STATUS_FULL_SITE
+			$this->activateFullSiteMaintenanceMode();
+			return true;
+		}
+		if ($this->status === EE_Maintenance_Mode::STATUS_FULL_SITE) {
+			// we also want to handle the opposite: if the site is mm2, but there aren't any migrations to run
+			// then we shouldn't be in mm2. (Maybe an addon got deactivated?)
+			$this->deactivateMaintenanceMode();
+		}
+		return false;
+	}
+
+
+	/**
+	 * Updates the maintenance level on the site
+	 *
+	 * @param int $level
+	 * @return void
+	 */
+	public function set_maintenance_level(int $level): void
+	{
+		switch ($level) {
+			case EE_Maintenance_Mode::STATUS_OFF:
+				$this->deactivateMaintenanceMode();
+				return;
+			case EE_Maintenance_Mode::STATUS_PUBLIC_ONLY:
+				$this->activatePublicOnlyMaintenanceMode();
+				return;
+			case EE_Maintenance_Mode::STATUS_FULL_SITE:
+				$this->activateFullSiteMaintenanceMode();
+				return;
+		}
+		throw new DomainException(
+			sprintf(
+				esc_html__(
+					'"%1$s" is not valid a EE maintenance mode level. Please choose from one of the following: %2$s',
+					'event_espresso'
+				),
+				$level,
+				'EE_Maintenance_Mode::STATUS_OFF, EE_Maintenance_Mode::STATUS_PUBLIC_ONLY, EE_Maintenance_Mode::STATUS_FULL_SITE',
+			)
+		);
+	}
+
+
+	/**
+	 * sets database status to online
+	 * sets maintenance mode status to public only, unless current user is an admin, then maintenance mode is disabled
+	 *
+	 * @return void
+	 * @since 5.0.12.p
+	 */
+	public function activatePublicOnlyMaintenanceMode()
+	{
+		DbStatus::setOnline();
+		// disable maintenance mode for admins, otherwise enable public only maintenance mode
+		if ($this->current_user_is_admin) {
+			MaintenanceStatus::disableMaintenanceMode();
+		} else {
+			MaintenanceStatus::setPublicOnlyMaintenanceMode();
+		}
+		$this->updateMaintenaceModeStatus(EE_Maintenance_Mode::STATUS_PUBLIC_ONLY);
+	}
+
+
+	/**
+	 * sets database status to offline
+	 * sets maintenance mode status to full site
+	 *
+	 * @return void
+	 * @since 5.0.12.p
+	 */
+	public function activateFullSiteMaintenanceMode()
+	{
+		DbStatus::setOffline();
+		MaintenanceStatus::setFullSiteMaintenanceMode();
+		$this->updateMaintenaceModeStatus(EE_Maintenance_Mode::STATUS_FULL_SITE);
+	}
+
+
+	/**
+	 * sets database status to online
+	 * turns maintenance mode off
+	 *
+	 * @return void
+	 * @since 5.0.12.p
+	 */
+	public function deactivateMaintenanceMode()
+	{
+		DbStatus::setOnline();
+		MaintenanceStatus::disableMaintenanceMode();
+		$this->updateMaintenaceModeStatus(EE_Maintenance_Mode::STATUS_OFF);
+	}
+
+
+	private function updateMaintenaceModeStatus(int $status)
+	{
+		$this->status = $status;
+		$this->setAdminStatus($status);
+		if (! $this->update_db) {
+			return;
+		}
+		do_action('AHEE__EE_Maintenance_Mode__set_maintenance_level', $status);
+		update_option(EE_Maintenance_Mode::OPTION_NAME, $status);
+	}
+
+
+	/**
+	 * returns TRUE if M-Mode is engaged and the current request is not for the admin
+	 *
+	 * @return bool
+	 */
+	public static function disable_frontend_for_maintenance(): bool
+	{
+		return ! is_admin() && MaintenanceStatus::isNotDisabled();
+	}
+
+
+	/**
+	 * @return void
+	 */
+	public function load_assets_required_for_m_mode(): void
+	{
+		if (
+			$this->status === EE_Maintenance_Mode::STATUS_FULL_SITE
+			&& ! wp_script_is('espresso_core')
+		) {
+			wp_register_style(
+				'espresso_default',
+				EE_GLOBAL_ASSETS_URL . 'css/espresso_default.css',
+				['dashicons'],
+				EVENT_ESPRESSO_VERSION
+			);
+			wp_enqueue_style('espresso_default');
+			wp_register_script(
+				'espresso_core',
+				EE_GLOBAL_ASSETS_URL . 'scripts/espresso_core.js',
+				['jquery'],
+				EVENT_ESPRESSO_VERSION,
+				true
+			);
+			wp_enqueue_script('espresso_core');
+		}
+	}
+
+
+	/**
+	 * replacement EE CPT template that displays message notifying site visitors
+	 * that EE has been temporarily placed into maintenance mode
+	 * does NOT get called on non-EE-CPT requests
+	 *
+	 * @return    string
+	 */
+	public static function template_include(): string
+	{
+		// shut 'er down for maintenance ? then don't use any of our templates for our endpoints
+		return get_template_directory() . '/index.php';
+	}
+
+
+	/**
+	 * displays message notifying site visitors that EE has been temporarily
+	 * placed into maintenance mode when post_type != EE CPT
+	 *
+	 * @param string $the_content
+	 * @return string
+	 */
+	public function the_content(string $the_content): string
+	{
+		// check if M-mode is engaged and for EE shortcode
+		if ($this->admin_status && strpos($the_content, '[ESPRESSO_') !== false) {
+			// this can eventually be moved to a template, or edited via admin. But for now...
+			$the_content = sprintf(
+				esc_html__(
+					'%sMaintenance Mode%sEvent Registration has been temporarily closed while system maintenance is being performed. We\'re sorry for any inconveniences this may have caused. Please try back again later.%s',
+					'event_espresso'
+				),
+				'<h3>',
+				'</h3><p>',
+				'</p>'
+			);
+		}
+		return $the_content;
+	}
+
+
+	/**
+	 * displays message on frontend of site notifying admin that EE has been temporarily placed into maintenance mode
+	 */
+	public function display_maintenance_mode_notice()
+	{
+		if (
+			! $this->current_user_is_admin
+			|| $this->status === EE_Maintenance_Mode::STATUS_OFF
+			|| $this->request->isAdmin()
+			|| $this->request->isAjax()
+			|| ! did_action('AHEE__EE_System__load_core_configuration__complete')
+		) {
+			return;
+		}
+		/** @var CurrentPage $current_page */
+		$current_page = $this->loader->getShared(CurrentPage::class);
+		if ($current_page->isEspressoPage()) {
+			printf(
+				esc_html__(
+					'%sclose%sEvent Registration is currently disabled because Event Espresso has been placed into Maintenance Mode. To change Maintenance Mode settings, click here %sEE Maintenance Mode Admin Page%s',
+					'event_espresso'
+				),
+				'<div id="ee-m-mode-admin-notice-dv" class="ee-really-important-notice-dv"><a class="close-espresso-notice" title="',
+				'"><span class="dashicons dashicons-no"></span></a><p>',
+				' &raquo; <a href="' . add_query_arg(
+					['page' => 'espresso_maintenance_settings'],
+					admin_url('admin.php')
+				) . '">',
+				'</a></p></div>'
+			);
+		}
+	}
+	// espresso-notices important-notice ee-attention
+
+
+	/**
+	 * Redirects EE admin menu requests to the maintenance page
+	 */
+	public function redirect_to_maintenance()
+	{
+		global $pagenow;
+		$page = $this->request->getRequestParam('page', '', DataType::STRING);
+		if (
+			$pagenow == 'admin.php'
+			&& $page !== 'espresso_maintenance_settings'
+			&& strpos($page, 'espresso_') !== false
+			&& $this->status == EE_Maintenance_Mode::STATUS_FULL_SITE
+		) {
+			EEH_URL::safeRedirectAndExit('admin.php?page=espresso_maintenance_settings');
+		}
+	}
+
+
+	/**
+	 * override magic methods
+	 */
+	final public function __destruct()
+	{
+	}
+
+
+	final public function __call($a, $b)
+	{
+	}
+
+
+	final public function __get($a)
+	{
+	}
+
+
+	final public function __set($a, $b)
+	{
+	}
+
+
+	final public function __isset($a)
+	{
+	}
+
+
+	final public function __unset($a)
+	{
+	}
+
+
+	final public function __sleep()
+	{
+		return [];
+	}
+
+
+	final public function __wakeup()
+	{
+	}
+
+
+	final public function __invoke()
+	{
+	}
+
+
+	final public static function __set_state($a = null)
+	{
+		return EE_Maintenance_Mode::instance();
+	}
+
+
+	final public function __clone()
+	{
+	}
+
+
+	final public static function __callStatic($a, $b)
+	{
+	}
 
 
-    /************************ @DEPRECATED ********************** */
+	/************************ @DEPRECATED ********************** */
 
-    /**
-     * @depecated 5.0.12.p
-     */
-    const level_0_not_in_maintenance = 0;
+	/**
+	 * @depecated 5.0.12.p
+	 */
+	const level_0_not_in_maintenance = 0;
 
-    /**
-     * @depecated 5.0.12.p
-     */
-    const level_1_frontend_only_maintenance = 1;
+	/**
+	 * @depecated 5.0.12.p
+	 */
+	const level_1_frontend_only_maintenance = 1;
 
-    /**
-     * @depecated 5.0.12.p
-     */
-    const level_2_complete_maintenance = 2;
+	/**
+	 * @depecated 5.0.12.p
+	 */
+	const level_2_complete_maintenance = 2;
 
-    /**
-     * @depecated 5.0.12.p
-     */
-    const option_name_maintenance_mode = 'ee_maintenance_mode';
+	/**
+	 * @depecated 5.0.12.p
+	 */
+	const option_name_maintenance_mode = 'ee_maintenance_mode';
 
 
-    /**
-     * Returns whether the models reportedly are able to run queries or not
-     * (ie, if the system thinks their tables are present and up-to-date).
-     *
-     * @return boolean
-     * @depecated 5.0.12.p
-     */
-    public function models_can_query(): bool
-    {
-        return DbStatus::isOnline();
-    }
+	/**
+	 * Returns whether the models reportedly are able to run queries or not
+	 * (ie, if the system thinks their tables are present and up-to-date).
+	 *
+	 * @return boolean
+	 * @depecated 5.0.12.p
+	 */
+	public function models_can_query(): bool
+	{
+		return DbStatus::isOnline();
+	}
 }

Spacing +9 added lines, -9 removed lines

@@ -91,7 +91,7 @@ 
         ?RequestInterface $request = null
     ): ?EE_Maintenance_Mode {
         // check if class object is instantiated
-        if (! self::$_instance instanceof EE_Maintenance_Mode) {
+        if ( ! self::$_instance instanceof EE_Maintenance_Mode) {
             self::$_instance = new EE_Maintenance_Mode($loader, $request);
         }
         return self::$_instance;
@@ -199,9 +199,9 @@ 
     public function set_maintenance_mode_if_db_old(): bool
     {
         /** @var EE_Data_Migration_Manager $data_migration_manager */
-        $data_migration_manager = $this->loader->getShared(EE_Data_Migration_Manager::class );
+        $data_migration_manager = $this->loader->getShared(EE_Data_Migration_Manager::class);
         $scripts_that_should_run = $data_migration_manager->check_for_applicable_data_migration_scripts();
-        if (! empty($scripts_that_should_run)) { //  && $this->status !== EE_Maintenance_Mode::STATUS_FULL_SITE
+        if ( ! empty($scripts_that_should_run)) { //  && $this->status !== EE_Maintenance_Mode::STATUS_FULL_SITE
             $this->activateFullSiteMaintenanceMode();
             return true;
         }
@@ -300,7 +300,7 @@ 
     {
         $this->status = $status;
         $this->setAdminStatus($status);
-        if (! $this->update_db) {
+        if ( ! $this->update_db) {
             return;
         }
         do_action('AHEE__EE_Maintenance_Mode__set_maintenance_level', $status);
@@ -330,14 +330,14 @@ 
         ) {
             wp_register_style(
                 'espresso_default',
-                EE_GLOBAL_ASSETS_URL . 'css/espresso_default.css',
+                EE_GLOBAL_ASSETS_URL.'css/espresso_default.css',
                 ['dashicons'],
                 EVENT_ESPRESSO_VERSION
             );
             wp_enqueue_style('espresso_default');
             wp_register_script(
                 'espresso_core',
-                EE_GLOBAL_ASSETS_URL . 'scripts/espresso_core.js',
+                EE_GLOBAL_ASSETS_URL.'scripts/espresso_core.js',
                 ['jquery'],
                 EVENT_ESPRESSO_VERSION,
                 true
@@ -357,7 +357,7 @@ 
     public static function template_include(): string
     {
         // shut 'er down for maintenance ? then don't use any of our templates for our endpoints
-        return get_template_directory() . '/index.php';
+        return get_template_directory().'/index.php';
     }
 
 
@@ -411,10 +411,10 @@ 
                 ),
                 '<div id="ee-m-mode-admin-notice-dv" class="ee-really-important-notice-dv"><a class="close-espresso-notice" title="',
                 '"><span class="dashicons dashicons-no"></span></a><p>',
-                ' &raquo; <a href="' . add_query_arg(
+                ' &raquo; <a href="'.add_query_arg(
                     ['page' => 'espresso_maintenance_settings'],
                     admin_url('admin.php')
-                ) . '">',
+                ).'">',
                 '</a></p></div>'
             );
         }

core/libraries/shortcodes/EE_Event_Author_Shortcodes.lib.php

Indentation +106 added lines, -106 removed lines

@@ -19,121 +19,121 @@
  */
 class EE_Event_Author_Shortcodes extends EE_Shortcodes
 {
-    protected function _init_props()
-    {
-        $this->label       = esc_html__('Event Author Details Shortcodes', 'event_espresso');
-        $this->description = esc_html__('All shortcodes specific to event_author data', 'event_espresso');
-        $this->_shortcodes = [
-            '[EVENT_AUTHOR_FNAME]'           => esc_html__(
-                'Parses to the first name of the event author.',
-                'event_espresso'
-            ),
-            '[EVENT_AUTHOR_LNAME]'           => esc_html__(
-                'Parses to the last name of the event author.',
-                'event_espresso'
-            ),
-            '[EVENT_AUTHOR_FORMATTED_EMAIL]' => esc_html__(
-                'Parses to a formatted email address of the event author (fname lname &lt;email@address.com&gt;).  <strong>NOTE:</strong> If the event author has not filled out their WordPress user profile then the organization name will be used as the "From" name.',
-                'event_espresso'
-            ),
-            '[EVENT_AUTHOR_EMAIL]'           => esc_html__(
-                'Parses to the unformatted email address of the event author',
-                'event_espresso'
-            ),
-        ];
-    }
+	protected function _init_props()
+	{
+		$this->label       = esc_html__('Event Author Details Shortcodes', 'event_espresso');
+		$this->description = esc_html__('All shortcodes specific to event_author data', 'event_espresso');
+		$this->_shortcodes = [
+			'[EVENT_AUTHOR_FNAME]'           => esc_html__(
+				'Parses to the first name of the event author.',
+				'event_espresso'
+			),
+			'[EVENT_AUTHOR_LNAME]'           => esc_html__(
+				'Parses to the last name of the event author.',
+				'event_espresso'
+			),
+			'[EVENT_AUTHOR_FORMATTED_EMAIL]' => esc_html__(
+				'Parses to a formatted email address of the event author (fname lname &lt;email@address.com&gt;).  <strong>NOTE:</strong> If the event author has not filled out their WordPress user profile then the organization name will be used as the "From" name.',
+				'event_espresso'
+			),
+			'[EVENT_AUTHOR_EMAIL]'           => esc_html__(
+				'Parses to the unformatted email address of the event author',
+				'event_espresso'
+			),
+		];
+	}
 
 
-    /**
-     * @param string $shortcode
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    protected function _parser($shortcode)
-    {
-        // make sure we end up with a copy of the EE_Messages_Addressee object
-        $recipient = $this->_data instanceof EE_Messages_Addressee ? $this->_data : null;
-        $recipient = ! $recipient instanceof EE_Messages_Addressee
-            && is_array($this->_data)
-            && isset($this->_data['data'])
-            && $this->_data['data'] instanceof EE_Messages_Addressee
-                ? $this->_data['data']
-                : $recipient;
-        $recipient = ! $recipient instanceof EE_Messages_Addressee
-            && ! empty($this->_extra_data['data'])
-            && $this->_extra_data['data'] instanceof EE_Messages_Addressee
-                ? $this->_extra_data['data']
-                : $recipient;
+	/**
+	 * @param string $shortcode
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	protected function _parser($shortcode)
+	{
+		// make sure we end up with a copy of the EE_Messages_Addressee object
+		$recipient = $this->_data instanceof EE_Messages_Addressee ? $this->_data : null;
+		$recipient = ! $recipient instanceof EE_Messages_Addressee
+			&& is_array($this->_data)
+			&& isset($this->_data['data'])
+			&& $this->_data['data'] instanceof EE_Messages_Addressee
+				? $this->_data['data']
+				: $recipient;
+		$recipient = ! $recipient instanceof EE_Messages_Addressee
+			&& ! empty($this->_extra_data['data'])
+			&& $this->_extra_data['data'] instanceof EE_Messages_Addressee
+				? $this->_extra_data['data']
+				: $recipient;
 
-        // now it's possible that $recipient is not an instance of EE_Messages_Addressee in which case we need to see if $this->_data is an instance of $event.
-        $event = $this->_data instanceof EE_Event ? $this->_data : null;
+		// now it's possible that $recipient is not an instance of EE_Messages_Addressee in which case we need to see if $this->_data is an instance of $event.
+		$event = $this->_data instanceof EE_Event ? $this->_data : null;
 
-        if (! $recipient instanceof EE_Messages_Addressee && ! $event instanceof EE_Event) {
-            return '';
-        }
+		if (! $recipient instanceof EE_Messages_Addressee && ! $event instanceof EE_Event) {
+			return '';
+		}
 
-        switch ($shortcode) {
-            case '[EVENT_AUTHOR_FNAME]':
-                $fname = ! empty($recipient) ? $recipient->fname : null;
-                if (empty($fname) && ! empty($event)) {
-                    $user  = $this->_get_author_for_event($event);
-                    $fname = $user->first_name;
-                }
-                return $fname;
+		switch ($shortcode) {
+			case '[EVENT_AUTHOR_FNAME]':
+				$fname = ! empty($recipient) ? $recipient->fname : null;
+				if (empty($fname) && ! empty($event)) {
+					$user  = $this->_get_author_for_event($event);
+					$fname = $user->first_name;
+				}
+				return $fname;
 
-            case '[EVENT_AUTHOR_LNAME]':
-                $lname = ! empty($recipient) ? $recipient->lname : null;
-                if (empty($lname) && ! empty($event)) {
-                    $user  = $this->_get_author_for_event($event);
-                    $lname = $user->last_name;
-                }
-                return $lname;
+			case '[EVENT_AUTHOR_LNAME]':
+				$lname = ! empty($recipient) ? $recipient->lname : null;
+				if (empty($lname) && ! empty($event)) {
+					$user  = $this->_get_author_for_event($event);
+					$lname = $user->last_name;
+				}
+				return $lname;
 
-            case '[EVENT_AUTHOR_FORMATTED_EMAIL]':
-                if (! empty($recipient)) {
-                    $email = ! empty($recipient->fname)
-                        ? $recipient->fname . ' ' . $recipient->lname . '<' . $recipient->admin_email . '>'
-                        : EE_Registry::instance()->CFG->organization->get_pretty(
-                            'name'
-                        ) . '<' . $recipient->admin_email . '>';
-                } else {
-                    $email = null;
-                }
-                if (empty($email) && ! empty($event)) {
-                    $user  = $this->_get_author_for_event($event);
-                    $email = ! empty($user->first_name)
-                        ? $user->first_name . ' ' . $user->last_name . '<' . $user->user_email . '>'
-                        : EE_Registry::instance()->CFG->organization->get_pretty(
-                            'name'
-                        ) . '<' . $user->user_email . '>';
-                }
-                return $email;
+			case '[EVENT_AUTHOR_FORMATTED_EMAIL]':
+				if (! empty($recipient)) {
+					$email = ! empty($recipient->fname)
+						? $recipient->fname . ' ' . $recipient->lname . '<' . $recipient->admin_email . '>'
+						: EE_Registry::instance()->CFG->organization->get_pretty(
+							'name'
+						) . '<' . $recipient->admin_email . '>';
+				} else {
+					$email = null;
+				}
+				if (empty($email) && ! empty($event)) {
+					$user  = $this->_get_author_for_event($event);
+					$email = ! empty($user->first_name)
+						? $user->first_name . ' ' . $user->last_name . '<' . $user->user_email . '>'
+						: EE_Registry::instance()->CFG->organization->get_pretty(
+							'name'
+						) . '<' . $user->user_email . '>';
+				}
+				return $email;
 
-            case '[EVENT_AUTHOR_EMAIL]':
-                $email = ! empty($recipient) ? $recipient->admin_email : null;
-                if (empty($email) && ! empty($event)) {
-                    $user  = $this->_get_author_for_event($event);
-                    $email = $user instanceof WP_User ? $user->user_email : '';
-                }
-                return $email;
+			case '[EVENT_AUTHOR_EMAIL]':
+				$email = ! empty($recipient) ? $recipient->admin_email : null;
+				if (empty($email) && ! empty($event)) {
+					$user  = $this->_get_author_for_event($event);
+					$email = $user instanceof WP_User ? $user->user_email : '';
+				}
+				return $email;
 
-            default:
-                return '';
-        }
-    }
+			default:
+				return '';
+		}
+	}
 
 
-    /**
-     * Helper method to return the user object for the author of the given EE_Event
-     *
-     * @param EE_Event $event
-     *
-     * @return WP_User|false
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    private function _get_author_for_event(EE_Event $event)
-    {
-        return get_userdata($event->wp_user());
-    }
+	/**
+	 * Helper method to return the user object for the author of the given EE_Event
+	 *
+	 * @param EE_Event $event
+	 *
+	 * @return WP_User|false
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	private function _get_author_for_event(EE_Event $event)
+	{
+		return get_userdata($event->wp_user());
+	}
 }

Spacing +6 added lines, -6 removed lines

@@ -68,7 +68,7 @@ 
         // now it's possible that $recipient is not an instance of EE_Messages_Addressee in which case we need to see if $this->_data is an instance of $event.
         $event = $this->_data instanceof EE_Event ? $this->_data : null;
 
-        if (! $recipient instanceof EE_Messages_Addressee && ! $event instanceof EE_Event) {
+        if ( ! $recipient instanceof EE_Messages_Addressee && ! $event instanceof EE_Event) {
             return '';
         }
 
@@ -90,22 +90,22 @@ 
                 return $lname;
 
             case '[EVENT_AUTHOR_FORMATTED_EMAIL]':
-                if (! empty($recipient)) {
+                if ( ! empty($recipient)) {
                     $email = ! empty($recipient->fname)
-                        ? $recipient->fname . ' ' . $recipient->lname . '<' . $recipient->admin_email . '>'
+                        ? $recipient->fname.' '.$recipient->lname.'<'.$recipient->admin_email.'>'
                         : EE_Registry::instance()->CFG->organization->get_pretty(
                             'name'
-                        ) . '<' . $recipient->admin_email . '>';
+                        ).'<'.$recipient->admin_email.'>';
                 } else {
                     $email = null;
                 }
                 if (empty($email) && ! empty($event)) {
                     $user  = $this->_get_author_for_event($event);
                     $email = ! empty($user->first_name)
-                        ? $user->first_name . ' ' . $user->last_name . '<' . $user->user_email . '>'
+                        ? $user->first_name.' '.$user->last_name.'<'.$user->user_email.'>'
                         : EE_Registry::instance()->CFG->organization->get_pretty(
                             'name'
-                        ) . '<' . $user->user_email . '>';
+                        ).'<'.$user->user_email.'>';
                 }
                 return $email;
 

core/libraries/rest_api/ModelDataTranslator.php

Indentation +660 added lines, -660 removed lines

@@ -39,664 +39,664 @@
  */
 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_maybe_array
-     * @param string              $requested_version
-     * @param string|null         $timezone_string treat values as being in this timezone
-     * @return mixed
-     * @throws RestException
-     * @throws EE_Error
-     */
-    public static function prepareFieldValuesFromJson(
-        EE_Model_Field_Base $field_obj,
-        $original_value_maybe_array,
-        string $requested_version,
-        ?string $timezone_string = 'UTC'
-    ) {
-        if (
-            is_array($original_value_maybe_array)
-            && ! $field_obj instanceof EE_Serialized_Text_Field
-        ) {
-            $new_value_maybe_array = [];
-            foreach ($original_value_maybe_array as $array_key => $array_item) {
-                $new_value_maybe_array[ $array_key ] = ModelDataTranslator::prepareFieldValueFromJson(
-                    $field_obj,
-                    $array_item,
-                    $requested_version,
-                    $timezone_string
-                );
-            }
-        } else {
-            $new_value_maybe_array = ModelDataTranslator::prepareFieldValueFromJson(
-                $field_obj,
-                $original_value_maybe_array,
-                $requested_version,
-                $timezone_string
-            );
-        }
-        return $new_value_maybe_array;
-    }
-
-
-    /**
-     * Prepares an array of field values FOR use in JSON/REST API
-     *
-     * @param EE_Model_Field_Base $field_obj
-     * @param mixed               $original_value_maybe_array
-     * @param string              $request_version (eg 4.8.36)
-     * @return array|int|string
-     * @throws EE_Error
-     * @throws EE_Error
-     */
-    public static function prepareFieldValuesForJson(
-        EE_Model_Field_Base $field_obj,
-        $original_value_maybe_array,
-        string $request_version
-    ) {
-        if (is_array($original_value_maybe_array)) {
-            $new_value = [];
-            foreach ($original_value_maybe_array as $key => $value) {
-                $new_value[ $key ] = ModelDataTranslator::prepareFieldValuesForJson(
-                    $field_obj,
-                    $value,
-                    $request_version
-                );
-            }
-        } else {
-            $new_value = ModelDataTranslator::prepareFieldValueForJson(
-                $field_obj,
-                $original_value_maybe_array,
-                $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|null         $timezone_string treat values as being in this timezone
-     * @return mixed
-     * @throws RestException
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws Exception
-     */
-    public static function prepareFieldValueFromJson(
-        EE_Model_Field_Base $field_obj,
-        $original_value,
-        string $requested_version,
-        ?string $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,
-                ]
-            );
-        }
-        // 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);
-        $new_value = $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) {
-            if (! (empty($original_value) && $field_obj->is_nullable())) {
-                $new_value = rest_parse_date(
-                    self::getTimestampWithTimezoneOffset($original_value, $field_obj, $timezone_string)
-                );
-                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);
-        }
-        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|null       $original_timestamp
-     * @param EE_Datetime_Field $datetime_field
-     * @param string|null       $timezone_string
-     * @return string
-     * @throws DomainException
-     * @throws Exception
-     */
-    private static function getTimestampWithTimezoneOffset(
-        ?string $original_timestamp,
-        EE_Datetime_Field $datetime_field,
-        ?string $timezone_string
-    ): ?string {
-        // already have timezone information?
-        if (preg_match('/Z|([+-])(\d{2}:\d{2})/', (string) $original_timestamp)) {
-            // yes, we're ignoring the timezone.
-            return $original_timestamp;
-        }
-        // need to append timezone
-        [$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|string|null $timezone_offset
-     * @return array
-     */
-    private static function parseTimezoneOffset($timezone_offset): array
-    {
-        $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|null $field_obj
-     * @param mixed                    $original_value
-     * @param string                   $requested_version
-     * @return mixed
-     * @throws EE_Error
-     * @throws EE_Error
-     * @throws Exception
-     */
-    public static function prepareFieldValueForJson(
-        ?EE_Model_Field_Base $field_obj,
-        $original_value,
-        string $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 it's 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 it's 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) {
-                $new_value = mysql2date('Y-m-d\TH:i:s', $new_value, false);
-            }
-        } 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
-     */
-    public static function prepareConditionsQueryParamsForModels(
-        array $inputted_query_params_of_this_type,
-        EEM_Base $model,
-        string $requested_version,
-        bool $writing = false
-    ): array {
-        $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 (
-                    (isset($query_param_for_models[ $query_param_meta->getQueryParamKey() ])
-                        && $query_param_meta->isGmtField())
-                    || $translated_value === null
-                ) {
-                    // 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 it's a
-     * gmt date field name
-     *
-     * @param string $field_name
-     * @return boolean
-     */
-    public static function isGmtDateFieldName(string $field_name): bool
-    {
-        $field_name = ModelDataTranslator::removeStarsAndAnythingAfterFromConditionQueryParamKey($field_name);
-        return substr($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(string $field_name): string
-    {
-        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(string $field_name): string
-    {
-        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): array
-    {
-        $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): array
-    {
-        $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|null $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,
-        ?string $requested_version = ''
-    ): array {
-        if (! $requested_version) {
-            $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 RestException if somehow a PHP object were in the query param's 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(
-        array $inputted_query_params_of_this_type,
-        EEM_Base $model,
-        string $requested_version
-    ): array {
-        $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): string
-    {
-        $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(string $query_param_name, EEM_Base $model): ?EE_Model_Field_Base
-    {
-        // 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): bool
-    {
-        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_maybe_array
+	 * @param string              $requested_version
+	 * @param string|null         $timezone_string treat values as being in this timezone
+	 * @return mixed
+	 * @throws RestException
+	 * @throws EE_Error
+	 */
+	public static function prepareFieldValuesFromJson(
+		EE_Model_Field_Base $field_obj,
+		$original_value_maybe_array,
+		string $requested_version,
+		?string $timezone_string = 'UTC'
+	) {
+		if (
+			is_array($original_value_maybe_array)
+			&& ! $field_obj instanceof EE_Serialized_Text_Field
+		) {
+			$new_value_maybe_array = [];
+			foreach ($original_value_maybe_array as $array_key => $array_item) {
+				$new_value_maybe_array[ $array_key ] = ModelDataTranslator::prepareFieldValueFromJson(
+					$field_obj,
+					$array_item,
+					$requested_version,
+					$timezone_string
+				);
+			}
+		} else {
+			$new_value_maybe_array = ModelDataTranslator::prepareFieldValueFromJson(
+				$field_obj,
+				$original_value_maybe_array,
+				$requested_version,
+				$timezone_string
+			);
+		}
+		return $new_value_maybe_array;
+	}
+
+
+	/**
+	 * Prepares an array of field values FOR use in JSON/REST API
+	 *
+	 * @param EE_Model_Field_Base $field_obj
+	 * @param mixed               $original_value_maybe_array
+	 * @param string              $request_version (eg 4.8.36)
+	 * @return array|int|string
+	 * @throws EE_Error
+	 * @throws EE_Error
+	 */
+	public static function prepareFieldValuesForJson(
+		EE_Model_Field_Base $field_obj,
+		$original_value_maybe_array,
+		string $request_version
+	) {
+		if (is_array($original_value_maybe_array)) {
+			$new_value = [];
+			foreach ($original_value_maybe_array as $key => $value) {
+				$new_value[ $key ] = ModelDataTranslator::prepareFieldValuesForJson(
+					$field_obj,
+					$value,
+					$request_version
+				);
+			}
+		} else {
+			$new_value = ModelDataTranslator::prepareFieldValueForJson(
+				$field_obj,
+				$original_value_maybe_array,
+				$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|null         $timezone_string treat values as being in this timezone
+	 * @return mixed
+	 * @throws RestException
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws Exception
+	 */
+	public static function prepareFieldValueFromJson(
+		EE_Model_Field_Base $field_obj,
+		$original_value,
+		string $requested_version,
+		?string $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,
+				]
+			);
+		}
+		// 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);
+		$new_value = $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) {
+			if (! (empty($original_value) && $field_obj->is_nullable())) {
+				$new_value = rest_parse_date(
+					self::getTimestampWithTimezoneOffset($original_value, $field_obj, $timezone_string)
+				);
+				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);
+		}
+		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|null       $original_timestamp
+	 * @param EE_Datetime_Field $datetime_field
+	 * @param string|null       $timezone_string
+	 * @return string
+	 * @throws DomainException
+	 * @throws Exception
+	 */
+	private static function getTimestampWithTimezoneOffset(
+		?string $original_timestamp,
+		EE_Datetime_Field $datetime_field,
+		?string $timezone_string
+	): ?string {
+		// already have timezone information?
+		if (preg_match('/Z|([+-])(\d{2}:\d{2})/', (string) $original_timestamp)) {
+			// yes, we're ignoring the timezone.
+			return $original_timestamp;
+		}
+		// need to append timezone
+		[$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|string|null $timezone_offset
+	 * @return array
+	 */
+	private static function parseTimezoneOffset($timezone_offset): array
+	{
+		$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|null $field_obj
+	 * @param mixed                    $original_value
+	 * @param string                   $requested_version
+	 * @return mixed
+	 * @throws EE_Error
+	 * @throws EE_Error
+	 * @throws Exception
+	 */
+	public static function prepareFieldValueForJson(
+		?EE_Model_Field_Base $field_obj,
+		$original_value,
+		string $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 it's 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 it's 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) {
+				$new_value = mysql2date('Y-m-d\TH:i:s', $new_value, false);
+			}
+		} 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
+	 */
+	public static function prepareConditionsQueryParamsForModels(
+		array $inputted_query_params_of_this_type,
+		EEM_Base $model,
+		string $requested_version,
+		bool $writing = false
+	): array {
+		$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 (
+					(isset($query_param_for_models[ $query_param_meta->getQueryParamKey() ])
+						&& $query_param_meta->isGmtField())
+					|| $translated_value === null
+				) {
+					// 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 it's a
+	 * gmt date field name
+	 *
+	 * @param string $field_name
+	 * @return boolean
+	 */
+	public static function isGmtDateFieldName(string $field_name): bool
+	{
+		$field_name = ModelDataTranslator::removeStarsAndAnythingAfterFromConditionQueryParamKey($field_name);
+		return substr($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(string $field_name): string
+	{
+		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(string $field_name): string
+	{
+		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): array
+	{
+		$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): array
+	{
+		$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|null $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,
+		?string $requested_version = ''
+	): array {
+		if (! $requested_version) {
+			$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 RestException if somehow a PHP object were in the query param's 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(
+		array $inputted_query_params_of_this_type,
+		EEM_Base $model,
+		string $requested_version
+	): array {
+		$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): string
+	{
+		$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(string $query_param_name, EEM_Base $model): ?EE_Model_Field_Base
+	{
+		// 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): bool
+	{
+		return is_scalar($data) || is_array($data) || is_null($data);
+	}
 }

Spacing +19 added lines, -19 removed lines

@@ -69,7 +69,7 @@ 
         ) {
             $new_value_maybe_array = [];
             foreach ($original_value_maybe_array as $array_key => $array_item) {
-                $new_value_maybe_array[ $array_key ] = ModelDataTranslator::prepareFieldValueFromJson(
+                $new_value_maybe_array[$array_key] = ModelDataTranslator::prepareFieldValueFromJson(
                     $field_obj,
                     $array_item,
                     $requested_version,
@@ -106,7 +106,7 @@ 
         if (is_array($original_value_maybe_array)) {
             $new_value = [];
             foreach ($original_value_maybe_array as $key => $value) {
-                $new_value[ $key ] = ModelDataTranslator::prepareFieldValuesForJson(
+                $new_value[$key] = ModelDataTranslator::prepareFieldValuesForJson(
                     $field_obj,
                     $value,
                     $request_version
@@ -177,7 +177,7 @@ 
         ) {
             $new_value = EE_INF;
         } elseif ($field_obj instanceof EE_Datetime_Field) {
-            if (! (empty($original_value) && $field_obj->is_nullable())) {
+            if ( ! (empty($original_value) && $field_obj->is_nullable())) {
                 $new_value = rest_parse_date(
                     self::getTimestampWithTimezoneOffset($original_value, $field_obj, $timezone_string)
                 );
@@ -249,7 +249,7 @@ 
                 '0',
                 STR_PAD_LEFT
             );
-        return $original_timestamp . $offset_sign . $offset_string;
+        return $original_timestamp.$offset_sign.$offset_string;
     }
 
 
@@ -332,7 +332,7 @@ 
                     // first, check if it's a MySQL timestamp in GMT
                     $datetime_obj = DateTime::createFromFormat('Y-m-d H:i:s', $original_value);
                 }
-                if (! $datetime_obj instanceof DateTime) {
+                if ( ! $datetime_obj instanceof DateTime) {
                     // so it's not a unix timestamp or a MySQL timestamp. Maybe it's in the field's date/time format?
                     $datetime_obj = $field_obj->prepare_for_set($original_value);
                 }
@@ -358,7 +358,7 @@ 
                         $original_value,
                         $field_obj->get_name(),
                         $field_obj->get_model_name(),
-                        $field_obj->get_time_format() . ' ' . $field_obj->get_time_format()
+                        $field_obj->get_time_format().' '.$field_obj->get_time_format()
                     )
                 );
             }
@@ -370,7 +370,7 @@ 
         }
         // 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)) {
+        if ( ! ModelDataTranslator::isRepresentableInJson($new_value)) {
             $new_value = [
                 'error_code'    => 'php_object_not_return',
                 'error_message' => esc_html__(
@@ -421,7 +421,7 @@ 
             if ($query_param_meta->getField() instanceof EE_Model_Field_Base) {
                 $translated_value = $query_param_meta->determineConditionsQueryParameterValue();
                 if (
-                    (isset($query_param_for_models[ $query_param_meta->getQueryParamKey() ])
+                    (isset($query_param_for_models[$query_param_meta->getQueryParamKey()])
                         && $query_param_meta->isGmtField())
                     || $translated_value === null
                 ) {
@@ -430,11 +430,11 @@ 
                     // OR we couldn't create a translated value from their input
                     continue;
                 }
-                $query_param_for_models[ $query_param_meta->getQueryParamKey() ] = $translated_value;
+                $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;
+                    $query_param_for_models[$query_param_meta->getQueryParamKey()] = $nested_query_params;
                 }
             }
         }
@@ -464,10 +464,10 @@ 
      */
     public static function removeGmtFromFieldName(string $field_name): string
     {
-        if (! ModelDataTranslator::isGmtDateFieldName($field_name)) {
+        if ( ! ModelDataTranslator::isGmtDateFieldName($field_name)) {
             return $field_name;
         }
-        $query_param_sans_stars              =
+        $query_param_sans_stars =
             ModelDataTranslator::removeStarsAndAnythingAfterFromConditionQueryParamKey(
                 $field_name
             );
@@ -508,7 +508,7 @@ 
     {
         $new_array = [];
         foreach ($field_names as $key => $field_name) {
-            $new_array[ $key ] = ModelDataTranslator::prepareFieldNameFromJson($field_name);
+            $new_array[$key] = ModelDataTranslator::prepareFieldNameFromJson($field_name);
         }
         return $new_array;
     }
@@ -525,7 +525,7 @@ 
     {
         $new_array = [];
         foreach ($field_names_as_keys as $field_name => $value) {
-            $new_array[ ModelDataTranslator::prepareFieldNameFromJson($field_name) ] = $value;
+            $new_array[ModelDataTranslator::prepareFieldNameFromJson($field_name)] = $value;
         }
         return $new_array;
     }
@@ -547,7 +547,7 @@ 
         EEM_Base $model,
         ?string $requested_version = ''
     ): array {
-        if (! $requested_version) {
+        if ( ! $requested_version) {
             $requested_version = EED_Core_Rest_Api::latest_rest_api_version();
         }
         $rest_query_params = $model_query_params;
@@ -619,10 +619,10 @@ 
                         $requested_version
                     );
                 }
-                $query_param_for_models[ $query_param_key ] = $translated_value;
+                $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 ] =
+                $query_param_for_models[$query_param_key] =
                     ModelDataTranslator::prepareConditionsQueryParamsForRestApi(
                         $query_param_value,
                         $model,
@@ -674,11 +674,11 @@ 
             );
         }
         $number_of_parts       = count($query_param_parts);
-        $last_query_param_part = $query_param_parts[ count($query_param_parts) - 1 ];
+        $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 ]);
+            $model = EE_Registry::instance()->load_model($query_param_parts[$number_of_parts - 2]);
         }
         try {
             return $model->field_settings_for($field_name, false);

core/libraries/rest_api/controllers/Base.php

Indentation +313 added lines, -313 removed lines

@@ -21,317 +21,317 @@
  */
 class Base
 {
-    public const HEADER_PREFIX_FOR_EE = 'X-EE-';
-
-    public const HEADER_PREFIX_FOR_WP = 'X-WP-';
-
-    /**
-     * Contains debug info we'll send back in the response headers
-     *
-     * @var array
-     */
-    protected array $debug_info = [];
-
-    /**
-     * Indicates whether the API is in debug mode
-     *
-     * @var boolean
-     */
-    protected bool $debug_mode = false;
-
-    /**
-     * Indicates the version that was requested
-     *
-     * @var string
-     */
-    protected string $requested_version = '';
-
-    /**
-     * flat array of headers to send in the response
-     *
-     * @var array
-     */
-    protected array $response_headers = [];
-
-
-    public function __construct()
-    {
-        $this->debug_mode = EED_Core_Rest_Api::debugMode();
-        // we are handling a REST request. Don't show a fancy HTML error message is any error comes up
-        add_filter('FHEE__EE_Error__get_error__show_normal_exceptions', '__return_true');
-    }
-
-
-    /**
-     * Sets the version the user requested
-     *
-     * @param string $version eg '4.8'
-     */
-    public function setRequestedVersion(string $version)
-    {
-        $this->requested_version = $version;
-    }
-
-
-    /**
-     * Sets some debug info that we'll send back in headers
-     *
-     * @param string       $key
-     * @param string|array $info
-     */
-    protected function setDebugInfo(string $key, $info)
-    {
-        $this->debug_info[ $key ] = $info;
-    }
-
-
-    /**
-     * Sets headers for the response
-     *
-     * @param string       $header_key    , excluding the "X-EE-" part
-     * @param array|string $value         if an array, multiple headers will be added, one
-     *                                    for each key in the array
-     * @param boolean      $use_ee_prefix whether to use the EE prefix on the header, or fallback to
-     *                                    the standard WP one
-     */
-    protected function setResponseHeader(string $header_key, $value, bool $use_ee_prefix = true)
-    {
-        if (is_array($value)) {
-            foreach ($value as $value_key => $value_value) {
-                $this->setResponseHeader($header_key . '[' . $value_key . ']', $value_value);
-            }
-        } else {
-            $prefix                                          =
-                $use_ee_prefix ? Base::HEADER_PREFIX_FOR_EE : Base::HEADER_PREFIX_FOR_WP;
-            $this->response_headers[ $prefix . $header_key ] = $value;
-        }
-    }
-
-
-    /**
-     * Returns a flat array of headers to be added to the response
-     *
-     * @return array
-     */
-    protected function getResponseHeaders(): array
-    {
-        return apply_filters(
-            'FHEE__EventEspresso\core\libraries\rest_api\controllers\Base___get_response_headers',
-            $this->response_headers,
-            $this,
-            $this->requested_version
-        );
-    }
-
-
-    /**
-     * Adds error notices from EE_Error onto the provided \WP_Error
-     *
-     * @param WP_Error $wp_error_response
-     * @return WP_Error
-     */
-    protected function addEeErrorsToResponse(WP_Error $wp_error_response): WP_Error
-    {
-        $notices_during_checkin = EE_Error::get_raw_notices();
-        if (! empty($notices_during_checkin['errors'])) {
-            foreach ($notices_during_checkin['errors'] as $error_code => $error_message) {
-                $wp_error_response->add(
-                    sanitize_key($error_code),
-                    strip_tags($error_message)
-                );
-            }
-        }
-        return $wp_error_response;
-    }
-
-
-    /**
-     * Sends a response, but also makes sure to attach headers that
-     * are handy for debugging.
-     * Specifically, we assume folks will want to know what exactly was the DB query that got run,
-     * what exactly was the Models query that got run, what capabilities came into play, what fields were omitted from
-     * the response, others?
-     *
-     * @param array|WP_Error|Exception|RestException $response
-     * @return WP_REST_Response
-     */
-    public function sendResponse($response): WP_REST_Response
-    {
-        if ($response instanceof RestException) {
-            $response = new WP_Error($response->getStringCode(), $response->getMessage(), $response->getData());
-        }
-        if ($response instanceof Exception) {
-            $code     = $response->getCode() ?: 'error_occurred';
-            $response = new WP_Error($code, $response->getMessage());
-        }
-        if ($response instanceof WP_Error) {
-            $response      = $this->addEeErrorsToResponse($response);
-            $rest_response = $this->createRestResponseFromWpError($response);
-        } else {
-            $rest_response = new WP_REST_Response($response, 200);
-        }
-        $headers = [];
-        if ($this->debug_mode) {
-            foreach ($this->debug_info as $debug_key => $debug_info) {
-                if (is_array($debug_info)) {
-                    $debug_info = wp_json_encode($debug_info);
-                }
-                $debug_key             = ucwords(str_replace("\x20", '-', $debug_key));
-                $debug_key             = Base::HEADER_PREFIX_FOR_EE . '4-Debug-' . $debug_key;
-                $headers[ $debug_key ] = $debug_info;
-            }
-        }
-        $headers = array_merge(
-            $headers,
-            $this->getResponseHeaders(),
-            $this->getHeadersFromEeNotices()
-        );
-        $rest_response->set_headers($headers);
-        return $rest_response;
-    }
-
-
-    /**
-     * Converts the \WP_Error into `WP_REST_Response.
-     * Mostly this is just a copy-and-paste from \WP_REST_Server::error_to_response
-     * (which is protected)
-     *
-     * @param WP_Error $wp_error
-     * @return WP_REST_Response
-     */
-    protected function createRestResponseFromWpError(WP_Error $wp_error): WP_REST_Response
-    {
-        $error_data = $wp_error->get_error_data();
-        if (is_array($error_data) && isset($error_data['status'])) {
-            $status = $error_data['status'];
-        } else {
-            $status = 500;
-        }
-        $errors = [];
-        foreach ((array) $wp_error->errors as $code => $messages) {
-            foreach ((array) $messages as $message) {
-                $errors[] = [
-                    'code'    => $code,
-                    'message' => $message,
-                    'data'    => $wp_error->get_error_data($code),
-                ];
-            }
-        }
-        $data = $errors[0] ?? [];
-        if (count($errors) > 1) {
-            // Remove the primary error.
-            array_shift($errors);
-            $data['additional_errors'] = $errors;
-        }
-        return new WP_REST_Response($data, $status);
-    }
-
-
-    /**
-     * Array of headers derived from EE success, attention, and error messages
-     *
-     * @return array
-     */
-    protected function getHeadersFromEeNotices(): array
-    {
-        $headers = [];
-        $notices = EE_Error::get_raw_notices();
-        foreach ($notices as $notice_type => $sub_notices) {
-            if (! is_array($sub_notices)) {
-                continue;
-            }
-            foreach ($sub_notices as $notice_code => $sub_notice) {
-                $headers[ 'X-EE4-Notices-'
-                . EEH_Inflector::humanize($notice_type)
-                . '['
-                . $notice_code
-                . ']' ] = strip_tags((string) $sub_notice);
-            }
-        }
-        return apply_filters(
-            'FHEE__EventEspresso\core\libraries\rest_api\controllers\Base___get_headers_from_ee_notices__return',
-            $headers,
-            $this->requested_version,
-            $notices
-        );
-    }
-
-
-    /**
-     * Finds which version of the API was requested given the route, and returns it.
-     * eg in a request to "mysite.com/wp-json/ee/v4.8.29/events/123" this would return
-     * "4.8.29".
-     * We should know hte requested version in this model though, so if no route is
-     * provided just use what we set earlier
-     *
-     * @param string|null $route
-     * @return string
-     * @throws EE_Error
-     */
-    public function getRequestedVersion(?string $route = null): string
-    {
-        if ($route === null) {
-            return $this->requested_version;
-        }
-        $matches = $this->parseRoute(
-            $route,
-            '~' . EED_Core_Rest_Api::ee_api_namespace_for_regex . '~',
-            ['version']
-        );
-        return $matches['version'] ?? EED_Core_Rest_Api::latest_rest_api_version();
-    }
-
-
-    /**
-     * Applies the regex to the route, then creates an array using the values of
-     * $match_keys as keys (but ignores the full pattern match). Returns the array of matches.
-     * For example, if you call
-     * parse_route( '/ee/v4.8/events', '~\/ee\/v([^/]*)\/(.*)~', array( 'version', 'model' ) )
-     * it will return array( 'version' => '4.8', 'model' => 'events' )
-     *
-     * @param string $route
-     * @param string $regex
-     * @param array  $match_keys EXCLUDING matching the entire regex
-     * @return array where  $match_keys are the keys (the first value of $match_keys
-     *                           becomes the first key of the return value, etc. Eg passing in $match_keys of
-     *                           array( 'model', 'id' ), will, if the regex is successful, will return
-     *                           array( 'model' => 'foo', 'id' => 'bar' )
-     * @throws EE_Error if it couldn't be parsed
-     */
-    public function parseRoute(string $route, string $regex, array $match_keys): array
-    {
-        $indexed_matches = [];
-        $success         = preg_match($regex, $route, $matches);
-        if (is_array($matches)) {
-            // skip the overall regex match. Who cares
-            for ($i = 1; $i <= count($match_keys); $i++) {
-                if (! isset($matches[ $i ])) {
-                    $success = false;
-                } else {
-                    $indexed_matches[ $match_keys[ $i - 1 ] ] = $matches[ $i ];
-                }
-            }
-        }
-        if (! $success) {
-            throw new EE_Error(
-                esc_html__('We could not parse the URL. Please contact Event Espresso Support', 'event_espresso'),
-                'endpoint_parsing_error'
-            );
-        }
-        return $indexed_matches;
-    }
-
-
-    /**
-     * Gets the body's params (either from JSON or parsed body), which EXCLUDES the GET params and URL params
-     *
-     * @param WP_REST_Request $request
-     * @return array
-     */
-    protected function getBodyParams(WP_REST_Request $request): array
-    {
-        $body_params = (array) $request->get_body_params();
-        $json_params = (array) $request->get_json_params();
-        return [...$body_params, ...$json_params];
-    }
+	public const HEADER_PREFIX_FOR_EE = 'X-EE-';
+
+	public const HEADER_PREFIX_FOR_WP = 'X-WP-';
+
+	/**
+	 * Contains debug info we'll send back in the response headers
+	 *
+	 * @var array
+	 */
+	protected array $debug_info = [];
+
+	/**
+	 * Indicates whether the API is in debug mode
+	 *
+	 * @var boolean
+	 */
+	protected bool $debug_mode = false;
+
+	/**
+	 * Indicates the version that was requested
+	 *
+	 * @var string
+	 */
+	protected string $requested_version = '';
+
+	/**
+	 * flat array of headers to send in the response
+	 *
+	 * @var array
+	 */
+	protected array $response_headers = [];
+
+
+	public function __construct()
+	{
+		$this->debug_mode = EED_Core_Rest_Api::debugMode();
+		// we are handling a REST request. Don't show a fancy HTML error message is any error comes up
+		add_filter('FHEE__EE_Error__get_error__show_normal_exceptions', '__return_true');
+	}
+
+
+	/**
+	 * Sets the version the user requested
+	 *
+	 * @param string $version eg '4.8'
+	 */
+	public function setRequestedVersion(string $version)
+	{
+		$this->requested_version = $version;
+	}
+
+
+	/**
+	 * Sets some debug info that we'll send back in headers
+	 *
+	 * @param string       $key
+	 * @param string|array $info
+	 */
+	protected function setDebugInfo(string $key, $info)
+	{
+		$this->debug_info[ $key ] = $info;
+	}
+
+
+	/**
+	 * Sets headers for the response
+	 *
+	 * @param string       $header_key    , excluding the "X-EE-" part
+	 * @param array|string $value         if an array, multiple headers will be added, one
+	 *                                    for each key in the array
+	 * @param boolean      $use_ee_prefix whether to use the EE prefix on the header, or fallback to
+	 *                                    the standard WP one
+	 */
+	protected function setResponseHeader(string $header_key, $value, bool $use_ee_prefix = true)
+	{
+		if (is_array($value)) {
+			foreach ($value as $value_key => $value_value) {
+				$this->setResponseHeader($header_key . '[' . $value_key . ']', $value_value);
+			}
+		} else {
+			$prefix                                          =
+				$use_ee_prefix ? Base::HEADER_PREFIX_FOR_EE : Base::HEADER_PREFIX_FOR_WP;
+			$this->response_headers[ $prefix . $header_key ] = $value;
+		}
+	}
+
+
+	/**
+	 * Returns a flat array of headers to be added to the response
+	 *
+	 * @return array
+	 */
+	protected function getResponseHeaders(): array
+	{
+		return apply_filters(
+			'FHEE__EventEspresso\core\libraries\rest_api\controllers\Base___get_response_headers',
+			$this->response_headers,
+			$this,
+			$this->requested_version
+		);
+	}
+
+
+	/**
+	 * Adds error notices from EE_Error onto the provided \WP_Error
+	 *
+	 * @param WP_Error $wp_error_response
+	 * @return WP_Error
+	 */
+	protected function addEeErrorsToResponse(WP_Error $wp_error_response): WP_Error
+	{
+		$notices_during_checkin = EE_Error::get_raw_notices();
+		if (! empty($notices_during_checkin['errors'])) {
+			foreach ($notices_during_checkin['errors'] as $error_code => $error_message) {
+				$wp_error_response->add(
+					sanitize_key($error_code),
+					strip_tags($error_message)
+				);
+			}
+		}
+		return $wp_error_response;
+	}
+
+
+	/**
+	 * Sends a response, but also makes sure to attach headers that
+	 * are handy for debugging.
+	 * Specifically, we assume folks will want to know what exactly was the DB query that got run,
+	 * what exactly was the Models query that got run, what capabilities came into play, what fields were omitted from
+	 * the response, others?
+	 *
+	 * @param array|WP_Error|Exception|RestException $response
+	 * @return WP_REST_Response
+	 */
+	public function sendResponse($response): WP_REST_Response
+	{
+		if ($response instanceof RestException) {
+			$response = new WP_Error($response->getStringCode(), $response->getMessage(), $response->getData());
+		}
+		if ($response instanceof Exception) {
+			$code     = $response->getCode() ?: 'error_occurred';
+			$response = new WP_Error($code, $response->getMessage());
+		}
+		if ($response instanceof WP_Error) {
+			$response      = $this->addEeErrorsToResponse($response);
+			$rest_response = $this->createRestResponseFromWpError($response);
+		} else {
+			$rest_response = new WP_REST_Response($response, 200);
+		}
+		$headers = [];
+		if ($this->debug_mode) {
+			foreach ($this->debug_info as $debug_key => $debug_info) {
+				if (is_array($debug_info)) {
+					$debug_info = wp_json_encode($debug_info);
+				}
+				$debug_key             = ucwords(str_replace("\x20", '-', $debug_key));
+				$debug_key             = Base::HEADER_PREFIX_FOR_EE . '4-Debug-' . $debug_key;
+				$headers[ $debug_key ] = $debug_info;
+			}
+		}
+		$headers = array_merge(
+			$headers,
+			$this->getResponseHeaders(),
+			$this->getHeadersFromEeNotices()
+		);
+		$rest_response->set_headers($headers);
+		return $rest_response;
+	}
+
+
+	/**
+	 * Converts the \WP_Error into `WP_REST_Response.
+	 * Mostly this is just a copy-and-paste from \WP_REST_Server::error_to_response
+	 * (which is protected)
+	 *
+	 * @param WP_Error $wp_error
+	 * @return WP_REST_Response
+	 */
+	protected function createRestResponseFromWpError(WP_Error $wp_error): WP_REST_Response
+	{
+		$error_data = $wp_error->get_error_data();
+		if (is_array($error_data) && isset($error_data['status'])) {
+			$status = $error_data['status'];
+		} else {
+			$status = 500;
+		}
+		$errors = [];
+		foreach ((array) $wp_error->errors as $code => $messages) {
+			foreach ((array) $messages as $message) {
+				$errors[] = [
+					'code'    => $code,
+					'message' => $message,
+					'data'    => $wp_error->get_error_data($code),
+				];
+			}
+		}
+		$data = $errors[0] ?? [];
+		if (count($errors) > 1) {
+			// Remove the primary error.
+			array_shift($errors);
+			$data['additional_errors'] = $errors;
+		}
+		return new WP_REST_Response($data, $status);
+	}
+
+
+	/**
+	 * Array of headers derived from EE success, attention, and error messages
+	 *
+	 * @return array
+	 */
+	protected function getHeadersFromEeNotices(): array
+	{
+		$headers = [];
+		$notices = EE_Error::get_raw_notices();
+		foreach ($notices as $notice_type => $sub_notices) {
+			if (! is_array($sub_notices)) {
+				continue;
+			}
+			foreach ($sub_notices as $notice_code => $sub_notice) {
+				$headers[ 'X-EE4-Notices-'
+				. EEH_Inflector::humanize($notice_type)
+				. '['
+				. $notice_code
+				. ']' ] = strip_tags((string) $sub_notice);
+			}
+		}
+		return apply_filters(
+			'FHEE__EventEspresso\core\libraries\rest_api\controllers\Base___get_headers_from_ee_notices__return',
+			$headers,
+			$this->requested_version,
+			$notices
+		);
+	}
+
+
+	/**
+	 * Finds which version of the API was requested given the route, and returns it.
+	 * eg in a request to "mysite.com/wp-json/ee/v4.8.29/events/123" this would return
+	 * "4.8.29".
+	 * We should know hte requested version in this model though, so if no route is
+	 * provided just use what we set earlier
+	 *
+	 * @param string|null $route
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public function getRequestedVersion(?string $route = null): string
+	{
+		if ($route === null) {
+			return $this->requested_version;
+		}
+		$matches = $this->parseRoute(
+			$route,
+			'~' . EED_Core_Rest_Api::ee_api_namespace_for_regex . '~',
+			['version']
+		);
+		return $matches['version'] ?? EED_Core_Rest_Api::latest_rest_api_version();
+	}
+
+
+	/**
+	 * Applies the regex to the route, then creates an array using the values of
+	 * $match_keys as keys (but ignores the full pattern match). Returns the array of matches.
+	 * For example, if you call
+	 * parse_route( '/ee/v4.8/events', '~\/ee\/v([^/]*)\/(.*)~', array( 'version', 'model' ) )
+	 * it will return array( 'version' => '4.8', 'model' => 'events' )
+	 *
+	 * @param string $route
+	 * @param string $regex
+	 * @param array  $match_keys EXCLUDING matching the entire regex
+	 * @return array where  $match_keys are the keys (the first value of $match_keys
+	 *                           becomes the first key of the return value, etc. Eg passing in $match_keys of
+	 *                           array( 'model', 'id' ), will, if the regex is successful, will return
+	 *                           array( 'model' => 'foo', 'id' => 'bar' )
+	 * @throws EE_Error if it couldn't be parsed
+	 */
+	public function parseRoute(string $route, string $regex, array $match_keys): array
+	{
+		$indexed_matches = [];
+		$success         = preg_match($regex, $route, $matches);
+		if (is_array($matches)) {
+			// skip the overall regex match. Who cares
+			for ($i = 1; $i <= count($match_keys); $i++) {
+				if (! isset($matches[ $i ])) {
+					$success = false;
+				} else {
+					$indexed_matches[ $match_keys[ $i - 1 ] ] = $matches[ $i ];
+				}
+			}
+		}
+		if (! $success) {
+			throw new EE_Error(
+				esc_html__('We could not parse the URL. Please contact Event Espresso Support', 'event_espresso'),
+				'endpoint_parsing_error'
+			);
+		}
+		return $indexed_matches;
+	}
+
+
+	/**
+	 * Gets the body's params (either from JSON or parsed body), which EXCLUDES the GET params and URL params
+	 *
+	 * @param WP_REST_Request $request
+	 * @return array
+	 */
+	protected function getBodyParams(WP_REST_Request $request): array
+	{
+		$body_params = (array) $request->get_body_params();
+		$json_params = (array) $request->get_json_params();
+		return [...$body_params, ...$json_params];
+	}
 }

Spacing +13 added lines, -13 removed lines

@@ -81,7 +81,7 @@ 
      */
     protected function setDebugInfo(string $key, $info)
     {
-        $this->debug_info[ $key ] = $info;
+        $this->debug_info[$key] = $info;
     }
 
 
@@ -98,12 +98,12 @@ 
     {
         if (is_array($value)) {
             foreach ($value as $value_key => $value_value) {
-                $this->setResponseHeader($header_key . '[' . $value_key . ']', $value_value);
+                $this->setResponseHeader($header_key.'['.$value_key.']', $value_value);
             }
         } else {
             $prefix                                          =
                 $use_ee_prefix ? Base::HEADER_PREFIX_FOR_EE : Base::HEADER_PREFIX_FOR_WP;
-            $this->response_headers[ $prefix . $header_key ] = $value;
+            $this->response_headers[$prefix.$header_key] = $value;
         }
     }
 
@@ -133,7 +133,7 @@ 
     protected function addEeErrorsToResponse(WP_Error $wp_error_response): WP_Error
     {
         $notices_during_checkin = EE_Error::get_raw_notices();
-        if (! empty($notices_during_checkin['errors'])) {
+        if ( ! empty($notices_during_checkin['errors'])) {
             foreach ($notices_during_checkin['errors'] as $error_code => $error_message) {
                 $wp_error_response->add(
                     sanitize_key($error_code),
@@ -177,8 +177,8 @@ 
                     $debug_info = wp_json_encode($debug_info);
                 }
                 $debug_key             = ucwords(str_replace("\x20", '-', $debug_key));
-                $debug_key             = Base::HEADER_PREFIX_FOR_EE . '4-Debug-' . $debug_key;
-                $headers[ $debug_key ] = $debug_info;
+                $debug_key             = Base::HEADER_PREFIX_FOR_EE.'4-Debug-'.$debug_key;
+                $headers[$debug_key] = $debug_info;
             }
         }
         $headers = array_merge(
@@ -237,15 +237,15 @@ 
         $headers = [];
         $notices = EE_Error::get_raw_notices();
         foreach ($notices as $notice_type => $sub_notices) {
-            if (! is_array($sub_notices)) {
+            if ( ! is_array($sub_notices)) {
                 continue;
             }
             foreach ($sub_notices as $notice_code => $sub_notice) {
-                $headers[ 'X-EE4-Notices-'
+                $headers['X-EE4-Notices-'
                 . EEH_Inflector::humanize($notice_type)
                 . '['
                 . $notice_code
-                . ']' ] = strip_tags((string) $sub_notice);
+                . ']'] = strip_tags((string) $sub_notice);
             }
         }
         return apply_filters(
@@ -275,7 +275,7 @@ 
         }
         $matches = $this->parseRoute(
             $route,
-            '~' . EED_Core_Rest_Api::ee_api_namespace_for_regex . '~',
+            '~'.EED_Core_Rest_Api::ee_api_namespace_for_regex.'~',
             ['version']
         );
         return $matches['version'] ?? EED_Core_Rest_Api::latest_rest_api_version();
@@ -305,14 +305,14 @@ 
         if (is_array($matches)) {
             // skip the overall regex match. Who cares
             for ($i = 1; $i <= count($match_keys); $i++) {
-                if (! isset($matches[ $i ])) {
+                if ( ! isset($matches[$i])) {
                     $success = false;
                 } else {
-                    $indexed_matches[ $match_keys[ $i - 1 ] ] = $matches[ $i ];
+                    $indexed_matches[$match_keys[$i - 1]] = $matches[$i];
                 }
             }
         }
-        if (! $success) {
+        if ( ! $success) {
             throw new EE_Error(
                 esc_html__('We could not parse the URL. Please contact Event Espresso Support', 'event_espresso'),
                 'endpoint_parsing_error'

core/libraries/rest_api/controllers/model/Read.php

Indentation +1686 added lines, -1686 removed lines

@@ -51,1690 +51,1690 @@
  */
 class Read extends Base
 {
-    protected CalculatedModelFields $fields_calculator;
-
-
-    /**
-     * Read constructor.
-     *
-     * @param CalculatedModelFields $fields_calculator
-     */
-    public function __construct(CalculatedModelFields $fields_calculator)
-    {
-        parent::__construct();
-        $this->fields_calculator = $fields_calculator;
-    }
-
-
-    /**
-     * @return Read
-     */
-    private static function getReadController(): Read
-    {
-        return LoaderFactory::getLoader()->getNew(Read::class);
-    }
-
-
-    /**
-     * Handles requests to get all (or a filtered subset) of entities for a particular model
-     *
-     * @param WP_REST_Request $request
-     * @param string          $version
-     * @param string          $model_name
-     * @return WP_REST_Response
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public static function handleRequestGetAll(
-        WP_REST_Request $request,
-        string $version,
-        string $model_name
-    ): WP_REST_Response {
-        $controller = self::getReadController();
-        try {
-            $controller->setRequestedVersion($version);
-            if (! $controller->getModelVersionInfo()->isModelNameInThisVersion($model_name)) {
-                return $controller->sendResponse(
-                    new WP_Error(
-                        'endpoint_parsing_error',
-                        sprintf(
-                            esc_html__(
-                                'There is no model for endpoint %s. Please contact event espresso support',
-                                'event_espresso'
-                            ),
-                            $model_name
-                        )
-                    )
-                );
-            }
-            return $controller->sendResponse(
-                $controller->getEntitiesFromModel(
-                    $controller->getModelVersionInfo()->loadModel($model_name),
-                    $request
-                )
-            );
-        } catch (Exception $e) {
-            return $controller->sendResponse($e);
-        }
-    }
-
-
-    /**
-     * Prepares and returns schema for any OPTIONS request.
-     *
-     * @param string $version    The API endpoint version being used.
-     * @param string $model_name Something like `Event` or `Registration`
-     * @return array
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     */
-    public static function handleSchemaRequest(string $version, string $model_name): array
-    {
-        $controller = self::getReadController();
-        try {
-            $controller->setRequestedVersion($version);
-            if (! $controller->getModelVersionInfo()->isModelNameInThisVersion($model_name)) {
-                return [];
-            }
-            // get the model for this version
-            $model        = $controller->getModelVersionInfo()->loadModel($model_name);
-            $model_schema = new JsonModelSchema(
-                $model,
-                LoaderFactory::getLoader()->getShared('EventEspresso\core\libraries\rest_api\CalculatedModelFields')
-            );
-            return $model_schema->getModelSchemaForRelations(
-                $controller->getModelVersionInfo()->relationSettings($model),
-                $controller->customizeSchemaForRestResponse(
-                    $model,
-                    $model_schema->getModelSchemaForFields(
-                        $controller->getModelVersionInfo()->fieldsOnModelInThisVersion($model),
-                        $model_schema->getInitialSchemaStructure()
-                    )
-                )
-            );
-        } catch (Exception $e) {
-            error_log($e->getMessage());
-            return [];
-        }
-    }
-
-
-    /**
-     * This loops through each field in the given schema for the model and does the following:
-     * - add any extra fields that are REST API specific and related to existing fields.
-     * - transform default values into the correct format for a REST API response.
-     *
-     * @param EEM_Base $model
-     * @param array    $schema
-     * @return array  The final schema.
-     * @throws EE_Error
-     */
-    public function customizeSchemaForRestResponse(EEM_Base $model, array $schema): array
-    {
-        foreach ($this->getModelVersionInfo()->fieldsOnModelInThisVersion($model) as $field_name => $field) {
-            $schema = $this->translateDefaultsForRestResponse(
-                $field_name,
-                $field,
-                $this->maybeAddExtraFieldsToSchema($field_name, $field, $schema)
-            );
-        }
-        return $schema;
-    }
-
-
-    /**
-     * This is used to ensure that the 'default' value set in the schema response is formatted correctly for the REST
-     * response.
-     *
-     * @param                      $field_name
-     * @param EE_Model_Field_Base  $field
-     * @param array                $schema
-     * @return array
-     * @throws RestException  if a default value has a PHP object, which we should never do
-     *                                  (but if we did, let's know about it ASAP, so let the exception bubble up)
-     * @throws EE_Error
-     *
-     */
-    protected function translateDefaultsForRestResponse($field_name, EE_Model_Field_Base $field, array $schema): array
-    {
-        if (isset($schema['properties'][ $field_name ]['default'])) {
-            if (is_array($schema['properties'][ $field_name ]['default'])) {
-                foreach ($schema['properties'][ $field_name ]['default'] as $default_key => $default_value) {
-                    if ($default_key === 'raw') {
-                        $schema['properties'][ $field_name ]['default'][ $default_key ] =
-                            ModelDataTranslator::prepareFieldValueForJson(
-                                $field,
-                                $default_value,
-                                $this->getModelVersionInfo()->requestedVersion()
-                            );
-                    }
-                }
-            } else {
-                $schema['properties'][ $field_name ]['default'] = ModelDataTranslator::prepareFieldValueForJson(
-                    $field,
-                    $schema['properties'][ $field_name ]['default'],
-                    $this->getModelVersionInfo()->requestedVersion()
-                );
-            }
-        }
-        return $schema;
-    }
-
-
-    /**
-     * Adds additional fields to the schema
-     * The REST API returns a GMT value field for each datetime field in the resource.  Thus the description about this
-     * needs to be added to the schema.
-     *
-     * @param                      $field_name
-     * @param EE_Model_Field_Base  $field
-     * @param array                $schema
-     * @return array
-     */
-    protected function maybeAddExtraFieldsToSchema($field_name, EE_Model_Field_Base $field, array $schema): array
-    {
-        if ($field instanceof EE_Datetime_Field) {
-            $schema['properties'][ $field_name . '_gmt' ] = $field->getSchema();
-            // modify the description
-            $schema['properties'][ $field_name . '_gmt' ]['description'] = sprintf(
-                esc_html__('%s - the value for this field is in GMT.', 'event_espresso'),
-                wp_specialchars_decode($field->get_nicename(), ENT_QUOTES)
-            );
-        }
-        return $schema;
-    }
-
-
-    /**
-     * Used to figure out the route from the request when a `WP_REST_Request` object is not available
-     *
-     * @return string
-     */
-    protected function getRouteFromRequest(): string
-    {
-        if (
-            isset($GLOBALS['wp'])
-            && $GLOBALS['wp'] instanceof WP
-            && isset($GLOBALS['wp']->query_vars['rest_route'])
-        ) {
-            return $GLOBALS['wp']->query_vars['rest_route'];
-        }
-        /** @var RequestInterface $request */
-        $request = LoaderFactory::getLoader()->getShared(RequestInterface::class);
-        return $request->serverParamIsSet('PATH_INFO')
-            ? $request->getServerParam('PATH_INFO')
-            : '/';
-    }
-
-
-    /**
-     * Gets a single entity related to the model indicated in the path and its id
-     *
-     * @param WP_REST_Request $request
-     * @param string          $version
-     * @param string          $model_name
-     * @return WP_REST_Response
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws InvalidArgumentException
-     */
-    public static function handleRequestGetOne(
-        WP_REST_Request $request,
-        string $version,
-        string $model_name
-    ): WP_REST_Response {
-        $controller = self::getReadController();
-        try {
-            $controller->setRequestedVersion($version);
-            if (! $controller->getModelVersionInfo()->isModelNameInThisVersion($model_name)) {
-                return $controller->sendResponse(
-                    new WP_Error(
-                        'endpoint_parsing_error',
-                        sprintf(
-                            esc_html__(
-                                'There is no model for endpoint %s. Please contact event espresso support',
-                                'event_espresso'
-                            ),
-                            $model_name
-                        )
-                    )
-                );
-            }
-            return $controller->sendResponse(
-                $controller->getEntityFromModel(
-                    $controller->getModelVersionInfo()->loadModel($model_name),
-                    $request
-                )
-            );
-        } catch (Exception $e) {
-            return $controller->sendResponse($e);
-        }
-    }
-
-
-    /**
-     * Gets all the related entities (or if its a belongs-to relation just the one)
-     * to the item with the given id
-     *
-     * @param WP_REST_Request $request
-     * @param string          $version
-     * @param string          $model_name
-     * @param string          $related_model_name
-     * @return WP_REST_Response
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws InvalidArgumentException
-     */
-    public static function handleRequestGetRelated(
-        WP_REST_Request $request,
-        string $version,
-        string $model_name,
-        string $related_model_name
-    ): WP_REST_Response {
-        $controller = self::getReadController();
-        try {
-            $controller->setRequestedVersion($version);
-            $main_model = $controller->validateModel($model_name);
-            $controller->validateModel($related_model_name);
-            return $controller->sendResponse(
-                $controller->getEntitiesFromRelation(
-                    $request->get_param('id'),
-                    $main_model->related_settings_for($related_model_name),
-                    $request
-                )
-            );
-        } catch (Exception $e) {
-            return $controller->sendResponse($e);
-        }
-    }
-
-
-    /**
-     * Gets a collection for the given model and filters
-     *
-     * @param EEM_Base        $model
-     * @param WP_REST_Request $request
-     * @return array
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ModelConfigurationException
-     * @throws ReflectionException
-     * @throws RestException
-     * @throws RestPasswordIncorrectException
-     * @throws RestPasswordRequiredException
-     * @throws UnexpectedEntityException
-     */
-    public function getEntitiesFromModel(EEM_Base $model, WP_REST_Request $request): array
-    {
-        $query_params = $this->createModelQueryParams($model, $request->get_params());
-        if (! Capabilities::currentUserHasPartialAccessTo($model, $query_params['caps'])) {
-            $model_name_plural = EEH_Inflector::pluralize_and_lower($model->get_this_model_name());
-            throw new RestException(
-                sprintf('rest_%s_cannot_list', $model_name_plural),
-                sprintf(
-                    esc_html__('Sorry, you are not allowed to list %1$s. Missing permissions: %2$s', 'event_espresso'),
-                    $model_name_plural,
-                    Capabilities::getMissingPermissionsString($model, $query_params['caps'])
-                ),
-                ['status' => 403]
-            );
-        }
-        if (! $request->get_header('no_rest_headers')) {
-            $this->setHeadersFromQueryParams($model, $query_params);
-        }
-        /** @type array $results */
-        $results      = $model->get_all_wpdb_results($query_params);
-        $nice_results = [];
-        foreach ($results as $result) {
-            $nice_results[] = $this->createEntityFromWpdbResult(
-                $model,
-                $result,
-                $request
-            );
-        }
-        return $nice_results;
-    }
-
-
-    /**
-     * Gets the collection for given relation object
-     * The same as Read::get_entities_from_model(), except if the relation
-     * is a HABTM relation, in which case it merges any non-foreign-key fields from
-     * the join-model-object into the results
-     *
-     * @param array                  $primary_model_query_params  query params for finding the item from which
-     *                                                            relations will be based
-     * @param EE_Model_Relation_Base $relation
-     * @param WP_REST_Request        $request
-     * @return array|null
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ModelConfigurationException
-     * @throws ReflectionException
-     * @throws RestException
-     * @throws ModelConfigurationException
-     * @throws UnexpectedEntityException
-     * @throws Exception
-     */
-    protected function getEntitiesFromRelationUsingModelQueryParams(
-        array $primary_model_query_params,
-        EE_Model_Relation_Base $relation,
-        WP_REST_Request $request
-    ): ?array {
-        $context       = $this->validateContext($request->get_param('caps'));
-        $model         = $relation->get_this_model();
-        $related_model = $relation->get_other_model();
-        if (! isset($primary_model_query_params[0])) {
-            $primary_model_query_params[0] = [];
-        }
-        // check if they can access the 1st model object
-        $primary_model_query_params = [
-            0       => $primary_model_query_params[0],
-            'limit' => 1,
-        ];
-        if ($model instanceof EEM_Soft_Delete_Base) {
-            $primary_model_query_params = $model->alter_query_params_so_deleted_and_undeleted_items_included(
-                $primary_model_query_params
-            );
-        }
-        $restricted_query_params          = $primary_model_query_params;
-        $restricted_query_params['caps']  = $context;
-        $restricted_query_params['limit'] = 1;
-        $this->setDebugInfo('main model query params', $restricted_query_params);
-        $this->setDebugInfo('missing caps', Capabilities::getMissingPermissionsString($related_model, $context));
-        $primary_model_rows = $model->get_all_wpdb_results($restricted_query_params);
-        $primary_model_row  = null;
-        if (is_array($primary_model_rows)) {
-            $primary_model_row = reset($primary_model_rows);
-        }
-        if (
-            ! (
-                $primary_model_row
-                && Capabilities::currentUserHasPartialAccessTo($related_model, $context)
-            )
-        ) {
-            if ($relation instanceof EE_Belongs_To_Relation) {
-                $related_model_name_maybe_plural = strtolower($related_model->get_this_model_name());
-            } else {
-                $related_model_name_maybe_plural = EEH_Inflector::pluralize_and_lower(
-                    $related_model->get_this_model_name()
-                );
-            }
-            throw new RestException(
-                sprintf('rest_%s_cannot_list', $related_model_name_maybe_plural),
-                sprintf(
-                    esc_html__(
-                        'Sorry, you are not allowed to list %1$s related to %2$s. Missing permissions: %3$s',
-                        'event_espresso'
-                    ),
-                    $related_model_name_maybe_plural,
-                    $relation->get_this_model()->get_this_model_name(),
-                    implode(
-                        ',',
-                        array_keys(
-                            Capabilities::getMissingPermissions($related_model, $context)
-                        )
-                    )
-                ),
-                ['status' => 403]
-            );
-        }
-
-        $this->checkPassword(
-            $model,
-            $primary_model_row,
-            $restricted_query_params,
-            $request
-        );
-        $query_params = $this->createModelQueryParams($relation->get_other_model(), $request->get_params());
-        foreach ($primary_model_query_params[0] as $where_condition_key => $where_condition_value) {
-            $query_params[0][ $relation->get_this_model()->get_this_model_name()
-                              . '.'
-                              . $where_condition_key ] = $where_condition_value;
-        }
-        $query_params['default_where_conditions'] = 'none';
-        $query_params['caps']                     = $context;
-        if (! $request->get_header('no_rest_headers')) {
-            $this->setHeadersFromQueryParams($relation->get_other_model(), $query_params);
-        }
-        /** @type array $results */
-        $results      = $relation->get_other_model()->get_all_wpdb_results($query_params);
-        $nice_results = [];
-        foreach ($results as $result) {
-            $nice_result = $this->createEntityFromWpdbResult(
-                $relation->get_other_model(),
-                $result,
-                $request
-            );
-            if ($relation instanceof EE_HABTM_Relation) {
-                // put the unusual stuff (properties from the HABTM relation) first, and make sure
-                // if there are conflicts we prefer the properties from the main model
-                $join_model_result = $this->createEntityFromWpdbResult(
-                    $relation->get_join_model(),
-                    $result,
-                    $request
-                );
-                $joined_result     = array_merge($join_model_result, $nice_result);
-                // but keep the meta stuff from the main model
-                if (isset($nice_result['meta'])) {
-                    $joined_result['meta'] = $nice_result['meta'];
-                }
-                $nice_result = $joined_result;
-            }
-            $nice_results[] = $nice_result;
-        }
-        if ($relation instanceof EE_Belongs_To_Relation) {
-            return array_shift($nice_results);
-        } else {
-            return $nice_results;
-        }
-    }
-
-
-    /**
-     * Gets the collection for given relation object
-     * The same as Read::get_entities_from_model(), except if the relation
-     * is a HABTM relation, in which case it merges any non-foreign-key fields from
-     * the join-model-object into the results
-     *
-     * @param int|string             $id the ID of the thing we are fetching related stuff from
-     * @param EE_Model_Relation_Base $relation
-     * @param WP_REST_Request        $request
-     * @return array
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     * @throws RestException
-     * @throws ModelConfigurationException
-     * @throws UnexpectedEntityException
-     * @throws Exception
-     */
-    public function getEntitiesFromRelation($id, EE_Model_Relation_Base $relation, WP_REST_Request $request): array
-    {
-        if (! $relation->get_this_model()->has_primary_key_field()) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                    // @codingStandardsIgnoreStart
-                        'Read::get_entities_from_relation should only be called from a model with a primary key, it was called from %1$s',
-                        // @codingStandardsIgnoreEnd
-                        'event_espresso'
-                    ),
-                    $relation->get_this_model()->get_this_model_name()
-                )
-            );
-        }
-        // can we edit that main item?
-        // if not, show nothing but an error
-        // otherwise, please proceed
-        return $this->getEntitiesFromRelationUsingModelQueryParams(
-            [
-                [
-                    $relation->get_this_model()->primary_key_name() => $id,
-                ],
-            ],
-            $relation,
-            $request
-        );
-    }
-
-
-    /**
-     * Sets the headers that are based on the model and query params,
-     * like the total records. This should only be called on the original request
-     * from the client, not on subsequent internal
-     *
-     * @param EEM_Base $model
-     * @param array    $query_params
-     * @return void
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    protected function setHeadersFromQueryParams(EEM_Base $model, array $query_params)
-    {
-        $this->setDebugInfo('model query params', $query_params);
-        $this->setDebugInfo(
-            'missing caps',
-            Capabilities::getMissingPermissionsString($model, $query_params['caps'])
-        );
-        // normally the limit to a 2-part array, where the 2nd item is the limit
-        if (! isset($query_params['limit'])) {
-            $query_params['limit'] = EED_Core_Rest_Api::get_default_query_limit();
-        }
-        if (is_array($query_params['limit'])) {
-            $limit_parts = $query_params['limit'];
-        } else {
-            $limit_parts = explode(',', $query_params['limit']);
-            if (count($limit_parts) === 1) {
-                $limit_parts = [0, $limit_parts[0]];
-            }
-        }
-        // remove the group by and having parts of the query, as those will
-        // make the sql query return an array of values, instead of just a single value
-        unset($query_params['group_by'], $query_params['having'], $query_params['limit']);
-        $count = $model->count($query_params, null, true);
-        $pages = $count / $limit_parts[1];
-        $this->setResponseHeader('Total', $count, false);
-        $this->setResponseHeader('PageSize', $limit_parts[1], false);
-        $this->setResponseHeader('TotalPages', ceil($pages), false);
-    }
-
-
-    /**
-     * Changes database results into REST API entities
-     *
-     * @param EEM_Base             $model
-     * @param array                $db_row     like results from $wpdb->get_results()
-     * @param WP_REST_Request|null $rest_request
-     * @param string|null          $deprecated no longer used
-     * @return array ready for being converted into json for sending to client
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ModelConfigurationException
-     * @throws ReflectionException
-     * @throws RestException
-     * @throws RestPasswordIncorrectException
-     * @throws RestPasswordRequiredException
-     * @throws UnexpectedEntityException
-     */
-    public function createEntityFromWpdbResult(
-        EEM_Base $model,
-        array $db_row,
-        ?WP_REST_Request $rest_request,
-        string $deprecated = null
-    ): array {
-        if (! $rest_request instanceof WP_REST_Request) {
-            // ok so this was called in the old style, where the 3rd arg was
-            // $include, and the 4th arg was $context
-            // now setup the request just to avoid fatal errors, although we won't be able
-            // to truly make use of it because it's kinda devoid of info
-            $rest_request = new WP_REST_Request();
-            $rest_request->set_param('include', $rest_request);
-            $rest_request->set_param('caps', $deprecated);
-        }
-        if ($rest_request->get_param('caps') === null) {
-            $rest_request->set_param('caps', EEM_Base::caps_read);
-        }
-        $current_user_full_access_to_entity = $model->currentUserCan(
-            EEM_Base::caps_read_admin,
-            $model->deduce_fields_n_values_from_cols_n_values($db_row)
-        );
-        $entity_array                       = $this->createBareEntityFromWpdbResults($model, $db_row);
-        $entity_array                       = $this->addExtraFields($model, $db_row, $entity_array);
-        $entity_array['_links']             = $this->getEntityLinks($model, $db_row, $entity_array);
-        // when it's a regular read request for a model with a password and the password wasn't provided
-        // remove the password protected fields
-        $has_protected_fields = false;
-        try {
-            $this->checkPassword(
-                $model,
-                $db_row,
-                $model->alter_query_params_to_restrict_by_ID(
-                    $model->get_index_primary_key_string(
-                        $model->deduce_fields_n_values_from_cols_n_values($db_row)
-                    )
-                ),
-                $rest_request
-            );
-        } catch (RestPasswordRequiredException $e) {
-            if ($model->hasPassword()) {
-                // just remove protected fields
-                $has_protected_fields = true;
-                $entity_array         = Capabilities::filterOutPasswordProtectedFields(
-                    $entity_array,
-                    $model,
-                    $this->getModelVersionInfo()
-                );
-            } else {
-                // that's a problem. None of this should be accessible if no password was provided
-                throw $e;
-            }
-        }
-
-        $entity_array['_calculated_fields'] = $this->getEntityCalculations(
-            $model,
-            $db_row,
-            $rest_request,
-            $has_protected_fields
-        );
-        $entity_array                       = apply_filters(
-            'FHEE__Read__create_entity_from_wpdb_results__entity_before_including_requested_models',
-            $entity_array,
-            $model,
-            $rest_request->get_param('caps'),
-            $rest_request,
-            $this
-        );
-        // add an empty protected property for now. If it's still around after we remove everything the request didn't
-        // want, we'll populate it then. k?
-        $entity_array['_protected'] = [];
-        // remove any properties the request didn't want. This way _protected won't bother mentioning them
-        $entity_array = $this->includeOnlyRequestedProperties($model, $rest_request, $entity_array);
-        $entity_array = $this->includeRequestedModels(
-            $model,
-            $rest_request,
-            $entity_array,
-            $db_row,
-            $has_protected_fields
-        );
-        // if they still wanted the _protected property, add it.
-        if (isset($entity_array['_protected'])) {
-            $entity_array = $this->addProtectedProperty($model, $entity_array, $has_protected_fields);
-        }
-        $entity_array = apply_filters(
-            'FHEE__Read__create_entity_from_wpdb_results__entity_before_inaccessible_field_removal',
-            $entity_array,
-            $model,
-            $rest_request->get_param('caps'),
-            $rest_request,
-            $this
-        );
-        if (! $current_user_full_access_to_entity) {
-            $result_without_inaccessible_fields = Capabilities::filterOutInaccessibleEntityFields(
-                $entity_array,
-                $model,
-                $rest_request->get_param('caps'),
-                $this->getModelVersionInfo()
-            );
-        } else {
-            $result_without_inaccessible_fields = $entity_array;
-        }
-        $this->setDebugInfo(
-            'inaccessible fields',
-            array_keys(array_diff_key((array) $entity_array, (array) $result_without_inaccessible_fields))
-        );
-        return apply_filters(
-            'FHEE__Read__create_entity_from_wpdb_results__entity_return',
-            $result_without_inaccessible_fields,
-            $model,
-            $rest_request->get_param('caps')
-        );
-    }
-
-
-    /**
-     * Returns an array describing which fields can be protected, and which actually were removed this request
-     *
-     * @param EEM_Base $model
-     * @param array    $results_so_far
-     * @param bool     $protected
-     * @return array results
-     * @throws EE_Error
-     * @since 4.9.74.p
-     */
-    protected function addProtectedProperty(EEM_Base $model, array $results_so_far, bool $protected): array
-    {
-        if (! $protected || ! $model->hasPassword()) {
-            return $results_so_far;
-        }
-        $password_field  = $model->getPasswordField();
-        $all_protected   = array_merge(
-            [$password_field->get_name()],
-            $password_field->protectedFields()
-        );
-        $fields_included = array_keys($results_so_far);
-        $fields_included = array_intersect(
-            $all_protected,
-            $fields_included
-        );
-        foreach ($fields_included as $field_name) {
-            $results_so_far['_protected'][] = $field_name;
-        }
-        return $results_so_far;
-    }
-
-
-    /**
-     * Creates a REST entity array (JSON object we're going to return in the response, but
-     * for now still a PHP array, but soon enough we'll call json_encode on it, don't worry),
-     * from $wpdb->get_row( $sql, ARRAY_A)
-     *
-     * @param EEM_Base $model
-     * @param array    $db_row
-     * @return array entity mostly ready for converting to JSON and sending in the response
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @throws RestException
-     * @throws Exception
-     */
-    protected function createBareEntityFromWpdbResults(EEM_Base $model, array $db_row): array
-    {
-        $result = $model->deduce_fields_n_values_from_cols_n_values($db_row);
-        $result = array_intersect_key(
-            $result,
-            $this->getModelVersionInfo()->fieldsOnModelInThisVersion($model)
-        );
-        // if this is a CPT, we need to set the global $post to it,
-        // otherwise shortcodes etc won't work properly while rendering it
-        if ($model instanceof EEM_CPT_Base) {
-            $do_chevy_shuffle = true;
-        } else {
-            $do_chevy_shuffle = false;
-        }
-        if ($do_chevy_shuffle) {
-            global $post;
-            $old_post = $post;
-            $post     = get_post($result[ $model->primary_key_name() ]);
-            if (! $post instanceof WP_Post) {
-                // well that's weird, because $result is what we JUST fetched from the database
-                throw new RestException(
-                    'error_fetching_post_from_database_results',
-                    esc_html__(
-                        'An item was retrieved from the database but it\'s not a WP_Post like it should be.',
-                        'event_espresso'
-                    )
-                );
-            }
-            $model_object_classname          = 'EE_' . $model->get_this_model_name();
-            $post->{$model_object_classname} = EE_Registry::instance()->load_class(
-                $model_object_classname,
-                $result,
-                false,
-                false
-            );
-        }
-        foreach ($result as $field_name => $field_value) {
-            $field_obj = $model->field_settings_for($field_name);
-            if ($this->isSubclassOfOne($field_obj, $this->getModelVersionInfo()->fieldsIgnored())) {
-                unset($result[ $field_name ]);
-            } elseif (
-                $this->isSubclassOfOne(
-                    $field_obj,
-                    $this->getModelVersionInfo()->fieldsThatHaveRenderedFormat()
-                )
-            ) {
-                $result[ $field_name ] = [
-                    'raw'      => $this->prepareFieldObjValueForJson($field_obj, $field_value),
-                    'rendered' => $this->prepareFieldObjValueForJson($field_obj, $field_value, 'pretty'),
-                ];
-            } elseif (
-                $this->isSubclassOfOne(
-                    $field_obj,
-                    $this->getModelVersionInfo()->fieldsThatHavePrettyFormat()
-                )
-            ) {
-                $result[ $field_name ] = [
-                    'raw'    => $this->prepareFieldObjValueForJson($field_obj, $field_value),
-                    'pretty' => $this->prepareFieldObjValueForJson($field_obj, $field_value, 'pretty'),
-                ];
-            } elseif ($field_obj instanceof EE_Datetime_Field) {
-                $field_value = $field_obj->prepare_for_set_from_db($field_value);
-                // if the value is null, but we're not supposed to permit null, then set to the field's default
-                if (is_null($field_value)) {
-                    $field_value = $field_obj->getDefaultDateTimeObj();
-                }
-                if (is_null($field_value)) {
-                    $gmt_date = $local_date = ModelDataTranslator::prepareFieldValuesForJson(
-                        $field_obj,
-                        $field_value,
-                        $this->getModelVersionInfo()->requestedVersion()
-                    );
-                } else {
-                    $timezone = $field_value->getTimezone();
-                    EEH_DTT_Helper::setTimezone($field_value, new DateTimeZone('UTC'));
-                    $gmt_date = ModelDataTranslator::prepareFieldValuesForJson(
-                        $field_obj,
-                        $field_value,
-                        $this->getModelVersionInfo()->requestedVersion()
-                    );
-                    EEH_DTT_Helper::setTimezone($field_value, $timezone);
-                    $local_date = ModelDataTranslator::prepareFieldValuesForJson(
-                        $field_obj,
-                        $field_value,
-                        $this->getModelVersionInfo()->requestedVersion()
-                    );
-                }
-                $result[ $field_name . '_gmt' ] = $gmt_date;
-                $result[ $field_name ]          = $local_date;
-            } else {
-                $result[ $field_name ] = $this->prepareFieldObjValueForJson($field_obj, $field_value);
-            }
-        }
-        if ($do_chevy_shuffle) {
-            $post = $old_post;
-        }
-        return $result;
-    }
-
-
-    /**
-     * Takes a value all the way from the DB representation, to the model object's representation, to the
-     * user-facing PHP representation, to the REST API representation. (Assumes you've already taken from the DB
-     * representation using $field_obj->prepare_for_set_from_db())
-     *
-     * @param EE_Model_Field_Base $field_obj
-     * @param mixed               $value  as it's stored on a model object
-     * @param string              $format valid values are 'normal' (default), 'pretty', 'datetime_obj'
-     * @return array|int
-     * @throws RestException if $value contains a PHP object
-     * @throws EE_Error
-     */
-    protected function prepareFieldObjValueForJson(
-        EE_Model_Field_Base $field_obj,
-        $value,
-        string $format = 'normal'
-    ) {
-        $value = $field_obj->prepare_for_set_from_db($value);
-        switch ($format) {
-            case 'pretty':
-                $value = $field_obj->prepare_for_pretty_echoing($value);
-                break;
-            case 'normal':
-            default:
-                $value = $field_obj->prepare_for_get($value);
-                break;
-        }
-        return ModelDataTranslator::prepareFieldValuesForJson(
-            $field_obj,
-            $value,
-            $this->getModelVersionInfo()->requestedVersion()
-        );
-    }
-
-
-    /**
-     * Adds a few extra fields to the entity response
-     *
-     * @param EEM_Base $model
-     * @param array    $db_row
-     * @param array    $entity_array
-     * @return array modified entity
-     * @throws EE_Error
-     */
-    protected function addExtraFields(EEM_Base $model, array $db_row, array $entity_array): array
-    {
-        if ($model instanceof EEM_CPT_Base) {
-            $entity_array['link'] = get_permalink($db_row[ $model->get_primary_key_field()->get_qualified_column() ]);
-        }
-        return $entity_array;
-    }
-
-
-    /**
-     * Gets links we want to add to the response
-     *
-     * @param EEM_Base        $model
-     * @param array           $db_row
-     * @param array           $entity_array
-     * @return array the _links item in the entity
-     * @throws EE_Error
-     * @global WP_REST_Server $wp_rest_server
-     */
-    protected function getEntityLinks(EEM_Base $model, array $db_row, array $entity_array): array
-    {
-        // add basic links
-        $links = [];
-        if ($model->has_primary_key_field()) {
-            $links['self'] = [
-                [
-                    'href' => $this->getVersionedLinkTo(
-                        EEH_Inflector::pluralize_and_lower($model->get_this_model_name())
-                        . '/'
-                        . $entity_array[ $model->primary_key_name() ]
-                    ),
-                ],
-            ];
-        }
-        $links['collection'] = [
-            [
-                'href' => $this->getVersionedLinkTo(
-                    EEH_Inflector::pluralize_and_lower($model->get_this_model_name())
-                ),
-            ],
-        ];
-        // add links to related models
-        if ($model->has_primary_key_field()) {
-            foreach ($this->getModelVersionInfo()->relationSettings($model) as $relation_name => $relation_obj) {
-                $related_model_part                                                      =
-                    Read::getRelatedEntityName($relation_name, $relation_obj);
-                $links[ EED_Core_Rest_Api::ee_api_link_namespace . $related_model_part ] = [
-                    [
-                        'href'   => $this->getVersionedLinkTo(
-                            EEH_Inflector::pluralize_and_lower($model->get_this_model_name())
-                            . '/'
-                            . $entity_array[ $model->primary_key_name() ]
-                            . '/'
-                            . $related_model_part
-                        ),
-                        'single' => $relation_obj instanceof EE_Belongs_To_Relation,
-                    ],
-                ];
-            }
-        }
-        return $links;
-    }
-
-
-    /**
-     * Adds the included models indicated in the request to the entity provided
-     *
-     * @param EEM_Base        $model
-     * @param WP_REST_Request $rest_request
-     * @param array           $entity_array
-     * @param array           $db_row
-     * @param boolean         $included_items_protected if the original item is password protected, don't include any
-     *                                                  related models.
-     * @return array the modified entity
-     * @throws DomainException
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ModelConfigurationException
-     * @throws ReflectionException
-     * @throws UnexpectedEntityException
-     */
-    protected function includeRequestedModels(
-        EEM_Base $model,
-        WP_REST_Request $rest_request,
-        array $entity_array,
-        array $db_row = [],
-        bool $included_items_protected = false
-    ): array {
-        // if $db_row not included, hope the entity array has what we need
-        if (! $db_row) {
-            $db_row = $entity_array;
-        }
-        $relation_settings = $this->getModelVersionInfo()->relationSettings($model);
-        foreach ($relation_settings as $relation_name => $relation_obj) {
-            $related_fields_to_include   = $this->explodeAndGetItemsPrefixedWith(
-                $rest_request->get_param('include'),
-                $relation_name
-            );
-            $related_fields_to_calculate = $this->explodeAndGetItemsPrefixedWith(
-                $rest_request->get_param('calculate'),
-                $relation_name
-            );
-            // did they specify they wanted to include a related model, or
-            // specific fields from a related model?
-            // or did they specify to calculate a field from a related model?
-            if ($related_fields_to_include || $related_fields_to_calculate) {
-                // if so, we should include at least some part of the related model
-                $pretend_related_request = new WP_REST_Request();
-                $pretend_related_request->set_query_params(
-                    [
-                        'caps'      => $rest_request->get_param('caps'),
-                        'include'   => $related_fields_to_include,
-                        'calculate' => $related_fields_to_calculate,
-                        'password'  => $rest_request->get_param('password'),
-                    ]
-                );
-                $pretend_related_request->add_header('no_rest_headers', true);
-                $primary_model_query_params = $model->alter_query_params_to_restrict_by_ID(
-                    $model->get_index_primary_key_string(
-                        $model->deduce_fields_n_values_from_cols_n_values($db_row)
-                    )
-                );
-                if (! $included_items_protected) {
-                    try {
-                        $related_results = $this->getEntitiesFromRelationUsingModelQueryParams(
-                            $primary_model_query_params,
-                            $relation_obj,
-                            $pretend_related_request
-                        );
-                    } catch (RestException $e) {
-                        $related_results = null;
-                    }
-                } else {
-                    // they're protected, hide them.
-                    $related_results              = null;
-                    $entity_array['_protected'][] = Read::getRelatedEntityName($relation_name, $relation_obj);
-                }
-                if ($related_results instanceof WP_Error || $related_results === null) {
-                    $related_results = $relation_obj instanceof EE_Belongs_To_Relation
-                            ? null
-                            : [];
-                }
-                $entity_array[ Read::getRelatedEntityName($relation_name, $relation_obj) ] = $related_results;
-            }
-        }
-        return $entity_array;
-    }
-
-
-    /**
-     * If the user has requested only specific properties (including meta properties like _links or _protected)
-     * remove everything else.
-     *
-     * @param EEM_Base        $model
-     * @param WP_REST_Request $rest_request
-     * @param                 $entity_array
-     * @return array
-     * @throws EE_Error
-     * @since 4.9.74.p
-     */
-    protected function includeOnlyRequestedProperties(
-        EEM_Base $model,
-        WP_REST_Request $rest_request,
-        $entity_array
-    ): array {
-
-        $includes_for_this_model = $this->explodeAndGetItemsPrefixedWith($rest_request->get_param('include'), '');
-        $includes_for_this_model = $this->removeModelNamesFromArray($includes_for_this_model);
-        // if they passed in * or didn't specify any includes, return everything
-        if (! empty($includes_for_this_model) && ! in_array('*', $includes_for_this_model, true)) {
-            if ($model->has_primary_key_field()) {
-                // always include the primary key. ya just gotta know that at least
-                $includes_for_this_model[] = $model->primary_key_name();
-            }
-            if ($this->explodeAndGetItemsPrefixedWith($rest_request->get_param('calculate'), '')) {
-                $includes_for_this_model[] = '_calculated_fields';
-            }
-            $entity_array = array_intersect_key($entity_array, array_flip($includes_for_this_model));
-        }
-        return $entity_array;
-    }
-
-
-    /**
-     * Returns a new array with all the names of models removed. Eg
-     * array( 'Event', 'Datetime.*', 'foobar' ) would become array( 'Datetime.*', 'foobar' )
-     *
-     * @param array $array
-     * @return array
-     */
-    private function removeModelNamesFromArray(array $array): array
-    {
-        return array_diff($array, array_keys(EE_Registry::instance()->non_abstract_db_models));
-    }
-
-
-    /**
-     * Gets the calculated fields for the response
-     *
-     * @param EEM_Base        $model
-     * @param array           $wpdb_row
-     * @param WP_REST_Request $rest_request
-     * @param bool            $row_is_protected whether this row is password protected or not
-     * @return stdClass the _calculations item in the entity
-     * @throws RestException if a default value has a PHP object, which should never do (and if we
-     *                                          did, let's know about it ASAP, so let the exception bubble up)
-     * @throws EE_Error
-     */
-    protected function getEntityCalculations(
-        EEM_Base $model,
-        array $wpdb_row,
-        WP_REST_Request $rest_request,
-        bool $row_is_protected = false
-    ): stdClass {
-        $calculated_fields = $this->explodeAndGetItemsPrefixedWith(
-            $rest_request->get_param('calculate'),
-            ''
-        );
-        // note: setting calculate=* doesn't do anything
-        $calculated_fields_to_return = new stdClass();
-        $protected_fields            = [];
-        foreach ($calculated_fields as $field_to_calculate) {
-            try {
-                // it's password protected, so they shouldn't be able to read this. Remove the value
-                $schema = $this->fields_calculator->getJsonSchemaForModel($model);
-                if (
-                    $row_is_protected
-                    && isset($schema['properties'][ $field_to_calculate ]['protected'])
-                    && $schema['properties'][ $field_to_calculate ]['protected']
-                ) {
-                    $calculated_value   = null;
-                    $protected_fields[] = $field_to_calculate;
-                    if ($schema['properties'][ $field_to_calculate ]['type']) {
-                        switch ($schema['properties'][ $field_to_calculate ]['type']) {
-                            case 'boolean':
-                                $calculated_value = false;
-                                break;
-                            case 'integer':
-                                $calculated_value = 0;
-                                break;
-                            case 'string':
-                                $calculated_value = '';
-                                break;
-                            case 'array':
-                                $calculated_value = [];
-                                break;
-                            case 'object':
-                                $calculated_value = new stdClass();
-                                break;
-                        }
-                    }
-                } else {
-                    $calculated_value = ModelDataTranslator::prepareFieldValueForJson(
-                        null,
-                        $this->fields_calculator->retrieveCalculatedFieldValue(
-                            $model,
-                            $field_to_calculate,
-                            $wpdb_row,
-                            $rest_request,
-                            $this
-                        ),
-                        $this->getModelVersionInfo()->requestedVersion()
-                    );
-                }
-                $calculated_fields_to_return->{$field_to_calculate} = $calculated_value;
-            } catch (RestException $e) {
-                // if we don't have permission to read it, just leave it out. but let devs know about the problem
-                $this->setResponseHeader(
-                    'Notices-Field-Calculation-Errors['
-                    . $e->getStringCode()
-                    . ']['
-                    . $model->get_this_model_name()
-                    . ']['
-                    . $field_to_calculate
-                    . ']',
-                    $e->getMessage()
-                );
-            }
-        }
-        $calculated_fields_to_return->_protected = $protected_fields;
-        return $calculated_fields_to_return;
-    }
-
-
-    /**
-     * Gets the full URL to the resource, taking the requested version into account
-     *
-     * @param string $link_part_after_version_and_slash eg "events/10/datetimes"
-     * @return string url eg "http://mysite.com/wp-json/ee/v4.6/events/10/datetimes"
-     * @throws EE_Error
-     */
-    public function getVersionedLinkTo(string $link_part_after_version_and_slash): string
-    {
-        return rest_url(
-            EED_Core_Rest_Api::get_versioned_route_to(
-                $link_part_after_version_and_slash,
-                $this->getModelVersionInfo()->requestedVersion()
-            )
-        );
-    }
-
-
-    /**
-     * Gets the correct lowercase name for the relation in the API according
-     * to the relation's type
-     *
-     * @param string                 $relation_name
-     * @param EE_Model_Relation_Base $relation_obj
-     * @return string
-     */
-    public static function getRelatedEntityName(string $relation_name, EE_Model_Relation_Base $relation_obj): string
-    {
-        if ($relation_obj instanceof EE_Belongs_To_Relation) {
-            return strtolower($relation_name);
-        }
-        return EEH_Inflector::pluralize_and_lower($relation_name);
-    }
-
-
-    /**
-     * Gets the one model object with the specified id for the specified model
-     *
-     * @param EEM_Base        $model
-     * @param WP_REST_Request $request
-     * @return array
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ModelConfigurationException
-     * @throws ReflectionException
-     * @throws RestException
-     * @throws RestPasswordIncorrectException
-     * @throws RestPasswordRequiredException
-     * @throws UnexpectedEntityException
-     * @throws DomainException
-     */
-    public function getEntityFromModel(EEM_Base $model, WP_REST_Request $request): array
-    {
-        $context = $this->validateContext($request->get_param('caps'));
-        return $this->getOneOrReportPermissionError($model, $request, $context);
-    }
-
-
-    /**
-     * If a context is provided which isn't valid, maybe it was added in a future
-     * version so just treat it as a default read
-     *
-     * @param string|null $context
-     * @return string array key of EEM_Base::cap_contexts_to_cap_action_map()
-     */
-    public function validateContext(?string $context): string
-    {
-        if (! $context) {
-            $context = EEM_Base::caps_read;
-        }
-        $valid_contexts = EEM_Base::valid_cap_contexts();
-        if (in_array($context, $valid_contexts, true)) {
-            return $context;
-        }
-        return EEM_Base::caps_read;
-    }
-
-
-    /**
-     * Verifies the passed in value is an allowable default where conditions value.
-     *
-     * @param string $default_where_conditions
-     * @return string
-     */
-    public function validateDefaultQueryParams(string $default_where_conditions): string
-    {
-        $valid_default_where_conditions_for_api_calls = [
-            EEM_Base::default_where_conditions_all,
-            EEM_Base::default_where_conditions_minimum_all,
-            EEM_Base::default_where_conditions_minimum_others,
-        ];
-        if (! $default_where_conditions) {
-            $default_where_conditions = EEM_Base::default_where_conditions_all;
-        }
-        if (
-            in_array(
-                $default_where_conditions,
-                $valid_default_where_conditions_for_api_calls,
-                true
-            )
-        ) {
-            return $default_where_conditions;
-        }
-        return EEM_Base::default_where_conditions_all;
-    }
-
-
-    /**
-     * Translates API filter get parameter into model query params @param EEM_Base $model
-     *
-     * @param array $query_params
-     * @return array model query params (@see
-     *               https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions)
-     *               or FALSE to indicate that absolutely no results should be returned
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws RestException
-     * @throws DomainException
-     * @throws ReflectionException
-     * @see
-     *               https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions.
-     *               Note: right now the query parameter keys for fields (and related fields) can be left as-is, but
-     *               it's quite possible this will change someday. Also, this method's contents might be candidate for
-     *               moving to Model_Data_Translator
-     *
-     */
-    public function createModelQueryParams(EEM_Base $model, array $query_params): array
-    {
-        $model_query_params = [];
-        if (isset($query_params['where'])) {
-            $model_query_params[0] = ModelDataTranslator::prepareConditionsQueryParamsForModels(
-                $query_params['where'],
-                $model,
-                $this->getModelVersionInfo()->requestedVersion()
-            );
-        }
-        if (isset($query_params['order_by'])) {
-            $order_by = $query_params['order_by'];
-        } elseif (isset($query_params['orderby'])) {
-            $order_by = $query_params['orderby'];
-        } else {
-            $order_by = null;
-        }
-        if ($order_by !== null) {
-            if (is_array($order_by)) {
-                $order_by = ModelDataTranslator::prepareFieldNamesInArrayKeysFromJson($order_by);
-            } else {
-                // it's a single item
-                $order_by = ModelDataTranslator::prepareFieldNameFromJson($order_by);
-            }
-            $model_query_params['order_by'] = $order_by;
-        }
-        if (isset($query_params['group_by'])) {
-            $group_by = $query_params['group_by'];
-        } elseif (isset($query_params['groupby'])) {
-            $group_by = $query_params['groupby'];
-        } else {
-            $group_by = array_keys($model->get_combined_primary_key_fields());
-        }
-        // make sure they're all real names
-        if (is_array($group_by)) {
-            $group_by = ModelDataTranslator::prepareFieldNamesFromJson($group_by);
-        }
-        if ($group_by !== null) {
-            $model_query_params['group_by'] = $group_by;
-        }
-        if (isset($query_params['having'])) {
-            $model_query_params['having'] = ModelDataTranslator::prepareConditionsQueryParamsForModels(
-                $query_params['having'],
-                $model,
-                $this->getModelVersionInfo()->requestedVersion()
-            );
-        }
-        if (isset($query_params['order'])) {
-            $model_query_params['order'] = $query_params['order'];
-        }
-        if (isset($query_params['mine'])) {
-            $model_query_params = $model->alter_query_params_to_only_include_mine($model_query_params);
-        }
-        if (isset($query_params['limit'])) {
-            // limit should be either a string like '23' or '23,43', or an array with two items in it
-            if (! is_array($query_params['limit'])) {
-                $limit_array = explode(',', (string) $query_params['limit']);
-            } else {
-                $limit_array = $query_params['limit'];
-            }
-            $sanitized_limit = [];
-            foreach ($limit_array as $limit_part) {
-                if ($this->debug_mode && (! is_numeric($limit_part) || count($sanitized_limit) > 2)) {
-                    throw new EE_Error(
-                        sprintf(
-                            esc_html__(
-                            // @codingStandardsIgnoreStart
-                                'An invalid limit filter was provided. It was: %s. If the EE4 JSON REST API weren\'t in debug mode, this message would not appear.',
-                                // @codingStandardsIgnoreEnd
-                                'event_espresso'
-                            ),
-                            wp_json_encode($query_params['limit'])
-                        )
-                    );
-                }
-                $sanitized_limit[] = (int) $limit_part;
-            }
-            $model_query_params['limit'] = implode(',', $sanitized_limit);
-        } else {
-            $model_query_params['limit'] = EED_Core_Rest_Api::get_default_query_limit();
-        }
-        if (isset($query_params['caps'])) {
-            $model_query_params['caps'] = $this->validateContext($query_params['caps']);
-        } else {
-            $model_query_params['caps'] = EEM_Base::caps_read;
-        }
-        if (isset($query_params['default_where_conditions'])) {
-            $model_query_params['default_where_conditions'] = $this->validateDefaultQueryParams(
-                $query_params['default_where_conditions']
-            );
-        }
-        // if this is a model protected by a password on another model, exclude the password protected
-        // entities by default. But if they passed in a password, try to show them all. If the password is wrong,
-        // though, they'll get an error (see Read::createEntityFromWpdbResult() which calls Read::checkPassword)
-        if (
-            $model_query_params['caps'] === EEM_Base::caps_read
-            && empty($query_params['password'])
-            && ! $model->hasPassword()
-            && $model->restrictedByRelatedModelPassword()
-        ) {
-            $model_query_params['exclude_protected'] = true;
-        }
-
-        return apply_filters('FHEE__Read__create_model_query_params', $model_query_params, $query_params, $model);
-    }
-
-
-    /**
-     * Changes the REST-style query params for use in the models
-     *
-     * @param EEM_Base $model
-     * @param array    $query_params sub-array from @see EEM_Base::get_all()
-     * @return array
-     * @deprecated
-     */
-    public function prepareRestQueryParamsKeyForModels(EEM_Base $model, array $query_params): array
-    {
-        $model_ready_query_params = [];
-        foreach ($query_params as $key => $value) {
-            $model_ready_query_params[ $key ] = is_array($value)
-                ? $this->prepareRestQueryParamsKeyForModels($model, $value)
-                : $value;
-        }
-        return $model_ready_query_params;
-    }
-
-
-    /**
-     * @param $model
-     * @param $query_params
-     * @return array
-     * @deprecated instead use ModelDataTranslator::prepareFieldValuesFromJson()
-     */
-    public function prepareRestQueryParamsValuesForModels($model, $query_params): array
-    {
-        $model_ready_query_params = [];
-        foreach ($query_params as $key => $value) {
-            if (is_array($value)) {
-                $model_ready_query_params[ $key ] = $this->prepareRestQueryParamsValuesForModels($model, $value);
-            } else {
-                $model_ready_query_params[ $key ] = $value;
-            }
-        }
-        return $model_ready_query_params;
-    }
-
-
-    /**
-     * Explodes the string on commas, and only returns items with $prefix followed by a period.
-     * If no prefix is specified, returns items with no period.
-     *
-     * @param string|array $string_to_explode eg "jibba,jabba, blah, blah, blah" or array('jibba', 'jabba' )
-     * @param string       $prefix            "Event" or "foobar"
-     * @return array $string_to_exploded exploded on COMMAS, and if a prefix was specified
-     *                                        we only return strings starting with that and a period; if no prefix was
-     *                                        specified we return all items containing NO periods
-     */
-    public function explodeAndGetItemsPrefixedWith($string_to_explode, string $prefix): array
-    {
-        if (is_string($string_to_explode)) {
-            $exploded_contents = explode(',', $string_to_explode);
-        } elseif (is_array($string_to_explode)) {
-            $exploded_contents = $string_to_explode;
-        } else {
-            $exploded_contents = [];
-        }
-        // if the string was empty, we want an empty array
-        $exploded_contents    = array_filter($exploded_contents);
-        $contents_with_prefix = [];
-        foreach ($exploded_contents as $item) {
-            $item = trim($item);
-            // if no prefix was provided, so we look for items with no "." in them
-            if (! $prefix) {
-                // does this item have a period?
-                if (strpos($item, '.') === false) {
-                    // if not, then its what we're looking for
-                    $contents_with_prefix[] = $item;
-                }
-            } elseif (strpos($item, $prefix . '.') === 0) {
-                // this item has the prefix and a period, grab it
-                $contents_with_prefix[] = substr(
-                    $item,
-                    strpos($item, $prefix . '.') + strlen($prefix . '.')
-                );
-            } elseif ($item === $prefix) {
-                // this item is JUST the prefix
-                // so let's grab everything after, which is a blank string
-                $contents_with_prefix[] = '';
-            }
-        }
-        return $contents_with_prefix;
-    }
-
-
-    /**
-     * @param string      $include_string @see Read:handle_request_get_all
-     * @param string|null $model_name
-     * @return array of fields for this model. If $model_name is provided, then
-     *                                    the fields for that model, with the model's name removed from each.
-     *                                    If $include_string was blank or '*' returns an empty array
-     * @throws EE_Error
-     * @throws EE_Error
-     * @deprecated since 4.8.36.rc.001 You should instead use Read::explode_and_get_items_prefixed_with.
-     *                                    Deprecated because its return values were really quite confusing- sometimes
-     *                                    it
-     *                                    returned an empty array (when the include string was blank or '*') or
-     *                                    sometimes it returned array('*') (when you provided a model and a model of
-     *                                    that kind was found). Parses the $include_string so we fetch all the field
-     *                                    names relating to THIS model
-     *                                    (ie have NO period in them), or for the provided model (ie start with the
-     *                                    model name and then a period).
-     */
-    public function extractIncludesForThisModel(string $include_string, string $model_name = null): array
-    {
-        if (is_array($include_string)) {
-            $include_string = implode(',', $include_string);
-        }
-        if ($include_string === '*' || $include_string === '') {
-            return [];
-        }
-        $includes                    = explode(',', $include_string);
-        $extracted_fields_to_include = [];
-        if ($model_name) {
-            foreach ($includes as $field_to_include) {
-                $field_to_include = trim($field_to_include);
-                if (strpos($field_to_include, $model_name . '.') === 0) {
-                    // found the model name at the exact start
-                    $field_sans_model_name         = str_replace($model_name . '.', '', $field_to_include);
-                    $extracted_fields_to_include[] = $field_sans_model_name;
-                } elseif ($field_to_include === $model_name) {
-                    $extracted_fields_to_include[] = '*';
-                }
-            }
-        } else {
-            // look for ones with no period
-            foreach ($includes as $field_to_include) {
-                $field_to_include = trim($field_to_include);
-                if (
-                    strpos($field_to_include, '.') === false
-                    && ! $this->getModelVersionInfo()->isModelNameInThisVersion($field_to_include)
-                ) {
-                    $extracted_fields_to_include[] = $field_to_include;
-                }
-            }
-        }
-        return $extracted_fields_to_include;
-    }
-
-
-    /**
-     * Gets the single item using the model according to the request in the context given, otherwise
-     * returns that it's inaccessible to the current user
-     *
-     * @param EEM_Base        $model
-     * @param WP_REST_Request $request
-     * @param null            $context
-     * @return array
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function getOneOrReportPermissionError(EEM_Base $model, WP_REST_Request $request, $context = null): array
-    {
-        $query_params = [[$model->primary_key_name() => $request->get_param('id')], 'limit' => 1];
-        if ($model instanceof EEM_Soft_Delete_Base) {
-            $query_params = $model->alter_query_params_so_deleted_and_undeleted_items_included($query_params);
-        }
-        $restricted_query_params         = $query_params;
-        $restricted_query_params['caps'] = $context;
-        $this->setDebugInfo('model query params', $restricted_query_params);
-        $model_rows = $model->get_all_wpdb_results($restricted_query_params);
-        if (! empty($model_rows)) {
-            return $this->createEntityFromWpdbResult(
-                $model,
-                reset($model_rows),
-                $request
-            );
-        }
-        // ok let's test to see if we WOULD have found it, had we not had restrictions from missing capabilities
-        $lowercase_model_name = strtolower($model->get_this_model_name());
-        if ($model->exists($query_params)) {
-            // you got shafted- it existed but we didn't want to tell you!
-            throw new RestException(
-                'rest_user_cannot_' . $context,
-                sprintf(
-                    __('Sorry, you cannot %1$s this %2$s. Missing permissions are: %3$s', 'event_espresso'),
-                    $context,
-                    $lowercase_model_name,
-                    Capabilities::getMissingPermissionsString(
-                        $model,
-                        $context
-                    )
-                ),
-                ['status' => 403]
-            );
-        }
-        // it's not you. It just doesn't exist
-        throw new RestException(
-            sprintf('rest_%s_invalid_id', $lowercase_model_name),
-            sprintf(__('Invalid %s ID.', 'event_espresso'), $lowercase_model_name),
-            ['status' => 404]
-        );
-    }
-
-
-    /**
-     * Checks that if this content requires a password to be read, that it's been provided and is correct.
-     *
-     * @param EEM_Base        $model
-     * @param array           $model_row
-     * @param array           $query_params Adds 'default_where_conditions' => 'minimum'
-     *                                      to ensure we don't confuse trashed with password protected.
-     * @param WP_REST_Request $request
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws RestPasswordRequiredException
-     * @throws RestPasswordIncorrectException
-     * @throws ModelConfigurationException
-     * @throws ReflectionException
-     * @since 4.9.74.p
-     */
-    protected function checkPassword(EEM_Base $model, array $model_row, array $query_params, WP_REST_Request $request)
-    {
-        $query_params['default_where_conditions'] = 'minimum';
-        // stuff is only "protected" for front-end requests. Elsewhere, you either get full permission to access the object
-        // or you don't.
-        $request_caps = $request->get_param('caps');
-        if (isset($request_caps) && $request_caps !== EEM_Base::caps_read) {
-            return;
-        }
-        // if this entity requires a password, they better give it and it better be right!
-        if (
-            $model->hasPassword()
-            && $model_row[ $model->getPasswordField()->get_qualified_column() ] !== ''
-        ) {
-            if (empty($request['password'])) {
-                throw new RestPasswordRequiredException();
-            }
-            if (
-                ! hash_equals(
-                    $model_row[ $model->getPasswordField()->get_qualified_column() ],
-                    $request['password']
-                )
-            ) {
-                throw new RestPasswordIncorrectException();
-            }
-        } elseif (
-            // wait! maybe this content is password protected
-            $model->restrictedByRelatedModelPassword()
-            && $request->get_param('caps') === EEM_Base::caps_read
-        ) {
-            $password_supplied = $request->get_param('password');
-            if (empty($password_supplied)) {
-                $query_params['exclude_protected'] = true;
-                if (! $model->exists($query_params)) {
-                    throw new RestPasswordRequiredException();
-                }
-            } else {
-                $query_params[0][ $model->modelChainAndPassword() ] = $password_supplied;
-                if (! $model->exists($query_params)) {
-                    throw new RestPasswordIncorrectException();
-                }
-            }
-        }
-    }
+	protected CalculatedModelFields $fields_calculator;
+
+
+	/**
+	 * Read constructor.
+	 *
+	 * @param CalculatedModelFields $fields_calculator
+	 */
+	public function __construct(CalculatedModelFields $fields_calculator)
+	{
+		parent::__construct();
+		$this->fields_calculator = $fields_calculator;
+	}
+
+
+	/**
+	 * @return Read
+	 */
+	private static function getReadController(): Read
+	{
+		return LoaderFactory::getLoader()->getNew(Read::class);
+	}
+
+
+	/**
+	 * Handles requests to get all (or a filtered subset) of entities for a particular model
+	 *
+	 * @param WP_REST_Request $request
+	 * @param string          $version
+	 * @param string          $model_name
+	 * @return WP_REST_Response
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public static function handleRequestGetAll(
+		WP_REST_Request $request,
+		string $version,
+		string $model_name
+	): WP_REST_Response {
+		$controller = self::getReadController();
+		try {
+			$controller->setRequestedVersion($version);
+			if (! $controller->getModelVersionInfo()->isModelNameInThisVersion($model_name)) {
+				return $controller->sendResponse(
+					new WP_Error(
+						'endpoint_parsing_error',
+						sprintf(
+							esc_html__(
+								'There is no model for endpoint %s. Please contact event espresso support',
+								'event_espresso'
+							),
+							$model_name
+						)
+					)
+				);
+			}
+			return $controller->sendResponse(
+				$controller->getEntitiesFromModel(
+					$controller->getModelVersionInfo()->loadModel($model_name),
+					$request
+				)
+			);
+		} catch (Exception $e) {
+			return $controller->sendResponse($e);
+		}
+	}
+
+
+	/**
+	 * Prepares and returns schema for any OPTIONS request.
+	 *
+	 * @param string $version    The API endpoint version being used.
+	 * @param string $model_name Something like `Event` or `Registration`
+	 * @return array
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 */
+	public static function handleSchemaRequest(string $version, string $model_name): array
+	{
+		$controller = self::getReadController();
+		try {
+			$controller->setRequestedVersion($version);
+			if (! $controller->getModelVersionInfo()->isModelNameInThisVersion($model_name)) {
+				return [];
+			}
+			// get the model for this version
+			$model        = $controller->getModelVersionInfo()->loadModel($model_name);
+			$model_schema = new JsonModelSchema(
+				$model,
+				LoaderFactory::getLoader()->getShared('EventEspresso\core\libraries\rest_api\CalculatedModelFields')
+			);
+			return $model_schema->getModelSchemaForRelations(
+				$controller->getModelVersionInfo()->relationSettings($model),
+				$controller->customizeSchemaForRestResponse(
+					$model,
+					$model_schema->getModelSchemaForFields(
+						$controller->getModelVersionInfo()->fieldsOnModelInThisVersion($model),
+						$model_schema->getInitialSchemaStructure()
+					)
+				)
+			);
+		} catch (Exception $e) {
+			error_log($e->getMessage());
+			return [];
+		}
+	}
+
+
+	/**
+	 * This loops through each field in the given schema for the model and does the following:
+	 * - add any extra fields that are REST API specific and related to existing fields.
+	 * - transform default values into the correct format for a REST API response.
+	 *
+	 * @param EEM_Base $model
+	 * @param array    $schema
+	 * @return array  The final schema.
+	 * @throws EE_Error
+	 */
+	public function customizeSchemaForRestResponse(EEM_Base $model, array $schema): array
+	{
+		foreach ($this->getModelVersionInfo()->fieldsOnModelInThisVersion($model) as $field_name => $field) {
+			$schema = $this->translateDefaultsForRestResponse(
+				$field_name,
+				$field,
+				$this->maybeAddExtraFieldsToSchema($field_name, $field, $schema)
+			);
+		}
+		return $schema;
+	}
+
+
+	/**
+	 * This is used to ensure that the 'default' value set in the schema response is formatted correctly for the REST
+	 * response.
+	 *
+	 * @param                      $field_name
+	 * @param EE_Model_Field_Base  $field
+	 * @param array                $schema
+	 * @return array
+	 * @throws RestException  if a default value has a PHP object, which we should never do
+	 *                                  (but if we did, let's know about it ASAP, so let the exception bubble up)
+	 * @throws EE_Error
+	 *
+	 */
+	protected function translateDefaultsForRestResponse($field_name, EE_Model_Field_Base $field, array $schema): array
+	{
+		if (isset($schema['properties'][ $field_name ]['default'])) {
+			if (is_array($schema['properties'][ $field_name ]['default'])) {
+				foreach ($schema['properties'][ $field_name ]['default'] as $default_key => $default_value) {
+					if ($default_key === 'raw') {
+						$schema['properties'][ $field_name ]['default'][ $default_key ] =
+							ModelDataTranslator::prepareFieldValueForJson(
+								$field,
+								$default_value,
+								$this->getModelVersionInfo()->requestedVersion()
+							);
+					}
+				}
+			} else {
+				$schema['properties'][ $field_name ]['default'] = ModelDataTranslator::prepareFieldValueForJson(
+					$field,
+					$schema['properties'][ $field_name ]['default'],
+					$this->getModelVersionInfo()->requestedVersion()
+				);
+			}
+		}
+		return $schema;
+	}
+
+
+	/**
+	 * Adds additional fields to the schema
+	 * The REST API returns a GMT value field for each datetime field in the resource.  Thus the description about this
+	 * needs to be added to the schema.
+	 *
+	 * @param                      $field_name
+	 * @param EE_Model_Field_Base  $field
+	 * @param array                $schema
+	 * @return array
+	 */
+	protected function maybeAddExtraFieldsToSchema($field_name, EE_Model_Field_Base $field, array $schema): array
+	{
+		if ($field instanceof EE_Datetime_Field) {
+			$schema['properties'][ $field_name . '_gmt' ] = $field->getSchema();
+			// modify the description
+			$schema['properties'][ $field_name . '_gmt' ]['description'] = sprintf(
+				esc_html__('%s - the value for this field is in GMT.', 'event_espresso'),
+				wp_specialchars_decode($field->get_nicename(), ENT_QUOTES)
+			);
+		}
+		return $schema;
+	}
+
+
+	/**
+	 * Used to figure out the route from the request when a `WP_REST_Request` object is not available
+	 *
+	 * @return string
+	 */
+	protected function getRouteFromRequest(): string
+	{
+		if (
+			isset($GLOBALS['wp'])
+			&& $GLOBALS['wp'] instanceof WP
+			&& isset($GLOBALS['wp']->query_vars['rest_route'])
+		) {
+			return $GLOBALS['wp']->query_vars['rest_route'];
+		}
+		/** @var RequestInterface $request */
+		$request = LoaderFactory::getLoader()->getShared(RequestInterface::class);
+		return $request->serverParamIsSet('PATH_INFO')
+			? $request->getServerParam('PATH_INFO')
+			: '/';
+	}
+
+
+	/**
+	 * Gets a single entity related to the model indicated in the path and its id
+	 *
+	 * @param WP_REST_Request $request
+	 * @param string          $version
+	 * @param string          $model_name
+	 * @return WP_REST_Response
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidArgumentException
+	 */
+	public static function handleRequestGetOne(
+		WP_REST_Request $request,
+		string $version,
+		string $model_name
+	): WP_REST_Response {
+		$controller = self::getReadController();
+		try {
+			$controller->setRequestedVersion($version);
+			if (! $controller->getModelVersionInfo()->isModelNameInThisVersion($model_name)) {
+				return $controller->sendResponse(
+					new WP_Error(
+						'endpoint_parsing_error',
+						sprintf(
+							esc_html__(
+								'There is no model for endpoint %s. Please contact event espresso support',
+								'event_espresso'
+							),
+							$model_name
+						)
+					)
+				);
+			}
+			return $controller->sendResponse(
+				$controller->getEntityFromModel(
+					$controller->getModelVersionInfo()->loadModel($model_name),
+					$request
+				)
+			);
+		} catch (Exception $e) {
+			return $controller->sendResponse($e);
+		}
+	}
+
+
+	/**
+	 * Gets all the related entities (or if its a belongs-to relation just the one)
+	 * to the item with the given id
+	 *
+	 * @param WP_REST_Request $request
+	 * @param string          $version
+	 * @param string          $model_name
+	 * @param string          $related_model_name
+	 * @return WP_REST_Response
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws InvalidArgumentException
+	 */
+	public static function handleRequestGetRelated(
+		WP_REST_Request $request,
+		string $version,
+		string $model_name,
+		string $related_model_name
+	): WP_REST_Response {
+		$controller = self::getReadController();
+		try {
+			$controller->setRequestedVersion($version);
+			$main_model = $controller->validateModel($model_name);
+			$controller->validateModel($related_model_name);
+			return $controller->sendResponse(
+				$controller->getEntitiesFromRelation(
+					$request->get_param('id'),
+					$main_model->related_settings_for($related_model_name),
+					$request
+				)
+			);
+		} catch (Exception $e) {
+			return $controller->sendResponse($e);
+		}
+	}
+
+
+	/**
+	 * Gets a collection for the given model and filters
+	 *
+	 * @param EEM_Base        $model
+	 * @param WP_REST_Request $request
+	 * @return array
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ModelConfigurationException
+	 * @throws ReflectionException
+	 * @throws RestException
+	 * @throws RestPasswordIncorrectException
+	 * @throws RestPasswordRequiredException
+	 * @throws UnexpectedEntityException
+	 */
+	public function getEntitiesFromModel(EEM_Base $model, WP_REST_Request $request): array
+	{
+		$query_params = $this->createModelQueryParams($model, $request->get_params());
+		if (! Capabilities::currentUserHasPartialAccessTo($model, $query_params['caps'])) {
+			$model_name_plural = EEH_Inflector::pluralize_and_lower($model->get_this_model_name());
+			throw new RestException(
+				sprintf('rest_%s_cannot_list', $model_name_plural),
+				sprintf(
+					esc_html__('Sorry, you are not allowed to list %1$s. Missing permissions: %2$s', 'event_espresso'),
+					$model_name_plural,
+					Capabilities::getMissingPermissionsString($model, $query_params['caps'])
+				),
+				['status' => 403]
+			);
+		}
+		if (! $request->get_header('no_rest_headers')) {
+			$this->setHeadersFromQueryParams($model, $query_params);
+		}
+		/** @type array $results */
+		$results      = $model->get_all_wpdb_results($query_params);
+		$nice_results = [];
+		foreach ($results as $result) {
+			$nice_results[] = $this->createEntityFromWpdbResult(
+				$model,
+				$result,
+				$request
+			);
+		}
+		return $nice_results;
+	}
+
+
+	/**
+	 * Gets the collection for given relation object
+	 * The same as Read::get_entities_from_model(), except if the relation
+	 * is a HABTM relation, in which case it merges any non-foreign-key fields from
+	 * the join-model-object into the results
+	 *
+	 * @param array                  $primary_model_query_params  query params for finding the item from which
+	 *                                                            relations will be based
+	 * @param EE_Model_Relation_Base $relation
+	 * @param WP_REST_Request        $request
+	 * @return array|null
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ModelConfigurationException
+	 * @throws ReflectionException
+	 * @throws RestException
+	 * @throws ModelConfigurationException
+	 * @throws UnexpectedEntityException
+	 * @throws Exception
+	 */
+	protected function getEntitiesFromRelationUsingModelQueryParams(
+		array $primary_model_query_params,
+		EE_Model_Relation_Base $relation,
+		WP_REST_Request $request
+	): ?array {
+		$context       = $this->validateContext($request->get_param('caps'));
+		$model         = $relation->get_this_model();
+		$related_model = $relation->get_other_model();
+		if (! isset($primary_model_query_params[0])) {
+			$primary_model_query_params[0] = [];
+		}
+		// check if they can access the 1st model object
+		$primary_model_query_params = [
+			0       => $primary_model_query_params[0],
+			'limit' => 1,
+		];
+		if ($model instanceof EEM_Soft_Delete_Base) {
+			$primary_model_query_params = $model->alter_query_params_so_deleted_and_undeleted_items_included(
+				$primary_model_query_params
+			);
+		}
+		$restricted_query_params          = $primary_model_query_params;
+		$restricted_query_params['caps']  = $context;
+		$restricted_query_params['limit'] = 1;
+		$this->setDebugInfo('main model query params', $restricted_query_params);
+		$this->setDebugInfo('missing caps', Capabilities::getMissingPermissionsString($related_model, $context));
+		$primary_model_rows = $model->get_all_wpdb_results($restricted_query_params);
+		$primary_model_row  = null;
+		if (is_array($primary_model_rows)) {
+			$primary_model_row = reset($primary_model_rows);
+		}
+		if (
+			! (
+				$primary_model_row
+				&& Capabilities::currentUserHasPartialAccessTo($related_model, $context)
+			)
+		) {
+			if ($relation instanceof EE_Belongs_To_Relation) {
+				$related_model_name_maybe_plural = strtolower($related_model->get_this_model_name());
+			} else {
+				$related_model_name_maybe_plural = EEH_Inflector::pluralize_and_lower(
+					$related_model->get_this_model_name()
+				);
+			}
+			throw new RestException(
+				sprintf('rest_%s_cannot_list', $related_model_name_maybe_plural),
+				sprintf(
+					esc_html__(
+						'Sorry, you are not allowed to list %1$s related to %2$s. Missing permissions: %3$s',
+						'event_espresso'
+					),
+					$related_model_name_maybe_plural,
+					$relation->get_this_model()->get_this_model_name(),
+					implode(
+						',',
+						array_keys(
+							Capabilities::getMissingPermissions($related_model, $context)
+						)
+					)
+				),
+				['status' => 403]
+			);
+		}
+
+		$this->checkPassword(
+			$model,
+			$primary_model_row,
+			$restricted_query_params,
+			$request
+		);
+		$query_params = $this->createModelQueryParams($relation->get_other_model(), $request->get_params());
+		foreach ($primary_model_query_params[0] as $where_condition_key => $where_condition_value) {
+			$query_params[0][ $relation->get_this_model()->get_this_model_name()
+							  . '.'
+							  . $where_condition_key ] = $where_condition_value;
+		}
+		$query_params['default_where_conditions'] = 'none';
+		$query_params['caps']                     = $context;
+		if (! $request->get_header('no_rest_headers')) {
+			$this->setHeadersFromQueryParams($relation->get_other_model(), $query_params);
+		}
+		/** @type array $results */
+		$results      = $relation->get_other_model()->get_all_wpdb_results($query_params);
+		$nice_results = [];
+		foreach ($results as $result) {
+			$nice_result = $this->createEntityFromWpdbResult(
+				$relation->get_other_model(),
+				$result,
+				$request
+			);
+			if ($relation instanceof EE_HABTM_Relation) {
+				// put the unusual stuff (properties from the HABTM relation) first, and make sure
+				// if there are conflicts we prefer the properties from the main model
+				$join_model_result = $this->createEntityFromWpdbResult(
+					$relation->get_join_model(),
+					$result,
+					$request
+				);
+				$joined_result     = array_merge($join_model_result, $nice_result);
+				// but keep the meta stuff from the main model
+				if (isset($nice_result['meta'])) {
+					$joined_result['meta'] = $nice_result['meta'];
+				}
+				$nice_result = $joined_result;
+			}
+			$nice_results[] = $nice_result;
+		}
+		if ($relation instanceof EE_Belongs_To_Relation) {
+			return array_shift($nice_results);
+		} else {
+			return $nice_results;
+		}
+	}
+
+
+	/**
+	 * Gets the collection for given relation object
+	 * The same as Read::get_entities_from_model(), except if the relation
+	 * is a HABTM relation, in which case it merges any non-foreign-key fields from
+	 * the join-model-object into the results
+	 *
+	 * @param int|string             $id the ID of the thing we are fetching related stuff from
+	 * @param EE_Model_Relation_Base $relation
+	 * @param WP_REST_Request        $request
+	 * @return array
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 * @throws RestException
+	 * @throws ModelConfigurationException
+	 * @throws UnexpectedEntityException
+	 * @throws Exception
+	 */
+	public function getEntitiesFromRelation($id, EE_Model_Relation_Base $relation, WP_REST_Request $request): array
+	{
+		if (! $relation->get_this_model()->has_primary_key_field()) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+					// @codingStandardsIgnoreStart
+						'Read::get_entities_from_relation should only be called from a model with a primary key, it was called from %1$s',
+						// @codingStandardsIgnoreEnd
+						'event_espresso'
+					),
+					$relation->get_this_model()->get_this_model_name()
+				)
+			);
+		}
+		// can we edit that main item?
+		// if not, show nothing but an error
+		// otherwise, please proceed
+		return $this->getEntitiesFromRelationUsingModelQueryParams(
+			[
+				[
+					$relation->get_this_model()->primary_key_name() => $id,
+				],
+			],
+			$relation,
+			$request
+		);
+	}
+
+
+	/**
+	 * Sets the headers that are based on the model and query params,
+	 * like the total records. This should only be called on the original request
+	 * from the client, not on subsequent internal
+	 *
+	 * @param EEM_Base $model
+	 * @param array    $query_params
+	 * @return void
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	protected function setHeadersFromQueryParams(EEM_Base $model, array $query_params)
+	{
+		$this->setDebugInfo('model query params', $query_params);
+		$this->setDebugInfo(
+			'missing caps',
+			Capabilities::getMissingPermissionsString($model, $query_params['caps'])
+		);
+		// normally the limit to a 2-part array, where the 2nd item is the limit
+		if (! isset($query_params['limit'])) {
+			$query_params['limit'] = EED_Core_Rest_Api::get_default_query_limit();
+		}
+		if (is_array($query_params['limit'])) {
+			$limit_parts = $query_params['limit'];
+		} else {
+			$limit_parts = explode(',', $query_params['limit']);
+			if (count($limit_parts) === 1) {
+				$limit_parts = [0, $limit_parts[0]];
+			}
+		}
+		// remove the group by and having parts of the query, as those will
+		// make the sql query return an array of values, instead of just a single value
+		unset($query_params['group_by'], $query_params['having'], $query_params['limit']);
+		$count = $model->count($query_params, null, true);
+		$pages = $count / $limit_parts[1];
+		$this->setResponseHeader('Total', $count, false);
+		$this->setResponseHeader('PageSize', $limit_parts[1], false);
+		$this->setResponseHeader('TotalPages', ceil($pages), false);
+	}
+
+
+	/**
+	 * Changes database results into REST API entities
+	 *
+	 * @param EEM_Base             $model
+	 * @param array                $db_row     like results from $wpdb->get_results()
+	 * @param WP_REST_Request|null $rest_request
+	 * @param string|null          $deprecated no longer used
+	 * @return array ready for being converted into json for sending to client
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ModelConfigurationException
+	 * @throws ReflectionException
+	 * @throws RestException
+	 * @throws RestPasswordIncorrectException
+	 * @throws RestPasswordRequiredException
+	 * @throws UnexpectedEntityException
+	 */
+	public function createEntityFromWpdbResult(
+		EEM_Base $model,
+		array $db_row,
+		?WP_REST_Request $rest_request,
+		string $deprecated = null
+	): array {
+		if (! $rest_request instanceof WP_REST_Request) {
+			// ok so this was called in the old style, where the 3rd arg was
+			// $include, and the 4th arg was $context
+			// now setup the request just to avoid fatal errors, although we won't be able
+			// to truly make use of it because it's kinda devoid of info
+			$rest_request = new WP_REST_Request();
+			$rest_request->set_param('include', $rest_request);
+			$rest_request->set_param('caps', $deprecated);
+		}
+		if ($rest_request->get_param('caps') === null) {
+			$rest_request->set_param('caps', EEM_Base::caps_read);
+		}
+		$current_user_full_access_to_entity = $model->currentUserCan(
+			EEM_Base::caps_read_admin,
+			$model->deduce_fields_n_values_from_cols_n_values($db_row)
+		);
+		$entity_array                       = $this->createBareEntityFromWpdbResults($model, $db_row);
+		$entity_array                       = $this->addExtraFields($model, $db_row, $entity_array);
+		$entity_array['_links']             = $this->getEntityLinks($model, $db_row, $entity_array);
+		// when it's a regular read request for a model with a password and the password wasn't provided
+		// remove the password protected fields
+		$has_protected_fields = false;
+		try {
+			$this->checkPassword(
+				$model,
+				$db_row,
+				$model->alter_query_params_to_restrict_by_ID(
+					$model->get_index_primary_key_string(
+						$model->deduce_fields_n_values_from_cols_n_values($db_row)
+					)
+				),
+				$rest_request
+			);
+		} catch (RestPasswordRequiredException $e) {
+			if ($model->hasPassword()) {
+				// just remove protected fields
+				$has_protected_fields = true;
+				$entity_array         = Capabilities::filterOutPasswordProtectedFields(
+					$entity_array,
+					$model,
+					$this->getModelVersionInfo()
+				);
+			} else {
+				// that's a problem. None of this should be accessible if no password was provided
+				throw $e;
+			}
+		}
+
+		$entity_array['_calculated_fields'] = $this->getEntityCalculations(
+			$model,
+			$db_row,
+			$rest_request,
+			$has_protected_fields
+		);
+		$entity_array                       = apply_filters(
+			'FHEE__Read__create_entity_from_wpdb_results__entity_before_including_requested_models',
+			$entity_array,
+			$model,
+			$rest_request->get_param('caps'),
+			$rest_request,
+			$this
+		);
+		// add an empty protected property for now. If it's still around after we remove everything the request didn't
+		// want, we'll populate it then. k?
+		$entity_array['_protected'] = [];
+		// remove any properties the request didn't want. This way _protected won't bother mentioning them
+		$entity_array = $this->includeOnlyRequestedProperties($model, $rest_request, $entity_array);
+		$entity_array = $this->includeRequestedModels(
+			$model,
+			$rest_request,
+			$entity_array,
+			$db_row,
+			$has_protected_fields
+		);
+		// if they still wanted the _protected property, add it.
+		if (isset($entity_array['_protected'])) {
+			$entity_array = $this->addProtectedProperty($model, $entity_array, $has_protected_fields);
+		}
+		$entity_array = apply_filters(
+			'FHEE__Read__create_entity_from_wpdb_results__entity_before_inaccessible_field_removal',
+			$entity_array,
+			$model,
+			$rest_request->get_param('caps'),
+			$rest_request,
+			$this
+		);
+		if (! $current_user_full_access_to_entity) {
+			$result_without_inaccessible_fields = Capabilities::filterOutInaccessibleEntityFields(
+				$entity_array,
+				$model,
+				$rest_request->get_param('caps'),
+				$this->getModelVersionInfo()
+			);
+		} else {
+			$result_without_inaccessible_fields = $entity_array;
+		}
+		$this->setDebugInfo(
+			'inaccessible fields',
+			array_keys(array_diff_key((array) $entity_array, (array) $result_without_inaccessible_fields))
+		);
+		return apply_filters(
+			'FHEE__Read__create_entity_from_wpdb_results__entity_return',
+			$result_without_inaccessible_fields,
+			$model,
+			$rest_request->get_param('caps')
+		);
+	}
+
+
+	/**
+	 * Returns an array describing which fields can be protected, and which actually were removed this request
+	 *
+	 * @param EEM_Base $model
+	 * @param array    $results_so_far
+	 * @param bool     $protected
+	 * @return array results
+	 * @throws EE_Error
+	 * @since 4.9.74.p
+	 */
+	protected function addProtectedProperty(EEM_Base $model, array $results_so_far, bool $protected): array
+	{
+		if (! $protected || ! $model->hasPassword()) {
+			return $results_so_far;
+		}
+		$password_field  = $model->getPasswordField();
+		$all_protected   = array_merge(
+			[$password_field->get_name()],
+			$password_field->protectedFields()
+		);
+		$fields_included = array_keys($results_so_far);
+		$fields_included = array_intersect(
+			$all_protected,
+			$fields_included
+		);
+		foreach ($fields_included as $field_name) {
+			$results_so_far['_protected'][] = $field_name;
+		}
+		return $results_so_far;
+	}
+
+
+	/**
+	 * Creates a REST entity array (JSON object we're going to return in the response, but
+	 * for now still a PHP array, but soon enough we'll call json_encode on it, don't worry),
+	 * from $wpdb->get_row( $sql, ARRAY_A)
+	 *
+	 * @param EEM_Base $model
+	 * @param array    $db_row
+	 * @return array entity mostly ready for converting to JSON and sending in the response
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @throws RestException
+	 * @throws Exception
+	 */
+	protected function createBareEntityFromWpdbResults(EEM_Base $model, array $db_row): array
+	{
+		$result = $model->deduce_fields_n_values_from_cols_n_values($db_row);
+		$result = array_intersect_key(
+			$result,
+			$this->getModelVersionInfo()->fieldsOnModelInThisVersion($model)
+		);
+		// if this is a CPT, we need to set the global $post to it,
+		// otherwise shortcodes etc won't work properly while rendering it
+		if ($model instanceof EEM_CPT_Base) {
+			$do_chevy_shuffle = true;
+		} else {
+			$do_chevy_shuffle = false;
+		}
+		if ($do_chevy_shuffle) {
+			global $post;
+			$old_post = $post;
+			$post     = get_post($result[ $model->primary_key_name() ]);
+			if (! $post instanceof WP_Post) {
+				// well that's weird, because $result is what we JUST fetched from the database
+				throw new RestException(
+					'error_fetching_post_from_database_results',
+					esc_html__(
+						'An item was retrieved from the database but it\'s not a WP_Post like it should be.',
+						'event_espresso'
+					)
+				);
+			}
+			$model_object_classname          = 'EE_' . $model->get_this_model_name();
+			$post->{$model_object_classname} = EE_Registry::instance()->load_class(
+				$model_object_classname,
+				$result,
+				false,
+				false
+			);
+		}
+		foreach ($result as $field_name => $field_value) {
+			$field_obj = $model->field_settings_for($field_name);
+			if ($this->isSubclassOfOne($field_obj, $this->getModelVersionInfo()->fieldsIgnored())) {
+				unset($result[ $field_name ]);
+			} elseif (
+				$this->isSubclassOfOne(
+					$field_obj,
+					$this->getModelVersionInfo()->fieldsThatHaveRenderedFormat()
+				)
+			) {
+				$result[ $field_name ] = [
+					'raw'      => $this->prepareFieldObjValueForJson($field_obj, $field_value),
+					'rendered' => $this->prepareFieldObjValueForJson($field_obj, $field_value, 'pretty'),
+				];
+			} elseif (
+				$this->isSubclassOfOne(
+					$field_obj,
+					$this->getModelVersionInfo()->fieldsThatHavePrettyFormat()
+				)
+			) {
+				$result[ $field_name ] = [
+					'raw'    => $this->prepareFieldObjValueForJson($field_obj, $field_value),
+					'pretty' => $this->prepareFieldObjValueForJson($field_obj, $field_value, 'pretty'),
+				];
+			} elseif ($field_obj instanceof EE_Datetime_Field) {
+				$field_value = $field_obj->prepare_for_set_from_db($field_value);
+				// if the value is null, but we're not supposed to permit null, then set to the field's default
+				if (is_null($field_value)) {
+					$field_value = $field_obj->getDefaultDateTimeObj();
+				}
+				if (is_null($field_value)) {
+					$gmt_date = $local_date = ModelDataTranslator::prepareFieldValuesForJson(
+						$field_obj,
+						$field_value,
+						$this->getModelVersionInfo()->requestedVersion()
+					);
+				} else {
+					$timezone = $field_value->getTimezone();
+					EEH_DTT_Helper::setTimezone($field_value, new DateTimeZone('UTC'));
+					$gmt_date = ModelDataTranslator::prepareFieldValuesForJson(
+						$field_obj,
+						$field_value,
+						$this->getModelVersionInfo()->requestedVersion()
+					);
+					EEH_DTT_Helper::setTimezone($field_value, $timezone);
+					$local_date = ModelDataTranslator::prepareFieldValuesForJson(
+						$field_obj,
+						$field_value,
+						$this->getModelVersionInfo()->requestedVersion()
+					);
+				}
+				$result[ $field_name . '_gmt' ] = $gmt_date;
+				$result[ $field_name ]          = $local_date;
+			} else {
+				$result[ $field_name ] = $this->prepareFieldObjValueForJson($field_obj, $field_value);
+			}
+		}
+		if ($do_chevy_shuffle) {
+			$post = $old_post;
+		}
+		return $result;
+	}
+
+
+	/**
+	 * Takes a value all the way from the DB representation, to the model object's representation, to the
+	 * user-facing PHP representation, to the REST API representation. (Assumes you've already taken from the DB
+	 * representation using $field_obj->prepare_for_set_from_db())
+	 *
+	 * @param EE_Model_Field_Base $field_obj
+	 * @param mixed               $value  as it's stored on a model object
+	 * @param string              $format valid values are 'normal' (default), 'pretty', 'datetime_obj'
+	 * @return array|int
+	 * @throws RestException if $value contains a PHP object
+	 * @throws EE_Error
+	 */
+	protected function prepareFieldObjValueForJson(
+		EE_Model_Field_Base $field_obj,
+		$value,
+		string $format = 'normal'
+	) {
+		$value = $field_obj->prepare_for_set_from_db($value);
+		switch ($format) {
+			case 'pretty':
+				$value = $field_obj->prepare_for_pretty_echoing($value);
+				break;
+			case 'normal':
+			default:
+				$value = $field_obj->prepare_for_get($value);
+				break;
+		}
+		return ModelDataTranslator::prepareFieldValuesForJson(
+			$field_obj,
+			$value,
+			$this->getModelVersionInfo()->requestedVersion()
+		);
+	}
+
+
+	/**
+	 * Adds a few extra fields to the entity response
+	 *
+	 * @param EEM_Base $model
+	 * @param array    $db_row
+	 * @param array    $entity_array
+	 * @return array modified entity
+	 * @throws EE_Error
+	 */
+	protected function addExtraFields(EEM_Base $model, array $db_row, array $entity_array): array
+	{
+		if ($model instanceof EEM_CPT_Base) {
+			$entity_array['link'] = get_permalink($db_row[ $model->get_primary_key_field()->get_qualified_column() ]);
+		}
+		return $entity_array;
+	}
+
+
+	/**
+	 * Gets links we want to add to the response
+	 *
+	 * @param EEM_Base        $model
+	 * @param array           $db_row
+	 * @param array           $entity_array
+	 * @return array the _links item in the entity
+	 * @throws EE_Error
+	 * @global WP_REST_Server $wp_rest_server
+	 */
+	protected function getEntityLinks(EEM_Base $model, array $db_row, array $entity_array): array
+	{
+		// add basic links
+		$links = [];
+		if ($model->has_primary_key_field()) {
+			$links['self'] = [
+				[
+					'href' => $this->getVersionedLinkTo(
+						EEH_Inflector::pluralize_and_lower($model->get_this_model_name())
+						. '/'
+						. $entity_array[ $model->primary_key_name() ]
+					),
+				],
+			];
+		}
+		$links['collection'] = [
+			[
+				'href' => $this->getVersionedLinkTo(
+					EEH_Inflector::pluralize_and_lower($model->get_this_model_name())
+				),
+			],
+		];
+		// add links to related models
+		if ($model->has_primary_key_field()) {
+			foreach ($this->getModelVersionInfo()->relationSettings($model) as $relation_name => $relation_obj) {
+				$related_model_part                                                      =
+					Read::getRelatedEntityName($relation_name, $relation_obj);
+				$links[ EED_Core_Rest_Api::ee_api_link_namespace . $related_model_part ] = [
+					[
+						'href'   => $this->getVersionedLinkTo(
+							EEH_Inflector::pluralize_and_lower($model->get_this_model_name())
+							. '/'
+							. $entity_array[ $model->primary_key_name() ]
+							. '/'
+							. $related_model_part
+						),
+						'single' => $relation_obj instanceof EE_Belongs_To_Relation,
+					],
+				];
+			}
+		}
+		return $links;
+	}
+
+
+	/**
+	 * Adds the included models indicated in the request to the entity provided
+	 *
+	 * @param EEM_Base        $model
+	 * @param WP_REST_Request $rest_request
+	 * @param array           $entity_array
+	 * @param array           $db_row
+	 * @param boolean         $included_items_protected if the original item is password protected, don't include any
+	 *                                                  related models.
+	 * @return array the modified entity
+	 * @throws DomainException
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ModelConfigurationException
+	 * @throws ReflectionException
+	 * @throws UnexpectedEntityException
+	 */
+	protected function includeRequestedModels(
+		EEM_Base $model,
+		WP_REST_Request $rest_request,
+		array $entity_array,
+		array $db_row = [],
+		bool $included_items_protected = false
+	): array {
+		// if $db_row not included, hope the entity array has what we need
+		if (! $db_row) {
+			$db_row = $entity_array;
+		}
+		$relation_settings = $this->getModelVersionInfo()->relationSettings($model);
+		foreach ($relation_settings as $relation_name => $relation_obj) {
+			$related_fields_to_include   = $this->explodeAndGetItemsPrefixedWith(
+				$rest_request->get_param('include'),
+				$relation_name
+			);
+			$related_fields_to_calculate = $this->explodeAndGetItemsPrefixedWith(
+				$rest_request->get_param('calculate'),
+				$relation_name
+			);
+			// did they specify they wanted to include a related model, or
+			// specific fields from a related model?
+			// or did they specify to calculate a field from a related model?
+			if ($related_fields_to_include || $related_fields_to_calculate) {
+				// if so, we should include at least some part of the related model
+				$pretend_related_request = new WP_REST_Request();
+				$pretend_related_request->set_query_params(
+					[
+						'caps'      => $rest_request->get_param('caps'),
+						'include'   => $related_fields_to_include,
+						'calculate' => $related_fields_to_calculate,
+						'password'  => $rest_request->get_param('password'),
+					]
+				);
+				$pretend_related_request->add_header('no_rest_headers', true);
+				$primary_model_query_params = $model->alter_query_params_to_restrict_by_ID(
+					$model->get_index_primary_key_string(
+						$model->deduce_fields_n_values_from_cols_n_values($db_row)
+					)
+				);
+				if (! $included_items_protected) {
+					try {
+						$related_results = $this->getEntitiesFromRelationUsingModelQueryParams(
+							$primary_model_query_params,
+							$relation_obj,
+							$pretend_related_request
+						);
+					} catch (RestException $e) {
+						$related_results = null;
+					}
+				} else {
+					// they're protected, hide them.
+					$related_results              = null;
+					$entity_array['_protected'][] = Read::getRelatedEntityName($relation_name, $relation_obj);
+				}
+				if ($related_results instanceof WP_Error || $related_results === null) {
+					$related_results = $relation_obj instanceof EE_Belongs_To_Relation
+							? null
+							: [];
+				}
+				$entity_array[ Read::getRelatedEntityName($relation_name, $relation_obj) ] = $related_results;
+			}
+		}
+		return $entity_array;
+	}
+
+
+	/**
+	 * If the user has requested only specific properties (including meta properties like _links or _protected)
+	 * remove everything else.
+	 *
+	 * @param EEM_Base        $model
+	 * @param WP_REST_Request $rest_request
+	 * @param                 $entity_array
+	 * @return array
+	 * @throws EE_Error
+	 * @since 4.9.74.p
+	 */
+	protected function includeOnlyRequestedProperties(
+		EEM_Base $model,
+		WP_REST_Request $rest_request,
+		$entity_array
+	): array {
+
+		$includes_for_this_model = $this->explodeAndGetItemsPrefixedWith($rest_request->get_param('include'), '');
+		$includes_for_this_model = $this->removeModelNamesFromArray($includes_for_this_model);
+		// if they passed in * or didn't specify any includes, return everything
+		if (! empty($includes_for_this_model) && ! in_array('*', $includes_for_this_model, true)) {
+			if ($model->has_primary_key_field()) {
+				// always include the primary key. ya just gotta know that at least
+				$includes_for_this_model[] = $model->primary_key_name();
+			}
+			if ($this->explodeAndGetItemsPrefixedWith($rest_request->get_param('calculate'), '')) {
+				$includes_for_this_model[] = '_calculated_fields';
+			}
+			$entity_array = array_intersect_key($entity_array, array_flip($includes_for_this_model));
+		}
+		return $entity_array;
+	}
+
+
+	/**
+	 * Returns a new array with all the names of models removed. Eg
+	 * array( 'Event', 'Datetime.*', 'foobar' ) would become array( 'Datetime.*', 'foobar' )
+	 *
+	 * @param array $array
+	 * @return array
+	 */
+	private function removeModelNamesFromArray(array $array): array
+	{
+		return array_diff($array, array_keys(EE_Registry::instance()->non_abstract_db_models));
+	}
+
+
+	/**
+	 * Gets the calculated fields for the response
+	 *
+	 * @param EEM_Base        $model
+	 * @param array           $wpdb_row
+	 * @param WP_REST_Request $rest_request
+	 * @param bool            $row_is_protected whether this row is password protected or not
+	 * @return stdClass the _calculations item in the entity
+	 * @throws RestException if a default value has a PHP object, which should never do (and if we
+	 *                                          did, let's know about it ASAP, so let the exception bubble up)
+	 * @throws EE_Error
+	 */
+	protected function getEntityCalculations(
+		EEM_Base $model,
+		array $wpdb_row,
+		WP_REST_Request $rest_request,
+		bool $row_is_protected = false
+	): stdClass {
+		$calculated_fields = $this->explodeAndGetItemsPrefixedWith(
+			$rest_request->get_param('calculate'),
+			''
+		);
+		// note: setting calculate=* doesn't do anything
+		$calculated_fields_to_return = new stdClass();
+		$protected_fields            = [];
+		foreach ($calculated_fields as $field_to_calculate) {
+			try {
+				// it's password protected, so they shouldn't be able to read this. Remove the value
+				$schema = $this->fields_calculator->getJsonSchemaForModel($model);
+				if (
+					$row_is_protected
+					&& isset($schema['properties'][ $field_to_calculate ]['protected'])
+					&& $schema['properties'][ $field_to_calculate ]['protected']
+				) {
+					$calculated_value   = null;
+					$protected_fields[] = $field_to_calculate;
+					if ($schema['properties'][ $field_to_calculate ]['type']) {
+						switch ($schema['properties'][ $field_to_calculate ]['type']) {
+							case 'boolean':
+								$calculated_value = false;
+								break;
+							case 'integer':
+								$calculated_value = 0;
+								break;
+							case 'string':
+								$calculated_value = '';
+								break;
+							case 'array':
+								$calculated_value = [];
+								break;
+							case 'object':
+								$calculated_value = new stdClass();
+								break;
+						}
+					}
+				} else {
+					$calculated_value = ModelDataTranslator::prepareFieldValueForJson(
+						null,
+						$this->fields_calculator->retrieveCalculatedFieldValue(
+							$model,
+							$field_to_calculate,
+							$wpdb_row,
+							$rest_request,
+							$this
+						),
+						$this->getModelVersionInfo()->requestedVersion()
+					);
+				}
+				$calculated_fields_to_return->{$field_to_calculate} = $calculated_value;
+			} catch (RestException $e) {
+				// if we don't have permission to read it, just leave it out. but let devs know about the problem
+				$this->setResponseHeader(
+					'Notices-Field-Calculation-Errors['
+					. $e->getStringCode()
+					. ']['
+					. $model->get_this_model_name()
+					. ']['
+					. $field_to_calculate
+					. ']',
+					$e->getMessage()
+				);
+			}
+		}
+		$calculated_fields_to_return->_protected = $protected_fields;
+		return $calculated_fields_to_return;
+	}
+
+
+	/**
+	 * Gets the full URL to the resource, taking the requested version into account
+	 *
+	 * @param string $link_part_after_version_and_slash eg "events/10/datetimes"
+	 * @return string url eg "http://mysite.com/wp-json/ee/v4.6/events/10/datetimes"
+	 * @throws EE_Error
+	 */
+	public function getVersionedLinkTo(string $link_part_after_version_and_slash): string
+	{
+		return rest_url(
+			EED_Core_Rest_Api::get_versioned_route_to(
+				$link_part_after_version_and_slash,
+				$this->getModelVersionInfo()->requestedVersion()
+			)
+		);
+	}
+
+
+	/**
+	 * Gets the correct lowercase name for the relation in the API according
+	 * to the relation's type
+	 *
+	 * @param string                 $relation_name
+	 * @param EE_Model_Relation_Base $relation_obj
+	 * @return string
+	 */
+	public static function getRelatedEntityName(string $relation_name, EE_Model_Relation_Base $relation_obj): string
+	{
+		if ($relation_obj instanceof EE_Belongs_To_Relation) {
+			return strtolower($relation_name);
+		}
+		return EEH_Inflector::pluralize_and_lower($relation_name);
+	}
+
+
+	/**
+	 * Gets the one model object with the specified id for the specified model
+	 *
+	 * @param EEM_Base        $model
+	 * @param WP_REST_Request $request
+	 * @return array
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ModelConfigurationException
+	 * @throws ReflectionException
+	 * @throws RestException
+	 * @throws RestPasswordIncorrectException
+	 * @throws RestPasswordRequiredException
+	 * @throws UnexpectedEntityException
+	 * @throws DomainException
+	 */
+	public function getEntityFromModel(EEM_Base $model, WP_REST_Request $request): array
+	{
+		$context = $this->validateContext($request->get_param('caps'));
+		return $this->getOneOrReportPermissionError($model, $request, $context);
+	}
+
+
+	/**
+	 * If a context is provided which isn't valid, maybe it was added in a future
+	 * version so just treat it as a default read
+	 *
+	 * @param string|null $context
+	 * @return string array key of EEM_Base::cap_contexts_to_cap_action_map()
+	 */
+	public function validateContext(?string $context): string
+	{
+		if (! $context) {
+			$context = EEM_Base::caps_read;
+		}
+		$valid_contexts = EEM_Base::valid_cap_contexts();
+		if (in_array($context, $valid_contexts, true)) {
+			return $context;
+		}
+		return EEM_Base::caps_read;
+	}
+
+
+	/**
+	 * Verifies the passed in value is an allowable default where conditions value.
+	 *
+	 * @param string $default_where_conditions
+	 * @return string
+	 */
+	public function validateDefaultQueryParams(string $default_where_conditions): string
+	{
+		$valid_default_where_conditions_for_api_calls = [
+			EEM_Base::default_where_conditions_all,
+			EEM_Base::default_where_conditions_minimum_all,
+			EEM_Base::default_where_conditions_minimum_others,
+		];
+		if (! $default_where_conditions) {
+			$default_where_conditions = EEM_Base::default_where_conditions_all;
+		}
+		if (
+			in_array(
+				$default_where_conditions,
+				$valid_default_where_conditions_for_api_calls,
+				true
+			)
+		) {
+			return $default_where_conditions;
+		}
+		return EEM_Base::default_where_conditions_all;
+	}
+
+
+	/**
+	 * Translates API filter get parameter into model query params @param EEM_Base $model
+	 *
+	 * @param array $query_params
+	 * @return array model query params (@see
+	 *               https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions)
+	 *               or FALSE to indicate that absolutely no results should be returned
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws RestException
+	 * @throws DomainException
+	 * @throws ReflectionException
+	 * @see
+	 *               https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions.
+	 *               Note: right now the query parameter keys for fields (and related fields) can be left as-is, but
+	 *               it's quite possible this will change someday. Also, this method's contents might be candidate for
+	 *               moving to Model_Data_Translator
+	 *
+	 */
+	public function createModelQueryParams(EEM_Base $model, array $query_params): array
+	{
+		$model_query_params = [];
+		if (isset($query_params['where'])) {
+			$model_query_params[0] = ModelDataTranslator::prepareConditionsQueryParamsForModels(
+				$query_params['where'],
+				$model,
+				$this->getModelVersionInfo()->requestedVersion()
+			);
+		}
+		if (isset($query_params['order_by'])) {
+			$order_by = $query_params['order_by'];
+		} elseif (isset($query_params['orderby'])) {
+			$order_by = $query_params['orderby'];
+		} else {
+			$order_by = null;
+		}
+		if ($order_by !== null) {
+			if (is_array($order_by)) {
+				$order_by = ModelDataTranslator::prepareFieldNamesInArrayKeysFromJson($order_by);
+			} else {
+				// it's a single item
+				$order_by = ModelDataTranslator::prepareFieldNameFromJson($order_by);
+			}
+			$model_query_params['order_by'] = $order_by;
+		}
+		if (isset($query_params['group_by'])) {
+			$group_by = $query_params['group_by'];
+		} elseif (isset($query_params['groupby'])) {
+			$group_by = $query_params['groupby'];
+		} else {
+			$group_by = array_keys($model->get_combined_primary_key_fields());
+		}
+		// make sure they're all real names
+		if (is_array($group_by)) {
+			$group_by = ModelDataTranslator::prepareFieldNamesFromJson($group_by);
+		}
+		if ($group_by !== null) {
+			$model_query_params['group_by'] = $group_by;
+		}
+		if (isset($query_params['having'])) {
+			$model_query_params['having'] = ModelDataTranslator::prepareConditionsQueryParamsForModels(
+				$query_params['having'],
+				$model,
+				$this->getModelVersionInfo()->requestedVersion()
+			);
+		}
+		if (isset($query_params['order'])) {
+			$model_query_params['order'] = $query_params['order'];
+		}
+		if (isset($query_params['mine'])) {
+			$model_query_params = $model->alter_query_params_to_only_include_mine($model_query_params);
+		}
+		if (isset($query_params['limit'])) {
+			// limit should be either a string like '23' or '23,43', or an array with two items in it
+			if (! is_array($query_params['limit'])) {
+				$limit_array = explode(',', (string) $query_params['limit']);
+			} else {
+				$limit_array = $query_params['limit'];
+			}
+			$sanitized_limit = [];
+			foreach ($limit_array as $limit_part) {
+				if ($this->debug_mode && (! is_numeric($limit_part) || count($sanitized_limit) > 2)) {
+					throw new EE_Error(
+						sprintf(
+							esc_html__(
+							// @codingStandardsIgnoreStart
+								'An invalid limit filter was provided. It was: %s. If the EE4 JSON REST API weren\'t in debug mode, this message would not appear.',
+								// @codingStandardsIgnoreEnd
+								'event_espresso'
+							),
+							wp_json_encode($query_params['limit'])
+						)
+					);
+				}
+				$sanitized_limit[] = (int) $limit_part;
+			}
+			$model_query_params['limit'] = implode(',', $sanitized_limit);
+		} else {
+			$model_query_params['limit'] = EED_Core_Rest_Api::get_default_query_limit();
+		}
+		if (isset($query_params['caps'])) {
+			$model_query_params['caps'] = $this->validateContext($query_params['caps']);
+		} else {
+			$model_query_params['caps'] = EEM_Base::caps_read;
+		}
+		if (isset($query_params['default_where_conditions'])) {
+			$model_query_params['default_where_conditions'] = $this->validateDefaultQueryParams(
+				$query_params['default_where_conditions']
+			);
+		}
+		// if this is a model protected by a password on another model, exclude the password protected
+		// entities by default. But if they passed in a password, try to show them all. If the password is wrong,
+		// though, they'll get an error (see Read::createEntityFromWpdbResult() which calls Read::checkPassword)
+		if (
+			$model_query_params['caps'] === EEM_Base::caps_read
+			&& empty($query_params['password'])
+			&& ! $model->hasPassword()
+			&& $model->restrictedByRelatedModelPassword()
+		) {
+			$model_query_params['exclude_protected'] = true;
+		}
+
+		return apply_filters('FHEE__Read__create_model_query_params', $model_query_params, $query_params, $model);
+	}
+
+
+	/**
+	 * Changes the REST-style query params for use in the models
+	 *
+	 * @param EEM_Base $model
+	 * @param array    $query_params sub-array from @see EEM_Base::get_all()
+	 * @return array
+	 * @deprecated
+	 */
+	public function prepareRestQueryParamsKeyForModels(EEM_Base $model, array $query_params): array
+	{
+		$model_ready_query_params = [];
+		foreach ($query_params as $key => $value) {
+			$model_ready_query_params[ $key ] = is_array($value)
+				? $this->prepareRestQueryParamsKeyForModels($model, $value)
+				: $value;
+		}
+		return $model_ready_query_params;
+	}
+
+
+	/**
+	 * @param $model
+	 * @param $query_params
+	 * @return array
+	 * @deprecated instead use ModelDataTranslator::prepareFieldValuesFromJson()
+	 */
+	public function prepareRestQueryParamsValuesForModels($model, $query_params): array
+	{
+		$model_ready_query_params = [];
+		foreach ($query_params as $key => $value) {
+			if (is_array($value)) {
+				$model_ready_query_params[ $key ] = $this->prepareRestQueryParamsValuesForModels($model, $value);
+			} else {
+				$model_ready_query_params[ $key ] = $value;
+			}
+		}
+		return $model_ready_query_params;
+	}
+
+
+	/**
+	 * Explodes the string on commas, and only returns items with $prefix followed by a period.
+	 * If no prefix is specified, returns items with no period.
+	 *
+	 * @param string|array $string_to_explode eg "jibba,jabba, blah, blah, blah" or array('jibba', 'jabba' )
+	 * @param string       $prefix            "Event" or "foobar"
+	 * @return array $string_to_exploded exploded on COMMAS, and if a prefix was specified
+	 *                                        we only return strings starting with that and a period; if no prefix was
+	 *                                        specified we return all items containing NO periods
+	 */
+	public function explodeAndGetItemsPrefixedWith($string_to_explode, string $prefix): array
+	{
+		if (is_string($string_to_explode)) {
+			$exploded_contents = explode(',', $string_to_explode);
+		} elseif (is_array($string_to_explode)) {
+			$exploded_contents = $string_to_explode;
+		} else {
+			$exploded_contents = [];
+		}
+		// if the string was empty, we want an empty array
+		$exploded_contents    = array_filter($exploded_contents);
+		$contents_with_prefix = [];
+		foreach ($exploded_contents as $item) {
+			$item = trim($item);
+			// if no prefix was provided, so we look for items with no "." in them
+			if (! $prefix) {
+				// does this item have a period?
+				if (strpos($item, '.') === false) {
+					// if not, then its what we're looking for
+					$contents_with_prefix[] = $item;
+				}
+			} elseif (strpos($item, $prefix . '.') === 0) {
+				// this item has the prefix and a period, grab it
+				$contents_with_prefix[] = substr(
+					$item,
+					strpos($item, $prefix . '.') + strlen($prefix . '.')
+				);
+			} elseif ($item === $prefix) {
+				// this item is JUST the prefix
+				// so let's grab everything after, which is a blank string
+				$contents_with_prefix[] = '';
+			}
+		}
+		return $contents_with_prefix;
+	}
+
+
+	/**
+	 * @param string      $include_string @see Read:handle_request_get_all
+	 * @param string|null $model_name
+	 * @return array of fields for this model. If $model_name is provided, then
+	 *                                    the fields for that model, with the model's name removed from each.
+	 *                                    If $include_string was blank or '*' returns an empty array
+	 * @throws EE_Error
+	 * @throws EE_Error
+	 * @deprecated since 4.8.36.rc.001 You should instead use Read::explode_and_get_items_prefixed_with.
+	 *                                    Deprecated because its return values were really quite confusing- sometimes
+	 *                                    it
+	 *                                    returned an empty array (when the include string was blank or '*') or
+	 *                                    sometimes it returned array('*') (when you provided a model and a model of
+	 *                                    that kind was found). Parses the $include_string so we fetch all the field
+	 *                                    names relating to THIS model
+	 *                                    (ie have NO period in them), or for the provided model (ie start with the
+	 *                                    model name and then a period).
+	 */
+	public function extractIncludesForThisModel(string $include_string, string $model_name = null): array
+	{
+		if (is_array($include_string)) {
+			$include_string = implode(',', $include_string);
+		}
+		if ($include_string === '*' || $include_string === '') {
+			return [];
+		}
+		$includes                    = explode(',', $include_string);
+		$extracted_fields_to_include = [];
+		if ($model_name) {
+			foreach ($includes as $field_to_include) {
+				$field_to_include = trim($field_to_include);
+				if (strpos($field_to_include, $model_name . '.') === 0) {
+					// found the model name at the exact start
+					$field_sans_model_name         = str_replace($model_name . '.', '', $field_to_include);
+					$extracted_fields_to_include[] = $field_sans_model_name;
+				} elseif ($field_to_include === $model_name) {
+					$extracted_fields_to_include[] = '*';
+				}
+			}
+		} else {
+			// look for ones with no period
+			foreach ($includes as $field_to_include) {
+				$field_to_include = trim($field_to_include);
+				if (
+					strpos($field_to_include, '.') === false
+					&& ! $this->getModelVersionInfo()->isModelNameInThisVersion($field_to_include)
+				) {
+					$extracted_fields_to_include[] = $field_to_include;
+				}
+			}
+		}
+		return $extracted_fields_to_include;
+	}
+
+
+	/**
+	 * Gets the single item using the model according to the request in the context given, otherwise
+	 * returns that it's inaccessible to the current user
+	 *
+	 * @param EEM_Base        $model
+	 * @param WP_REST_Request $request
+	 * @param null            $context
+	 * @return array
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function getOneOrReportPermissionError(EEM_Base $model, WP_REST_Request $request, $context = null): array
+	{
+		$query_params = [[$model->primary_key_name() => $request->get_param('id')], 'limit' => 1];
+		if ($model instanceof EEM_Soft_Delete_Base) {
+			$query_params = $model->alter_query_params_so_deleted_and_undeleted_items_included($query_params);
+		}
+		$restricted_query_params         = $query_params;
+		$restricted_query_params['caps'] = $context;
+		$this->setDebugInfo('model query params', $restricted_query_params);
+		$model_rows = $model->get_all_wpdb_results($restricted_query_params);
+		if (! empty($model_rows)) {
+			return $this->createEntityFromWpdbResult(
+				$model,
+				reset($model_rows),
+				$request
+			);
+		}
+		// ok let's test to see if we WOULD have found it, had we not had restrictions from missing capabilities
+		$lowercase_model_name = strtolower($model->get_this_model_name());
+		if ($model->exists($query_params)) {
+			// you got shafted- it existed but we didn't want to tell you!
+			throw new RestException(
+				'rest_user_cannot_' . $context,
+				sprintf(
+					__('Sorry, you cannot %1$s this %2$s. Missing permissions are: %3$s', 'event_espresso'),
+					$context,
+					$lowercase_model_name,
+					Capabilities::getMissingPermissionsString(
+						$model,
+						$context
+					)
+				),
+				['status' => 403]
+			);
+		}
+		// it's not you. It just doesn't exist
+		throw new RestException(
+			sprintf('rest_%s_invalid_id', $lowercase_model_name),
+			sprintf(__('Invalid %s ID.', 'event_espresso'), $lowercase_model_name),
+			['status' => 404]
+		);
+	}
+
+
+	/**
+	 * Checks that if this content requires a password to be read, that it's been provided and is correct.
+	 *
+	 * @param EEM_Base        $model
+	 * @param array           $model_row
+	 * @param array           $query_params Adds 'default_where_conditions' => 'minimum'
+	 *                                      to ensure we don't confuse trashed with password protected.
+	 * @param WP_REST_Request $request
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws RestPasswordRequiredException
+	 * @throws RestPasswordIncorrectException
+	 * @throws ModelConfigurationException
+	 * @throws ReflectionException
+	 * @since 4.9.74.p
+	 */
+	protected function checkPassword(EEM_Base $model, array $model_row, array $query_params, WP_REST_Request $request)
+	{
+		$query_params['default_where_conditions'] = 'minimum';
+		// stuff is only "protected" for front-end requests. Elsewhere, you either get full permission to access the object
+		// or you don't.
+		$request_caps = $request->get_param('caps');
+		if (isset($request_caps) && $request_caps !== EEM_Base::caps_read) {
+			return;
+		}
+		// if this entity requires a password, they better give it and it better be right!
+		if (
+			$model->hasPassword()
+			&& $model_row[ $model->getPasswordField()->get_qualified_column() ] !== ''
+		) {
+			if (empty($request['password'])) {
+				throw new RestPasswordRequiredException();
+			}
+			if (
+				! hash_equals(
+					$model_row[ $model->getPasswordField()->get_qualified_column() ],
+					$request['password']
+				)
+			) {
+				throw new RestPasswordIncorrectException();
+			}
+		} elseif (
+			// wait! maybe this content is password protected
+			$model->restrictedByRelatedModelPassword()
+			&& $request->get_param('caps') === EEM_Base::caps_read
+		) {
+			$password_supplied = $request->get_param('password');
+			if (empty($password_supplied)) {
+				$query_params['exclude_protected'] = true;
+				if (! $model->exists($query_params)) {
+					throw new RestPasswordRequiredException();
+				}
+			} else {
+				$query_params[0][ $model->modelChainAndPassword() ] = $password_supplied;
+				if (! $model->exists($query_params)) {
+					throw new RestPasswordIncorrectException();
+				}
+			}
+		}
+	}
 }

core/libraries/rest_api/controllers/model/Base.php

Indentation +80 added lines, -80 removed lines

@@ -18,95 +18,95 @@
  */
 class Base extends Controller_Base
 {
-    /**
-     * Holds reference to the model version info, which knows the requested version
-     *
-     * @var ModelVersionInfo
-     */
-    protected $model_version_info;
+	/**
+	 * Holds reference to the model version info, which knows the requested version
+	 *
+	 * @var ModelVersionInfo
+	 */
+	protected $model_version_info;
 
 
 
-    /**
-     * Sets the version the user requested
-     *
-     * @param string $version eg '4.8'
-     */
-    public function setRequestedVersion(string $version)
-    {
-        parent::setRequestedVersion($version);
-        $this->model_version_info = new ModelVersionInfo($version);
-    }
+	/**
+	 * Sets the version the user requested
+	 *
+	 * @param string $version eg '4.8'
+	 */
+	public function setRequestedVersion(string $version)
+	{
+		parent::setRequestedVersion($version);
+		$this->model_version_info = new ModelVersionInfo($version);
+	}
 
 
 
-    /**
-     * Gets the object that should be used for getting any info from the models,
-     * because it's takes the requested and current core version into account
-     *
-     * @return ModelVersionInfo
-     * @throws EE_Error
-     */
-    public function getModelVersionInfo()
-    {
-        if (! $this->model_version_info) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'Cannot use model version info before setting the requested version in the controller',
-                        'event_espresso'
-                    )
-                )
-            );
-        }
-        return $this->model_version_info;
-    }
+	/**
+	 * Gets the object that should be used for getting any info from the models,
+	 * because it's takes the requested and current core version into account
+	 *
+	 * @return ModelVersionInfo
+	 * @throws EE_Error
+	 */
+	public function getModelVersionInfo()
+	{
+		if (! $this->model_version_info) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'Cannot use model version info before setting the requested version in the controller',
+						'event_espresso'
+					)
+				)
+			);
+		}
+		return $this->model_version_info;
+	}
 
 
 
-    /**
-     * Determines if $object is of one of the classes of $classes. Similar to
-     * in_array(), except this checks if $object is a subclass of the classnames provided
-     * in $classnames
-     *
-     * @param object $object
-     * @param array  $classnames
-     * @return boolean
-     */
-    public function isSubclassOfOne($object, $classnames)
-    {
-        foreach ($classnames as $classname) {
-            if (is_a($object, $classname)) {
-                return true;
-            }
-        }
-        return false;
-    }
+	/**
+	 * Determines if $object is of one of the classes of $classes. Similar to
+	 * in_array(), except this checks if $object is a subclass of the classnames provided
+	 * in $classnames
+	 *
+	 * @param object $object
+	 * @param array  $classnames
+	 * @return boolean
+	 */
+	public function isSubclassOfOne($object, $classnames)
+	{
+		foreach ($classnames as $classname) {
+			if (is_a($object, $classname)) {
+				return true;
+			}
+		}
+		return false;
+	}
 
-    /**
-     * Verifies the model name provided was valid. If so, returns the model (as an object). Otherwise, throws an
-     * exception. Must be called after `setRequestedVersion()`.
-     * @since 4.9.76.p
-     * @param $model_name
-     * @return EEM_Base
-     * @throws EE_Error
-     * @throws RestException
-     */
-    protected function validateModel($model_name)
-    {
-        if (! $this->getModelVersionInfo()->isModelNameInThisVersion($model_name)) {
-            throw new RestException(
-                'endpoint_parsing_error',
-                sprintf(
-                    esc_html__(
-                        'There is no model for endpoint %s. Please contact event espresso support',
-                        'event_espresso'
-                    ),
-                    $model_name
-                )
-            );
-        }
-        return $this->getModelVersionInfo()->loadModel($model_name);
-    }
+	/**
+	 * Verifies the model name provided was valid. If so, returns the model (as an object). Otherwise, throws an
+	 * exception. Must be called after `setRequestedVersion()`.
+	 * @since 4.9.76.p
+	 * @param $model_name
+	 * @return EEM_Base
+	 * @throws EE_Error
+	 * @throws RestException
+	 */
+	protected function validateModel($model_name)
+	{
+		if (! $this->getModelVersionInfo()->isModelNameInThisVersion($model_name)) {
+			throw new RestException(
+				'endpoint_parsing_error',
+				sprintf(
+					esc_html__(
+						'There is no model for endpoint %s. Please contact event espresso support',
+						'event_espresso'
+					),
+					$model_name
+				)
+			);
+		}
+		return $this->getModelVersionInfo()->loadModel($model_name);
+	}
 }
 // End of file Base.php

core/libraries/rest_api/controllers/model/Write.php

Indentation +606 added lines, -606 removed lines

@@ -36,636 +36,636 @@
  */
 class Write extends Base
 {
-    /**
-     * Handles requests to get all (or a filtered subset) of entities for a particular model
-     *
-     * @param WP_REST_Request $request
-     * @param string          $version
-     * @param string          $model_name
-     * @return WP_REST_Response
-     */
-    public static function handleRequestInsert(
-        WP_REST_Request $request,
-        string $version,
-        string $model_name
-    ): WP_REST_Response {
-        $controller = new Write();
-        try {
-            $controller->setRequestedVersion($version);
-            return $controller->sendResponse(
-                $controller->insert(
-                    $controller->getModelVersionInfo()->loadModel($model_name),
-                    $request
-                )
-            );
-        } catch (Exception $e) {
-            return $controller->sendResponse($e);
-        }
-    }
+	/**
+	 * Handles requests to get all (or a filtered subset) of entities for a particular model
+	 *
+	 * @param WP_REST_Request $request
+	 * @param string          $version
+	 * @param string          $model_name
+	 * @return WP_REST_Response
+	 */
+	public static function handleRequestInsert(
+		WP_REST_Request $request,
+		string $version,
+		string $model_name
+	): WP_REST_Response {
+		$controller = new Write();
+		try {
+			$controller->setRequestedVersion($version);
+			return $controller->sendResponse(
+				$controller->insert(
+					$controller->getModelVersionInfo()->loadModel($model_name),
+					$request
+				)
+			);
+		} catch (Exception $e) {
+			return $controller->sendResponse($e);
+		}
+	}
 
 
-    /**
-     * Handles a request from \WP_REST_Server to update an EE model
-     *
-     * @param WP_REST_Request $request
-     * @param string          $version
-     * @param string          $model_name
-     * @return WP_REST_Response
-     */
-    public static function handleRequestUpdate(
-        WP_REST_Request $request,
-        string $version,
-        string $model_name
-    ): WP_REST_Response {
-        $controller = new Write();
-        try {
-            $controller->setRequestedVersion($version);
-            return $controller->sendResponse(
-                $controller->update(
-                    $controller->getModelVersionInfo()->loadModel($model_name),
-                    $request
-                )
-            );
-        } catch (Exception $e) {
-            return $controller->sendResponse($e);
-        }
-    }
+	/**
+	 * Handles a request from \WP_REST_Server to update an EE model
+	 *
+	 * @param WP_REST_Request $request
+	 * @param string          $version
+	 * @param string          $model_name
+	 * @return WP_REST_Response
+	 */
+	public static function handleRequestUpdate(
+		WP_REST_Request $request,
+		string $version,
+		string $model_name
+	): WP_REST_Response {
+		$controller = new Write();
+		try {
+			$controller->setRequestedVersion($version);
+			return $controller->sendResponse(
+				$controller->update(
+					$controller->getModelVersionInfo()->loadModel($model_name),
+					$request
+				)
+			);
+		} catch (Exception $e) {
+			return $controller->sendResponse($e);
+		}
+	}
 
 
-    /**
-     * Deletes a single model object and returns it. Unless
-     *
-     * @param WP_REST_Request $request
-     * @param string          $version
-     * @param string          $model_name
-     * @return WP_REST_Response
-     */
-    public static function handleRequestDelete(
-        WP_REST_Request $request,
-        string $version,
-        string $model_name
-    ): WP_REST_Response {
-        $controller = new Write();
-        try {
-            $controller->setRequestedVersion($version);
-            return $controller->sendResponse(
-                $controller->delete(
-                    $controller->getModelVersionInfo()->loadModel($model_name),
-                    $request
-                )
-            );
-        } catch (Exception $e) {
-            return $controller->sendResponse($e);
-        }
-    }
+	/**
+	 * Deletes a single model object and returns it. Unless
+	 *
+	 * @param WP_REST_Request $request
+	 * @param string          $version
+	 * @param string          $model_name
+	 * @return WP_REST_Response
+	 */
+	public static function handleRequestDelete(
+		WP_REST_Request $request,
+		string $version,
+		string $model_name
+	): WP_REST_Response {
+		$controller = new Write();
+		try {
+			$controller->setRequestedVersion($version);
+			return $controller->sendResponse(
+				$controller->delete(
+					$controller->getModelVersionInfo()->loadModel($model_name),
+					$request
+				)
+			);
+		} catch (Exception $e) {
+			return $controller->sendResponse($e);
+		}
+	}
 
 
-    /**
-     * Inserts a new model object according to the $request
-     *
-     * @param EEM_Base        $model
-     * @param WP_REST_Request $request
-     * @return array
-     * @throws EE_Error
-     * @throws RestException
-     * @throws ReflectionException
-     * @throws Exception
-     */
-    public function insert(EEM_Base $model, WP_REST_Request $request): array
-    {
-        // echo "\n\n";
-        // \EEH_Debug_Tools::printr(__FUNCTION__, __CLASS__, __FILE__, __LINE__, 3);
-        Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_edit, 'create');
-        $default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
-        // \EEH_Debug_Tools::printr($default_cap_to_check_for, '$default_cap_to_check_for', __FILE__, __LINE__);
-        if (! current_user_can($default_cap_to_check_for)) {
-            throw new RestException(
-                'rest_cannot_create_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
-                sprintf(
-                    esc_html__(
-                    // @codingStandardsIgnoreStart
-                        'For now, only those with the admin capability to "%1$s" are allowed to use the REST API to insert data into Event Espresso.',
-                        // @codingStandardsIgnoreEnd
-                        'event_espresso'
-                    ),
-                    $default_cap_to_check_for
-                ),
-                ['status' => 403]
-            );
-        }
-        $submitted_json_data = $this->getBodyParams($request);
-        // \EEH_Debug_Tools::printr($submitted_json_data, '$submitted_json_data', __FILE__, __LINE__);
-        $model_data          = ModelDataTranslator::prepareConditionsQueryParamsForModels(
-            $submitted_json_data,
-            $model,
-            $this->getModelVersionInfo()->requestedVersion(),
-            true
-        );
-        // \EEH_Debug_Tools::printr($model_data, '$model_data', __FILE__, __LINE__);
-        $model_obj           = EE_Registry::instance()->load_class(
-            $model->get_this_model_name(),
-            [$model_data, $model->get_timezone()],
-            false,
-            false
-        );
-        $model_obj->save();
-        $new_id = $model_obj->ID();
-        if (! $new_id) {
-            throw new RestException(
-                'rest_insertion_failed',
-                sprintf(esc_html__('Could not insert new %1$s', 'event_espresso'), $model->get_this_model_name())
-            );
-        }
-        return $this->returnModelObjAsJsonResponse($model_obj, $request);
-    }
+	/**
+	 * Inserts a new model object according to the $request
+	 *
+	 * @param EEM_Base        $model
+	 * @param WP_REST_Request $request
+	 * @return array
+	 * @throws EE_Error
+	 * @throws RestException
+	 * @throws ReflectionException
+	 * @throws Exception
+	 */
+	public function insert(EEM_Base $model, WP_REST_Request $request): array
+	{
+		// echo "\n\n";
+		// \EEH_Debug_Tools::printr(__FUNCTION__, __CLASS__, __FILE__, __LINE__, 3);
+		Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_edit, 'create');
+		$default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
+		// \EEH_Debug_Tools::printr($default_cap_to_check_for, '$default_cap_to_check_for', __FILE__, __LINE__);
+		if (! current_user_can($default_cap_to_check_for)) {
+			throw new RestException(
+				'rest_cannot_create_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
+				sprintf(
+					esc_html__(
+					// @codingStandardsIgnoreStart
+						'For now, only those with the admin capability to "%1$s" are allowed to use the REST API to insert data into Event Espresso.',
+						// @codingStandardsIgnoreEnd
+						'event_espresso'
+					),
+					$default_cap_to_check_for
+				),
+				['status' => 403]
+			);
+		}
+		$submitted_json_data = $this->getBodyParams($request);
+		// \EEH_Debug_Tools::printr($submitted_json_data, '$submitted_json_data', __FILE__, __LINE__);
+		$model_data          = ModelDataTranslator::prepareConditionsQueryParamsForModels(
+			$submitted_json_data,
+			$model,
+			$this->getModelVersionInfo()->requestedVersion(),
+			true
+		);
+		// \EEH_Debug_Tools::printr($model_data, '$model_data', __FILE__, __LINE__);
+		$model_obj           = EE_Registry::instance()->load_class(
+			$model->get_this_model_name(),
+			[$model_data, $model->get_timezone()],
+			false,
+			false
+		);
+		$model_obj->save();
+		$new_id = $model_obj->ID();
+		if (! $new_id) {
+			throw new RestException(
+				'rest_insertion_failed',
+				sprintf(esc_html__('Could not insert new %1$s', 'event_espresso'), $model->get_this_model_name())
+			);
+		}
+		return $this->returnModelObjAsJsonResponse($model_obj, $request);
+	}
 
 
-    /**
-     * Updates an existing model object according to the $request
-     *
-     * @param EEM_Base        $model
-     * @param WP_REST_Request $request
-     * @return array
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function update(EEM_Base $model, WP_REST_Request $request): array
-    {
-        Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_edit, 'edit');
-        $default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
-        if (! current_user_can($default_cap_to_check_for)) {
-            throw new RestException(
-                'rest_cannot_edit_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
-                sprintf(
-                    esc_html__(
-                    // @codingStandardsIgnoreStart
-                        'For now, only those with the admin capability to "%1$s" are allowed to use the REST API to update data into Event Espresso.',
-                        // @codingStandardsIgnoreEnd
-                        'event_espresso'
-                    ),
-                    $default_cap_to_check_for
-                ),
-                ['status' => 403]
-            );
-        }
-        $obj_id = $request->get_param('id');
-        if (! $obj_id) {
-            throw new RestException(
-                'rest_edit_failed',
-                sprintf(esc_html__('Could not edit %1$s', 'event_espresso'), $model->get_this_model_name())
-            );
-        }
-        $model_data = ModelDataTranslator::prepareConditionsQueryParamsForModels(
-            $this->getBodyParams($request),
-            $model,
-            $this->getModelVersionInfo()->requestedVersion(),
-            true
-        );
-        $model_obj  = $model->get_one_by_ID($obj_id);
-        if (! $model_obj instanceof EE_Base_Class) {
-            $lowercase_model_name = strtolower($model->get_this_model_name());
-            throw new RestException(
-                sprintf('rest_%s_invalid_id', $lowercase_model_name),
-                sprintf(esc_html__('Invalid %s ID.', 'event_espresso'), $lowercase_model_name),
-                ['status' => 404]
-            );
-        }
-        $model_obj->save($model_data);
-        return $this->returnModelObjAsJsonResponse($model_obj, $request);
-    }
+	/**
+	 * Updates an existing model object according to the $request
+	 *
+	 * @param EEM_Base        $model
+	 * @param WP_REST_Request $request
+	 * @return array
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function update(EEM_Base $model, WP_REST_Request $request): array
+	{
+		Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_edit, 'edit');
+		$default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
+		if (! current_user_can($default_cap_to_check_for)) {
+			throw new RestException(
+				'rest_cannot_edit_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
+				sprintf(
+					esc_html__(
+					// @codingStandardsIgnoreStart
+						'For now, only those with the admin capability to "%1$s" are allowed to use the REST API to update data into Event Espresso.',
+						// @codingStandardsIgnoreEnd
+						'event_espresso'
+					),
+					$default_cap_to_check_for
+				),
+				['status' => 403]
+			);
+		}
+		$obj_id = $request->get_param('id');
+		if (! $obj_id) {
+			throw new RestException(
+				'rest_edit_failed',
+				sprintf(esc_html__('Could not edit %1$s', 'event_espresso'), $model->get_this_model_name())
+			);
+		}
+		$model_data = ModelDataTranslator::prepareConditionsQueryParamsForModels(
+			$this->getBodyParams($request),
+			$model,
+			$this->getModelVersionInfo()->requestedVersion(),
+			true
+		);
+		$model_obj  = $model->get_one_by_ID($obj_id);
+		if (! $model_obj instanceof EE_Base_Class) {
+			$lowercase_model_name = strtolower($model->get_this_model_name());
+			throw new RestException(
+				sprintf('rest_%s_invalid_id', $lowercase_model_name),
+				sprintf(esc_html__('Invalid %s ID.', 'event_espresso'), $lowercase_model_name),
+				['status' => 404]
+			);
+		}
+		$model_obj->save($model_data);
+		return $this->returnModelObjAsJsonResponse($model_obj, $request);
+	}
 
 
-    /**
-     * Updates an existing model object according to the $request
-     *
-     * @param EEM_Base        $model
-     * @param WP_REST_Request $request
-     * @return array of either the soft-deleted item, or
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function delete(EEM_Base $model, WP_REST_Request $request): array
-    {
-        Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_delete, 'delete');
-        $default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
-        if (! current_user_can($default_cap_to_check_for)) {
-            throw new RestException(
-                'rest_cannot_delete_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
-                sprintf(
-                    esc_html__(
-                    // @codingStandardsIgnoreStart
-                        'For now, only those with the admin capability to "%1$s" are allowed to use the REST API to delete data into Event Espresso.',
-                        // @codingStandardsIgnoreEnd
-                        'event_espresso'
-                    ),
-                    $default_cap_to_check_for
-                ),
-                ['status' => 403]
-            );
-        }
-        $obj_id = $request->get_param('id');
-        // this is where we would apply more fine-grained caps
-        $model_obj = $model->get_one_by_ID($obj_id);
-        if (! $model_obj instanceof EE_Base_Class) {
-            $lowercase_model_name = strtolower($model->get_this_model_name());
-            throw new RestException(
-                sprintf('rest_%s_invalid_id', $lowercase_model_name),
-                sprintf(esc_html__('Invalid %s ID.', 'event_espresso'), $lowercase_model_name),
-                ['status' => 404]
-            );
-        }
-        $requested_permanent_delete = filter_var($request->get_param('force'), FILTER_VALIDATE_BOOLEAN);
-        $requested_allow_blocking   = filter_var($request->get_param('allow_blocking'), FILTER_VALIDATE_BOOLEAN);
-        if ($requested_permanent_delete) {
-            $previous = $this->returnModelObjAsJsonResponse($model_obj, $request);
-            $deleted  = (bool) $model->delete_permanently_by_ID($obj_id, $requested_allow_blocking);
-            return [
-                'deleted'  => $deleted,
-                'previous' => $previous,
-            ];
-        } else {
-            if ($model instanceof EEM_Soft_Delete_Base) {
-                $model->delete_by_ID($obj_id, $requested_allow_blocking);
-                return $this->returnModelObjAsJsonResponse($model_obj, $request);
-            } else {
-                throw new RestException(
-                    'rest_trash_not_supported',
-                    sprintf(
-                        esc_html__('%1$s do not support trashing. Set force=1 to delete.', 'event_espresso'),
-                        EEH_Inflector::pluralize($model->get_this_model_name())
-                    )
-                );
-            }
-        }
-    }
+	/**
+	 * Updates an existing model object according to the $request
+	 *
+	 * @param EEM_Base        $model
+	 * @param WP_REST_Request $request
+	 * @return array of either the soft-deleted item, or
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function delete(EEM_Base $model, WP_REST_Request $request): array
+	{
+		Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_delete, 'delete');
+		$default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
+		if (! current_user_can($default_cap_to_check_for)) {
+			throw new RestException(
+				'rest_cannot_delete_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
+				sprintf(
+					esc_html__(
+					// @codingStandardsIgnoreStart
+						'For now, only those with the admin capability to "%1$s" are allowed to use the REST API to delete data into Event Espresso.',
+						// @codingStandardsIgnoreEnd
+						'event_espresso'
+					),
+					$default_cap_to_check_for
+				),
+				['status' => 403]
+			);
+		}
+		$obj_id = $request->get_param('id');
+		// this is where we would apply more fine-grained caps
+		$model_obj = $model->get_one_by_ID($obj_id);
+		if (! $model_obj instanceof EE_Base_Class) {
+			$lowercase_model_name = strtolower($model->get_this_model_name());
+			throw new RestException(
+				sprintf('rest_%s_invalid_id', $lowercase_model_name),
+				sprintf(esc_html__('Invalid %s ID.', 'event_espresso'), $lowercase_model_name),
+				['status' => 404]
+			);
+		}
+		$requested_permanent_delete = filter_var($request->get_param('force'), FILTER_VALIDATE_BOOLEAN);
+		$requested_allow_blocking   = filter_var($request->get_param('allow_blocking'), FILTER_VALIDATE_BOOLEAN);
+		if ($requested_permanent_delete) {
+			$previous = $this->returnModelObjAsJsonResponse($model_obj, $request);
+			$deleted  = (bool) $model->delete_permanently_by_ID($obj_id, $requested_allow_blocking);
+			return [
+				'deleted'  => $deleted,
+				'previous' => $previous,
+			];
+		} else {
+			if ($model instanceof EEM_Soft_Delete_Base) {
+				$model->delete_by_ID($obj_id, $requested_allow_blocking);
+				return $this->returnModelObjAsJsonResponse($model_obj, $request);
+			} else {
+				throw new RestException(
+					'rest_trash_not_supported',
+					sprintf(
+						esc_html__('%1$s do not support trashing. Set force=1 to delete.', 'event_espresso'),
+						EEH_Inflector::pluralize($model->get_this_model_name())
+					)
+				);
+			}
+		}
+	}
 
 
-    /**
-     * Returns an array ready to be converted into a JSON response, based solely on the model object
-     *
-     * @param EE_Base_Class   $model_obj
-     * @param WP_REST_Request $request
-     * @return array ready for a response
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @throws RestException
-     * @throws RestPasswordIncorrectException
-     * @throws RestPasswordRequiredException
-     */
-    protected function returnModelObjAsJsonResponse(EE_Base_Class $model_obj, WP_REST_Request $request): array
-    {
-        $model = $model_obj->get_model();
-        // create an array exactly like the wpdb results row,
-        // so we can pass it to controllers/model/Read::create_entity_from_wpdb_result()
-        $simulated_db_row = [];
-        foreach ($model->field_settings(true) as $field_name => $field_obj) {
-            // we need to reconstruct the normal wpdb results, including the db-only fields
-            // like a secondary table's primary key. The models expect those (but don't care what value they have)
-            if ($field_obj instanceof EE_DB_Only_Field_Base) {
-                $raw_value = true;
-            } elseif ($field_obj instanceof EE_Datetime_Field) {
-                $raw_value = $model_obj->get_DateTime_object($field_name);
-            } else {
-                $raw_value = $model_obj->get_raw($field_name);
-            }
-            $simulated_db_row[ $field_obj->get_qualified_column() ] = $field_obj->prepare_for_use_in_db($raw_value);
-        }
-        /** @var Read $read_controller */
-        $read_controller = LoaderFactory::getLoader()->getNew(Read::class);
-        $read_controller->setRequestedVersion($this->getRequestedVersion());
-        // the simulates request really doesn't need any info downstream
-        $simulated_request = new WP_REST_Request('GET');
-        // set the caps context on the simulated according to the original request.
-        switch ($request->get_method()) {
-            case 'POST':
-            case 'PUT':
-                $caps_context = EEM_Base::caps_edit;
-                break;
-            case 'DELETE':
-                $caps_context = EEM_Base::caps_delete;
-                break;
-            default:
-                $caps_context = EEM_Base::caps_read_admin;
-        }
-        $simulated_request->set_param('caps', $caps_context);
-        return $read_controller->createEntityFromWpdbResult(
-            $model_obj->get_model(),
-            $simulated_db_row,
-            $simulated_request
-        );
-    }
+	/**
+	 * Returns an array ready to be converted into a JSON response, based solely on the model object
+	 *
+	 * @param EE_Base_Class   $model_obj
+	 * @param WP_REST_Request $request
+	 * @return array ready for a response
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @throws RestException
+	 * @throws RestPasswordIncorrectException
+	 * @throws RestPasswordRequiredException
+	 */
+	protected function returnModelObjAsJsonResponse(EE_Base_Class $model_obj, WP_REST_Request $request): array
+	{
+		$model = $model_obj->get_model();
+		// create an array exactly like the wpdb results row,
+		// so we can pass it to controllers/model/Read::create_entity_from_wpdb_result()
+		$simulated_db_row = [];
+		foreach ($model->field_settings(true) as $field_name => $field_obj) {
+			// we need to reconstruct the normal wpdb results, including the db-only fields
+			// like a secondary table's primary key. The models expect those (but don't care what value they have)
+			if ($field_obj instanceof EE_DB_Only_Field_Base) {
+				$raw_value = true;
+			} elseif ($field_obj instanceof EE_Datetime_Field) {
+				$raw_value = $model_obj->get_DateTime_object($field_name);
+			} else {
+				$raw_value = $model_obj->get_raw($field_name);
+			}
+			$simulated_db_row[ $field_obj->get_qualified_column() ] = $field_obj->prepare_for_use_in_db($raw_value);
+		}
+		/** @var Read $read_controller */
+		$read_controller = LoaderFactory::getLoader()->getNew(Read::class);
+		$read_controller->setRequestedVersion($this->getRequestedVersion());
+		// the simulates request really doesn't need any info downstream
+		$simulated_request = new WP_REST_Request('GET');
+		// set the caps context on the simulated according to the original request.
+		switch ($request->get_method()) {
+			case 'POST':
+			case 'PUT':
+				$caps_context = EEM_Base::caps_edit;
+				break;
+			case 'DELETE':
+				$caps_context = EEM_Base::caps_delete;
+				break;
+			default:
+				$caps_context = EEM_Base::caps_read_admin;
+		}
+		$simulated_request->set_param('caps', $caps_context);
+		return $read_controller->createEntityFromWpdbResult(
+			$model_obj->get_model(),
+			$simulated_db_row,
+			$simulated_request
+		);
+	}
 
 
-    /**
-     * Gets the item affected by this request
-     *
-     * @param EEM_Base        $model
-     * @param WP_REST_Request $request
-     * @param int|string      $obj_id
-     * @return WP_Error|array
-     * @throws EE_Error
-     */
-    protected function getOneBasedOnRequest(EEM_Base $model, WP_REST_Request $request, $obj_id)
-    {
-        $requested_version = $this->getRequestedVersion($request->get_route());
-        $get_request       = new WP_REST_Request(
-            'GET',
-            EED_Core_Rest_Api::ee_api_namespace
-            . $requested_version
-            . '/'
-            . EEH_Inflector::pluralize_and_lower($model->get_this_model_name())
-            . '/'
-            . $obj_id
-        );
-        $get_request->set_url_params(
-            [
-                'id'      => $obj_id,
-                'include' => $request->get_param('include'),
-            ]
-        );
-        $read_controller = LoaderFactory::getLoader()->getNew(
-            'EventEspresso\core\libraries\rest_api\controllers\model\Read'
-        );
-        $read_controller->setRequestedVersion($this->getRequestedVersion());
-        return $read_controller->getEntityFromModel($model, $get_request);
-    }
+	/**
+	 * Gets the item affected by this request
+	 *
+	 * @param EEM_Base        $model
+	 * @param WP_REST_Request $request
+	 * @param int|string      $obj_id
+	 * @return WP_Error|array
+	 * @throws EE_Error
+	 */
+	protected function getOneBasedOnRequest(EEM_Base $model, WP_REST_Request $request, $obj_id)
+	{
+		$requested_version = $this->getRequestedVersion($request->get_route());
+		$get_request       = new WP_REST_Request(
+			'GET',
+			EED_Core_Rest_Api::ee_api_namespace
+			. $requested_version
+			. '/'
+			. EEH_Inflector::pluralize_and_lower($model->get_this_model_name())
+			. '/'
+			. $obj_id
+		);
+		$get_request->set_url_params(
+			[
+				'id'      => $obj_id,
+				'include' => $request->get_param('include'),
+			]
+		);
+		$read_controller = LoaderFactory::getLoader()->getNew(
+			'EventEspresso\core\libraries\rest_api\controllers\model\Read'
+		);
+		$read_controller->setRequestedVersion($this->getRequestedVersion());
+		return $read_controller->getEntityFromModel($model, $get_request);
+	}
 
 
-    /**
-     * Adds a relation between the specified models (if it doesn't already exist.)
-     *
-     * @param WP_REST_Request $request
-     * @param string          $version
-     * @param string          $model_name
-     * @param string          $related_model_name
-     * @return WP_REST_Response
-     * @since 4.9.76.p
-     */
-    public static function handleRequestAddRelation(
-        WP_REST_Request $request,
-        string $version,
-        string $model_name,
-        string $related_model_name
-    ): WP_REST_Response {
-        $controller = new Write();
-        try {
-            $controller->setRequestedVersion($version);
-            $main_model = $controller->validateModel($model_name);
-            $controller->validateModel($related_model_name);
-            return $controller->sendResponse(
-                $controller->addRelation(
-                    $main_model,
-                    $main_model->related_settings_for($related_model_name),
-                    $request
-                )
-            );
-        } catch (Exception $e) {
-            return $controller->sendResponse($e);
-        }
-    }
+	/**
+	 * Adds a relation between the specified models (if it doesn't already exist.)
+	 *
+	 * @param WP_REST_Request $request
+	 * @param string          $version
+	 * @param string          $model_name
+	 * @param string          $related_model_name
+	 * @return WP_REST_Response
+	 * @since 4.9.76.p
+	 */
+	public static function handleRequestAddRelation(
+		WP_REST_Request $request,
+		string $version,
+		string $model_name,
+		string $related_model_name
+	): WP_REST_Response {
+		$controller = new Write();
+		try {
+			$controller->setRequestedVersion($version);
+			$main_model = $controller->validateModel($model_name);
+			$controller->validateModel($related_model_name);
+			return $controller->sendResponse(
+				$controller->addRelation(
+					$main_model,
+					$main_model->related_settings_for($related_model_name),
+					$request
+				)
+			);
+		} catch (Exception $e) {
+			return $controller->sendResponse($e);
+		}
+	}
 
 
-    /**
-     * Adds a relation between the two model specified model objects.
-     *
-     * @param EEM_Base               $model
-     * @param EE_Model_Relation_Base $relation
-     * @param WP_REST_Request        $request
-     * @return array
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @throws RestException
-     * @throws Exception
-     * @since 4.9.76.p
-     */
-    public function addRelation(EEM_Base $model, EE_Model_Relation_Base $relation, WP_REST_Request $request): array
-    {
-        [$model_obj, $other_obj] = $this->getBothModelObjects($model, $relation, $request);
-        $extra_params = [];
-        if ($relation instanceof EE_HABTM_Relation) {
-            $extra_params = array_intersect_key(
-                ModelDataTranslator::prepareConditionsQueryParamsForModels(
-                    $request->get_body_params(),
-                    $relation->get_join_model(),
-                    $this->getModelVersionInfo()->requestedVersion(),
-                    true
-                ),
-                $relation->getNonKeyFields()
-            );
-        }
-        // Add a relation.
-        $related_obj = $model_obj->_add_relation_to(
-            $other_obj,
-            $relation->get_other_model()->get_this_model_name(),
-            $extra_params
-        );
-        $response    = [
-            strtolower($model->get_this_model_name())                       => $this->returnModelObjAsJsonResponse(
-                $model_obj,
-                $request
-            ),
-            strtolower($relation->get_other_model()->get_this_model_name()) => $this->returnModelObjAsJsonResponse(
-                $related_obj,
-                $request
-            ),
-        ];
-        if ($relation instanceof EE_HABTM_Relation) {
-            $join_model_obj                                                                     =
-                $relation->get_join_model()->get_one(
-                    [
-                        [
-                            $relation->get_join_model()->get_foreign_key_to($model->get_this_model_name())->get_name(
-                            )             => $model_obj->ID(),
-                            $relation->get_join_model()->get_foreign_key_to(
-                                $relation->get_other_model()->get_this_model_name()
-                            )->get_name() => $related_obj->ID(),
-                        ],
-                    ]
-                );
-            $response['join'][ strtolower($relation->get_join_model()->get_this_model_name()) ] =
-                $this->returnModelObjAsJsonResponse($join_model_obj, $request);
-        }
-        return $response;
-    }
+	/**
+	 * Adds a relation between the two model specified model objects.
+	 *
+	 * @param EEM_Base               $model
+	 * @param EE_Model_Relation_Base $relation
+	 * @param WP_REST_Request        $request
+	 * @return array
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @throws RestException
+	 * @throws Exception
+	 * @since 4.9.76.p
+	 */
+	public function addRelation(EEM_Base $model, EE_Model_Relation_Base $relation, WP_REST_Request $request): array
+	{
+		[$model_obj, $other_obj] = $this->getBothModelObjects($model, $relation, $request);
+		$extra_params = [];
+		if ($relation instanceof EE_HABTM_Relation) {
+			$extra_params = array_intersect_key(
+				ModelDataTranslator::prepareConditionsQueryParamsForModels(
+					$request->get_body_params(),
+					$relation->get_join_model(),
+					$this->getModelVersionInfo()->requestedVersion(),
+					true
+				),
+				$relation->getNonKeyFields()
+			);
+		}
+		// Add a relation.
+		$related_obj = $model_obj->_add_relation_to(
+			$other_obj,
+			$relation->get_other_model()->get_this_model_name(),
+			$extra_params
+		);
+		$response    = [
+			strtolower($model->get_this_model_name())                       => $this->returnModelObjAsJsonResponse(
+				$model_obj,
+				$request
+			),
+			strtolower($relation->get_other_model()->get_this_model_name()) => $this->returnModelObjAsJsonResponse(
+				$related_obj,
+				$request
+			),
+		];
+		if ($relation instanceof EE_HABTM_Relation) {
+			$join_model_obj                                                                     =
+				$relation->get_join_model()->get_one(
+					[
+						[
+							$relation->get_join_model()->get_foreign_key_to($model->get_this_model_name())->get_name(
+							)             => $model_obj->ID(),
+							$relation->get_join_model()->get_foreign_key_to(
+								$relation->get_other_model()->get_this_model_name()
+							)->get_name() => $related_obj->ID(),
+						],
+					]
+				);
+			$response['join'][ strtolower($relation->get_join_model()->get_this_model_name()) ] =
+				$this->returnModelObjAsJsonResponse($join_model_obj, $request);
+		}
+		return $response;
+	}
 
 
-    /**
-     * Removes the relation between the specified models (if it exists).
-     *
-     * @param WP_REST_Request $request
-     * @param                 $version
-     * @param                 $model_name
-     * @param                 $related_model_name
-     * @return WP_REST_Response
-     * @since 4.9.76.p
-     */
-    public static function handleRequestRemoveRelation(
-        WP_REST_Request $request,
-        $version,
-        $model_name,
-        $related_model_name
-    ): WP_REST_Response {
-        $controller = new Write();
-        try {
-            $controller->setRequestedVersion($version);
-            $main_model = $controller->getModelVersionInfo()->loadModel($model_name);
-            return $controller->sendResponse(
-                $controller->removeRelation(
-                    $main_model,
-                    $main_model->related_settings_for($related_model_name),
-                    $request
-                )
-            );
-        } catch (Exception $e) {
-            return $controller->sendResponse($e);
-        }
-    }
+	/**
+	 * Removes the relation between the specified models (if it exists).
+	 *
+	 * @param WP_REST_Request $request
+	 * @param                 $version
+	 * @param                 $model_name
+	 * @param                 $related_model_name
+	 * @return WP_REST_Response
+	 * @since 4.9.76.p
+	 */
+	public static function handleRequestRemoveRelation(
+		WP_REST_Request $request,
+		$version,
+		$model_name,
+		$related_model_name
+	): WP_REST_Response {
+		$controller = new Write();
+		try {
+			$controller->setRequestedVersion($version);
+			$main_model = $controller->getModelVersionInfo()->loadModel($model_name);
+			return $controller->sendResponse(
+				$controller->removeRelation(
+					$main_model,
+					$main_model->related_settings_for($related_model_name),
+					$request
+				)
+			);
+		} catch (Exception $e) {
+			return $controller->sendResponse($e);
+		}
+	}
 
 
-    /**
-     * Adds a relation between the two model specified model objects.
-     *
-     * @param EEM_Base               $model
-     * @param EE_Model_Relation_Base $relation
-     * @param WP_REST_Request        $request
-     * @return array
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @throws RestException *@throws ReflectionException
-     * @throws Exception
-     * @since 4.9.76.p
-     */
-    public function removeRelation(EEM_Base $model, EE_Model_Relation_Base $relation, WP_REST_Request $request): array
-    {
-        // This endpoint doesn't accept body parameters (it's understandable to think it might, so let developers know
-        // up-front that it doesn't.)
-        $body_params = $request->get_body_params();
-        if (! empty($body_params)) {
-            throw new RestException(
-                'invalid_field',
-                sprintf(
-                    esc_html__('This endpoint doesn\'t accept post body arguments, you sent in %1$s', 'event_espresso'),
-                    implode(array_keys($body_params))
-                )
-            );
-        }
-        [$model_obj, $other_obj] = $this->getBothModelObjects($model, $relation, $request);
-        // Remember the old relation, if it used a join entry.
-        $join_model_obj = null;
-        if ($relation instanceof EE_HABTM_Relation) {
-            $join_model_obj = $relation->get_join_model()->get_one(
-                [
-                    [
-                        $model->primary_key_name()                       => $model_obj->ID(),
-                        $relation->get_other_model()->primary_key_name() => $other_obj->ID(),
-                    ],
-                ]
-            );
-        }
-        // Remove the relation.
-        $related_obj = $model_obj->_remove_relation_to(
-            $other_obj,
-            $relation->get_other_model()->get_this_model_name()
-        );
-        $response    = [
-            strtolower($model->get_this_model_name())                       => $this->returnModelObjAsJsonResponse(
-                $model_obj,
-                $request
-            ),
-            strtolower($relation->get_other_model()->get_this_model_name()) => $this->returnModelObjAsJsonResponse(
-                $related_obj,
-                $request
-            ),
-        ];
-        if ($relation instanceof EE_HABTM_Relation) {
-            $relation->get_join_model()->get_one(
-                [
-                    [
-                        $model->primary_key_name()                       => $model_obj->ID(),
-                        $relation->get_other_model()->primary_key_name() => $other_obj->ID(),
-                    ],
-                ]
-            );
-            if ($join_model_obj instanceof EE_Base_Class) {
-                $response['join'][ strtolower($relation->get_join_model()->get_this_model_name()) ] =
-                    $this->returnModelObjAsJsonResponse($join_model_obj, $request);
-            } else {
-                $response['join'][ strtolower($relation->get_join_model()->get_this_model_name()) ] = null;
-            }
-        }
-        return $response;
-    }
+	/**
+	 * Adds a relation between the two model specified model objects.
+	 *
+	 * @param EEM_Base               $model
+	 * @param EE_Model_Relation_Base $relation
+	 * @param WP_REST_Request        $request
+	 * @return array
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @throws RestException *@throws ReflectionException
+	 * @throws Exception
+	 * @since 4.9.76.p
+	 */
+	public function removeRelation(EEM_Base $model, EE_Model_Relation_Base $relation, WP_REST_Request $request): array
+	{
+		// This endpoint doesn't accept body parameters (it's understandable to think it might, so let developers know
+		// up-front that it doesn't.)
+		$body_params = $request->get_body_params();
+		if (! empty($body_params)) {
+			throw new RestException(
+				'invalid_field',
+				sprintf(
+					esc_html__('This endpoint doesn\'t accept post body arguments, you sent in %1$s', 'event_espresso'),
+					implode(array_keys($body_params))
+				)
+			);
+		}
+		[$model_obj, $other_obj] = $this->getBothModelObjects($model, $relation, $request);
+		// Remember the old relation, if it used a join entry.
+		$join_model_obj = null;
+		if ($relation instanceof EE_HABTM_Relation) {
+			$join_model_obj = $relation->get_join_model()->get_one(
+				[
+					[
+						$model->primary_key_name()                       => $model_obj->ID(),
+						$relation->get_other_model()->primary_key_name() => $other_obj->ID(),
+					],
+				]
+			);
+		}
+		// Remove the relation.
+		$related_obj = $model_obj->_remove_relation_to(
+			$other_obj,
+			$relation->get_other_model()->get_this_model_name()
+		);
+		$response    = [
+			strtolower($model->get_this_model_name())                       => $this->returnModelObjAsJsonResponse(
+				$model_obj,
+				$request
+			),
+			strtolower($relation->get_other_model()->get_this_model_name()) => $this->returnModelObjAsJsonResponse(
+				$related_obj,
+				$request
+			),
+		];
+		if ($relation instanceof EE_HABTM_Relation) {
+			$relation->get_join_model()->get_one(
+				[
+					[
+						$model->primary_key_name()                       => $model_obj->ID(),
+						$relation->get_other_model()->primary_key_name() => $other_obj->ID(),
+					],
+				]
+			);
+			if ($join_model_obj instanceof EE_Base_Class) {
+				$response['join'][ strtolower($relation->get_join_model()->get_this_model_name()) ] =
+					$this->returnModelObjAsJsonResponse($join_model_obj, $request);
+			} else {
+				$response['join'][ strtolower($relation->get_join_model()->get_this_model_name()) ] = null;
+			}
+		}
+		return $response;
+	}
 
 
-    /**
-     * Gets the model objects indicated by the model, relation object, and request.
-     * Throws an exception if the first object doesn't exist, and currently if the related object also doesn't exist.
-     * However, this behaviour may change, as we may add support for simultaneously creating and relating data.
-     *
-     * @param EEM_Base               $model
-     * @param EE_Model_Relation_Base $relation
-     * @param WP_REST_Request        $request
-     * @return array {
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @throws RestException *@throws EE_Error
-     * @throws Exception
-     * @since 4.9.76.p
-     */
-    protected function getBothModelObjects(
-        EEM_Base $model,
-        EE_Model_Relation_Base $relation,
-        WP_REST_Request $request
-    ): array {
-        // Check generic caps. For now, we're only allowing access to this endpoint to full admins.
-        Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_edit, 'edit');
-        $default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
-        if (! current_user_can($default_cap_to_check_for)) {
-            throw new RestException(
-                'rest_cannot_edit_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
-                sprintf(
-                    esc_html__(
-                    // @codingStandardsIgnoreStart
-                        'For now, only those with the admin capability to "%1$s" are allowed to use the REST API to add relations in Event Espresso.',
-                        // @codingStandardsIgnoreEnd
-                        'event_espresso'
-                    ),
-                    $default_cap_to_check_for
-                ),
-                ['status' => 403]
-            );
-        }
-        // Get the main model object.
-        $model_obj = $this->getOneOrThrowException($model, $request->get_param('id'));
-        // For now, we require the other model object to exist too. This might be relaxed later.
-        $other_obj = $this->getOneOrThrowException($relation->get_other_model(), $request->get_param('related_id'));
-        return [$model_obj, $other_obj];
-    }
+	/**
+	 * Gets the model objects indicated by the model, relation object, and request.
+	 * Throws an exception if the first object doesn't exist, and currently if the related object also doesn't exist.
+	 * However, this behaviour may change, as we may add support for simultaneously creating and relating data.
+	 *
+	 * @param EEM_Base               $model
+	 * @param EE_Model_Relation_Base $relation
+	 * @param WP_REST_Request        $request
+	 * @return array {
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @throws RestException *@throws EE_Error
+	 * @throws Exception
+	 * @since 4.9.76.p
+	 */
+	protected function getBothModelObjects(
+		EEM_Base $model,
+		EE_Model_Relation_Base $relation,
+		WP_REST_Request $request
+	): array {
+		// Check generic caps. For now, we're only allowing access to this endpoint to full admins.
+		Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_edit, 'edit');
+		$default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
+		if (! current_user_can($default_cap_to_check_for)) {
+			throw new RestException(
+				'rest_cannot_edit_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
+				sprintf(
+					esc_html__(
+					// @codingStandardsIgnoreStart
+						'For now, only those with the admin capability to "%1$s" are allowed to use the REST API to add relations in Event Espresso.',
+						// @codingStandardsIgnoreEnd
+						'event_espresso'
+					),
+					$default_cap_to_check_for
+				),
+				['status' => 403]
+			);
+		}
+		// Get the main model object.
+		$model_obj = $this->getOneOrThrowException($model, $request->get_param('id'));
+		// For now, we require the other model object to exist too. This might be relaxed later.
+		$other_obj = $this->getOneOrThrowException($relation->get_other_model(), $request->get_param('related_id'));
+		return [$model_obj, $other_obj];
+	}
 
 
-    /**
-     * Gets the model with that ID or throws a REST exception.
-     *
-     * @param EEM_Base   $model
-     * @param int|string $id
-     * @return EE_Base_Class
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @throws RestException
-     * @since 4.9.76.p
-     */
-    protected function getOneOrThrowException(EEM_Base $model, $id): EE_Base_Class
-    {
-        $model_obj = $model->get_one_by_ID($id);
-        // @todo: check they can permission for it. For now unnecessary because only full admins can use this endpoint.
-        if ($model_obj instanceof EE_Base_Class) {
-            return $model_obj;
-        }
-        $lowercase_model_name = strtolower($model->get_this_model_name());
-        throw new RestException(
-            sprintf('rest_%s_invalid_id', $lowercase_model_name),
-            sprintf(esc_html__('Invalid %s ID.', 'event_espresso'), $lowercase_model_name),
-            ['status' => 404]
-        );
-    }
+	/**
+	 * Gets the model with that ID or throws a REST exception.
+	 *
+	 * @param EEM_Base   $model
+	 * @param int|string $id
+	 * @return EE_Base_Class
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @throws RestException
+	 * @since 4.9.76.p
+	 */
+	protected function getOneOrThrowException(EEM_Base $model, $id): EE_Base_Class
+	{
+		$model_obj = $model->get_one_by_ID($id);
+		// @todo: check they can permission for it. For now unnecessary because only full admins can use this endpoint.
+		if ($model_obj instanceof EE_Base_Class) {
+			return $model_obj;
+		}
+		$lowercase_model_name = strtolower($model->get_this_model_name());
+		throw new RestException(
+			sprintf('rest_%s_invalid_id', $lowercase_model_name),
+			sprintf(esc_html__('Invalid %s ID.', 'event_espresso'), $lowercase_model_name),
+			['status' => 404]
+		);
+	}
 }

Spacing +22 added lines, -22 removed lines

@@ -138,9 +138,9 @@ 
         Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_edit, 'create');
         $default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
         // \EEH_Debug_Tools::printr($default_cap_to_check_for, '$default_cap_to_check_for', __FILE__, __LINE__);
-        if (! current_user_can($default_cap_to_check_for)) {
+        if ( ! current_user_can($default_cap_to_check_for)) {
             throw new RestException(
-                'rest_cannot_create_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
+                'rest_cannot_create_'.EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
                 sprintf(
                     esc_html__(
                     // @codingStandardsIgnoreStart
@@ -162,7 +162,7 @@ 
             true
         );
         // \EEH_Debug_Tools::printr($model_data, '$model_data', __FILE__, __LINE__);
-        $model_obj           = EE_Registry::instance()->load_class(
+        $model_obj = EE_Registry::instance()->load_class(
             $model->get_this_model_name(),
             [$model_data, $model->get_timezone()],
             false,
@@ -170,7 +170,7 @@ 
         );
         $model_obj->save();
         $new_id = $model_obj->ID();
-        if (! $new_id) {
+        if ( ! $new_id) {
             throw new RestException(
                 'rest_insertion_failed',
                 sprintf(esc_html__('Could not insert new %1$s', 'event_espresso'), $model->get_this_model_name())
@@ -193,9 +193,9 @@ 
     {
         Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_edit, 'edit');
         $default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
-        if (! current_user_can($default_cap_to_check_for)) {
+        if ( ! current_user_can($default_cap_to_check_for)) {
             throw new RestException(
-                'rest_cannot_edit_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
+                'rest_cannot_edit_'.EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
                 sprintf(
                     esc_html__(
                     // @codingStandardsIgnoreStart
@@ -209,7 +209,7 @@ 
             );
         }
         $obj_id = $request->get_param('id');
-        if (! $obj_id) {
+        if ( ! $obj_id) {
             throw new RestException(
                 'rest_edit_failed',
                 sprintf(esc_html__('Could not edit %1$s', 'event_espresso'), $model->get_this_model_name())
@@ -221,8 +221,8 @@ 
             $this->getModelVersionInfo()->requestedVersion(),
             true
         );
-        $model_obj  = $model->get_one_by_ID($obj_id);
-        if (! $model_obj instanceof EE_Base_Class) {
+        $model_obj = $model->get_one_by_ID($obj_id);
+        if ( ! $model_obj instanceof EE_Base_Class) {
             $lowercase_model_name = strtolower($model->get_this_model_name());
             throw new RestException(
                 sprintf('rest_%s_invalid_id', $lowercase_model_name),
@@ -248,9 +248,9 @@ 
     {
         Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_delete, 'delete');
         $default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
-        if (! current_user_can($default_cap_to_check_for)) {
+        if ( ! current_user_can($default_cap_to_check_for)) {
             throw new RestException(
-                'rest_cannot_delete_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
+                'rest_cannot_delete_'.EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
                 sprintf(
                     esc_html__(
                     // @codingStandardsIgnoreStart
@@ -266,7 +266,7 @@ 
         $obj_id = $request->get_param('id');
         // this is where we would apply more fine-grained caps
         $model_obj = $model->get_one_by_ID($obj_id);
-        if (! $model_obj instanceof EE_Base_Class) {
+        if ( ! $model_obj instanceof EE_Base_Class) {
             $lowercase_model_name = strtolower($model->get_this_model_name());
             throw new RestException(
                 sprintf('rest_%s_invalid_id', $lowercase_model_name),
@@ -328,7 +328,7 @@ 
             } else {
                 $raw_value = $model_obj->get_raw($field_name);
             }
-            $simulated_db_row[ $field_obj->get_qualified_column() ] = $field_obj->prepare_for_use_in_db($raw_value);
+            $simulated_db_row[$field_obj->get_qualified_column()] = $field_obj->prepare_for_use_in_db($raw_value);
         }
         /** @var Read $read_controller */
         $read_controller = LoaderFactory::getLoader()->getNew(Read::class);
@@ -459,7 +459,7 @@ 
             $relation->get_other_model()->get_this_model_name(),
             $extra_params
         );
-        $response    = [
+        $response = [
             strtolower($model->get_this_model_name())                       => $this->returnModelObjAsJsonResponse(
                 $model_obj,
                 $request
@@ -470,7 +470,7 @@ 
             ),
         ];
         if ($relation instanceof EE_HABTM_Relation) {
-            $join_model_obj                                                                     =
+            $join_model_obj =
                 $relation->get_join_model()->get_one(
                     [
                         [
@@ -482,7 +482,7 @@ 
                         ],
                     ]
                 );
-            $response['join'][ strtolower($relation->get_join_model()->get_this_model_name()) ] =
+            $response['join'][strtolower($relation->get_join_model()->get_this_model_name())] =
                 $this->returnModelObjAsJsonResponse($join_model_obj, $request);
         }
         return $response;
@@ -540,7 +540,7 @@ 
         // This endpoint doesn't accept body parameters (it's understandable to think it might, so let developers know
         // up-front that it doesn't.)
         $body_params = $request->get_body_params();
-        if (! empty($body_params)) {
+        if ( ! empty($body_params)) {
             throw new RestException(
                 'invalid_field',
                 sprintf(
@@ -567,7 +567,7 @@ 
             $other_obj,
             $relation->get_other_model()->get_this_model_name()
         );
-        $response    = [
+        $response = [
             strtolower($model->get_this_model_name())                       => $this->returnModelObjAsJsonResponse(
                 $model_obj,
                 $request
@@ -587,10 +587,10 @@ 
                 ]
             );
             if ($join_model_obj instanceof EE_Base_Class) {
-                $response['join'][ strtolower($relation->get_join_model()->get_this_model_name()) ] =
+                $response['join'][strtolower($relation->get_join_model()->get_this_model_name())] =
                     $this->returnModelObjAsJsonResponse($join_model_obj, $request);
             } else {
-                $response['join'][ strtolower($relation->get_join_model()->get_this_model_name()) ] = null;
+                $response['join'][strtolower($relation->get_join_model()->get_this_model_name())] = null;
             }
         }
         return $response;
@@ -620,9 +620,9 @@ 
         // Check generic caps. For now, we're only allowing access to this endpoint to full admins.
         Capabilities::verifyAtLeastPartialAccessTo($model, EEM_Base::caps_edit, 'edit');
         $default_cap_to_check_for = EE_Restriction_Generator_Base::get_default_restrictions_cap();
-        if (! current_user_can($default_cap_to_check_for)) {
+        if ( ! current_user_can($default_cap_to_check_for)) {
             throw new RestException(
-                'rest_cannot_edit_' . EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
+                'rest_cannot_edit_'.EEH_Inflector::pluralize_and_lower(($model->get_this_model_name())),
                 sprintf(
                     esc_html__(
                     // @codingStandardsIgnoreStart