eventespresso / event-espresso-core

core/helpers/EEH_Line_Item.helper.php

Indentation +2128 added lines, -2128 removed lines

@@ -21,2132 +21,2132 @@
  */
 class EEH_Line_Item
 {
-    /**
-     * @var EE_Line_Item[]
-    */
-    private static $global_taxes;
-
-
-    /**
-     * 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'      => $items_subtotal instanceof EE_Line_Item
-                    ? count($items_subtotal->children())
-                    : 0,
-                'LIN_total'      => (float) $unit_price * (int) $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_quantity'   => 1,
-                'LIN_is_taxable' => $taxable,
-                'LIN_total'      => (float) $total,
-                'LIN_type'       => EEM_Line_Item::type_line_item,
-                'LIN_parent'     => $parent_line_item->ID(),
-                'LIN_code'       => $code,
-            ]
-        );
-        $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
-     * @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
-    ): ?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);
-        }
-        $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 $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,
-        $qty = 1
-    ) {
-        $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
-                    && (int) $ticket_line_item->OBJ_ID() === (int) $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, $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, $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, $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, $qty = 1)
-    {
-        $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(array(
-            '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_total = 0;
-        $running_pre_tax_total = 0;
-        foreach ($ticket->prices() as $price) {
-            $sign = $price->is_discount() ? -1 : 1;
-            $price_total = $price->is_percent()
-                ? $running_pre_tax_total * $price->amount() / 100
-                : $price->amount() * $qty;
-            if ($price->is_percent()) {
-                $percent = $sign * $price->amount();
-                $unit_price = 0;
-            } else {
-                $percent    = 0;
-                $unit_price = $sign * $price->amount();
-            }
-            $sub_line_item = EE_Line_Item::new_instance(array(
-                'LIN_name'       => $price->name(),
-                'LIN_desc'       => $price->desc(),
-                'LIN_quantity'   => $price->is_percent() ? null : $qty,
-                '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_total += $sign * $price_total;
-            $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
-     * @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, $recalculate_totals = true)
-    {
-        $pre_tax_subtotal = self::get_pre_tax_subtotal($total_line_item);
-        if ($pre_tax_subtotal instanceof EE_Line_Item) {
-            $success = $pre_tax_subtotal->add_child_line_item($item);
-        } else {
-            return false;
-        }
-        if ($recalculate_totals) {
-            $total_line_item->recalculate_total_including_taxes();
-        }
-        return $success;
-    }
-
-
-    /**
-     * cancels an existing ticket line item,
-     * by decrementing it's 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, $qty = 1)
-    {
-        // 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(array(
-                '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_unit_price' => 0, // $ticket_line_item->unit_price()
-                'LIN_quantity'   => $qty,
-                'LIN_is_taxable' => $ticket_line_item->is_taxable(),
-                'LIN_order'      => count($ticket_line_item->children()),
-                'LIN_total'      => 0, // $ticket_line_item->unit_price()
-                '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 it's quantity by 1, and decrementing it's "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, $qty = 1)
-    {
-        // 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)
-    {
-        $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)
-    {
-        $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)
-    {
-        $taxes = $total_line_item->get_child_line_item('taxes');
-        return $taxes ? $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 $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, $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 $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($transaction = null)
-    {
-        $total_line_item = EE_Line_Item::new_instance(array(
-            '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 $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, $transaction = null)
-    {
-        $pre_tax_line_item = EE_Line_Item::new_instance(array(
-            '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 $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, $transaction = null)
-    {
-        $tax_line_item = EE_Line_Item::new_instance(array(
-            '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 $transaction
-     * @param EE_Event       $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, $transaction = null, $event = null)
-    {
-        $event_line_item = EE_Line_Item::new_instance(array(
-            '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 $event
-     * @return string
-     * @throws EE_Error
-     */
-    public static function get_event_code($event)
-    {
-        return 'event-' . ($event instanceof EE_Event ? $event->ID() : '0');
-    }
-
-
-    /**
-     * Gets the event name
-     *
-     * @param EE_Event $event
-     * @return string
-     * @throws EE_Error
-     */
-    public static function get_event_name($event)
-    {
-        return $event instanceof EE_Event
-            ? mb_substr($event->name(), 0, 245)
-            : esc_html__('Event', 'event_espresso');
-    }
-
-
-    /**
-     * Gets the event excerpt
-     *
-     * @param EE_Event $event
-     * @return string
-     * @throws EE_Error
-     */
-    public static function get_event_desc($event)
-    {
-        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)
-    {
-        $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 $grand_total
-     * @param EE_Event     $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 $grand_total, $event)
-    {
-        /** @type EE_Event $event */
-        $event = EEM_Event::instance()->ensure_is_obj($event, true);
-        $event_line_item = null;
-        $found = false;
-        foreach (EEH_Line_Item::get_event_subtotals($grand_total) as $event_line_item) {
-            // default event subtotal, we should only ever find this the first time this method is called
-            if (! $event_line_item->OBJ_ID()) {
-                // let's use this! but first... set the event details
-                EEH_Line_Item::set_event_subtotal_details($event_line_item, $event);
-                $found = true;
-                break;
-            }
-            if ($event_line_item->OBJ_ID() === $event->ID()) {
-                // found existing line item for this event in the cart, so break out of loop and use this one
-                $found = true;
-                break;
-            }
-        }
-        if (! $found) {
-            // there is no event sub-total yet, so add it
-            $pre_tax_subtotal = EEH_Line_Item::get_pre_tax_subtotal($grand_total);
-            // create a new "event" subtotal below that
-            $event_line_item = EEH_Line_Item::create_event_subtotal($pre_tax_subtotal, null, $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       $event
-     * @param EE_Transaction $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,
-        $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, $update_txn_status = false)
-    {
-        $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) {
-            $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 $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($total_line_item)
-    {
-        $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
-     */
-    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'
-            );
-        }
-        do_action('AHEE_log', __FILE__, __FUNCTION__, '');
-
-        // 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 = array($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,
-        $amount,
-        $name = null,
-        $description = null,
-        $code = null,
-        $add_to_existing_line_item = false
-    ) {
-        $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(
-                array(array('LIN_code' => array('!=', $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(array(
-                '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       $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
-     */
-    public static function set_line_items_taxable(
-        EE_Line_Item $line_item,
-        $taxable = true,
-        $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
-     *
-     * @uses  EEH_Line_Item::get_subtotals_of_object_type()
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     */
-    public static function get_event_subtotals(EE_Line_Item $parent_line_item)
-    {
-        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
-     *
-     * @uses  EEH_Line_Item::_get_descendants_by_type_and_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
-     */
-    public static function get_subtotals_of_object_type(EE_Line_Item $parent_line_item, $obj_type = '')
-    {
-        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
-     *
-     * @uses  EEH_Line_Item::get_line_items_of_object_type()
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     */
-    public static function get_ticket_line_items(EE_Line_Item $parent_line_item)
-    {
-        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
-     *
-     * @uses  EEH_Line_Item::_get_descendants_by_type_and_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
-     */
-    public static function get_line_items_of_object_type(EE_Line_Item $parent_line_item, $obj_type = '')
-    {
-        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'
-     *
-     * @uses  EEH_Line_Item::get_descendants_of_type()
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     */
-    public static function get_tax_descendants(EE_Line_Item $parent_line_item)
-    {
-        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
-     *
-     * @uses  EEH_Line_Item::get_descendants_of_type()
-     * @param EE_Line_Item $parent_line_item - the line item to find descendants of
-     * @return EE_Line_Item[]
-     * @throws EE_Error
-     */
-    public static function get_line_item_descendants(EE_Line_Item $parent_line_item)
-    {
-        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
-     *
-     * @uses  EEH_Line_Item::_get_descendants_by_type_and_object_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
-     */
-    public static function get_descendants_of_type(EE_Line_Item $parent_line_item, $line_item_type)
-    {
-        return self::_get_descendants_by_type_and_object_type(
-            $parent_line_item,
-            $line_item_type,
-            null
-        );
-    }
-
-
-    /**
-     * 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
-     */
-    protected static function _get_descendants_by_type_and_object_type(
-        EE_Line_Item $parent_line_item,
-        $line_item_type,
-        $obj_type = null
-    ) {
-        $objects = array();
-        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
-     *
-     * @uses  EEH_Line_Item::_get_descendants_by_type_and_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
-     */
-    public static function get_line_items_by_object_type_and_IDs(
-        EE_Line_Item $parent_line_item,
-        $OBJ_type = '',
-        $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
-     */
-    protected static function _get_descendants_by_object_type_and_object_ID(
-        EE_Line_Item $parent_line_item,
-        $OBJ_type,
-        $OBJ_IDs
-    ) {
-        $objects = array();
-        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
-                    && is_array($OBJ_IDs)
-                    && 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
-     *
-     * @uses  EEH_Line_Item::_get_nearest_descendant()
-     * @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
-     */
-    public static function get_nearest_descendant_of_type(EE_Line_Item $parent_line_item, $type)
-    {
-        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
-     *
-     * @uses  EEH_Line_Item::_get_nearest_descendant()
-     * @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
-     */
-    public static function get_nearest_descendant_having_code(EE_Line_Item $parent_line_item, $code)
-    {
-        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 string       $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, $search_field, $value)
-    {
-        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
-     * @return void
-     * @throws EE_Error
-     */
-    public static function visualize(EE_Line_Item $line_item, $indentation = 0)
-    {
-        $new_line = defined('EE_TESTS_DIR') ? "\n" : '<br />';
-        echo $new_line;
-        if (! $indentation) {
-            echo $new_line;
-        }
-        echo str_repeat('. ', $indentation);
-        $breakdown = '';
-        if ($line_item->is_line_item() || $line_item->is_sub_line_item() || $line_item->isSubTax()) {
-            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()}";
-        if ($breakdown) {
-            echo " ( {$breakdown} )";
-        }
-        if ($line_item->is_taxable()) {
-            echo '  * taxable';
-        }
-        if ($line_item->children()) {
-            foreach ($line_item->children() as $child) {
-                self::visualize($child, $indentation + 1);
-            }
-        }
-        if (! $indentation) {
-            echo $new_line . $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,
-        $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) {
-                        $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 {
-                            // its 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
-    ) {
-        static $final_prices_per_ticket_line_item = array();
-        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, $registrations)
-    {
-        $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, $registrations)
-    {
-        $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)
-    {
-        $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
-        ) {
-            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)
-    {
-        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 of 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
-     * @since 4.9.79.p
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    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   $VID:$
-     */
-    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 *************************************** */
-    /**
-     * @deprecated
-     * @param EE_Line_Item $total_line_item
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function get_items_subtotal(EE_Line_Item $total_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);
-    }
-
-
-    /**
-     * @deprecated
-     * @param EE_Transaction $transaction
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function create_default_total_line_item($transaction = null)
-    {
-        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);
-    }
-
-
-    /**
-     * @deprecated
-     * @param EE_Line_Item   $total_line_item
-     * @param EE_Transaction $transaction
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function create_default_tickets_subtotal(EE_Line_Item $total_line_item, $transaction = null)
-    {
-        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);
-    }
-
-
-    /**
-     * @deprecated
-     * @param EE_Line_Item   $total_line_item
-     * @param EE_Transaction $transaction
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function create_default_taxes_subtotal(EE_Line_Item $total_line_item, $transaction = null)
-    {
-        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);
-    }
-
-
-    /**
-     * @deprecated
-     * @param EE_Line_Item   $total_line_item
-     * @param EE_Transaction $transaction
-     * @return EE_Line_Item
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws InvalidInterfaceException
-     * @throws ReflectionException
-     */
-    public static function create_default_event_subtotal(EE_Line_Item $total_line_item, $transaction = null)
-    {
-        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[]
+	 */
+	private static $global_taxes;
+
+
+	/**
+	 * 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'      => $items_subtotal instanceof EE_Line_Item
+					? count($items_subtotal->children())
+					: 0,
+				'LIN_total'      => (float) $unit_price * (int) $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_quantity'   => 1,
+				'LIN_is_taxable' => $taxable,
+				'LIN_total'      => (float) $total,
+				'LIN_type'       => EEM_Line_Item::type_line_item,
+				'LIN_parent'     => $parent_line_item->ID(),
+				'LIN_code'       => $code,
+			]
+		);
+		$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
+	 * @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
+	): ?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);
+		}
+		$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 $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,
+		$qty = 1
+	) {
+		$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
+					&& (int) $ticket_line_item->OBJ_ID() === (int) $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, $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, $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, $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, $qty = 1)
+	{
+		$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(array(
+			'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_total = 0;
+		$running_pre_tax_total = 0;
+		foreach ($ticket->prices() as $price) {
+			$sign = $price->is_discount() ? -1 : 1;
+			$price_total = $price->is_percent()
+				? $running_pre_tax_total * $price->amount() / 100
+				: $price->amount() * $qty;
+			if ($price->is_percent()) {
+				$percent = $sign * $price->amount();
+				$unit_price = 0;
+			} else {
+				$percent    = 0;
+				$unit_price = $sign * $price->amount();
+			}
+			$sub_line_item = EE_Line_Item::new_instance(array(
+				'LIN_name'       => $price->name(),
+				'LIN_desc'       => $price->desc(),
+				'LIN_quantity'   => $price->is_percent() ? null : $qty,
+				'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_total += $sign * $price_total;
+			$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
+	 * @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, $recalculate_totals = true)
+	{
+		$pre_tax_subtotal = self::get_pre_tax_subtotal($total_line_item);
+		if ($pre_tax_subtotal instanceof EE_Line_Item) {
+			$success = $pre_tax_subtotal->add_child_line_item($item);
+		} else {
+			return false;
+		}
+		if ($recalculate_totals) {
+			$total_line_item->recalculate_total_including_taxes();
+		}
+		return $success;
+	}
+
+
+	/**
+	 * cancels an existing ticket line item,
+	 * by decrementing it's 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, $qty = 1)
+	{
+		// 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(array(
+				'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_unit_price' => 0, // $ticket_line_item->unit_price()
+				'LIN_quantity'   => $qty,
+				'LIN_is_taxable' => $ticket_line_item->is_taxable(),
+				'LIN_order'      => count($ticket_line_item->children()),
+				'LIN_total'      => 0, // $ticket_line_item->unit_price()
+				'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 it's quantity by 1, and decrementing it's "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, $qty = 1)
+	{
+		// 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)
+	{
+		$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)
+	{
+		$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)
+	{
+		$taxes = $total_line_item->get_child_line_item('taxes');
+		return $taxes ? $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 $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, $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 $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($transaction = null)
+	{
+		$total_line_item = EE_Line_Item::new_instance(array(
+			'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 $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, $transaction = null)
+	{
+		$pre_tax_line_item = EE_Line_Item::new_instance(array(
+			'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 $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, $transaction = null)
+	{
+		$tax_line_item = EE_Line_Item::new_instance(array(
+			'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 $transaction
+	 * @param EE_Event       $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, $transaction = null, $event = null)
+	{
+		$event_line_item = EE_Line_Item::new_instance(array(
+			'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 $event
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public static function get_event_code($event)
+	{
+		return 'event-' . ($event instanceof EE_Event ? $event->ID() : '0');
+	}
+
+
+	/**
+	 * Gets the event name
+	 *
+	 * @param EE_Event $event
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public static function get_event_name($event)
+	{
+		return $event instanceof EE_Event
+			? mb_substr($event->name(), 0, 245)
+			: esc_html__('Event', 'event_espresso');
+	}
+
+
+	/**
+	 * Gets the event excerpt
+	 *
+	 * @param EE_Event $event
+	 * @return string
+	 * @throws EE_Error
+	 */
+	public static function get_event_desc($event)
+	{
+		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)
+	{
+		$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 $grand_total
+	 * @param EE_Event     $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 $grand_total, $event)
+	{
+		/** @type EE_Event $event */
+		$event = EEM_Event::instance()->ensure_is_obj($event, true);
+		$event_line_item = null;
+		$found = false;
+		foreach (EEH_Line_Item::get_event_subtotals($grand_total) as $event_line_item) {
+			// default event subtotal, we should only ever find this the first time this method is called
+			if (! $event_line_item->OBJ_ID()) {
+				// let's use this! but first... set the event details
+				EEH_Line_Item::set_event_subtotal_details($event_line_item, $event);
+				$found = true;
+				break;
+			}
+			if ($event_line_item->OBJ_ID() === $event->ID()) {
+				// found existing line item for this event in the cart, so break out of loop and use this one
+				$found = true;
+				break;
+			}
+		}
+		if (! $found) {
+			// there is no event sub-total yet, so add it
+			$pre_tax_subtotal = EEH_Line_Item::get_pre_tax_subtotal($grand_total);
+			// create a new "event" subtotal below that
+			$event_line_item = EEH_Line_Item::create_event_subtotal($pre_tax_subtotal, null, $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       $event
+	 * @param EE_Transaction $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,
+		$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, $update_txn_status = false)
+	{
+		$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) {
+			$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 $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($total_line_item)
+	{
+		$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
+	 */
+	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'
+			);
+		}
+		do_action('AHEE_log', __FILE__, __FUNCTION__, '');
+
+		// 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 = array($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,
+		$amount,
+		$name = null,
+		$description = null,
+		$code = null,
+		$add_to_existing_line_item = false
+	) {
+		$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(
+				array(array('LIN_code' => array('!=', $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(array(
+				'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       $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
+	 */
+	public static function set_line_items_taxable(
+		EE_Line_Item $line_item,
+		$taxable = true,
+		$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
+	 *
+	 * @uses  EEH_Line_Item::get_subtotals_of_object_type()
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 */
+	public static function get_event_subtotals(EE_Line_Item $parent_line_item)
+	{
+		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
+	 *
+	 * @uses  EEH_Line_Item::_get_descendants_by_type_and_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
+	 */
+	public static function get_subtotals_of_object_type(EE_Line_Item $parent_line_item, $obj_type = '')
+	{
+		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
+	 *
+	 * @uses  EEH_Line_Item::get_line_items_of_object_type()
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 */
+	public static function get_ticket_line_items(EE_Line_Item $parent_line_item)
+	{
+		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
+	 *
+	 * @uses  EEH_Line_Item::_get_descendants_by_type_and_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
+	 */
+	public static function get_line_items_of_object_type(EE_Line_Item $parent_line_item, $obj_type = '')
+	{
+		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'
+	 *
+	 * @uses  EEH_Line_Item::get_descendants_of_type()
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 */
+	public static function get_tax_descendants(EE_Line_Item $parent_line_item)
+	{
+		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
+	 *
+	 * @uses  EEH_Line_Item::get_descendants_of_type()
+	 * @param EE_Line_Item $parent_line_item - the line item to find descendants of
+	 * @return EE_Line_Item[]
+	 * @throws EE_Error
+	 */
+	public static function get_line_item_descendants(EE_Line_Item $parent_line_item)
+	{
+		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
+	 *
+	 * @uses  EEH_Line_Item::_get_descendants_by_type_and_object_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
+	 */
+	public static function get_descendants_of_type(EE_Line_Item $parent_line_item, $line_item_type)
+	{
+		return self::_get_descendants_by_type_and_object_type(
+			$parent_line_item,
+			$line_item_type,
+			null
+		);
+	}
+
+
+	/**
+	 * 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
+	 */
+	protected static function _get_descendants_by_type_and_object_type(
+		EE_Line_Item $parent_line_item,
+		$line_item_type,
+		$obj_type = null
+	) {
+		$objects = array();
+		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
+	 *
+	 * @uses  EEH_Line_Item::_get_descendants_by_type_and_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
+	 */
+	public static function get_line_items_by_object_type_and_IDs(
+		EE_Line_Item $parent_line_item,
+		$OBJ_type = '',
+		$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
+	 */
+	protected static function _get_descendants_by_object_type_and_object_ID(
+		EE_Line_Item $parent_line_item,
+		$OBJ_type,
+		$OBJ_IDs
+	) {
+		$objects = array();
+		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
+					&& is_array($OBJ_IDs)
+					&& 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
+	 *
+	 * @uses  EEH_Line_Item::_get_nearest_descendant()
+	 * @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
+	 */
+	public static function get_nearest_descendant_of_type(EE_Line_Item $parent_line_item, $type)
+	{
+		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
+	 *
+	 * @uses  EEH_Line_Item::_get_nearest_descendant()
+	 * @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
+	 */
+	public static function get_nearest_descendant_having_code(EE_Line_Item $parent_line_item, $code)
+	{
+		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 string       $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, $search_field, $value)
+	{
+		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
+	 * @return void
+	 * @throws EE_Error
+	 */
+	public static function visualize(EE_Line_Item $line_item, $indentation = 0)
+	{
+		$new_line = defined('EE_TESTS_DIR') ? "\n" : '<br />';
+		echo $new_line;
+		if (! $indentation) {
+			echo $new_line;
+		}
+		echo str_repeat('. ', $indentation);
+		$breakdown = '';
+		if ($line_item->is_line_item() || $line_item->is_sub_line_item() || $line_item->isSubTax()) {
+			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()}";
+		if ($breakdown) {
+			echo " ( {$breakdown} )";
+		}
+		if ($line_item->is_taxable()) {
+			echo '  * taxable';
+		}
+		if ($line_item->children()) {
+			foreach ($line_item->children() as $child) {
+				self::visualize($child, $indentation + 1);
+			}
+		}
+		if (! $indentation) {
+			echo $new_line . $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,
+		$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) {
+						$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 {
+							// its 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
+	) {
+		static $final_prices_per_ticket_line_item = array();
+		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, $registrations)
+	{
+		$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, $registrations)
+	{
+		$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)
+	{
+		$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
+		) {
+			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)
+	{
+		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 of 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
+	 * @since 4.9.79.p
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	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   $VID:$
+	 */
+	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 *************************************** */
+	/**
+	 * @deprecated
+	 * @param EE_Line_Item $total_line_item
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function get_items_subtotal(EE_Line_Item $total_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);
+	}
+
+
+	/**
+	 * @deprecated
+	 * @param EE_Transaction $transaction
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function create_default_total_line_item($transaction = null)
+	{
+		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);
+	}
+
+
+	/**
+	 * @deprecated
+	 * @param EE_Line_Item   $total_line_item
+	 * @param EE_Transaction $transaction
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function create_default_tickets_subtotal(EE_Line_Item $total_line_item, $transaction = null)
+	{
+		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);
+	}
+
+
+	/**
+	 * @deprecated
+	 * @param EE_Line_Item   $total_line_item
+	 * @param EE_Transaction $transaction
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function create_default_taxes_subtotal(EE_Line_Item $total_line_item, $transaction = null)
+	{
+		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);
+	}
+
+
+	/**
+	 * @deprecated
+	 * @param EE_Line_Item   $total_line_item
+	 * @param EE_Transaction $transaction
+	 * @return EE_Line_Item
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws InvalidInterfaceException
+	 * @throws ReflectionException
+	 */
+	public static function create_default_event_subtotal(EE_Line_Item $total_line_item, $transaction = null)
+	{
+		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 +43 added lines, -43 removed lines

@@ -75,12 +75,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;
     }
 
@@ -133,7 +133,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 @@ 
         EE_Ticket $ticket,
         int $qty = 1
     ): ?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);
         }
         $total_line_item->recalculate_total_including_taxes();
@@ -237,7 +237,7 @@ 
      */
     public static function increment_quantity(EE_Line_Item $line_item, $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);
@@ -266,7 +266,7 @@ 
      */
     public static function decrement_quantity(EE_Line_Item $line_item, $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);
@@ -295,7 +295,7 @@ 
      */
     public static function update_quantity(EE_Line_Item $line_item, $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();
@@ -336,7 +336,7 @@ 
         // add $ticket to cart
         $line_item = EE_Line_Item::new_instance(array(
             '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(),
@@ -350,7 +350,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')
             );
@@ -502,7 +502,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_unit_price' => 0, // $ticket_line_item->unit_price()
                 'LIN_quantity'   => $qty,
@@ -565,7 +565,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) {
@@ -771,7 +771,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(
             'FHEE__EEH_Line_Item__create_taxes_subtotal__tax_line_item',
@@ -827,7 +827,7 @@ 
      */
     public static function get_event_code($event)
     {
-        return 'event-' . ($event instanceof EE_Event ? $event->ID() : '0');
+        return 'event-'.($event instanceof EE_Event ? $event->ID() : '0');
     }
 
 
@@ -876,7 +876,7 @@ 
     public static function get_event_line_item_for_ticket(EE_Line_Item $grand_total, EE_Ticket $ticket)
     {
         $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'),
@@ -885,7 +885,7 @@ 
             );
         }
         $event = $first_datetime->event();
-        if (! $event instanceof EE_Event) {
+        if ( ! $event instanceof EE_Event) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -897,7 +897,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__(
@@ -933,7 +933,7 @@ 
         $found = false;
         foreach (EEH_Line_Item::get_event_subtotals($grand_total) as $event_line_item) {
             // default event subtotal, we should only ever find this the first time this method is called
-            if (! $event_line_item->OBJ_ID()) {
+            if ( ! $event_line_item->OBJ_ID()) {
                 // let's use this! but first... set the event details
                 EEH_Line_Item::set_event_subtotal_details($event_line_item, $event);
                 $found = true;
@@ -945,7 +945,7 @@ 
                 break;
             }
         }
-        if (! $found) {
+        if ( ! $found) {
             // there is no event sub-total yet, so add it
             $pre_tax_subtotal = EEH_Line_Item::get_pre_tax_subtotal($grand_total);
             // create a new "event" subtotal below that
@@ -1025,7 +1025,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',
@@ -1072,7 +1072,7 @@ 
     public static function ensure_taxes_applied($total_line_item)
     {
         $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();
@@ -1139,7 +1139,7 @@ 
         do_action('AHEE_log', __FILE__, __FUNCTION__, '');
 
         // 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 = array($line_item_codes);
         }
@@ -1246,7 +1246,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) {
@@ -1615,7 +1615,7 @@ 
     {
         $new_line = defined('EE_TESTS_DIR') ? "\n" : '<br />';
         echo $new_line;
-        if (! $indentation) {
+        if ( ! $indentation) {
             echo $new_line;
         }
         echo str_repeat('. ', $indentation);
@@ -1641,8 +1641,8 @@ 
                 self::visualize($child, $indentation + 1);
             }
         }
-        if (! $indentation) {
-            echo $new_line . $new_line;
+        if ( ! $indentation) {
+            echo $new_line.$new_line;
         }
     }
 
@@ -1720,8 +1720,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;
 
@@ -1729,7 +1729,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 {
@@ -1740,18 +1740,18 @@ 
                                 $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
+                            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
+                                $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;
@@ -1771,12 +1771,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];
                             }
                         }
                     }
@@ -1803,14 +1803,14 @@ 
         EE_Line_Item $ticket_line_item
     ) {
         static $final_prices_per_ticket_line_item = array();
-        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(
+        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() ];
+        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__(
@@ -1821,7 +1821,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/EE_Capabilities.core.php

Indentation +1396 added lines, -1396 removed lines

@@ -13,991 +13,991 @@ 
  */
 final class EE_Capabilities extends EE_Base
 {
-    const ROLE_ADMINISTRATOR        = 'administrator';
-
-    const ROLE_EVENTS_ADMINISTRATOR = 'ee_events_administrator';
-
-
-    /**
-     * the name of the wp option used to store caps previously initialized
-     */
-    const option_name = 'ee_caps_initialized';
-
-    /**
-     * instance of EE_Capabilities object
-     *
-     * @var EE_Capabilities
-     */
-    private static $_instance;
-
-
-    /**
-     * This is a map of caps that correspond to a default WP_Role.
-     * Array is indexed by Role and values are ee capabilities.
-     *
-     * @since 4.5.0
-     *
-     * @var array
-     */
-    private $capabilities_map = [];
-
-    /**
-     * This used to hold an array of EE_Meta_Capability_Map objects
-     * that define the granular capabilities mapped to for a user depending on context.
-     *
-     * @var EE_Meta_Capability_Map[]
-     */
-    private $_meta_caps = [];
-
-    /**
-     * The internal $capabilities_map needs to be initialized before it can be used.
-     * This flag tracks whether that has happened or not.
-     * But for this to work, we need three states to indicate:
-     *      initialization has not occurred at all
-     *      initialization has started but is not complete
-     *      initialization is complete
-     * The reason this is needed is because the addCaps() method
-     * normally requires the $capabilities_map to be initialized,
-     * but is also used during the initialization process.
-     * So:
-     *      If initialized === null, init_caps() will be called before any other methods will run.
-     *      If initialized === false, then init_caps() is in the process of running it's logic.
-     *      If initialized === true, then init_caps() has completed the initialization process.
-     *
-     * @var boolean|null $initialized
-     */
-    private $initialized;
-
-    /**
-     * @var boolean $reset
-     */
-    private $reset = false;
-
-
-    /**
-     * singleton method used to instantiate class object
-     *
-     * @return EE_Capabilities
-     * @since 4.5.0
-     *
-     */
-    public static function instance(): EE_Capabilities
-    {
-        // check if instantiated, and if not do so.
-        if (! self::$_instance instanceof EE_Capabilities) {
-            self::$_instance = new self();
-        }
-        return self::$_instance;
-    }
-
-
-    /**
-     * private constructor
-     *
-     * @since 4.5.0
-     */
-    private function __construct()
-    {
-    }
-
-
-    /**
-     * This delays the initialization of the capabilities class until EE_System core is loaded and ready.
-     *
-     * @param bool $reset allows for resetting the default capabilities saved on roles.  Note that this doesn't
-     *                    actually REMOVE any capabilities from existing roles, it just resaves defaults roles and
-     *                    ensures that they are up to date.
-     *
-     * @since 4.5.0
-     * @return bool
-     * @throws EE_Error
-     */
-    public function init_caps(?bool $reset = false): bool
-    {
-        if (! EE_Maintenance_Mode::instance()->models_can_query()) {
-            return false;
-        }
-        $this->reset = filter_var($reset, FILTER_VALIDATE_BOOLEAN);
-        // if reset, then completely delete the cache option and clear the $capabilities_map property.
-        if ($this->reset) {
-            $this->initialized      = null;
-            $this->capabilities_map = [];
-            delete_option(self::option_name);
-        }
-        if ($this->initialized === null) {
-            $this->initialized = false;
-            do_action(
-                'AHEE__EE_Capabilities__init_caps__before_initialization',
-                $this->reset
-            );
-            $this->addCaps($this->_init_caps_map());
-            $this->_set_meta_caps();
-            do_action(
-                'AHEE__EE_Capabilities__init_caps__after_initialization',
-                $this->capabilities_map
-            );
-            $this->initialized = true;
-        }
-        // reset $this->reset so that it's not stuck on true if init_caps() gets called again
-        $this->reset = false;
-        return true;
-    }
-
-
-    /**
-     * This sets the meta caps property.
-     *
-     * @return void
-     * @throws EE_Error
-     * @since 4.5.0
-     */
-    private function _set_meta_caps()
-    {
-        // get default meta caps and filter the returned array
-        $this->_meta_caps = apply_filters(
-            'FHEE__EE_Capabilities___set_meta_caps__meta_caps',
-            $this->_get_default_meta_caps_array()
-        );
-        // add filter for map_meta_caps but only if models can query.
-        if (! has_filter('map_meta_cap', [$this, 'map_meta_caps'])) {
-            add_filter('map_meta_cap', [$this, 'map_meta_caps'], 10, 4);
-        }
-    }
-
-
-    /**
-     * This builds and returns the default meta_caps array only once.
-     *
-     * @return array
-     * @throws EE_Error
-     * @since  4.8.28.rc.012
-     */
-    private function _get_default_meta_caps_array(): array
-    {
-        static $default_meta_caps = [];
-        // make sure we're only ever initializing the default _meta_caps array once if it's empty.
-        if (empty($default_meta_caps)) {
-            $default_meta_caps = [
-                // edits
-                new EE_Meta_Capability_Map_Edit(
-                    'ee_edit_event',
-                    ['Event', 'ee_edit_published_events', 'ee_edit_others_events', 'ee_edit_private_events']
-                ),
-                new EE_Meta_Capability_Map_Edit(
-                    'ee_edit_venue',
-                    ['Venue', 'ee_edit_published_venues', 'ee_edit_others_venues', 'ee_edit_private_venues']
-                ),
-                new EE_Meta_Capability_Map_Edit(
-                    'ee_edit_registration',
-                    ['Registration', '', 'ee_edit_others_registrations', '']
-                ),
-                new EE_Meta_Capability_Map_Edit(
-                    'ee_edit_checkin',
-                    ['Registration', '', 'ee_edit_others_checkins', '']
-                ),
-                new EE_Meta_Capability_Map_Messages_Cap(
-                    'ee_edit_message',
-                    ['Message_Template_Group', '', 'ee_edit_others_messages', 'ee_edit_global_messages']
-                ),
-                new EE_Meta_Capability_Map_Edit(
-                    'ee_edit_default_ticket',
-                    ['Ticket', '', 'ee_edit_others_default_tickets', '']
-                ),
-                new EE_Meta_Capability_Map_Registration_Form_Cap(
-                    'ee_edit_question',
-                    ['Question', '', '', 'ee_edit_system_questions']
-                ),
-                new EE_Meta_Capability_Map_Registration_Form_Cap(
-                    'ee_edit_question_group',
-                    ['Question_Group', '', '', 'ee_edit_system_question_groups']
-                ),
-                new EE_Meta_Capability_Map_Edit(
-                    'ee_edit_payment_method',
-                    ['Payment_Method', '', 'ee_edit_others_payment_methods', '']
-                ),
-                // reads
-                new EE_Meta_Capability_Map_Read(
-                    'ee_read_event',
-                    ['Event', '', 'ee_read_others_events', 'ee_read_private_events']
-                ),
-                new EE_Meta_Capability_Map_Read(
-                    'ee_read_venue',
-                    ['Venue', '', 'ee_read_others_venues', 'ee_read_private_venues']
-                ),
-                new EE_Meta_Capability_Map_Read(
-                    'ee_read_registration',
-                    ['Registration', '', 'ee_read_others_registrations', '']
-                ),
-                new EE_Meta_Capability_Map_Read(
-                    'ee_read_checkin',
-                    ['Registration', '', 'ee_read_others_checkins', '']
-                ),
-                new EE_Meta_Capability_Map_Messages_Cap(
-                    'ee_read_message',
-                    ['Message_Template_Group', '', 'ee_read_others_messages', 'ee_read_global_messages']
-                ),
-                new EE_Meta_Capability_Map_Read(
-                    'ee_read_default_ticket',
-                    ['Ticket', '', 'ee_read_others_default_tickets', '']
-                ),
-                new EE_Meta_Capability_Map_Read(
-                    'ee_read_payment_method',
-                    ['Payment_Method', '', 'ee_read_others_payment_methods', '']
-                ),
-                // deletes
-                new EE_Meta_Capability_Map_Delete(
-                    'ee_delete_event',
-                    [
-                        'Event',
-                        'ee_delete_published_events',
-                        'ee_delete_others_events',
-                        'ee_delete_private_events',
-                    ]
-                ),
-                new EE_Meta_Capability_Map_Delete(
-                    'ee_delete_venue',
-                    [
-                        'Venue',
-                        'ee_delete_published_venues',
-                        'ee_delete_others_venues',
-                        'ee_delete_private_venues',
-                    ]
-                ),
-                new EE_Meta_Capability_Map_Delete(
-                    'ee_delete_registration',
-                    ['Registration', '', 'ee_delete_others_registrations', '']
-                ),
-                new EE_Meta_Capability_Map_Delete(
-                    'ee_delete_checkin',
-                    ['Registration', '', 'ee_delete_others_checkins', '']
-                ),
-                new EE_Meta_Capability_Map_Messages_Cap(
-                    'ee_delete_message',
-                    ['Message_Template_Group', '', 'ee_delete_others_messages', 'ee_delete_global_messages']
-                ),
-                new EE_Meta_Capability_Map_Delete(
-                    'ee_delete_default_ticket',
-                    ['Ticket', '', 'ee_delete_others_default_tickets', '']
-                ),
-                new EE_Meta_Capability_Map_Registration_Form_Cap(
-                    'ee_delete_question',
-                    ['Question', '', '', 'delete_system_questions']
-                ),
-                new EE_Meta_Capability_Map_Registration_Form_Cap(
-                    'ee_delete_question_group',
-                    ['Question_Group', '', '', 'delete_system_question_groups']
-                ),
-                new EE_Meta_Capability_Map_Delete(
-                    'ee_delete_payment_method',
-                    ['Payment_Method', '', 'ee_delete_others_payment_methods', '']
-                ),
-            ];
-        }
-        return $default_meta_caps;
-    }
-
-
-    /**
-     * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
-     * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
-     *
-     * The actual logic is carried out by implementer classes in their definition of _map_meta_caps.
-     *
-     * @param array  $caps    actual users capabilities
-     * @param string $cap     initial capability name that is being checked (the "map" key)
-     * @param int    $user_id The user id
-     * @param array  $args    Adds context to the cap. Typically the object ID.
-     * @return array actual users capabilities
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @since 4.5.0
-     * @see   wp-includes/capabilities.php
-     *
-     */
-    public function map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
-    {
-        if (did_action('AHEE__EE_System__load_espresso_addons__complete')) {
-            // loop through our _meta_caps array
-            foreach ($this->_meta_caps as $meta_map) {
-                if (! $meta_map instanceof EE_Meta_Capability_Map) {
-                    continue;
-                }
-                // don't load models if there is no object ID in the args
-                if (! empty($args[0])) {
-                    $meta_map->ensure_is_model();
-                }
-                $caps = $meta_map->map_meta_caps($caps, $cap, $user_id, $args);
-            }
-        }
-        return $caps;
-    }
-
-
-    /**
-     * This sets up and returns the initial capabilities map for Event Espresso
-     * Note this array is filtered.
-     * It is assumed that all available EE capabilities are assigned to the administrator role.
-     *
-     * @return array
-     * @since 4.5.0
-     *
-     */
-    private function _init_caps_map(): array
-    {
-        return apply_filters(
-            'FHEE__EE_Capabilities__init_caps_map__caps',
-            [
-                EE_Capabilities::ROLE_ADMINISTRATOR        => [
-                    // basic access
-                    'ee_read_ee',
-                    // gateways
-                    /**
-                     * note that with payment method capabilities, although we've implemented
-                     * capability mapping which will be used for accessing payment methods owned by
-                     * other users.  This is not fully implemented yet in the payment method ui.
-                     * Currently only the "plural" caps are in active use.
-                     * (Specific payment method caps are in use as well).
-                     **/
-                    'ee_manage_gateways',
-                    'ee_read_payment_methods',
-                    'ee_read_others_payment_methods',
-                    'ee_edit_payment_methods',
-                    'ee_edit_others_payment_methods',
-                    'ee_delete_payment_methods',
-                    // events
-                    'ee_publish_events',
-                    'ee_read_private_events',
-                    'ee_read_others_events',
-                    'ee_read_events',
-                    'ee_edit_events',
-                    'ee_edit_published_events',
-                    'ee_edit_others_events',
-                    'ee_edit_private_events',
-                    'ee_delete_published_events',
-                    'ee_delete_private_events',
-                    'ee_delete_events',
-                    'ee_delete_others_events',
-                    // event categories
-                    'ee_manage_event_categories',
-                    'ee_edit_event_category',
-                    'ee_delete_event_category',
-                    'ee_assign_event_category',
-                    // venues
-                    'ee_publish_venues',
-                    'ee_read_venues',
-                    'ee_read_others_venues',
-                    'ee_read_private_venues',
-                    'ee_edit_venues',
-                    'ee_edit_others_venues',
-                    'ee_edit_published_venues',
-                    'ee_edit_private_venues',
-                    'ee_delete_venues',
-                    'ee_delete_others_venues',
-                    'ee_delete_private_venues',
-                    'ee_delete_published_venues',
-                    // venue categories
-                    'ee_manage_venue_categories',
-                    'ee_edit_venue_category',
-                    'ee_delete_venue_category',
-                    'ee_assign_venue_category',
-                    // contacts
-                    'ee_read_contacts',
-                    'ee_edit_contacts',
-                    'ee_delete_contacts',
-                    // registrations
-                    'ee_read_registrations',
-                    'ee_read_others_registrations',
-                    'ee_edit_registrations',
-                    'ee_edit_others_registrations',
-                    'ee_delete_registrations',
-                    'ee_delete_others_registrations',
-                    // checkins
-                    'ee_read_others_checkins',
-                    'ee_read_checkins',
-                    'ee_edit_checkins',
-                    'ee_edit_others_checkins',
-                    'ee_delete_checkins',
-                    'ee_delete_others_checkins',
-                    // transactions && payments
-                    'ee_read_transaction',
-                    'ee_read_transactions',
-                    'ee_edit_payments',
-                    'ee_delete_payments',
-                    // messages
-                    'ee_read_messages',
-                    'ee_read_others_messages',
-                    'ee_read_global_messages',
-                    'ee_edit_global_messages',
-                    'ee_edit_messages',
-                    'ee_edit_others_messages',
-                    'ee_delete_messages',
-                    'ee_delete_others_messages',
-                    'ee_delete_global_messages',
-                    'ee_send_message',
-                    // tickets
-                    'ee_read_default_tickets',
-                    'ee_read_others_default_tickets',
-                    'ee_edit_default_tickets',
-                    'ee_edit_others_default_tickets',
-                    'ee_delete_default_tickets',
-                    'ee_delete_others_default_tickets',
-                    // prices
-                    'ee_edit_default_price',
-                    'ee_edit_default_prices',
-                    'ee_delete_default_price',
-                    'ee_delete_default_prices',
-                    'ee_edit_default_price_type',
-                    'ee_edit_default_price_types',
-                    'ee_delete_default_price_type',
-                    'ee_delete_default_price_types',
-                    'ee_read_default_prices',
-                    'ee_read_default_price_types',
-                    // registration form
-                    'ee_edit_questions',
-                    'ee_edit_system_questions',
-                    'ee_read_questions',
-                    'ee_delete_questions',
-                    'ee_edit_question_groups',
-                    'ee_read_question_groups',
-                    'ee_edit_system_question_groups',
-                    'ee_delete_question_groups',
-                    // event_type taxonomy
-                    'ee_assign_event_type',
-                    'ee_manage_event_types',
-                    'ee_edit_event_type',
-                    'ee_delete_event_type',
-                ],
-                EE_Capabilities::ROLE_EVENTS_ADMINISTRATOR => [
-                    // core wp caps
-                    'read',
-                    'read_private_pages',
-                    'read_private_posts',
-                    'edit_users',
-                    'edit_posts',
-                    'edit_pages',
-                    'edit_published_posts',
-                    'edit_published_pages',
-                    'edit_private_pages',
-                    'edit_private_posts',
-                    'edit_others_posts',
-                    'edit_others_pages',
-                    'publish_posts',
-                    'publish_pages',
-                    'delete_posts',
-                    'delete_pages',
-                    'delete_private_pages',
-                    'delete_private_posts',
-                    'delete_published_pages',
-                    'delete_published_posts',
-                    'delete_others_posts',
-                    'delete_others_pages',
-                    'manage_categories',
-                    'manage_links',
-                    'moderate_comments',
-                    'unfiltered_html',
-                    'upload_files',
-                    'export',
-                    'import',
-                    'list_users',
-                    'level_1', // required if user with this role shows up in author dropdowns
-                    // basic ee access
-                    'ee_read_ee',
-                    // events
-                    'ee_publish_events',
-                    'ee_read_private_events',
-                    'ee_read_others_events',
-                    'ee_read_event',
-                    'ee_read_events',
-                    'ee_edit_event',
-                    'ee_edit_events',
-                    'ee_edit_published_events',
-                    'ee_edit_others_events',
-                    'ee_edit_private_events',
-                    'ee_delete_published_events',
-                    'ee_delete_private_events',
-                    'ee_delete_event',
-                    'ee_delete_events',
-                    'ee_delete_others_events',
-                    // event categories
-                    'ee_manage_event_categories',
-                    'ee_edit_event_category',
-                    'ee_delete_event_category',
-                    'ee_assign_event_category',
-                    // venues
-                    'ee_publish_venues',
-                    'ee_read_venue',
-                    'ee_read_venues',
-                    'ee_read_others_venues',
-                    'ee_read_private_venues',
-                    'ee_edit_venue',
-                    'ee_edit_venues',
-                    'ee_edit_others_venues',
-                    'ee_edit_published_venues',
-                    'ee_edit_private_venues',
-                    'ee_delete_venue',
-                    'ee_delete_venues',
-                    'ee_delete_others_venues',
-                    'ee_delete_private_venues',
-                    'ee_delete_published_venues',
-                    // venue categories
-                    'ee_manage_venue_categories',
-                    'ee_edit_venue_category',
-                    'ee_delete_venue_category',
-                    'ee_assign_venue_category',
-                    // contacts
-                    'ee_read_contacts',
-                    'ee_edit_contacts',
-                    'ee_delete_contacts',
-                    // registrations
-                    'ee_read_registrations',
-                    'ee_read_others_registrations',
-                    'ee_edit_registration',
-                    'ee_edit_registrations',
-                    'ee_edit_others_registrations',
-                    'ee_delete_registration',
-                    'ee_delete_registrations',
-                    'ee_delete_others_registrations',
-                    // checkins
-                    'ee_read_others_checkins',
-                    'ee_read_checkins',
-                    'ee_edit_checkins',
-                    'ee_edit_others_checkins',
-                    'ee_delete_checkins',
-                    'ee_delete_others_checkins',
-                    // transactions && payments
-                    'ee_read_transaction',
-                    'ee_read_transactions',
-                    'ee_edit_payments',
-                    'ee_delete_payments',
-                    // messages
-                    'ee_read_messages',
-                    'ee_read_others_messages',
-                    'ee_read_global_messages',
-                    'ee_edit_global_messages',
-                    'ee_edit_messages',
-                    'ee_edit_others_messages',
-                    'ee_delete_messages',
-                    'ee_delete_others_messages',
-                    'ee_delete_global_messages',
-                    'ee_send_message',
-                    // tickets
-                    'ee_read_default_tickets',
-                    'ee_read_others_default_tickets',
-                    'ee_edit_default_tickets',
-                    'ee_edit_others_default_tickets',
-                    'ee_delete_default_tickets',
-                    'ee_delete_others_default_tickets',
-                    // prices
-                    'ee_edit_default_price',
-                    'ee_edit_default_prices',
-                    'ee_delete_default_price',
-                    'ee_delete_default_prices',
-                    'ee_edit_default_price_type',
-                    'ee_edit_default_price_types',
-                    'ee_delete_default_price_type',
-                    'ee_delete_default_price_types',
-                    'ee_read_default_prices',
-                    'ee_read_default_price_types',
-                    // registration form
-                    'ee_edit_questions',
-                    'ee_edit_system_questions',
-                    'ee_read_questions',
-                    'ee_delete_questions',
-                    'ee_edit_question_groups',
-                    'ee_read_question_groups',
-                    'ee_edit_system_question_groups',
-                    'ee_delete_question_groups',
-                    // event_type taxonomy
-                    'ee_assign_event_type',
-                    'ee_manage_event_types',
-                    'ee_edit_event_type',
-                    'ee_delete_event_type',
-                ],
-            ]
-        );
-    }
-
-
-    /**
-     * @return bool
-     * @throws EE_Error
-     */
-    private function setupCapabilitiesMap(): bool
-    {
-        // if the initialization process hasn't even started, then we need to call init_caps()
-        if ($this->initialized === null) {
-            return $this->init_caps();
-        }
-        // unless resetting, get caps from db if we haven't already
-        $this->capabilities_map = $this->reset || ! empty($this->capabilities_map)
-            ? $this->capabilities_map
-            : get_option(self::option_name, []);
-        return true;
-    }
-
-
-    /**
-     * @param bool $update
-     * @return bool
-     */
-    private function updateCapabilitiesMap(bool $update = true): bool
-    {
-        return $update && update_option(self::option_name, $this->capabilities_map);
-    }
-
-
-    /**
-     * Adds capabilities to roles.
-     *
-     * @param array $capabilities_to_add array of capabilities to add, indexed by roles.
-     *                                   Note that this should ONLY be called on activation hook
-     *                                   otherwise the caps will be added on every request.
-     * @return bool
-     * @throws EE_Error
-     * @since 4.9.42
-     */
-    public function addCaps(array $capabilities_to_add): bool
-    {
-        // don't do anything if the capabilities map can not be initialized
-        if (! $this->setupCapabilitiesMap()) {
-            return false;
-        }
-        // and filter the array so others can get in on the fun during resets
-        $capabilities_to_add     = apply_filters(
-            'FHEE__EE_Capabilities__addCaps__capabilities_to_add',
-            $capabilities_to_add,
-            $this->reset,
-            $this->capabilities_map
-        );
-        $update_capabilities_map = false;
-        // if not reset, see what caps are new for each role. if they're new, add them.
-        foreach ($capabilities_to_add as $role => $caps_for_role) {
-            if (is_array($caps_for_role)) {
-                foreach ($caps_for_role as $cap) {
-                    if (
-                        ! $this->capHasBeenAddedToRole($role, $cap)
-                        && $this->add_cap_to_role($role, $cap, true, false)
-                    ) {
-                        $update_capabilities_map = true;
-                    }
-                }
-            }
-        }
-        // now let's just save the cap that has been set but only if there's been a change.
-        $updated = $this->updateCapabilitiesMap($update_capabilities_map);
-        $this->flushWpUser($updated);
-        do_action('AHEE__EE_Capabilities__addCaps__complete', $this->capabilities_map, $updated);
-        return $updated;
-    }
-
-
-    /**
-     * Loops through the capabilities map and removes the role caps specified by the incoming array
-     *
-     * @param array $caps_map map of capabilities to be removed (indexed by roles)
-     * @return bool
-     * @throws EE_Error
-     */
-    public function removeCaps(array $caps_map): bool
-    {
-        // don't do anything if the capabilities map can not be initialized
-        if (! $this->setupCapabilitiesMap()) {
-            return false;
-        }
-        $update_capabilities_map = false;
-        foreach ($caps_map as $role => $caps_for_role) {
-            if (is_array($caps_for_role)) {
-                foreach ($caps_for_role as $cap) {
-                    if (
-                        $this->capHasBeenAddedToRole($role, $cap)
-                        && $this->remove_cap_from_role($role, $cap, false)
-                    ) {
-                        $update_capabilities_map = true;
-                    }
-                }
-            }
-        }
-        // maybe resave the caps
-        $updated = $this->updateCapabilitiesMap($update_capabilities_map);
-        $this->flushWpUser($updated);
-        return $updated;
-    }
-
-
-    /**
-     * This ensures that the WP User object cached on the $current_user global in WP has the latest capabilities from
-     * the roles on that user.
-     *
-     * @param bool $flush Default is to flush the WP_User object.  If false, then this method effectively does nothing.
-     */
-    private function flushWpUser(bool $flush = true)
-    {
-        if ($flush) {
-            $user = wp_get_current_user();
-            if ($user instanceof WP_User) {
-                $user->get_role_caps();
-            }
-        }
-    }
-
-
-    /**
-     * This method sets a capability on a role.  Note this should only be done on activation, or if you have something
-     * specific to prevent the cap from being added on every page load (adding caps are persistent to the db). Note.
-     * this is a wrapper for $wp_role->add_cap()
-     *
-     * @param string|WP_Role $role  A WordPress role the capability is being added to
-     * @param string         $cap   The capability being added to the role
-     * @param bool           $grant Whether to grant access to this cap on this role.
-     * @param bool           $update_capabilities_map
-     * @return bool
-     * @throws EE_Error
-     * @see   wp-includes/capabilities.php
-     * @since 4.5.0
-     */
-    public function add_cap_to_role(
-        $role,
-        string $cap,
-        bool $grant = true,
-        bool $update_capabilities_map = true
-    ): bool {
-        // capture incoming value for $role because we may need it to create a new WP_Role
-        $orig_role = $role;
-        $role      = $role instanceof WP_Role ? $role : get_role($role);
-        // if the role isn't available then we create it.
-        if (! $role instanceof WP_Role) {
-            // if a plugin wants to create a specific role name then they should create the role before
-            // EE_Capabilities does.  Otherwise this function will create the role name from the slug:
-            // - removes any `ee_` namespacing from the start of the slug.
-            // - replaces `_` with ` ` (empty space).
-            // - sentence case on the resulting string.
-            $role_label = ucwords(str_replace(['ee_', '_'], ['', ' '], $orig_role));
-            $role       = add_role($orig_role, $role_label);
-        }
-        if ($role instanceof WP_Role) {
-            // don't do anything if the capabilities map can not be initialized
-            if (! $this->setupCapabilitiesMap()) {
-                return false;
-            }
-            if (! $this->capHasBeenAddedToRole($role->name, $cap)) {
-                $role->add_cap($cap, $grant);
-                $this->capabilities_map[ $role->name ][] = $cap;
-                $this->updateCapabilitiesMap($update_capabilities_map);
-                return true;
-            }
-        }
-        return false;
-    }
-
-
-    /**
-     * Functions similarly to add_cap_to_role except removes cap from given role.
-     * Wrapper for $wp_role->remove_cap()
-     *
-     * @param string|WP_Role $role A WordPress role the capability is being removed from.
-     * @param string         $cap  The capability being removed
-     * @param bool           $update_capabilities_map
-     * @return bool
-     * @throws EE_Error
-     * @since 4.5.0
-     * @see   wp-includes/capabilities.php
-     */
-    public function remove_cap_from_role($role, string $cap, bool $update_capabilities_map = true): bool
-    {
-        // don't do anything if the capabilities map can not be initialized
-        if (! $this->setupCapabilitiesMap()) {
-            return false;
-        }
-
-        $role = $role instanceof WP_Role ? $role : get_role($role);
-        if ($role instanceof WP_Role && $index = $this->capHasBeenAddedToRole($role->name, $cap, true)) {
-            $role->remove_cap($cap);
-            unset($this->capabilities_map[ $role->name ][ $index ]);
-            $this->updateCapabilitiesMap($update_capabilities_map);
-            return true;
-        }
-        return false;
-    }
-
-
-    /**
-     * @param string $role_name
-     * @param string $cap
-     * @param bool   $get_index
-     * @return bool|int|string
-     */
-    private function capHasBeenAddedToRole(string $role_name = '', string $cap = '', bool $get_index = false)
-    {
-        if (
-            isset($this->capabilities_map[ $role_name ])
-            && ($index = array_search($cap, $this->capabilities_map[ $role_name ], true)) !== false
-        ) {
-            return $get_index ? $index : true;
-        }
-        return false;
-    }
-
-
-    /**
-     * Wrapper for the native WP current_user_can() method.
-     * This is provided as a handy method for a couple things:
-     * 1. Using the context string it allows for targeted filtering by addons for a specific check (without having to
-     * write those filters wherever current_user_can is called).
-     * 2. Explicit passing of $id from a given context ( useful in the cases of map_meta_cap filters )
-     *
-     * @param string $cap     The cap being checked.
-     * @param string $context The context where the current_user_can is being called from.
-     * @param int    $id      Optional. Id for item where current_user_can is being called from (used in map_meta_cap()
-     *                        filters.
-     *
-     * @return bool  Whether user can or not.
-     * @since 4.5.0
-     *
-     */
-    public function current_user_can(string $cap, string $context, int $id = 0): bool
-    {
-        // apply filters (both a global on just the cap, and context specific.  Global overrides context specific)
-        $filtered_cap = apply_filters('FHEE__EE_Capabilities__current_user_can__cap__' . $context, $cap, $id);
-        $filtered_cap = apply_filters(
-            'FHEE__EE_Capabilities__current_user_can__cap',
-            $filtered_cap,
-            $context,
-            $cap,
-            $id
-        );
-        return ! empty($id)
-            ? current_user_can($filtered_cap, $id)
-            : current_user_can($filtered_cap);
-    }
-
-
-    /**
-     * This is a wrapper for the WP user_can() function and follows the same style as the other wrappers in this class.
-     *
-     * @param int|WP_User $user    Either the user_id or a WP_User object
-     * @param string      $cap     The capability string being checked
-     * @param string      $context The context where the user_can is being called from (used in filters).
-     * @param int         $id      Optional. Id for item where user_can is being called from ( used in map_meta_cap()
-     *                             filters)
-     *
-     * @return bool Whether user can or not.
-     */
-    public function user_can($user, string $cap, string $context, int $id = 0): bool
-    {
-        // apply filters (both a global on just the cap, and context specific.  Global overrides context specific)
-        $filtered_cap = apply_filters('FHEE__EE_Capabilities__user_can__cap__' . $context, $cap, $user, $id);
-        $filtered_cap = apply_filters(
-            'FHEE__EE_Capabilities__user_can__cap',
-            $filtered_cap,
-            $context,
-            $cap,
-            $user,
-            $id
-        );
-        return ! empty($id)
-            ? user_can($user, $filtered_cap, $id)
-            : user_can($user, $filtered_cap);
-    }
-
-
-    /**
-     * Wrapper for the native WP current_user_can_for_blog() method.
-     * This is provided as a handy method for a couple things:
-     * 1. Using the context string it allows for targeted filtering by addons for a specific check (without having to
-     * write those filters wherever current_user_can is called).
-     * 2. Explicit passing of $id from a given context ( useful in the cases of map_meta_cap filters )
-     *
-     * @param int    $blog_id The blog id that is being checked for.
-     * @param string $cap     The cap being checked.
-     * @param string $context The context where the current_user_can is being called from.
-     * @param int    $id      Optional. Id for item where current_user_can is being called from (used in map_meta_cap()
-     *                        filters.
-     *
-     * @return bool  Whether user can or not.
-     * @since 4.5.0
-     *
-     */
-    public function current_user_can_for_blog(int $blog_id, string $cap, string $context, int $id = 0): bool
-    {
-        $user_can = ! empty($id)
-            ? current_user_can_for_blog($blog_id, $cap, $id)
-            : current_user_can($blog_id, $cap);
-        // apply filters (both a global on just the cap, and context specific.  Global overrides context specific)
-        $user_can = apply_filters(
-            'FHEE__EE_Capabilities__current_user_can_for_blog__user_can__' . $context,
-            $user_can,
-            $blog_id,
-            $cap,
-            $id
-        );
-        return apply_filters(
-            'FHEE__EE_Capabilities__current_user_can_for_blog__user_can',
-            $user_can,
-            $context,
-            $blog_id,
-            $cap,
-            $id
-        );
-    }
-
-
-    /**
-     * This helper method just returns an array of registered EE capabilities.
-     *
-     * @param string|null $role If empty then the entire role/capability map is returned.
-     *                          Otherwise just the capabilities for the given role are returned.
-     * @return array
-     * @throws EE_Error
-     * @since 4.5.0
-     */
-    public function get_ee_capabilities(?string $role = EE_Capabilities::ROLE_ADMINISTRATOR): array
-    {
-        if (! $this->initialized) {
-            $this->init_caps();
-        }
-        if ($role === '') {
-            return $this->capabilities_map;
-        }
-        return $this->capabilities_map[ $role ] ?? [];
-    }
-
-
-    /**
-     * @param bool  $reset      If you need to reset Event Espresso's capabilities,
-     *                          then please use the init_caps() method with the "$reset" parameter set to "true"
-     * @param array $caps_map   Optional.
-     *                          Can be used to send a custom map of roles and capabilities for setting them up.
-     *                          Note that this should ONLY be called on activation hook or some other one-time
-     *                          task otherwise the caps will be added on every request.
-     * @return void
-     * @throws EE_Error
-     * @deprecated 4.9.42
-     */
-    public function init_role_caps(bool $reset = false, array $caps_map = [])
-    {
-        // If this method is called directly and reset is set as 'true',
-        // then display a doing it wrong notice, because we want resets to go through init_caps()
-        // to guarantee that everything is set up correctly.
-        // This prevents the capabilities map getting reset incorrectly by direct calls to this method.
-        if ($reset) {
-            EE_Error::doing_it_wrong(
-                __METHOD__,
-                sprintf(
-                    esc_html__(
-                        'The "%1$s" parameter for the "%2$s" method is deprecated. If you need to reset Event Espresso\'s capabilities, then please use the "%3$s" method with the "%1$s" parameter set to "%4$s".',
-                        'event_espresso'
-                    ),
-                    '$reset',
-                    __METHOD__ . '()',
-                    'EE_Capabilities::init_caps()',
-                    'true'
-                ),
-                '4.9.42',
-                '5.0.0'
-            );
-        }
-        $this->addCaps($caps_map);
-    }
+	const ROLE_ADMINISTRATOR        = 'administrator';
+
+	const ROLE_EVENTS_ADMINISTRATOR = 'ee_events_administrator';
+
+
+	/**
+	 * the name of the wp option used to store caps previously initialized
+	 */
+	const option_name = 'ee_caps_initialized';
+
+	/**
+	 * instance of EE_Capabilities object
+	 *
+	 * @var EE_Capabilities
+	 */
+	private static $_instance;
+
+
+	/**
+	 * This is a map of caps that correspond to a default WP_Role.
+	 * Array is indexed by Role and values are ee capabilities.
+	 *
+	 * @since 4.5.0
+	 *
+	 * @var array
+	 */
+	private $capabilities_map = [];
+
+	/**
+	 * This used to hold an array of EE_Meta_Capability_Map objects
+	 * that define the granular capabilities mapped to for a user depending on context.
+	 *
+	 * @var EE_Meta_Capability_Map[]
+	 */
+	private $_meta_caps = [];
+
+	/**
+	 * The internal $capabilities_map needs to be initialized before it can be used.
+	 * This flag tracks whether that has happened or not.
+	 * But for this to work, we need three states to indicate:
+	 *      initialization has not occurred at all
+	 *      initialization has started but is not complete
+	 *      initialization is complete
+	 * The reason this is needed is because the addCaps() method
+	 * normally requires the $capabilities_map to be initialized,
+	 * but is also used during the initialization process.
+	 * So:
+	 *      If initialized === null, init_caps() will be called before any other methods will run.
+	 *      If initialized === false, then init_caps() is in the process of running it's logic.
+	 *      If initialized === true, then init_caps() has completed the initialization process.
+	 *
+	 * @var boolean|null $initialized
+	 */
+	private $initialized;
+
+	/**
+	 * @var boolean $reset
+	 */
+	private $reset = false;
+
+
+	/**
+	 * singleton method used to instantiate class object
+	 *
+	 * @return EE_Capabilities
+	 * @since 4.5.0
+	 *
+	 */
+	public static function instance(): EE_Capabilities
+	{
+		// check if instantiated, and if not do so.
+		if (! self::$_instance instanceof EE_Capabilities) {
+			self::$_instance = new self();
+		}
+		return self::$_instance;
+	}
+
+
+	/**
+	 * private constructor
+	 *
+	 * @since 4.5.0
+	 */
+	private function __construct()
+	{
+	}
+
+
+	/**
+	 * This delays the initialization of the capabilities class until EE_System core is loaded and ready.
+	 *
+	 * @param bool $reset allows for resetting the default capabilities saved on roles.  Note that this doesn't
+	 *                    actually REMOVE any capabilities from existing roles, it just resaves defaults roles and
+	 *                    ensures that they are up to date.
+	 *
+	 * @since 4.5.0
+	 * @return bool
+	 * @throws EE_Error
+	 */
+	public function init_caps(?bool $reset = false): bool
+	{
+		if (! EE_Maintenance_Mode::instance()->models_can_query()) {
+			return false;
+		}
+		$this->reset = filter_var($reset, FILTER_VALIDATE_BOOLEAN);
+		// if reset, then completely delete the cache option and clear the $capabilities_map property.
+		if ($this->reset) {
+			$this->initialized      = null;
+			$this->capabilities_map = [];
+			delete_option(self::option_name);
+		}
+		if ($this->initialized === null) {
+			$this->initialized = false;
+			do_action(
+				'AHEE__EE_Capabilities__init_caps__before_initialization',
+				$this->reset
+			);
+			$this->addCaps($this->_init_caps_map());
+			$this->_set_meta_caps();
+			do_action(
+				'AHEE__EE_Capabilities__init_caps__after_initialization',
+				$this->capabilities_map
+			);
+			$this->initialized = true;
+		}
+		// reset $this->reset so that it's not stuck on true if init_caps() gets called again
+		$this->reset = false;
+		return true;
+	}
+
+
+	/**
+	 * This sets the meta caps property.
+	 *
+	 * @return void
+	 * @throws EE_Error
+	 * @since 4.5.0
+	 */
+	private function _set_meta_caps()
+	{
+		// get default meta caps and filter the returned array
+		$this->_meta_caps = apply_filters(
+			'FHEE__EE_Capabilities___set_meta_caps__meta_caps',
+			$this->_get_default_meta_caps_array()
+		);
+		// add filter for map_meta_caps but only if models can query.
+		if (! has_filter('map_meta_cap', [$this, 'map_meta_caps'])) {
+			add_filter('map_meta_cap', [$this, 'map_meta_caps'], 10, 4);
+		}
+	}
+
+
+	/**
+	 * This builds and returns the default meta_caps array only once.
+	 *
+	 * @return array
+	 * @throws EE_Error
+	 * @since  4.8.28.rc.012
+	 */
+	private function _get_default_meta_caps_array(): array
+	{
+		static $default_meta_caps = [];
+		// make sure we're only ever initializing the default _meta_caps array once if it's empty.
+		if (empty($default_meta_caps)) {
+			$default_meta_caps = [
+				// edits
+				new EE_Meta_Capability_Map_Edit(
+					'ee_edit_event',
+					['Event', 'ee_edit_published_events', 'ee_edit_others_events', 'ee_edit_private_events']
+				),
+				new EE_Meta_Capability_Map_Edit(
+					'ee_edit_venue',
+					['Venue', 'ee_edit_published_venues', 'ee_edit_others_venues', 'ee_edit_private_venues']
+				),
+				new EE_Meta_Capability_Map_Edit(
+					'ee_edit_registration',
+					['Registration', '', 'ee_edit_others_registrations', '']
+				),
+				new EE_Meta_Capability_Map_Edit(
+					'ee_edit_checkin',
+					['Registration', '', 'ee_edit_others_checkins', '']
+				),
+				new EE_Meta_Capability_Map_Messages_Cap(
+					'ee_edit_message',
+					['Message_Template_Group', '', 'ee_edit_others_messages', 'ee_edit_global_messages']
+				),
+				new EE_Meta_Capability_Map_Edit(
+					'ee_edit_default_ticket',
+					['Ticket', '', 'ee_edit_others_default_tickets', '']
+				),
+				new EE_Meta_Capability_Map_Registration_Form_Cap(
+					'ee_edit_question',
+					['Question', '', '', 'ee_edit_system_questions']
+				),
+				new EE_Meta_Capability_Map_Registration_Form_Cap(
+					'ee_edit_question_group',
+					['Question_Group', '', '', 'ee_edit_system_question_groups']
+				),
+				new EE_Meta_Capability_Map_Edit(
+					'ee_edit_payment_method',
+					['Payment_Method', '', 'ee_edit_others_payment_methods', '']
+				),
+				// reads
+				new EE_Meta_Capability_Map_Read(
+					'ee_read_event',
+					['Event', '', 'ee_read_others_events', 'ee_read_private_events']
+				),
+				new EE_Meta_Capability_Map_Read(
+					'ee_read_venue',
+					['Venue', '', 'ee_read_others_venues', 'ee_read_private_venues']
+				),
+				new EE_Meta_Capability_Map_Read(
+					'ee_read_registration',
+					['Registration', '', 'ee_read_others_registrations', '']
+				),
+				new EE_Meta_Capability_Map_Read(
+					'ee_read_checkin',
+					['Registration', '', 'ee_read_others_checkins', '']
+				),
+				new EE_Meta_Capability_Map_Messages_Cap(
+					'ee_read_message',
+					['Message_Template_Group', '', 'ee_read_others_messages', 'ee_read_global_messages']
+				),
+				new EE_Meta_Capability_Map_Read(
+					'ee_read_default_ticket',
+					['Ticket', '', 'ee_read_others_default_tickets', '']
+				),
+				new EE_Meta_Capability_Map_Read(
+					'ee_read_payment_method',
+					['Payment_Method', '', 'ee_read_others_payment_methods', '']
+				),
+				// deletes
+				new EE_Meta_Capability_Map_Delete(
+					'ee_delete_event',
+					[
+						'Event',
+						'ee_delete_published_events',
+						'ee_delete_others_events',
+						'ee_delete_private_events',
+					]
+				),
+				new EE_Meta_Capability_Map_Delete(
+					'ee_delete_venue',
+					[
+						'Venue',
+						'ee_delete_published_venues',
+						'ee_delete_others_venues',
+						'ee_delete_private_venues',
+					]
+				),
+				new EE_Meta_Capability_Map_Delete(
+					'ee_delete_registration',
+					['Registration', '', 'ee_delete_others_registrations', '']
+				),
+				new EE_Meta_Capability_Map_Delete(
+					'ee_delete_checkin',
+					['Registration', '', 'ee_delete_others_checkins', '']
+				),
+				new EE_Meta_Capability_Map_Messages_Cap(
+					'ee_delete_message',
+					['Message_Template_Group', '', 'ee_delete_others_messages', 'ee_delete_global_messages']
+				),
+				new EE_Meta_Capability_Map_Delete(
+					'ee_delete_default_ticket',
+					['Ticket', '', 'ee_delete_others_default_tickets', '']
+				),
+				new EE_Meta_Capability_Map_Registration_Form_Cap(
+					'ee_delete_question',
+					['Question', '', '', 'delete_system_questions']
+				),
+				new EE_Meta_Capability_Map_Registration_Form_Cap(
+					'ee_delete_question_group',
+					['Question_Group', '', '', 'delete_system_question_groups']
+				),
+				new EE_Meta_Capability_Map_Delete(
+					'ee_delete_payment_method',
+					['Payment_Method', '', 'ee_delete_others_payment_methods', '']
+				),
+			];
+		}
+		return $default_meta_caps;
+	}
+
+
+	/**
+	 * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
+	 * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
+	 *
+	 * The actual logic is carried out by implementer classes in their definition of _map_meta_caps.
+	 *
+	 * @param array  $caps    actual users capabilities
+	 * @param string $cap     initial capability name that is being checked (the "map" key)
+	 * @param int    $user_id The user id
+	 * @param array  $args    Adds context to the cap. Typically the object ID.
+	 * @return array actual users capabilities
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @since 4.5.0
+	 * @see   wp-includes/capabilities.php
+	 *
+	 */
+	public function map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
+	{
+		if (did_action('AHEE__EE_System__load_espresso_addons__complete')) {
+			// loop through our _meta_caps array
+			foreach ($this->_meta_caps as $meta_map) {
+				if (! $meta_map instanceof EE_Meta_Capability_Map) {
+					continue;
+				}
+				// don't load models if there is no object ID in the args
+				if (! empty($args[0])) {
+					$meta_map->ensure_is_model();
+				}
+				$caps = $meta_map->map_meta_caps($caps, $cap, $user_id, $args);
+			}
+		}
+		return $caps;
+	}
+
+
+	/**
+	 * This sets up and returns the initial capabilities map for Event Espresso
+	 * Note this array is filtered.
+	 * It is assumed that all available EE capabilities are assigned to the administrator role.
+	 *
+	 * @return array
+	 * @since 4.5.0
+	 *
+	 */
+	private function _init_caps_map(): array
+	{
+		return apply_filters(
+			'FHEE__EE_Capabilities__init_caps_map__caps',
+			[
+				EE_Capabilities::ROLE_ADMINISTRATOR        => [
+					// basic access
+					'ee_read_ee',
+					// gateways
+					/**
+					 * note that with payment method capabilities, although we've implemented
+					 * capability mapping which will be used for accessing payment methods owned by
+					 * other users.  This is not fully implemented yet in the payment method ui.
+					 * Currently only the "plural" caps are in active use.
+					 * (Specific payment method caps are in use as well).
+					 **/
+					'ee_manage_gateways',
+					'ee_read_payment_methods',
+					'ee_read_others_payment_methods',
+					'ee_edit_payment_methods',
+					'ee_edit_others_payment_methods',
+					'ee_delete_payment_methods',
+					// events
+					'ee_publish_events',
+					'ee_read_private_events',
+					'ee_read_others_events',
+					'ee_read_events',
+					'ee_edit_events',
+					'ee_edit_published_events',
+					'ee_edit_others_events',
+					'ee_edit_private_events',
+					'ee_delete_published_events',
+					'ee_delete_private_events',
+					'ee_delete_events',
+					'ee_delete_others_events',
+					// event categories
+					'ee_manage_event_categories',
+					'ee_edit_event_category',
+					'ee_delete_event_category',
+					'ee_assign_event_category',
+					// venues
+					'ee_publish_venues',
+					'ee_read_venues',
+					'ee_read_others_venues',
+					'ee_read_private_venues',
+					'ee_edit_venues',
+					'ee_edit_others_venues',
+					'ee_edit_published_venues',
+					'ee_edit_private_venues',
+					'ee_delete_venues',
+					'ee_delete_others_venues',
+					'ee_delete_private_venues',
+					'ee_delete_published_venues',
+					// venue categories
+					'ee_manage_venue_categories',
+					'ee_edit_venue_category',
+					'ee_delete_venue_category',
+					'ee_assign_venue_category',
+					// contacts
+					'ee_read_contacts',
+					'ee_edit_contacts',
+					'ee_delete_contacts',
+					// registrations
+					'ee_read_registrations',
+					'ee_read_others_registrations',
+					'ee_edit_registrations',
+					'ee_edit_others_registrations',
+					'ee_delete_registrations',
+					'ee_delete_others_registrations',
+					// checkins
+					'ee_read_others_checkins',
+					'ee_read_checkins',
+					'ee_edit_checkins',
+					'ee_edit_others_checkins',
+					'ee_delete_checkins',
+					'ee_delete_others_checkins',
+					// transactions && payments
+					'ee_read_transaction',
+					'ee_read_transactions',
+					'ee_edit_payments',
+					'ee_delete_payments',
+					// messages
+					'ee_read_messages',
+					'ee_read_others_messages',
+					'ee_read_global_messages',
+					'ee_edit_global_messages',
+					'ee_edit_messages',
+					'ee_edit_others_messages',
+					'ee_delete_messages',
+					'ee_delete_others_messages',
+					'ee_delete_global_messages',
+					'ee_send_message',
+					// tickets
+					'ee_read_default_tickets',
+					'ee_read_others_default_tickets',
+					'ee_edit_default_tickets',
+					'ee_edit_others_default_tickets',
+					'ee_delete_default_tickets',
+					'ee_delete_others_default_tickets',
+					// prices
+					'ee_edit_default_price',
+					'ee_edit_default_prices',
+					'ee_delete_default_price',
+					'ee_delete_default_prices',
+					'ee_edit_default_price_type',
+					'ee_edit_default_price_types',
+					'ee_delete_default_price_type',
+					'ee_delete_default_price_types',
+					'ee_read_default_prices',
+					'ee_read_default_price_types',
+					// registration form
+					'ee_edit_questions',
+					'ee_edit_system_questions',
+					'ee_read_questions',
+					'ee_delete_questions',
+					'ee_edit_question_groups',
+					'ee_read_question_groups',
+					'ee_edit_system_question_groups',
+					'ee_delete_question_groups',
+					// event_type taxonomy
+					'ee_assign_event_type',
+					'ee_manage_event_types',
+					'ee_edit_event_type',
+					'ee_delete_event_type',
+				],
+				EE_Capabilities::ROLE_EVENTS_ADMINISTRATOR => [
+					// core wp caps
+					'read',
+					'read_private_pages',
+					'read_private_posts',
+					'edit_users',
+					'edit_posts',
+					'edit_pages',
+					'edit_published_posts',
+					'edit_published_pages',
+					'edit_private_pages',
+					'edit_private_posts',
+					'edit_others_posts',
+					'edit_others_pages',
+					'publish_posts',
+					'publish_pages',
+					'delete_posts',
+					'delete_pages',
+					'delete_private_pages',
+					'delete_private_posts',
+					'delete_published_pages',
+					'delete_published_posts',
+					'delete_others_posts',
+					'delete_others_pages',
+					'manage_categories',
+					'manage_links',
+					'moderate_comments',
+					'unfiltered_html',
+					'upload_files',
+					'export',
+					'import',
+					'list_users',
+					'level_1', // required if user with this role shows up in author dropdowns
+					// basic ee access
+					'ee_read_ee',
+					// events
+					'ee_publish_events',
+					'ee_read_private_events',
+					'ee_read_others_events',
+					'ee_read_event',
+					'ee_read_events',
+					'ee_edit_event',
+					'ee_edit_events',
+					'ee_edit_published_events',
+					'ee_edit_others_events',
+					'ee_edit_private_events',
+					'ee_delete_published_events',
+					'ee_delete_private_events',
+					'ee_delete_event',
+					'ee_delete_events',
+					'ee_delete_others_events',
+					// event categories
+					'ee_manage_event_categories',
+					'ee_edit_event_category',
+					'ee_delete_event_category',
+					'ee_assign_event_category',
+					// venues
+					'ee_publish_venues',
+					'ee_read_venue',
+					'ee_read_venues',
+					'ee_read_others_venues',
+					'ee_read_private_venues',
+					'ee_edit_venue',
+					'ee_edit_venues',
+					'ee_edit_others_venues',
+					'ee_edit_published_venues',
+					'ee_edit_private_venues',
+					'ee_delete_venue',
+					'ee_delete_venues',
+					'ee_delete_others_venues',
+					'ee_delete_private_venues',
+					'ee_delete_published_venues',
+					// venue categories
+					'ee_manage_venue_categories',
+					'ee_edit_venue_category',
+					'ee_delete_venue_category',
+					'ee_assign_venue_category',
+					// contacts
+					'ee_read_contacts',
+					'ee_edit_contacts',
+					'ee_delete_contacts',
+					// registrations
+					'ee_read_registrations',
+					'ee_read_others_registrations',
+					'ee_edit_registration',
+					'ee_edit_registrations',
+					'ee_edit_others_registrations',
+					'ee_delete_registration',
+					'ee_delete_registrations',
+					'ee_delete_others_registrations',
+					// checkins
+					'ee_read_others_checkins',
+					'ee_read_checkins',
+					'ee_edit_checkins',
+					'ee_edit_others_checkins',
+					'ee_delete_checkins',
+					'ee_delete_others_checkins',
+					// transactions && payments
+					'ee_read_transaction',
+					'ee_read_transactions',
+					'ee_edit_payments',
+					'ee_delete_payments',
+					// messages
+					'ee_read_messages',
+					'ee_read_others_messages',
+					'ee_read_global_messages',
+					'ee_edit_global_messages',
+					'ee_edit_messages',
+					'ee_edit_others_messages',
+					'ee_delete_messages',
+					'ee_delete_others_messages',
+					'ee_delete_global_messages',
+					'ee_send_message',
+					// tickets
+					'ee_read_default_tickets',
+					'ee_read_others_default_tickets',
+					'ee_edit_default_tickets',
+					'ee_edit_others_default_tickets',
+					'ee_delete_default_tickets',
+					'ee_delete_others_default_tickets',
+					// prices
+					'ee_edit_default_price',
+					'ee_edit_default_prices',
+					'ee_delete_default_price',
+					'ee_delete_default_prices',
+					'ee_edit_default_price_type',
+					'ee_edit_default_price_types',
+					'ee_delete_default_price_type',
+					'ee_delete_default_price_types',
+					'ee_read_default_prices',
+					'ee_read_default_price_types',
+					// registration form
+					'ee_edit_questions',
+					'ee_edit_system_questions',
+					'ee_read_questions',
+					'ee_delete_questions',
+					'ee_edit_question_groups',
+					'ee_read_question_groups',
+					'ee_edit_system_question_groups',
+					'ee_delete_question_groups',
+					// event_type taxonomy
+					'ee_assign_event_type',
+					'ee_manage_event_types',
+					'ee_edit_event_type',
+					'ee_delete_event_type',
+				],
+			]
+		);
+	}
+
+
+	/**
+	 * @return bool
+	 * @throws EE_Error
+	 */
+	private function setupCapabilitiesMap(): bool
+	{
+		// if the initialization process hasn't even started, then we need to call init_caps()
+		if ($this->initialized === null) {
+			return $this->init_caps();
+		}
+		// unless resetting, get caps from db if we haven't already
+		$this->capabilities_map = $this->reset || ! empty($this->capabilities_map)
+			? $this->capabilities_map
+			: get_option(self::option_name, []);
+		return true;
+	}
+
+
+	/**
+	 * @param bool $update
+	 * @return bool
+	 */
+	private function updateCapabilitiesMap(bool $update = true): bool
+	{
+		return $update && update_option(self::option_name, $this->capabilities_map);
+	}
+
+
+	/**
+	 * Adds capabilities to roles.
+	 *
+	 * @param array $capabilities_to_add array of capabilities to add, indexed by roles.
+	 *                                   Note that this should ONLY be called on activation hook
+	 *                                   otherwise the caps will be added on every request.
+	 * @return bool
+	 * @throws EE_Error
+	 * @since 4.9.42
+	 */
+	public function addCaps(array $capabilities_to_add): bool
+	{
+		// don't do anything if the capabilities map can not be initialized
+		if (! $this->setupCapabilitiesMap()) {
+			return false;
+		}
+		// and filter the array so others can get in on the fun during resets
+		$capabilities_to_add     = apply_filters(
+			'FHEE__EE_Capabilities__addCaps__capabilities_to_add',
+			$capabilities_to_add,
+			$this->reset,
+			$this->capabilities_map
+		);
+		$update_capabilities_map = false;
+		// if not reset, see what caps are new for each role. if they're new, add them.
+		foreach ($capabilities_to_add as $role => $caps_for_role) {
+			if (is_array($caps_for_role)) {
+				foreach ($caps_for_role as $cap) {
+					if (
+						! $this->capHasBeenAddedToRole($role, $cap)
+						&& $this->add_cap_to_role($role, $cap, true, false)
+					) {
+						$update_capabilities_map = true;
+					}
+				}
+			}
+		}
+		// now let's just save the cap that has been set but only if there's been a change.
+		$updated = $this->updateCapabilitiesMap($update_capabilities_map);
+		$this->flushWpUser($updated);
+		do_action('AHEE__EE_Capabilities__addCaps__complete', $this->capabilities_map, $updated);
+		return $updated;
+	}
+
+
+	/**
+	 * Loops through the capabilities map and removes the role caps specified by the incoming array
+	 *
+	 * @param array $caps_map map of capabilities to be removed (indexed by roles)
+	 * @return bool
+	 * @throws EE_Error
+	 */
+	public function removeCaps(array $caps_map): bool
+	{
+		// don't do anything if the capabilities map can not be initialized
+		if (! $this->setupCapabilitiesMap()) {
+			return false;
+		}
+		$update_capabilities_map = false;
+		foreach ($caps_map as $role => $caps_for_role) {
+			if (is_array($caps_for_role)) {
+				foreach ($caps_for_role as $cap) {
+					if (
+						$this->capHasBeenAddedToRole($role, $cap)
+						&& $this->remove_cap_from_role($role, $cap, false)
+					) {
+						$update_capabilities_map = true;
+					}
+				}
+			}
+		}
+		// maybe resave the caps
+		$updated = $this->updateCapabilitiesMap($update_capabilities_map);
+		$this->flushWpUser($updated);
+		return $updated;
+	}
+
+
+	/**
+	 * This ensures that the WP User object cached on the $current_user global in WP has the latest capabilities from
+	 * the roles on that user.
+	 *
+	 * @param bool $flush Default is to flush the WP_User object.  If false, then this method effectively does nothing.
+	 */
+	private function flushWpUser(bool $flush = true)
+	{
+		if ($flush) {
+			$user = wp_get_current_user();
+			if ($user instanceof WP_User) {
+				$user->get_role_caps();
+			}
+		}
+	}
+
+
+	/**
+	 * This method sets a capability on a role.  Note this should only be done on activation, or if you have something
+	 * specific to prevent the cap from being added on every page load (adding caps are persistent to the db). Note.
+	 * this is a wrapper for $wp_role->add_cap()
+	 *
+	 * @param string|WP_Role $role  A WordPress role the capability is being added to
+	 * @param string         $cap   The capability being added to the role
+	 * @param bool           $grant Whether to grant access to this cap on this role.
+	 * @param bool           $update_capabilities_map
+	 * @return bool
+	 * @throws EE_Error
+	 * @see   wp-includes/capabilities.php
+	 * @since 4.5.0
+	 */
+	public function add_cap_to_role(
+		$role,
+		string $cap,
+		bool $grant = true,
+		bool $update_capabilities_map = true
+	): bool {
+		// capture incoming value for $role because we may need it to create a new WP_Role
+		$orig_role = $role;
+		$role      = $role instanceof WP_Role ? $role : get_role($role);
+		// if the role isn't available then we create it.
+		if (! $role instanceof WP_Role) {
+			// if a plugin wants to create a specific role name then they should create the role before
+			// EE_Capabilities does.  Otherwise this function will create the role name from the slug:
+			// - removes any `ee_` namespacing from the start of the slug.
+			// - replaces `_` with ` ` (empty space).
+			// - sentence case on the resulting string.
+			$role_label = ucwords(str_replace(['ee_', '_'], ['', ' '], $orig_role));
+			$role       = add_role($orig_role, $role_label);
+		}
+		if ($role instanceof WP_Role) {
+			// don't do anything if the capabilities map can not be initialized
+			if (! $this->setupCapabilitiesMap()) {
+				return false;
+			}
+			if (! $this->capHasBeenAddedToRole($role->name, $cap)) {
+				$role->add_cap($cap, $grant);
+				$this->capabilities_map[ $role->name ][] = $cap;
+				$this->updateCapabilitiesMap($update_capabilities_map);
+				return true;
+			}
+		}
+		return false;
+	}
+
+
+	/**
+	 * Functions similarly to add_cap_to_role except removes cap from given role.
+	 * Wrapper for $wp_role->remove_cap()
+	 *
+	 * @param string|WP_Role $role A WordPress role the capability is being removed from.
+	 * @param string         $cap  The capability being removed
+	 * @param bool           $update_capabilities_map
+	 * @return bool
+	 * @throws EE_Error
+	 * @since 4.5.0
+	 * @see   wp-includes/capabilities.php
+	 */
+	public function remove_cap_from_role($role, string $cap, bool $update_capabilities_map = true): bool
+	{
+		// don't do anything if the capabilities map can not be initialized
+		if (! $this->setupCapabilitiesMap()) {
+			return false;
+		}
+
+		$role = $role instanceof WP_Role ? $role : get_role($role);
+		if ($role instanceof WP_Role && $index = $this->capHasBeenAddedToRole($role->name, $cap, true)) {
+			$role->remove_cap($cap);
+			unset($this->capabilities_map[ $role->name ][ $index ]);
+			$this->updateCapabilitiesMap($update_capabilities_map);
+			return true;
+		}
+		return false;
+	}
+
+
+	/**
+	 * @param string $role_name
+	 * @param string $cap
+	 * @param bool   $get_index
+	 * @return bool|int|string
+	 */
+	private function capHasBeenAddedToRole(string $role_name = '', string $cap = '', bool $get_index = false)
+	{
+		if (
+			isset($this->capabilities_map[ $role_name ])
+			&& ($index = array_search($cap, $this->capabilities_map[ $role_name ], true)) !== false
+		) {
+			return $get_index ? $index : true;
+		}
+		return false;
+	}
+
+
+	/**
+	 * Wrapper for the native WP current_user_can() method.
+	 * This is provided as a handy method for a couple things:
+	 * 1. Using the context string it allows for targeted filtering by addons for a specific check (without having to
+	 * write those filters wherever current_user_can is called).
+	 * 2. Explicit passing of $id from a given context ( useful in the cases of map_meta_cap filters )
+	 *
+	 * @param string $cap     The cap being checked.
+	 * @param string $context The context where the current_user_can is being called from.
+	 * @param int    $id      Optional. Id for item where current_user_can is being called from (used in map_meta_cap()
+	 *                        filters.
+	 *
+	 * @return bool  Whether user can or not.
+	 * @since 4.5.0
+	 *
+	 */
+	public function current_user_can(string $cap, string $context, int $id = 0): bool
+	{
+		// apply filters (both a global on just the cap, and context specific.  Global overrides context specific)
+		$filtered_cap = apply_filters('FHEE__EE_Capabilities__current_user_can__cap__' . $context, $cap, $id);
+		$filtered_cap = apply_filters(
+			'FHEE__EE_Capabilities__current_user_can__cap',
+			$filtered_cap,
+			$context,
+			$cap,
+			$id
+		);
+		return ! empty($id)
+			? current_user_can($filtered_cap, $id)
+			: current_user_can($filtered_cap);
+	}
+
+
+	/**
+	 * This is a wrapper for the WP user_can() function and follows the same style as the other wrappers in this class.
+	 *
+	 * @param int|WP_User $user    Either the user_id or a WP_User object
+	 * @param string      $cap     The capability string being checked
+	 * @param string      $context The context where the user_can is being called from (used in filters).
+	 * @param int         $id      Optional. Id for item where user_can is being called from ( used in map_meta_cap()
+	 *                             filters)
+	 *
+	 * @return bool Whether user can or not.
+	 */
+	public function user_can($user, string $cap, string $context, int $id = 0): bool
+	{
+		// apply filters (both a global on just the cap, and context specific.  Global overrides context specific)
+		$filtered_cap = apply_filters('FHEE__EE_Capabilities__user_can__cap__' . $context, $cap, $user, $id);
+		$filtered_cap = apply_filters(
+			'FHEE__EE_Capabilities__user_can__cap',
+			$filtered_cap,
+			$context,
+			$cap,
+			$user,
+			$id
+		);
+		return ! empty($id)
+			? user_can($user, $filtered_cap, $id)
+			: user_can($user, $filtered_cap);
+	}
+
+
+	/**
+	 * Wrapper for the native WP current_user_can_for_blog() method.
+	 * This is provided as a handy method for a couple things:
+	 * 1. Using the context string it allows for targeted filtering by addons for a specific check (without having to
+	 * write those filters wherever current_user_can is called).
+	 * 2. Explicit passing of $id from a given context ( useful in the cases of map_meta_cap filters )
+	 *
+	 * @param int    $blog_id The blog id that is being checked for.
+	 * @param string $cap     The cap being checked.
+	 * @param string $context The context where the current_user_can is being called from.
+	 * @param int    $id      Optional. Id for item where current_user_can is being called from (used in map_meta_cap()
+	 *                        filters.
+	 *
+	 * @return bool  Whether user can or not.
+	 * @since 4.5.0
+	 *
+	 */
+	public function current_user_can_for_blog(int $blog_id, string $cap, string $context, int $id = 0): bool
+	{
+		$user_can = ! empty($id)
+			? current_user_can_for_blog($blog_id, $cap, $id)
+			: current_user_can($blog_id, $cap);
+		// apply filters (both a global on just the cap, and context specific.  Global overrides context specific)
+		$user_can = apply_filters(
+			'FHEE__EE_Capabilities__current_user_can_for_blog__user_can__' . $context,
+			$user_can,
+			$blog_id,
+			$cap,
+			$id
+		);
+		return apply_filters(
+			'FHEE__EE_Capabilities__current_user_can_for_blog__user_can',
+			$user_can,
+			$context,
+			$blog_id,
+			$cap,
+			$id
+		);
+	}
+
+
+	/**
+	 * This helper method just returns an array of registered EE capabilities.
+	 *
+	 * @param string|null $role If empty then the entire role/capability map is returned.
+	 *                          Otherwise just the capabilities for the given role are returned.
+	 * @return array
+	 * @throws EE_Error
+	 * @since 4.5.0
+	 */
+	public function get_ee_capabilities(?string $role = EE_Capabilities::ROLE_ADMINISTRATOR): array
+	{
+		if (! $this->initialized) {
+			$this->init_caps();
+		}
+		if ($role === '') {
+			return $this->capabilities_map;
+		}
+		return $this->capabilities_map[ $role ] ?? [];
+	}
+
+
+	/**
+	 * @param bool  $reset      If you need to reset Event Espresso's capabilities,
+	 *                          then please use the init_caps() method with the "$reset" parameter set to "true"
+	 * @param array $caps_map   Optional.
+	 *                          Can be used to send a custom map of roles and capabilities for setting them up.
+	 *                          Note that this should ONLY be called on activation hook or some other one-time
+	 *                          task otherwise the caps will be added on every request.
+	 * @return void
+	 * @throws EE_Error
+	 * @deprecated 4.9.42
+	 */
+	public function init_role_caps(bool $reset = false, array $caps_map = [])
+	{
+		// If this method is called directly and reset is set as 'true',
+		// then display a doing it wrong notice, because we want resets to go through init_caps()
+		// to guarantee that everything is set up correctly.
+		// This prevents the capabilities map getting reset incorrectly by direct calls to this method.
+		if ($reset) {
+			EE_Error::doing_it_wrong(
+				__METHOD__,
+				sprintf(
+					esc_html__(
+						'The "%1$s" parameter for the "%2$s" method is deprecated. If you need to reset Event Espresso\'s capabilities, then please use the "%3$s" method with the "%1$s" parameter set to "%4$s".',
+						'event_espresso'
+					),
+					'$reset',
+					__METHOD__ . '()',
+					'EE_Capabilities::init_caps()',
+					'true'
+				),
+				'4.9.42',
+				'5.0.0'
+			);
+		}
+		$this->addCaps($caps_map);
+	}
 }
 
 
@@ -1013,158 +1013,158 @@ 
  */
 abstract class EE_Meta_Capability_Map
 {
-    /**
-     * @var EEM_Base
-     */
-    protected $_model;
-
-    /**
-     * @var string
-     */
-    protected $_model_name;
-
-    /**
-     * @var string
-     */
-    public $meta_cap;
-
-    /**
-     * @var string
-     */
-    public $published_cap = '';
-
-    /**
-     * @var string
-     */
-    public $others_cap = '';
-
-    /**
-     * @var string
-     */
-    public $private_cap = '';
-
-
-    /**
-     * constructor.
-     * Receives the setup arguments for the map.
-     *
-     * @param string $meta_cap   What meta capability is this mapping.
-     * @param array  $map_values array {
-     *                           //array of values that MUST match a count of 4.  It's okay to send an empty string for
-     *                           capabilities that don't get mapped to.
-     *
-     * @type         $map_values [0] string A string representing the model name. Required.  String's
-     *                               should always be used when Menu Maps are registered via the
-     *                               plugin API as models are not allowed to be instantiated when
-     *                               in maintenance mode 2 (migrations).
-     * @type         $map_values [1] string represents the capability used for published. Optional.
-     * @type         $map_values [2] string represents the capability used for "others". Optional.
-     * @type         $map_values [3] string represents the capability used for private. Optional.
-     *                               }
-     * @throws EE_Error
-     * @since                        4.5.0
-     *
-     */
-    public function __construct(string $meta_cap, array $map_values)
-    {
-        $this->meta_cap = $meta_cap;
-        // verify there are four args in the $map_values array;
-        if (count($map_values) !== 4) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'Incoming $map_values array should have a count of four values in it.  This is what was given: %s',
-                        'event_espresso'
-                    ),
-                    '<br>' . print_r($map_values, true)
-                )
-            );
-        }
-        // set properties
-        $this->_model        = null;
-        $this->_model_name   = $map_values[0];
-        $this->published_cap = (string) $map_values[1];
-        $this->others_cap    = (string) $map_values[2];
-        $this->private_cap   = (string) $map_values[3];
-    }
-
-
-    /**
-     * Makes it so this object stops filtering caps
-     */
-    public function remove_filters()
-    {
-        remove_filter('map_meta_cap', [$this, 'map_meta_caps']);
-    }
-
-
-    /**
-     * This method ensures that the $model property is converted from the model name string to a proper EEM_Base class
-     *
-     * @return void
-     * @throws EE_Error
-     * @throws ReflectionException
-     * @since 4.5.0
-     */
-    public function ensure_is_model()
-    {
-        // is it already instantiated?
-        if ($this->_model instanceof EEM_Base) {
-            return;
-        }
-        // ensure model name is string
-        $this->_model_name = (string) $this->_model_name;
-        // error proof if the name has EEM in it
-        $this->_model_name = str_replace('EEM', '', $this->_model_name);
-        $this->_model      = EE_Registry::instance()->load_model($this->_model_name);
-        if (! $this->_model instanceof EEM_Base) {
-            throw new EE_Error(
-                sprintf(
-                    esc_html__(
-                        'This string passed in to %s to represent a EEM_Base model class was not able to be used to instantiate the class.   Please ensure that the string is a match for the EEM_Base model name (not including the EEM_ part). This was given: %s',
-                        'event_espresso'
-                    ),
-                    get_class($this),
-                    $this->_model
-                )
-            );
-        }
-    }
-
-
-    /**
-     *
-     * @param $caps
-     * @param $cap
-     * @param $user_id
-     * @param $args
-     *
-     * @return array
-     * @since 4.6.x
-     *
-     * @see   EE_Meta_Capability_Map::_map_meta_caps() for docs on params.
-     */
-    public function map_meta_caps($caps, $cap, $user_id, $args): array
-    {
-        return $this->_map_meta_caps($caps, $cap, (int) $user_id, $args);
-    }
-
-
-    /**
-     * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
-     * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
-     *
-     * @param array  $caps    actual users capabilities
-     * @param string $cap     initial capability name that is being checked (the "map" key)
-     * @param int    $user_id The user id
-     * @param array  $args    Adds context to the cap. Typically the object ID.
-     *
-     * @return array   actual users capabilities
-     * @see   wp-includes/capabilities.php
-     *
-     * @since 4.5.0
-     */
-    abstract protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array;
+	/**
+	 * @var EEM_Base
+	 */
+	protected $_model;
+
+	/**
+	 * @var string
+	 */
+	protected $_model_name;
+
+	/**
+	 * @var string
+	 */
+	public $meta_cap;
+
+	/**
+	 * @var string
+	 */
+	public $published_cap = '';
+
+	/**
+	 * @var string
+	 */
+	public $others_cap = '';
+
+	/**
+	 * @var string
+	 */
+	public $private_cap = '';
+
+
+	/**
+	 * constructor.
+	 * Receives the setup arguments for the map.
+	 *
+	 * @param string $meta_cap   What meta capability is this mapping.
+	 * @param array  $map_values array {
+	 *                           //array of values that MUST match a count of 4.  It's okay to send an empty string for
+	 *                           capabilities that don't get mapped to.
+	 *
+	 * @type         $map_values [0] string A string representing the model name. Required.  String's
+	 *                               should always be used when Menu Maps are registered via the
+	 *                               plugin API as models are not allowed to be instantiated when
+	 *                               in maintenance mode 2 (migrations).
+	 * @type         $map_values [1] string represents the capability used for published. Optional.
+	 * @type         $map_values [2] string represents the capability used for "others". Optional.
+	 * @type         $map_values [3] string represents the capability used for private. Optional.
+	 *                               }
+	 * @throws EE_Error
+	 * @since                        4.5.0
+	 *
+	 */
+	public function __construct(string $meta_cap, array $map_values)
+	{
+		$this->meta_cap = $meta_cap;
+		// verify there are four args in the $map_values array;
+		if (count($map_values) !== 4) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'Incoming $map_values array should have a count of four values in it.  This is what was given: %s',
+						'event_espresso'
+					),
+					'<br>' . print_r($map_values, true)
+				)
+			);
+		}
+		// set properties
+		$this->_model        = null;
+		$this->_model_name   = $map_values[0];
+		$this->published_cap = (string) $map_values[1];
+		$this->others_cap    = (string) $map_values[2];
+		$this->private_cap   = (string) $map_values[3];
+	}
+
+
+	/**
+	 * Makes it so this object stops filtering caps
+	 */
+	public function remove_filters()
+	{
+		remove_filter('map_meta_cap', [$this, 'map_meta_caps']);
+	}
+
+
+	/**
+	 * This method ensures that the $model property is converted from the model name string to a proper EEM_Base class
+	 *
+	 * @return void
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 * @since 4.5.0
+	 */
+	public function ensure_is_model()
+	{
+		// is it already instantiated?
+		if ($this->_model instanceof EEM_Base) {
+			return;
+		}
+		// ensure model name is string
+		$this->_model_name = (string) $this->_model_name;
+		// error proof if the name has EEM in it
+		$this->_model_name = str_replace('EEM', '', $this->_model_name);
+		$this->_model      = EE_Registry::instance()->load_model($this->_model_name);
+		if (! $this->_model instanceof EEM_Base) {
+			throw new EE_Error(
+				sprintf(
+					esc_html__(
+						'This string passed in to %s to represent a EEM_Base model class was not able to be used to instantiate the class.   Please ensure that the string is a match for the EEM_Base model name (not including the EEM_ part). This was given: %s',
+						'event_espresso'
+					),
+					get_class($this),
+					$this->_model
+				)
+			);
+		}
+	}
+
+
+	/**
+	 *
+	 * @param $caps
+	 * @param $cap
+	 * @param $user_id
+	 * @param $args
+	 *
+	 * @return array
+	 * @since 4.6.x
+	 *
+	 * @see   EE_Meta_Capability_Map::_map_meta_caps() for docs on params.
+	 */
+	public function map_meta_caps($caps, $cap, $user_id, $args): array
+	{
+		return $this->_map_meta_caps($caps, $cap, (int) $user_id, $args);
+	}
+
+
+	/**
+	 * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
+	 * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
+	 *
+	 * @param array  $caps    actual users capabilities
+	 * @param string $cap     initial capability name that is being checked (the "map" key)
+	 * @param int    $user_id The user id
+	 * @param array  $args    Adds context to the cap. Typically the object ID.
+	 *
+	 * @return array   actual users capabilities
+	 * @see   wp-includes/capabilities.php
+	 *
+	 * @since 4.5.0
+	 */
+	abstract protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array;
 }
 
 
@@ -1179,80 +1179,80 @@ 
  */
 class EE_Meta_Capability_Map_Edit extends EE_Meta_Capability_Map
 {
-    /**
-     * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
-     * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
-     *
-     * @param array  $caps    actual users capabilities
-     * @param string $cap     initial capability name that is being checked (the "map" key)
-     * @param int    $user_id The user id
-     * @param array  $args    Adds context to the cap. Typically the object ID.
-     *
-     * @return array   actual users capabilities
-     * @throws EE_Error
-     * @throws EE_Error
-     * @since 4.5.0
-     * @see   wp-includes/capabilities.php
-     *
-     */
-    protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
-    {
-        // only process if we're checking our mapped_cap
-        if ($cap !== $this->meta_cap) {
-            return $caps;
-        }
-
-        // okay it is a meta cap so let's first remove that cap from the $caps array.
-        if (($key = array_search($cap, $caps)) !== false) {
-            unset($caps[ $key ]);
-        }
-
-        /** @var EE_Base_Class $obj */
-        $obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
-        // if no obj then let's just do cap
-        if (! $obj instanceof EE_Base_Class) {
-            $caps[] = 'do_not_allow';
-            return $caps;
-        }
-        $caps[] = $cap . 's';
-        if ($obj instanceof EE_CPT_Base) {
-            // if the item author is set and the user is the author...
-            if ($obj->wp_user() && $user_id === $obj->wp_user()) {
-                // if obj is published...
-                if ($obj->status() === 'publish') {
-                    $caps[] = $this->published_cap;
-                }
-            } else {
-                // the user is trying to edit someone else's obj
-                if (! empty($this->others_cap)) {
-                    $caps[] = $this->others_cap;
-                }
-                if (! empty($this->published_cap) && $obj->status() === 'publish') {
-                    $caps[] = $this->published_cap;
-                } elseif (! empty($this->private_cap) && $obj->status() === 'private') {
-                    $caps[] = $this->private_cap;
-                }
-            }
-        } else {
-            // not a cpt object so handled differently
-            $has_cap = false;
-            try {
-                $has_cap = method_exists($obj, 'wp_user')
-                           && $obj->wp_user()
-                           && $obj->wp_user() === $user_id;
-            } catch (Exception $e) {
-                if (WP_DEBUG) {
-                    EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
-                }
-            }
-            if (! $has_cap) {
-                if (! empty($this->others_cap)) {
-                    $caps[] = $this->others_cap;
-                }
-            }
-        }
-        return $caps;
-    }
+	/**
+	 * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
+	 * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
+	 *
+	 * @param array  $caps    actual users capabilities
+	 * @param string $cap     initial capability name that is being checked (the "map" key)
+	 * @param int    $user_id The user id
+	 * @param array  $args    Adds context to the cap. Typically the object ID.
+	 *
+	 * @return array   actual users capabilities
+	 * @throws EE_Error
+	 * @throws EE_Error
+	 * @since 4.5.0
+	 * @see   wp-includes/capabilities.php
+	 *
+	 */
+	protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
+	{
+		// only process if we're checking our mapped_cap
+		if ($cap !== $this->meta_cap) {
+			return $caps;
+		}
+
+		// okay it is a meta cap so let's first remove that cap from the $caps array.
+		if (($key = array_search($cap, $caps)) !== false) {
+			unset($caps[ $key ]);
+		}
+
+		/** @var EE_Base_Class $obj */
+		$obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
+		// if no obj then let's just do cap
+		if (! $obj instanceof EE_Base_Class) {
+			$caps[] = 'do_not_allow';
+			return $caps;
+		}
+		$caps[] = $cap . 's';
+		if ($obj instanceof EE_CPT_Base) {
+			// if the item author is set and the user is the author...
+			if ($obj->wp_user() && $user_id === $obj->wp_user()) {
+				// if obj is published...
+				if ($obj->status() === 'publish') {
+					$caps[] = $this->published_cap;
+				}
+			} else {
+				// the user is trying to edit someone else's obj
+				if (! empty($this->others_cap)) {
+					$caps[] = $this->others_cap;
+				}
+				if (! empty($this->published_cap) && $obj->status() === 'publish') {
+					$caps[] = $this->published_cap;
+				} elseif (! empty($this->private_cap) && $obj->status() === 'private') {
+					$caps[] = $this->private_cap;
+				}
+			}
+		} else {
+			// not a cpt object so handled differently
+			$has_cap = false;
+			try {
+				$has_cap = method_exists($obj, 'wp_user')
+						   && $obj->wp_user()
+						   && $obj->wp_user() === $user_id;
+			} catch (Exception $e) {
+				if (WP_DEBUG) {
+					EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
+				}
+			}
+			if (! $has_cap) {
+				if (! empty($this->others_cap)) {
+					$caps[] = $this->others_cap;
+				}
+			}
+		}
+		return $caps;
+	}
 }
 
 
@@ -1268,25 +1268,25 @@ 
  */
 class EE_Meta_Capability_Map_Delete extends EE_Meta_Capability_Map_Edit
 {
-    /**
-     * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
-     * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
-     *
-     * @param array  $caps    actual users capabilities
-     * @param string $cap     initial capability name that is being checked (the "map" key)
-     * @param int    $user_id The user id
-     * @param array  $args    Adds context to the cap. Typically the object ID.
-     *
-     * @return array   actual users capabilities
-     * @throws EE_Error
-     * @since 4.5.0
-     * @see   wp-includes/capabilities.php
-     *
-     */
-    protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
-    {
-        return parent::_map_meta_caps($caps, $cap, $user_id, $args);
-    }
+	/**
+	 * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
+	 * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
+	 *
+	 * @param array  $caps    actual users capabilities
+	 * @param string $cap     initial capability name that is being checked (the "map" key)
+	 * @param int    $user_id The user id
+	 * @param array  $args    Adds context to the cap. Typically the object ID.
+	 *
+	 * @return array   actual users capabilities
+	 * @throws EE_Error
+	 * @since 4.5.0
+	 * @see   wp-includes/capabilities.php
+	 *
+	 */
+	protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
+	{
+		return parent::_map_meta_caps($caps, $cap, $user_id, $args);
+	}
 }
 
 
@@ -1301,85 +1301,85 @@ 
  */
 class EE_Meta_Capability_Map_Read extends EE_Meta_Capability_Map
 {
-    /**
-     * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
-     * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
-     *
-     * @param array  $caps    actual users capabilities
-     * @param string $cap     initial capability name that is being checked (the "map" key)
-     * @param int    $user_id The user id
-     * @param array  $args    Adds context to the cap. Typically the object ID.
-     *
-     * @return array   actual users capabilities
-     * @throws EE_Error
-     * @throws EE_Error
-     * @since 4.5.0
-     * @see   wp-includes/capabilities.php
-     *
-     */
-    protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
-    {
-        // only process if we're checking our mapped cap;
-        if ($cap !== $this->meta_cap) {
-            return $caps;
-        }
-
-        // okay it is a meta cap so let's first remove that cap from the $caps array.
-        if (($key = array_search($cap, $caps)) !== false) {
-            unset($caps[ $key ]);
-        }
-
-        $obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
-        // if no obj then let's just do cap
-        if (! $obj instanceof EE_Base_Class) {
-            $caps[] = 'do_not_allow';
-            return $caps;
-        }
-
-        $caps[] = $cap . 's';
-        if ($obj instanceof EE_CPT_Base) {
-            $status_obj = get_post_status_object($obj->status());
-            if ($status_obj->public) {
-                return $caps;
-            }
-            // if the item author is set and the user is not the author...
-            if ($obj->wp_user() && $obj->wp_user() !== $user_id) {
-                if (! empty($this->others_cap)) {
-                    $caps[] = $this->others_cap;
-                }
-            }
-            // yes this means that if users created the private post, they are able to see it regardless of private cap.
-            if (
-                $status_obj->private
-                && ! empty($this->private_cap)
-                && $obj->wp_user() !== $user_id
-            ) {
-                // the user is trying to view a private object for an object they don't own.
-                $caps[] = $this->private_cap;
-            }
-        } else {
-            // not a cpt object so handled differently
-            $has_cap = false;
-            try {
-                $has_cap = method_exists($obj, 'wp_user')
-                           && $obj->wp_user()
-                           && $obj->wp_user() === $user_id;
-            } catch (Exception $e) {
-                if (WP_DEBUG) {
-                    EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
-                }
-            }
-            if (! $has_cap) {
-                if (! empty($this->private_cap)) {
-                    $caps[] = $this->private_cap;
-                }
-                if (! empty($this->others_cap)) {
-                    $caps[] = $this->others_cap;
-                }
-            }
-        }
-        return $caps;
-    }
+	/**
+	 * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
+	 * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
+	 *
+	 * @param array  $caps    actual users capabilities
+	 * @param string $cap     initial capability name that is being checked (the "map" key)
+	 * @param int    $user_id The user id
+	 * @param array  $args    Adds context to the cap. Typically the object ID.
+	 *
+	 * @return array   actual users capabilities
+	 * @throws EE_Error
+	 * @throws EE_Error
+	 * @since 4.5.0
+	 * @see   wp-includes/capabilities.php
+	 *
+	 */
+	protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
+	{
+		// only process if we're checking our mapped cap;
+		if ($cap !== $this->meta_cap) {
+			return $caps;
+		}
+
+		// okay it is a meta cap so let's first remove that cap from the $caps array.
+		if (($key = array_search($cap, $caps)) !== false) {
+			unset($caps[ $key ]);
+		}
+
+		$obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
+		// if no obj then let's just do cap
+		if (! $obj instanceof EE_Base_Class) {
+			$caps[] = 'do_not_allow';
+			return $caps;
+		}
+
+		$caps[] = $cap . 's';
+		if ($obj instanceof EE_CPT_Base) {
+			$status_obj = get_post_status_object($obj->status());
+			if ($status_obj->public) {
+				return $caps;
+			}
+			// if the item author is set and the user is not the author...
+			if ($obj->wp_user() && $obj->wp_user() !== $user_id) {
+				if (! empty($this->others_cap)) {
+					$caps[] = $this->others_cap;
+				}
+			}
+			// yes this means that if users created the private post, they are able to see it regardless of private cap.
+			if (
+				$status_obj->private
+				&& ! empty($this->private_cap)
+				&& $obj->wp_user() !== $user_id
+			) {
+				// the user is trying to view a private object for an object they don't own.
+				$caps[] = $this->private_cap;
+			}
+		} else {
+			// not a cpt object so handled differently
+			$has_cap = false;
+			try {
+				$has_cap = method_exists($obj, 'wp_user')
+						   && $obj->wp_user()
+						   && $obj->wp_user() === $user_id;
+			} catch (Exception $e) {
+				if (WP_DEBUG) {
+					EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
+				}
+			}
+			if (! $has_cap) {
+				if (! empty($this->private_cap)) {
+					$caps[] = $this->private_cap;
+				}
+				if (! empty($this->others_cap)) {
+					$caps[] = $this->others_cap;
+				}
+			}
+		}
+		return $caps;
+	}
 }
 
 
@@ -1395,55 +1395,55 @@ 
  */
 class EE_Meta_Capability_Map_Messages_Cap extends EE_Meta_Capability_Map
 {
-    /**
-     * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
-     * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
-     *
-     * @param array  $caps    actual users capabilities
-     * @param string $cap     initial capability name that is being checked (the "map" key)
-     * @param int    $user_id The user id
-     * @param array  $args    Adds context to the cap. Typically the object ID.
-     *
-     * @return array   actual users capabilities
-     * @throws EE_Error
-     * @throws EE_Error
-     * @since 4.5.0
-     * @see   wp-includes/capabilities.php
-     *
-     */
-    protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
-    {
-        // only process if we're checking our mapped_cap
-        if ($cap !== $this->meta_cap) {
-            return $caps;
-        }
-
-        // okay it is a meta cap so let's first remove that cap from the $caps array.
-        if (($key = array_search($cap, $caps)) !== false) {
-            unset($caps[ $key ]);
-        }
-
-        $obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
-        // if no obj then let's just do cap
-        if (! $obj instanceof EE_Message_Template_Group) {
-            $caps[] = 'do_not_allow';
-            return $caps;
-        }
-        $caps[]    = $cap . 's';
-        $is_global = $obj->is_global();
-        if ($obj->wp_user() && $obj->wp_user() === $user_id) {
-            if ($is_global) {
-                $caps[] = $this->private_cap;
-            }
-        } else {
-            if ($is_global) {
-                $caps[] = $this->private_cap;
-            } else {
-                $caps[] = $this->others_cap;
-            }
-        }
-        return $caps;
-    }
+	/**
+	 * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
+	 * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
+	 *
+	 * @param array  $caps    actual users capabilities
+	 * @param string $cap     initial capability name that is being checked (the "map" key)
+	 * @param int    $user_id The user id
+	 * @param array  $args    Adds context to the cap. Typically the object ID.
+	 *
+	 * @return array   actual users capabilities
+	 * @throws EE_Error
+	 * @throws EE_Error
+	 * @since 4.5.0
+	 * @see   wp-includes/capabilities.php
+	 *
+	 */
+	protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
+	{
+		// only process if we're checking our mapped_cap
+		if ($cap !== $this->meta_cap) {
+			return $caps;
+		}
+
+		// okay it is a meta cap so let's first remove that cap from the $caps array.
+		if (($key = array_search($cap, $caps)) !== false) {
+			unset($caps[ $key ]);
+		}
+
+		$obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
+		// if no obj then let's just do cap
+		if (! $obj instanceof EE_Message_Template_Group) {
+			$caps[] = 'do_not_allow';
+			return $caps;
+		}
+		$caps[]    = $cap . 's';
+		$is_global = $obj->is_global();
+		if ($obj->wp_user() && $obj->wp_user() === $user_id) {
+			if ($is_global) {
+				$caps[] = $this->private_cap;
+			}
+		} else {
+			if ($is_global) {
+				$caps[] = $this->private_cap;
+			} else {
+				$caps[] = $this->others_cap;
+			}
+		}
+		return $caps;
+	}
 }
 
 
@@ -1459,42 +1459,42 @@ 
  */
 class EE_Meta_Capability_Map_Registration_Form_Cap extends EE_Meta_Capability_Map
 {
-    /**
-     * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
-     * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
-     *
-     * @param array  $caps    actual users capabilities
-     * @param string $cap     initial capability name that is being checked (the "map" key)
-     * @param int    $user_id The user id
-     * @param array  $args    Adds context to the cap. Typically the object ID.
-     * @return array   actual users capabilities
-     * @throws EE_Error
-     * @throws EE_Error
-     * @since 4.5.0
-     * @see   wp-includes/capabilities.php
-     */
-    protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
-    {
-        // only process if we're checking our mapped_cap
-        if ($cap !== $this->meta_cap) {
-            return $caps;
-        }
-        // okay it is a meta cap so let's first remove that cap from the $caps array.
-        if (($key = array_search($cap, $caps)) !== false) {
-            unset($caps[ $key ]);
-        }
-        $obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
-        // if no obj then let's just do cap
-        if (! $obj instanceof EE_Base_Class) {
-            $caps[] = 'do_not_allow';
-            return $caps;
-        }
-        $caps[]    = $cap . 's';
-        $is_system = $obj instanceof EE_Question_Group ? $obj->system_group() : false;
-        $is_system = $obj instanceof EE_Question ? $obj->is_system_question() : $is_system;
-        if ($is_system) {
-            $caps[] = $this->private_cap;
-        }
-        return $caps;
-    }
+	/**
+	 * This is the callback for the wp map_meta_caps() function which allows for ensuring certain caps that act as a
+	 * "meta" for other caps ( i.e. ee_edit_event is a meta for ee_edit_others_events ) work as expected.
+	 *
+	 * @param array  $caps    actual users capabilities
+	 * @param string $cap     initial capability name that is being checked (the "map" key)
+	 * @param int    $user_id The user id
+	 * @param array  $args    Adds context to the cap. Typically the object ID.
+	 * @return array   actual users capabilities
+	 * @throws EE_Error
+	 * @throws EE_Error
+	 * @since 4.5.0
+	 * @see   wp-includes/capabilities.php
+	 */
+	protected function _map_meta_caps(array $caps, string $cap, int $user_id, array $args): array
+	{
+		// only process if we're checking our mapped_cap
+		if ($cap !== $this->meta_cap) {
+			return $caps;
+		}
+		// okay it is a meta cap so let's first remove that cap from the $caps array.
+		if (($key = array_search($cap, $caps)) !== false) {
+			unset($caps[ $key ]);
+		}
+		$obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
+		// if no obj then let's just do cap
+		if (! $obj instanceof EE_Base_Class) {
+			$caps[] = 'do_not_allow';
+			return $caps;
+		}
+		$caps[]    = $cap . 's';
+		$is_system = $obj instanceof EE_Question_Group ? $obj->system_group() : false;
+		$is_system = $obj instanceof EE_Question ? $obj->is_system_question() : $is_system;
+		if ($is_system) {
+			$caps[] = $this->private_cap;
+		}
+		return $caps;
+	}
 }

Spacing +45 added lines, -45 removed lines

@@ -84,7 +84,7 @@ 
     public static function instance(): EE_Capabilities
     {
         // check if instantiated, and if not do so.
-        if (! self::$_instance instanceof EE_Capabilities) {
+        if ( ! self::$_instance instanceof EE_Capabilities) {
             self::$_instance = new self();
         }
         return self::$_instance;
@@ -114,7 +114,7 @@ 
      */
     public function init_caps(?bool $reset = false): bool
     {
-        if (! EE_Maintenance_Mode::instance()->models_can_query()) {
+        if ( ! EE_Maintenance_Mode::instance()->models_can_query()) {
             return false;
         }
         $this->reset = filter_var($reset, FILTER_VALIDATE_BOOLEAN);
@@ -159,7 +159,7 @@ 
             $this->_get_default_meta_caps_array()
         );
         // add filter for map_meta_caps but only if models can query.
-        if (! has_filter('map_meta_cap', [$this, 'map_meta_caps'])) {
+        if ( ! has_filter('map_meta_cap', [$this, 'map_meta_caps'])) {
             add_filter('map_meta_cap', [$this, 'map_meta_caps'], 10, 4);
         }
     }
@@ -319,11 +319,11 @@ 
         if (did_action('AHEE__EE_System__load_espresso_addons__complete')) {
             // loop through our _meta_caps array
             foreach ($this->_meta_caps as $meta_map) {
-                if (! $meta_map instanceof EE_Meta_Capability_Map) {
+                if ( ! $meta_map instanceof EE_Meta_Capability_Map) {
                     continue;
                 }
                 // don't load models if there is no object ID in the args
-                if (! empty($args[0])) {
+                if ( ! empty($args[0])) {
                     $meta_map->ensure_is_model();
                 }
                 $caps = $meta_map->map_meta_caps($caps, $cap, $user_id, $args);
@@ -659,11 +659,11 @@ 
     public function addCaps(array $capabilities_to_add): bool
     {
         // don't do anything if the capabilities map can not be initialized
-        if (! $this->setupCapabilitiesMap()) {
+        if ( ! $this->setupCapabilitiesMap()) {
             return false;
         }
         // and filter the array so others can get in on the fun during resets
-        $capabilities_to_add     = apply_filters(
+        $capabilities_to_add = apply_filters(
             'FHEE__EE_Capabilities__addCaps__capabilities_to_add',
             $capabilities_to_add,
             $this->reset,
@@ -701,7 +701,7 @@ 
     public function removeCaps(array $caps_map): bool
     {
         // don't do anything if the capabilities map can not be initialized
-        if (! $this->setupCapabilitiesMap()) {
+        if ( ! $this->setupCapabilitiesMap()) {
             return false;
         }
         $update_capabilities_map = false;
@@ -765,7 +765,7 @@ 
         $orig_role = $role;
         $role      = $role instanceof WP_Role ? $role : get_role($role);
         // if the role isn't available then we create it.
-        if (! $role instanceof WP_Role) {
+        if ( ! $role instanceof WP_Role) {
             // if a plugin wants to create a specific role name then they should create the role before
             // EE_Capabilities does.  Otherwise this function will create the role name from the slug:
             // - removes any `ee_` namespacing from the start of the slug.
@@ -776,12 +776,12 @@ 
         }
         if ($role instanceof WP_Role) {
             // don't do anything if the capabilities map can not be initialized
-            if (! $this->setupCapabilitiesMap()) {
+            if ( ! $this->setupCapabilitiesMap()) {
                 return false;
             }
-            if (! $this->capHasBeenAddedToRole($role->name, $cap)) {
+            if ( ! $this->capHasBeenAddedToRole($role->name, $cap)) {
                 $role->add_cap($cap, $grant);
-                $this->capabilities_map[ $role->name ][] = $cap;
+                $this->capabilities_map[$role->name][] = $cap;
                 $this->updateCapabilitiesMap($update_capabilities_map);
                 return true;
             }
@@ -805,14 +805,14 @@ 
     public function remove_cap_from_role($role, string $cap, bool $update_capabilities_map = true): bool
     {
         // don't do anything if the capabilities map can not be initialized
-        if (! $this->setupCapabilitiesMap()) {
+        if ( ! $this->setupCapabilitiesMap()) {
             return false;
         }
 
         $role = $role instanceof WP_Role ? $role : get_role($role);
         if ($role instanceof WP_Role && $index = $this->capHasBeenAddedToRole($role->name, $cap, true)) {
             $role->remove_cap($cap);
-            unset($this->capabilities_map[ $role->name ][ $index ]);
+            unset($this->capabilities_map[$role->name][$index]);
             $this->updateCapabilitiesMap($update_capabilities_map);
             return true;
         }
@@ -829,8 +829,8 @@ 
     private function capHasBeenAddedToRole(string $role_name = '', string $cap = '', bool $get_index = false)
     {
         if (
-            isset($this->capabilities_map[ $role_name ])
-            && ($index = array_search($cap, $this->capabilities_map[ $role_name ], true)) !== false
+            isset($this->capabilities_map[$role_name])
+            && ($index = array_search($cap, $this->capabilities_map[$role_name], true)) !== false
         ) {
             return $get_index ? $index : true;
         }
@@ -857,7 +857,7 @@ 
     public function current_user_can(string $cap, string $context, int $id = 0): bool
     {
         // apply filters (both a global on just the cap, and context specific.  Global overrides context specific)
-        $filtered_cap = apply_filters('FHEE__EE_Capabilities__current_user_can__cap__' . $context, $cap, $id);
+        $filtered_cap = apply_filters('FHEE__EE_Capabilities__current_user_can__cap__'.$context, $cap, $id);
         $filtered_cap = apply_filters(
             'FHEE__EE_Capabilities__current_user_can__cap',
             $filtered_cap,
@@ -885,7 +885,7 @@ 
     public function user_can($user, string $cap, string $context, int $id = 0): bool
     {
         // apply filters (both a global on just the cap, and context specific.  Global overrides context specific)
-        $filtered_cap = apply_filters('FHEE__EE_Capabilities__user_can__cap__' . $context, $cap, $user, $id);
+        $filtered_cap = apply_filters('FHEE__EE_Capabilities__user_can__cap__'.$context, $cap, $user, $id);
         $filtered_cap = apply_filters(
             'FHEE__EE_Capabilities__user_can__cap',
             $filtered_cap,
@@ -924,7 +924,7 @@ 
             : current_user_can($blog_id, $cap);
         // apply filters (both a global on just the cap, and context specific.  Global overrides context specific)
         $user_can = apply_filters(
-            'FHEE__EE_Capabilities__current_user_can_for_blog__user_can__' . $context,
+            'FHEE__EE_Capabilities__current_user_can_for_blog__user_can__'.$context,
             $user_can,
             $blog_id,
             $cap,
@@ -952,13 +952,13 @@ 
      */
     public function get_ee_capabilities(?string $role = EE_Capabilities::ROLE_ADMINISTRATOR): array
     {
-        if (! $this->initialized) {
+        if ( ! $this->initialized) {
             $this->init_caps();
         }
         if ($role === '') {
             return $this->capabilities_map;
         }
-        return $this->capabilities_map[ $role ] ?? [];
+        return $this->capabilities_map[$role] ?? [];
     }
 
 
@@ -988,7 +988,7 @@ 
                         'event_espresso'
                     ),
                     '$reset',
-                    __METHOD__ . '()',
+                    __METHOD__.'()',
                     'EE_Capabilities::init_caps()',
                     'true'
                 ),
@@ -1076,7 +1076,7 @@ 
                         'Incoming $map_values array should have a count of four values in it.  This is what was given: %s',
                         'event_espresso'
                     ),
-                    '<br>' . print_r($map_values, true)
+                    '<br>'.print_r($map_values, true)
                 )
             );
         }
@@ -1117,7 +1117,7 @@ 
         // error proof if the name has EEM in it
         $this->_model_name = str_replace('EEM', '', $this->_model_name);
         $this->_model      = EE_Registry::instance()->load_model($this->_model_name);
-        if (! $this->_model instanceof EEM_Base) {
+        if ( ! $this->_model instanceof EEM_Base) {
             throw new EE_Error(
                 sprintf(
                     esc_html__(
@@ -1204,17 +1204,17 @@ 
 
         // okay it is a meta cap so let's first remove that cap from the $caps array.
         if (($key = array_search($cap, $caps)) !== false) {
-            unset($caps[ $key ]);
+            unset($caps[$key]);
         }
 
         /** @var EE_Base_Class $obj */
         $obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
         // if no obj then let's just do cap
-        if (! $obj instanceof EE_Base_Class) {
+        if ( ! $obj instanceof EE_Base_Class) {
             $caps[] = 'do_not_allow';
             return $caps;
         }
-        $caps[] = $cap . 's';
+        $caps[] = $cap.'s';
         if ($obj instanceof EE_CPT_Base) {
             // if the item author is set and the user is the author...
             if ($obj->wp_user() && $user_id === $obj->wp_user()) {
@@ -1224,12 +1224,12 @@ 
                 }
             } else {
                 // the user is trying to edit someone else's obj
-                if (! empty($this->others_cap)) {
+                if ( ! empty($this->others_cap)) {
                     $caps[] = $this->others_cap;
                 }
-                if (! empty($this->published_cap) && $obj->status() === 'publish') {
+                if ( ! empty($this->published_cap) && $obj->status() === 'publish') {
                     $caps[] = $this->published_cap;
-                } elseif (! empty($this->private_cap) && $obj->status() === 'private') {
+                } elseif ( ! empty($this->private_cap) && $obj->status() === 'private') {
                     $caps[] = $this->private_cap;
                 }
             }
@@ -1245,8 +1245,8 @@ 
                     EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
                 }
             }
-            if (! $has_cap) {
-                if (! empty($this->others_cap)) {
+            if ( ! $has_cap) {
+                if ( ! empty($this->others_cap)) {
                     $caps[] = $this->others_cap;
                 }
             }
@@ -1326,17 +1326,17 @@ 
 
         // okay it is a meta cap so let's first remove that cap from the $caps array.
         if (($key = array_search($cap, $caps)) !== false) {
-            unset($caps[ $key ]);
+            unset($caps[$key]);
         }
 
         $obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
         // if no obj then let's just do cap
-        if (! $obj instanceof EE_Base_Class) {
+        if ( ! $obj instanceof EE_Base_Class) {
             $caps[] = 'do_not_allow';
             return $caps;
         }
 
-        $caps[] = $cap . 's';
+        $caps[] = $cap.'s';
         if ($obj instanceof EE_CPT_Base) {
             $status_obj = get_post_status_object($obj->status());
             if ($status_obj->public) {
@@ -1344,7 +1344,7 @@ 
             }
             // if the item author is set and the user is not the author...
             if ($obj->wp_user() && $obj->wp_user() !== $user_id) {
-                if (! empty($this->others_cap)) {
+                if ( ! empty($this->others_cap)) {
                     $caps[] = $this->others_cap;
                 }
             }
@@ -1369,11 +1369,11 @@ 
                     EE_Error::add_error($e->getMessage(), __FILE__, __FUNCTION__, __LINE__);
                 }
             }
-            if (! $has_cap) {
-                if (! empty($this->private_cap)) {
+            if ( ! $has_cap) {
+                if ( ! empty($this->private_cap)) {
                     $caps[] = $this->private_cap;
                 }
-                if (! empty($this->others_cap)) {
+                if ( ! empty($this->others_cap)) {
                     $caps[] = $this->others_cap;
                 }
             }
@@ -1420,16 +1420,16 @@ 
 
         // okay it is a meta cap so let's first remove that cap from the $caps array.
         if (($key = array_search($cap, $caps)) !== false) {
-            unset($caps[ $key ]);
+            unset($caps[$key]);
         }
 
         $obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
         // if no obj then let's just do cap
-        if (! $obj instanceof EE_Message_Template_Group) {
+        if ( ! $obj instanceof EE_Message_Template_Group) {
             $caps[] = 'do_not_allow';
             return $caps;
         }
-        $caps[]    = $cap . 's';
+        $caps[]    = $cap.'s';
         $is_global = $obj->is_global();
         if ($obj->wp_user() && $obj->wp_user() === $user_id) {
             if ($is_global) {
@@ -1481,15 +1481,15 @@ 
         }
         // okay it is a meta cap so let's first remove that cap from the $caps array.
         if (($key = array_search($cap, $caps)) !== false) {
-            unset($caps[ $key ]);
+            unset($caps[$key]);
         }
         $obj = ! empty($args[0]) ? $this->_model->get_one_by_ID($args[0]) : null;
         // if no obj then let's just do cap
-        if (! $obj instanceof EE_Base_Class) {
+        if ( ! $obj instanceof EE_Base_Class) {
             $caps[] = 'do_not_allow';
             return $caps;
         }
-        $caps[]    = $cap . 's';
+        $caps[]    = $cap.'s';
         $is_system = $obj instanceof EE_Question_Group ? $obj->system_group() : false;
         $is_system = $obj instanceof EE_Question ? $obj->is_system_question() : $is_system;
         if ($is_system) {