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

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.

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

<?php
 
use NamedParameterAlias;
 
// Old function signature:
function log($arg1) {}
 
// New function signature introduces better name
function log(#[NamedParameterAlias("arg1")] $message) {}

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

<?php
 
log(arg1: "Hello World!");
log(message: "Hello World!");

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

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

8.1

None

None

None

None

None

• 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?

Accept #[NamedParameterAlias] attribute into core?

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