Les attributs PHP fournissent des métadonnées structurées et lisibles par machine pour les classes, méthodes, fonctions, paramètres, propriétés et constantes. Ils peuvent être inspectés à l'exécution via l'API de réflexion, permettant un comportement dynamique sans modifier le code. Les attributs offrent un moyen déclaratif d'annoter le code avec des métadonnées. Les attributs permettent de découpler l'implémentation d'une fonctionnalité de son utilisation. Alors que les interfaces définissent une structure en imposant des méthodes, les attributs fournissent des métadonnées sur plusieurs éléments, y compris les méthodes, fonctions, propriétés et constantes. Contrairement aux interfaces, qui imposent l'implémentation de méthodes, les attributs annotent le code sans en modifier la structure. Les attributs peuvent compléter ou remplacer des méthodes d'interface optionnelles en fournissant des métadonnées plutôt qu'une structure imposée. Prenons une interface ActionHandler qui représente une opération dans une application. Certaines implémentations peuvent nécessiter une étape d'initialisation, tandis que d'autres non. Plutôt que d'obliger toutes les classes implémentant ActionHandler à définir une méthode setUp(), un attribut peut indiquer les besoins en initialisation. Cette approche augmente la flexibilité en permettant d'appliquer les attributs plusieurs fois si nécessaire. fileName)) { throw new RuntimeException("Le fichier n'existe pas."); } } #[SetUp] public function targetDirectoryExists() { if (!file_exists($this->targetDirectory)) { mkdir($this->targetDirectory); } elseif (!is_dir($this->targetDirectory)) { throw new RuntimeException("Le répertoire cible $this->targetDirectory n'est pas un répertoire."); } } public function execute() { copy($this->fileName, $this->targetDirectory . '/' . basename($this->fileName)); } } function executeAction(ActionHandler $actionHandler) { $reflection = new ReflectionObject($actionHandler); foreach ($reflection->getMethods() as $method) { $attributes = $method->getAttributes(SetUp::class); if (count($attributes) > 0) { $methodName = $method->getName(); $actionHandler->$methodName(); } } $actionHandler->execute(); } $copyAction = new CopyFile(); $copyAction->fileName = "/tmp/foo.jpg"; $copyAction->targetDirectory = "/home/user"; executeAction($copyAction); ]]> La syntaxe des attributs consiste en plusieurs composants clés. Une déclaration d'attribut commence par #[ et se termine par ]. À l'intérieur, un ou plusieurs attributs peuvent être listés, séparés par des virgules. Le nom de l'attribut peut être non qualifié, qualifié, ou complètement qualifié, comme décrit dans Utilisation de base des espaces de noms. Les arguments de l'attribut sont optionnels et sont placés entre parenthèses (). Les arguments peuvent uniquement être des valeurs littérales ou des expressions constantes. La syntaxe des arguments positionnels et nommés est supportée. Les noms d'attributs et leurs arguments sont résolus vers une classe, et les arguments sont passés à son constructeur lorsqu'une instance de l'attribut est demandée via l'API de réflexion. Il est donc recommandé d'introduire une classe pour chaque attribut. value = $value; } } // b.php namespace Another; use MyExample\MyAttribute; #[MyAttribute] #[\MyExample\MyAttribute] #[MyAttribute(1234)] #[MyAttribute(value: 1234)] #[MyAttribute(MyAttribute::VALUE)] #[MyAttribute(array("key" => "value"))] #[MyAttribute(100 + 200)] class Thing { } #[MyAttribute(1234), MyAttribute(5678)] class AnotherThing { } ]]> Pour accéder aux attributs des classes, méthodes, fonctions, paramètres, propriétés et constantes de classe, il convient d'utiliser la méthode getAttributes fournie par l'API de réflexion. Cette méthode retourne un tableau d'instances de ReflectionAttribute. Ces instances permettent d'interroger le nom de l'attribut, ses arguments, et peuvent être utilisées pour créer une instance de l'attribut représenté. Séparer la représentation obtenue par réflexion d'un attribut de son instance réelle offre un meilleur contrôle sur la gestion des erreurs, comme l'absence de classe d'attribut, les arguments mal typés ou les valeurs manquantes. Les objets de la classe d'attribut ne sont instanciés qu'après l'appel à ReflectionAttribute::newInstance, garantissant que la validation des arguments a lieu à ce moment-là. value = $value; } } #[MyAttribute(value: 1234)] class Thing { } function dumpAttributeData($reflection) { $attributes = $reflection->getAttributes(); foreach ($attributes as $attribute) { var_dump($attribute->getName()); var_dump($attribute->getArguments()); var_dump($attribute->newInstance()); } } dumpAttributeData(new ReflectionClass(Thing::class)); /* string(11) "MyAttribute" array(1) { ["value"]=> int(1234) } object(MyAttribute)#3 (1) { ["value"]=> int(1234) } */ ]]> Plutôt que d'itérer sur tous les attributs d'une instance de réflexion, il est possible de récupérer uniquement ceux d'une classe d'attribut spécifique en passant le nom de la classe d'attribut en argument. getAttributes(MyAttribute::class); foreach ($attributes as $attribute) { var_dump($attribute->getName()); var_dump($attribute->getArguments()); var_dump($attribute->newInstance()); } } dumpMyAttributeData(new ReflectionClass(Thing::class)); ]]> Il est recommandé de définir une classe distincte pour chaque attribut. Dans le cas le plus simple, une classe vide avec la déclaration #[Attribute] est suffisante. L'attribut peut être importé depuis le namespace global à l'aide d'une instruction use. Pour restreindre les types de déclarations auxquels un attribut peut être appliqué, passez un masque de bits en premier argument de la déclaration #[Attribute]. La déclaration de MyAttribute sur un autre type lèvera désormais une exception lors de l'appel à ReflectionAttribute::newInstance Les cibles suivantes peuvent être spécifiées: Attribute::TARGET_CLASS Attribute::TARGET_FUNCTION Attribute::TARGET_METHOD Attribute::TARGET_PROPERTY Attribute::TARGET_CLASS_CONSTANT Attribute::TARGET_PARAMETER Attribute::TARGET_ALL Par défaut, un attribut ne peut être utilisé qu'une seule fois par déclaration. Pour autoriser un attribut à être répété, il faut le spécifier dans le masque de bits de la déclaration #[Attribute] en utilisant le drapeau Attribute::IS_REPEATABLE.