<?php
/**
 * @package PlugixaCrm
 */

declare( strict_types = 1 );

namespace PlugixaCrm\Core\Http;

use WP_REST_Response;

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

/**
 * Serving a file from a REST route without WordPress turning it into JSON.
 *
 * THE PROBLEM. `WP_REST_Response` holding a string is JSON-encoded by the REST server on its way out,
 * which is right for an API and ruinous for a download: a `.csv` arrives as one quoted, escaped string
 * that a spreadsheet opens into a single cell, and a `.pdf` arrives as bytes no reader will touch.
 * `rest_pre_serve_request` is the one hook that runs after the response is built and before it is
 * encoded, so it is the only place a body can be sent untouched.
 *
 * WHY THIS IS IN CORE RATHER THAN IN THE MODULE THAT NEEDED IT FIRST. The CSV export owned this
 * listener when it was the only raw route in the plugin. The moment PDF printing became the second,
 * that arrangement turned into a bug waiting to happen: `apply_filters()` runs EVERY callback
 * regardless of what an earlier one returned, so two modules each echoing a body they recognise would
 * have written the same PDF to the output stream twice and produced a file that opens nowhere.
 *
 * One listener, registered once, with `$served` honoured — which is the part that makes a third raw
 * route free rather than another chance to get this wrong.
 */
final class RawResponse {

	/**
	 * Marks a response whose body must be sent as-is.
	 *
	 * A header rather than a subclass or a global, because it is the only thing that survives the trip
	 * through WordPress's dispatcher to the point where the decision can be acted on.
	 */
	public const HEADER = 'X-Plugixa-Raw';

	public function register_hooks(): void {
		add_filter( 'rest_pre_serve_request', array( $this, 'serve' ), 10, 2 );
	}

	/**
	 * @param bool  $served Whether the request has already been served.
	 * @param mixed $result The response being sent.
	 */
	public function serve( bool $served, mixed $result ): bool {
		// Somebody else already wrote the body. Writing ours after it would corrupt both.
		if ( $served || ! $result instanceof WP_REST_Response ) {
			return $served;
		}

		$headers = $result->get_headers();

		if ( empty( $headers[ self::HEADER ] ) ) {
			return $served;
		}

		$body = $result->get_data();

		if ( ! is_string( $body ) ) {
			return $served;
		}

		// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- a generated file (CSV, PDF), sent with its own Content-Type and nosniff. Escaping it for HTML would corrupt the very bytes this path exists to deliver.
		echo $body;

		return true;
	}
}