First Commit

tc-lib-pdf/vendor/tecnickcom/tc-lib-pdf-page/src/Region.php

@@ -0,0 +1,382 @@
+<?php
+
+/**
+ * Region.php
+ *
+ * @since     2011-05-23
+ * @category  Library
+ * @package   PdfPage
+ * @author    Nicola Asuni <info@tecnick.com>
+ * @copyright 2011-2024 Nicola Asuni - Tecnick.com LTD
+ * @license   http://www.gnu.org/copyleft/lesser.html GNU-LGPL v3 (see LICENSE.TXT)
+ * @link      https://github.com/tecnickcom/tc-lib-pdf-page
+ *
+ * This file is part of tc-lib-pdf-page software library.
+ */
+
+namespace Com\Tecnick\Pdf\Page;
+
+use Com\Tecnick\Pdf\Page\Exception as PageException;
+
+/**
+ * Com\Tecnick\Pdf\Page\Region
+ *
+ * @since     2011-05-23
+ * @category  Library
+ * @package   PdfPage
+ * @author    Nicola Asuni <info@tecnick.com>
+ * @copyright 2011-2024 Nicola Asuni - Tecnick.com LTD
+ * @license   http://www.gnu.org/copyleft/lesser.html GNU-LGPL v3 (see LICENSE.TXT)
+ * @link      https://github.com/tecnickcom/tc-lib-pdf-page
+ *
+ * @phpstan-import-type RegionData from \Com\Tecnick\Pdf\Page\Box
+ * @phpstan-import-type PageData from \Com\Tecnick\Pdf\Page\Box
+ * @phpstan-import-type PageInputData from \Com\Tecnick\Pdf\Page\Box
+ *
+ * A page region defines the writable area of the page.
+ */
+abstract class Region extends \Com\Tecnick\Pdf\Page\Settings
+{
+    /**
+     * Add a new page.
+     *
+     * @param PageInputData $data Page data:
+     *     annotrefs   : array containing the annotation object references.
+     *     autobreak   : true to automatically add a page when the content reaches the breaking point.
+     *     box         : array containing page box boundaries and settings (@see setBox).
+     *     columns     : number of equal vertical columns, if set it will automatically populate the region array.
+     *     content     : string containing the raw page content.
+     *     format      : page format name, or alternatively you can set width and height as below.
+     *     group       : page group number.
+     *     height      : page height.
+     *     margin      : page margins:
+     *                   - booklet : true to enable booklet mode
+     *                   - PL : page left margin measured from the left page edge
+     *                   - PR : page right margin measured from the right page edge
+     *                   - PT : page top or header top measured distance from the top page edge
+     *                   - HB : header bottom measured from the top page edge
+     *                   - CT : content top measured from the top page edge
+     *                   - CB : content bottom (page breaking point) measured from the top page edge
+     *                   - FT : footer top measured from the bottom page edge
+     *                   - PB : page bottom (footer bottom) measured from the bottom page edge
+     *     num         : if set overwrites the page number.
+     *     orientation : page orientation ('P' or 'L').
+     *     region      : array containing the ordered list of rectangular areas where it is allowed to write,
+     *                   each region is defined by:
+     *                   - RX : horizontal coordinate of top-left corner
+     *                   - RY : vertical coordinate of top-left corner
+     *                   - RW : region width
+     *                   - RH : region height
+     *     rotation    : the number of degrees by which the page shall be rotated clockwise when displayed or printed.
+     *     time        : UTC page modification time in seconds.
+     *     transition  : array containing page transition data (@see getPageTransition).
+     *     width       : page width.
+     *     zoom        : preferred zoom (magnification) factor: 1.0 = 100%.
+     *
+     * NOTE: if $data is null, then the last page format will be cloned.
+     *
+     * @return PageData Page data with additional Page ID property 'pid'.
+     */
+    public function add(array $data = []): array
+    {
+        if (($data === []) && ($this->pmaxid >= 0)) {
+            // clone last page data
+            $data = $this->page[$this->pmaxid];
+            unset($data['time'], $data['content'], $data['annotrefs'], $data['pagenum']);
+        } else {
+            $this->sanitizeGroup($data);
+            $this->sanitizeRotation($data);
+            $this->sanitizeZoom($data);
+            $this->sanitizePageFormat($data);
+            $this->sanitizeBoxData($data);
+            $this->sanitizeTransitions($data);
+            $this->sanitizeMargins($data);
+            $this->sanitizeRegions($data);
+        }
+
+        $this->sanitizeTime($data);
+        $this->sanitizeContent($data);
+        $this->sanitizeAnnotRefs($data);
+        $this->sanitizePageNumber($data);
+        $data['content_mark'] = [0];
+        $data['currentRegion'] = 0;
+        $data['pid'] = ++$this->pmaxid;
+        $this->pid = $data['pid'];
+        $this->page[$this->pid] = $data; // @phpstan-ignore assign.propertyType
+        if (isset($data['group'])) {
+            if (isset($this->group[$data['group']])) {
+                ++$this->group[(int) $data['group']];
+            } else {
+                $this->group[(int) $data['group']] = 1;
+            }
+        }
+
+        return $this->page[$this->pid]; // @phpstan-ignore return.type
+    }
+
+    /**
+     * Set the current page number (move to the specified page).
+     *
+     * @param int $pid page index. Omit or set it to -1 for the current page ID.
+     *
+     * @return PageData Page data.
+     */
+    public function setCurrentPage(int $pid = -1): array
+    {
+        $pid = $this->sanitizePageID($pid);
+        $this->pid = $pid;
+        return $this->page[$this->pid];
+    }
+
+    /**
+     * Returns the specified page data.
+     *
+     * @param int $pid page index. Omit or set it to -1 for the current page ID.
+     *
+     * @return PageData Page data.
+     */
+    public function getPage(int $pid = -1): array
+    {
+        $pid = $this->sanitizePageID($pid);
+        return $this->page[$pid];
+    }
+
+
+    /**
+     * Check if the specified page ID exist.
+     *
+     * @param int $pid page index. Omit or set it to -1 for the current page ID.
+     *
+     * @return int Page ID.
+     */
+    protected function sanitizePageID(int $pid = -1): int
+    {
+        if ($pid < 0) {
+            $pid = $this->pid;
+        }
+
+        if (! isset($this->page[$pid])) {
+            throw new PageException('The page with index ' . $pid . ' do not exist.');
+        }
+
+        return $pid;
+    }
+
+    /**
+     * Select the specified page region.
+     *
+     * @param int $idr ID of the region.
+     * @param int $pid page index. Omit or set it to -1 for the current page ID.
+     *
+     * @return RegionData Selected region data.
+     */
+    public function selectRegion(int $idr, int $pid = -1): array
+    {
+        $pid = $this->sanitizePageID($pid);
+        $this->page[$pid]['currentRegion'] = min(max(0, $idr), $this->page[$pid]['columns']);
+        return $this->getRegion();
+    }
+
+    /**
+     * Returns the current region data.
+     *
+     * @param int $pid page index. Omit or set it to -1 for the current page ID.
+     *
+     * @return RegionData Region.
+     */
+    public function getRegion(int $pid = -1): array
+    {
+        $pid = $this->sanitizePageID($pid);
+        return $this->page[$pid]['region'][$this->page[$pid]['currentRegion']];
+    }
+
+    /**
+     * Returns the next page data.
+     * Creates a new page if required and page break is enabled.
+     *
+     * @param int $pid page index. Omit or set it to -1 for the current page ID.
+     *
+     * @return PageData Page data.
+     */
+    public function getNextPage(int $pid = -1): array
+    {
+        $pid = $this->sanitizePageID($pid);
+        if ($pid < $this->pmaxid) {
+            $this->pid = ++$pid;
+            return $this->page[$this->pid];
+        }
+
+        if (! $this->isAutoPageBreakEnabled()) {
+            return $this->setCurrentPage($pid);
+        }
+
+        return $this->add();
+    }
+
+    /**
+     * Returns the page data with the next selected region.
+     * If there are no more regions available, then the first region on the next page is selected.
+     * A new page is added if required.
+     *
+     * @param int $pid page index. Omit or set it to -1 for the current page ID.
+     *
+     * @return PageData Current page data.
+     */
+    public function getNextRegion(int $pid = -1): array
+    {
+        $pid = $this->sanitizePageID($pid);
+        $nextid = ($this->page[$pid]['currentRegion'] + 1);
+        if (isset($this->page[$pid]['region'][$nextid])) {
+            $this->page[$pid]['currentRegion'] = $nextid;
+            return $this->page[$pid];
+        }
+
+        return $this->getNextPage($pid);
+    }
+
+    /**
+     * Move to the next page region if required.
+     *
+     * @param float  $height Height of the block to add.
+     * @param ?float $ypos   Starting Y position or NULL for current position.
+     * @param int    $pid    Page index. Omit or set it to -1 for the current page ID.
+     *
+     * @return PageData Page data.
+     */
+    public function checkRegionBreak(
+        float $height = 0.0,
+        ?float $ypos = null,
+        int $pid = -1,
+    ): array {
+        if ($this->isYOutRegion($ypos, $height, $pid)) {
+            return $this->getNextRegion($pid);
+        }
+
+        return $this->getPage($pid);
+    }
+
+    /**
+     * Return the auto-page-break status.
+     *
+     * @param int $pid page index. Omit or set it to -1 for the current page ID.
+     *
+     * @return bool True if the auto page break is enabled, false otherwise.
+     */
+    public function isAutoPageBreakEnabled(int $pid = -1): bool
+    {
+        $pid = $this->sanitizePageID($pid);
+        return $this->page[$pid]['autobreak'];
+    }
+
+    /**
+     * Enable or disable automatic page break.
+     *
+     * @param bool $isenabled Set this to true to enable automatic page break.
+     * @param int  $pid       page index. Omit or set it to -1 for the current page ID.
+     */
+    public function enableAutoPageBreak(bool $isenabled = true, int $pid = -1): void
+    {
+        $pid = $this->sanitizePageID($pid);
+        $this->page[$pid]['autobreak'] = $isenabled;
+    }
+
+    /**
+     * Check if the specified position is outside the region.
+     *
+     * @param float  $pos Position.
+     * @param string $min ID of the min region value to check.
+     * @param string $max ID of the max region value to check.
+     * @param int    $pid page index. Omit or set it to -1 for the current page ID.
+     */
+    private function isOutRegion(float $pos, string $min, string $max, int $pid = -1): bool
+    {
+        $region = $this->getRegion($pid);
+        return (($pos < ($region[$min] - self::EPS)) || ($pos > ($region[$max] + self::EPS)));
+    }
+
+    /**
+     * Check if the specified vertical position is outside the region.
+     *
+     * @param ?float $posy   Y position or NULL for current position.
+     * @param float  $height Additional height to add.
+     * @param int    $pid    page index. Omit or set it to -1 for the current page ID.
+     */
+    public function isYOutRegion(
+        ?float $posy = null,
+        float $height = 0.0,
+        int $pid = -1,
+    ): bool {
+        if ($posy === null) {
+            $posy = $this->getY();
+        }
+
+        return $this->isOutRegion($posy + $height, 'RY', 'RT', $pid);
+    }
+
+    /**
+     * Check if the specified horizontal position is outside the region.
+     *
+     * @param ?float $posx  X position or NULL for current position.
+     * @param float  $width Additional width to add.
+     * @param int    $pid   page index. Omit or set it to -1 for the current page ID.
+     */
+    public function isXOutRegion(
+        ?float $posx = null,
+        float $width = 0.0,
+        int $pid = -1
+    ): bool {
+        if ($posx === null) {
+            $posx = $this->getX();
+        }
+
+        return $this->isOutRegion($posx + $width, 'RX', 'RL', $pid);
+    }
+
+    /**
+     * Return the absolute horizontal cursor position for the current region.
+     *
+     * @param int $pid page index. Omit or set it to -1 for the current page ID.
+     */
+    public function getX(int $pid = -1): float
+    {
+        $pid = $this->sanitizePageID($pid);
+        return $this->page[$pid]['region'][$this->page[$pid]['currentRegion']]['x'];
+    }
+
+    /**
+     * Return the absolute vertical cursor position for the current region.
+     *
+     * @param int $pid page index. Omit or set it to -1 for the current page ID.
+     */
+    public function getY(int $pid = -1): float
+    {
+        $pid = $this->sanitizePageID($pid);
+        return $this->page[$pid]['region'][$this->page[$pid]['currentRegion']]['y'];
+    }
+
+    /**
+     * Set the absolute horizontal cursor position for the current region.
+     *
+     * @param float $xpos X position relative to the page coordinates.
+     * @param int   $pid  page index. Omit or set it to -1 for the current page ID.
+     */
+    public function setX(float $xpos, int $pid = -1): static
+    {
+        $pid = $this->sanitizePageID($pid);
+        $this->page[$pid]['region'][$this->page[$pid]['currentRegion']]['x'] = $xpos;
+        return $this;
+    }
+
+    /**
+     * Set the absolute vertical cursor position for the current region.
+     *
+     * @param float $ypos Y position relative to the page coordinates.
+     * @param int   $pid  page index. Omit or set it to -1 for the current page ID.
+     */
+    public function setY(float $ypos, int $pid = -1): static
+    {
+        $pid = $this->sanitizePageID($pid);
+        $this->page[$pid]['region'][$this->page[$pid]['currentRegion']]['y'] = $ypos;
+        return $this;
+    }
+}