====== PHP RFC: #[NamedParameterAlias] Attribute ======

  * Version: 1.0
  * Date: 2020-12-19
  * Author: Benjamin Ebelei 
  * Status: Under Discussion
  * First Published at: http://wiki.php.net/rfc/named_parameter_alias_attribute

===== Introduction =====

During the RFC vote and discussion on the named params RFC one frequent concern was that the names of parameters are now part of the public
API surface, changing from PHP up to version 7.4 where the parameter names could be changed at any time without backwards compatilbity concerns.

Renaming a parameter name of a public API, for example in open source libraries, can now break the clients of that code that rely on these names.

A prudent refactoring and deprecation strategy of an old parameter name would allow users to simoultaneously use the old and the new name for
a short amount of time to allow for a step-by-step migration of users code.

This proposal attempts to address this need by introducing alias names for parameters with the support of an attribute.

===== Proposal =====

<nowiki>Developers can put a new attribute #[NamedParameterAlias] on arguments of a function or method:</nowiki>

<code php>
<?php

use NamedParameterAlias;

// Old function signature:
function log($arg1) {}

// New function signature introduces better name
function log(#[NamedParameterAlias("arg1")] $message) {}
</code>

With the signature using the alias attribute both kinds of named parameter calls will work:

<code php>
<?php

log(arg1: "Hello World!");
log(message: "Hello World!");
</code>

This attribute is *not* currently repeatable, which means it will allow only one alias to be defined per parameter.

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

A class with the name "NamedParameterAlias" is introduced into the global namespace.

===== Proposed PHP Version(s) =====

8.1

===== RFC Impact =====
==== To SAPIs ====
None

==== To Existing Extensions ====
None

==== To Opcache ====

None

==== New Constants ====

None

==== php.ini Defaults ====

None

===== Open Questions =====

  * The name of the attribute is still open for debate. Is there a better name?
  * Current implementation is for parameters of userland functions/method. But given the quick schedule between named parameters and the final PHP 8.0 release there is probably the need to use this API for core/internal APIs as well.
  * Should this attribute be repeatable on a single parameter?

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

Accept #[NamedParameterAlias] attribute into core?

===== Patches and Tests =====

https://github.com/php/php-src/pull/6522