Add tag to declare variable types

[drjayvee]

See #4003 and #4009 for some context. In short, since the PHP language itself as well as its community are moving to (optional) stricter typing, it makes sense for Twig to support this as well by adding a types tag.

@fabpot said he'd like to bootstrap a spec. This is the first draft. Everything is up for debate, obviously. In addition, I've put in italics parts of the spec that I have doubts about myself.

Given the discussions below (thanks all for contributing), I think the spec is now crystallizing. Consider it a beta.

Syntax

The types tag contains a mapping of variable name to constant type string (no expression or interpolation):

{% types {variable: 'Type'} %}

The reason for quoting the type is that several characters (e.g., \) are currently not supported by the Lexer. It also allows analyzer implementations to freely specify the syntax.

The variable name must not be quoted. This is to ensure that only valid names can be used.

Types

The syntax and content of the types are not part of this specification. This provides complete freedom to extensions that inspect and analyze the tags. It also keeps the implementation in Twig very simple and robust.

(In practice, it's likely that implementations will rely on widely-used specifications like PHPDoc / PHPStan types.)

Examples

Here are two examples:

{% types {foo: 'bool'} %}

{% types {
  bar: "list<int>",
  baz: '?\Name\Space\ClassName'
} %}

Behavior

This specification does require any behavior other than validating the syntax for the tag itself. The tag does not lead to generated PHP code.

Usage

This section describes possible implementations to demonstrate the utility of this addition.

It is up to extensions developed by the community to implement any of this.

Development time

The types can be useful during development by enabling IDEs to auto-complete code, issue warnings, and more.

This is already implemented by the Symfony Support plugin for PHPStorm when using comments to declare variable types (e.g., {# @var id int #}).

These tags also provide precious documentation about the variables expected in a template's context.

Compile time

During compilation, a Twig extension can:

1. Check the type and throw an appropriate Exception if it is not valid.
2. For objects, check whether properties and more methods exist, and throw an appropriate Exception if there is none.
3. Add run-time checks (see below).

Run time

During run time, behavior may depend on strict_variables environment option:

• If disabled (likely in production environments), a PHP warning is triggered.
• If enabled, (development and testing environments), an Exception is thrown.

Possible extensions

• Use property access or method call for objects instead of twig_get_attribute() to improve performance. (see Prevent calling twig_get_attribute by generating the guessed PHP code instead #3928)

[JoshuaBehrens]

Would you mind linking

Use property access or method call for objects instead of twig_get_attribute() to improve performance

with #3928 so we can see, when this is unblocked by this issue? :)

[ruudk]

If I may suggest: instead of deciding the possible var type values, why not accept any valid PHPDoc type. Together with PHPStan's PHPDoc Parser we can parse them into PhpDocNode's that then can be transformed to PHPStan types. From there, it can be used to build compile time assertions. Doing it from scratch feels like reinventing the wheel 😅

We could still only accept a subset from the possible types, and let others improve it over time via PR's.

[ericmorand]

Give it enough time and Twig will end up being PHTML, the format it was supposed to replace.

[drjayvee]

If I may suggest: instead of deciding the possible var type values, why not accept any valid PHPDoc type

Thanks, that's a good suggestion. I was mindful of not reinventing the wheel and hoped that we could re-use parts of PHPStan to parse and evaluate the types. Should we perhaps go all the way and support any PHPStan type? I'll add a sentence in italics to that section for now.

I'll add support for nullable types, which I forgot. But the more gets added, the more sense it makes to just go all the way

[willrowe]

I'm not sure if this would be the best place to implement this, but a lot of times I have a flag in a template to allow certain markup to be turned on or off, but need to retain previous functionality for other templates that are already including it. I usually have to add a set tag to check if the variable exists and set it to a default value if not. I already include a comment at the top of the template denoting what variables are used in the template, but it would be nice to be able to provide a default value for any optional variables in the same place that I denote the type, replacing the need for a bunch of set tags.

[ruudk]

{% var variable Type %}

I think that the order should be the same as with inline PHPDocs:

{% var Type variable %}

[willrowe]

I agree with @ruudk on the order. It would also match how class properties and argument types are defined in PHP.

Also, going along with that and clarifying what I was proposing in #4165 (comment), this is what it would look like to specify a default value:

{% var Type variable = 'default_value' %}
{% var bool flag = false %}

[drjayvee]

I think that the order should be the same as with inline PHPDocs:

Agreed. I've updated the OP. (While I prefer the original order, we should follow existing conventions.)

We could also consider an optional description. phpDocumentor supports this, but PHPStan doesn't seem to.

{% var bool foo to foo or not to foo %}

Then again, this makes the tag less readable, plus there's nothing Twig itself would do with this. The alternative is to just add a comment (before or afterwards) for humans:

{% var bool foo %} {# to foo or not to foo #}

[ruudk]

We could also consider an optional description. phpDocumentor supports this, but PHPStan doesn't seem to.

What's the point of providing a description there?
The reason why PHPStan doesn't support it at that position is that the @var is already inside a comment. So you can add a comment above the @var to explain the why.

Same can be done with Twig:

{# I need to explain this somehow #}
{% var 'bool' foo %}

PS: The Type should be a string (ConstantStringExpression).

The variable could be a NameExpression or ConstantStringExpression.

[drjayvee]

it would be nice to be able to provide a default value for any optional variables in the same place that I denote the type, replacing the need for a bunch of set tags.

I personally actually disagree on principle: declaring the type and any value should not be mixed. This does bring up two interesting questions, though.

First, should we add undefined as a possible type? Or should template developers ensure variables are always set (possibly using null)? Since var is all about stricter typing, I would prefer the latter.

Second, what do we do about variables defined using set? Should users add var afterwards? Or should Twig try to auto-detect the type? That would be very difficult (or outright infeasible) since set can use an expression (using literals and even function calls).

[drjayvee]

What's the point of providing a description there? The reason why PHPStan doesn't support it at that position is that the @var is already inside a comment. So you can add a comment above the @var to explain the why.

Exactly. I was just thinking out loud.

PS: The Type should be a string (ConstantStringExpression).

The variable could be a NameExpression or ConstantStringExpression.

Why should the type be quoted? It's not an expression (although I confess not to know the definition of "expression"). It also looks really weird to me and is inconsistent with PHPStan.

Do you think the implementation could be tricky if the type isn't quoted?

Update: the implementation does indeed run into issues. Therefore, I've amended the spec to quote types.

[willrowe]

I personally actually disagree on principle: declaring the type and any value should not be mixed.

@drjayvee can you explain more?

[drjayvee]

I personally actually disagree on principle: declaring the type and any value should not be mixed.

@drjayvee can you explain more?

@willrowe, absolutely! I should have done that straight away.

But first off, I want to point out that this is just my personal opinion. I'd love to hear what other people think.

One reason I dislike your proposal is that Twig already has three ways of setting values:

1. injecting them into the template's context (in PHP)
2. using the set tag
3. defining a macro argument

I feel like adding a fourth way leads to bloat. (Or worse, conflicts.)

Macros arguments already have support for default values. (In fact, they're never even undefined, since they get an implicit default of null. I'm actually proposing to make this distinction clear in the AST: #4010)

The set tag already supports your use case just fine:

{% set foo = foo ?? 'bar' %}

{# or, in case null must be kept as-is, more strictly: #}
{% set foo = foo is defined ? foo : 'bar' %}

The second problem is that it feels like mixing concerns. I'm envisioning the var tag to be analogous to PHPStan's @var annotation, not PHP's native type declarations (e.g., for class properties and function arguments). Another way of looking at var is that it only affects template code (and therefore provide value) after the tag. You can read it like "from here on out, foo is guaranteed to be of this type".

However, I'm not super convinced by my own argument here, since both PHP and Typescript (as just two examples) do let you declare types and default values in one go in many places (e.g., function default values and class properties).

A third problem is that var is currently envisioned to have no effect on compiled templates. I think this is a sensible design goal is prevent compatibility issues and make the change more palatable to maintainers and users. If var does support default values, it will have to affect compilation output.

I hope I explained clearly. I'm sincerely curious as to you what you think now you know my reasoning.

[ericmorand]

@drjayvee

{% var ?\Name\Space\ClassName baz %}

What does it mean? What is \Name\Space\ClassName and how is such a type supposed to be declared?