Add stateless ApiResource attribute

[mtarld]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tickets
License	MIT
Doc PR	TODO

In Symfony 5.1, it will be possible to declare routes as stateless (symfony/symfony#35732)
For stateless routes, kernel will either throw an exception (debug enabled) or log a warning (debug disabled) on session usage.

As API Platform shouldn't use session (according to REST architecture constraints), this PR proposes to add an ApiResource attribute in order to declare related routes as stateless: stateless

false will be the default in order to prevent BC break (and we could set it at true in the next major)

One question still remains. API Plateform could be on top of older version of Symfony (4.x, 5.0.x).
How to handle it ?

• Throw an exception saying that this feature isn't supported for that Symfony's version
• Log a warning saying that this feature isn't supported for that Symfony's version
• Do nothing (which is dangerous IMO)

WDYT ?

[teohhanhui]

I think the default cannot be false, but null. This allows us to trigger a deprecation error when it's null, so as to force the user to set it to true (or false). And then we can default to true in 3.0

WDYT @dunglas?

[teohhanhui]

API Platform could be on top of older version of Symfony (4.x, 5.0.x).
How to handle it ?

We could detect the version of symfony/http-kernel by checking if Symfony\Component\HttpKernel\Exception\UnexpectedSessionUsageException exists. I don't think doing nothing is dangerous, as it's just an extra safety net that didn't exist before, so we use it if it exists, otherwise nothing has changed.

[mtarld]

We could detect the version of symfony/http-kernel by checking if Symfony\Component\HttpKernel\Exception\UnexpectedSessionUsageException exists. I don't think doing nothing is dangerous, as it's just an extra safety net that didn't exist before, so we use it if it exists, otherwise nothing has changed.

We could as well use version_compare on Kernel::VERSION ?

Furthermore, what I meant is just telling the developer that he is using stateless but nothing will occur (as it's not handled by Symfony)

[teohhanhui]

We could as well use version_compare on Kernel::VERSION ?

Uhh, yeah, I forgot this is the HttpKernel we're talking about. Lol...

telling the developer that he is using stateless but nothing will occur (as it's not handled by Symfony)

Personally, I think it's fine to just do nothing. It should be documented that this feature requires Symfony 5.1

[mtarld]

Ok, using the current approach, stateless priority will be handled as the following:

1. Operation stateless attribute in attributes
2. Operation stateless attribute
3. Resource stateless attribute in attributes
4. Resource stateless attribute
5. Global defaults

Same goes for subresources.

[teohhanhui]

Missing deprecation: #3436 (comment)

[teohhanhui]

I think there are some fundamental problems with the current implementation... This needs work.

[teohhanhui]

And sorry for the earlier confusion, there's no explicit attributes key under each operation. The attributes are just directly specified.

[mtarld]

No worries! I should have been aware of that. The new implementation is much cleaner now, thanks.

[dunglas]

Could you rebase please?