PHP: rfc:same-site-parameter

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Add SameSite cookie attribute parameter ======

  * Version: 0.1
  * Date: 2022-11-16
  * Author: George Peter Banyard, <girgias@php.net>
  * Status: Under Discussion
  * Target Version: PHP 8.3
  * Implementation: [[https://github.com/php/php-src/pull/10317]]
  * First Published at: [[http://wiki.php.net/rfc/same-site-parameter]]

===== Introduction =====

The support for the SameSite cookie attribute has been added in PHP 7.3.
However, it can only be set by passing an array of options with the ''"samesite"'' key defined to the chosen value, this contrasts with all the other attributes.

This RFC proposes to add a SameSite parameter to all relevant functions.

==== Background and Motivation ====

Support for the SameSite attribute was added in the [[rfc:same-site-cookie|Same Site Cookie]] RFC, the vote was split between two implementations, the one which was implemented, changing the 3rd argument to accept an array of optional attributes referenced by keys, and adding a SameSite parameter.

The proposal to add a SameSite parameter was unanimously declined, however, we believe this proposal should be revisited as PHP has changed and gained additional capabilities since version 7.3.

One of the primary arguments against adding a parameter is that the function already has 6 optional parameters, and attempting to set the SameSite attribute would require providing all the other optional parameters.
However, with the introduction of named arguments in PHP 8.0 this is no more an issue.

Moreover, parameters provide the benefit of type declarations, which can eliminate sources of bugs via the use of static analysis.

===== Proposal =====

The proposal consists of two parts.
First, add the following enumeration:

<PHP>
enum SameSite {
    case None;
    case Lax;
    case Strict;
}
</PHP>

Which contains the 3 valid values for the SameSite attribute defined in the [[https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-the-samesite-attribute|IETF 6265 RFC draft]].

Secondly, add a <php>SameSite $sameSite = SameSite::Lax</php> parameter to:

  * <php>setcookie(string $name, string $value = "", array|int $expires_or_options = 0, string $path = "", string $domain = "", bool $secure = false, bool $httponly = false, SameSite $sameSite = SameSite::Lax)</php>
  * <php>setrawcookie(string $name, string $value = "", array|int $expires_or_options = 0, string $path = "", string $domain = "", bool $secure = false, bool $httponly = false, SameSite $sameSite = SameSite::Lax)</php>
  * <php>session_set_cookie_params(array|int $lifetime_or_options, ?string $path = null, ?string $domain = null, ?bool $secure = null, ?bool $httponly = null, SameSite $sameSite = SameSite::Lax)</php>
 
Moreover, if attempting to set the SameSite attribute to None, the Secure attribute must be set, otherwise a ValueError will be raised.
This behaviour aligns with section 5.6.19 of the [[https://datatracker.ietf.org/doc/draft-ietf-httpbis-rfc6265bis/|Draft IETF RFC 6265bis]]:
<blockquote>
19.  If the cookie's "same-site-flag" is "None", abort these steps and ignore the cookie entirely unless the cookie's secure-only-flag is true.
</blockquote>

==== Implementation details ====

Currently, if no SameSite attribute is set, the Set-Cookie header is emitted without any ''SameSite'' attribute relying on the default behaviour of user agents, which used to be ''SameSite=None'' but is being replaced by ''SameSite=Lax'' in the IETF RFC 6265bis Cookies: HTTP State Management Mechanism draft, and this behavioural change has already started in some user agents.

As it is recommended to set this attribute, we align the default value with the draft internet standard.
But to preserve BC at this stage, the default function value of Lax is not enforced.
This would be similar to making this parameter nullable and accepting null,
however, doing as such is undesirable because we would then need to deprecate passing null to this parameter.

===== Backward Incompatible Changes =====

This RFC does not contain any backwards incompatible changes for the PHP 8 major release cycle.

In PHP 9, the <php>SameSite $sameSite = SameSite::Lax</php> value will be enforced. Meaning, every cookie header set via the relevant function will contain the ''SameSite=Lax'' attribute.

===== Proposed PHP Version =====

Next minor version, i.e. PHP 8.3.

===== Proposed Voting Choices =====

As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted.

Voting started on 2023-XX-XX and will end on 2023-XX-XX.
<doodle title="Accept Add SameSite cookie attribute parameter RFC?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Implementation =====

GitHub pull request: https://github.com/php/php-src/pull/10317

After the project is implemented, this section should contain

  * the version(s) it was merged into
  * a link to the git commit(s)
  * a link to the PHP manual entry for the feature

===== References =====
Page Tools
