1014 lines
33 KiB
PHP
1014 lines
33 KiB
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'] );
|
|
}
|