Repository navigation
Releases
Release v1.9.1
v1.9.1
Changelog
Fixed
TableRowswhose row variable sits inside a false${#if}block (namedConditionalBlockor expression), an empty${#for}loop or an expression block removed byon_error: hideno longer throws PHPWord'sCan 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.mdrefreshed.
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
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 towardsmax_evaluations(spec004-else-branches).- Configuration
conditional_elseif_opening/conditional_elseif_closing(${#elseif/}) andconditional_else_opening/conditional_else_closing(${#else/}), and the matching optionalWordTemplateProcessor/ConditionalExpressionApplicatorconstructor 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 …/#elsemarkers. - An evaluation error in any branch applies
on_errorto the whole block:hideremoves it,keepleaves every marker and branch as text.
Full Changelog: v1.8.0...v1.9.0
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
Release v1.7.1
v1.7.1
Changelog
Security
- HTML image filter bypass via HTML entities (SSRF / local file read).
HtmlImageSanitizerlooked for<imgbefore
decoding entities, while PHPWord decodes them before parsing, so<img src="http://…"/>reached
Html::parseImage()(file_get_contents()on any URL or stream wrapper, files outsideallowed_rootsembedded 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). AffectsHtmlContentvalues built from untrusted HTML, 1.5.0–1.7.0 (REQ-SEC-004 re-audit M1,
CWE-918 / CWE-180).
Changed
phpoffice/phpwordfloor raised to^1.4(keepsphpoffice/math0.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
v1.7.0
Changelog
Added
- PSR-3 logging (REQ-OBS-001):
WordTemplateProcessortakes an optional?LoggerInterface $logger(last
constructor argument, wired to@?logger, Monolog channelword_template). It logs finished merges (info),
path rejections byallowed_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 inrequire. 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 rootcoverage-datavolume is mounted at/app/coverage(REQ-DOC-001). - PHPDoc on every public class and method of
src/(REQ-CS-001);docs/PSR.mdre-evaluated (PSR-3 adopted, REQ-CS-007). - Makefile:
assetsno-op target andhelpin the REQ-MAKE-001 block order (incl.igor,update,update-deps,validate). .github/SECURITY.md: supported versions1.xand the canonical report checklist (REQ-SEC-003)..gitignore:# Archives / compressedblock with*.tar(REQ-GITIGNORE-001); demo compose explains itsdns:(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
v1.6.1
Changelog
Security
- Temporary files are owner-only. The temporary output
.docxand 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 are0600now.
Changed
- Docs: USAGE states that host and demo forms are Symfony Form Types rendered with
form_start/ thenot child.renderedchild loop /form_end, and that raw<form>/<input>must not be reintroduced;check-no-raw-html-formenforces it inrelease-check(REQ-TWIG-005 rule 9). - Developer tooling:
make release-checkruns the full REQ-MAKE-002 chain in order (ensure-upfirst, thencheck-no-cursor-coauthor,check-open-prs, newcheck-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.twigkeeps 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
HtmlImageSanitizermade non-static); no behaviour change.make rector-dryis 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
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/yamlmoved fromrequire-devtorequire(the extension loadsservices.yamlwithYamlFileLoader).
Release v1.5.0
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 outsideallowed_rootsare dropped, closing SSRF and arbitrary local file reads. Onlydata:image/(png|jpeg|gif|bmp);base64images up tohtml_image_max_bytes(default 5 MiB) and, whenallowed_rootsis configured, existing local files under those roots are kept.HtmlContent: temp files created fordata:images are deleted after each merge (previously leaked one file per image, unbounded in FrankenPHP worker mode).
Added
- Config
html_image_max_bytes(default5242880): maximum decoded size of onedata:image insideHtmlContent.
Fixed
listVariables()derives the conditional-marker filter from the configuredconditional_if_opening/conditional_endif_opening(andmacro_opening) instead of hard-coding#if/#endif, so custom conditional delimiters no longer show up as variables.
Documentation
docs/CONFIGURATION.mdand the reference/recipe YAML now documentallowed_roots,path_allowlist_requiredandhtml_image_max_bytes.
Full Changelog: v1.4.3...v1.5.0
Release v1.4.3
Release v1.4.3: dependency refresh and repository maintenance.
Changelog
Changed
- Development:
composer.jsonpinsconfig.platform.phpto 8.2.0 so localcomposer updateresolves 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
v1.4.2
Changelog
Dependencies
igor-php/igor-phprequire-dev constraint bumped to^0.10.1(Dependabot). Dev tooling only.- Demo
symfony8: Symfony 8.1.8, Twig 3.30.0,sabberworm/php-css-parser9.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