feat(export): run pricelist export in the background via Action Scheduler

The full per-user pricelist is far too large to build in one request, so the cron
job and the "Generate and email now" button were timing out. Move both to Action
Scheduler (bundled with WooCommerce): capture the product list once, then process
users in bounded batches, emailing the assembled CSV after the last batch.

- PricelistExporter: split out email_file(); add batch primitives product_refs(),
  user_refs_page(), init_csv(), append_rows(). Pass the explicit fputcsv escape arg
  (silences the PHP 8.4 deprecation; output unchanged).
- ExportModule: start_background() sizes user batches to ~wc_pricebook_export_batch_rows
  (default 5,000) rows, writes the header, and queues the first batch; run_batch()
  processes a page and re-queues, or emails + cleans up when users run out. Single active
  run (guarded); stale/failed runs are reset. Synchronous fallback when Action Scheduler
  is unavailable. run_cron() and the Send-now button now start a background run; new
  "started"/"running" admin notices. CLI gains --async.
- Plugin: on_deactivation clears queued batches + run state.
- Docs/README: document background processing, --async, and wc_pricebook_export_batch_rows.
- Tests: init_csv + append_rows round-trip. 120 passing.

Verified end-to-end on a live store: batches processed via `wp action-scheduler run`,
final batch emailed and cleaned up, no wp_mail failure logged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mjoslyn

README.md

@@ -214,8 +214,13 @@ Three ways to run it, all production‑safe:
 
 The **recipient** defaults to the signed‑in admin's email (falling back to the site
 `admin_email` when blank), and an optional **role filter** limits the export to users in
-selected roles. Users and products are gathered in pages so the command scales on large
-stores.
+selected roles.
+
+The scheduled run and the **Generate and email now** button run **in the background via
+Action Scheduler** (bundled with WooCommerce): users are processed in bounded batches so
+no single request builds the whole file — this is what keeps a large store from timing
+out. The email arrives when the last batch finishes. WP‑CLI stays synchronous by default
+(no request timeout); pass `--async` to use the background batches instead.
 
 ## Multi-account / sub-accounts
 

docs/reference/filters.md

@@ -47,6 +47,7 @@ Used by the [pricelist export](/reference/pricelist-export):
 | `wc_pricebook_export_settings` | Recipient / schedule / role filter |
 | `wc_pricebook_export_product_ids` | The product refs included in the export |
 | `wc_pricebook_export_user_query` | The `WP_User_Query` args used to gather users |
+| `wc_pricebook_export_batch_rows` | Target CSV rows per background (Action Scheduler) batch — default 5,000 |
 
 ## Example
 

docs/reference/pricelist-export.md

@@ -43,6 +43,7 @@ wp wc-pricebook export-pricelist --roles=dealer,operator --send
 | `--email=<address>` | Email the CSV to this address as an attachment. |
 | `--roles=<slugs>` | Comma-separated WP roles to limit the export to (default: every user). |
 | `--send` | Email the CSV to the configured recipient (or the site admin). |
+| `--async` | Queue the run through Action Scheduler (background batches) and email it when done. |
 
 ### Scheduled (WP-Cron)
 
@@ -52,8 +53,26 @@ whenever the settings are saved, and is cleared on plugin deactivation.
 
 ### On demand
 
-The **Generate and email now** button on that settings page builds the CSV immediately
-and emails it to the recipient.
+The **Generate and email now** button on that settings page starts the export in the
+background and returns immediately; the email arrives when it finishes.
+
+### Background processing
+
+The scheduled run and the **Generate and email now** button run **in the background via
+[Action Scheduler](https://actionscheduler.org/)** (bundled with WooCommerce): the
+product list is captured once, then users are processed in bounded batches so no single
+request builds the whole file. This is what keeps a large store from timing out — a full
+export is far too big for one PHP request.
+
+- Batches are sized so `users-per-batch × products ≈ 5,000` rows; tune with the
+  [`wc_pricebook_export_batch_rows`](/reference/filters#pricelist-export) filter.
+- Batches run as Action Scheduler jobs, which are processed by WP-Cron (site traffic) or
+  a real cron pinging `wp-cron.php` / `wp action-scheduler run`. On a very low-traffic
+  site, make sure something is driving the queue.
+- Only one export runs at a time; starting another while one is in progress is ignored
+  until it finishes.
+- WP-CLI stays **synchronous** by default (no request timeout). Pass `--async` to route a
+  CLI run through the same background batches instead.
 
 ## Settings
 
@@ -85,3 +104,4 @@ explicitly on the product if you need a figure in the export.
 | `wc_pricebook_export_settings` | Recipient / schedule / role filter |
 | `wc_pricebook_export_product_ids` | The product refs (`id`, `name`, `sku`) included |
 | `wc_pricebook_export_user_query` | The `WP_User_Query` args used to gather users |
+| `wc_pricebook_export_batch_rows` | Target CSV rows per background batch (default 5,000) |

src/Export/ExportModule.php

@@ -2,11 +2,18 @@
 /**
  * WordPress integration for the pricelist export.
  *
- * Wires {@see PricelistExporter} to the three ways a store runs it:
- *   - WP-CLI:  `wp wc-pricebook export-pricelist [--file] [--email] [--roles] [--send]`
+ * Wires {@see PricelistExporter} to the ways a store runs it:
+ *   - WP-CLI:  `wp wc-pricebook export-pricelist [--file] [--email] [--roles] [--send] [--async]`
  *   - Cron:    a daily/weekly scheduled event that emails the configured recipient.
  *   - Admin:   the settings-page "Send now" button (admin-post handler).
  *
+ * Cron and the "Send now" button run the export **in the background** via Action
+ * Scheduler (bundled with WooCommerce): the product list is captured once, then users
+ * are processed in bounded batches so no single request builds the whole file — this is
+ * what stops a large store from timing out. The finished CSV is emailed after the last
+ * batch. When Action Scheduler is unavailable the run falls back to synchronous mode.
+ * The WP-CLI command stays synchronous by default (no request timeout).
+ *
  * The cron schedule is (re)synced whenever the config option is saved. Nothing here
  * touches pricing logic — it only orchestrates when/where the CSV is produced and sent.
  *
@@ -37,6 +44,22 @@ class ExportModule {
 	 */
 	const ACTION_NOW = 'wc_pricebook_export_now';
 
+	/**
+	 * Action Scheduler hook for a single background batch of users.
+	 */
+	const BATCH_HOOK = 'wc_pricebook_export_batch';
+
+	/**
+	 * Option holding the in-progress run's state ({ run, file, recipient, roles, page,
+	 * per_page, rows }). Non-autoloaded.
+	 */
+	const STATE_OPTION = 'wc_pricebook_export_state';
+
+	/**
+	 * Option holding the run's captured product refs. Non-autoloaded.
+	 */
+	const PRODUCTS_OPTION = 'wc_pricebook_export_products';
+
 	/**
 	 * Config provider.
 	 *
@@ -70,6 +93,7 @@ public function __construct( Config $config, PriceEngine $engine ) {
 	 */
 	public function register() {
 		add_action( self::CRON_HOOK, array( $this, 'run_cron' ) );
+		add_action( self::BATCH_HOOK, array( $this, 'run_batch' ), 10, 1 );
 		add_action( 'update_option_' . Config::OPTION, array( $this, 'reschedule' ), 10, 2 );
 		add_action( 'add_option_' . Config::OPTION, array( $this, 'reschedule_added' ), 10, 2 );
 		add_action( 'admin_post_' . self::ACTION_NOW, array( $this, 'handle_send_now' ) );
@@ -81,14 +105,200 @@ public function register() {
 	}
 
 	/**
-	 * The scheduled cron callback: build the pricelist and email the configured
-	 * recipient (or the site admin), then clean up the temp file.
+	 * The scheduled cron callback: start a background export to the configured recipient
+	 * (or the site admin). The heavy work runs in Action Scheduler batches, not in this
+	 * (WP-Cron) request.
 	 *
 	 * @return void
 	 */
 	public function run_cron() {
-		$result = $this->exporter->run_and_email( $this->recipient(), array( 'roles' => $this->config->export()['roles'] ) );
-		$this->cleanup( $result['file'] );
+		$this->start_background( $this->recipient(), $this->config->export()['roles'] );
+	}
+
+	/**
+	 * Whether Action Scheduler (bundled with WooCommerce) is available to run the export
+	 * in the background. When absent, callers fall back to a synchronous run.
+	 *
+	 * @return bool
+	 */
+	private function async_available() {
+		return function_exists( 'as_enqueue_async_action' ) && function_exists( 'as_has_scheduled_action' );
+	}
+
+	/**
+	 * Whether a background export is currently in progress (state present and a batch
+	 * still queued).
+	 *
+	 * @return bool
+	 */
+	private function is_running() {
+		return false !== get_option( self::STATE_OPTION, false )
+			&& $this->async_available()
+			&& as_has_scheduled_action( self::BATCH_HOOK );
+	}
+
+	/**
+	 * Start a background export: capture the product list, size the user batches to a
+	 * target row count, write the CSV header, and queue the first batch. Each batch runs
+	 * as an Action Scheduler job, so no single request builds the whole file.
+	 *
+	 * Falls back to a synchronous run + email when Action Scheduler is unavailable.
+	 *
+	 * @param string            $recipient Recipient email.
+	 * @param array<int,string> $roles     Role filter (empty = all users).
+	 * @return string Status: 'started', 'running', 'norecipient', 'sent', 'mailfail', or 'error'.
+	 */
+	public function start_background( $recipient, array $roles ) {
+		if ( '' === (string) $recipient || ! is_email( $recipient ) ) {
+			return 'norecipient';
+		}
+
+		// No Action Scheduler (e.g. WooCommerce inactive): run synchronously as before.
+		if ( ! $this->async_available() ) {
+			try {
+				$result = $this->exporter->run_and_email( $recipient, array( 'roles' => $roles ) );
+				$this->cleanup( $result['file'] );
+				return $result['sent'] ? 'sent' : 'mailfail';
+			} catch ( \RuntimeException $e ) {
+				$this->log( 'Pricelist export failed: ' . $e->getMessage() );
+				return 'error';
+			}
+		}
+
+		if ( $this->is_running() ) {
+			return 'running';
+		}
+
+		// A stale state with no queued batch (e.g. a previous run died) — reset it.
+		$this->clear_run();
+
+		$products = $this->exporter->product_refs();
+		$file     = $this->run_file();
+		try {
+			$this->exporter->init_csv( $file );
+		} catch ( \RuntimeException $e ) {
+			$this->log( 'Pricelist export could not create its file: ' . $e->getMessage() );
+			return 'error';
+		}
+
+		/**
+		 * Filters the target number of CSV rows per background batch. Batches are sized
+		 * so users-per-batch × products ≈ this, keeping each Action Scheduler run well
+		 * inside a request's time/memory budget.
+		 *
+		 * @param int $rows Target rows per batch.
+		 */
+		$target   = (int) apply_filters( 'wc_pricebook_export_batch_rows', 5000 );
+		$target   = $target > 0 ? $target : 5000;
+		$per_page = max( 1, (int) floor( $target / max( 1, count( $products ) ) ) );
+		$run      = function_exists( 'wp_generate_uuid4' ) ? wp_generate_uuid4() : uniqid( 'run', true );
+
+		add_option( self::PRODUCTS_OPTION, $products, '', 'no' );
+		add_option(
+			self::STATE_OPTION,
+			array(
+				'run'       => $run,
+				'file'      => $file,
+				'recipient' => $recipient,
+				'roles'     => array_values( $roles ),
+				'page'      => 1,
+				'per_page'  => $per_page,
+				'rows'      => 0,
+			),
+			'',
+			'no'
+		);
+
+		as_enqueue_async_action( self::BATCH_HOOK, array( 'run' => $run ), 'wc-pricebook' );
+		return 'started';
+	}
+
+	/**
+	 * Process one batch of users (each priced against every product), then queue the
+	 * next — or, when the users run out, email the finished CSV and clean up. Hooked to
+	 * {@see self::BATCH_HOOK} via Action Scheduler.
+	 *
+	 * @param string $run Run token; a mismatch means the action is stale (superseded).
+	 * @return void
+	 */
+	public function run_batch( $run = '' ) {
+		$state = get_option( self::STATE_OPTION, false );
+		if ( ! is_array( $state ) || ( '' !== (string) $run && ( $state['run'] ?? '' ) !== $run ) ) {
+			return; // Stale or superseded action.
+		}
+
+		try {
+			$products = get_option( self::PRODUCTS_OPTION, array() );
+			$products = is_array( $products ) ? $products : array();
+
+			$users = $this->exporter->user_refs_page( (array) $state['roles'], (int) $state['page'], (int) $state['per_page'] );
+
+			if ( empty( $users ) ) {
+				// Done — email the assembled file, then clean up.
+				$sent = $this->exporter->email_file( $state['recipient'], $state['file'], (int) $state['rows'] );
+				if ( ! $sent ) {
+					$this->log( sprintf( 'Pricelist export assembled %d rows but wp_mail() failed to send to %s.', (int) $state['rows'], $state['recipient'] ) );
+				}
+				$this->cleanup( $state['file'] );
+				$this->clear_run();
+				return;
+			}
+
+			$state['rows'] += $this->exporter->append_rows( $state['file'], $users, $products );
+			$state['page']  = (int) $state['page'] + 1;
+			update_option( self::STATE_OPTION, $state, false );
+
+			as_enqueue_async_action( self::BATCH_HOOK, array( 'run' => $state['run'] ), 'wc-pricebook' );
+		} catch ( \Throwable $e ) {
+			$this->log( 'Pricelist export batch failed: ' . $e->getMessage() );
+			$this->cleanup( isset( $state['file'] ) ? $state['file'] : '' );
+			$this->clear_run();
+		}
+	}
+
+	/**
+	 * Remove the run state + captured product list, and drop any queued batches.
+	 *
+	 * @return void
+	 */
+	private function clear_run() {
+		delete_option( self::STATE_OPTION );
+		delete_option( self::PRODUCTS_OPTION );
+		if ( function_exists( 'as_unschedule_all_actions' ) ) {
+			as_unschedule_all_actions( self::BATCH_HOOK );
+		}
+	}
+
+	/**
+	 * A per-run CSV path under uploads/wc-pricebook (persists across batch requests).
+	 *
+	 * @return string
+	 */
+	private function run_file() {
+		if ( function_exists( 'wp_upload_dir' ) ) {
+			$uploads = wp_upload_dir();
+			if ( empty( $uploads['error'] ) ) {
+				$dir = rtrim( $uploads['basedir'], '/\\' ) . '/wc-pricebook';
+				wp_mkdir_p( $dir );
+				return $dir . '/pricelist-' . gmdate( 'Ymd-His' ) . '.csv';
+			}
+		}
+		$tmp = function_exists( 'get_temp_dir' ) ? get_temp_dir() : sys_get_temp_dir() . '/';
+		return rtrim( $tmp, '/\\' ) . '/wc-pricebook-pricelist-' . gmdate( 'Ymd-His' ) . '.csv';
+	}
+
+	/**
+	 * Log a message (WooCommerce logger when present, else the PHP error log).
+	 *
+	 * @param string $message Message.
+	 * @return void
+	 */
+	private function log( $message ) {
+		if ( function_exists( 'wc_get_logger' ) ) {
+			wc_get_logger()->error( $message, array( 'source' => 'wc-pricebook-export' ) );
+			return;
+		}
+		error_log( '[wc-pricebook] ' . $message ); // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
 	}
 
 	/**
@@ -160,18 +370,9 @@ public function handle_send_now() {
 			$recipient = $this->recipient();
 		}
 
-		$status = 'sent';
-		if ( '' === $recipient ) {
-			$status = 'norecipient';
-		} else {
-			try {
-				$result = $this->exporter->run_and_email( $recipient, array( 'roles' => $this->config->export()['roles'] ) );
-				$this->cleanup( $result['file'] );
-				$status = $result['sent'] ? 'sent' : 'mailfail';
-			} catch ( \RuntimeException $e ) {
-				$status = 'error';
-			}
-		}
+		// Queue the export in the background (synchronous fallback if Action Scheduler
+		// is unavailable). The button returns immediately; the email follows.
+		$status = $this->start_background( $recipient, $this->config->export()['roles'] );
 
 		$redirect = add_query_arg(
 			array(
@@ -196,6 +397,8 @@ public function maybe_notice() {
 		$status = sanitize_key( wp_unslash( $_GET['wc_pricebook_export'] ) ); // phpcs:ignore WordPress.Security.NonceVerification.Recommended
 
 		$messages = array(
+			'started'     => array( 'success', __( 'Pricelist export started. It runs in the background — you’ll get an email with the CSV when it finishes.', 'wc-pricebook' ) ),
+			'running'     => array( 'warning', __( 'A pricelist export is already running. You’ll get the email when it finishes.', 'wc-pricebook' ) ),
 			'sent'        => array( 'success', __( 'Pricelist export emailed.', 'wc-pricebook' ) ),
 			'mailfail'    => array( 'error', __( 'The pricelist CSV was generated but the email could not be sent. Check the site’s mail configuration.', 'wc-pricebook' ) ),
 			'norecipient' => array( 'error', __( 'No recipient email is set. Enter one in the Pricelist export settings.', 'wc-pricebook' ) ),
@@ -229,11 +432,16 @@ public function maybe_notice() {
 	 * : Email the CSV to the configured recipient (or the site admin) instead of / in
 	 *   addition to writing a file.
 	 *
+	 * [--async]
+	 * : Queue the export via Action Scheduler (background batches) and email it when done,
+	 *   instead of building it inline. Uses --email or the configured recipient.
+	 *
 	 * ## EXAMPLES
 	 *
 	 *     wp wc-pricebook export-pricelist --file=/tmp/pricelist.csv
 	 *     wp wc-pricebook export-pricelist --email=sales@example.com
 	 *     wp wc-pricebook export-pricelist --roles=dealer,operator --send
+	 *     wp wc-pricebook export-pricelist --async --email=sales@example.com
 	 *
 	 * @param array<int,string>    $args       Positional args (unused).
 	 * @param array<string,string> $assoc_args Flags.
@@ -249,6 +457,22 @@ public function cli_export( $args, $assoc_args ) {
 		$email = isset( $assoc_args['email'] ) ? (string) $assoc_args['email'] : '';
 		$send  = isset( $assoc_args['send'] );
 
+		// Background mode: queue Action Scheduler batches and let them email when done.
+		if ( isset( $assoc_args['async'] ) ) {
+			$recipient = '' !== $email ? $email : $this->recipient();
+			$status    = $this->start_background( $recipient, $roles );
+			if ( in_array( $status, array( 'started', 'sent' ), true ) ) {
+				\WP_CLI::success( sprintf( 'Queued the background pricelist export to %s. Run the Action Scheduler queue (e.g. `wp action-scheduler run`) to process it.', $recipient ) );
+			} elseif ( 'running' === $status ) {
+				\WP_CLI::warning( 'A background pricelist export is already running.' );
+			} elseif ( 'norecipient' === $status ) {
+				\WP_CLI::error( 'No valid recipient. Pass --email=<address> or configure a recipient in Pricebook settings.' );
+			} else {
+				\WP_CLI::error( 'Could not start the background export. Check the log.' );
+			}
+			return;
+		}
+
 		try {
 			// Emailing: use the recipient flag, else the configured/admin recipient.
 			if ( '' !== $email || $send ) {