Table of Contents
The EDD_Customer class is used for getting customer data, creating new customer entries, and editing existing customer entries. The values that may be managed with this class are:
Getting a Customer
Your reasons for getting Customer data can vary from simply rendering the info to using it for stats or logging or anything else. Here are the steps to get and render customer information.
Step 1, Get the data
In order to create a Customer object you must pass some sort of identifier when instantiating the class. This can be email address, Customer ID, or WordPress user ID.
$customer = new EDD_Customer( 'email@example.com' );
$customer = new EDD_Customer( 33 );
WordPress user ID
$customer = new EDD_Customer( 96, true );
Note: for the WordPress user ID you must pass a value of true as the second parameter, so that it knows to look at WordPress rather than EDD.
Step 2, Use the data
Now you can access properties of the customer object like this:
- $customer->id; // Customer ID
- $customer->user_id; // WordPress user ID
You can echo those, parse them; anything you wish.
Getting Customer Payment Data
The EDD_Customer class has a method called
get_payments(). This method will return an array of EDD_Payment objects. Example:
$customer = new EDD_Customer( 33 ); $payments = $customer->get_payments();
Now $payments will hold an array of EDD_Payment objects. For more information on what that array looks like, please see the docs on the EDD_Payment class.
Creating a Customer
First instantiate an object:
$customer = new EDD_Customer;
$args = array( 'user_id' => 12 'name' => 'Jose Canseco', 'email' => 'firstname.lastname@example.org', 'payment_ids' => '', 'purchase_value' => '', 'purchase_count' => '', 'notes' => 'Whatever note you\'d like', );
Note: the user_id above is a WordPress user ID number. It is only required if you want to associate your Customer with a WordPress user. If not, remove it from the array.
$customer->create( $args );
$args = array( 'email' => 'email@example.com', );
$customer->create( $args );
This creates a customer with only the email address provided, which works just fine.
Updating a Customer
Step 1, Get The Data.
Use the example code from "Getting A Customer" above.
Step 2, Update The Data
There are two ways of updating customer data with EDD_Customer. One is to use the update() method and update multiple fields at one time.
$customer = new EDD_Customer( 33 ); $update_args = array( 'email' => 'firstname.lastname@example.org', 'name' => 'Jose Canseco', );
Now customer 33 has an updated email address and a new note.
Note: updating the notes field with this method will wipe out any existing notes. Use the add_note() method mentioned below to add a new note.
Updating Specific Fields
Rather than using the general update() method listed above you should generally try to use one of the helper methods provided below. These provide specific limited functionality that can help reduce errors.
For each of the following methods you would first instantiate the customer class as above:
$customer = new EDD_Customer( 33 );
attach_payment() and remove_payment()
These are used for attaching and removing payments to and from a customer. They both take a payment_id as the first variable, and a boolean option as the second. The second will update stats if set to true.
$customer->attach_payment( 33, true );
$customer->remove_payment( 33, true );
increase_purchase_count() and decrease_purchase_count()
These are used to increase and decrease the number of purchases made by a single customer. They both simply take an integer, changing the stored value by that much.
$customer->increase_purchase_count( 1 );
$customer->decrease_purchase_count( 1 );
increase_value() and decrease_value()
These are used to increase and decrease the amount spent by a single customer. They both simply take a decimal number, to two places, changing the stored value by that much.
$customer->increase_value( 14.98 );
$customer->decrease_value( 3.00 );
This method returns notes left on the customer's account. It accepts 2 variables, the first for how many notes you want, and the second is an offset.
$customer->get_notes( 5 );// gets the first 5 notes
$customer->decrease_value( 5, 6 );// gets 5 notes starting at position 6, so notes 6-10
This method returns the number of notes on the customer's account. It takes no input.
This method accepts a string as input, and stores it as a new note on the customer's account. It preserves hard returns, but does not allow HTML.
$customer->add_note( 'This is a note. Isn\'t that cool?' );
Arbitrary customer meta may be managed using the meta functions built into the EDD_Customer class.
get_meta( $meta_key = '', $single = true )
get_meta simply takes a meta key and returns the value. If single is set to false it will always return an array.
add_meta( $meta_key = '', $meta_value, $unique = false )
add_meta accepts a meta_key and its value, but it also accepts a boolean for unique. If the third input is true then add_meta will only succeed if the meta_key does not previously exist. Returns false for failure. True for success.
update_meta( $meta_key = '', $meta_value, $prev_value = '' )
update_meta accepts a meta_key and the new value you wish to set for it. If you have multiple keys of the same name they will all be updated with the new value. The third input accepts a value to compare the previous value against. So if you already have several meta_keys of
foo but only one with a value of
bar, you could make
bar the third input and the update would only occur on that one. Returns false for failure. True for success.
delete_meta( $meta_key = '', $meta_value = '' )
delete_meta will delete all meta data with a matching key. If a value is also passed then both must match. Returns false for failure. True for success.
Customer Email Addresses
Each customer can have multiple email addresses, allowing them to purchase from more than one address, or purchase from one and get support from another. Each customer will also have a primary email address, which gets used as a default for the customer. In the Customer Management tab the UI looks like this:
The EDD_Customer class allows the developer to removes addresses from a customer and add addressed to a customer as well as make a specific address primary.
add_email( $email = '', $primary = false )
This function accepts an email address to add to the customer. If the second input is true, the new email address will be set as the primary address for the customer. Returns false for failure. True for success.
set_primary_email( $new_primary_email = '' )
This function accepts an email address and if the email address is already attached to this customer it will make it the primary email address for that customer. Returns false for failure. True for success.
remove_email( $email = '' )
This function accepts an email address and if the email address is already attached to this customer it removes it from that customer. Returns false for failure. True for success.