Introducing EDD_Payment

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.

Background

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:
https://gist.github.com/cklosowski/29b6c4b245355cfc32cd

You can see in this, that much of the code is used in creating a properly formatted set of arrays to nest inside the $payment_data array.

Here’s the same type of payment created, with EDD_Payment:
https://gist.github.com/cklosowski/0df45b1d476c71357ee7

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.

Backwards compatible

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 EDD_Payment.

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 = 'lisa@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 = 'john@example.org'; // 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.

Testing

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.