laipower/wp-content/plugins/easy-digital-downloads/includes/customer-functions.php

<?php
/**
 * Customer Functions.
 *
 * This file contains all of the first class functions for interacting with a
 * customer or it's related meta data.
 *
 * @package     EDD
 * @subpackage  Functions
 * @copyright   Copyright (c) 2018, Easy Digital Downloads, LLC
 * @license     http://opensource.org/licenses/gpl-2.0.php GNU Public License
 * @since       3.0
 */

// Exit if accessed directly
defined( 'ABSPATH' ) || exit;

/**
 * Add a customer.
 *
 * @since 3.0
 *
 * @param array $data {
 *     Array of customer data. Default empty.
 *
 *     The `date_created` and `date_modified` parameters do not need to be passed.
 *     They will be automatically populated if empty.
 *
 *     @type int    $user_id        WordPress user ID linked to the customer account.
 *                                  Default 0.
 *     @type string $email          Customer's primary email address. Default empty.
 *     @type string $name           Customer's name. Default empty.
 *     @type string $status         Customer's status. Default `active`.
 *     @type float  $purchase_value Aggregated purchase value of the customer.
 *                                  Default 0.
 *     @type int    $purchase_count Aggregated purchase count of the customer.
 *                                  Default 0.
 *     @type string $date_created   Optional. Automatically calculated on add/edit.
 *                                  The date & time the customer was created.
 *                                  Format: YYYY-MM-DD HH:MM:SS. Default empty.
 *     @type string $date_modified  Optional. Automatically calculated on add/edit.
 *                                  The date & time the customer was last modified.
 *                                  Format: YYYY-MM-DD HH:MM:SS. Default empty.
 * }
 * @return int|false ID of the inserted customer, false on failure.
 */
function edd_add_customer( $data = array() ) {

	// An email must be given for every customer that is created.
	if ( ! isset( $data['email'] ) || empty( $data['email'] ) ) {
		return false;
	}

	$customers  = new EDD\Database\Queries\Customer();
	$customer_id = $customers->add_item( $data );

	if ( ! empty( $customer_id ) ) {
		/**
		 * Action that runs when a customer is added with the edd_add_customer function.
		 *
		 * @since 3.0.4
		 *
		 * @param int          $customer_id Customer ID added.
		 * @param array        $data        Array of arguments sent to create the customer with.
		 */
		do_action( 'edd_customer_added', $customer_id, $data );
	}

	return $customer_id;
}

/**
 * Delete a customer.
 *
 * @since 3.0
 *
 * @param int ID of customer to delete.
 * @return int|false `1` if the customer was deleted successfully, false on error.
 */
function edd_delete_customer( $customer_id = 0 ) {
	$customers = new EDD\Database\Queries\Customer();

	$customer_deleted = $customers->delete_item( $customer_id );

	if ( ! empty( $customer_deleted ) ) {
		/**
		 * Action that runs when a customer is deleted with the edd_delete_customer function.
		 *
		 * @since 3.0.4
		 *
		 * @param int          $customer_id Customer ID being deleted.
		 */
		do_action( 'edd_customer_deleted', $customer_id );
	}

	return $customer_deleted;
}

/**
 * Destroy a customer.
 *
 * Completely deletes a customer, and the addresses and email addresses with it.
 *
 * @since 3.0
 *
 * @param int $customer_id Customer ID.
 * @return int|false `1` if the customer was deleted successfully, false on error.
 */
function edd_destroy_customer( $customer_id = 0 ) {

	// Bail if a customer ID was not passed.
	if ( empty( $customer_id ) ) {
		return false;
	}

	// Get email addresses.
	$email_addresses = edd_get_customer_email_addresses( array(
		'customer_id'   => $customer_id,
		'no_found_rows' => true,
	) );

	// Destroy email addresses.
	if ( ! empty( $email_addresses ) ) {
		foreach ( $email_addresses as $email_address ) {
			edd_delete_customer_email_address( $email_address->id );
		}
	}

	// Get addresses.
	$addresses = edd_get_customer_addresses( array(
		'customer_id'   => $customer_id,
		'no_found_rows' => true,
	) );

	// Destroy addresses.
	if ( ! empty( $addresses ) ) {
		foreach ( $addresses as $address ) {
			edd_delete_customer_address( $address->id );
		}
	}

	// Delete the customer.
	$customer_destroyed = edd_delete_customer( $customer_id );
	if ( ! empty( $customer_destroyed ) ) {
		/**
		 * Action that runs when a customer is destroyed with the edd_destroy_customer function.
		 *
		 * This action is similar to edd_customer_deleted and includes running that action,
		 * but also includes deleting all customer addresses and email addresses.
		 *
		 * @since 3.0.4
		 *
		 * @param int          $customer_id Customer ID being destroyed.
		 */
		do_action( 'edd_customer_destroyed', $customer_id );
	}

	return $customer_destroyed;
}

/**
 * Update a customer.
 *
 * @since 3.0
 *
 * @param int $customer_id Customer ID.
 * @param array $data {
 *     Array of customer data. Default empty.
 *
 *     @type int    $user_id        WordPress user ID linked to the customer account.
 *                                  Default 0.
 *     @type string $email          Customer's primary email address. Default empty.
 *     @type string $name           Customer's name. Default empty.
 *     @type string $status         Customer's status. Default `active`.
 *     @type float  $purchase_value Aggregated purchase value of the customer.
 *                                  Default 0.
 *     @type int    $purchase_count Aggregated purchase count of the customer.
 *                                  Default 0.
 *     @type string $date_created   Optional. Automatically calculated on add/edit.
 *                                  The date & time the customer was created.
 *                                  Format: YYYY-MM-DD HH:MM:SS. Default empty.
 *     @type string $date_modified  Optional. Automatically calculated on add/edit.
 *                                  The date & time the customer was last modified.
 *                                  Format: YYYY-MM-DD HH:MM:SS. Default empty.
 * }
 *
 * @return int|false Number of rows updated if successful, false otherwise.
 */
function edd_update_customer( $customer_id = 0, $data = array() ) {
	$customers = new EDD\Database\Queries\Customer();

	$previous_customer_data = edd_get_customer( $customer_id );
	$customer_updated       = $customers->update_item( $customer_id, $data );

	if ( ! empty( $customer_updated ) ) {
		/**
		 * Action that runs when a customer is updated with the edd_update_customer function.
		 *
		 * @since 3.0.4
		 *
		 * @param int          $customer_id            Customer ID updated.
		 * @param array        $data                   Array of arguments sent to create the customer with.
		 * @param EDD_Customer $previous_customer_data The customer row before it was updated.
		 */
		do_action( 'edd_customer_updated', $customer_id, $data, $previous_customer_data );
	}

	return $customer_updated;
}

/**
 * Get a customer item by ID.
 *
 * @since 3.0
 *
 * @param int $customer_id Customer ID.
 * @return EDD_Customer|false Customer object if successful, false otherwise.
 */
function edd_get_customer( $customer_id = 0 ) {
	$customers = new EDD\Database\Queries\Customer();

	// Return customer.
	return $customers->get_item( $customer_id );
}

/**
 * Get a customer item by a specific field value.
 *
 * @since 3.0
 *
 * @param string $field Database table field.
 * @param string $value Value of the row.
 *
 * @return EDD_Customer|false Customer object if successful, false otherwise.
 */
function edd_get_customer_by( $field = '', $value = '' ) {
	// For backwards compatibility in filters only.
	$customers_db = EDD()->customers;

	/**
	 * Filters the Customer before querying the database.
	 *
	 * Return a non-null value to bypass the default query and return early.
	 *
	 * @since 2.9.23
	 *
	 * @param mixed|null          $customer         Customer to return instead. Default null to use default method.
	 * @param string              $field            The field to retrieve by.
	 * @param mixed               $value            The value to search by.
	 * @param EDD\Compat\Customer $edd_customers_db Customer database class. Deprecated in 3.0.
	 */
	$found = apply_filters( 'edd_pre_get_customer', null, $field, $value, $customers_db );

	if ( null !== $found ) {
		return $found;
	}

	$customers = new EDD\Database\Queries\Customer();
	if ( 'email' === $field ) {
		$customer_emails = new EDD\Database\Queries\Customer_Email_Address();
		$customer_email  = $customer_emails->get_item_by( 'email', $value );

		$customer = false;
		if ( ! empty( $customer_email->customer_id ) ) {
			$customer  = $customers->get_item_by( 'id', $customer_email->customer_id );
		}
	} else {
		$customer  = $customers->get_item_by( $field, $value );
	}

	/**
	 * Filters the single Customer retrieved from the database based on field.
	 *
	 * @since 2.9.23
	 *
	 * @param EDD_Customer|false  $customer         Customer query result. False if no Customer is found.
	 * @param array               $args             Arguments used to query the Customer.
	 * @param EDD\Compat\Customer $edd_customers_db Customer database class. Deprecated in 3.0.
	 */
	$customer = apply_filters( "edd_get_customer_by_{$field}", $customer, $customers->query_vars, $customers_db );

	/**
	 * Filters the single Customer retrieved from the database.
	 *
	 * @since 2.9.23
	 *
	 * @param EDD_Customer|false $customer         Customer query result. False if no Customer is found.
	 * @param array              $args             Arguments used to query the Customer.
	 * @param EDD_DB_Customers   $edd_customers_db Customer database class.
	 */
	$customer = apply_filters( 'edd_get_customer', $customer, $customers->query_vars, $customers_db );

	return $customer;
}

/**
 * Get a field from a customer object.
 *
 * @since 3.0
 *
 * @param int    $customer_id Customer ID. Default `0`.
 * @param string $field       Field to retrieve from object. Default empty.
 *
 * @return mixed Null if customer does not exist. Value of Customer if exists.
 */
function edd_get_customer_field( $customer_id = 0, $field = '' ) {
	$customer = edd_get_customer( $customer_id );

	// Check that field exists.
	return isset( $customer->{$field} )
		? $customer->{$field}
		: null;
}

/**
 * Query for customers.
 *
 * @see \EDD\Database\Queries\Customer::__construct()
 *
 * @since 3.0
 *
 * @param array $args Arguments. See `EDD\Database\Queries\Customer` for
 *                    accepted arguments.
 * @return \EDD_Customer[] Array of `EDD_Customer` objects.
 */
function edd_get_customers( $args = array() ) {

	// Parse args
	$r = wp_parse_args( $args, array(
		'number' => 30
	) );

	if ( -1 == $r['number'] ) {
		_doing_it_wrong( __FUNCTION__, esc_html__( 'Do not use -1 to retrieve all results.', 'easy-digital-downloads' ), '3.0' );
		$r['number'] = 9999999;
	}

	// Instantiate a query object
	$customers = new EDD\Database\Queries\Customer();

	// Return customers
	return $customers->query( $r );
}

/**
 * Get total number of customers.
 *
 * @see \EDD\Database\Queries\Customer::__construct()
 *
 * @since 3.0
 *
 * @param array $args Arguments. See `EDD\Database\Queries\Customer` for
 *                    accepted arguments.
 * @return int Number of customers returned based on query arguments passed.
 */
function edd_count_customers( $args = array() ) {

	// Parse args
	$r = wp_parse_args( $args, array(
		'count' => true
	) );

	// Query for count(s)
	$customers = new EDD\Database\Queries\Customer( $r );

	// Return count(s)
	return absint( $customers->found_items );
}

/**
 * Query for and return array of customer counts, keyed by status.
 *
 * @since 3.0
 *
 * @param array $args Arguments. See `EDD\Database\Queries\Customer` for
 *                    accepted arguments.
 * @return array Customer counts keyed by status.
 */
function edd_get_customer_counts( $args = array() ) {

	// Parse arguments
	$r = wp_parse_args( $args, array(
		'count'   => true,
		'groupby' => 'status'
	) );

	// Query for count
	$counts = new EDD\Database\Queries\Customer( $r );

	// Format & return
	return edd_format_counts( $counts, $r['groupby'] );
}

/**
 * Return the role used to edit customers.
 *
 * @since 3.0
 *
 * @return string Role used to edit customers.
 */
function edd_get_edit_customers_role() {

	/**
	 * Filter role used to edit customers.
	 *
	 * @since 2.3
	 *
	 * @param string WordPress role used to edit customers. Default `edit_shop_payments`.
	 */
	return apply_filters( 'edd_edit_customers_role', 'edit_shop_payments' );
}

/**
 * Retrieve all of the IP addresses used by a customer.
 *
 * @since 3.0
 *
 * @param int $customer_id Customer ID.
 *
 * @return array Array of objects containing IP addresses.
 */
function edd_get_customer_ip_addresses( $customer_id = 0 ) {

	// Bail if no customer ID was passed.
	if ( empty( $customer_id ) ) {
		return array();
	}

	$customer = edd_get_customer( $customer_id );

	return $customer->get_ips();
}

/** Meta **********************************************************************/

/**
 * Add meta data field to a customer.
 *
 * @since 3.0
 *
 * @param int     $customer_id  Customer ID.
 * @param string  $meta_key     Meta data name.
 * @param mixed   $meta_value   Meta data value. Must be serializable if non-scalar.
 * @param bool    $unique       Optional. Whether the same key should not be added.
 *                              Default false.
 *
 * @return int|false Meta ID on success, false on failure.
 */
function edd_add_customer_meta( $customer_id, $meta_key, $meta_value, $unique = false ) {
	return add_metadata( 'edd_customer', $customer_id, $meta_key, $meta_value, $unique );
}

/**
 * Remove meta data matching criteria from a customer.
 *
 * You can match based on the key, or key and value. Removing based on key and
 * value, will keep from removing duplicate meta data with the same key. It also
 * allows removing all meta data matching key, if needed.
 *
 * @since 3.0
 *
 * @param int     $customer_id  Customer ID.
 * @param string  $meta_key     Meta data name.
 * @param mixed   $meta_value   Optional. Meta data value. Must be serializable if
 *                              non-scalar. Default empty.
 *
 * @return bool True on success, false on failure.
 */
function edd_delete_customer_meta( $customer_id, $meta_key, $meta_value = '' ) {
	return delete_metadata( 'edd_customer', $customer_id, $meta_key, $meta_value );
}

/**
 * Retrieve customer meta field for a customer.
 *
 * @since 3.0
 *
 * @param int     $customer_id  Customer ID.
 * @param string  $key          Optional. The meta key to retrieve. By default, returns
 *                              data for all keys. Default empty.
 * @param bool    $single       Optional, default is false.
 *                              If true, return only the first value of the specified meta_key.
 *                              This parameter has no effect if meta_key is not specified.
 *
 * @return mixed Will be an array if $single is false. Will be value of meta data
 *               field if $single is true.
 */
function edd_get_customer_meta( $customer_id, $key = '', $single = false ) {
	return get_metadata( 'edd_customer', $customer_id, $key, $single );
}

/**
 * Update customer meta field based on customer ID.
 *
 * Use the $prev_value parameter to differentiate between meta fields with the
 * same key and customer ID.
 *
 * If the meta field for the customer does not exist, it will be added.
 *
 * @since 3.0
 *
 * @param int     $customer_id  Customer ID.
 * @param string  $meta_key     Meta data key.
 * @param mixed   $meta_value   Meta data value. Must be serializable if non-scalar.
 * @param mixed   $prev_value   Optional. Previous value to check before removing.
 *                              Default empty.
 *
 * @return int|bool Meta ID if the key didn't exist, true on successful update,
 *                  false on failure.
 */
function edd_update_customer_meta( $customer_id, $meta_key, $meta_value, $prev_value = '' ) {
	return update_metadata( 'edd_customer', $customer_id, $meta_key, $meta_value, $prev_value );
}

/**
 * Delete everything from customer meta matching meta key.
 *
 * @since 3.0
 *
 * @param string $meta_key Key to search for when deleting.
 *
 * @return bool Whether the customer meta key was deleted from the database.
 */
function edd_delete_customer_meta_by_key( $meta_key ) {
	return delete_metadata( 'edd_customer', null, $meta_key, '', true );
}

/** Customer Addresses **********************************************************/

/**
 * Get a customer address by ID.
 *
 * @internal This method is named edd_fetch_customer_address as edd_get_customer_address
 *           exists for backwards compatibility purposes and returns an array instead of
 *           an object.
 *
 * @since 3.0
 *
 * @param int $customer_address_id Customer address ID.
 * @return EDD\Customers\Customer_Address Customer address object.
 */
function edd_fetch_customer_address( $customer_address_id = 0 ) {
	$customer_addresses = new EDD\Database\Queries\Customer_Address();

	// Return customer address.
	return $customer_addresses->get_item( $customer_address_id );
}

/**
 * Add a customer address.
 *
 * @since 3.0
 *
 * @param array $data {
 *     Array of customer address data. Default empty.
 *
 *     The `date_created` and `date_modified` parameters do not need to be passed.
 *     They will be automatically populated if empty.
 *
 *     @type int    $customer_id   Customer ID. Default `0`.
 *     @type string $type          Address type. Default `billing`.
 *     @type string $status        Address status, if used or not. Default `active`.
 *     @type string $address       First line of address. Default empty.
 *     @type string $address2      Second line of address. Default empty.
 *     @type string $city          City. Default empty.
 *     @type string $region        Region. See `edd_get_shop_states()` for
 *                                 accepted values. Default empty.
 *     @type string $postal_code   Postal code. Default empty.
 *     @type string $country       Country. See `edd_get_country_list()` for
 *                                 accepted values. Default empty.
 *     @type string $date_created  Optional. Automatically calculated on add/edit.
 *                                 The date & time the address was inserted.
 *                                 Format: YYYY-MM-DD HH:MM:SS. Default empty.
 *     @type string $date_modified Optional. Automatically calculated on add/edit.
 *                                 The date & time the address was last modified.
 *                                 Format: YYYY-MM-DD HH:MM:SS. Default empty.
 * }
 * @return int|false ID of newly created customer address, false on error.
 */
function edd_add_customer_address( $data = array() ) {

	// A customer ID must be supplied for every address inserted.
	if ( empty( $data['customer_id'] ) ) {
		return false;
	}

	$customer_addresses = new EDD\Database\Queries\Customer_Address();

	return $customer_addresses->add_item( $data );
}

/**
 * Delete a customer address.
 *
 * @since 3.0
 *
 * @param int $customer_address_id Customer address ID.
 * @return int|false `1` if the adjustment was deleted successfully, false on error.
 */
function edd_delete_customer_address( $customer_address_id = 0 ) {
	$customer_addresses = new EDD\Database\Queries\Customer_Address();

	return $customer_addresses->delete_item( $customer_address_id );
}

/**
 * Update a customer address.
 *
 * @since 3.0
 *
 * @param int   $customer_address_id Customer address ID.
 * @param array $data {
 *     Array of customer address data. Default empty.
 *
 *     @type int    $customer_id   Customer ID. Default `0`.
 *     @type string $type          Address type. Default `billing`.
 *     @type string $status        Address status, if used or not. Default `active`.
 *     @type string $address       First line of address. Default empty.
 *     @type string $address2      Second line of address. Default empty.
 *     @type string $city          City. Default empty.
 *     @type string $region        Region. See `edd_get_shop_states()` for
 *                                 accepted values. Default empty.
 *     @type string $postal_code   Postal code. Default empty.
 *     @type string $country       Country. See `edd_get_country_list()` for
 *                                 accepted values. Default empty.
 *     @type string $date_created  Optional. Automatically calculated on add/edit.
 *                                 The date & time the adjustment was inserted.
 *                                 Format: YYYY-MM-DD HH:MM:SS. Default empty.
 *     @type string $date_modified Optional. Automatically calculated on add/edit.
 *                                 The date & time the adjustment was last modified.
 *                                 Format: YYYY-MM-DD HH:MM:SS. Default empty.
 * }
 *
 * @return int|false Number of rows updated if successful, false otherwise.
 */
function edd_update_customer_address( $customer_address_id = 0, $data = array() ) {
	$customer_addresses = new EDD\Database\Queries\Customer_Address();

	return $customer_addresses->update_item( $customer_address_id, $data );
}

/**
 * Get a customer address by a specific field value.
 *
 * @since 3.0
 *
 * @param string $field Database table field.
 * @param string $value Value of the row.
 *
 * @return \EDD\Customers\Customer_Address|false Customer_Address if successful,
 *                                               false otherwise.
 */
function edd_get_customer_address_by( $field = '', $value = '' ) {
	$customer_addresses = new EDD\Database\Queries\Customer_Address();

	// Return customer address
	return $customer_addresses->get_item_by( $field, $value );
}

/**
 * Query for customer addresses.
 *
 * @see \EDD\Database\Queries\Customer_Address::__construct()
 *
 * @since 3.0
 *
 * @param array $args Arguments. See `EDD\Database\Queries\Customer_Address` for
 *                    accepted arguments.
 * @return \EDD\Customers\Customer_Address[] Array of `Customer_Address` objects.
 */
function edd_get_customer_addresses( $args = array() ) {

	// Parse args
	$r = wp_parse_args( $args, array(
		'number' => 30
	) );

	// Instantiate a query object
	$customer_addresses = new EDD\Database\Queries\Customer_Address();

	// Return addresses
	return $customer_addresses->query( $r );
}

/**
 * Count customer addresses.
 *
 * @see \EDD\Database\Queries\Customer_Address::__construct()
 *
 * @since 3.0
 *
 * @param array $args Arguments. See `EDD\Database\Queries\Customer_Address` for
 *                    accepted arguments.
 * @return int Number of customer addresses returned based on query arguments passed.
 */
function edd_count_customer_addresses( $args = array() ) {

	// Parse args
	$r = wp_parse_args( $args, array(
		'count' => true
	) );

	// Query for count(s)
	$customer_addresses = new EDD\Database\Queries\Customer_Address( $r );

	// Return count(s)
	return absint( $customer_addresses->found_items );
}

/**
 * Maybe add a customer address. Only unique addresses will be added. Used
 * by `edd_build_order()` and `edd_add_manual_order()` to maybe add order
 * addresses to the customer addresses table. Also used by the data migrator
 * class when migrating orders from 2.9.
 *
 * @since 3.0
 *
 * @param int   $customer_id Customer ID.
 * @param array $data {
 *     Array of customer address data. Default empty.
 *
 *     @type string $type          Address type. Default `billing`.
 *     @type string $status        Address status, if used or not. Default `active`.
 *     @type string $address       First line of address. Default empty.
 *     @type string $address2      Second line of address. Default empty.
 *     @type string $city          City. Default empty.
 *     @type string $region        Region. See `edd_get_shop_states()` for
 *                                 accepted values. Default empty.
 *     @type string $postal_code   Postal code. Default empty.
 *     @type string $country       Country. See `edd_get_country_list()` for
 *                                 accepted values. Default empty.
 *     @type string $date_created  Optional. Automatically calculated on add/edit.
 *                                 The date & time the address was inserted.
 *                                 Format: YYYY-MM-DD HH:MM:SS. Default empty.
 *     @type string $date_modified Optional. Automatically calculated on add/edit.
 *                                 The date & time the address was last modified.
 *                                 Format: YYYY-MM-DD HH:MM:SS. Default empty.
 * }
 *
 * @return int|false ID of the insert customer address. False otherwise.
 */
function edd_maybe_add_customer_address( $customer_id = 0, $data = array() ) {

	// Bail if nothing passed.
	if ( empty( $customer_id ) || empty( $data ) ) {
		return false;
	}

	// Set up an array with empty address keys. If all of these are empty in $data, the address should not be added.
	$empty_address    = array(
		'address'     => '',
		'address2'    => '',
		'city'        => '',
		'region'      => '',
		'country'     => '',
		'postal_code' => '',
	);
	$address_to_check = array_intersect_key( $data, $empty_address );
	$address_to_check = array_filter( $address_to_check );
	if ( empty( $address_to_check ) ) {
		return false;
	}
	$address_to_check['customer_id'] = $customer_id;
	$address_to_check['type']        = empty( $data['type'] ) ? 'billing' : $data['type'];

	// Check if this address is already assigned to the customer.
	$address_exists = edd_get_customer_addresses( $address_to_check );
	if ( ! empty( $address_exists ) ) {
		if ( 'billing' === $address_to_check['type'] ) {
			edd_update_customer_address( $address_exists[0], array( 'is_primary' => true ) );
		}
		return false;
	}

	$data['customer_id'] = $customer_id;
	if ( 'billing' === $address_to_check['type'] ) {
		$data['is_primary'] = true;
	}

	// Add the new address to the customer record.
	return edd_add_customer_address( $data );
}

/**
 * Query for and return array of customer address counts, keyed by status.
 *
 * @see \EDD\Database\Queries\Customer_Address::__construct()
 *
 * @since 3.0
 *
 * @param array $args Arguments. See `EDD\Database\Queries\Customer_Address` for
 *                    accepted arguments.
 * @return array Customer address counts keyed by status.
 */
function edd_get_customer_address_counts( $args = array() ) {

	// Parse args
	$r = wp_parse_args( $args, array(
		'count'   => true,
		'groupby' => 'status'
	) );

	// Query for count
	$counts = new EDD\Database\Queries\Customer_Address( $r );

	// Format & return
	return edd_format_counts( $counts, $r['groupby'] );
}

/** Customer Email Addresses *************************************************/

/**
 * Add a customer email address.
 *
 * @since 3.0
 *
 * @param array $data {
 *     Array of customer email address data. Default empty.
 *
 *     The `date_created` and `date_modified` parameters do not need to be passed.
 *     They will be automatically populated if empty.
 *
 *     @type int    $customer_id   Customer ID. Default `0`.
 *     @type string $type          Email address type. Default `secondary`.
 *     @type string $status        Email address type. Default `active`.
 *     @type string $email         Email address. Default empty.
 *     @type string $date_created  Optional. Automatically calculated on add/edit.
 *                                 The date & time the email address was inserted.
 *                                 Format: YYYY-MM-DD HH:MM:SS. Default empty.
 *     @type string $date_modified Optional. Automatically calculated on add/edit.
 *                                 The date & time the email address was last
 *                                 modified. Format: YYYY-MM-DD HH:MM:SS. Default empty.
 * }
 * @return int|false ID of newly created customer email address, false on error.
 */
function edd_add_customer_email_address( $data ) {

	// A customer ID and email must be supplied for every address inserted.
	if ( empty( $data['customer_id'] ) || empty( $data['email'] ) ) {
		return false;
	}

	// Instantiate a query object.
	$customer_email_addresses = new EDD\Database\Queries\Customer_Email_Address();

	// Check if the address already exists for this customer.
	$existing_addresses = $customer_email_addresses->query(
		array(
			'customer_id' => $data['customer_id'],
			'email'       => $data['email'],
		)
	);
	if ( ! empty( $existing_addresses ) ) {
		return false;
	}

	// Add the email address to the customer.
	return $customer_email_addresses->add_item( $data );
}

/**
 * Delete a customer email address.
 *
 * @since 3.0
 *
 * @param int $customer_email_address_id Customer email address ID.
 * @return int|false `1` if the customer email address was deleted successfully,
 *                   false on error.
 */
function edd_delete_customer_email_address( $customer_email_address_id ) {
	$customer_email_addresses = new EDD\Database\Queries\Customer_Email_Address();

	return $customer_email_addresses->delete_item( $customer_email_address_id );
}

/**
 * Update a customer email address.
 *
 * @since 3.0
 *
 * @param int   $customer_email_address_id Customer email address ID.
 * @param array $data {
 *     Array of customer email address data. Default empty.
 *
 *     @type int    $customer_id   Customer ID. Default `0`.
 *     @type string $type          Email address type. Default `secondary`.
 *     @type string $status        Email address type. Default `active`.
 *     @type string $email         Email address. Default empty.
 *     @type string $date_created  Optional. Automatically calculated on add/edit.
 *                                 The date & time the email address was inserted.
 *                                 Format: YYYY-MM-DD HH:MM:SS. Default empty.
 *     @type string $date_modified Optional. Automatically calculated on add/edit.
 *                                 The date & time the email address was last
 *                                 modified. Format: YYYY-MM-DD HH:MM:SS. Default empty.
 * }
 *
 * @return int|false Number of rows updated if successful, false otherwise.
 */
function edd_update_customer_email_address( $customer_email_address_id, $data = array() ) {
	$customer_email_addresses = new EDD\Database\Queries\Customer_Email_Address();

	return $customer_email_addresses->update_item( $customer_email_address_id, $data );
}

/**
 * Get a customer email address by ID.
 *
 * @since 3.0
 *
 * @param int $customer_email_address_id Customer email address ID.
 * @return \EDD\Customers\Customer_Email_Address|false Customer_Email_Address if
 *                                                     successful, false otherwise.
 */
function edd_get_customer_email_address( $customer_email_address_id ) {
	$customer_email_addresses = new EDD\Database\Queries\Customer_Email_Address();

	// Return customer email address
	return $customer_email_addresses->get_item( $customer_email_address_id );
}

/**
 * Get a customer email address by a specific field value.
 *
 * @since 3.0
 *
 * @param string $field Database table field.
 * @param string $value Value of the row.
 *
 * @return \EDD\Customers\Customer_Email_Address|false Customer_Email_Address if
 *                                                     successful, false otherwise.
 */
function edd_get_customer_email_address_by( $field = '', $value = '' ) {
	$customer_email_addresses = new EDD\Database\Queries\Customer_Email_Address();

	// Return customer email address
	return $customer_email_addresses->get_item_by( $field, $value );
}

/**
 * Query for customer email addresses.
 *
 * @see \EDD\Database\Queries\Customer_Email_Address::__construct()
 *
 * @since 3.0
 *
 * @param array $args Arguments. See `EDD\Database\Queries\Customer_Email_Address`
 *                    for accepted arguments.
 * @return \EDD\Customers\Customer_Email_Address[] Array of `Customer_Email_Address` objects.
 */
function edd_get_customer_email_addresses( $args = array() ) {

	// Parse args
	$r = wp_parse_args( $args, array(
		'number' => 30
	) );

	// Instantiate a query object
	$customer_email_addresses = new EDD\Database\Queries\Customer_Email_Address();

	// Return customer email addresses
	return $customer_email_addresses->query( $r );
}

/**
 * Count customer addresses.
 *
 * @see \EDD\Database\Queries\Customer_Email_Address::__construct()
 *
 * @since 3.0
 *
 * @param array $args Arguments. See `EDD\Database\Queries\Customer_Email_Address`
 *                    for accepted arguments.
 * @return int Number of customer email addresses returned based on query arguments passed.
 */
function edd_count_customer_email_addresses( $args = array() ) {

	// Parse args
	$r = wp_parse_args( $args, array(
		'count' => true
	) );

	// Query for count(s)
	$customer_email_addresses = new EDD\Database\Queries\Customer_Email_Address( $r );

	// Return count(s)
	return absint( $customer_email_addresses->found_items );
}

/**
 * Query for and return array of customer email counts, keyed by status.
 *
 * @see \EDD\Database\Queries\Customer_Email_Address::__construct()
 *
 * @since 3.0
 *
 * @param array $args Arguments. See `EDD\Database\Queries\Customer_Email_Address`
 *                    for accepted arguments.
 * @return array Customer email addresses keyed by status.
 */
function edd_get_customer_email_address_counts( $args = array() ) {

	// Parse args
	$r = wp_parse_args( $args, array(
		'count'   => true,
		'groupby' => 'status'
	) );

	// Query for count
	$counts = new EDD\Database\Queries\Customer_Email_Address( $r );

	// Format & return
	return edd_format_counts( $counts, $r['groupby'] );
}