Breaking changes to orders in Easy Digital Downloads 3.0

Since our last development update for Easy Digital Downloads 3.0, we have continued working away on this huge release.

Disclaimer: before we proceed, it’s important to note that this version of Easy Digital Downloads will bring significant changes and it is highly advised that all developers read through these changes thoroughly. We’ve made every effort to ensure backwards compatibility throughout the entire codebase, but any change has the potential to break some custom code, and we want to make everything go as smoothly as we can for everyone.

We have now completed our migration from payments to orders. Upgrade routines have been written that migrate payments from wp_posts and wp_postmeta across to our new custom database tables. The new schema allows for the complete overhaul we are bringing to reporting and boasts huge performance improvements.

Here at Sandhills Development, we pride ourselves in creating solutions that are backwards compatible.  However, with this migration there are some changes that will break custom implementations.

As part of the migration of payments, we’ve moved away from using -1 as user IDs.  Up until now, customers that do not have a user ID would get a user ID of -1 stored in the _edd_payment_meta meta key.  Going forwards, any customer that does not have a corresponding WordPress user ID will have the ID stored as 0.  The migration routine also converts all user IDs that were -1 to 0.  This will, unfortunately, break custom code that retrieves the meta value and checks specifically for -1 as it will no longer evaluate to true.

Another breaking change that arises is when using get_post() and get_post_status().  Both of these are WordPress Core methods and these will continue to work with all existing data that is migrated as our new backwards compatibility layer checks if the ID referred to a post of the edd_payment post type at which point our new database layer takes over.  However, this will not work for new orders that do not have a corresponding legacy ID stored.  In all cases, get_post() should not be used to fetch Easy Digital Downloads data, be it downloads or payments.  We have helper methods that handle the retrieval of this data from the database: edd_get_download() and edd_get_payment(), respectively.

Unfortunately, our receipt template also makes use of get_post() .  Of course, it will be updated to use our new query methods but it means that any developers that have extended the template will also have to adjust the shortcode-receipt.php template to change the get_post() call to edd_get_payment().  We are adding some code to automatically update the file to use the new method, however, if this is unsuccessful (perhaps due to file permissions), a notice will be displayed with a guide as to how to go about updating the file.

To update compatibility, in shortcode-receipt.php change $payment = get_post( $edd_receipt_args['id'] ); to $payment = edd_get_payment( $edd_receipt_args['id'] );.

Please note if you are using the get_post functions to retrieve downloads or payments, it is wise to update your code to use the aforementioned wrapper functions provided by EDD to be future-friendly.