Skip to content

Release v1.8.0

Choose a tag to compare

@github-actions github-actions released this 30 Oct 11:57
· 9 commits to main since this release

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