PHP native attributes

In PHP 8.0, PHP added attributes to its vast arsenal of features. Later, the first native attribute, aka, available in the core of PHP, appeared. Here they are, for quick reference.

In PHP 8.2, there are 4 native attributes.

• Attribute
• ReturnTypeWillChange
• SensitiveParameter
• AllowDynamicProperties

Attribute

Attribute is the attribute to make a class a valid Attribute class. This definition sound pretty meta, but it is quite simple : there must be a first class that defines what an attribute is.

It is not compulsory, although, as a gesture of courtesy to the next developer : just add it to every attribute class, and all will be fine.

Available since PHP 8.0.

ReturnTypeWillChange

ReturnTypeWillChange characterize a method, whose returntype will change in child classes. This prevents PHP from emitting an error about a possible type mismatch.

It was created when the native PHP method JsonSerializable::jsonSerialize()received the mixed returntype. Although that type is the universal type, as it accepts everything, PHP reports a type mismatch with any method which doesn’t use that type. Adding this attribute relax that constraint.

It only works with PHP native methods, and has no effect on custom methods.

<?php

class x implements JsonSerializable { 
    #[\ReturnTypeWillChange] 
    function jsonSerialize() {} 
}

?>

Here is a list of PHP native interfaces and methods, which may require their usage :

• JsonSerializable::jsonSerialize()
• SessionHandlerInterface::open()
• SessionHandlerInterface::close()
• SessionHandlerInterface::read()
• SessionHandlerInterface::write()
• SessionHandlerInterface::destroy()
• SessionHandlerInterface::gc()
• Iterator::current()
• Iterator::next()
• Iterator::key()
• Iterator::valid()
• Iterator::rewind()
• Countable::count()
• IteratorAggregate::getIterator()
• php_user_filter::filter()
• ArrayAccess::offsetGet()
• ArrayAccess::offsetSet()
• ArrayAccess::offsetUnset()
• ArrayAccess::offsetExists()
• RecursiveIterator::getChildren()
• FilterIterator::accept()
• Exception::__wakeup()

Available since PHP 8.1.

SensitiveParameter

SensitiveParameter mark arguments as security sensitive, so that they will be automatically masked when a debug backtrace is displayed. Here is an example :

<?php

function foo($user, #[SensitiveParameter] string $password) {
    var_dump(debug_backtrace());
}

passwordHash('my', 'password');
?>

With PHP 8.2, the result is the following :

Array
(
    [0] => Array
        (
            [file] => /Users/famille/Desktop/analyzeG3/test.php
            [line] => 7
            [function] => foo
            [args] => Array
                (
                    [0] => my
                    [1] => SensitiveParameterValue Object

                )

        )

)

Properties are not covered by this parameter. For them, there is already the __debugInfo(), which may be used to hide any sensitive value, instead of displaying it.

Available in PHP 8.2.

AllowDynamicProperties

AllowDynamicProperties relaxes the compulsory property definition that starts with PHP 8.2. The default behavior is now to declare explicitely all properties. Yet, since dynamic properties are a valid use case, albeit a rare one, it is possible to relax this constraint by using this attribute.

<?php

#[AllowDynamicProperties]
class x { }

$x = new x;
// In PHP 8.2 : PHP Deprecated:  Creation of dynamic property x::$foo is deprecated 
$x->foo = 1;

?>

Another option is to use the Stdclass or extend it. This class is built-in with that attribute.

Available in PHP 8.2.