app/Report/AbstractRenderer.php

<?php

/**
 * webtrees: online genealogy
 * Copyright (C) 2023 webtrees development team
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 */

declare(strict_types=1);

namespace Fisharebest\Webtrees\Report;

use Fisharebest\Webtrees\I18N;
use Fisharebest\Webtrees\MediaFile;
use Fisharebest\Webtrees\Webtrees;

/**
 * Class AbstractRenderer - base for PDF and HTML reports
 */
abstract class AbstractRenderer
{
    // Reports layouts are measured in points.
    protected const UNITS = 'pt';

    // A point is 1/72 of an inch
    protected const INCH_TO_POINTS = 72.0;
    protected const MM_TO_POINTS   = 72.0 / 25.4;

    protected const PAPER_SIZES = [
        // ISO 216
        'A0'         => [841.0 * self::MM_TO_POINTS, 1189.0 * self::MM_TO_POINTS],
        'A1'         => [594.0 * self::MM_TO_POINTS, 841.0 * self::MM_TO_POINTS],
        'A2'         => [420.0 * self::MM_TO_POINTS, 594.0 * self::MM_TO_POINTS],
        'A3'         => [297.0 * self::MM_TO_POINTS, 420.0 * self::MM_TO_POINTS],
        'A4'         => [210.0 * self::MM_TO_POINTS, 297.0 * self::MM_TO_POINTS],
        // US
        'US-Letter'  => [8.5 * self::INCH_TO_POINTS, 11.0 * self::INCH_TO_POINTS],
        'US-Legal'   => [8.5 * self::INCH_TO_POINTS, 14.0 * self::INCH_TO_POINTS],
        'US-Tabloid' => [11.0 * self::INCH_TO_POINTS, 17.0 * self::INCH_TO_POINTS],
    ];

    public float $left_margin = 18.0 * self::MM_TO_POINTS;

    public float $right_margin = 9.9 * self::MM_TO_POINTS;

    public float $top_margin = 26.8 * self::MM_TO_POINTS;

    public float $bottom_margin = 21.6 * self::MM_TO_POINTS;

    public float $header_margin = 4.9 * self::MM_TO_POINTS;

    public float $footer_margin = 9.9 * self::MM_TO_POINTS;

    /** @var string Page orientation (portrait, landscape) */
    public string $orientation = 'portrait';

    /** @var string Page format name */
    public string $page_format = 'A4';

    /** @var float Height of page format in points */
    public float $page_height = 0.0;

    /** @var float Width of page format in points */
    public float $page_width = 0.0;

    /** @var array<array{'name': string, 'font': string, 'style': string, 'size': float}> Styles elements found in the document */
    public array $styles = [];

    /** @var string The default Report font name */
    public string $default_font = 'dejavusans';

    /** @var float The default Report font size */
    public float $default_font_size = 12.0;

    /** @var string Header (H), Body (B) or Footer (F) */
    public string $processing = 'H';

    /** @var bool RTL Language (false=LTR, true=RTL) */
    public bool $rtl = false;

    /** @var bool Show the Generated by... (true=show the text) */
    public bool $show_generated_by = true;

    /** @var string Generated By... text */
    public string $generated_by = '';

    /** @var string The report title */
    public string $title = '';

    /** @var string Author of the report, the users full name */
    public string $rauthor = Webtrees::NAME . ' ' . Webtrees::VERSION;

    /** @var string Keywords */
    public string $rkeywords = '';

    /** @var string Report Description / Subject */
    public string $rsubject = '';

    /** @var array<ReportBaseElement|string> */
    public array $headerElements = [];

    /** @var array<ReportBaseElement|string> */
    public array $footerElements = [];

    /** @var array<ReportBaseElement|string> */
    public array $bodyElements = [];

    public string $currentStyle = '';

    /**
     * Clear the Header.
     *
     * @return void
     */
    abstract public function clearHeader(): void;

    /**
     * @param ReportBaseElement|string $element
     *
     * @return void
     */
    public function addElement($element): void
    {
        if ($this->processing === 'B') {
            $this->addElementToBody($element);
        } elseif ($this->processing === 'H') {
            $this->addElementToHeader($element);
        } elseif ($this->processing === 'F') {
            $this->addElementToFooter($element);
        }
    }

    /**
     * @param ReportBaseElement|string $element
     *
     * @return void
     */
    public function addElementToHeader($element): void
    {
        $this->headerElements[] = $element;
    }

    /**
     * @param ReportBaseElement|string $element
     *
     * @return void
     */
    public function addElementToBody($element): void
    {
        $this->bodyElements[] = $element;
    }

    /**
     * @param ReportBaseElement|string $element
     *
     * @return void
     */
    public function addElementToFooter($element): void
    {
        $this->footerElements[] = $element;
    }

    /**
     * Run the report.
     *
     * @return void
     */
    abstract public function run(): void;

    /**
     * Create a new Cell object.
     *
     * @param float  $width   cell width (expressed in points)
     * @param float  $height  cell height (expressed in points)
     * @param string $border  Border style
     * @param string $align   Text alignment
     * @param string $bgcolor Background color code
     * @param string $style   The name of the text style
     * @param int    $ln      Indicates where the current position should go after the call
     * @param float  $top     Y-position
     * @param float  $left    X-position
     * @param bool   $fill    Indicates if the cell background must be painted (1) or transparent (0). Default value: 1
     * @param int    $stretch Stretch character mode
     * @param string $bocolor Border color
     * @param string $tcolor  Text color
     * @param bool   $reseth
     *
     * @return ReportBaseCell
     */
    abstract public function createCell(
        float $width,
        float $height,
        string $border,
        string $align,
        string $bgcolor,
        string $style,
        int $ln,
        float $top,
        float $left,
        bool $fill,
        int $stretch,
        string $bocolor,
        string $tcolor,
        bool $reseth
    ): ReportBaseCell;

    /**
     * Create a new TextBox object.
     *
     * @param float  $width   Text box width
     * @param float  $height  Text box height
     * @param bool   $border
     * @param string $bgcolor Background color code in HTML
     * @param bool   $newline
     * @param float  $left
     * @param float  $top
     * @param bool   $pagecheck
     * @param string $style
     * @param bool   $fill
     * @param bool   $padding
     * @param bool   $reseth
     *
     * @return ReportBaseTextbox
     */
    abstract public function createTextBox(
        float $width,
        float $height,
        bool $border,
        string $bgcolor,
        bool $newline,
        float $left,
        float $top,
        bool $pagecheck,
        string $style,
        bool $fill,
        bool $padding,
        bool $reseth
    ): ReportBaseTextbox;

    /**
     * Create a text element.
     *
     * @param string $style
     * @param string $color
     *
     * @return ReportBaseText
     */
    abstract public function createText(string $style, string $color): ReportBaseText;

    /**
     * Create a line.
     *
     * @param float $x1
     * @param float $y1
     * @param float $x2
     * @param float $y2
     *
     * @return ReportBaseLine
     */
    abstract public function createLine(float $x1, float $y1, float $x2, float $y2): ReportBaseLine;

    /**
     * Create a new image object.
     *
     * @param string $file  Filename
     * @param float  $x
     * @param float  $y
     * @param float  $w     Image width
     * @param float  $h     Image height
     * @param string $align L:left, C:center, R:right or empty to use x/y
     * @param string $ln    T:same line, N:next line
     *
     * @return ReportBaseImage
     */
    abstract public function createImage(string $file, float $x, float $y, float $w, float $h, string $align, string $ln): ReportBaseImage;

    /**
     * Create a new image object from Media Object.
     *
     * @param MediaFile          $media_file
     * @param float              $x
     * @param float              $y
     * @param float              $w     Image width
     * @param float              $h     Image height
     * @param string             $align L:left, C:center, R:right or empty to use x/y
     * @param string             $ln    T:same line, N:next line
     *
     * @return ReportBaseImage
     */
    abstract public function createImageFromObject(
        MediaFile $media_file,
        float $x,
        float $y,
        float $w,
        float $h,
        string $align,
        string $ln
    ): ReportBaseImage;

    /**
     * Create a new Footnote object.
     *
     * @param string $style Style name
     *
     * @return ReportBaseFootnote
     */
    abstract public function createFootnote(string $style): ReportBaseFootnote;

    /**
     * Initial Setup
     * Setting up document wide defaults that will be inherited of the report modules
     * As DEFAULT A4 and Portrait will be used if not set
     *
     * @return void
     */
    public function setup(): void
    {
        $this->rtl = I18N::direction() === 'rtl';

        $this->rkeywords = '';

        // I18N: This is a report footer. %s is the name of the application.
        $this->generated_by = I18N::translate('Generated by %s', Webtrees::NAME . ' ' . Webtrees::VERSION);

        // Paper size - defaults to A4 if the report fails to define a size.
        [$this->page_width, $this->page_height] = self::PAPER_SIZES[$this->page_format] ?? self::PAPER_SIZES['A4'];
    }

    /**
     * Process the Header, Body or Footer
     *
     * @param string $p Header (H), Body (B) or Footer (F)
     *
     * @return void
     */
    public function setProcessing(string $p): void
    {
        $this->processing = $p;
    }

    /**
     * Add the Title when raw character data is used in Title
     *
     * @param string $data
     *
     * @return void
     */
    public function addTitle(string $data): void
    {
        $this->title .= $data;
    }

    /**
     * Add the Description when raw character data is used in Description
     *
     * @param string $data
     *
     * @return void
     */
    public function addDescription(string $data): void
    {
        $this->rsubject .= $data;
    }

    /**
     * Add Style to Styles array
     *
     * @param array{'name': string, 'font': string, 'style': string, 'size': float} $style
     *
     * @return void
     */
    public function addStyle(array $style): void
    {
        $this->styles[$style['name']] = $style;
    }

    /**
     * Get a style from the Styles array
     *
     * @param string $s Style name
     *
     * @return array{'name': string, 'font': string, 'style': string, 'size': float}
     */
    public function getStyle(string $s): array
    {
        return $this->styles[$s];
    }
}