Skip to content

[FEATURE] Introduce ArgumentProcessor API#1062

Merged
s2b merged 1 commit intomainfrom
feature/argumentProcessor
May 6, 2025
Merged

[FEATURE] Introduce ArgumentProcessor API#1062
s2b merged 1 commit intomainfrom
feature/argumentProcessor

Conversation

@s2b
Copy link
Contributor

@s2b s2b commented May 2, 2025

Fluid allows ViewHelpers to specify their API by using
AbstractViewHelper::registerArgument(), which is usually called in
initializeArguments() of the ViewHelper. Internally, ArgumentDefinition
is used to represent the provided argument information and constraints.
Among those is the ability to specify the type of an argument as well
as if the argument should be a required argument.

While the required status is already validated at the parser level, the
argument types are validated by the ViewHelper implementation. However,
in most cases, Fluid's built-in validation method by AbstractViewHelper
is used. Unfortunately, this implementation has many flaws:

  • it only covers a subset of possible types (e. g. it covers "boolean", but
    not "bool")
  • It doesn't ensure the correct argument type for scalar arguments (e. g.
    you might receive an integer in your ViewHelper implementation, even
    if the argument has been defined as "string")
  • There are several small inconsistencies

In order to fix this in a future Fluid version without introducing too many
hard-to-debug breaking changes, a new API is introduced which extracts
validation functionality from the AbstractViewHelper and allows
alternative implementations in the future. It also adds the possibility
to pre-process arguments before their validity is checked, which will
allow implicit type conversions in the future (e. g. convert "int" to "string").

As a first step, the existing helper methods isValidType() and
getFirstElementOfNonEmpty() are deprecated and extracted into
a LenientArgumentProcessor, which mimicks the current validation
behavior. Like the current implementation, it doesn't modify the argument
types, but rather passes them along unmodified.

The new API is then called for the pre-processing step in
ViewHelperInvoker as well as the validation step in AbstractViewHelper.
In this first implementation, it isn't possible yet to replace the default
implementation with an alternative.

@s2b s2b force-pushed the feature/argumentProcessor branch 2 times, most recently from f7dd6e0 to 3f6c15b Compare May 2, 2025 17:19
@s2b s2b added the components label May 2, 2025
@s2b s2b force-pushed the feature/argumentProcessor branch 6 times, most recently from ad1fd28 to efd423d Compare May 4, 2025 08:54
Fluid allows ViewHelpers to specify their API by using
`AbstractViewHelper::registerArgument()`, which is usually called in
`initializeArguments()` of the ViewHelper. Internally, `ArgumentDefinition`
is used to represent the provided argument information and constraints.
Among those is the ability to specify the type of an argument as well
as if the argument should be a required argument.

While the required status is already validated at the parser level, the
argument types are validated by the ViewHelper implementation. However,
in most cases, Fluid's built-in validation method by `AbstractViewHelper`
is used. Unfortunately, this implementation has many flaws:

* it only covers a subset of possible types (e. g. it covers "boolean", but
  not "bool")
* It doesn't ensure the correct argument type for scalar arguments (e. g.
  you might receive an integer in your ViewHelper implementation, even
  if the argument has been defined as "string")
* There are several small inconsistencies

In order to fix this in a future Fluid version without introducing too many
hard-to-debug breaking changes, a new API is introduced which extracts
validation functionality from the `AbstractViewHelper` and allows
alternative implementations in the future. It also adds the possibility
to pre-process arguments before their validity is checked, which will
allow implicit type conversions in the future (e. g. convert "int" to "string").

As a first step, the existing helper methods `isValidType()` and
`getFirstElementOfNonEmpty()` are deprecated and extracted into
a `LenientArgumentProcessor`, which mimicks the current validation
behavior. Like the current implementation, it doesn't modify the argument
types, but rather passes them along unmodified.

The new API is then called for the pre-processing step in
`ViewHelperInvoker` as well as the validation step in `AbstractViewHelper`.
In this first implementation, it isn't possible yet to replace the default
implementation with an alternative.
@s2b s2b force-pushed the feature/argumentProcessor branch from efd423d to 18800e9 Compare May 5, 2025 08:59
@s2b s2b merged commit 9dc605a into main May 6, 2025
8 checks passed
@s2b s2b deleted the feature/argumentProcessor branch May 6, 2025 13:58
@s2b s2b added this to the Community Budget Q2/2025 milestone May 20, 2025
s2b added a commit that referenced this pull request Aug 15, 2025
Fluid v4.2.0 introduced a new API to process component and ViewHelper
arguments (see #1062). To avoid breaking changes in Fluid v4 with
how ViewHelpers handle their arguments, a `LenientArgumentProcessor`
has been introduced which has been used exclusively for ViewHelpers.
Components have used the new `StrictArgumentProcessor` from the
beginning.

With this breaking change, this is now unified: `StrictArgumentProcessor`
is now used for ViewHelper arguments as well. This allows us to define
an API in a follow-up patch that allows developers to define their custom
argument processing and validation logic or extend/wrap the existing
logic by Fluid.

The `StrictArgumentProcessor` deals with argument types in a stricter
way: If the supplied argument value doesn't meet the type requirement,
an exception is thrown. For scalar types, automatic type conversion
is happening in a processing step to avoid errors that can be easily
solved by Fluid itself (like "string is required, integer given").

There might be consequences for custom ViewHelpers, however in
most cases this change will make a lot of custom validation code
that was necessary until Fluid v5 obsolete.
s2b added a commit that referenced this pull request Aug 15, 2025
Fluid v4.2.0 introduced a new API to process component and ViewHelper
arguments (see #1062). To avoid breaking changes in Fluid v4 with
how ViewHelpers handle their arguments, a `LenientArgumentProcessor`
has been introduced which has been used exclusively for ViewHelpers.
Components have used the new `StrictArgumentProcessor` from the
beginning.

With this breaking change, this is now unified: `StrictArgumentProcessor`
is now used for ViewHelper arguments as well. This allows us to define
an API in a follow-up patch that allows developers to define their custom
argument processing and validation logic or extend/wrap the existing
logic by Fluid.

The `StrictArgumentProcessor` deals with argument types in a stricter
way: If the supplied argument value doesn't meet the type requirement,
an exception is thrown. For scalar types, automatic type conversion
is happening in a processing step to avoid errors that can be easily
solved by Fluid itself (like "string is required, integer given").

There might be consequences for custom ViewHelpers, however in
most cases this change will make a lot of custom validation code
that was necessary until Fluid v5 obsolete.
s2b added a commit that referenced this pull request Aug 15, 2025
Fluid v4.2.0 introduced a new API to process component and ViewHelper
arguments (see #1062). To avoid breaking changes in Fluid v4 with
how ViewHelpers handle their arguments, a `LenientArgumentProcessor`
has been introduced which has been used exclusively for ViewHelpers.
Components have used the new `StrictArgumentProcessor` from the
beginning.

With this breaking change, this is now unified: `StrictArgumentProcessor`
is now used for ViewHelper arguments as well. This allows us to define
an API in a follow-up patch that allows developers to define their custom
argument processing and validation logic or extend/wrap the existing
logic by Fluid.

The `StrictArgumentProcessor` deals with argument types in a stricter
way: If the supplied argument value doesn't meet the type requirement,
an exception is thrown. For scalar types, automatic type conversion
is happening in a processing step to avoid errors that can be easily
solved by Fluid itself (like "string is required, integer given").

There might be consequences for custom ViewHelpers, however in
most cases this change will make a lot of custom validation code
that was necessary until Fluid v5 obsolete.
s2b added a commit that referenced this pull request Aug 15, 2025
Fluid v4.2.0 introduced a new API to process component and ViewHelper
arguments (see #1062). To avoid breaking changes in Fluid v4 with
how ViewHelpers handle their arguments, a `LenientArgumentProcessor`
has been introduced which has been used exclusively for ViewHelpers.
Components have used the new `StrictArgumentProcessor` from the
beginning.

With this breaking change, this is now unified: `StrictArgumentProcessor`
is now used for ViewHelper arguments as well. This allows us to define
an API in a follow-up patch that allows developers to define their custom
argument processing and validation logic or extend/wrap the existing
logic by Fluid.

The `StrictArgumentProcessor` deals with argument types in a stricter
way: If the supplied argument value doesn't meet the type requirement,
an exception is thrown. For scalar types, automatic type conversion
is happening in a processing step to avoid errors that can be easily
solved by Fluid itself (like "string is required, integer given").

There might be consequences for custom ViewHelpers, however in
most cases this change will make a lot of custom validation code
that was necessary until Fluid v5 obsolete.
s2b added a commit that referenced this pull request Aug 15, 2025
Fluid v4.2.0 introduced a new API to process component and ViewHelper
arguments (see #1062). To avoid breaking changes in Fluid v4 with
how ViewHelpers handle their arguments, a `LenientArgumentProcessor`
has been introduced which has been used exclusively for ViewHelpers.
Components have used the new `StrictArgumentProcessor` from the
beginning.

With this breaking change, this is now unified: `StrictArgumentProcessor`
is now used for ViewHelper arguments as well. This allows us to define
an API in a follow-up patch that allows developers to define their custom
argument processing and validation logic or extend/wrap the existing
logic by Fluid.

The `StrictArgumentProcessor` deals with argument types in a stricter
way: If the supplied argument value doesn't meet the type requirement,
an exception is thrown. For scalar types, automatic type conversion
is happening in a processing step to avoid errors that can be easily
solved by Fluid itself (like "string is required, integer given").

There might be consequences for custom ViewHelpers, however in
most cases this change will make a lot of custom validation code
that was necessary until Fluid v5 obsolete.
s2b added a commit that referenced this pull request Aug 18, 2025
Fluid v4.2.0 introduced a new API to process component and ViewHelper
arguments (see #1062). To avoid breaking changes in Fluid v4 with
how ViewHelpers handle their arguments, a `LenientArgumentProcessor`
has been introduced which has been used exclusively for ViewHelpers.
Components have used the new `StrictArgumentProcessor` from the
beginning.

With this breaking change, this is now unified: `StrictArgumentProcessor`
is now used for ViewHelper arguments as well. This allows us to define
an API in a follow-up patch that allows developers to define their custom
argument processing and validation logic or extend/wrap the existing
logic by Fluid.

The `StrictArgumentProcessor` deals with argument types in a stricter
way: If the supplied argument value doesn't meet the type requirement,
an exception is thrown. For scalar types, automatic type conversion
is happening in a processing step to avoid errors that can be easily
solved by Fluid itself (like "string is required, integer given").

There might be consequences for custom ViewHelpers, however in
most cases this change will make a lot of custom validation code
that was necessary until Fluid v5 obsolete.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants