Skip to content

Releases

Release v1.9.1

Choose a tag to compare

@github-actions github-actions released this 16 Nov 21:30

v1.9.1

Changelog

Fixed

  • TableRows whose row variable sits inside a false ${#if} block (named ConditionalBlock or expression), an empty ${#for} loop or an expression block removed by on_error: hide no longer throws PHPWord's Can not clone row…: the rows are skipped with a debug log. A row variable that never existed in the template still throws. Image and HTML values for hidden placeholders were already ignored.

Tests

  • WorkerKeptAliveKernelTest: one kept-alive kernel, 1000 merges as two users, no resetter, isolation and memory assertions (REQ-RUNTIME-002); docs/FRANKENPHP-WORKER-AUDIT.md refreshed.

Documentation

  • USAGE: new section "Using it from a DDD / hexagonal application" (own port implemented with WordTemplateProcessorInterface, replace/decorate through the alias, read-model context, ExpressionLanguage SPI on the infrastructure side, known limitations).

Changed

  • Demo uses the UiKit base style and FormKit forms (REQ-DEMO-014/015).

What's Changed

  • ci: run the PR title check on pull_request by @HecFranco in #15
  • docs: add DDD / hexagonal host path to USAGE by @HecFranco in #16
  • ci: run the igor worker-state audit by @HecFranco in #17
  • test(worker): kept-alive kernel test and refreshed worker audit by @HecFranco in #18
  • chore(demo): UiKit base style and FormKit forms with CSRF (REQ-DEMO-014/015) by @HecFranco in #19
  • fix(processor): skip TableRows whose row variable a false conditional removed by @HecFranco in #20

Full Changelog: v1.9.0...v1.9.1

Release v1.9.0

Choose a tag to compare

@HecFranco HecFranco released this 03 Nov 12:49

Release v1.9.0

Changelog

Added

  • ${#elseif …} / ${#else} branches in expression conditionals (conditional_expressions.enabled: true): ${#if a > 5000} … ${#elseif a > 1000} … ${#else} … ${#endif}. The first true branch is rendered and the expressions after it are not evaluated; ${#else} is the optional, last fallback. Branches can hold nested blocks and loops, work on whole table rows when the markers sit in rows of their own, and count towards max_evaluations (spec 004-else-branches).
  • Configuration conditional_elseif_opening / conditional_elseif_closing (${#elseif / }) and conditional_else_opening / conditional_else_closing (${#else / }), and the matching optional WordTemplateProcessor / ConditionalExpressionApplicator constructor arguments.
  • listConditionalExpressions() also lists ${#elseif} expressions; lintConditionalExpressions() checks them and the blocks nested in every branch.
  • Layout errors (per on_error): a branch marker with no open expression block, inside a loop body, in a named block, in a block that is never closed, after the ${#else} of its block, sharing a paragraph with another marker, outside the rows of a row block, or a branch cutting table cells in half.

Changed

  • With expression conditionals enabled, listVariables() omits #elseif … / #else markers.
  • An evaluation error in any branch applies on_error to the whole block: hide removes it, keep leaves every marker and branch as text.

Full Changelog: v1.8.0...v1.9.0

Release v1.8.0

Choose a tag to compare

@github-actions github-actions released this 30 Oct 11:57

v1.8.0

Changelog

WordTemplate: opt-in expression conditionals (${#if total > 1000}), Twig-like functions and ${#for} loops incl. table-row loops; values never re-read as placeholders; bounded templates (SEC-004 BQ) See UPGRADING.

Added

  • Expression conditionals (opt-in). ${#if <expression>} … ${#endif} — a nameless end marker makes the block an
    expression evaluated against the context with a sandboxed Symfony ExpressionLanguage (==, !=, ===, !==, <,
    >, <=, >=, and/or/not, in/not in, matches, starts with/ends with, contains, arithmetic,
    ??, ?., ranges). Named blocks (${#if name} … ${#endif name} + ConditionalBlock) are unchanged; the
    classification is syntactic (nameless vs named end marker). Enable with
    nowo_word_template.conditional_expressions.enabled: true (default false: no behaviour change).
  • Built-in, Twig-named expression functions (lower, upper, capitalize, title, trim, length, replace,
    slice, starts_with, ends_with, abs, round, floor, ceil, min, max, number_format, count, keys,
    first, last, join, empty, default, is_null, is_defined, now, date, date_diff_days); now() /
    date() use the Symfony clock and conditional_expressions.timezone. Host functions via
    ExpressionFunctionProviderInterface (autoconfigured tag nowo_word_template.expression_function_provider);
    conditional_expressions.functions.allow / deny.
  • conditional_expressions.on_error (exception default, hide, keep) and conditional_expressions.max_length;
    new ConditionalExpressionException (implements WordTemplateExceptionInterface).
  • ConditionalExpressionInspectorInterface (implemented by WordTemplateProcessor):
    listConditionalExpressions() and lintConditionalExpressions() to validate templates before merging.
  • Word typographic quotes (‘ ’ “ ”), dashes, non-breaking spaces and split runs inside expression markers are normalised.
  • Backed enums (value), pure enums (case name) and DateTimeInterface ('Y-m-d') are accepted in the context (they were
    rejected with InvalidContextValueException before) and render as such in placeholders.
  • New runtime dependencies: symfony/expression-language, symfony/cache, symfony/clock (^7.4 || ^8.0).
  • Loops (opt-in). ${#for item in <expression>} … ${#endfor} (and ${#for key, item in …}) repeat the paragraphs
    between the markers — or whole table rows when the markers sit in rows of their own — once per element of a list or
    map; ${item.name}, ${key} and Twig-like ${loop.index}, index0, revindex, revindex0, first, last,
    length, parent are filled per iteration and are variables of the ${#if …} / ${#for …} blocks inside the body
    (processed outside-in with scoping). Enable with nowo_word_template.loops.enabled: true; limits
    loops.max_iterations (1000) and loops.max_total_iterations (10000, nested loops multiply), loops.max_output_bytes
    (32 MiB for the whole merge); delimiters loop_for_opening / loop_for_closing / loop_endfor_opening / loop_endfor_closing.
  • Expression blocks whose markers sit in different rows of the same table keep or remove whole rows.
  • ConditionalExpressionInspectorInterface::listLoops(); lintConditionalExpressions() checks loop heads and knows the
    loop variables inside loop bodies.

Security

  • Hardening of the unreleased expression conditionals after the REQ-SEC-004 review (Appendix BQ): the .. range
    operator only accepts integer literals with a span below 10,000 (count(1..100000000) exhausted memory);
    number_format() accepts at most 20 decimals and replace(), join(), number_format() check the result size before
    building it; date formats are limited to 100 bytes; error messages no longer echo context values (function arguments,
    dynamic map keys / list indexes, regexes read from values); a PCRE failure while scanning markers fails closed.
    replace() accepts maps with numeric keys again and bounds its work (search strings × subject bytes).
  • Loops and expression blocks (REQ-SEC-004 Appendix BQ M2, M3, L1, L2): one output byte budget for all loops and parts of
    a merge (loops.max_output_bytes, 32 MiB), checked before a loop renders; linear marker layout analysis with
    conditional_expressions.max_markers (2000 per part), max_depth (32) and max_evaluations (100,000 per merge), which
    always throw the new TemplateLimitExceededException; the merge timeout is checked while rendering and the
    inspection APIs run under it; values printed by loops and by ordinary placeholders can no longer be read as
    placeholders again — alone or next to another value ('$' + '{other}') — because every $ in a value is written
    as &#36; (collision-free internal escaping), HtmlContent and images are inserted after the scalar placeholders so
    ${key} inside HTML stays literal, and XML-invalid control characters are dropped from values. With expression
    blocks or loops enabled, all copies of the scalar placeholders are checked against loops.max_output_bytes before
    PHPWord writes them.

Documentation

  • docs/USAGE.md — new Expression conditionals section (enable, classification rule, exposed values, operators,
    data types, function reference and Twig mapping, host functions, nesting / else / one of N, PHP vs template, errors
    and error modes, linting, security) and Loops section (paragraph and row loops, loop variables, maps and keys,
    nesting, empty lists, errors and limits); README conditionals and loops sections with screenshots; CONFIGURATION, UPGRADING,
    SECURITY (threat table) and FRANKENPHP-WORKER-AUDIT updated.

  • docs/USAGE.md — new Conditionals by data type section: how to turn bool, ?bool, int/?int, float,
    string/?string, null/optional values, arrays, DateTimeInterface, backed enums, Doctrine relations/collections and
    Symfony request/form data into the bool that ConditionalBlock requires, with recommended expressions and pitfalls
    ('0' is falsy, (bool) 'false' is true, float noise, stripos() at offset 0, loose in_array(), time zones,
    getBoolean()/getInt() throwing BadRequestException), the TypeError in strict mode vs weak-mode coercion, the
    "else" and "one of N" patterns, combining conditions (flatten vs nest), same block name used twice, the table / "no
    items" pattern with TableRows, what happens with a missing block (markers stay as literal text), and where markers may
    go in Word (own paragraph, table cells, headers/footers, page breaks; not across cells, footnotes or overlapping).
    Linked from the README.

Tests

  • Unit tests for the classifier/applicator (mixed nesting, layout errors per mode, split runs, smart quotes, custom
    delimiters), the evaluator (every operator, failures), every built-in function (happy path, bad types, size caps,
    allow/deny, host providers) and the exposure rules; .docx integration tests (body, table cell, header, footer,
    functions, error modes, listing/linting, kernel wiring with an autoconfigured host provider).

  • tests/Integration/ExpressionConditionalsUsageDocTest.php renders every operator / data-type / function / error row of
    the new USAGE section through a real .docx and runs every "In Word / In PHP / Result" example as written.

  • tests/Integration/ConditionalsUsageDocTest.php executes every documented expression (asserting the snippet is present
    in docs/USAGE.md) and renders the documented patterns and edge cases through real .docx templates, so the docs
    cannot drift from the behaviour. doctrine/collections added to require-dev for the collection examples.

Demo

  • New /conditionals page in demo/symfony8: one form field per PHP type, a preview of the ConditionalBlock
    decisions and a download of public/demo/conditionals-tpl.docx (built by bin/build-conditionals-template.php).
  • /conditionals also shows the expression conditionals of its template (evaluated from the raw order values);
    new /conditionals/examples page (Word text, PHP context, result, template / generated .docx downloads);
    bin/console app:conditionals:export-examples; Playwright e2e (make test-e2e), page screenshots
    (make demo-screenshots) and LibreOffice-rendered "template → generated document" previews (make docx-previews)
    under docs/images/demo/.
  • New /loops page: an invoice whose lines are repeated table rows with a conditional discount row, loop variables,
    nested loops, a map and an empty list, with downloads, e2e and previews.

Changed

  • CHANGELOG headings use the ## [x.y.z] - YYYY-MM-DD form.
  • listVariables() also omits the nameless ${#endif} marker.
  • With conditional_expressions.enabled: true, listConditionalBlocks() returns named blocks only (expression blocks
    are listed by listConditionalExpressions()).
  • With loops.enabled: true, listVariables() omits loop markers and the placeholders of loop variables
    (${line.name}, ${loop.index}).

What's Changed

  • docs(usage): conditionals by data type, executable doc tests and demo page by @HecFranco in #12
  • feat: opt-in expression conditionals with Twig-like functions (1.8.0) by @HecFranco in #13
  • feat: opt-in template loops with row loops and loop variables (1.8.0) by @HecFranco in #14

Full Changelog: v1.7.1...v1.8.0

Release v1.7.1

Choose a tag to compare

@github-actions github-actions released this 29 Oct 16:08

v1.7.1

Changelog

Security

  • HTML image filter bypass via HTML entities (SSRF / local file read). HtmlImageSanitizer looked for <img before
    decoding entities, while PHPWord decodes them before parsing, so &#60;img src="http://…"/&#62; reached
    Html::parseImage() (file_get_contents() on any URL or stream wrapper, files outside allowed_roots embedded in the
    output). The filter now runs on the same decoded XML PHPWord parses, and an unparsable fragment that contains an image
    is dropped (fail closed). Affects HtmlContent values built from untrusted HTML, 1.5.0–1.7.0 (REQ-SEC-004 re-audit M1,
    CWE-918 / CWE-180).

Changed

  • phpoffice/phpword floor raised to ^1.4 (keeps phpoffice/math 0.2 with GHSA-42hm-pq2f-3r7m out of the tree).

What's Changed

  • fix(security): filter HTML images after entity decoding by @HecFranco in #11

Full Changelog: v1.7.0...v1.7.1

Release v1.7.0

Choose a tag to compare

@github-actions github-actions released this 29 Oct 14:38

v1.7.0

Changelog

Added

  • PSR-3 logging (REQ-OBS-001): WordTemplateProcessor takes an optional ?LoggerInterface $logger (last
    constructor argument, wired to @?logger, Monolog channel word_template). It logs finished merges (info),
    path rejections by allowed_roots, dropped HTML images, timeouts and rejected input (warning) and unexpected
    failures (error) with structured context; only the template file name is logged, never full paths, context
    values or document contents. psr/log (^1.1 || ^2.0 || ^3.0) is now in require.
  • HtmlImageSanitizer::droppedImages() and an optional temp directory argument (internal class).

Changed

  • Coverage gate raised from 99% to 100% lines (composer coverage-check, CI); README publishes the measured value
    and TS/JS / Python N/A rows (REQ-TEST-003 / REQ-TEST-007).
  • Coverage reports move to coverage/ (coverage/coverage.xml, coverage/coverage-php.txt,
    coverage/coverage-output.txt); the root coverage-data volume is mounted at /app/coverage (REQ-DOC-001).
  • PHPDoc on every public class and method of src/ (REQ-CS-001); docs/PSR.md re-evaluated (PSR-3 adopted, REQ-CS-007).
  • Makefile: assets no-op target and help in the REQ-MAKE-001 block order (incl. igor, update, update-deps, validate).
  • .github/SECURITY.md: supported versions 1.x and the canonical report checklist (REQ-SEC-003).
  • .gitignore: # Archives / compressed block with *.tar (REQ-GITIGNORE-001); demo compose explains its dns: (REQ-DEMO-009).

What's Changed

  • feat: PSR-3 logging and REQ-100 compliance fixes by @HecFranco in #10

Full Changelog: v1.6.1...v1.7.0

Release v1.6.1

Choose a tag to compare

@github-actions github-actions released this 28 Oct 16:51

v1.6.1

Changelog

Security

  • Temporary files are owner-only. The temporary output .docx and the images extracted from HTML values were
    written to the shared temp dir with the default umask (usually world-readable); merged documents (contracts,
    invoices) could be read by other local users until disposed. Both are 0600 now.

Changed

  • Docs: USAGE states that host and demo forms are Symfony Form Types rendered with form_start / the not child.rendered child loop / form_end, and that raw <form> / <input> must not be reintroduced; check-no-raw-html-form enforces it in release-check (REQ-TWIG-005 rule 9).
  • Developer tooling: make release-check runs the full REQ-MAKE-002 chain in order (ensure-up first, then check-no-cursor-coauthor, check-open-prs, new check-no-raw-html-form (REQ-TWIG-005), composer-sync, cs-fix, cs-check, rector-dry, phpstan, igor, coverage-check, demo release-check).
  • Dependencies refreshed (Composer and pnpm/npm lock files of the bundle and its demos, campaign 2026-10-19).
  • .php-cs-fixer.dist.php: new ParallelConfig(2) (REQ-CS-001).
  • Demo: demo/index.html.twig keeps its grouped placeholder fieldsets (rule 3) and ends the form with the child loop
    ({% for child in form %} + not child.rendered + form_row(child)) so any remaining child is rendered, per
    REQ-TWIG-003.
  • Internal: applied the pending Rector suggestion (private static helper in the internal HtmlImageSanitizer made non-static); no behaviour change. make rector-dry is clean again.

Documentation

  • Documentation: wave-1 REQ compliance — README badges (canonical Downloads, Symfony 7.4 | 8.0 | 8.1, Coverage), canonical FrankenPHP claim, documentation list order (extras under Additional documentation), canonical issue and pull request templates, CONTRIBUTING Code of Conduct link and Cursor Agent queue settings (REQ-IDE-006), DEMO-FRANKENPHP troubleshooting, commented demo .env.example, tables of contents on long docs, Spec Kit inventory refresh (25/25: path allowlist, image sanitizer, split-macro normalizer, PHPWord HTML state).

What's Changed

  • fix(security): temporary output and HTML images are created 0600 (1.6.1) by @HecFranco in #9

Full Changelog: v1.6.0...v1.6.1

Release v1.6.0

Choose a tag to compare

@github-actions github-actions released this 13 Oct 10:06

Release v1.6.0: symfony/yaml required at runtime, Symfony >=7.4.

Changelog

Changed

  • Minimum Symfony version raised from 7.0 to 7.4 (the lowest version tested in CI).
  • symfony/yaml moved from require-dev to require (the extension loads services.yaml with YamlFileLoader).

Release v1.5.0

Choose a tag to compare

@github-actions github-actions released this 13 Oct 09:28

Release v1.5.0: security - HtmlContent images filtered before PHPWord (no SSRF / local file read / temp leak).

Changelog

Security

  • HtmlContent: <img src> values are filtered before PHPWord parses the HTML. Remote URLs, stream wrappers (php://, phar://, file://, …) and local paths outside allowed_roots are dropped, closing SSRF and arbitrary local file reads. Only data:image/(png|jpeg|gif|bmp);base64 images up to html_image_max_bytes (default 5 MiB) and, when allowed_roots is configured, existing local files under those roots are kept.
  • HtmlContent: temp files created for data: images are deleted after each merge (previously leaked one file per image, unbounded in FrankenPHP worker mode).

Added

  • Config html_image_max_bytes (default 5242880): maximum decoded size of one data: image inside HtmlContent.

Fixed

  • listVariables() derives the conditional-marker filter from the configured conditional_if_opening / conditional_endif_opening (and macro_opening) instead of hard-coding #if / #endif , so custom conditional delimiters no longer show up as variables.

Documentation

  • docs/CONFIGURATION.md and the reference/recipe YAML now document allowed_roots, path_allowlist_required and html_image_max_bytes.

Full Changelog: v1.4.3...v1.5.0

Release v1.4.3

Choose a tag to compare

@github-actions github-actions released this 13 Oct 07:17

Release v1.4.3: dependency refresh and repository maintenance.

Changelog

Changed

  • Development: composer.json pins config.platform.php to 8.2.0 so local composer update resolves dependencies installable on the minimum PHP (the lock is not committed); CI overrides the platform per matrix cell.

Full Changelog: v1.4.2...v1.4.3

Release v1.4.2

Choose a tag to compare

@github-actions github-actions released this 09 Oct 08:33

v1.4.2

Changelog

Dependencies

  • igor-php/igor-php require-dev constraint bumped to ^0.10.1 (Dependabot). Dev tooling only.
  • Demo symfony8: Symfony 8.1.8, Twig 3.30.0, sabberworm/php-css-parser 9.5.0.

What's Changed

  • composer: update igor-php/igor-php requirement from ^0.9.7 to ^0.10.1 by @dependabot[bot] in #8

Full Changelog: v1.4.1...v1.4.2