Merge pull request #29 from php-school/attributes

Attributes

Author: AydinHassan

app/bootstrap.php

@@ -27,6 +27,7 @@
 use PhpSchool\PHP8Appreciate\Exercise\InfiniteDivisions;
 use PhpSchool\PHP8Appreciate\Exercise\PhpPromotion;
 use PhpSchool\PHP8Appreciate\Exercise\LordOfTheStrings;
+use PhpSchool\PHP8Appreciate\Exercise\TheAttributesOfSuccess;
 use PhpSchool\PHP8Appreciate\Exercise\TheReturnOfStatic;
 use PhpSchool\PHP8Appreciate\Exercise\ThrowAnExpression;
 use PhpSchool\PHP8Appreciate\Exercise\UniteTheTypes;
@@ -47,6 +48,7 @@
 $app->addExercise(TheReturnOfStatic::class);
 $app->addExercise(ThrowAnExpression::class);
 $app->addExercise(StringifyToDemystify::class);
+$app->addExercise(TheAttributesOfSuccess::class);
 
 $art = <<<ART
         _ __ _

app/config.php

@@ -8,6 +8,7 @@
 use PhpSchool\PHP8Appreciate\Exercise\InfiniteDivisions;
 use PhpSchool\PHP8Appreciate\Exercise\PhpPromotion;
 use PhpSchool\PHP8Appreciate\Exercise\LordOfTheStrings;
+use PhpSchool\PHP8Appreciate\Exercise\TheAttributesOfSuccess;
 use PhpSchool\PHP8Appreciate\Exercise\TheReturnOfStatic;
 use PhpSchool\PHP8Appreciate\Exercise\ThrowAnExpression;
 use PhpSchool\PHP8Appreciate\Exercise\UniteTheTypes;
@@ -57,4 +58,7 @@
     StringifyToDemystify::class => function (ContainerInterface $c) {
         return new StringifyToDemystify($c->get(PhpParser\Parser::class));
     },
+    TheAttributesOfSuccess::class => function (ContainerInterface $c) {
+        return new TheAttributesOfSuccess($c->get(PhpParser\Parser::class), $c->get(\Faker\Generator::class));
+    }
 ];

exercises/the-attributes-of-success/initial/attributes.php

@@ -0,0 +1,18 @@
+<?php
+
+#[Attribute(Attribute::TARGET_CLASS)]
+class Deserialize {
+
+}
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class Map {
+    public function __construct(public string $mapFrom)
+    {
+    }
+}
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class Skip {
+
+}

exercises/the-attributes-of-success/initial/deserialize.php

@@ -0,0 +1,58 @@
+<?php
+
+function camelCaseToSnakeCase(string $string): string
+{
+    return strtolower(preg_replace(['/([a-z\d])([A-Z])/', '/([^_])([A-Z][a-z])/'], '$1_$2', $string));
+}
+
+function deserialize(string $data, string $className): object
+{
+    $reflectionClass = new \ReflectionClass($className);
+    $attrs = $reflectionClass->getAttributes(Deserialize::class);
+
+    if (empty($attrs)) {
+        throw new \RuntimeException('Class cannot be deserialized');
+    }
+
+    $attrs[0]->newInstance();
+
+    $object = new $className();
+
+    $data = json_decode($data, true);
+
+    $obfuscators = array_filter(
+        $reflectionClass->getMethods(),
+        fn (ReflectionMethod $m) => count($m->getAttributes(Obfuscate::class)) > 0
+    );
+
+    $obfuscators = array_combine(
+        array_map(
+            fn(ReflectionMethod $m) => $m->getAttributes(Obfuscate::class)[0]->newInstance()->key,
+            $obfuscators
+        ),
+        $obfuscators
+    );
+
+    foreach ($data as $key => $value) {
+        if (isset($obfuscators[$key])) {
+            $data[$key] = $object->{$obfuscators[$key]->getName()}($value);
+        }
+    }
+
+    foreach ($reflectionClass->getProperties() as $property) {
+        if ($map = $property->getAttributes(Map::class)) {
+            $key = $map[0]->newInstance()->mapFrom;
+
+            if (isset($data[$key])) {
+                $object->{$property->getName()} = $data[$key];
+            }
+
+        } elseif ($skip = $property->getAttributes(Skip::class)) {
+            continue;
+        } elseif (isset($data[camelCaseToSnakeCase($property->getName())])) {
+            $object->{$property->getName()} = $data[camelCaseToSnakeCase($property->getName())];
+        }
+    }
+
+    return $object;
+}

exercises/the-attributes-of-success/initial/the-attributes-of-success.php

@@ -0,0 +1,4 @@
+<?php
+
+require_once __DIR__ . '/deserialize.php';
+require_once __DIR__ . '/attributes.php';

exercises/the-attributes-of-success/problem/problem.md

@@ -0,0 +1,143 @@
+You have been given a few pieces of code (look for `attributes.php`, `deserialize.php` & `the-attributes-of-success.php` in your working directory).
+
+Your entry point is `the-attributes-of-success.php`. This is the file you should edit and work on. The other files should not be modified. However, they are included by `the-attributes-of-success.php`.
+
+You can run and verify your program like so:
+
+```sh
+$ {appname} run the-attributes-of-success.php
+$ {appname} verify the-attributes-of-success.php
+```
+
+Your task is split into two sections. The overall task is to write a class using properties and attributes which describe how to map data to an instance of the class.
+
+The data will be passed to you in a JSON encoded string via the first command line argument. 
+
+The data will represent a product review.
+
+You pass the `JSON` data and the name of your class to a function named `deserialize` which is provided to you in the file  `deserialize.php`. For reference, its signature is:
+
+```php
+function deserialize(string $data, string $className): object;
+```
+
+It will return to you an instance of `$className` with the data from the `JSON` string `$data` mapped to its properties.
+
+You should dump out the object using `var_dump`.
+
+### Task 1 - Annotate a class with existing attributes
+
+Create a class named `Review` with five public properties which represent the data of the review. The properties should all be `string` types and should be named `comment`, `starRating`, `date`, `id` and `reviewer`.
+
+The class should use the Attribute `Deserialize` so that our `deserialize` function knows that this is a valid class to use.
+
+By default, our `deserialize` function will use the names of the class properties to locate the field value in the `JSON` data.
+
+For example, when passing the following class to our `deserialise` function it would look for the `sku` key in the `JSON` data and set it on the `sku` property.
+
+```php
+#[Deserialize]
+class Product {
+    public string $sku;
+}
+```
+
+#### Mapping properties
+
+However, the `starRating` key does not exist in the `JSON` data. It exists as `rating`. So here, we need to use the `Map` attribute. By using the `Map` attribute we can tell our `deserialize` function to fetch the star rating from a different key in the `JSON` data.
+
+Use it like so:
+
+```php
+#[Deserialize]
+class Product {
+    #[Map('reference')]
+    public string $sku;
+}
+```
+
+Where `reference` is the key in the `JSON` data you want to use rather than `sku`.
+
+#### Skipping properties
+
+We don't care about the ID value, this relates to a 3rd party system and is not relevant in our code.
+
+Use the `Skip` attribute on the `id` property of our `Review` class to tell our `deserialize` function to skip this piece of data.
+
+### Task 2 - Create your own attribute
+
+By now you should be able to call the `deserialize` function with the `JSON` data and your class name.
+
+When executing your program with
+
+```sh
+$ {appname} run the-attributes-of-success.php
+```
+
+You should see a dump of your `Review` instance.
+
+Here comes our problem: The reviewers name is not anonymous. We have to comply with strict privacy laws, we cannot display this data without the reviewer's permission.
+
+For now, we will have to obfuscate this data. We can accomplish this using a custom attribute.
+
+#### Create the obfuscate method
+
+Create a method on your `Review` class named `obfuscateReviewer`. It should take a string input, run it through the `md5` function and return it.
+
+#### Create an attribute
+
+Create an attribute named `Obfuscate`. It should have a public property named `key` and it's constructor should assign the first passed in string value to this property.
+
+The attribute must be designated as an attribute by using the `Attribute` attribute (confused much??) and it should target methods only.
+
+Targets designate where an attribute can be used, on classes, methods or properties and so on. For reference, the `Deserialize` attribute can only be used on classes and hence its target is `Attribute::TARGET_CLASS`.
+
+See below for an example of designating a class as an attribute and configuring its target as classes only.
+
+```php
+#[Attribute(Attribute::TARGET_CLASS)] //This is how we designate `MyAttribute` as an attribute with its target.
+class MyAttribute {
+    public function __construct(string $someValue) {
+    }
+}
+```
+
+#### Use the attribute
+
+The last step is to use the attribute on your `obfuscateReviewer` method. We need to tell our `deserialize` function that this method should be called when accessing the `reviewer` key from the `JSON` data.
+
+Use the `Obfuscate` attribute on the method and pass to it the name of the key in the `JSON` data we want the obfuscator to run over, which is the `reviewer` key.
+
+When the `deserialize` function sees a method with the `Obfuscate` attribute it will use the key found in the public property named `key` of the attribute. It will find the value referenced by that key in the `JSON` data and pass it to the obfuscator method. 
+
+Finally, the returned data will be set on the `Review` object instance.
+
+### Dump your object
+
+The last task is to dump your object instance out using the PHP function `var_dump` - we use this output to verify the structure and data in your `Review` instance.    
+
+### The advantages of Attributes
+
+* Add Metadata to classes, methods, properties and arguments and so on
+* They can replace PHP doc blocks, each with custom parsers and rules to a unified standard supported by PHP
+* The data can be introspected using PHP's Reflection API's
+* PHP Core and extensions can provide new behaviour and runtime configuration which is opt-in, such as conditionally declaring functions, deprecating features and so on
+
+----------------------------------------------------------------------
+## HINTS
+
+Documentation on the Attributes feature can be found by pointing your browser here:
+[https://www.php.net/manual/en/language.attributes.overview.php]()
+
+Remember, do not edit `attributes.php` or `deserialize.php` - verification will fail if you do. Feel free to read the files to get a better understanding of the deserialization process.
+
+You must call the `deserialize` function and you must use the `var_dump` function to output your deserialized object.
+
+If you want to see the `JSON` data - use `var_dump` to dump it out.
+
+
+## Extra
+
+If you're not sure how to access command line arguments - you should maybe try a different workshop which covers that topic. Try `learnyouphp`.
+
+`json_decode` can fail if it is passed a malformed string. Wrap the decode in a `try\catch` statement and pass the `JSON_THROW_ON_ERROR` flag to `json_decode`'s fourth parameter.

exercises/the-attributes-of-success/solution/attributes.php

@@ -0,0 +1,18 @@
+<?php
+
+#[Attribute(Attribute::TARGET_CLASS)]
+class Deserialize {
+
+}
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class Map {
+    public function __construct(public string $mapFrom)
+    {
+    }
+}
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class Skip {
+
+}

exercises/the-attributes-of-success/solution/deserialize.php

@@ -0,0 +1,58 @@
+<?php
+
+function camelCaseToSnakeCase(string $string): string
+{
+    return strtolower(preg_replace(['/([a-z\d])([A-Z])/', '/([^_])([A-Z][a-z])/'], '$1_$2', $string));
+}
+
+function deserialize(string $data, string $className): object
+{
+    $reflectionClass = new \ReflectionClass($className);
+    $attrs = $reflectionClass->getAttributes(Deserialize::class);
+
+    if (empty($attrs)) {
+        throw new \RuntimeException('Class cannot be deserialized');
+    }
+
+    $attrs[0]->newInstance();
+
+    $object = new $className();
+
+    $data = json_decode($data, true);
+
+    $obfuscators = array_filter(
+        $reflectionClass->getMethods(),
+        fn (ReflectionMethod $m) => count($m->getAttributes(Obfuscate::class)) > 0
+    );
+
+    $obfuscators = array_combine(
+        array_map(
+            fn(ReflectionMethod $m) => $m->getAttributes(Obfuscate::class)[0]->newInstance()->key,
+            $obfuscators
+        ),
+        $obfuscators
+    );
+
+    foreach ($data as $key => $value) {
+        if (isset($obfuscators[$key])) {
+            $data[$key] = $object->{$obfuscators[$key]->getName()}($value);
+        }
+    }
+
+    foreach ($reflectionClass->getProperties() as $property) {
+        if ($map = $property->getAttributes(Map::class)) {
+            $key = $map[0]->newInstance()->mapFrom;
+
+            if (isset($data[$key])) {
+                $object->{$property->getName()} = $data[$key];
+            }
+
+        } elseif ($skip = $property->getAttributes(Skip::class)) {
+            continue;
+        } elseif (isset($data[camelCaseToSnakeCase($property->getName())])) {
+            $object->{$property->getName()} = $data[camelCaseToSnakeCase($property->getName())];
+        }
+    }
+
+    return $object;
+}

exercises/the-attributes-of-success/solution/solution.php

@@ -0,0 +1,37 @@
+<?php
+
+require_once __DIR__ . '/deserialize.php';
+require_once __DIR__ . '/attributes.php';
+
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Obfuscate {
+    public function __construct(public string $key)
+    {
+    }
+}
+
+#[Deserialize]
+class Review {
+    public string $comment;
+
+    #[Map('rating')]
+    public string $starRating;
+
+    public string $date;
+
+    #[Skip()]
+    public string $id;
+
+    public ?string $reviewer = null;
+
+    #[Obfuscate('reviewer')]
+    public function obfuscateReviewer(string $reviewer): string
+    {
+        return md5($reviewer);
+    }
+}
+
+$object = deserialize($argv[1], Review::class);
+
+var_dump($object);

phpstan.neon

@@ -4,6 +4,7 @@ parameters:
         - '#Cannot access property \$args on PhpParser\\Node\|null#'
         - '#Call to an undefined method PhpParser\\Node\\Expr\|PhpParser\\Node\\Name\:\:toString\(\)#'
         - '#Parameter \#1 \$array of function array_flip expects array<int\|string>, array<int, int\|string>\|int\|string given.#'
+        - '#Call to an undefined method Faker\\Generator\:\:userName\(\).#'
 
     excludes_analyse:
         - src/TestUtils/WorkshopExerciseTest.php