chore: cleanup Areas annotation (#2431)

## Description

Cleans up the `Area` annotation/attribute to trigger a deprecation
warning whenever a list of strings isn't passed.

## What type of PR is this? (check all applicable)
- [ ] Bug Fix
- [ ] Feature
- [ ] Refactor
- [x] Deprecation
- [ ] Breaking Change
- [ ] Documentation Update
- [ ] CI

## Checklist
- [ ] I have made corresponding changes to the documentation (`docs/`)
- [x] I have made corresponding changes to the changelog
(`CHANGELOG.md`)

CHANGELOG.md

@@ -1,5 +1,15 @@
 # CHANGELOG
 
+## 4.36.1
+- Passing an array key `value` with a list of strings to the `Areas` annotation/attribute is deprecated. Pass the list of strings directly.
+```diff
+-#[Areas(properties: ['value' => ['foo', 'bar']])]
++#[Areas(properties: ['foo', 'bar'])]
+
+-#[Areas(['value' => ['foo', 'bar']])]
++#[Areas(['foo', 'bar'])]
+```
+
 ## 4.36.0
 * Configuration option `with_annotation` has been deprecated in favor of `with_attribute`
 ```diff

phpunit-ignore.txt

@@ -6,4 +6,7 @@
 
 # Ignoring deprecations from Nelmio\ApiDocBundle 4.33.4
 /^Since nelmio\/api-doc-bundle 4\.33\.4: Passing null to the "\$options" argument of "Nelmio\\ApiDocBundle\\Model\\Model\:\:\_\_construct\(\)" is deprecated\, pass an empty array instead\./
-/^Since nelmio\/api-doc-bundle 4\.33\.4: Passing null to the "\$options" argument of "Nelmio\\ApiDocBundle\\Attribute\\Model\:\:\_\_construct\(\)" is deprecated\, pass an empty array instead\./
+/^Since nelmio\/api-doc-bundle 4\.33\.4: Passing null to the "\$options" argument of "Nelmio\\ApiDocBundle\\Attribute\\Model\:\:\_\_construct\(\)" is deprecated\, pass an empty array instead\./
+
+# Ignoring deprecations from Nelmio\ApiDocBundle 4.36.1
+/^Since nelmio\/api-doc-bundle 4\.36\.1: Passing an array with key "value" to "Nelmio\\ApiDocBundle\\Attribute\\Areas\:\:\_\_construct" is deprecated\, pass the list of strings directly\./

src/Attribute/Areas.php

@@ -25,26 +25,26 @@ class Areas
      */
     public function __construct(array $properties)
     {
-        if (!array_key_exists('value', $properties) || !is_array($properties['value'])) {
-            $properties['value'] = array_values($properties);
-        }
-
-        if ([] === $properties['value']) {
-            throw new \InvalidArgumentException('An array of areas was expected');
-        }
-
-        $areas = [];
-        foreach ($properties['value'] as $area) {
-            if (!is_string($area)) {
-                throw new \InvalidArgumentException('An area must be given as a string');
-            }
-
-            if (!in_array($area, $areas, true)) {
-                $areas[] = $area;
+        if (array_key_exists('value', $properties) && is_array($properties['value'])) {
+            trigger_deprecation('nelmio/api-doc-bundle', '4.36.1', 'Passing an array with key "value" to "%s" is deprecated, pass the list of strings directly.', __METHOD__);
+
+            $this->areas = array_values($properties['value']);
+        } else {
+            $this->areas = [];
+            foreach ($properties as $area) {
+                if (!is_string($area)) {
+                    throw new \InvalidArgumentException('An area must be given as a string');
+                }
+
+                if (!in_array($area, $this->areas, true)) {
+                    $this->areas[] = $area;
+                }
             }
         }
 
-        $this->areas = $areas;
+        if ([] === $this->areas) {
+            throw new \InvalidArgumentException('A list of areas was expected');
+        }
     }
 
     public function has(string $area): bool

tests/Attribute/AreasTest.php

@@ -0,0 +1,99 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\Tests\Attribute;
+
+use Nelmio\ApiDocBundle\Attribute\Areas;
+use PHPUnit\Framework\TestCase;
+
+class AreasTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     *
+     * @param string[] $areas
+     */
+    public function testConstruct(array $areas): void
+    {
+        $areasAttribute = new Areas($areas);
+
+        foreach ($areas as $area) {
+            self::assertTrue($areasAttribute->has($area));
+        }
+    }
+
+    /**
+     * @dataProvider provideData
+     *
+     * @param string[] $areas
+     *
+     * @group legacy
+     */
+    public function testDeprecatedConstruct(array $areas): void
+    {
+        $areasAttribute = new Areas(['value' => $areas]);
+
+        foreach ($areas as $area) {
+            self::assertTrue($areasAttribute->has($area));
+        }
+    }
+
+    public static function provideData(): \Generator
+    {
+        yield [
+            ['foo', 'bar'],
+        ];
+
+        yield [
+            ['foo']
+        ];
+
+        yield [
+            ['bar']
+        ];
+    }
+
+    /**
+     * @dataProvider provideInvalidData
+     *
+     * @param string[] $areas
+     */
+    public function testItChecksArrayItemType(array $areas): void
+    {
+        self::expectException(\InvalidArgumentException::class);
+        self::expectExceptionMessage('An area must be given as a string');
+
+        new Areas($areas);
+    }
+
+    public function testItChecksEmptyArray(): void
+    {
+        self::expectException(\InvalidArgumentException::class);
+        self::expectExceptionMessage('A list of areas was expected');
+
+        new Areas([]);
+    }
+
+    public static function provideInvalidData(): \Generator
+    {
+        yield [
+            ['foo', 'bar', 42],
+        ];
+
+        yield [
+            ['foo', 'bar', []],
+        ];
+
+        yield [
+            ['foo', 'bar', new \stdClass()],
+        ];
+    }
+}

tests/Routing/FilteredRouteCollectionBuilderTest.php

@@ -213,7 +213,7 @@ public function testMatchingRoutesWithAnnotation(string $name, Route $route, arr
             $annotationReader
                 ->method('getMethodAnnotation')
                 ->with($reflectionMethodStub, Areas::class)
-                ->willReturn(new Areas(['value' => [$area]]))
+                ->willReturn(new Areas([$area]))
             ;
         }