Merge pull request #1103 from cakephp/docblock

Use "array<>" form instead of "[]" to denote arrays in docblocks

Author: ADmad

src/View/Helper/DocBlockHelper.php

@@ -21,11 +21,12 @@ class DocBlockHelper extends Helper
     /**
      * @var bool Whether to add a blank line between different class annotations
      */
-    protected bool $annotationSpacing = true;
+    protected bool $annotationSpacing = false;
 
     /**
      * Writes the DocBlock header for a class which includes the property and method declarations. Annotations are
-     * sorted and grouped by type and value. Groups of annotations are separated by blank lines.
+     * sorted and grouped by type and value. If enabled via the `$annotationSpacing` setting of this helper, groups of
+     * annotations are separated by blank lines.
      *
      * @param string $className The class this comment block is for.
      * @param string $classType The type of class (example, Entity)
@@ -80,7 +81,7 @@ public function associatedEntityTypeToHintType(string $type, Association $associ
             $annotationType === Association::MANY_TO_MANY ||
             $annotationType === Association::ONE_TO_MANY
         ) {
-            return $type . '[]';
+            return 'array<' . $type . '>';
         }
 
         return $type;

templates/bake/Model/entity.twig

@@ -18,7 +18,6 @@
 {% set annotations = DocBlock.propertyHints(propertyHintMap) %}
 
 {%- if associationHintMap %}
-    {%~ set annotations = annotations|merge(['']) %}
     {%~ set annotations = annotations|merge(DocBlock.propertyHints(associationHintMap)) %}
 {% endif %}
 

templates/bake/Template/add.twig

@@ -19,12 +19,12 @@
  * @var \{{ entityClass }} ${{ singularVar }}
 {% if associations.BelongsTo is defined %}
     {%~ for assocName, assocData in associations.BelongsTo %}
- * @var \Cake\Collection\CollectionInterface|string[] ${{ assocData.variable }}
+ * @var \Cake\Collection\CollectionInterface|array<string> ${{ assocData.variable }}
     {%~ endfor %}
 {% endif %}
 {% if associations.BelongsToMany is defined %}
     {%~ for assocName, assocData in associations.BelongsToMany %}
- * @var \Cake\Collection\CollectionInterface|string[] ${{ assocData.variable }}
+ * @var \Cake\Collection\CollectionInterface|array<string> ${{ assocData.variable }}
     {%~ endfor %}
 {% endif %}
  */

templates/bake/Template/edit.twig

@@ -19,12 +19,12 @@
  * @var \{{ entityClass }} ${{ singularVar }}
 {% if associations.BelongsTo is defined %}
     {%~ for assocName, assocData in associations.BelongsTo %}
- * @var string[]|\Cake\Collection\CollectionInterface ${{ assocData.variable }}
+ * @var array<string>|\Cake\Collection\CollectionInterface ${{ assocData.variable }}
     {%~ endfor %}
 {% endif %}
 {% if associations.BelongsToMany is defined %}
     {%~ for assocName, assocData in associations.BelongsToMany %}
- * @var string[]|\Cake\Collection\CollectionInterface ${{ assocData.variable }}
+ * @var array<string>|\Cake\Collection\CollectionInterface ${{ assocData.variable }}
     {%~ endfor %}
 {% endif %}
  */

tests/TestCase/Command/PluginCommandTest.php

@@ -281,7 +281,7 @@ public function assertPluginContents($pluginName, bool $vendor = false): void
     /**
      * Get recursive files list for given path.
      *
-     * @return string[]
+     * @return array<string>
      */
     protected function getFiles(string $path): array
     {

tests/TestCase/Command/SimpleBakeCommandTest.php

@@ -129,7 +129,7 @@ public function testBakePlugin(): void
     /**
      * Provider for subclasses.
      *
-     * @return string[][]
+     * @return array<array<string>>
      */
     public static function subclassProvider(): array
     {

tests/TestCase/View/Helper/DocBlockHelperTest.php

@@ -28,6 +28,7 @@
 use Cake\ORM\Table;
 use Cake\TestSuite\TestCase;
 use PHPUnit\Framework\Attributes\CoversClass;
+use ReflectionProperty;
 
 /**
  * DocBlockHelper Test
@@ -72,7 +73,7 @@ protected function tearDown(): void
     }
 
     /**
-     * Tests the classDescription method including annotation spacing
+     * Tests the classDescription method
      *
      * @return void
      */
@@ -85,6 +86,28 @@ public function testClassDescription(): void
             '@foo $bar baz',
             '@see there',
         ];
+        $classDescription = $this->DocBlockHelper->classDescription($className, $classType, $lines);
+        $expected = "/**\n * Comments Model\n *\n * Line 1\n * @foo \$bar baz\n * @see there\n */";
+        $this::assertSame($expected, $classDescription);
+    }
+
+    /**
+     * Tests the classDescription method with annotation spacing enabled
+     *
+     * @return void
+     */
+    public function testClassDescriptionAnnotationSpacing(): void
+    {
+        $className = 'Comments';
+        $classType = 'Model';
+        $lines = [
+            'Line 1',
+            '@foo $bar baz',
+            '@see there',
+        ];
+        $reflection = new ReflectionProperty($this->DocBlockHelper, 'annotationSpacing');
+        $reflection->setValue($this->DocBlockHelper, true);
+
         $classDescription = $this->DocBlockHelper->classDescription($className, $classType, $lines);
         $expected = "/**\n * Comments Model\n *\n * Line 1\n * @foo \$bar baz\n *\n * @see there\n */";
         $this::assertSame($expected, $classDescription);
@@ -103,14 +126,14 @@ public function testAssociatedEntityTypeToHintType(): void
         $type = 'Foo';
         $association = new BelongsToMany('Foo', $sourceTable);
         $assocEntityType = $this->DocBlockHelper->associatedEntityTypeToHintType($type, $association);
-        $expected = 'Foo[]';
+        $expected = 'array<Foo>';
         $this->assertSame($expected, $assocEntityType);
 
         // Test with ONE_TO_MANY
         $type = 'Bar';
         $association = new HasMany('Bar', $sourceTable);
         $assocEntityType = $this->DocBlockHelper->associatedEntityTypeToHintType($type, $association);
-        $expected = 'Bar[]';
+        $expected = 'array<Bar>';
         $this->assertSame($expected, $assocEntityType);
 
         // Test with ONE_TO_ONE

tests/comparisons/Model/testBakeAssociationDetectionCategoriesProductsTable.php

@@ -13,7 +13,6 @@
  *
  * @property \Bake\Test\App\Model\Table\CategoriesTable&\Cake\ORM\Association\BelongsTo $Categories
  * @property \Bake\Test\App\Model\Table\ProductsTable&\Cake\ORM\Association\BelongsTo $Products
- *
  * @method \Bake\Test\App\Model\Entity\CategoriesProduct newEmptyEntity()
  * @method \Bake\Test\App\Model\Entity\CategoriesProduct newEntity(array $data, array $options = [])
  * @method array<\Bake\Test\App\Model\Entity\CategoriesProduct> newEntities(array $data, array $options = [])

tests/comparisons/Model/testBakeAssociationDetectionCategoriesTable.php

@@ -12,7 +12,6 @@
  * Categories Model
  *
  * @property \Bake\Test\App\Model\Table\ProductsTable&\Cake\ORM\Association\BelongsToMany $Products
- *
  * @method \Bake\Test\App\Model\Entity\Category newEmptyEntity()
  * @method \Bake\Test\App\Model\Entity\Category newEntity(array $data, array $options = [])
  * @method array<\Bake\Test\App\Model\Entity\Category> newEntities(array $data, array $options = [])
@@ -26,7 +25,6 @@
  * @method iterable<\Bake\Test\App\Model\Entity\Category>|\Cake\Datasource\ResultSetInterface<\Bake\Test\App\Model\Entity\Category> saveManyOrFail(iterable $entities, array $options = [])
  * @method iterable<\Bake\Test\App\Model\Entity\Category>|\Cake\Datasource\ResultSetInterface<\Bake\Test\App\Model\Entity\Category>|false deleteMany(iterable $entities, array $options = [])
  * @method iterable<\Bake\Test\App\Model\Entity\Category>|\Cake\Datasource\ResultSetInterface<\Bake\Test\App\Model\Entity\Category> deleteManyOrFail(iterable $entities, array $options = [])
- *
  * @mixin \Cake\ORM\Behavior\TimestampBehavior
  */
 class CategoriesTable extends Table

tests/comparisons/Model/testBakeAssociationDetectionCategoriesTableSigned.php

@@ -12,7 +12,6 @@
  * Categories Model
  *
  * @property \Bake\Test\App\Model\Table\ProductsTable&\Cake\ORM\Association\BelongsToMany $Products
- *
  * @method \Bake\Test\App\Model\Entity\Category newEmptyEntity()
  * @method \Bake\Test\App\Model\Entity\Category newEntity(array $data, array $options = [])
  * @method array<\Bake\Test\App\Model\Entity\Category> newEntities(array $data, array $options = [])
@@ -26,7 +25,6 @@
  * @method iterable<\Bake\Test\App\Model\Entity\Category>|\Cake\Datasource\ResultSetInterface<\Bake\Test\App\Model\Entity\Category> saveManyOrFail(iterable $entities, array $options = [])
  * @method iterable<\Bake\Test\App\Model\Entity\Category>|\Cake\Datasource\ResultSetInterface<\Bake\Test\App\Model\Entity\Category>|false deleteMany(iterable $entities, array $options = [])
  * @method iterable<\Bake\Test\App\Model\Entity\Category>|\Cake\Datasource\ResultSetInterface<\Bake\Test\App\Model\Entity\Category> deleteManyOrFail(iterable $entities, array $options = [])
- *
  * @mixin \Cake\ORM\Behavior\TimestampBehavior
  */
 class CategoriesTable extends Table