feat: native SVG Form XObject support with transform coverage by vitormattos · Pull Request #23 · LibreSign/xobject-template

vitormattos · 2026-05-30T16:18:20Z

Summary

add native SVG -> PDF Form XObject pipeline via SvgPdfXObjectFactory
remove raster-only assumptions from exporter/embedder flow
add regression/unit/integration coverage for real SVG scenarios (including arc/quadratic and group transforms)
move GOV.BR SVG fixture to structured path under tests/Fixtures/Pdf/Svg

What was validated

focused SVG tests
GOV.BR-like integration scenario using SVG fixture
full quality gate (scripts/quality-gate.sh) passing

Notes addressing review concerns

The GOV.BR integration test now explicitly uses SVG fixture path (tests/Fixtures/Pdf/Svg/govbr-logo.svg) and asserts Form XObject usage.
No PNG fixture is required for GOV.BR SVG coverage; loose govbr-logo.png was removed from the pending change set.
SVG test files and fixtures were aligned to src/Pdf/Svg structure conventions.

Commit strategy

Commits were created one file per commit, all with DCO sign-off (-s).

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

- Add testEmbedCorrectlyDetectsSvgByFileExtensionBoundary with data provider - Test cases for .svg/.svgz, case-insensitive detection, boundary conditions - Validates regex anchor ($) is essential - without it, .svg.txt etc. would match - Optimize count() evaluation in loops (store in variable before loop) - Simplify test assertions to avoid risky test warnings This test coverage kills the escaped mutant that removes regex anchors in isSvgSource detection. Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

- Simplify test to use mock factory returns instead of exceptions - Ensure both SVG and non-SVG branches execute and assert properly - Remove unnecessary complexity that caused test failures - All 421 tests pass with 5216 assertions Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

- Create PathParsingState to encapsulate command parsing state - Create PathCommandContext to encapsulate transform/coordinate context - Refactor convertPathData() to use state/context objects - Extract handler methods for each SVG path command (M,L,H,V,C,S,Q,T,A,Z) - Reduce parameter counts from 10 to 2 by using context objects - Remove ExcessiveParameterList PHPMD violation - All 421 tests passing Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

- Extract normalizeArcRadii() to handle radii validation/scaling - Extract calculateArcCenter() for center point computation - Extract calculateArcAngles() for angle calculations - Extract generateArcCurves() for cubic Bézier segment generation - Reduce arcToBezierCurves() from 117 to 40 lines - Remove ExcessiveMethodLength and NPath violations on arcToBezierCurves - All 421 tests passing Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

- Extract shared resolveColorAttribute() method for color resolution - Eliminate duplication between resolveFillColor/resolveStrokeColor - Reduce NPath violations from 960+384=1344 to single 960 - Complexity reduced from 213 to 206 overall - All 421 tests passing Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

- Move arcToBezierCurves and 4 helper methods to separate class - Reduce SvgPdfXObjectFactory from 1509 to 1255 lines (-254) - Reduce method count from 48 to 43 (-5) - Reduce class complexity from 206 to 186 (-20) - All 421 tests passing - Pure math/utility methods with no state dependencies Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

- Move resolveFillColor, resolveStrokeColor, resolveColorAttribute to SvgColorResolver - Move extractColorFromStyleAttribute, extractValueFromStyleAttribute, normalizeColor - Inject SvgColorResolver as dependency via constructor - Reduce factory from 1255 to 1122 lines (-133) - Reduce method count from 43 to 37 (-6) - Reduce class complexity from 186 to 159 (-27) - All 421 tests passing Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

@SuppressWarnings

…hCommandParser; reduce CC - Extract SvgTransformResolver to encapsulate SVG transform matrix resolution - Extract SvgPathCommandParser to handle SVG path data parsing (CC reduced from 74 to ~48) - Add resolveCoord() helper to eliminate 26 relative-coord ternaries - Add reflectControlPoint() helper for smooth cubic/quadratic S/T commands - Extract SvgElementPathBuilder to build PDF path strings from SVG shape elements - Update SvgPdfXObjectFactory to delegate to extracted classes (ExcessiveClassComplexity fixed) - Fix SvgColorResolver.resolveColorAttribute() CC: 10 -> 9 via PREG_SPLIT_NO_EMPTY - Add @SuppressWarnings(PHPMD.ExcessiveParameterList) to ArcParams (domain-mandated 10-param DTO) All PHPMD violations resolved; 421 unit tests passing. Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

…pliance Infection's class reflection requires each class to reside in a file matching its name. ArcParams was co-located with SvgArcConverter, causing Infection to fail with 'Class does not exist' during mutation generation. Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

…ance PathCommandContext was co-located with PathParsingState; Infection requires each class in a file matching its name. Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

@SuppressWarnings

- Rename short variable names (, , etc.) to descriptive names (, , etc.) to comply with PHPMD minimum 3-character rule - Update variable names in ArcParams.php, SvgArcConverter.php, SvgElementPathBuilder.php, SvgPathCommandParser.php, and SvgTransformResolver.php - Refactor SvgPathCommandParser to extract tokenization logic (tokenizePathData) and token processing (processPathTokens) to reduce method complexity - Add @SuppressWarnings annotation for ExcessiveClassComplexity in SvgPathCommandParser to account for legitimate SVG command handling All PHPMD checks now pass without violations. Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

vitormattos added 28 commits May 30, 2026 13:17

feat(svg): add xobject factory interface

c09c4c4

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

feat(svg): implement native form xobject factory

82a8ce3

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

feat(pdf): route svg sources to native xobject factory

54b37a1

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

feat(pdf): support generic xobject subtypes

eedbd50

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): cover native svg xobject scenarios

7e209fa

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(pdf): validate svg embedder dispatch

6e24eca

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(pdf): adjust exporter expectations for xobjects

761b038

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(fixtures): add govbr svg fixture in structured path

f7b467f

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(integration): validate govbr flow with native svg support

aa7ae16

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): raise coverage for native svg xobject factory

c6cced2

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(integration): remove legacy png previews for visible stamp outputs

e268bb9

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

chore: convert to newest syntax

8ebd28a

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

chore: increase composer process timeout to 600s for mutation tests

09b5349

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

refactor: extract PathCommandContext to its own file for PSR-4 compli…

5d0c351

…ance PathCommandContext was co-located with PathParsingState; Infection requires each class in a file matching its name. Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

fix: line length

9e0fcbe

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

fix: line length

5a8cfed

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

fix: rector issues and indent code

e580563

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

fix: php lint

50df875

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

vitormattos force-pushed the feat/native-svg-xobject-hardening branch from b938adb to 50df875 Compare May 30, 2026 21:26

fix: cs

a653b83

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

vitormattos added 28 commits May 31, 2026 15:35

fix(svg): guard path token loop progress

5e647ef

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

fix(svg): harden arc converter edge handling

1dc929e

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

fix(svg): stabilize path builder parsing loops

25dc724

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): add element path builder coverage

11facb0

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): expand arc converter provider scenarios

56aa989

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): extend path parser final and invalid cases

33a55db

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): harden color resolver style parsing coverage

1103b19

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

refactor(svg): simplify class style rule guard

19d4b42

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): expand arc converter provider scenarios

69f1a80

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): cover empty and malformed style declarations

f535099

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): polish element path builder assertions

28a4412

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): extend path parser mutation scenarios

0365ff0

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): cover style-block skip branches in factory

8e35cde

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): refactor factory tests with data providers

0940691

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

feat: harden svg parsing and test providers

8c8c0d8

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test: consolidate svg parser scenarios

97e150a

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test: consolidate svg factory scenarios

88f981b

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

style: fix svg factory test indentation

95a0bfb

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

fix(svg): remove redundant DOMElement guards

5250a4d

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): harden parser mutation safety and cover transform edge cases

df8fe5d

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test(svg): reduce resolver duplication and fix factory docblocks

1191d0e

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

style(svg): fix misplaced inline @var annotation

94b7b42

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

style(test): fix multiline declaration brace placement

33a855a

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

fix(svg): normalize form xobject matrix for correct logo rendering

cfa8790

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

feat: harden SVG color handling and test coverage

37cdea7

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

test: harden svg arc/color mutation and rector compliance

8fc4e25

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

refactor: extract svg arc math collaborator and public tests

6c55388

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

style: fix phpcs issues in arc math refactor

ca010b2

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

vitormattos merged commit 99789f6 into main Jun 1, 2026
25 checks passed

vitormattos deleted the feat/native-svg-xobject-hardening branch June 1, 2026 20:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: native SVG Form XObject support with transform coverage#23

feat: native SVG Form XObject support with transform coverage#23
vitormattos merged 85 commits into
mainfrom
feat/native-svg-xobject-hardening

vitormattos commented May 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

vitormattos commented May 30, 2026

Summary

What was validated

Notes addressing review concerns

Commit strategy

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant