#[\ReturnTypeWillChange]: what the attribute does, and when it’s the wrong fix
Short answer
#[\ReturnTypeWillChange] is an attribute that silences one deprecation notice: “Return type of … should either be compatible with …”, which PHP 8.1 and later show when a class overrides a built-in method (from ArrayAccess, Countable, Iterator and others) without declaring its return type. It changes nothing else, and it’s ignored on PHP 7. It is a stopgap for code that must still run on old PHP versions; the real fix is to declare the return type, which works without a notice on PHP 8.0 and later.
The notice it silences
A settings class lets code read its values like an array, by implementing PHP’s ArrayAccess, without return types on its methods. PHP 7.4 and 8.0 run it silently; from PHP 8.1 on, PHP adds a notice per method:
wp-content/plugins/site-settings/includes/class-settings.php
<?php
class Site_Settings implements ArrayAccess {
private $values = ['colour' => 'blue'];
public function offsetExists($key) { return isset($this->values[$key]); }
public function offsetGet($key) { return $this->values[$key]; }
public function offsetSet($key, $value) { $this->values[$key] = $value; }
public function offsetUnset($key) { unset($this->values[$key]); }
}
$settings = new Site_Settings();
echo $settings['colour'], "\n";
blueblueDeprecated: Return type of Site_Settings::offsetExists($key) should either be compatible with ArrayAccess::offsetExists(mixed $offset): bool, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /var/www/html/wp-content/plugins/site-settings/includes/class-settings.php on line 5
Deprecated: Return type of Site_Settings::offsetGet($key) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /var/www/html/wp-content/plugins/site-settings/includes/class-settings.php on line 6
Deprecated: Return type of Site_Settings::offsetSet($key, $value) should either be compatible with ArrayAccess::offsetSet(mixed $offset, mixed $value): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /var/www/html/wp-content/plugins/site-settings/includes/class-settings.php on line 7
Deprecated: Return type of Site_Settings::offsetUnset($key) should either be compatible with ArrayAccess::offsetUnset(mixed $offset): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /var/www/html/wp-content/plugins/site-settings/includes/class-settings.php on line 8
blueDeprecated: Return type of Site_Settings::offsetExists($key) should either be compatible with ArrayAccess::offsetExists(mixed $offset): bool, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /var/www/html/wp-content/plugins/site-settings/includes/class-settings.php on line 5
Deprecated: Return type of Site_Settings::offsetGet($key) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /var/www/html/wp-content/plugins/site-settings/includes/class-settings.php on line 6
Deprecated: Return type of Site_Settings::offsetSet($key, $value) should either be compatible with ArrayAccess::offsetSet(mixed $offset, mixed $value): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /var/www/html/wp-content/plugins/site-settings/includes/class-settings.php on line 7
Deprecated: Return type of Site_Settings::offsetUnset($key) should either be compatible with ArrayAccess::offsetUnset(mixed $offset): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /var/www/html/wp-content/plugins/site-settings/includes/class-settings.php on line 8
bluephp.net explains why: “As of PHP 8.1.0, a tentative phase of transitioning to return type declarations for internal class methods began. Most non-final internal methods now require overriding methods to declare a compatible return type.” (php.net)
What the attribute does
Adding #[\ReturnTypeWillChange] above such a method tells PHP: the return type will be added later. The notice disappears; nothing else changes. On PHP 7.4 the line starts with #, which older PHP reads as a comment, so the same code still runs there:
wp-content/plugins/site-settings/includes/class-settings.php
<?php
class Site_Settings implements ArrayAccess {
private $values = ['colour' => 'blue'];
#[\ReturnTypeWillChange]
public function offsetExists($key) { return isset($this->values[$key]); }
#[\ReturnTypeWillChange]
public function offsetGet($key) { return $this->values[$key]; }
#[\ReturnTypeWillChange]
public function offsetSet($key, $value) { $this->values[$key] = $value; }
#[\ReturnTypeWillChange]
public function offsetUnset($key) { unset($this->values[$key]); }
}
$settings = new Site_Settings();
echo $settings['colour'], "\n";
blueblueThat’s its purpose: code that must still support PHP 7.4 can silence the notice without breaking older sites.
The real fix
Declare the return type the message names. : bool, : mixed, : void and so on make the method compatible, with no attribute and no notice, on PHP 8.0 and 8.5:
wp-content/plugins/site-settings/includes/class-settings.php
<?php
class Site_Settings implements ArrayAccess {
private $values = ['colour' => 'blue'];
public function offsetExists($key): bool { return isset($this->values[$key]); }
public function offsetGet($key): mixed { return $this->values[$key]; }
public function offsetSet($key, $value): void { $this->values[$key] = $value; }
public function offsetUnset($key): void { unset($this->values[$key]); }
}
$settings = new Site_Settings();
echo $settings['colour'], "\n";
blueblueNote mixed exists only from PHP 8.0, so a plugin that still supports PHP 7.4 uses the attribute for those methods until it drops 7.4.
For site owners
You don’t need to change anything yourself: the notice keeps the code working. Update the plugin, or send one line of the message to its developer. Meanwhile log notices instead of showing them.
A check that reads code finds the methods that still need a return type or the attribute, while the site runs PHP 8.0. CompatNav reports them as deprecation notices. More PHP 8.1 changes: WordPress and PHP 8.1.
Key takeaways
- The notice appears on PHP 8.1 and later when a method overriding a built-in one has no return type.
#[\ReturnTypeWillChange]hides that notice for one method; the code is otherwise unchanged.- On PHP 7.4 the attribute is just a comment: old versions ignore it, so it’s safe for code that still supports them.
- The proper fix is to declare the return type (for example
: bool), as the message names it. - A check that reads code finds methods that still need one or the other.
Frequently asked questions
Is it OK to add #[\ReturnTypeWillChange] everywhere?
It works, but it only postpones the change: PHP’s own message calls it a way to temporarily suppress the notice. Declaring the return type is the lasting fix.
Why does the notice mention mixed?
Because some built-in methods return mixed (any type). The message shows the exact signature PHP expects, such as ArrayAccess::offsetGet(mixed $offset): mixed.
Does the attribute work on PHP 7.4?
PHP 7.4 reads #[ as the start of a comment, so the line is ignored there. That’s why plugins supporting old PHP versions use it.
Check your own site before you upgrade
CompatNav is a free WordPress plugin. It reads the code of your plugins and themes on your own server and tells you, in plain words, what will break and what will only show notices on the PHP version you choose. It never changes your code. It can’t see problems that only appear while code runs with real data, so a quick check of your site after the upgrade still matters.
Sources
About the code examples: each output is the real output of the code shown, run with the official PHP builds, without a php.ini, with all errors reported and displayed. Only the file path was replaced by a neutral server path.