@no-named-parameters DocBlock attribute

PHP 8.0 brings Named Parameters support to PHP.

With named parameters, the names of the function/method names become part of the API, and changing the parameter name will be breaking change.


function findSomething(string $heystack, string $needle) {}

With a function declaration like this, named parameter allows to call the findSomething function with explicitly declaring the parameters, without having to depend on the order of parameters.

findSomething(heystack: "FooBar", needle: "Bar");

Now, if the author of the findSomething notices the typo in heystack word, and decides to fix it with haystack, all code that used named parameters feature will raise a fatal error:

function findSomething(string $haystack, string $needle) {}
findSomething(heystack: "FooBar", needle: "Bar");
Fatal error: Uncaught Error: Unknown named parameter $heystack in ...:...

Note that in case of an interface/inheritance chain, PHP considers parameter names of the called class and all its parents.


@no-named-arguments

Over at Roave/BackwardCompatibilityCheck project, a discussion lead to a new @no-named-arguments DocBlock attribute (which is not the same as PHP 8.0 attributes as it is a PHP 8.0 feature) that might add support to explicitly declare that the code does not provide backwards-compatibility promise for parameter names, discouraging the use of named parameters with it.

If this DocBlock attribute is present, it means the author explicitly declares that there will be no backwards compatibility promise for the parameter names, and users of the library should not use named parameters calling pattern for functions/methods from that library.

/**
 * @no-named-arguments
 */
function findSomething(string $haystack, string $needle) {}

It is also possible to set a custom description:

/**
 * @no-named-arguments No BC promise.
 */
function findSomething(string $haystack, string $needle) {}

Adoption of @no-named-arguments

Static Analyzers

Projects

From the top 100 most downloaded Composer projects:

  • PHPUnit: Parameter names are not covered by the backward compatibility promise for PHPUnit

IDEs

PHPStorm will support named parameters in PHPStorm 2020.3.

Named parameters in PHPStorm 2020.3

It appears that there is no support for @no-named-arguments attribute in PHPStorm or any other IDE yet.

Recent Articles on PHP.Watch

All ArticlesFeed 
PHP 8.2 Highlights: What's New and Changed

PHP 8.2 Highlights: What's New and Changed

Read about the highlights of PHP 8.2: Major new features, changes, and deprecated functionality.
How to install/upgrade PHP 8.2 on Debian and Ubuntu systems

How to install/upgrade PHP 8.2 on Debian and Ubuntu systems

A detailed and a quick-start guide on installing and upgrading PHP 8.2 on Debian and Ubuntu systems
All the Easter Eggs in PHP

All the Easter Eggs in PHP

A trip down the memory with PHP's Easter Eggs over the years
Subscribe to PHP.Watch newsletter for monthly updates

You will receive an email on last Wednesday of every month and on major PHP releases with new articles related to PHP, upcoming changes, new features and what's changing in the language. No marketing emails, no selling of your contacts, no click-tracking, and one-click instant unsubscribe from any email you receive.