Skip to content

5.0.0

Choose a tag to compare

View all tags
@s2b s2b released this 16 Nov 15:57
· 43 commits to main since this release
5.0.0
ee5b89d
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Version 5.0 is the next major milestone in the development of the Fluid templating engine. Based on the previous efforts that went into Fluid 4, Fluid 5 continues to refactor and to modernize the underlining source code, which sometimes requires introducing strategic breaking changes. All breaking changes in this release have been pre-announced in Fluid 4, both in the changelog and by applying the @deprecated annotation or emitting a deprecation notice in the code.

These breaking changes allow us to ship meaningful new features that weren't possible before:

Streamlined ViewHelper Argument Validation

ViewHelpers now use the StrictArgumentProcessor to validate ViewHelper arguments. This means that argument validation behaves the same with ViewHelpers and with the <f:argument> ViewHelper, which was introduced with Fluid 4.2. While the new validation might require some adjustments in existing projects, it has clear advantages: ViewHelper instances can actually rely on the types specified in their API to be checked properly by Fluid, which makes a lot of custom validation code obsolete.

The new argument validation adds support for union types as well as iterable, countable and callable, which allows ViewHelpers to define a clearer API.

See #1062, #1074, #1194 and #1226 for more details.

Template File Resolving and File Extension

Fluid 5 now features an internal fallback chain for template file names. Template files are now resolved in the following order (first match wins):

templateRootPath: templates/
template: myTemplate
format: html

1. templates/myTemplate.fluid.html
2. templates/myTemplate.html
3. templates/myTemplate
4. templates/MyTemplate.fluid.html
5. templates/MyTemplate.html
6. templates/MyTemplate

This means that it's no longer necessary for template names to start with an uppercase character. Also, there is a new dedicated file extension *.fluid.* for Fluid templates: *.fluid.html instead of *.html, *.fluid.xml instead of *.xml, and so on. Because of the fallback chain, both can be added without breaking potential overrides from other template paths.

We recommend switching to the new file extension if Fluid 5 can be a hard requirement for your project. Otherwise, just stick to the existing general file extensions. The new file extension is entirely optional and will not be a requirement.

See #1243 and #1258 for more details.

Simplified Cache Warmup

Fluid 5 comes with a much simpler way to warmup the template cache in your project. The existing cache warmup functionality has been removed and replaced by a new implementation that requires much less configuration and context. By default, it makes use of the new *.fluid.* file extension to discover all Fluid templates in your project.

bin/fluid warmup \
    --cacheDirectory examples/cache/ \
    --path examples/Resources/
    --path examples/ResourceOverrides/

See #1224 for more details.

Alternative Syntax for CDATA Sections

A long-standing issue in Fluid templates has been that the Fluid variable and inline ViewHelper syntax collides with inlined CSS or JavaScript code. This issue has now been addressed with Fluid 5: A new alternative syntax has been introduced that makes collisions between CSS/JavaScript and Fluid far less likely.

The normal inline and variable syntax uses single curly braces { } as tokens in Fluid templates. In <![CDATA[ ]]> sections, this syntax are now ignored. Instead, three curly braces {{{ }}} can be used to call Fluid ViewHelpers or to access variables. The tag-based syntax is disabled altogether in CDATA sections.

See #1246 and the documentation for more details: Avoiding syntax collision with JS and CSS.

Deprecations and Breaking Changes

Please refer to the documentation for a full list of breaking changes and newly introduced deprecations in Fluid 5.0: Changelog 5.x.

What's Changed

Please note that some of the listed changes have been backported to Fluid 4.5.0, most importantly all new ViewHelpers.

  • [BUGFIX] empty array is now valid as typed array by @Kanti in #1139
  • [TASK] Set branch alias for Fluid 5 by @s2b in #1142
  • [TASK] Avoid testing of mocked abstract classes by @s2b in #1141
  • [!!!][TASK] Remove setChildNodes() on ViewHelpers by @s2b in #1145
  • [DOCS] Improve ViewHelper example code by @s2b in #1147
  • [TASK] Clarify code comments related to escaping by @s2b in #1151
  • [BUGFIX] allow usage of interfaces in StrictArgumentProcessor by @Kanti in #1155
  • [DOCS] Re-enable cross reference to TYPO3 doc for new ViewHelpers by @s2b in #1138
  • [TASK] Treat f:argument with default value as optional by @jramke in #1150
  • [TASK][v5] Disallow argument definitions with a default value while also being required by @jramke in #1157
  • [DOC] Incorrect path specified in the Contribution Guide – ViewHelper documentation is not referenced correctly (#1167) by @staatzstreich in #1168
  • [!!!][TASK] Remove renderStatic() for ViewHelpers by @s2b in #1146
  • [TASK] Add non-critical type hints to ViewHelper classes by @s2b in #1153
  • [!!!][TASK] Remove ViewHelper namespace inheritance by @s2b in #1154
  • [FEATURE] RangeViewHelper to return a range of integers as array (#1122) by @ulrichmathes in #1163
  • [!!!][TASK] Add final and type checks to SyntaxTree nodes by @s2b in #1140
  • [FEATURE] LengthViewHelper returns the length of a given string (#1124) by @staatzstreich in #1169
  • [TASK] Remove obsolete IgnoreDeprecations attribute by @s2b in #1178
  • [TASK] Annotate correct return types in ViewInterface by @s2b in #1181
  • [!!!][TASK] Remove deprecated methods from tag-based VH by @s2b in #1173
  • [!!!][TASK] Remove deprecated ViewHelper API methods by @s2b in #1174
  • [!!!][TASK] Remove support for {layoutName} variable by @s2b in #1175
  • [!!!][TASK] Remove deprecated methods from ViewHelperResolver by @s2b in #1176
  • [!!!][TASK] Remove deprecated TemplatePaths API by @s2b in #1177
  • [!!!][TASK] Remove wildly unknown VH namespace syntax by @lolli42 in #1184
  • [TASK] Add PHP 8.5 to test matrix by @lolli42 in #1185
  • [BUGFIX] Fix path access in ChainedVariableProvider::get by @sascha-egerer in #1165
  • [TASK] Apply react/promise patch to fix PHP 8.5 deprecation by @lolli42 in #1189
  • [DOCS] Improve TYPO3-related sections of components docs by @s2b in #1188
  • [TASK] Apply new cgl rules by @s2b in #1195
  • [BUGFIX] Address bug in test ViewHelper by @s2b in #1198
  • [BUGFIX] Call proper API to obtain ViewHelper API by @s2b in #1199
  • [TASK] Remove micro-optimization from HtmlspecialcharsViewHelper by @s2b in #1197
  • [FEATURE] A new <f:merge> ViewHelper should be added to Fluid (#1123) by @staatzstreich in #1206
  • [FEATURE] Two new ViewHelpers <f:startsWith> and <f:endsWith> should be added to Fluid. (#1126) by @staatzstreich in #1170
  • [TASK] Deprecate old cache warmup feature by @lolli42 in #1211
  • [TASK] Avoid PHP 8.5 deprecation \SplObjectStorage->attach() by @lolli42 in #1212
  • [TASK] Avoid context-dependent prefixes for cache files by @s2b in #1205
  • [FEATURE] Introduce ViewHelperArgumentsValidated event (#1200) by @s2b in #1213
  • [!!!][TASK] Strict argument processing for ViewHelpers by @s2b in #1194
  • Revert "[TASK] Apply react/promise patch to fix PHP 8.5 deprecation by @lolli42 in #1214
  • [!!!][TASK] Remove old cache warmup implementation by @s2b in #1209
  • [!!!][FEATURE] Ability to replace argument processor by @s2b in #1204
  • [TASK] Remove obsolete $tagAttributes property by @s2b in #1218
  • [BUGFIX] Allow NULL for optional arguments with default by @s2b in #1221
  • [TASK] Remove unused resetState() method by @s2b in #1217
  • [TASK] Address deprecations introduced by PHP 8.5 by @s2b in #1236
  • [!!!][TASK] Don't allow null as template identifier in parser by @s2b in #1239
  • [!!!][TASK] Remove tag attributes if set to null by @billdagou in #1233
  • [!!!][TASK] Accumulate validation code in ViewHelperInvoker by @s2b in #1216
  • [FEATURE] Add f:round, f:ceil and f:floor ViewHelpers by @staatzstreich in #1220
  • [!!!][TASK] Add type declarations to ViewHelper classes by @s2b in #1219
  • [FEATURE] Support union types for ViewHelper and component API by @s2b in #1226
  • [TASK] Increase test coverage for template path resolving by @s2b in #1241
  • Warn about using f:form. in Components by @linawolf in #1250
  • [FEATURE] Add f:min and f:max ViewHelpers by @s2b in #1245
  • [TASK] Correct return value comment in f:max ViewHelper by @eliashaeussler in #1254
  • [TASK] Remove a duplicate header comment by @eliashaeussler in #1255
  • [TASK] Deprecate variables that start with a "_" by @s2b in #1253
  • [!!!][TASK] Disallow variables that start with a "_" by @s2b in #1225
  • [TASK] Deprecate CDATA removal from templates by @staatzstreich in #1231
  • [!!!][FEATURE] Alternative Fluid syntax in CDATA by @s2b in #1246
  • [FEATURE] Overhaul template path resolving by @s2b in #1243
  • [TASK] Test real-world setup in TemplatePathsTest by @s2b in #1259
  • [TASK] Cleanup example code by @s2b in #1260
  • [FEATURE] <f:contains> ViewHelper by @staatzstreich in #1193
  • [FEATURE] Introduce optional .fluid.* file extension by @s2b in #1258
  • [TASK] Use Fluid file extensions in examples by @s2b in #1261
  • [FEATURE] Overhauled cache warmup command by @s2b in #1224

New Contributors

Full Changelog: 4.5.0...5.0.0

Contributors

s2b, Kanti, and 8 other contributors
Assets 2
Loading