GRAYBYTE

Back Back Up Advanced Editor

<?php
/**
 * Handles reports CSV export.
 */

namespace Automattic\WooCommerce\Admin;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

use Automattic\WooCommerce\Admin\Schedulers\SchedulerTraits;
use Automattic\WooCommerce\Utilities\TimeUtil;

/**
 * ReportExporter Class.
 */
class ReportExporter {
	/**
	 * Slug to identify the scheduler.
	 *
	 * @var string
	 */
	public static $name = 'report_exporter';

/**
	 * Scheduler traits.
	 */
	use SchedulerTraits {
		init as scheduler_init;
	}

/**
	 * Export status option name.
	 */
	const EXPORT_STATUS_OPTION = 'woocommerce_admin_report_export_status';

/**
	 * Export file download action.
	 */
	const DOWNLOAD_EXPORT_ACTION = 'woocommerce_admin_download_report_csv';

/**
	 * How long a generated export stays available for download.
	 */
	const EXPORT_RETENTION_PERIOD = WEEK_IN_SECONDS;

/**
	 * Get all available scheduling actions.
	 * Used to determine action hook names and clear events.
	 *
	 * @return array
	 */
	public static function get_scheduler_actions() {
		return array(
			'export_report'              => 'woocommerce_admin_report_export',
			'email_report_download_link' => 'woocommerce_admin_email_report_download_link',
		);
	}

/**
	 * Add action dependencies.
	 *
	 * @return array
	 */
	public static function get_dependencies() {
		return array(
			'email_report_download_link' => self::get_action( 'export_report' ),
		);
	}

/**
	 * Hook in action methods.
	 */
	public static function init() {
		// Initialize scheduled action handlers.
		self::scheduler_init();

self::init_export_files();
	}

/**
	 * Hook in the handlers that serve and expire already generated exports.
	 *
	 * These stay registered when Analytics is switched off, so a link that was already emailed
	 * keeps working and old exports still get cleaned up, even though no new ones are generated.
	 *
	 * @internal
	 * @since 11.2.0
	 * @return void
	 */
	public static function init_export_files() {
		add_action( 'admin_init', array( __CLASS__, 'download_export_file' ) );
		add_action( 'wc_admin_daily', array( __CLASS__, 'delete_expired_exports' ) );
	}

/**
	 * Delete generated exports that are past the retention period.
	 *
	 * @internal
	 * @since 11.2.0
	 * @return void
	 */
	public static function delete_expired_exports() {
		$expired_before = time() - self::EXPORT_RETENTION_PERIOD;

// Both the report body and its `.headers` companion, but never the directory's
		// .htaccess and index.html guards.
		$paths = glob( ReportCSVExporter::get_reports_directory() . '*.csv*' );

if ( $paths ) {
			foreach ( $paths as $path ) {
				if ( ! is_file( $path ) ) {
					continue;
				}

$modified = filemtime( $path );
				if ( $modified && $modified < $expired_before ) {
					wp_delete_file( $path );
					self::delete_export_status( $path );
				}
			}
		}

self::delete_shared_export_status();
	}

/**
	 * Delete the option every export shared before 11.3.0, once none of the exports in it can still be downloaded.
	 *
	 * @return void
	 */
	private static function delete_shared_export_status() {
		$exports_status = get_option( self::EXPORT_STATUS_OPTION );

if ( false === $exports_status ) {
			return;
		}

if ( is_array( $exports_status ) ) {
			foreach ( array_keys( $exports_status ) as $status_key ) {
				$key_parts   = explode( ':', (string) $status_key, 2 );
				$report_type = $key_parts[0];
				$export_id   = isset( $key_parts[1] ) ? $key_parts[1] : '';
				$filename    = self::get_export_filename( $report_type, $export_id );

$exporter = new ReportCSVExporter();
				$exporter->set_filename( $filename );

$path = ReportCSVExporter::get_reports_directory() . $exporter->get_filename();
				if ( file_exists( $path ) ) {
					return;
				}
			}
		}

delete_option( self::EXPORT_STATUS_OPTION );
	}

/**
	 * Delete the stored progress of an export whose file has been deleted.
	 *
	 * @param string $path Path of the deleted export body or its `.headers` companion.
	 * @return void
	 */
	private static function delete_export_status( $path ) {
		$filename = basename( $path );

if ( preg_match( '/^wc-(.+?)-report-export-(.+)\.csv(?:\.headers)?$/', $filename, $matches ) ) {
			$option_name = self::get_status_option_name( $matches[1], $matches[2] );
			delete_option( $option_name );
		}
	}

/**
	 * Queue up actions for a full report export.
	 *
	 * @param string $export_id Unique ID for report (timestamp expected).
	 * @param string $report_type Report type. E.g. 'customers'.
	 * @param array  $report_args Report parameters, passed to data query.
	 * @param bool   $send_email Optional. Send an email when the export is complete.
	 * @return int Number of items to export.
	 */
	public static function queue_report_export( $export_id, $report_type, $report_args = array(), $send_email = false ) {
		$exporter = new ReportCSVExporter( $report_type, $report_args );
		$exporter->prepare_data_to_export();

$total_rows  = $exporter->get_total_rows();
		$batch_size  = $exporter->get_limit();
		$num_batches = (int) ceil( $total_rows / $batch_size );

if ( 0 < $num_batches ) {
			// An export queued outside a user session has no user to email, but a filter on the email's recipient can still name one.
			$email_user_id = $send_email ? get_current_user_id() : false;

// Only the first page is queued. Each page queues the next one, so the pages run one at a time and in order.
			self::schedule_action( 'export_report', array( 1, $export_id, $report_type, $report_args, $email_user_id, $num_batches ) );
		}

return $total_rows;
	}

/**
	 * Process a report export action.
	 *
	 * @param int       $page_number Page number for this action.
	 * @param string    $export_id Unique ID for report (timestamp expected).
	 * @param string    $report_type Report type. E.g. 'customers'.
	 * @param array     $report_args Report parameters, passed to data query.
	 * @param int|false $email_user_id Optional. User to email the download link to once the last page is written, or false for no email.
	 * @param int       $num_batches Optional. Number of pages in the export. Exports queued before 11.3.0 run without it.
	 * @return void
	 */
	public static function export_report( $page_number, $export_id, $report_type, $report_args, $email_user_id = false, $num_batches = 0 ) {
		$exporter = self::get_page_exporter( $page_number, $export_id, $report_type, $report_args );

// An export queued before 11.3.0 queued all its pages at once, and its email with them.
		if ( ! $num_batches ) {
			$exporter->generate_file();
			self::update_export_percentage_complete( $report_type, $export_id, $exporter->get_percent_complete() );
			return;
		}

$written = $exporter->write_page();

// Without Action Scheduler the other pages run here, in a loop rather than one nested call per page.
		/**
		 * This filter is documented in includes/wc-update-functions.php
		 *
		 * @since 4.0.0
		 */
		if ( ! get_option( 'schema-ActionScheduler_StoreSchema' ) || apply_filters( 'woocommerce_analytics_disable_action_scheduling', false ) ) {
			while ( $written && $page_number < $num_batches ) {
				++$page_number;
				$exporter = self::get_page_exporter( $page_number, $export_id, $report_type, $report_args );
				$written  = $exporter->write_page();
			}
		}

if ( $written && $page_number < $num_batches ) {
			self::update_export_percentage_complete( $report_type, $export_id, (int) floor( $page_number / $num_batches * 100 ) );
			self::queue_next_page( array( $page_number + 1, $export_id, $report_type, $report_args, $email_user_id, $num_batches ) );
			return;
		}

// A page that was not written stops the export here, or it would be marked complete with rows missing.
		if ( ! $written || ! $exporter->write_headers_row_file() ) {
			wc_get_logger()->warning(
				sprintf( 'The %1$s report export %2$s did not finish: its file could not be written on page %3$d of %4$d.', $report_type, $export_id, $page_number, $num_batches ),
				array( 'source' => 'report-csv-exporter' )
			);

return;
		}

self::update_export_percentage_complete( $report_type, $export_id, 100 );

if ( false !== $email_user_id ) {
			self::schedule_action( 'email_report_download_link', array( (int) $email_user_id, $export_id, $report_type, $report_args ) );
		}
	}

/**
	 * Get the exporter that writes one page of an export to the export file.
	 *
	 * @param int    $page_number Page number.
	 * @param string $export_id Unique ID for report (timestamp expected).
	 * @param string $report_type Report type. E.g. 'customers'.
	 * @param array  $report_args Report parameters, passed to data query.
	 * @return ReportCSVExporter
	 */
	private static function get_page_exporter( $page_number, $export_id, $report_type, $report_args ) {
		// The arguments come from a scheduled action, so they are whatever it was queued with.
		$report_args = is_array( $report_args ) ? $report_args : array();

$exporter = new ReportCSVExporter( $report_type, array_merge( $report_args, array( 'page' => $page_number ) ) );
		$exporter->set_filename( self::get_export_filename( $report_type, $export_id ) );

return $exporter;
	}

/**
	 * Queue the next page of an export.
	 *
	 * @param array $args Arguments for export_report().
	 * @return void
	 */
	private static function queue_next_page( $args ) {
		// SchedulerTraits types the queue without a leading backslash, so PHPStan cannot resolve it.
		/** @var \WC_Queue_Interface $queue */ // phpcs:ignore Generic.Commenting.DocComment.MissingShort
		$queue = self::queue();
		$queue->add( (string) self::get_action( 'export_report' ), $args, (string) self::$group );
	}

/**
	 * Generate a key to reference an export status.
	 *
	 * @param string $report_type Report type. E.g. 'customers'.
	 * @param string $export_id Unique ID for report (timestamp expected).
	 * @return string Status key.
	 */
	protected static function get_status_key( $report_type, $export_id ) {
		return $report_type . ':' . $export_id;
	}

/**
	 * Get the name of the option an export's progress is stored under.
	 *
	 * The key is hashed so the name fits option_name whatever length the export ID has.
	 *
	 * @param string $report_type Report type. E.g. 'customers'.
	 * @param string $export_id Unique ID for report (timestamp expected).
	 * @return string Option name.
	 */
	protected static function get_status_option_name( $report_type, $export_id ) {
		$status_key = self::get_status_key( $report_type, $export_id );

return self::EXPORT_STATUS_OPTION . '_' . md5( $status_key );
	}

/**
	 * Update the completion percentage of a report export.
	 *
	 * @param string $report_type Report type. E.g. 'customers'.
	 * @param string $export_id Unique ID for report (timestamp expected).
	 * @param int    $percentage Completion percentage.
	 * @return void
	 */
	public static function update_export_percentage_complete( $report_type, $export_id, $percentage ) {
		$option_name = self::get_status_option_name( $report_type, $export_id );

// Not autoloaded: a persistent object cache can write back a stale copy of the autoloaded options from another
		// request, which left the email action reading an old percentage and never sending the download link.
		update_option( $option_name, $percentage, false );
	}

/**
	 * Get the completion percentage of a report export.
	 *
	 * @param string $report_type Report type. E.g. 'customers'.
	 * @param string $export_id Unique ID for report (timestamp expected).
	 * @return bool|int Completion percentage, or false if export not found.
	 */
	public static function get_export_percentage_complete( $report_type, $export_id ) {
		$option_name = self::get_status_option_name( $report_type, $export_id );
		$percentage  = get_option( $option_name );

if ( false === $percentage ) {
			// Exports queued before 11.3.0 report through the option every export shared.
			$exports_status = get_option( self::EXPORT_STATUS_OPTION );
			$status_key     = self::get_status_key( $report_type, $export_id );

if ( ! is_array( $exports_status ) || ! isset( $exports_status[ $status_key ] ) ) {
				return false;
			}

$percentage = $exports_status[ $status_key ];
		}

return (int) $percentage;
	}

/**
	 * Get the name a report export is stored under.
	 *
	 * @param string $report_type Report type. E.g. 'customers'.
	 * @param string $export_id Unique ID for report (timestamp expected).
	 * @return string
	 */
	private static function get_export_filename( $report_type, $export_id ) {
		return "wc-{$report_type}-report-export-{$export_id}";
	}

/**
	 * Get the URL a finished report export is downloaded from.
	 *
	 * @since 11.2.0
	 * @param string $report_type Report type. E.g. 'customers'.
	 * @param string $export_id Unique ID for report (timestamp expected).
	 * @param array  $report_args Optional. Report parameters the export was queued with. When they name
	 *                            a date range, the link carries it so the download is named after it.
	 * @return string
	 */
	public static function get_download_url( $report_type, $export_id, $report_args = array() ) {
		$query_args = array(
			'action'   => self::DOWNLOAD_EXPORT_ACTION,
			'filename' => self::get_export_filename( $report_type, $export_id ),
		);

$date_range = self::get_export_date_range( $report_args );
		if ( $date_range ) {
			$query_args['date_range'] = $date_range['after'] . '-to-' . $date_range['before'];
		}

return add_query_arg( $query_args, admin_url() );
	}

/**
	 * Get the date range a report export covers.
	 *
	 * Reports are not all limited to a period. Stock, for one, has no date range at all.
	 *
	 * @since 11.2.0
	 * @param array $report_args Report parameters, passed to data query.
	 * @return string[] The range's `after` and `before` dates as `Y-m-d`, or an empty array when the report has no range.
	 */
	public static function get_export_date_range( $report_args ) {
		if ( ! is_array( $report_args ) ) {
			return array();
		}

$date_range = array();

foreach ( array( 'after', 'before' ) as $bound ) {
			// Report args arrive from a REST request, so they hold whatever the caller sent. Take the
			// date as written rather than converting it: the report reads these as store local time.
			// The shape alone is not enough, since a date like 2025-06-31 would roll over to July 1.
			if (
				empty( $report_args[ $bound ] ) ||
				! is_string( $report_args[ $bound ] ) ||
				! preg_match( '/^(\d{4}-\d{2}-\d{2})/', $report_args[ $bound ], $matches ) ||
				! TimeUtil::is_valid_date( $matches[1], 'Y-m-d' )
			) {
				return array();
			}

$date_range[ $bound ] = $matches[1];
		}

return $date_range;
	}

/**
	 * Get the date range a report export covers, formatted for display.
	 *
	 * @since 11.2.0
	 * @param array $report_args Report parameters, passed to data query.
	 * @return string Date range in the site's date format, or an empty string when the report has no range.
	 */
	public static function get_export_date_range_label( $report_args ) {
		$date_range = self::get_export_date_range( $report_args );

if ( ! $date_range ) {
			return '';
		}

$after  = self::format_date_range_bound( $date_range['after'] );
		$before = self::format_date_range_bound( $date_range['before'] );

if ( '' === $after || '' === $before ) {
			return '';
		}

if ( $after === $before ) {
			return $after;
		}

/* translators: 1: first day of the period a report covers, 2: last day of that period. */
		return sprintf( _x( '%1$s - %2$s', 'Report date range: from-to', 'woocommerce' ), $after, $before );
	}

/**
	 * Format one end of a report's date range for display.
	 *
	 * @param string $date Date as `Y-m-d`.
	 * @return string The date in the store's date format, or an empty string when it cannot be read.
	 */
	private static function format_date_range_bound( $date ) {
		// Read in the store's own timezone, so the date reads back as the merchant picked it and a
		// date format that names the timezone names theirs rather than UTC. Midday is a safe anchor.
		$parsed = \DateTimeImmutable::createFromFormat( 'Y-m-d H:i:s', $date . ' 12:00:00', wp_timezone() );

if ( false === $parsed ) {
			return '';
		}

return (string) wp_date( wc_date_format(), $parsed->getTimestamp() );
	}

/**
	 * Build the exporter a download request is asking for.
	 *
	 * A read-only download of a report the requesting user is already allowed to view, gated on
	 * the view_woocommerce_reports capability, so a nonce would only prevent nuisance CSRF. The
	 * action is compared verbatim against a fixed name, and set_filename() applies
	 * sanitize_file_name(), which keeps the path inside the reports directory. A nonce is not an
	 * option here either: nonces last 24 hours, and this link is emailed and kept for a week.
	 *
	 * @param array $request Unslashed request parameters, expected to be `$_GET`.
	 * @return ReportCSVExporter|null The exporter for the requested export, or null when the request asks for no export.
	 */
	private static function get_requested_export( $request ) {
		if (
			! is_array( $request ) ||
			! isset( $request['action'] ) ||
			self::DOWNLOAD_EXPORT_ACTION !== $request['action'] ||
			empty( $request['filename'] ) ||
			! is_string( $request['filename'] ) ||
			! current_user_can( 'view_woocommerce_reports' )
		) {
			return null;
		}

$exporter = new ReportCSVExporter();
		$exporter->set_filename( $request['filename'] );

// The stored name only identifies the export, so the emailed link carries the report's date
		// range to name the download after the period it covers. It never reaches the file path.
		if ( ! empty( $request['date_range'] ) && is_string( $request['date_range'] ) ) {
			$exporter->set_download_suffix( $request['date_range'] );
		}

return $exporter;
	}

/**
	 * Serve the export file.
	 */
	public static function download_export_file() {
		// phpcs:ignore WordPress.Security.NonceVerification.Recommended, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- Read in get_requested_export(), which documents why there is no nonce and validates every value it reads.
		$exporter = self::get_requested_export( wp_unslash( $_GET ) );

if ( ! $exporter ) {
			return;
		}

// Say so rather than serving an empty CSV: the exporter creates a blank file for a path
		// that no longer exists, which reads as a report with no results.
		if ( ! $exporter->export_file_exists() ) {
			wp_die(
				esc_html(
					sprintf(
						/* translators: %s: length of time an export is kept, e.g. "1 week". */
						__( 'This report export is no longer available. Exports are kept for %s, so please request a new one.', 'woocommerce' ),
						human_time_diff( 0, self::EXPORT_RETENTION_PERIOD )
					)
				),
				esc_html__( 'Report export unavailable', 'woocommerce' ),
				array( 'response' => 404 )
			);
		}

$exporter->send_headers();
		$exporter->stream_export_file();
		exit;
	}

/**
	 * Process a report export email action.
	 *
	 * @param int    $user_id User ID that requested the email.
	 * @param string $export_id Unique ID for report (timestamp expected).
	 * @param string $report_type Report type. E.g. 'customers'.
	 * @param array  $report_args Optional. Report parameters the export was queued with. Exports queued
	 *                            before WooCommerce 11.2.0 run without them.
	 * @return void
	 */
	public static function email_report_download_link( $user_id, $export_id, $report_type, $report_args = array() ) {
		if ( 100 !== self::get_export_percentage_complete( $report_type, $export_id ) ) {
			wc_get_logger()->warning(
				sprintf( 'Not emailing the %1$s report export %2$s: it never reported itself complete.', $report_type, $export_id ),
				array( 'source' => 'report-csv-exporter' )
			);

return;
		}

$download_url = self::get_download_url( $report_type, $export_id, $report_args );

\WC_Emails::instance();
		$email = new ReportCSVEmail();
		$email->set_report_date_range( self::get_export_date_range_label( $report_args ) );
		$email->trigger( $user_id, $report_type, $download_url );
	}
}