rfc:named_parameter_alias_attribute

PHP RFC: #[NamedParameterAlias] 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

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.

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

rfc/named_parameter_alias_attribute.txt · Last modified: 2020/12/19 11:41 by beberlei