Repository navigation
Release v1.8.0
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(defaultfalse: 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 andconditional_expressions.timezone. Host functions via
ExpressionFunctionProviderInterface(autoconfigured tagnowo_word_template.expression_function_provider);
conditional_expressions.functions.allow/deny. -
conditional_expressions.on_error(exceptiondefault,hide,keep) andconditional_expressions.max_length;
newConditionalExpressionException(implementsWordTemplateExceptionInterface). -
ConditionalExpressionInspectorInterface(implemented byWordTemplateProcessor):
listConditionalExpressions()andlintConditionalExpressions()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 withInvalidContextValueExceptionbefore) 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,parentare filled per iteration and are variables of the${#if …}/${#for …}blocks inside the body
(processed outside-in with scoping). Enable withnowo_word_template.loops.enabled: true; limits
loops.max_iterations(1000) andloops.max_total_iterations(10000, nested loops multiply),loops.max_output_bytes
(32 MiB for the whole merge); delimitersloop_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 andreplace(),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) andmax_evaluations(100,000 per merge), which
always throw the newTemplateLimitExceededException; the mergetimeoutis 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$(collision-free internal escaping),HtmlContentand 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 againstloops.max_output_bytesbefore
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 turnbool,?bool,int/?int,float,
string/?string,null/optional values, arrays,DateTimeInterface, backed enums, Doctrine relations/collections and
Symfony request/form data into theboolthatConditionalBlockrequires, with recommended expressions and pitfalls
('0'is falsy,(bool) 'false'istrue, float noise,stripos()at offset 0, loosein_array(), time zones,
getBoolean()/getInt()throwingBadRequestException), theTypeErrorin 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 withTableRows, 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;.docxintegration tests (body, table cell, header, footer,
functions, error modes, listing/linting, kernel wiring with an autoconfigured host provider). -
tests/Integration/ExpressionConditionalsUsageDocTest.phprenders every operator / data-type / function / error row of
the new USAGE section through a real.docxand runs every "In Word / In PHP / Result" example as written. -
tests/Integration/ConditionalsUsageDocTest.phpexecutes every documented expression (asserting the snippet is present
indocs/USAGE.md) and renders the documented patterns and edge cases through real.docxtemplates, so the docs
cannot drift from the behaviour.doctrine/collectionsadded torequire-devfor the collection examples.
Demo
- New
/conditionalspage indemo/symfony8: one form field per PHP type, a preview of theConditionalBlock
decisions and a download ofpublic/demo/conditionals-tpl.docx(built bybin/build-conditionals-template.php). /conditionalsalso shows the expression conditionals of its template (evaluated from the rawordervalues);
new/conditionals/examplespage (Word text, PHP context, result, template / generated.docxdownloads);
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)
underdocs/images/demo/.- New
/loopspage: 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-DDform. -
listVariables()also omits the nameless${#endif}marker. - With
conditional_expressions.enabled: true,listConditionalBlocks()returns named blocks only (expression blocks
are listed bylistConditionalExpressions()). - 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