Easy Digital Downloads 3.0-beta1 now ready for testing

We’re pleased to announce that the first beta for Easy Digital Downloads 3.0 is now available! This has been a long time coming, and we want to thank you all for your patience and understanding while it’s been in development.

Important Note: This beta release is NOT production ready. It should only be tested on development sites. Do not install it on your live site.

Our goals for the first 3.0 beta

Easy Digital Downloads 3.0 is not yet a finished product. The point of this first beta release is not to test the plugin as a whole, but to focus on these key things:

  1. Early testing on our migration process, to ensure all necessary data is migrated to its new place and that there are no issues with the data transfer or backwards compatibility.
  2. Giving third party developers a chance to see how the code base has changed in 3.0, and the opportunity to update their extensions to be compatible.

Official extensions that are compatible with 3.0:

The following extensions have been already updated to work with 3.0 and may be used in testing:

  • Auto Register, version 1.3.11+
  • Braintree Gateway, version 1.1.6+
  • Commissions, version 3.4.11+
  • Gateway Fees
  • PDF Invoices, version 2.2.27+
  • Recurring, version 2.10.1+
  • Software Licensing, version 3.7+
  • Stripe Gateway, version 2.8+
    * When checking out with Stripe, you may see a debug notice about addresses being stored incorrectly. This will be addressed in version 2.8.1.

What’s not ready for testing

Order refunds are still undergoing some changes, particularly with regards to refunding fees, so we do not recommend testing refunds or updating any of your own refund-related code. We hope for this to be ready for the beta2 release.

System requirements

In order to run EDD 3.0 you’ll need to have the following minimum versions:

  • PHP 5.6+
  • WordPress 4.9+

Note: If you installed EDD 3.0 back in 2018 but have not pulled the release branch since then, we recommend starting with an entirely fresh install. This is because we’ve removed some incremental database upgrades from the 3.0 development branch that were introduced in 2018. If you’re installing or upgrading to 3.0 for the first time then this does not affect you.

Installing 3.0-beta1

The 3.0 beta release can be downloaded from GitHub and installed as normal. After installation, new database tables will be installed in the background and you will be prompted to run the 3.0 migration.

Testing the custom tables migration

In 3.0 we migrate the bulk of EDD data out of the WordPress core tables (posts, postmeta, etc.) and into our new custom tables. This includes:

  • Discounts
  • Payments
  • Customer addresses
  • Customer email addresses
  • Logs
  • Order notes
  • Customer notes

The migration can either be performed through an admin UI, or run through WP-CLI using this command:

wp edd v30_migration
EDD 3.0 migration UI

While testing the migration, double check that all your data has been migrated successfully and that none has been lost — this is particularly true of any custom data you may have added.

Custom payment meta to watch out for

_edd_payment_meta

If you’ve added any custom keys to the _edd_payment_meta array then those will be inserted into our new wp_edd_ordermeta table using the key payment_meta. Just like before, this will be saved as a serialized array.

Note: Calls to edd_get_payment_meta( $payment_id, '_edd_payment_meta' ) are still fully backwards compatible and will include your custom keys/values. However, the backwards compatibility layers do mean that this old method will be slower than our newer edd_get_order_meta() functions so we recommend updating if possible.

Cart item options

In 2.9, _edd_payment_meta included an array that looked like this:

array(
    'cart_details' => array(
        array(
            'item_number' => array(
                'options' => array(
                    'price_id' => 1,
                    'quantity' => 1,
                    // More
                )
            )
        )
    )
)

Any keys added to that options array will be migrated to our new wp_edd_order_itemmeta table. This is meta associated with an individual order item, rather than the order as a whole.

Note: Retrieving this information via edd_get_payment_meta() or edd_get_payment_meta_cart_details() is still fully backwards compatible in 3.0. However, the backwards compatibility layers do mean that this old method will be slower than our newer edd_get_order_meta() functions so we recommend updating if possible.

Custom meta keys

Any custom pieces of meta data associated with a payment will be transferred exactly over to our new wp_edd_ordermeta table. Only the storage location has changed; the data and format remains exactly the same.

Updating your integrations for 3.0

Plugins can be compatible with both EDD 2.9 and 3.0 at the same time. However, a few methods are no longer compatible with 3.0 and your code may need to be updated accordingly.

Ensure you’re not using “post” helper functions on payments, discounts, or logs

In 3.0 you can no longer use “post”-related helper functions on payment, log, or discount code objects. This includes get_post(), get_post_meta(), and more. You will need to update your code to use our wrapper functions instead.

Here’s a detailed list of examples:

Payments/orders

Note: in 3.0, payments are now referred to as “orders”, which is reflected in the new function names.

Retrieving a payment/order

// NO LONGER VALID
$payment = get_post( $payment_id );

// Valid in both 2.9 and 3.0
$payment = edd_get_payment( $payment_id );

// Valid in 3.0 only
$payment = edd_get_order( $payment_id );

Retrieving meta attached to a payment/order

// NO LONGER VALID
$meta = get_post_meta( $payment_id, 'your_meta_key_here', true );

// Valid in both 2.9 and 3.0
$meta = edd_get_payment_meta( $payment_id, 'your_meta_key_here', true );

// Valid in 3.0 only
$meta = edd_get_order_meta( $payment_id, 'your_meta_key_here', true );

Adding or updating payment/order meta

// NO LONGER VALID
update_post_meta( $payment_id, 'your_meta_key_here', 'your meta value' );

// Valid in both 2.9 and 3.0
edd_update_payment_meta( $payment_id, 'your_meta_key_here', 'your meta value' );

// Valid in 3.0 only
edd_update_order_meta( $payment_id, 'your_meta_key_here', 'your meta value' );

Querying for payment/order records

// NO LONGER VALID
$payments = get_posts( array(
    'post_type'   => 'edd_payment',
    'post_status' => 'publish'
) );

// NO LONGER VALID
$payments = new WP_Query( ( array(
    'post_type'   => 'edd_payment',
    'post_status' => 'publish'
) );

// Valid in both 2.9 and 3.0
$payments = edd_get_payments( array(
    'status' => 'publish'
) );

// Valid in 3.0 only
$payments = edd_get_orders( array(
    'status' => 'complete'
) );

Discounts

Retrieving a discount code

// NO LONGER VALID
$discount = get_post( $discount_id );

// Valid in both 2.9 and 3.0
// Get by ID
$discount = edd_get_discount( $discount_id );

// Get by code
$discount = edd_get_discount_by_code( 'BFCM2021' );

Querying for discount codes

// NO LONGER VALID
$discounts = get_posts( array(
    'post_type'   => 'edd_discount',
    'post_status' => array( 'active', 'inactive' )
) );

// Valid in both 2.9 and 3.0
$discounts = edd_get_discounts( array(
    'post_status' => array( 'active', 'inactive' )
) );

Retrieving meta attached to a discount

// NO LONGER VALID
$meta = get_post_meta( $discount_id, 'your_meta_key_here', true );

// Valid in both 2.9 and 3.0
$discount = edd_get_discount( $discount_id );
$discount->get_meta( 'your_meta_key_here', true );

// Valid in 3.0 only
edd_get_adjustment_meta( $discount_id, 'your_meta_key_here', true );

Adding or updating meta

// NO LONGER VALID
update_post_meta( $discount_id, 'your_meta_key_here', 'your meta value' );

// Valid in both 2.9 and 3.0
$discount = edd_get_discount( $discount_id );
$discount->update_meta( 'your_meta_key_here', 'your meta value' );

// Valid in 3.0 only
edd_update_adjustment_meta( $discount_id, 'your_meta_key_here', 'your meta value' );

Logs

EDD has a class called EDD_Logging, which is available in 2.9 and fully backwards compatible in 3.0. If your code needs to be compatible with both versions, ensure you use this class for all querying and inserting.

Querying logs:

global $edd_logs;
$edd_logs->get_logs( $object_id, $log_type, $page_number );

Inserting a log:

global $edd_logs;
$edd_logs->insert( array(
    'log_type'    => 'gateway_error',
    'post_parent' => $download_id
) );

EDD 3.0 also comes with several new functions. Logs are split up into different database tables according to type: file download logs, API request logs, and generic logs. Here are the new functions for generic logs:

Querying logs:

$logs = edd_get_logs( array(
    'type'    => 'gateway_error',
    'user_id' => $user_id
) );

Inserting a log:

edd_add_log( array(
    'object_id'   => $object_id,
    'object_type' => $object_type,
    'user_id'     => $user_id,
    'type'        => $log_type,
    'title'       => $log_title,
    'content'     => $log_content
) );

Update raw queries on the wp_posts database table

In 3.0, most data has been migrated out of wp_posts and wp_postmeta. As a result, if you’re performing any raw queries on those tables, you may need to update your integration to query on our new tables instead in 3.0.

Here’s a before and after example of one of our own queries for download logs:

2.9 query on the posts/postmeta tables:

SELECT post_parent as downloaded_product_id, COUNT(post_parent) AS number_of_downloads, COUNT(DISTINCT meta_value) AS unique_passes_used
FROM {$wpdb->posts} p
LEFT JOIN {$wpdb->postmeta} pm ON pm.post_id = p.ID
WHERE meta_key = '_edd_log_all_access_pass_id'
AND meta_value LIKE '%_{$all_access_product_id}_%'
AND post_date_gmt > %s
AND post_date_gmt < %s
GROUP BY post_parent
ORDER BY COUNT(post_parent) DESC;

3.0 query on the file_downloads/file_downloadmeta tables:

SELECT product_id as downloaded_product_id, COUNT(product_id) as number_of_downloads, COUNT(DISTINCT meta_value) as unique_passes_used
FROM {$wpdb->edd_logs_file_downloads} l
INNER JOIN {$wpdb->edd_logs_file_downloadmeta} lm ON l.id = lm.edd_logs_file_download_id
WHERE meta_key = '_edd_log_all_access_pass_id'
AND meta_value LIKE '%_{$all_access_product_id}_%'
AND date_created > %s
AND date_created < %s
GROUP BY product_id
ORDER BY COUNT(product_id) DESC

With custom queries like this, you will need to load one version if the site is running EDD 2.9 or lower, and another version if the site is running 3.0+.

Reporting issues

EDD 3.0 is still in active development on GitHub. If you encounter any bugs, please search through our existing issues. If there’s not already an open issue, you may create a new one (after reading our Contributor Guidelines). Please prefix all issues with “3.0 -” so we know it pertains to the 3.0 release.

12 responses... add one

When i see the post above, i can only guess how much work went into EDD 3.0. Great, that there is a light at the end of the tunnel πŸ™‚
Keep up the good work!
Matthias

Very exciting news. Already threw it up on a staging site and the first thing I did was head to the reporting dashboard. Amazing! πŸ‘ We’ve had to start righting some of our own queries to pull data because the reporting in the current version of EDD is well… not great. These new reports will help our business.

Keep up the great work.

Thanks Brian!

The new database schema is critical to these improved reports. Not only from a performance perspective, but what it allows us, and people who customize EDD to do. We’re excited for the possibilities that this will open up for the future.

Really appreciate all the work on this, team πŸ™ŒπŸ™. Great job.

I didn’t find any bugs but I wanted to leave some feedback here for others that might be testing out the beta.

I have ~4,000 orders & ~2,700 customers. I’m using recurring subscriptions & software licensing. The data migration took 10-15 minutes. No issues.

I spot checked a few orders, and checked all settings, and everything appears to have migrated successfully. Truly, a monumental task that should not go overlooked. I can’t even begin to wrap my head around the code/logic/brain power that went into this πŸ‘.

πŸ‘ Love the simplified left nav (and the other nav organization you did with tabs/links).
πŸ‘ Love the small UI tweaks.
πŸ‘ Love the new reports, especially the refund & renewal stats, as well as top customers.

Reports: Question: I noticed the “Acquisitions” report says “Legacy.” Does this mean you will eventually drop support for that extension in 3.x? Or just don’t plan to add a new graph for it?

Reports: Feedback: On the graphs that show sales & earnings, I have 5-10 sales with $300-400 in earnings. The sales line is super small and barely shows any variation down at the bottom. This isn’t very helpful. It would be great if you created a second Y-axis on the right side that more accurately depicted the lowest & highest sales number in that time period, and adjusted the line appropriately.

EDD Enhanced Ecommerce Tracking: I’m using this plugin from Ace Plugins by Jeroen Sormani. The current version (1.2.0.1) causes a fatal error when you install the beta. He hasn’t updated the plugin since July 2019. If this plugin is crucial for you, you might want to reach out to him and inquire about 3.0 compatibility.

Little Thing: For EDD… it’d be nice if you added a thousands separator to all numbersβ€”in reports, in the Sales column on the All Products page, Total Sales on the Dashboard widget, and others. I’m only in the 4 digits for sales right now, but hope to be in the 5 digits one day (thanks to your help πŸ˜‰). It would just add some nice consistency and improved legibility.

Thank you so much for all your feedback Dave — I’m thrilled to hear that the migration has gone well!

Acquisitions – The old method of adding reports is deprecated, but at this time we do not have any immediate plans to actually make it stop working entirely. Some day we might, but not immediately in 3.0 and not any time soon. We are currently working through updating all our add-ons to be 3.0 compatible, which also includes updating reports to use our new API. We haven’t gotten to this one yet, but we will! In short: you don’t need to be concerned.

Reports Sales & Earnings – Thanks for your feedback on this. I’ll make a note of it in GitHub so we can look into it.

Enhanced Ecommerce Tracking – Thanks for the report! We’ll see what we can do.

Thousands Separator – I’ll make a GitHub issue about this and we’ll address it. Appreciate the feedback!

I have 12k payments on my site. Testing 3.0 beta on my test site now and the upgrade process is taking hours.

Logs are the slowest part. I’ve also had it time out a few times and when I restart, it started back as 0% each time.

Hi there,

Sorry to hear you’re having difficulty with the migration. Have you tried using WP-CLI? That should be faster and avoid timeout problems.

For beta-2 we are hoping to be able to recover the exact part of the process you were on if you refresh, but right now it does revert back to the start.

Leave a Reply

Your email address will not be published. Required fields are marked *