<?php

namespace interfaces;

use Exception;

interface pdf_generator_i
{
    /**
     * Add the HTML content to be converted to PDF
     * @param string $html HTML content to be converted to PDF
     * @return self
     */
    public function add_html(string $html): self;

    /**
     * Set the filename to save the PDF as
     * @param string|null $filename Filename to save the PDF as
     * @return self
     */
    public function set_filename(string|null $filename): self;

    /**
     * Generate the PDF and save it to the specified path
     * @return string Path to the generated PDF file
     */
    public function generate_pdf(): string;

    /**
     * The function to check if a file is writeable
     * @param string $path Path to the file
     * @return bool True if the file is writeable, false otherwise
     */
    public function is_writeable(string $path): bool;

    /**
     * The function to validate the paths
     * This function checks if the paths are valid and writeable
     * @notation This function is used to validate the paths before generating the PDF
     * @param array $paths Array of paths to validate (e.g. ['var/tmp', 'var/log'])
     * @return bool True if the paths are valid, false otherwise
     */
    public function validate_paths(array $paths): bool;

    /**
     * The function to require valid paths
     * @param array $paths Array of paths to validate (e.g. ['var/tmp', 'var/log'])
     * @return bool True if the paths are valid, false otherwise
     * @throws Exception If the paths are not valid
     */
    public function require_valid_paths(array $paths): bool;

    /**
     * Generate the tmp file location
     * @notation This function creates a place to temporarily store the PDF file
     * @return self
     * @throws Exception If the tmp file location cannot be generated
     */
    public function generate_tmp_file(): self;

    /**
     * Store the PDF file in persistent storage
     * @return pdf_generator_i Path to the stored PDF file
     * @throws Exception If the PDF file cannot be stored
     */
    public function store_tmp_file(): self;
}