Merge pull request #3 from Dgame/v0.4.0

Started v0.4.0

Author: Dgame

Diff for: .github/workflows/php.yml

@@ -1,68 +1,68 @@
-name: Validation Workflow
-
-on:
-  pull_request:
-    types:
-      - opened
-      - synchronize
-      - reopened
-      - ready_for_review
-    paths:
-      - '**/*.php'
-
-jobs:
-  lint-and-test:
-    strategy:
-      matrix:
-        operating-system: ['ubuntu-latest']
-        php-versions: ['8.0']
-    runs-on: ${{ matrix.operating-system }}
-    if: github.event.pull_request.draft == false
-    steps:
-      - name: Cancel Previous Runs
-        uses: styfle/[email protected]
-        with:
-          ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Checkout
-        uses: actions/checkout@v2
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: ${{ matrix.php-versions }}
-          tools: composer:v2
-          coverage: none
-        env:
-          COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Display PHP information
-        run: |
-          php -v
-          php -m
-          composer --version
-      - name: Get composer cache directory
-        id: composer-cache
-        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
-
-      - name: Cache dependencies
-        uses: actions/cache@v2
-        with:
-          path: ${{ steps.composer-cache.outputs.dir }}
-          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
-          restore-keys: ${{ runner.os }}-composer-
-
-      - name: Run composer validate
-        run: composer validate
-
-      - name: Install dependencies
-        run: composer install --no-interaction --no-suggest --no-scripts --prefer-dist --ansi
-
-      - name: Run phpcstd
-        run: vendor/bin/phpcstd --ci --ansi
-
-      - name: Setup problem matchers for PHPUnit
-        run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
-
-      - name: Run Unit tests
-        run: composer test --ansi
+name: Validation Workflow
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
+    paths:
+      - '**/*.php'
+
+jobs:
+  lint-and-test:
+    strategy:
+      matrix:
+        operating-system: ['ubuntu-latest']
+        php-versions: ['8.0']
+    runs-on: ${{ matrix.operating-system }}
+    if: github.event.pull_request.draft == false
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/[email protected]
+        with:
+          ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-versions }}
+          tools: composer:v2
+          coverage: none
+        env:
+          COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Display PHP information
+        run: |
+          php -v
+          php -m
+          composer --version
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+          restore-keys: ${{ runner.os }}-composer-
+
+      - name: Run composer validate
+        run: composer validate
+
+      - name: Install dependencies
+        run: composer install --no-interaction --no-suggest --no-scripts --prefer-dist --ansi
+
+      - name: Run phpcstd
+        run: vendor/bin/phpcstd --ci --ansi
+
+      - name: Setup problem matchers for PHPUnit
+        run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
+
+      - name: Run Unit tests
+        run: composer test --ansi

Diff for: CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v0.4.0 - 10.09.2021
+
+### Added
+
+- [Boolean](/README.md/#Boolean)
+- [Date](/README.md/#Date)
+- [In](/README.md/#In)
+- [Matches](/README.md/#Matches)
+- [NotIn](/README.md/#NotIn)
+- [Numeric](/README.md/#Numeric)
+- [Trim](/README.md/#Trim)
+
+### Changed
+
+ - `finalize`of `DataTransferObject` is now private an will be called at the end of `from`.
+
 ## v0.3.0 - 15.08.2021
 
 ### Added

Diff for: README.md

@@ -497,6 +497,144 @@ $foo = Foo::from([]);
 assert($foo->id === 23);
 ```
 
+## Numeric
+
+You have `int` or `float` properties but aren't sure if those aren't delivered as e.g. `string`? `Numeric` to the rescue! It will translate the value to a numeric representation (to `int` or `float`):
+
+```php
+use Dgame\DataTransferObject\Annotation\Numeric;
+
+final class Foo
+{
+    use DataTransfer;
+    
+    #[Numeric(message: 'id must be numeric')]
+    public int $id;
+}
+
+$foo = Foo::from(['id' => '23']);
+assert($foo->id === 23);
+```
+
+## Boolean
+
+You have `bool` properties but aren't sure if those aren't delivered as `string` or `int`? `Boolean` can help you with that!
+
+```php
+use Dgame\DataTransferObject\Annotation\Boolean;
+
+final class Foo
+{
+    use DataTransfer;
+    
+    #[Boolean(message: 'checked must be a bool')]
+    public bool $checked;
+    #[Boolean(message: 'verified must be a bool')]
+    public bool $verified;
+}
+
+$foo = Foo::from(['checked' => 'yes', 'verified' => 0]);
+assert($foo->checked === true);
+assert($foo->verified === false);
+```
+
+## Date
+
+You want a `DateTime` but got a string? No problem:
+
+```php
+use Dgame\DataTransferObject\Annotation\Date;
+
+final class Foo
+{
+    use DataTransfer;
+    
+    #[Date(format: 'd.m.Y', message: 'Your birthday must be a date')]
+    public bool $birthday;
+}
+
+$foo = Foo::from(['birthday' => '19.09.1979']);
+assert($foo->birthday === DateTime::createFromFormat('d.m.Y', '19.09.1979'));
+```
+
+
+## In
+
+Your value must be one of a specific range or enumeration? You can ensure that with `In`:
+
+```php
+use Dgame\DataTransferObject\Annotation\In;
+
+final class Foo
+{
+    use DataTransfer;
+    
+    #[In(values: ['beginner', 'advanced', 'difficult'], message: 'Must be either "beginner", "advanced" or "difficult"')]
+    public string $difficulty;
+}
+
+Foo::from(['difficulty' => 'foo']); // will throw a error, since difficulty is not in the provided values
+$foo = Foo::from(['difficulty' => 'advanced']);
+assert($foo->difficulty === 'advanced');
+```
+
+## NotIn
+
+Your value must **not** be one of a specific range or enumeration? You can ensure that with `NotIn`:
+
+```php
+use Dgame\DataTransferObject\Annotation\NotIn;
+
+final class Foo
+{
+    use DataTransfer;
+    
+    #[NotIn(values: ['holy', 'shit', 'wtf'], message: 'Must not be a swear word')]
+    public string $word;
+}
+```
+
+## Matches
+
+You must be sure that your values match a specific pattern? You can do that for **all scalar** values by using `Matches`:
+
+```php
+use Dgame\DataTransferObject\Annotation\Matches;
+
+final class Foo
+{
+    use DataTransfer;
+    
+    #[Matches(pattern: '/^[a-z]+\w*/', message: 'Your name must start with a-z')]
+    public string $name;
+    
+    #[Matches(pattern: '/[1-9][0-9]+/', message: 'products must be at least 10')]
+    public int $products;
+}
+
+Foo::from(['name' => '_', 'products' => 99]); // will throw a error, since name does not start with a-z
+Foo::from(['name' => 'John', 'products' => 9]); // will throw a error, since products must be at least 10
+```
+
+## Trim
+
+You have to make sure, that `string` values are trimmed? No worries, we have `Trim`:
+
+```php
+use Dgame\DataTransferObject\Annotation\Trim;
+
+final class Foo
+{
+    use DataTransfer;
+    
+    #[Trim]
+    public string $name;
+}
+
+$foo = Foo::from(['name' => ' John   ']);
+assert($foo->name === 'John');
+```
+
 ## Path
 
 Did you ever wanted to extract a value from a provided array? `Path` to the rescue:

Diff for: composer.json

@@ -16,6 +16,7 @@
     ],
     "require": {
         "php": "^8.0",
+        "dgame/php-cast": "^0.1.0",
         "dgame/php-type": "^1.0",
         "thecodingmachine/safe": "^1.3"
     },

Diff for: phpstan.neon

@@ -14,6 +14,7 @@ parameters:
     checkTooWideReturnTypesInProtectedAndPublicMethods: true
     checkUninitializedProperties: true
     checkMissingCallableSignature: true
+    checkExplicitMixed: true
     level: max
     paths:
         - src

Diff for: src/Annotation/Boolean.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dgame\DataTransferObject\Annotation;
+
+use Attribute;
+use function Dgame\Cast\Assume\bool;
+use ReflectionProperty;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class Boolean implements Validation, Transformation
+{
+    public function __construct(private ?string $message = null)
+    {
+    }
+
+    public function validate(mixed $value, ValidationStrategy $validationStrategy): void
+    {
+        if (bool($value) === null) {
+            $validationStrategy->setFailure(
+                strtr(
+                    $this->message ?? 'Value {value} of {path} is not a bool',
+                    ['{value}' => var_export($value, true)]
+                )
+            );
+        }
+    }
+
+    public function transform(mixed $value, ReflectionProperty $property): mixed
+    {
+        return bool($value) ?? $value;
+    }
+}

Diff for: src/Annotation/Date.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dgame\DataTransferObject\Annotation;
+
+use Attribute;
+use DateTime;
+use DateTimeZone;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class Date implements Validation
+{
+    public function __construct(private ?string $format = null, private ?int $timezone = null, private ?string $message = null)
+    {
+    }
+
+    public function validate(mixed $value, ValidationStrategy $validationStrategy): void
+    {
+        $dt = null;
+        if ($this->format !== null) {
+            /** @phpstan-ignore-next-line => short ternary */
+            $dt = DateTime::createFromFormat($this->format, $value) ?: null;
+        } else {
+            /** @phpstan-ignore-next-line => short ternary */
+            $info = date_parse($value) ?: [];
+            if (($info['error_count'] ?? 0) === 0 && ($info['warning_count'] ?? 0) === 0) {
+                /** @phpstan-ignore-next-line */
+                $dt = new DateTime($value, $this->timezone === null ? null : new DateTimeZone($this->timezone));
+            }
+        }
+
+        if ($dt === null) {
+            $validationStrategy->setFailure(
+                strtr(
+                    $this->message ?? '{value} of {path} is not a Date',
+                    ['{value}' => var_export($value, true)]
+                )
+            );
+        }
+    }
+}