Add deprecated gateway migration workflow

[dparker1005]

What this does

Adds a guided sunset workflow for deprecated payment gateways on the Payment Settings page. When editing a deprecated gateway, admins now see a three-step panel:

1. Activate a new gateway — offers the Stripe Connect flow (or activates Stripe directly if already connected, including webhook setup), with a pointer to the PayPal Add On as an alternative.

2. Migrate subscriptions — a batched Action Scheduler workflow that processes every active subscription for the gateway in the current environment, with live progress, per-subscription logging, and a stop button. Two strategies:

   • Migrate to Stripe: each subscription is recreated at Stripe as a trialing subscription with no payment method (trial ends on the old next payment date, missing_payment_method => cancel). The member is emailed to add billing information before that date. Billing limits carry over as a remaining-payment count enforced by a $0 bridge order.
   • Cancel and set expiration dates: the membership expires on the old next payment date and the member is emailed to check out again.

   In both cases the old gateway subscription is cancelled last, so members are never left unnotified by a partial failure. Subscriptions without an upcoming payment date are skipped unless the Force option is enabled. Every outcome is recorded as complete / skipped / needs review in a downloadable migration log.

3. Remove gateway data — once no live subscriptions remain, deletes the stored credentials (PayPal-shared credentials only once no PayPal gateway needs them) and stops loading the gateway.

Implementation notes

• New includes/deprecated-gateways.php owns gateway loading (moved from includes/deprecated.php) plus the workflow: state machine in a per-gateway/environment option, batches chained through Action Scheduler with a unique initial action, and recovery designed so reruns are safe (crash-safe meta ordering, per-attempt Stripe idempotency keys, active-only placeholder adoption, already-processed subscriptions are skipped).
• The workflow refuses to run when PMPro services are paused (cloned sites), when the environment or active gateway changed after scheduling, or when a workflow is already queued.
• Two new editable email templates: deprecated_gateway_stripe_migration and deprecated_gateway_checkout_required, registered only while a deprecated gateway is loaded.
• New PMProGateway_stripe::create_deprecated_gateway_migration_subscription() creates the placeholder subscription with migration metadata.
• The Update Billing Information links on the Account and Billing pages no longer require the subscription to have an order, since Stripe placeholder subscriptions start with none (the billing preheader already supports order-less subscriptions).

Testing

• Migrated active subscriptions to Stripe placeholders in sandbox: placeholder created as trialing with the correct next payment date, member emailed with the billing update link, old subscription cancelled, progress/counters correct.
• Expiration strategy: enddate set to the old next payment date, checkout-required email sent, subscription cancelled.
• Edge cases covered by the workflow and verified in code review: deleted users, deleted subscriptions, users who already re-checked-out, billing limits already reached, dead placeholders on rerun (fresh placeholder + re-email), stop/restart, environment switching, cleanup blocked while live subscriptions remain.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an admin-guided “sunset” workflow for deprecated payment gateways, including UI on the Payment Settings screen, Action Scheduler–driven subscription migration (to Stripe placeholders or expiration dates), migration logging, and two new member-facing email templates. It also updates Account/Billing UI to allow “Update Billing Info” links for subscriptions that may not have an associated order (e.g., Stripe placeholder subscriptions).

Changes:

• Introduces includes/deprecated-gateways.php to own deprecated gateway loading plus a 3-step admin migration/cleanup workflow with logging + AJAX status polling.
• Adds Stripe-side placeholder subscription creation (PMProGateway_stripe::create_deprecated_gateway_migration_subscription()) and registers two new email templates for member notifications.
• Relaxes “Update Billing Info” link gating in account/billing templates to support order-less placeholder subscriptions.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
shortcodes/pmpro_account.php	Shows update-billing action link without requiring an order.
pages/billing.php	Shows update-billing link for subscriptions without requiring a successful order.
paid-memberships-pro.php	Loads the new deprecated-gateways module and new email template classes.
includes/deprecated.php	Removes deprecated-gateway helpers moved into the new module.
includes/deprecated-gateways.php	New deprecated gateway loading + migration state machine, batch processing, panel UI, AJAX, and logging.
classes/gateways/class.pmprogateway_stripe.php	Adds Stripe API helper for creating migration placeholder subscriptions.
classes/email-templates/class-pmpro-email-template-deprecated-gateway-stripe-migration.php	New email template for Stripe placeholder migrations.
classes/email-templates/class-pmpro-email-template-deprecated-gateway-checkout-required.php	New email template for “checkout again” expiration strategy.
adminpages/paymentsettings.php	Replaces deprecated gateway warning with the guided workflow panel + adds “removed” success notice.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[flintfromthebasement]

PR: #3700 — Add deprecated gateway sunset workflow
dparker1005 → v3.8 | 9 files, +2081 -103
#3700

---

Summary

Large, well-constructed feature. The state machine design, idempotency scheme, crash recovery, and staging-site guards are all solid. One bug in the stop implementation that leaves queued AS actions un-cancelled, plus three minor issues. Not blocking, but the stop bug should be fixed before this ships.

---

Issues

• Major includes/deprecated-gateways.php:1003 — as_unschedule_all_actions( '', array(), $group ) passes an empty string as the hook name. AS builds WHERE hook = '' internally, which matches no real actions. The queued pmpro_deprecated_gateway_process_batch actions are not removed from the queue. The state is correctly set to 'stopped', so batches that run will detect it and exit early — but for large migrations, this means dozens to hundreds of no-op AS action runs before the queue drains. The PR description says "Pending batches are unscheduled immediately," which isn't accurate. Fix:

  as_unschedule_all_actions(
      'pmpro_deprecated_gateway_process_batch',
      null,
      pmpro_deprecated_gateway_get_action_group( $gateway, $environment )
  );

• Minor includes/deprecated-gateways.php:860-866 — pmpro_deprecated_gateway_record_result() is a read-modify-write on counter fields. With concurrent AS workers (multi-threaded queue runners), two workers can read processed=5, both compute processed=6, and both write processed=6 — losing one count. Low risk with AS's default single-worker behavior, but worth noting if sites run parallel queues.

• Minor classes/gateways/class.pmprogateway_stripe.php:617 — catch ( \Throwable $e ) (PHP 7+) subsumes all exceptions and errors. The catch ( \Exception $e ) block immediately after it is dead code in PHP 7+. Remove it, or reorder to \Exception first if PHP 5 compatibility matters here.

• Minor includes/deprecated-gateways.php:1334 — $bridge_order->saveOrder() result is unchecked. If the insert fails silently, the billing limit bridge order is missing, and the remaining-payment count will be off by one (allowing one extra renewal cycle for billing-limited subscriptions).

---

Looks Good

• The "cancel last" ordering (create replacement → email → cancel old) is the right call. Partial failures leave the member's original subscription intact.
• The attempt-counter idempotency scheme for dead placeholders is correctly handled — bumping the counter before clearing stale meta ensures Stripe's 24-hour replay window doesn't return the cancelled subscription.
• Auth check before nonce check in pmpro_deprecated_gateway_ajax() is correct ordering.
• pmpro_is_paused() guard in both schedule() and process_batch() is good belt-and-suspenders against staging database copies.
• The shared PayPal credential deletion logic (only delete once all three PayPal gateways are removed) is handled correctly.

---

Questions

1. PMPro_Action_Scheduler::dispatch_queue() is called after scheduling the initial batch — does this reliably kick the queue on sites using WP-Cron, or are there configurations where it silently no-ops and the first batch waits for the next cron tick?

[dparker1005]

@flintfromthebasement Thanks for the thorough review. Point-by-point:

as_unschedule_all_actions( '', array(), $group ) — this works as written. In the bundled Action Scheduler (3.9.2), as_unschedule_all_actions() special-cases this exact signature: with an empty hook, empty args, and a non-empty group, it routes to ActionScheduler_Store::instance()->cancel_actions_by_group( $group ) before any hook-based query is built (see includes/lib/action-scheduler/functions.php). No WHERE hook = '' query is ever constructed, and all pending actions in the group are cancelled in one store call. The explicit-hook form you suggested also works, but it skips that branch and falls through to the one-action-at-a-time as_unschedule_action() loop, so the current call is actually the more efficient path. Possibly older AS versions behaved the way you describe, but not the one shipped here.

record_result() read-modify-write — agreed the pattern is real in general, but it isn't reachable in this design: each batch enqueues the next, so a workflow never has two actions in flight; the initial enqueue uses Action Scheduler's $unique flag, so concurrent start requests can't create parallel chains; and workflows for different gateways/environments write different option keys. If it ever did race, the damage is a cosmetic off-by-one in the progress counters — the per-subscription work is idempotent and unaffected. Leaving as is.

Triple-catch in the Stripe class — you're right that \Exception after \Throwable is dead code on PHP 7+, but the Stripe\Error\Base / \Throwable / \Exception chain is the established pattern throughout class.pmprogateway_stripe.php, so this method keeps it for consistency.

Unchecked $bridge_order->saveOrder() — good catch, fixed in c538a79 together with a related issue Copilot flagged on the same block. A save failure now marks the subscription needs_review with a log note explaining that the billing limit may allow one extra payment — important because reruns never revisit that branch once the placeholder exists, so a silent failure would have been permanent.