fix: command to fix active subs w/ missing next_payment dates

[dkoo]

All Submissions:

• Have you followed the Newspack Contributing guideline?
• Does your code follow the WordPress' coding standards and VIP Go coding standards?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?

Changes proposed in this Pull Request:

Adds a CLI command to report and and optionally fix active or pending subscriptions that have a next_payment date in the past, or are missing a next_payment date entirely. This could happen if Action Scheduler jobs failed to update or renew subscriptions as scheduled, or as a result of missing data on migrated subscriptions.

How to test the changes in this Pull Request:

1. Create some subscriptions with missing next_payment dates. This must be done using wp shell (replace 888 with a subscription ID on your test site) as the UI has safeguards to prevent the deletion of next payment dates. Make sure to do this for at least a few subscriptions that meet the following criteria:

• A subscription started within the past 90 days
• A subscription started more than 90 days ago
• A subscription with no end date
• A subscription with an end date BEFORE when the next payment date should be
• A subscription with an end date AFTER when the next payment date
• A subscription with at least one completed order
• A subscription with no successful orders (you may need to create this one manually in the admin dashboard)

> $sub = wcs_get_subscription( 888 )
= WC_Subscription {#15359
    +refunds: null,
    +order_type: "shop_subscription",
  }

> $sub->delete_date( 'next_payment' ) // OR, update the `next_payment` date to a date in the past with $sub->update_dates( [ 'next_payment' => '2024-09-01 21:13:36' ] )
= null

> $sub->save()
= 888

2. Run the new CLI command in dry run mode and confirm it reports the subscriptions and missed total revenue, but without actually updating the subscriptions' next_payment dates:

$ wp newspack-woocommerce fix_missing_next_payment_dates --dry-run

===================
=     DRY RUN     =
===================


Fetching active subscriptions with missing or missed next_payment dates...

+-----+--------+---------------------+---------------------+---------------------+----------------+----------------+--------------+
| ID  | status | start_date          | next_payment_date   | end_date            | billing_period | missed_periods | missed_total |
+-----+--------+---------------------+---------------------+---------------------+----------------+----------------+--------------+
| 969 | active | 2023-11-04 20:25:12 | 0                   | 2024-11-04 22:25:44 | month          | 12             | 2400         |
| 888 | active | 2024-06-01 21:13:36 | 2024-12-01 21:13:36 | 0                   | month          | 5              | 250          |
| 475 | active | 2024-08-05 20:36:11 | 2024-11-11 19:24:45 | 0                   | month          | 0              | 0            |
+-----+--------+---------------------+---------------------+---------------------+----------------+----------------+--------------+
Success: Finished processing 3 subscriptions. Total missed revenue: $2,650.00

3. In the reported results, ensure the following are true:

• Only subscriptions started in the past 90 days are handled
• Subscriptions with no end date get a newly calculated next_payment date (reported in the next_payment_date column)
• Subscriptions with a far-future end date should get a newly calculated next_payment date before the end date
• Subscriptions with an imminent end date don't get a new next_payment date (they should show 0 in the next_payment_date column)
• Missed periods and total values accurately reflect the number of renewals that should have occurred since the most recent completed renewal order (if any) or the subscription start (if no orders), and based on the subscription product's billing interval and period (e.g. every month/year, every 6 months, etc.).

4. Re-run the command with a --start-date arg in YYYY-MM-DD format and confirm that the command only reports subscriptions started after the given date.
5. Re-run the command without --dry-run and confirm that the command provides the same report data as in step 2, but also updates the subscriptions with the reported next_payment dates.

Other information:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes, as applicable?
• Have you successfully ran tests with your changes locally?

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1206214865188773

[dkoo]

@adekbadek just thought of a case that we need to handle with this. The script should check subscriptions for an end date, and if the end date is before the calculated next payment date, it should bail. Otherwise those subscriptions may get renewed instead of properly expiring.

[adekbadek]

Ah, good catch! Makes sense. Since this is "business-sensitive", would mind adding unit tests here?

[dkoo]

Great idea to add unit tests! I'll keep this PR alive until we add those and handle the "end dates" scenario above.

[dkoo]

@adekbadek 9686c86 adds handling for end dates (if a subscription has an end date that will occur before the calculated next payment date, a next payment date will not be set). It also calculates "missed" billing periods by starting from the last successful order, if one exists.

ff7c665 adds a new suite of unit tests and fixes a couple of minor issues exposed by the test suite.

[adekbadek]

Nit: the function name suggests the the return value is a date. Could be something along the lines of validate_subscription_dates.

[dkoo]

Updated to validate_subscription_dates in 879ba1a

[dkoo]

@adekbadek Merging this one since you preapproved it!

[github-actions]

Hey @dkoo, good job getting this PR merged! 🎉

Now, the needs-changelog label has been added to it.

Please check if this PR needs to be included in the "Upcoming Changes" and "Release Notes" doc. If it doesn't, simply remove the label.

If it does, please add an entry to it to our shared document, with screenshots and testing instructions if applicable, then remove the label.

Thank you! ❤️

[matticbot]

🎉 This PR is included in version 5.7.0-alpha.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[matticbot]

🎉 This PR is included in version 5.7.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀