<?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 );
}
}