Attributes in PHP 8

This talk provides an overview of the "metadata in code" functionality introduced in PHP 8.0 and extended in PHP 8.1. These attributes replace the previously everyday use of docblocks for metadata configuration with a much better system in the core of the PHP language. With attributes, you can provide a machine-readable specification of code elements such as classes, properties, methods, arguments, and constants. We will discuss use cases, the implementation, and pitfalls you should avoid when using attributes.

Transcript

1. ATTRIBUTES IN PHP 8 Metadata in the Language, Not in Docblocks Benjamin Eberlei
2. ATTRIBUTES IN PHP 8 1. Hello World 2. History of Metadata in PHP 3. Attributes in PHP 8 4. Use-Cases and Examples AGENDA 2
3. Hello World Example #[Route("/hello/world")] function helloWorld() { echo "Hello World"; } $router = new Router(); $router->collectRoutePaths(); $router->dispatch($_SERVER['REQUEST_URI'], $_GET);
4. Declaring an Attribute Class #[Attribute] class Route { public readonly string $path; public function __construct(string $path) { $this->path = $path; } }
5. Fetching Attributes from Reflection public function collectRoutePaths(): void { foreach (get_defined_functions()['user'] as $fn) { $refl = new ReflectionFunction($fn); $attributes = $refl->getAttributes(Route::class); foreach ($attributes as $attribute) { $this->collectRoutePath($attribute, $refl); } } }
6. Instantiating Attribute from Reflection private function collectRoutePath( ReflectionAttribute $reflectionAttribute, ReflectionFunction $reflFn ): void { $attribute = $reflectionAttribute->newInstance(); $this->paths[$attribute->path] = [ 'function' => $reflFn, 'attribute' => $attribute ]; }
7. Tying Metadata and Code Together public function dispatch(string $path) { if (isset($this->paths[$requestedPath])) { $route = $this->paths[$requestedPath]; $route['function']->invoke(); } else { http_response_code(404); } }
8. Meta-Programming Attributes allow to implement a feature “on the meta-level”, without knowledge who will use it.
9. HISTORY OF METADATA IN PHP 20 Years of Evolution 9
10. History of Docblocks in PHP • February 2000: First discussions about phpdoc format and tooling • October 2000: Ulf Wendel presents first version of phpdoc at PHP Congress in Cologne • March 2003: First code for Reflection*::getDocComment by Andrei Zmievski, shipping in PHP 5 • 2004/2005: @test Annotation (and others) in PHPUnit • 2010: Doctrine ORM 2.0 released with Annotations Parser 10
11. Docblocks /** * @param int $x * @param int $y * @return int */ function ($x, $y) { return $x + $y; }
12. Reflection API for Docblocks (2005) $reflectionFunction = new ReflectionFunction('add'); var_dump($reflectionFunction->getDocComment()); ?> string(56) "/** * @param int $x * @param int $y * @return int */"
13. Doctrine Annotations /** @Entity(repositoryClass=PostRepository::class) */ class Post { } /** @Annotation */ final class Entity { public $repositoryClass; }
14. Doctrine Annotations $reflectionClass = new ReflectionClass(Post::class); $annotationReader = new AnnotationReader(); $entityAnnnot = $annotationReader->getClassAnnotation( $reflectionClass, Entity::class, ); echo $entityAnnnot->repositoryClass;
15. HISTORY OF METADATA IN PHP • “ClassMetadata RFC”, 2010, Guilherme Blanco, Pierrick Charron“ • Annotations in DocBlock”, 2011, Guilherme Blanco, Pierrick Charron“ • Reflection Annotations using the Doc-Comment”, 2013, Yahav Gindi Bar • “Attributes”, April 2016, Dmitry Stogov • “Simple Annotations”, Mai 2016, Rasmus Scholz • “Annotations v2”, Februar 2019, Michał Brzuchalski • “Attributes v2”, Februar 2020, Martin Schröder, Benjamin Eberlei 15
16. HISTORY OF METADATA IN PHP Various Syntax suggestions and after three separate RFCs voting on them we decided on: #[Attribute] The following alternatives were rejected: @@Attribute @[Attribute] <<Attribute>> @:Attribute @{Attribute} 16
17. ATTRIBUTE IN PHP 8 Metadaten als Feature der Sprache 17
18. SYNTAX use PHPUnit\Framework\Attributes\Test; use PHPUnit\Framework\TestCase; final class ExampleTest extends TestCase { #[Test] public function it_does_something(): void { // ... } }
19. SYNTAX use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; final class ExampleTest extends TestCase { #[TestDox('It does something')] public function testOne(): void { // ... } }
20. SYNTAX use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; final class ExampleTest extends TestCase { #[TestDox(text: 'It does something')] public function testOne(): void { // ... } }
21. SYNTAX use PHPUnit\Framework\Attributes\Test; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; final class ExampleTest extends TestCase { #[Test] #[TestDox(text: 'It does something')] public function testOne(): void { // ... } }
22. SYNTAX use PHPUnit\Framework\Attributes\Test; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; final class ExampleTest extends TestCase { #[Test, TestDox(text: 'It does something')] public function testOne(): void { // ... } }
23. SYNTAX use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; final class ExampleTest extends TestCase { #[TestWith(["hello world", "foo" => 1])] #[TestWith([new \stdClass, \PDO::PARAM_INT])] public function testOne($a, $b): void { // … } }
24. SYNTAX Use of # as beginning symbol allows attributes to be interpreted as comments in PHP 7 and before.
25. TARGETS OF ATTRIBUTES • Classes • Methods • Functions • Constants • Class Properties • Function/Method Arguments
26. TARGETS OF ATTRIBUTES #[FunctionAttr] function test(#[ArgumentAttr] $argument) {} #[ClassAttr] class AttributedClass { #[ConstantAttr] const FOO = 1; #[PropertyAttr] public $bar; #[MethodAttr] public function baz() {} }
27. ReflectionAttribute class ReflectionAttribute { public function getName(): string {} public function getArguments(): array {} public function getTarget(): int {} public function isRepeated(): bool {} public function newInstance(): object {} }
28. Attributes map to Classes An attribute is namespaced and maps to a class name. This class is not required to exist until/unless ReflectionAttribute::newInstance() is called.
29. Attribute Classes use Attribute; #[Attribute(flags: Attribute::TARGET_FUNCTION| Attribute::TARGET_METHOD|Attribute::IS_REPEATABLE )] class Route { public readonly string $path; public function __construct(string $path) { $this->path = $path; } }
30. Validation of Attribute Flag A violation of the target or repeated attribute flags only leads to an error upon using ReflectionAttribute::newInstance()
31. Use-Cases: PHP Internal Attributes
32. Attributes in PHP: #[SensitiveParameter] use SensitiveParameter; class ConnectionFactory { public function connect( string $host, string $user, #[SensitiveParameter] string $password) { } }
33. Attributes in PHP: #[SensitiveParameter] Fatal error: Uncaught Exception Stack trace: #0 (15): ConnectionFactory->connect('foo', 'bar', Object(SensitiveParameterValue))
34. Attributes: #[AllowDynamicProperties] <?php use AllowDynamicProperties; class UserA { } #[AllowDynamicProperties] class UserB { }
35. Attributes: #[AllowDynamicProperties] <?php $o1 = new UserA(); // Deprecated: Creation of dynamic property UserA::name is deprecated $o1->name = true; $o2 = new UserB(); $o2->name = true;
36. Use-Cases: Validating Objects
37. Validating Objects class User { #[NotBlank(message: "Name should not be blank.")] public string $name; #[Minimum(min: 18, message: "Must be 18+ years old.")] public int $age; #[Email(message: "E-Mail address is not valid.")] public string $email; }
38. Validating Objects $user = new User(); $user->name = ''; $user->age = 17; $user->email = 'foo'; $validator = new Validator(); $violations = $validator->validateObject($user); var_dump($violations); // array("name" => array("Name should not be blank"), ...)
39. Validating Objects abstract class Assertion { public abstract function isValid(mixed $value): bool; }
40. Validating Objects #[Attribute(flags: Attribute::TARGET_PROPERTY)] class NotBlank extends Assertion { public function __construct( public string $message = 'Property is blank.', ) {} public function isValid(mixed $value): bool { return is_string($value) && strlen(trim($value)) > 0; } }
41. Validating Objects public function validateObject(object $object): Violations { $violations = []; $properties = (new ReflectionObject($object))->getProperties(); foreach ($properties as $property) { $attributes = $property->getAttributes( Assertion::class, ReflectionAttribute::IS_INSTANCEOF ); $violations = $violations + $this->validateProperty($attributes, $object, $property); } return new Violations($violations); }
42. Validating Objects private function validateProperty($attributes, $object, $property) { $violations = []; foreach ($attributes as $attribute) { $assertion = $attribute->newInstance(); if (!$assertion->isValid($property->getValue($object))) { $violations[$property->getName()][] = $assertion->message; } } return $violations; }
43. Use-Case: Routing again
44. Routing How to get all methods that have a route? https://github.com/olvlvl/composer-attribute-collector
45. Routing use olvlvl\ComposerAttributeCollector\Attributes; class Router { public function collectRoutePaths(): void { foreach (Attributes::findTargetMethods(Route::class) as $target) { $this->collectRoutePath( $target->attribute, new ReflectionMethod($target->class, $target->method) ); } } }
46. Use-Case: Object-Relational Mapping (ORM)
47. Doctrine ORM use Doctrine\ORM\Mapping as ORM; #[ORM\Entity] #[ORM\Table(name: 'products')] class Product { #[ORM\Id] #[ORM\Column(type: 'integer')] #[ORM\GeneratedValue] private int|null $id = null; #[ORM\Column(type: 'string')] private string $name; // .. (other code) }
48. THANK YOU! E-Mail: Benjamin@Tideways.com Linkedin: https://www.linkedin.com/in/benjamin-eberlei-4b5628116/ Mastodon: @beberlei@phpc.social