Merge pull request #23 from LibreSign/feat/native-svg-xobject-hardening

feat: native SVG Form XObject support with transform coverage

Author: vitormattos

.github/workflows/lint.yml

@@ -1,18 +1,27 @@
 # SPDX-FileCopyrightText: 2026 LibreSign
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-name: lint
+name: Lint php
 
-on:
-  pull_request:
-  push:
-    branches: [main]
+on: pull_request
+
+permissions:
+  contents: read
+
+concurrency:
+  group: lint-php-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
 
 jobs:
-  lint:
+  php-lint:
     runs-on: ubuntu-latest
+    name: php-lint
+
     steps:
-      - uses: actions/checkout@v6
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Detect minimum PHP from composer.json
         id: php_min
         run: |
@@ -22,6 +31,6 @@ jobs:
       - uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ steps.php_min.outputs.version }}
-      - run: composer install --no-interaction --prefer-dist
-      - run: composer bin all install --no-interaction --prefer-dist
-      - run: composer lint
+
+      - name: Lint
+        run: composer run php:lint

composer.json

@@ -31,6 +31,7 @@
   },
   "config": {
     "sort-packages": true,
+    "process-timeout": 600,
     "allow-plugins": {
       "bamarni/composer-bin-plugin": true,
       "infection/extension-installer": true
@@ -44,12 +45,14 @@
   },
   "scripts": {
     "lint": [
+      "@php:lint",
       "@cs:check",
       "@rector:check",
       "@psalm",
       "@duplication:check",
       "@composer:validate"
     ],
+    "php:lint": "find . -type f -name '*.php' -not -path './vendor/*' -not -path './vendor-bin/*' -not -path './build/*' -print0 | xargs -0 -n1 php -l",
     "cs:check": "vendor-bin/phpcs/vendor/squizlabs/php_codesniffer/bin/phpcs -q",
     "cs:fix": "vendor-bin/phpcs/vendor/squizlabs/php_codesniffer/bin/phpcbf -q",
     "rector:check": "vendor-bin/rector/vendor/rector/rector/bin/rector process --dry-run",

src/Pdf/FilesystemPdfImageEmbedder.php

@@ -12,29 +12,39 @@
 use LibreSign\XObjectTemplate\Pdf\Jpeg\JpegPdfImageFactoryInterface;
 use LibreSign\XObjectTemplate\Pdf\Png\PngPdfImageFactory;
 use LibreSign\XObjectTemplate\Pdf\Png\PngPdfImageFactoryInterface;
+use LibreSign\XObjectTemplate\Pdf\Svg\SvgPdfXObjectFactory;
+use LibreSign\XObjectTemplate\Pdf\Svg\SvgPdfXObjectFactoryInterface;
 
 final readonly class FilesystemPdfImageEmbedder implements PdfImageEmbedderInterface
 {
     private FilesystemImageSourceReaderInterface $sourceReader;
     private ImageMetadataInspectorInterface $metadataInspector;
     private JpegPdfImageFactoryInterface $jpegImageFactory;
     private PngPdfImageFactoryInterface $pngImageFactory;
+    private SvgPdfXObjectFactoryInterface $svgXObjectFactory;
 
     public function __construct(
         ?FilesystemImageSourceReaderInterface $sourceReader = null,
         ?ImageMetadataInspectorInterface $metadataInspector = null,
         ?JpegPdfImageFactoryInterface $jpegImageFactory = null,
         ?PngPdfImageFactoryInterface $pngImageFactory = null,
+        ?SvgPdfXObjectFactoryInterface $svgXObjectFactory = null,
     ) {
         $this->sourceReader = $sourceReader ?? new FilesystemImageSourceReader();
         $this->metadataInspector = $metadataInspector ?? new ImageMetadataInspector();
         $this->jpegImageFactory = $jpegImageFactory ?? new JpegPdfImageFactory();
         $this->pngImageFactory = $pngImageFactory ?? new PngPdfImageFactory();
+        $this->svgXObjectFactory = $svgXObjectFactory ?? new SvgPdfXObjectFactory();
     }
 
     public function embed(string $source): EmbeddedPdfImage
     {
         $contents = $this->sourceReader->read($source);
+
+        if ($this->isSvgSource($source, $contents)) {
+            return $this->svgXObjectFactory->create($contents, $source);
+        }
+
         $imageInfo = $this->metadataInspector->detect($contents, $source);
         $mime = $this->metadataInspector->resolveMimeType($imageInfo, $source);
 
@@ -46,4 +56,16 @@ public function embed(string $source): EmbeddedPdfImage
             ),
         };
     }
+
+    private function isSvgSource(string $source, string $contents): bool
+    {
+        if (preg_match('/\.svgz?$/i', $source) === 1) {
+            return true;
+        }
+
+        $trimmed = ltrim($contents);
+
+        return str_starts_with($trimmed, '<svg')
+            || (str_starts_with($trimmed, '<?xml') && str_contains($trimmed, '<svg'));
+    }
 }

src/Pdf/SinglePagePdfExporter.php

@@ -127,14 +127,10 @@ private function createImageObjects(array &$objects, array $xObjects): array
         $imageReferences = [];
 
         foreach ($xObjects as $alias => $resource) {
-            if (($resource['Subtype'] ?? null) !== '/Image') {
-                throw new InvalidArgumentException(sprintf('Unsupported XObject subtype for "%s".', $alias));
-            }
-
             $source = $resource['Source'] ?? null;
             if (!is_string($source) || $source === '') {
                 throw new InvalidArgumentException(
-                    sprintf('Image resource "%s" must expose a non-empty Source.', $alias),
+                    sprintf('XObject resource "%s" must expose a non-empty Source.', $alias),
                 );
             }
 

src/Pdf/Svg/ArcParams.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+// SPDX-FileCopyrightText: 2026 LibreSign
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace LibreSign\XObjectTemplate\Pdf\Svg;
+
+/**
+ * Internal value object grouping the common arc parameters.
+ *
+ * @internal
+ */
+final readonly class ArcParams
+{
+    /**
+     * @SuppressWarnings(PHPMD.ExcessiveParameterList)
+     */
+    public function __construct(
+        public float $fromX,
+        public float $fromY,
+        public float $toX,
+        public float $toY,
+        public float $radiusX,
+        public float $radiusY,
+        public float $cosTh,
+        public float $sinTh,
+        public int $largeArc,
+        public int $sweep,
+    ) {
+    }
+
+    public function withRadii(float $radiusX, float $radiusY): self
+    {
+        return new self(
+            $this->fromX,
+            $this->fromY,
+            $this->toX,
+            $this->toY,
+            $radiusX,
+            $radiusY,
+            $this->cosTh,
+            $this->sinTh,
+            $this->largeArc,
+            $this->sweep,
+        );
+    }
+}

src/Pdf/Svg/PathCommandContext.php

@@ -0,0 +1,28 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreSign
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreSign\XObjectTemplate\Pdf\Svg;
+
+/**
+ * Context for path command processing.
+ * Encapsulates transform and coordinate parameters.
+ *
+ * @internal
+ */
+final readonly class PathCommandContext
+{
+    /**
+     * @param array{0:float,1:float,2:float,3:float,4:float,5:float} $transformMatrix
+     */
+    public function __construct(
+        public array $transformMatrix,
+        public float $minX,
+        public float $maxY,
+        public string $source,
+    ) {
+    }
+}

src/Pdf/Svg/PathParsingState.php

@@ -0,0 +1,31 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreSign
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreSign\XObjectTemplate\Pdf\Svg;
+
+/**
+ * Mutable state container for SVG path parsing.
+ * Tracks current position, control points, and accumulated commands.
+ *
+ * @internal
+ */
+final class PathParsingState
+{
+    public function __construct(
+        public float $currentX = 0.0,
+        public float $currentY = 0.0,
+        public float $subpathStartX = 0.0,
+        public float $subpathStartY = 0.0,
+        public ?float $lastCubicControlX = null,
+        public ?float $lastCubicControlY = null,
+        public ?float $prevQuadCpX = null,
+        public ?float $prevQuadCpY = null,
+        /** @var list<string> */
+        public array $commands = [],
+    ) {
+    }
+}

src/Pdf/Svg/SvgArcConverter.php

@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+// SPDX-FileCopyrightText: 2026 LibreSign
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace LibreSign\XObjectTemplate\Pdf\Svg;
+
+use LibreSign\XObjectTemplate\Pdf\Svg\SvgArcMath;
+
+/**
+ * Converts SVG arc commands to cubic Bézier curve approximations.
+ *
+ * This class encapsulates the mathematical transformation of SVG arc path
+ * commands (A/a) into a series of cubic Bézier curves, which are directly
+ * supported by the PDF specification.
+ *
+ * The algorithm implements the SVG 2 specification's arc-to-Bézier conversion,
+ * decomposing the arc into multiple segments for accurate curve approximation.
+ */
+final readonly class SvgArcConverter
+{
+    public function __construct(
+        private SvgArcMath $math = new SvgArcMath(),
+    ) {
+    }
+
+    /**
+     * Convert SVG arc command parameters to cubic Bézier curves.
+     *
+     * This method takes the arc parameters as specified in SVG and converts
+     * them to an array of cubic Bézier curve control points that approximate
+     * the arc within the PDF coordinate space.
+     *
+     * @param float $fromX Starting X coordinate
+     * @param float $fromY Starting Y coordinate
+     * @param float $rx X-axis radius
+     * @param float $ry Y-axis radius
+     * @param float $rotation Rotation angle in degrees
+     * @param int $largeArc Large arc flag (0 or 1)
+     * @param int $sweep Sweep flag (0 or 1)
+     * @param float $toX Ending X coordinate
+     * @param float $toY Ending Y coordinate
+     * @return array<int, array<int, float>> Array of cubic Bézier control points
+     */
+    public function arcToBezierCurves(
+        float $fromX,
+        float $fromY,
+        float $radiusX,
+        float $radiusY,
+        float $rotation,
+        int $largeArc,
+        int $sweep,
+        float $toX,
+        float $toY,
+    ): array {
+        if (abs($toX - $fromX) < 1e-10 && abs($toY - $fromY) < 1e-10) {
+            return [];
+        }
+
+        if ($radiusX < 1e-10 || $radiusY < 1e-10) {
+            return [[$toX, $toY, $toX, $toY, $toX, $toY]];
+        }
+
+        $theta    = deg2rad($rotation);
+        $params = new ArcParams(
+            $fromX,
+            $fromY,
+            $toX,
+            $toY,
+            $radiusX,
+            $radiusY,
+            cos($theta),
+            sin($theta),
+            $largeArc,
+            $sweep,
+        );
+
+        $params = $this->math->normalizeArcRadii($params);
+
+        [$centerX, $centerY] = $this->math->calculateArcCenter($params);
+
+        [$startAngle, $deltaAngle] = $this->math->calculateArcAngles($params);
+
+        return $this->math->generateArcCurves(
+            $params,
+            $centerX,
+            $centerY,
+            $startAngle,
+            $deltaAngle,
+        );
+    }
+}