<?php
/**
 * Stray-output guard around Kordiam REST callbacks.
 *
 * @package Kordiam
 */

declare( strict_types=1 );

namespace Kordiam\Rest;

use Kordiam\Support\Config;
use Kordiam\Support\Str;
use WP_REST_Request;

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Keeps accidental output out of Kordiam REST responses.
 *
 * Buffers the route callback in one try/finally scope so nested REST dispatches stay balanced.
 * Output from permission callbacks is not covered.
 */
final class OutputGuard {

	/**
	 * Running a Kordiam route callback with its output buffered.
	 *
	 * @param mixed                                                 $dispatch_result Result from an earlier filter, or null when unhandled.
	 * @param WP_REST_Request<array<string, mixed>>|WP_REST_Request $request         Current request.
	 * @param string                                                $route           Matched route.
	 * @param array<string, mixed>|null                             $handler         Matched route handler.
	 *
	 * @return mixed The callback's return value, or the unchanged $dispatch_result.
	 */
	public function dispatch( $dispatch_result, $request, $route, $handler ) {
		unset( $route );

		if ( null !== $dispatch_result ) {
			return $dispatch_result;
		}

		if ( ! $request instanceof WP_REST_Request || ! self::is_kordiam_route( $request ) ) {
			return $dispatch_result;
		}

		if ( ! is_array( $handler ) || ! isset( $handler['callback'] ) || ! is_callable( $handler['callback'] ) ) {
			return $dispatch_result;
		}

		ob_start();

		try {
			$result = call_user_func( $handler['callback'], $request );
		} finally {
			ob_end_clean();
		}

		// Returning null would mean "not handled" and the server would run the callback again.
		return null === $result ? rest_ensure_response( $result ) : $result;
	}

	/**
	 * Checking whether a request targets one of this plugin's namespaces.
	 *
	 * @param WP_REST_Request<array<string, mixed>>|WP_REST_Request $request Current request.
	 *
	 * @return bool Whether the route belongs to Kordiam.
	 */
	private static function is_kordiam_route( WP_REST_Request $request ): bool {
		$route = ltrim( (string) $request->get_route(), '/' );

		foreach ( array( Config::REST_NAMESPACE, Config::REST_NAMESPACE_LEGACY ) as $namespace ) {
			if ( Str::starts_with( $route, $namespace ) ) {
				return true;
			}
		}

		return false;
	}
}