refactor: drop annotation support and prepare for Symfony 6 (#7)

Author: chris-doehring

.github/workflows/phpunit-symfony6.yml

@@ -0,0 +1,37 @@
+name: phpunit-symfony6
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: true
+      matrix:
+        os:
+          - ubuntu-latest
+        php:
+          - 8.0
+
+    name: php${{ matrix.php }} - symfony 6
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: xdebug
+
+      - name: Setup Problem Matches
+        run: |
+          echo "::add-matcher::${{ runner.tool_cache }}/php.json"
+          echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
+
+      - name: Install dependencies
+        run: composer require symfony/validator:6.0.x-dev && composer update
+
+      - name: Execute tests
+        run: vendor/bin/phpunit -v

.github/workflows/phpunit.yml

@@ -11,11 +11,10 @@ jobs:
         os:
           - ubuntu-latest
         php:
-          - 7.4
           - 8.0
         dependency-version: [prefer-lowest, prefer-stable]
 
-    name: P${{ matrix.php }} - ${{ matrix.dependency-version }}
+    name: php${{ matrix.php }} - ${{ matrix.dependency-version }}
 
     steps:
       - name: Checkout code

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v2.0.0 - 2021-07-XX
+
+- drop php 7.4 support
+- drop primary `doctrine/annotations` support for model validation
+- require `dogado/json-api-common:^2.0`
+- prepare support for `symfony/validator:^6.0`
+
+See [UPGRADE-2.0.md](UPGRADE-2.0.md) for more details.
+
 ## v1.0.0 - 2021-05-21
 
 - initial release

UPGRADE-2.0.md

@@ -0,0 +1,138 @@
+# UPGRADE to v2.0.0
+
+## Migrating JSON API model definitions from Doctrine annotations to php 8 attributes
+
+In `v2.0.0` the support for JSON API model definitions via Doctrine annotations has been removed and moved to native
+php 8 attributes. The annotation classes have been moved from the namespace `Dogado\JsonApi\Annotations` to
+`Dogado\JsonApi\Attribute`. The attributes are basically the same. The only change is that the `value` property
+in the `Type` and `Attribute` classes has been renamed to `name`.
+
+Your models have to be changed like this:
+```php
+// OLD
+use Dogado\JsonApi\Annotations\Attribute;
+use Dogado\JsonApi\Annotations\Id;
+use Dogado\JsonApi\Annotations\Type;
+
+/**
+ * @Type("dummy-model")
+ */
+class Model
+{
+    /**
+     * @Id()
+     */
+    private ?int $id = 123456;
+
+    /**
+     * @Attribute(value="name-alias", ignoreOnNull=true)
+     */
+    private ?string $name = 'loremIpsum';
+}
+```
+```php
+// NEW
+use Dogado\JsonApi\Attribute\Attribute;
+use Dogado\JsonApi\Attribute\Id;
+use Dogado\JsonApi\Attribute\Type;
+
+#[Type('dummy-model')]
+class Model
+{
+    #[Id]
+    private ?int $id = 123456;
+
+    #[Attribute(name: 'name-alias', ignoreOnNull: true)]
+    private ?string $name = 'loremIpsum';
+}
+```
+
+## Migrate to attribute constraint based Symfony model validation
+
+Symfony added php 8 attribute constraint based validation in
+[`symfony/validator:v5.2.0`](https://symfony.com/blog/new-in-symfony-5-2-constraints-as-php-attributes). It works just
+like with Doctrine annotations, with one exception: The following validation constraints are not totally compatible to
+php 8 attributes:
+
+* All
+* AtLeastOneOf
+* Collection
+* Compound (abstract)
+* Existence (abstract)
+** Required
+** Optional
+* Sequentially
+
+[They are missing nested attributes](https://github.com/symfony/symfony/issues/38503) which is a feature that will
+probably be added in php 8.1.
+
+Although this package suggests using php 8 attribute constraints with release `v2.0.0`, feel free to continue to
+use doctrine based annotations for validation. Symfony will continue to support them in Symfony 6.
+
+Either way, you should pay attention to the way how you initialize the Symfony Validator.
+
+### Validator initialization for php 8 attributes
+
+```php
+use Symfony\Component\Validator\ValidatorBuilder;
+
+$validatorBuilder = new ValidatorBuilder();
+
+// Symfony ^5.2
+$validator = $validatorBuilder->enableAnnotationMapping(true)->getValidator();
+
+// Symfony ^6.0
+$validator = $validatorBuilder->enableAnnotationMapping()->getValidator();
+```
+
+php 8 validation constraints in combination with the new json api attribute definitions are a real benefit. Not only
+is it faster, since php 8 attributes are a native php implementation, but you also do no longer need extra Doctrine
+packages that analyze phpdocs. Here is an example how good both go together:
+
+```php
+use Dogado\JsonApi\Attribute\Attribute;
+use Dogado\JsonApi\Attribute\Id;
+use Dogado\JsonApi\Attribute\Type;
+use Symfony\Component\Validator\Constraints as Assert;
+
+#[Type('user')]
+class User
+{
+    #[
+        Id,
+        Assert\Positive
+    ]
+    private ?int $id = 123456;
+
+    #[
+        Attribute,
+        Assert\NotBlank,
+        Assert\Length(min: 3, max: 32)
+    ]
+    private ?string $name = 'John Doe';
+
+    #[
+        Attribute,
+        Assert\NotBlank,
+        Assert\Email
+    ]
+    private ?string $email = null;
+}
+```
+
+### Validator initialization for Doctrine annotations
+
+The following change is not really necessary for `symfony/validator:^5.0`, but that change is the syntax that will still
+be working in `symfony/validator:^6.0` and is already supported in `^5.2`.
+
+```php
+use Symfony\Component\Validator\ValidatorBuilder;
+
+$validatorBuilder = new ValidatorBuilder();
+
+// OLD
+$validator = $validatorBuilder->enableAnnotationMapping()->getValidator();
+
+// NEW
+$validator = $validatorBuilder->enableAnnotationMapping()->addDefaultDoctrineAnnotationReader()->getValidator();
+```

composer.json

@@ -9,19 +9,17 @@
   "license": "MIT",
   "homepage": "https://github.com/dogado-group/json-api-server",
   "require": {
-    "php": "^7.4 || ^8.0",
+    "php": "^8.0",
     "ext-json": "*",
-    "dogado/json-api-common": "^1.0",
-    "symfony/validator": "^5.1",
-    "doctrine/annotations": "^1.11",
-    "doctrine/cache": "^1.10"
+    "dogado/json-api-common": "^2.0",
+    "symfony/validator": "^5.2"
   },
   "require-dev": {
     "phpunit/phpunit": "^9.5",
     "fakerphp/faker": "^1.15",
-    "phpstan/phpstan": "^0.12.49",
+    "phpstan/phpstan": "^0.12.92",
     "guzzlehttp/psr7": "^1.7",
-    "squizlabs/php_codesniffer": "^3.5"
+    "squizlabs/php_codesniffer": "^3.6"
   },
   "autoload": {
     "psr-4": {

docs/05-validator-for-data-models.md

@@ -3,33 +3,31 @@
 # Validator for data models
 
 The `dogado/json-api-common` package allows the conversion from resource instances to data models. It's usually the case, that we need some sort of validation on the JSON API data that is coming in.
-The `Dogado\JsonApi\Server\Validator\Validator` class offers the possibility to validate any model in it the current state, based on `symfony/validator`.
+The `Dogado\JsonApi\Server\Validator\ModelValidator` class offers the possibility to validate any model in it the current state, based on `symfony/validator`.
 
-Usually, you can use any validation you like. Although this validator will throw a custom JSON API compatible `\Dogado\JsonApi\Exception\JsonApi\ValidationException` containing error objects representing the Symfony Validator violations.
+Usually, you can use any validation you like. Although this validator will throw a custom JSON API compatible `Dogado\JsonApi\Exception\JsonApi\ValidationException` containing error objects representing the Symfony Validator violations.
 
 ## Code example
 
 ### Model class definition
 ```php
-use Dogado\JsonApi\Annotations\Attribute;
-use Dogado\JsonApi\Annotations\Type;
+use Dogado\JsonApi\Attribute\Attribute;
+use Dogado\JsonApi\Attribute\Type;
 use Symfony\Component\Validator\Constraints as Assert;
 
-/**
- * @Type("validation-test")
- */
+#[Type('validation-test')]
 class Model
 {
-    /**
-     * @Attribute()
-     * @Assert\Email()
-     */
+    #[
+        Attribute,
+        Assert\Email
+    ]
     private string $email = 'noValidEmail';
 
-    /**
-     * @Attribute("jsonApiValueObject")
-     * @Assert\Valid()
-     */
+    #[
+        Attribute('jsonApiValueObject'),
+        Assert\Valid
+    ]
     private ValueObjectModel $valueObject;
 
     public function __construct()
@@ -39,7 +37,7 @@ class Model
 }
 ```
 
-It is also possible to validate value objects. To do that, you need to add the `@Assert\Valid()` annotation to the object property. Within the value object, you can continue to use the regular assertions.
+It is also possible to validate value objects. To do that, you need to add the `Assert\Valid` attribute to the object property. Within the value object, you can continue to use the regular assertions.
 
 ### Execute validation
 
@@ -51,7 +49,7 @@ use Symfony\Component\Validator\ValidatorBuilder;
 
 $model = new Model();
 $validatorBuilder = new ValidatorBuilder();
-$validator = $validatorBuilder->enableAnnotationMapping()->getValidator();
+$validator = $validatorBuilder->enableAnnotationMapping(true)->getValidator();
 
 $jsonApiValidator = new ModelValidator($validator);
 /** @throws JsonApiException */
@@ -60,6 +58,23 @@ $jsonApiValidator->validate($model);
 
 In the above example we are using the annotation mapping that Symfony Validator offers by default. Feel free to use a different way of defining your validation rules. More details and validation examples can be found in the [Symfony documentation](https://symfony.com/doc/current/validation.html).
 
+## php 8 validation limitations and Doctrine annotation support
+
+Symfony added the php 8 attribute support for the assertion constraints in
+[`symfony/validator:5.2.0`](https://symfony.com/blog/new-in-symfony-5-2-constraints-as-php-attributes), but the
+alternative Doctrine annotation support is still given, even in Symfony 6. You can activate it like this:
+
+```php
+$validatorBuilder = new ValidatorBuilder();
+$validator = $validatorBuilder->enableAnnotationMapping(true)->addDefaultDoctrineAnnotationReader()->getValidator();
+```
+
+The benefit of using the php 8 attributes instead is that you don't have to require doctrine packages as dependencies.
+Attributes are a php 8 natively implemented feature and therefore faster to use. However, there
+are a few Symfony Constraints
+[that are not compatible to attributes yet](https://github.com/symfony/symfony/issues/38503), but that will probably
+change with php 8.1.
+
 ## Custom violation converter
 
 The Symfony validator creates violations for each failing assertion rule. The JSON API server validator will send all violations against a `Dogado\JsonApi\Server\Validator\ViolationConverterInterface`. There already is a default `ViolationConverter` which will be used, but feel free to create a custom one and pass that one as parameter to the Validator instantiation.

src/JsonApiServer.php

@@ -51,7 +51,6 @@ public function addHandler(string $type, RequestHandlerInterface $handler): self
     }
 
     /**
-     * @return RequestHandlerInterface
      * @throws UnsupportedTypeException
      */
     private function getHandler(string $type): RequestHandlerInterface

src/Validator/ModelValidator.php

@@ -16,26 +16,28 @@
 
 class ModelValidator
 {
-    protected ValidatorInterface $validator;
     protected ViolationConverterInterface $violationConverter;
 
     public function __construct(
-        ValidatorInterface $validator,
+        protected ValidatorInterface $validator,
         ViolationConverterInterface $violationConverter = null
     ) {
-        $this->validator = $validator;
         $this->violationConverter = $violationConverter ?? new ViolationConverter();
     }
 
     /**
      * @param Constraint|Constraint[]|null $constraints The constraint(s) to validate against
-     * @param string|GroupSequence|(string|GroupSequence)[]|null $groups
+     * @param string|GroupSequence|string[]|GroupSequence[]|null $groups
      * @param string|null $documentPath The path to the resource within the JSON API document
      * @throws ValidationException
      * @throws ReflectionException
      */
-    public function validate(object $model, $constraints = null, $groups = null, string $documentPath = null): void
-    {
+    public function validate(
+        object $model,
+        mixed $constraints = null,
+        mixed $groups = null,
+        string $documentPath = null
+    ): void {
         $documentPath ??= '/data';
         /** @var ConstraintViolationListInterface|ConstraintViolationInterface[] $violationList */
         $violationList = $this->validator->validate($model, $constraints, $groups);

tests/Stubs/Validator/Model.php

@@ -3,19 +3,17 @@
 
 namespace Dogado\JsonApi\Server\Tests\Stubs\Validator;
 
-use Dogado\JsonApi\Annotations\Attribute;
-use Dogado\JsonApi\Annotations\Type;
+use Dogado\JsonApi\Attribute\Attribute;
+use Dogado\JsonApi\Attribute\Type;
 use Symfony\Component\Validator\Constraints as Assert;
 
-/**
- * @Type("validation-test")
- */
+#[Type('validation-test')]
 class Model
 {
-    /**
-     * @Attribute("jsonApiValueObject")
-     * @Assert\Valid()
-     */
+    #[
+        Attribute('jsonApiValueObject'),
+        Assert\Valid
+    ]
     private ValueObjectModel $valueObject;
 
     public function __construct()