<?php
/**
 * Generator Interface
 *
 * Defines the contract for PDF generation operations.
 * Both Standalone and Integrated generators must implement this interface.
 *
 * @package Freefactu
 * @since 0.5.0
 */

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

/**
 * Interface Freefactu_Generator_Interface
 *
 * Defines methods for PDF generation that must be implemented by all generators.
 */
interface Freefactu_Generator_Interface {

	/**
	 * Set the order for PDF generation.
	 *
	 * @param WC_Order|int $order WooCommerce order object or order ID.
	 * @return bool True on success, false on failure.
	 */
	public function set_order( $order ): bool;

	/**
	 * Generate PDF for the order.
	 *
	 * @param WC_Order|int|null $order Optional order to generate PDF for.
	 * @return string|WP_Error PDF content as string or WP_Error on failure.
	 */
	public function generate( $order = null );

	/**
	 * Render the invoice template to HTML.
	 *
	 * @param WC_Order|int|null $order Optional order to render template for.
	 * @return string|WP_Error HTML content or WP_Error on failure.
	 */
	public function render_template( $order = null );

	/**
	 * Get PDF content as string.
	 *
	 * @return string|WP_Error PDF content or WP_Error on failure.
	 */
	public function get_pdf_content();

	/**
	 * Save PDF to file.
	 *
	 * @param string|null $path Optional custom path.
	 * @return string|WP_Error File path on success or WP_Error on failure.
	 */
	public function save_pdf( ?string $path = null );

	/**
	 * Output PDF to browser.
	 *
	 * @param string $mode Output mode: 'inline' or 'download'.
	 * @return void|WP_Error
	 */
	public function output_pdf( string $mode = 'inline' );

	/**
	 * Prepare template data from the order.
	 *
	 * @param bool $force_real_data If true, use real order data instead of snapshot.
	 * @return array Template data array.
	 */
	public function prepare_template_data( bool $force_real_data = false ): array;

	/**
	 * Get the URL for viewing the PDF in the browser.
	 *
	 * @param int $order_id Order ID.
	 * @return string PDF view URL.
	 */
	public function get_pdf_url( int $order_id ): string;

	/**
	 * Register hooks for handling PDF output requests.
	 * Each generator registers its own action hooks.
	 *
	 * @return void
	 */
	public function register_output_hooks();
}
