EEM_Line_Item::__construct() - Code Metrics - Inspection of "Daily Inspection: Merge branch 'FET/files-data-han..." - eventespresso/event-espresso-core - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Branch — FET/attendee-importer (b47c55)

unknown

created 2019-03-08 21:48 UTC

EEM_Line_Item::__construct() B

↳ Parent: EEM_Line_Item

Complexity

Conditions	1
Paths	1

Size

Total Lines

131

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
cc	1
nc	1
nop	1
dl	0
loc	131
rs	8
c	0
b	0
f	0

How to fix Long Method

<?php

use EventEspresso\core\exceptions\InvalidDataTypeException;
use EventEspresso\core\exceptions\InvalidInterfaceException;
use EventEspresso\core\services\loaders\LoaderFactory;

/**
 * Line Item Model. Mostly used for storing a snapshot of all the items in a transaction
 * as they were recorded at the time of being added to the cart.
 * There are different 'types' of line items: item, sub-item, tax, sub-total, and total.
 * Note that line items can be nested. For example, a total line item should have one-or-more
 * children sub-totals. Likewise, sub-totals should have one-or-more nested items or taxes
 * (or maybe promotions or products?). Also, items can have nested sub-items (eg. an item could be a
 * ticket, which has many sub-item prices which together make up the price of that ticket).
 * Note that line items should point to real model objects using OBJ_ID and OBJ_type (note:
 * there is a current limitation that they can only point to models with INT primary keys),
 * but this is NOT required. And in fact, the items they are related to CAN be deleted, but
 * the line item should still exist (in this case it merely shows that there was ONCE a model
 * object the line item was based off of).
 * In usage, Line Items are first stored on the EE_Cart, but not saved until a user's registration is
 * finalized (like how the EE_Transaction is stored in the session until it is confirmed).
 * Many of their methods (like
 *
 * @package            Event Espresso
 * @subpackage         includes/models/EEM_Line_Item.model.php
 * @author             Mike Nelson
 */
class EEM_Line_Item extends EEM_Base
{

    /**
     * Tax sub-total is just the total of all the taxes, which should be children
     * of this line item. There should only ever be one tax sub-total, and it should
     * be a direct child of. Its quantity and LIN_unit_price = 1.
     */
    const type_tax_sub_total = 'tax-sub-total';

    /**
     * Tax line items indicate a tax applied to all the taxable line items.
     * Should not have any children line items. Its LIN_unit_price = 0. Its LIN_percent is a percent, not a decimal
     * (eg 10% tax = 10, not 0.1). Its LIN_total = LIN_unit_price * pre-tax-total. Quantity = 1.
     */
    const type_tax = 'tax';

    /**
     * Indicating individual items purchased, or discounts or surcharges.
     * The sum of all the regular line items  plus the tax items should equal the grand total.
     * Possible children are sub-line-items and cancellations.
     * For flat items, LIN_unit_price * LIN_quantity = LIN_total. Its LIN_total is the sum of all the children
     * LIN_totals. Its LIN_percent = 0.
     * For percent items, its LIN_unit_price = 0. Its LIN_percent is a percent, not a decimal (eg 10% = 10, not 0.1).
     * Its LIN_total is LIN_percent / 100 * sum of lower-priority sibling line items. Quantity = 1.
     */
    const type_line_item = 'line-item';

    /**
     * Line item indicating all the factors that make a single line item.
     * Sub-line items should have NO children line items.
     * For flat sub-items, their quantity should match their parent item, their LIN_unit_price should be this sub-item's
     * contribution towards the price of ONE of their parent items, and its LIN_total should be
     *  = LIN_quantity * LIN_unit_price. Its LIN_percent = 0.
     * For percent sub-items, the quantity should be 1, LIN_unit_price should be 0, and its LIN_total should
     * = LIN_percent / 100 * sum of lower-priority sibling line items..
     */
    const type_sub_line_item = 'sub-item';

    /**
     * Line item indicating a sub-total (eg total for an event, or pre-tax subtotal).
     * Direct children should be event subtotals.
     * Should have quantity of 1, and a LIN_total and LIN_unit_price of the sum of all its sub-items' LIN_totals.
     */
    const type_sub_total = 'sub-total';

    /**
     * Line item for the grand total of an order.
     * Its direct children should be tax subtotals and (pre-tax) subtotals,
     * and possibly a regular line item indicating a transaction-wide discount/surcharge.
     * Should have a quantity of 1, a LIN_total and LIN_unit_price of the entire order's amount.
     */
    const type_total = 'total';

    /**
     * When a line item is cancelled, a sub-line-item of type 'cancellation'
     * should be created, indicating the quantity that were cancelled
     * (because a line item could have a quantity of 1, and its cancellation item
     * could be for 3, indicating that originally 4 were purchased, but 3 have been
     * cancelled, and only one remains).
     * When items are refunded, a cancellation line item should be made, which points
     * to teh payment model object which actually refunded the payment.
     * Cancellations should NOT have any children line items; the should NOT affect
     * any calculations, and are only meant as a record that cancellations have occurred.
     * Their LIN_percent should be 0.
     */
    const type_cancellation = 'cancellation';

    // various line item object types
    const OBJ_TYPE_EVENT = 'Event';

    const OBJ_TYPE_PRICE = 'Price';

    const OBJ_TYPE_PROMOTION = 'Promotion';

    const OBJ_TYPE_TICKET = 'Ticket';

    const OBJ_TYPE_TRANSACTION = 'Transaction';

    /**
     * @var EEM_Line_Item $_instance
     */
    protected static $_instance;


    /**
     * private constructor to prevent direct creation
     *
     * @Constructor
     * @param string $timezone string representing the timezone we want to set for returned Date Time Strings
     *                         (and any incoming timezone data that gets saved).
     *                         Note this just sends the timezone info to the date time model field objects.
     *                         Default is NULL
     *                         (and will be assumed using the set timezone in the 'timezone_string' wp option)
     * @throws EE_Error
     * @throws InvalidArgumentException
     */
    protected function __construct($timezone)
    {
        $this->singular_item = esc_html__('Line Item', 'event_espresso');
        $this->plural_item = esc_html__('Line Items', 'event_espresso');

        $this->_tables = array(
            'Line_Item' => new EE_Primary_Table('esp_line_item', 'LIN_ID'),
        );
        $line_items_can_be_for = apply_filters(
            'FHEE__EEM_Line_Item__line_items_can_be_for',
            array('Ticket', 'Price', 'Event')
        );
        $this->_fields = array(
            'Line_Item' => array(
                'LIN_ID'         => new EE_Primary_Key_Int_Field(
                    'LIN_ID',
                    esc_html__('ID', 'event_espresso')
                ),
                'LIN_code'       => new EE_Slug_Field(
                    'LIN_code',
                    esc_html__('Code for index into Cart', 'event_espresso'),
                    true
                ),
                'TXN_ID'         => new EE_Foreign_Key_Int_Field(
                    'TXN_ID',
                    esc_html__('Transaction ID', 'event_espresso'),
                    true,
                    null,
                    'Transaction'
                ),
                'LIN_name'       => new EE_Full_HTML_Field(
                    'LIN_name',
                    esc_html__('Line Item Name', 'event_espresso'),
                    false,
                    ''
                ),
                'LIN_desc'       => new EE_Full_HTML_Field(
                    'LIN_desc',
                    esc_html__('Line Item Description', 'event_espresso'),
                    true
                ),
                'LIN_unit_price' => new EE_Money_Field(
                    'LIN_unit_price',
                    esc_html__('Unit Price', 'event_espresso'),
                    false,
                    0
                ),
                'LIN_percent'    => new EE_Float_Field(
                    'LIN_percent',
                    esc_html__('Percent', 'event_espresso'),
                    false,
                    0
                ),
                'LIN_is_taxable' => new EE_Boolean_Field(
                    'LIN_is_taxable',
                    esc_html__('Taxable', 'event_espresso'),
                    false,
                    false
                ),
                'LIN_order'      => new EE_Integer_Field(
                    'LIN_order',
                    esc_html__('Order of Application towards total of parent', 'event_espresso'),
                    false,
                    1
                ),
                'LIN_total'      => new EE_Money_Field(
                    'LIN_total',
                    esc_html__('Total (unit price x quantity)', 'event_espresso'),
                    false,
                    0
                ),
                'LIN_quantity'   => new EE_Integer_Field(
                    'LIN_quantity',
                    esc_html__('Quantity', 'event_espresso'),
                    true,
                    1
                ),
                'LIN_parent'     => new EE_Integer_Field(
                    'LIN_parent',
                    esc_html__("Parent ID (this item goes towards that Line Item's total)", 'event_espresso'),
                    true,
                    null
                ),
                'LIN_type'       => new EE_Enum_Text_Field(
                    'LIN_type',
                    esc_html__('Type', 'event_espresso'),
                    false,
                    'line-item',
                    array(
                        self::type_line_item     => esc_html__('Line Item', 'event_espresso'),
                        self::type_sub_line_item => esc_html__('Sub-Item', 'event_espresso'),
                        self::type_sub_total     => esc_html__('Subtotal', 'event_espresso'),
                        self::type_tax_sub_total => esc_html__('Tax Subtotal', 'event_espresso'),
                        self::type_tax           => esc_html__('Tax', 'event_espresso'),
                        self::type_total         => esc_html__('Total', 'event_espresso'),
                        self::type_cancellation  => esc_html__('Cancellation', 'event_espresso'),
                    )
                ),
                'OBJ_ID'         => new EE_Foreign_Key_Int_Field(
                    'OBJ_ID',
                    esc_html__('ID of Item purchased.', 'event_espresso'),
                    true,
                    null,
                    $line_items_can_be_for
                ),
                'OBJ_type'       => new EE_Any_Foreign_Model_Name_Field(
                    'OBJ_type',
                    esc_html__('Model Name this Line Item is for', 'event_espresso'),
                    true,
                    null,
                    $line_items_can_be_for
                ),
                'LIN_timestamp'  => new EE_Datetime_Field(
                    'LIN_timestamp',
                    esc_html__('When the line item was created', 'event_espresso'),
                    false,
                    EE_Datetime_Field::now,
                    $timezone
                ),
            ),
        );
        $this->_model_relations = array(
            'Transaction' => new EE_Belongs_To_Relation(),
            'Ticket'      => new EE_Belongs_To_Any_Relation(),
            'Price'       => new EE_Belongs_To_Any_Relation(),
            'Event'       => new EE_Belongs_To_Any_Relation(),
        );
        $this->_model_chain_to_wp_user = 'Transaction.Registration.Event';
        $this->_caps_slug = 'transactions';
        parent::__construct($timezone);
    }


    /**
     * Gets all the line items for this transaction of the given type
     *
     * @param string             $line_item_type like one of EEM_Line_Item::type_*
     * @param EE_Transaction|int $transaction
     * @return EE_Base_Class[]|EE_Line_Item[]
     * @throws EE_Error
     * @throws InvalidArgumentException
     * @throws InvalidDataTypeException
     * @throws InvalidInterfaceException
     */
    public function get_all_of_type_for_transaction($line_item_type, $transaction)
    {
        $transaction = EEM_Transaction::instance()->ensure_is_ID($transaction);
        return $this->get_all(array(
            array(
                'LIN_type' => $line_item_type,
                'TXN_ID'   => $transaction,
            ),
        ));
    }


    /**
     * Gets all line items unrelated to tickets that are normal line items
     * (eg shipping, promotions, and miscellaneous other stuff should probably fit in this category)
     *
     * @param EE_Transaction|int $transaction
     * @return EE_Base_Class[]|EE_Line_Item[]
     * @throws EE_Error
     * @throws InvalidArgumentException
     * @throws InvalidDataTypeException
     * @throws InvalidInterfaceException
     */
    public function get_all_non_ticket_line_items_for_transaction($transaction)
    {
        $transaction = EEM_Transaction::instance()->ensure_is_ID($transaction);
        return $this->get_all(array(
            array(
                'LIN_type' => self::type_line_item,
                'TXN_ID'   => $transaction,
                'OR'       => array(
                    'OBJ_type*notticket' => array('!=', EEM_Line_Item::OBJ_TYPE_TICKET),
                    'OBJ_type*null'      => array('IS_NULL'),
                ),
            ),
        ));
    }


    /**
     * Deletes line items with no transaction who have passed the transaction cutoff time.
     * This needs to be very efficient
     * because if there are spam bots afoot there will be LOTS of line items
     *
     * @return int count of how many deleted
     * @throws EE_Error
     * @throws InvalidArgumentException
     * @throws InvalidDataTypeException
     * @throws InvalidInterfaceException
     */
    public function delete_line_items_with_no_transaction()
    {
        /** @type WPDB $wpdb */
        global $wpdb;
        $time_to_leave_alone = apply_filters(
            'FHEE__EEM_Line_Item__delete_line_items_with_no_transaction__time_to_leave_alone',
            WEEK_IN_SECONDS
        );
        $query = $wpdb->prepare(
            'DELETE li
				FROM ' . $this->table() . ' li
				LEFT JOIN ' . EEM_Transaction::instance()->table() . ' t ON li.TXN_ID = t.TXN_ID
				WHERE t.TXN_ID IS NULL AND li.LIN_timestamp < %s',
            // use GMT time because that's what TXN_timestamps are in
            date('Y-m-d H:i:s', time() - $time_to_leave_alone)
        );
        return $wpdb->query($query);
    }


    /**
     * get_line_item_for_transaction_object
     * Gets a transaction's line item record for a specific object such as a EE_Event or EE_Ticket
     *
     * @param int           $TXN_ID
     * @param EE_Base_Class $object
     * @return EE_Base_Class[]|EE_Line_Item[]
     * @throws EE_Error
     * @throws InvalidArgumentException
     * @throws InvalidDataTypeException
     * @throws InvalidInterfaceException
     * @throws ReflectionException
     */
    public function get_line_item_for_transaction_object($TXN_ID, EE_Base_Class $object)
    {
        return $this->get_all(array(
            array(
                'TXN_ID'   => $TXN_ID,
                'OBJ_type' => str_replace('EE_', '', get_class($object)),
                'OBJ_ID'   => $object->ID(),
            ),
        ));
    }


    /**
     * get_object_line_items_for_transaction
     * Gets all of the the object line items for a transaction, based on an object type plus an array of object IDs
     *
     * @param int    $TXN_ID
     * @param string $OBJ_type
     * @param array  $OBJ_IDs
     * @return EE_Base_Class[]|EE_Line_Item[]
     * @throws EE_Error
     */
    public function get_object_line_items_for_transaction(
        $TXN_ID,
        $OBJ_type = EEM_Line_Item::OBJ_TYPE_EVENT,
        $OBJ_IDs = array()
    ) {
        $query_params = array(
            'OBJ_type' => $OBJ_type,
            // if incoming $OBJ_IDs is an array, then make sure it is formatted correctly for the query
            'OBJ_ID'   => is_array($OBJ_IDs) && ! isset($OBJ_IDs['IN']) ? array('IN', $OBJ_IDs) : $OBJ_IDs,
        );
        if ($TXN_ID) {
            $query_params['TXN_ID'] = $TXN_ID;
        }
        return $this->get_all(array($query_params));
    }


    /**
     * get_all_ticket_line_items_for_transaction
     *
     * @param EE_Transaction $transaction
     * @return EE_Base_Class[]|EE_Line_Item[]
     * @throws EE_Error
     * @throws InvalidArgumentException
     * @throws InvalidDataTypeException
     * @throws InvalidInterfaceException
     * @throws ReflectionException
     */
    public function get_all_ticket_line_items_for_transaction(EE_Transaction $transaction)
    {
        return $this->get_all(array(
            array(
                'TXN_ID'   => $transaction->ID(),
                'OBJ_type' => EEM_Line_Item::OBJ_TYPE_TICKET,
            ),
        ));
    }


    /**
     * get_ticket_line_item_for_transaction
     *
     * @param int $TXN_ID
     * @param int $TKT_ID
     * @return EE_Base_Class|EE_Line_Item|EE_Soft_Delete_Base_Class|NULL
     * @throws EE_Error
     * @throws InvalidArgumentException
     * @throws InvalidDataTypeException
     * @throws InvalidInterfaceException
     */
    public function get_ticket_line_item_for_transaction($TXN_ID, $TKT_ID)
    {
        return $this->get_one(array(
            array(
                'TXN_ID'   => EEM_Transaction::instance()->ensure_is_ID($TXN_ID),
                'OBJ_ID'   => $TKT_ID,
                'OBJ_type' => EEM_Line_Item::OBJ_TYPE_TICKET,
            ),
        ));
    }


    /**
     * get_existing_promotion_line_item
     * searches the cart for existing line items for the specified promotion
     *
     * @since 1.0.0
     * @param EE_Line_Item $parent_line_item
     * @param EE_Promotion $promotion
     * @return EE_Base_Class|EE_Line_Item|EE_Soft_Delete_Base_Class|NULL
     * @throws EE_Error
     * @throws InvalidArgumentException
     * @throws InvalidDataTypeException
     * @throws InvalidInterfaceException
     * @throws ReflectionException
     */
    public function get_existing_promotion_line_item(EE_Line_Item $parent_line_item, EE_Promotion $promotion)
    {
        return $this->get_one(array(
            array(
                'TXN_ID'     => $parent_line_item->TXN_ID(),
                'LIN_parent' => $parent_line_item->ID(),
                'OBJ_type'   => EEM_Line_Item::OBJ_TYPE_PROMOTION,
                'OBJ_ID'     => $promotion->ID(),
            ),
        ));
    }


    /**
     * get_all_promotion_line_items
     * searches the cart for any and all existing promotion line items
     *
     * @since   1.0.0
     * @param EE_Line_Item $parent_line_item
     * @return EE_Base_Class[]|EE_Line_Item[]
     * @throws EE_Error
     * @throws InvalidArgumentException
     * @throws InvalidDataTypeException
     * @throws InvalidInterfaceException
     * @throws ReflectionException
     */
    public function get_all_promotion_line_items(EE_Line_Item $parent_line_item)
    {
        return $this->get_all(array(
            array(
                'TXN_ID'     => $parent_line_item->TXN_ID(),
                'LIN_parent' => $parent_line_item->ID(),
                'OBJ_type'   => EEM_Line_Item::OBJ_TYPE_PROMOTION,
            ),
        ));
    }


    /**
     * Gets the registration's corresponding line item.
     * Note: basically does NOT support having multiple line items for a single ticket,
     * which would happen if some of the registrations had a price modifier while others didn't.
     * In order to support that, we'd probably need a LIN_ID on registrations or something.
     *
     * @param EE_Registration $registration
     * @return EE_Base_Class|EE_Line_ITem|EE_Soft_Delete_Base_Class|NULL
     * @throws EE_Error
     */
    public function get_line_item_for_registration(EE_Registration $registration)
    {
        return $this->get_one($this->line_item_for_registration_query_params($registration));
    }


    /**
     * Gets the query params used to retrieve a specific line item for the given registration
     *
     * @param EE_Registration $registration
     * @param array           $original_query_params any extra query params you'd like to be merged with
     * @return array @see
     *      https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
     * @throws EE_Error
     */
    public function line_item_for_registration_query_params(
        EE_Registration $registration,
        $original_query_params = array()
    ) {
        return array_replace_recursive($original_query_params, array(
            array(
                'OBJ_ID'   => $registration->ticket_ID(),
                'OBJ_type' => EEM_Line_Item::OBJ_TYPE_TICKET,
                'TXN_ID'   => $registration->transaction_ID(),
            ),
        ));
    }


    /**
     * @return EE_Base_Class[]|EE_Line_Item[]
     * @throws InvalidInterfaceException
     * @throws InvalidDataTypeException
     * @throws EE_Error
     * @throws InvalidArgumentException
     */
    public function get_total_line_items_with_no_transaction()
    {
        return $this->get_total_line_items_for_carts();
    }


    /**
     * @return EE_Base_Class[]|EE_Line_Item[]
     * @throws InvalidInterfaceException
     * @throws InvalidDataTypeException
     * @throws EE_Error
     * @throws InvalidArgumentException
     */
    public function get_total_line_items_for_active_carts()
    {
        return $this->get_total_line_items_for_carts(false);
    }


    /**
     * @return EE_Base_Class[]|EE_Line_Item[]
     * @throws InvalidInterfaceException
     * @throws InvalidDataTypeException
     * @throws EE_Error
     * @throws InvalidArgumentException
     */
    public function get_total_line_items_for_expired_carts()
    {
        return $this->get_total_line_items_for_carts(true);
    }


    /**
     * Returns an array of grand total line items where the TXN_ID is 0.
     * If $expired is set to true, then only line items for expired sessions will be returned.
     * If $expired is set to false, then only line items for active sessions will be returned.
     *
     * @param null $expired
     * @return EE_Base_Class[]|EE_Line_Item[]
     * @throws EE_Error
     * @throws InvalidArgumentException
     * @throws InvalidDataTypeException
     * @throws InvalidInterfaceException
     */
    private function get_total_line_items_for_carts($expired = null)
    {
        $where_params = array(
            'TXN_ID'   => 0,
            'LIN_type' => 'total',
        );
        if ($expired !== null) {
            /** @var EventEspresso\core\domain\values\session\SessionLifespan $session_lifespan */
            $session_lifespan = LoaderFactory::getLoader()->getShared(
                'EventEspresso\core\domain\values\session\SessionLifespan'
            );
            $where_params['LIN_timestamp'] = array(
                $expired ? '<=' : '>',
                $session_lifespan->expiration(),
            );
        }
        return $this->get_all(array($where_params));
    }


    /**
     * Returns an array of ticket total line items where the TXN_ID is 0
     * AND the timestamp is older than the session lifespan.
     *
     * @param int $timestamp
     * @return EE_Base_Class[]|EE_Line_Item[]
     * @throws EE_Error
     * @throws InvalidArgumentException
     * @throws InvalidDataTypeException
     * @throws InvalidInterfaceException
     */
    public function getTicketLineItemsForExpiredCarts($timestamp = 0)
    {
        if (! absint($timestamp)) {
            /** @var EventEspresso\core\domain\values\session\SessionLifespan $session_lifespan */
            $session_lifespan = LoaderFactory::getLoader()->getShared(
                'EventEspresso\core\domain\values\session\SessionLifespan'
            );
            $timestamp = $session_lifespan->expiration();
        }
        return $this->get_all(
            array(
                array(
                    'TXN_ID'        => 0,
                    'OBJ_type'      => EEM_Line_Item::OBJ_TYPE_TICKET,
                    'LIN_timestamp' => array('<=', $timestamp),
                ),
            )
        );
    }
}


1			<?php
2
3			use EventEspresso\core\exceptions\InvalidDataTypeException;
4			use EventEspresso\core\exceptions\InvalidInterfaceException;
5			use EventEspresso\core\services\loaders\LoaderFactory;
6
7			/**
8			* Line Item Model. Mostly used for storing a snapshot of all the items in a transaction
9			* as they were recorded at the time of being added to the cart.
10			* There are different 'types' of line items: item, sub-item, tax, sub-total, and total.
11			* Note that line items can be nested. For example, a total line item should have one-or-more
12			* children sub-totals. Likewise, sub-totals should have one-or-more nested items or taxes
13			* (or maybe promotions or products?). Also, items can have nested sub-items (eg. an item could be a
14			* ticket, which has many sub-item prices which together make up the price of that ticket).
15			* Note that line items should point to real model objects using OBJ_ID and OBJ_type (note:
16			* there is a current limitation that they can only point to models with INT primary keys),
17			* but this is NOT required. And in fact, the items they are related to CAN be deleted, but
18			* the line item should still exist (in this case it merely shows that there was ONCE a model
19			* object the line item was based off of).
20			* In usage, Line Items are first stored on the EE_Cart, but not saved until a user's registration is
21			* finalized (like how the EE_Transaction is stored in the session until it is confirmed).
22			* Many of their methods (like
23			*
24			* @package Event Espresso
25			* @subpackage includes/models/EEM_Line_Item.model.php
26			* @author Mike Nelson
27			*/
28			class EEM_Line_Item extends EEM_Base
29			{
30
31			/**
32			* Tax sub-total is just the total of all the taxes, which should be children
33			* of this line item. There should only ever be one tax sub-total, and it should
34			* be a direct child of. Its quantity and LIN_unit_price = 1.
35			*/
36			const type_tax_sub_total = 'tax-sub-total';
37
38			/**
39			* Tax line items indicate a tax applied to all the taxable line items.
40			* Should not have any children line items. Its LIN_unit_price = 0. Its LIN_percent is a percent, not a decimal
41			* (eg 10% tax = 10, not 0.1). Its LIN_total = LIN_unit_price * pre-tax-total. Quantity = 1.
42			*/
43			const type_tax = 'tax';
44
45			/**
46			* Indicating individual items purchased, or discounts or surcharges.
47			* The sum of all the regular line items plus the tax items should equal the grand total.
48			* Possible children are sub-line-items and cancellations.
49			* For flat items, LIN_unit_price * LIN_quantity = LIN_total. Its LIN_total is the sum of all the children
50			* LIN_totals. Its LIN_percent = 0.
51			* For percent items, its LIN_unit_price = 0. Its LIN_percent is a percent, not a decimal (eg 10% = 10, not 0.1).
52			* Its LIN_total is LIN_percent / 100 * sum of lower-priority sibling line items. Quantity = 1.
53			*/
54			const type_line_item = 'line-item';
55
56			/**
57			* Line item indicating all the factors that make a single line item.
58			* Sub-line items should have NO children line items.
59			* For flat sub-items, their quantity should match their parent item, their LIN_unit_price should be this sub-item's
60			* contribution towards the price of ONE of their parent items, and its LIN_total should be
61			* = LIN_quantity * LIN_unit_price. Its LIN_percent = 0.
62			* For percent sub-items, the quantity should be 1, LIN_unit_price should be 0, and its LIN_total should
63			* = LIN_percent / 100 * sum of lower-priority sibling line items..
64			*/
65			const type_sub_line_item = 'sub-item';
66
67			/**
68			* Line item indicating a sub-total (eg total for an event, or pre-tax subtotal).
69			* Direct children should be event subtotals.
70			* Should have quantity of 1, and a LIN_total and LIN_unit_price of the sum of all its sub-items' LIN_totals.
71			*/
72			const type_sub_total = 'sub-total';
73
74			/**
75			* Line item for the grand total of an order.
76			* Its direct children should be tax subtotals and (pre-tax) subtotals,
77			* and possibly a regular line item indicating a transaction-wide discount/surcharge.
78			* Should have a quantity of 1, a LIN_total and LIN_unit_price of the entire order's amount.
79			*/
80			const type_total = 'total';
81
82			/**
83			* When a line item is cancelled, a sub-line-item of type 'cancellation'
84			* should be created, indicating the quantity that were cancelled
85			* (because a line item could have a quantity of 1, and its cancellation item
86			* could be for 3, indicating that originally 4 were purchased, but 3 have been
87			* cancelled, and only one remains).
88			* When items are refunded, a cancellation line item should be made, which points
89			* to teh payment model object which actually refunded the payment.
90			* Cancellations should NOT have any children line items; the should NOT affect
91			* any calculations, and are only meant as a record that cancellations have occurred.
92			* Their LIN_percent should be 0.
93			*/
94			const type_cancellation = 'cancellation';
95
96			// various line item object types
97			const OBJ_TYPE_EVENT = 'Event';
98
99			const OBJ_TYPE_PRICE = 'Price';
100
101			const OBJ_TYPE_PROMOTION = 'Promotion';
102
103			const OBJ_TYPE_TICKET = 'Ticket';
104
105			const OBJ_TYPE_TRANSACTION = 'Transaction';
106
107			/**
108			* @var EEM_Line_Item $_instance
109			*/
110			protected static $_instance;
111
112
113			/**
114			* private constructor to prevent direct creation
115			*
116			* @Constructor
117			* @param string $timezone string representing the timezone we want to set for returned Date Time Strings
118			* (and any incoming timezone data that gets saved).
119			* Note this just sends the timezone info to the date time model field objects.
120			* Default is NULL
121			* (and will be assumed using the set timezone in the 'timezone_string' wp option)
122			* @throws EE_Error
123			* @throws InvalidArgumentException
124			*/
125			protected function __construct($timezone)
126			{
127			$this->singular_item = esc_html__('Line Item', 'event_espresso');
128			$this->plural_item = esc_html__('Line Items', 'event_espresso');
129
130			$this->_tables = array(
131			'Line_Item' => new EE_Primary_Table('esp_line_item', 'LIN_ID'),
132			);
133			$line_items_can_be_for = apply_filters(
134			'FHEE__EEM_Line_Item__line_items_can_be_for',
135			array('Ticket', 'Price', 'Event')
136			);
137			$this->_fields = array(
138			'Line_Item' => array(
139			'LIN_ID' => new EE_Primary_Key_Int_Field(
140			'LIN_ID',
141			esc_html__('ID', 'event_espresso')
142			),
143			'LIN_code' => new EE_Slug_Field(
144			'LIN_code',
145			esc_html__('Code for index into Cart', 'event_espresso'),
146			true
147			),
148			'TXN_ID' => new EE_Foreign_Key_Int_Field(
149			'TXN_ID',
150			esc_html__('Transaction ID', 'event_espresso'),
151			true,
152			null,
153			'Transaction'
154			),
155			'LIN_name' => new EE_Full_HTML_Field(
156			'LIN_name',
157			esc_html__('Line Item Name', 'event_espresso'),
158			false,
159			''
160			),
161			'LIN_desc' => new EE_Full_HTML_Field(
162			'LIN_desc',
163			esc_html__('Line Item Description', 'event_espresso'),
164			true
165			),
166			'LIN_unit_price' => new EE_Money_Field(
167			'LIN_unit_price',
168			esc_html__('Unit Price', 'event_espresso'),
169			false,
170			0
171			),
172			'LIN_percent' => new EE_Float_Field(
173			'LIN_percent',
174			esc_html__('Percent', 'event_espresso'),
175			false,
176			0
177			),
178			'LIN_is_taxable' => new EE_Boolean_Field(
179			'LIN_is_taxable',
180			esc_html__('Taxable', 'event_espresso'),
181			false,
182			false
183			),
184			'LIN_order' => new EE_Integer_Field(
185			'LIN_order',
186			esc_html__('Order of Application towards total of parent', 'event_espresso'),
187			false,
188			1
189			),
190			'LIN_total' => new EE_Money_Field(
191			'LIN_total',
192			esc_html__('Total (unit price x quantity)', 'event_espresso'),
193			false,
194			0
195			),
196			'LIN_quantity' => new EE_Integer_Field(
197			'LIN_quantity',
198			esc_html__('Quantity', 'event_espresso'),
199			true,
200			1
201			),
202			'LIN_parent' => new EE_Integer_Field(
203			'LIN_parent',
204			esc_html__("Parent ID (this item goes towards that Line Item's total)", 'event_espresso'),
205			true,
206			null
207			),
208			'LIN_type' => new EE_Enum_Text_Field(
209			'LIN_type',
210			esc_html__('Type', 'event_espresso'),
211			false,
212			'line-item',
213			array(
214			self::type_line_item => esc_html__('Line Item', 'event_espresso'),
215			self::type_sub_line_item => esc_html__('Sub-Item', 'event_espresso'),
216			self::type_sub_total => esc_html__('Subtotal', 'event_espresso'),
217			self::type_tax_sub_total => esc_html__('Tax Subtotal', 'event_espresso'),
218			self::type_tax => esc_html__('Tax', 'event_espresso'),
219			self::type_total => esc_html__('Total', 'event_espresso'),
220			self::type_cancellation => esc_html__('Cancellation', 'event_espresso'),
221			)
222			),
223			'OBJ_ID' => new EE_Foreign_Key_Int_Field(
224			'OBJ_ID',
225			esc_html__('ID of Item purchased.', 'event_espresso'),
226			true,
227			null,
228			$line_items_can_be_for
229			),
230			'OBJ_type' => new EE_Any_Foreign_Model_Name_Field(
231			'OBJ_type',
232			esc_html__('Model Name this Line Item is for', 'event_espresso'),
233			true,
234			null,
235			$line_items_can_be_for
236			),
237			'LIN_timestamp' => new EE_Datetime_Field(
238			'LIN_timestamp',
239			esc_html__('When the line item was created', 'event_espresso'),
240			false,
241			EE_Datetime_Field::now,
242			$timezone
243			),
244			),
245			);
246			$this->_model_relations = array(
247			'Transaction' => new EE_Belongs_To_Relation(),
248			'Ticket' => new EE_Belongs_To_Any_Relation(),
249			'Price' => new EE_Belongs_To_Any_Relation(),
250			'Event' => new EE_Belongs_To_Any_Relation(),
251			);
252			$this->_model_chain_to_wp_user = 'Transaction.Registration.Event';
253			$this->_caps_slug = 'transactions';
254			parent::__construct($timezone);
255			}
256
257
258			/**
259			* Gets all the line items for this transaction of the given type
260			*
261			* @param string $line_item_type like one of EEM_Line_Item::type_*
262			* @param EE_Transaction\|int $transaction
263			* @return EE_Base_Class[]\|EE_Line_Item[]
264			* @throws EE_Error
265			* @throws InvalidArgumentException
266			* @throws InvalidDataTypeException
267			* @throws InvalidInterfaceException
268			*/
269			public function get_all_of_type_for_transaction($line_item_type, $transaction)
270			{
271			$transaction = EEM_Transaction::instance()->ensure_is_ID($transaction);
272			return $this->get_all(array(
273			array(
274			'LIN_type' => $line_item_type,
275			'TXN_ID' => $transaction,
276			),
277			));
278			}
279
280
281			/**
282			* Gets all line items unrelated to tickets that are normal line items
283			* (eg shipping, promotions, and miscellaneous other stuff should probably fit in this category)
284			*
285			* @param EE_Transaction\|int $transaction
286			* @return EE_Base_Class[]\|EE_Line_Item[]
287			* @throws EE_Error
288			* @throws InvalidArgumentException
289			* @throws InvalidDataTypeException
290			* @throws InvalidInterfaceException
291			*/
292			public function get_all_non_ticket_line_items_for_transaction($transaction)
293			{
294			$transaction = EEM_Transaction::instance()->ensure_is_ID($transaction);
295			return $this->get_all(array(
296			array(
297			'LIN_type' => self::type_line_item,
298			'TXN_ID' => $transaction,
299			'OR' => array(
300			'OBJ_type*notticket' => array('!=', EEM_Line_Item::OBJ_TYPE_TICKET),
301			'OBJ_type*null' => array('IS_NULL'),
302			),
303			),
304			));
305			}
306
307
308			/**
309			* Deletes line items with no transaction who have passed the transaction cutoff time.
310			* This needs to be very efficient
311			* because if there are spam bots afoot there will be LOTS of line items
312			*
313			* @return int count of how many deleted
314			* @throws EE_Error
315			* @throws InvalidArgumentException
316			* @throws InvalidDataTypeException
317			* @throws InvalidInterfaceException
318			*/
319			public function delete_line_items_with_no_transaction()
320			{
321			/** @type WPDB $wpdb */
322			global $wpdb;
323			$time_to_leave_alone = apply_filters(
324			'FHEE__EEM_Line_Item__delete_line_items_with_no_transaction__time_to_leave_alone',
325			WEEK_IN_SECONDS
326			);
327			$query = $wpdb->prepare(
328			'DELETE li
329			FROM ' . $this->table() . ' li
330			LEFT JOIN ' . EEM_Transaction::instance()->table() . ' t ON li.TXN_ID = t.TXN_ID
331			WHERE t.TXN_ID IS NULL AND li.LIN_timestamp < %s',
332			// use GMT time because that's what TXN_timestamps are in
333			date('Y-m-d H:i:s', time() - $time_to_leave_alone)
334			);
335			return $wpdb->query($query);
336			}
337
338
339			/**
340			* get_line_item_for_transaction_object
341			* Gets a transaction's line item record for a specific object such as a EE_Event or EE_Ticket
342			*
343			* @param int $TXN_ID
344			* @param EE_Base_Class $object
345			* @return EE_Base_Class[]\|EE_Line_Item[]
346			* @throws EE_Error
347			* @throws InvalidArgumentException
348			* @throws InvalidDataTypeException
349			* @throws InvalidInterfaceException
350			* @throws ReflectionException
351			*/
352			public function get_line_item_for_transaction_object($TXN_ID, EE_Base_Class $object)
353			{
354			return $this->get_all(array(
355			array(
356			'TXN_ID' => $TXN_ID,
357			'OBJ_type' => str_replace('EE_', '', get_class($object)),
358			'OBJ_ID' => $object->ID(),
359			),
360			));
361			}
362
363
364			/**
365			* get_object_line_items_for_transaction
366			* Gets all of the the object line items for a transaction, based on an object type plus an array of object IDs
367			*
368			* @param int $TXN_ID
369			* @param string $OBJ_type
370			* @param array $OBJ_IDs
371			* @return EE_Base_Class[]\|EE_Line_Item[]
372			* @throws EE_Error
373			*/
374			public function get_object_line_items_for_transaction(
375			$TXN_ID,
376			$OBJ_type = EEM_Line_Item::OBJ_TYPE_EVENT,
377			$OBJ_IDs = array()
378			) {
379			$query_params = array(
380			'OBJ_type' => $OBJ_type,
381			// if incoming $OBJ_IDs is an array, then make sure it is formatted correctly for the query
382			'OBJ_ID' => is_array($OBJ_IDs) && ! isset($OBJ_IDs['IN']) ? array('IN', $OBJ_IDs) : $OBJ_IDs,
383			);
384			if ($TXN_ID) {
385			$query_params['TXN_ID'] = $TXN_ID;
386			}
387			return $this->get_all(array($query_params));
388			}
389
390
391			/**
392			* get_all_ticket_line_items_for_transaction
393			*
394			* @param EE_Transaction $transaction
395			* @return EE_Base_Class[]\|EE_Line_Item[]
396			* @throws EE_Error
397			* @throws InvalidArgumentException
398			* @throws InvalidDataTypeException
399			* @throws InvalidInterfaceException
400			* @throws ReflectionException
401			*/
402			public function get_all_ticket_line_items_for_transaction(EE_Transaction $transaction)
403			{
404			return $this->get_all(array(
405			array(
406			'TXN_ID' => $transaction->ID(),
407			'OBJ_type' => EEM_Line_Item::OBJ_TYPE_TICKET,
408			),
409			));
410			}
411
412
413			/**
414			* get_ticket_line_item_for_transaction
415			*
416			* @param int $TXN_ID
417			* @param int $TKT_ID
418			* @return EE_Base_Class\|EE_Line_Item\|EE_Soft_Delete_Base_Class\|NULL
419			* @throws EE_Error
420			* @throws InvalidArgumentException
421			* @throws InvalidDataTypeException
422			* @throws InvalidInterfaceException
423			*/
424			public function get_ticket_line_item_for_transaction($TXN_ID, $TKT_ID)
425			{
426			return $this->get_one(array(
427			array(
428			'TXN_ID' => EEM_Transaction::instance()->ensure_is_ID($TXN_ID),
429			'OBJ_ID' => $TKT_ID,
430			'OBJ_type' => EEM_Line_Item::OBJ_TYPE_TICKET,
431			),
432			));
433			}
434
435
436			/**
437			* get_existing_promotion_line_item
438			* searches the cart for existing line items for the specified promotion
439			*
440			* @since 1.0.0
441			* @param EE_Line_Item $parent_line_item
442			* @param EE_Promotion $promotion
443			* @return EE_Base_Class\|EE_Line_Item\|EE_Soft_Delete_Base_Class\|NULL
444			* @throws EE_Error
445			* @throws InvalidArgumentException
446			* @throws InvalidDataTypeException
447			* @throws InvalidInterfaceException
448			* @throws ReflectionException
449			*/
450			public function get_existing_promotion_line_item(EE_Line_Item $parent_line_item, EE_Promotion $promotion)
451			{
452			return $this->get_one(array(
453			array(
454			'TXN_ID' => $parent_line_item->TXN_ID(),
455			'LIN_parent' => $parent_line_item->ID(),
456			'OBJ_type' => EEM_Line_Item::OBJ_TYPE_PROMOTION,
457			'OBJ_ID' => $promotion->ID(),
458			),
459			));
460			}
461
462
463			/**
464			* get_all_promotion_line_items
465			* searches the cart for any and all existing promotion line items
466			*
467			* @since 1.0.0
468			* @param EE_Line_Item $parent_line_item
469			* @return EE_Base_Class[]\|EE_Line_Item[]
470			* @throws EE_Error
471			* @throws InvalidArgumentException
472			* @throws InvalidDataTypeException
473			* @throws InvalidInterfaceException
474			* @throws ReflectionException
475			*/
476			public function get_all_promotion_line_items(EE_Line_Item $parent_line_item)
477			{
478			return $this->get_all(array(
479			array(
480			'TXN_ID' => $parent_line_item->TXN_ID(),
481			'LIN_parent' => $parent_line_item->ID(),
482			'OBJ_type' => EEM_Line_Item::OBJ_TYPE_PROMOTION,
483			),
484			));
485			}
486
487
488			/**
489			* Gets the registration's corresponding line item.
490			* Note: basically does NOT support having multiple line items for a single ticket,
491			* which would happen if some of the registrations had a price modifier while others didn't.
492			* In order to support that, we'd probably need a LIN_ID on registrations or something.
493			*
494			* @param EE_Registration $registration
495			* @return EE_Base_Class\|EE_Line_ITem\|EE_Soft_Delete_Base_Class\|NULL
496			* @throws EE_Error
497			*/
498			public function get_line_item_for_registration(EE_Registration $registration)
499			{
500			return $this->get_one($this->line_item_for_registration_query_params($registration));
501			}
502
503
504			/**
505			* Gets the query params used to retrieve a specific line item for the given registration
506			*
507			* @param EE_Registration $registration
508			* @param array $original_query_params any extra query params you'd like to be merged with
509			* @return array @see
510			* https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md
511			* @throws EE_Error
512			*/
513			public function line_item_for_registration_query_params(
514			EE_Registration $registration,
515			$original_query_params = array()
516			) {
517			return array_replace_recursive($original_query_params, array(
518			array(
519			'OBJ_ID' => $registration->ticket_ID(),
520			'OBJ_type' => EEM_Line_Item::OBJ_TYPE_TICKET,
521			'TXN_ID' => $registration->transaction_ID(),
522			),
523			));
524			}
525
526
527			/**
528			* @return EE_Base_Class[]\|EE_Line_Item[]
529			* @throws InvalidInterfaceException
530			* @throws InvalidDataTypeException
531			* @throws EE_Error
532			* @throws InvalidArgumentException
533			*/
534			public function get_total_line_items_with_no_transaction()
535			{
536			return $this->get_total_line_items_for_carts();
537			}
538
539
540			/**
541			* @return EE_Base_Class[]\|EE_Line_Item[]
542			* @throws InvalidInterfaceException
543			* @throws InvalidDataTypeException
544			* @throws EE_Error
545			* @throws InvalidArgumentException
546			*/
547			public function get_total_line_items_for_active_carts()
548			{
549			return $this->get_total_line_items_for_carts(false);
550			}
551
552
553			/**
554			* @return EE_Base_Class[]\|EE_Line_Item[]
555			* @throws InvalidInterfaceException
556			* @throws InvalidDataTypeException
557			* @throws EE_Error
558			* @throws InvalidArgumentException
559			*/
560			public function get_total_line_items_for_expired_carts()
561			{
562			return $this->get_total_line_items_for_carts(true);
563			}
564
565
566			/**
567			* Returns an array of grand total line items where the TXN_ID is 0.
568			* If $expired is set to true, then only line items for expired sessions will be returned.
569			* If $expired is set to false, then only line items for active sessions will be returned.
570			*
571			* @param null $expired
572			* @return EE_Base_Class[]\|EE_Line_Item[]
573			* @throws EE_Error
574			* @throws InvalidArgumentException
575			* @throws InvalidDataTypeException
576			* @throws InvalidInterfaceException
577			*/
578			private function get_total_line_items_for_carts($expired = null)
579			{
580			$where_params = array(
581			'TXN_ID' => 0,
582			'LIN_type' => 'total',
583			);
584			if ($expired !== null) {
585			/** @var EventEspresso\core\domain\values\session\SessionLifespan $session_lifespan */
586			$session_lifespan = LoaderFactory::getLoader()->getShared(
587			'EventEspresso\core\domain\values\session\SessionLifespan'
588			);
589			$where_params['LIN_timestamp'] = array(
590			$expired ? '<=' : '>',
591			$session_lifespan->expiration(),
592			);
593			}
594			return $this->get_all(array($where_params));
595			}
596
597
598			/**
599			* Returns an array of ticket total line items where the TXN_ID is 0
600			* AND the timestamp is older than the session lifespan.
601			*
602			* @param int $timestamp
603			* @return EE_Base_Class[]\|EE_Line_Item[]
604			* @throws EE_Error
605			* @throws InvalidArgumentException
606			* @throws InvalidDataTypeException
607			* @throws InvalidInterfaceException
608			*/
609			public function getTicketLineItemsForExpiredCarts($timestamp = 0)
610			{
611			if (! absint($timestamp)) {
612			/** @var EventEspresso\core\domain\values\session\SessionLifespan $session_lifespan */
613			$session_lifespan = LoaderFactory::getLoader()->getShared(
614			'EventEspresso\core\domain\values\session\SessionLifespan'
615			);
616			$timestamp = $session_lifespan->expiration();
617			}
618			return $this->get_all(
619			array(
620			array(
621			'TXN_ID' => 0,
622			'OBJ_type' => EEM_Line_Item::OBJ_TYPE_TICKET,
623			'LIN_timestamp' => array('<=', $timestamp),
624			),
625			)
626			);
627			}
628			}
629

eventespresso / event-espresso-core

Branch — FET/attendee-importer (b47c55)

EEM_Line_Item::__construct() B

Complexity

Size

Duplication

Importance

How to fix Long Method

Long Method

Duplication Side-by-Side

Filter issues like