The PropertyInfo component tells the rest of Symfony how to read and write the
properties of your objects. It finds the methods by convention: getName(),
isActive(), setName(), addRole(), removeRole(), etc. That works
for most classes, but not for the ones that prefer names taken from the domain,
like rename() or grant(). Symfony 8.2 lets you name those methods
yourself and improves the metadata of property hooks.
The #[WithAccessors] Attribute
Methods that don't follow the naming conventions were invisible to Symfony, and
the only solution was to write a custom extractor. In Symfony 8.2, add the new
#[WithAccessors] attribute to a property to tell which methods read and
write it:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
namespace App\Entity;
use Symfony\Component\PropertyInfo\Attribute\WithAccessors;
class User
{
#[WithAccessors(getter: 'displayName', setter: 'rename')]
private string $name;
#[WithAccessors(getter: 'grantedRoles', adder: 'grant', remover: 'revoke')]
private array $roles = [];
public function displayName(): string
{
return $this->name;
}
public function rename(string $name): void
{
$this->name = $name;
}
// ... grantedRoles(): array, grant(string $role): void
// and revoke(string $role): void are defined in the same way
}
Everything that relies on this metadata now uses those methods, including the PropertyAccess component and the features built on top of it, such as forms:
1 2 3 4 5 6 7 8
$propertyAccessor->getValue($user, 'name'); // calls displayName()
$propertyAccessor->setValue($user, 'name', 'Jane Doe'); // calls rename()
// calls grant() and revoke() to turn the current roles into the new ones
$propertyAccessor->setValue($user, 'roles', ['ROLE_EDITOR', 'ROLE_REVIEWER']);
// the type comes from the argument of the adder: list<string>
$propertyInfo->getType(User::class, 'roles');
The four arguments are optional, but adder and remover must be defined
together. If a method doesn't exist, Symfony throws a MappingException
instead of silently falling back to the conventions.
Custom Accessors in the Serializer
The serializer works the other way around: it loops over the public methods of
the class and needs to know which property each one exposes. It did that by
removing the usual prefixes, so a method like displayName() was ignored. In
Symfony 8.2, the serializer asks PropertyInfo for the property behind each
method, so #[WithAccessors] works when serializing and deserializing:
1 2 3 4 5 6 7 8 9
$user = new User();
$user->rename('Jane Doe');
$user->grant('ROLE_EDITOR');
$json = $serializer->serialize($user, 'json');
// {"name":"Jane Doe","roles":["ROLE_EDITOR"]}
// calls rename() and grant()
$user = $serializer->deserialize($json, User::class, 'json');
Property Hooks Metadata
With property hooks, reading or writing a public property can run some logic,
and some properties don't store any value. Libraries that map or hydrate objects
need to know that, and until now they had to use reflection themselves. In
Symfony 8.2, the read and write information returned by ReflectionExtractor
tells if a property has hooks and if it's virtual:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
class Customer
{
public string $firstName = '';
public string $lastName = '';
public string $email {
set => strtolower($value);
}
public string $fullName {
get => $this->firstName.' '.$this->lastName;
}
}
$extractor = new ReflectionExtractor();
$extractor->getReadInfo(Customer::class, 'fullName')->hasHook(); // true
$extractor->getReadInfo(Customer::class, 'fullName')->isVirtual(); // true
$extractor->getReadInfo(Customer::class, 'email')->hasHook(); // false (no "get" hook)
$extractor->getWriteInfo(Customer::class, 'email')->hasHook(); // true
$extractor->getReadInfo(Customer::class, 'email')->isVirtual(); // false
$extractor->getReadInfo(Customer::class, 'firstName')->hasHook(); // false
These methods return the same values as PHP's ReflectionProperty::hasHook()
and ReflectionProperty::isVirtual(). They return null when the
information is unknown, for example when the property is accessed via a method.
This is only metadata: PropertyAccess keeps reading and writing properties as
before.