In the recent weeks we’ve told you about the upcoming Easy Digital Downloads 2.5 release. Version 2.5, as stated, has been in development for quite some time, and most of that is due to one major enhancement being introduced: The EDD_Payment class.
A centralized way of interacting and manipulating a payment in EDD has been something we’ve needed for a while. Prior to 2.5 and EDD_Payment, to get or set any data for a payment you had to do a series of calls to the
edd_get/update_payment_meta() functions, which was simply a wrapper for
get/update_post_meta(). Not only was getting and updating payments lengthy, but creating them was especially painstaking. While we provided
edd_insert_payment() as a helper function, we relied on you (the developers), to provide us with a properly crafted array of data to create a payment. The introduction of EDD_Payment is our first step in giving you a better experience in payment management.
A Quick Example
So before getting into too much detail, let’s take a quick look at how you would have inserted a payment prior to EDD 2.5:
You can see in this, that much of the code is used in creating a properly formatted set of arrays to nest inside the
Here’s the same type of payment created, with EDD_Payment:
You can quickly identify that it’s much more friendly to interact with. No more creating arrays of data, no more price determination. EDD_Payment even handles the the inserting of the payment if it detects you are creating a new payment.
One of the primary efforts of
EDD_Payment was making it backwards compatible. If you use the
edd_insert_payment() function or any of the helper functions to get or update payment meta, we’ve updated those functions to use
EDD_Payment, so you don’t need to worry. Along with that, all the filters that existed in the helper functions have been moved into
EDD_Payment so that when you call
new EDD_Payment( 123 ), anything that uses those filters will be executed as well, and applied to the class you just instantiated.
More practical use cases
The above example is a pretty in depth example of creating a payment, so let’s dive into some smaller examples of ways to use the
Creating a payment
$payment = new EDD_Payment(); // Instantiates a payment object $payment->add_download( 12 ); // Adds download id 12 to the payment at it's default price $payment->email = 'firstname.lastname@example.org'; // Email is required for a payment $payment->status = 'complete'; // Completes the payment $payment->save(); // Writes to the database any changes that were made
Editing an existing payment
$payment = new EDD_Payment( 42 ); // Loads the information for Payment ID 42 $payment->email = 'email@example.com'; // Changes the email address on the payment $payment->save();
Changing a payment status
$payment = new EDD_Payment( 1337 ); $payment->status = 'revoked'; $payment->save();
Adding a variable priced download
$payment = new EDD_Payment( 1942 ); $args = array( 'price_id' => 1, // Variable price ID 'item_price' => 0.00, // Makes the item free ); $payment->add_download( 23, $args ); // Adds Download ID 23, variable price 1 to the payment $payment->save();
Adding a download with options
$payment = new EDD_Payment( 2008 ); $args = array( 'item_price' => 4.00, ); $options = array( 'is_renewal' => true, ); $payment->add_download( 28, $args, $options ); $payment->save();
Removing a download
$payment = new EDD_Payment( 2008 ); $payment->remove_download( 23 ); $payment->save();
Removing a download with variable pricing
$payment = new EDD_Payment( 2008 ); $args = array( 'price_id' => 1, ); $payment->remove_download( 28, $args ); $payment->save();
EDD_Payment as a Final
If you dig into the Class, the first thing you’ll notice is that we’ve marked the
EDD_Payment class as a
final, which means you cannot extend it via your own class…yet. This is to help us really solidify it as a class prior to you, the developers, taking it to the next level and doing awesome stuff with
EDD_Payment. Our intentions are to remove the
final designation prior to the 2.6 release, but as always that could change depending on what we run into.
As with all beta releases, we encourage testing this out in your development environments and letting us know what you think of the class, and where it could use improvement. It’s been a long haul getting this ready for you to use. So please leave us some feedback in the comments or over on the Github issue we have for this enhancement.