#213: use ListItemContext for ListView::renderItem related operations.

glpzzz · glpzzz · commit 7d1824f62b87 · 2024-09-10T15:21:44.000-04:00
diff --git a/src/ListItemContext.php b/src/ListItemContext.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace Yiisoft\Yii\DataView;
+
+final class ListItemContext
+{
+
+    public function __construct(
+        public readonly array|object $data,
+        public readonly int|string $key,
+        public readonly int $index,
+        public readonly ListView $widget,
+    )
+    {
+    }
+}
diff --git a/src/ListView.php b/src/ListView.php
@@ -173,13 +173,13 @@ public function itemViewTag(?string $tag): self
      * signature:
      *
      * ```php
-     * function ($data, $key, $index, $widget)
+     * function (ListItemContext $context)
      * ```
      * Also, each attribute value can be a function too, with the same signature as in:
      *
      * ```php
      * [
-     *     'class' => static fn($data, $key, $index, $widget) => "custom-class-{$data['id']}",
+     *     'class' => static fn(ListItemContext $context) => "custom-class-{$context->data['id']}",
      * ]
      * ```
      * @return ListView
@@ -223,13 +223,11 @@ public function viewParams(array $viewParams): self
     /**
      * Renders a single data model.
      *
-     * @param array|object $data The data to be rendered.
-     * @param mixed $key The key value associated with the data.
-     * @param int $index The zero-based index of the data array.
+     * @param ListItemContext $context
      *
      * @throws ViewNotFoundException If the item view file doesn't exist.
      */
-    protected function renderItem(array|object $data, mixed $key, int $index): string
+    protected function renderItem(ListItemContext $context): string
     {
         $content = '';
 
@@ -242,9 +240,9 @@ protected function renderItem(array|object $data, mixed $key, int $index): strin
                 $this->itemView,
                 array_merge(
                     [
-                        'data' => $data,
-                        'index' => $index,
-                        'key' => $key,
+                        'data' => $context->data,
+                        'index' => $context->index,
+                        'key' => $context->key,
                         'widget' => $this,
                     ],
                     $this->viewParams
@@ -253,16 +251,16 @@ protected function renderItem(array|object $data, mixed $key, int $index): strin
         }
 
         if ($this->itemView instanceof Closure) {
-            $content = (string)call_user_func($this->itemView, $data, $key, $index, $this);
+            $content = (string)call_user_func($this->itemView, $context);
         }
 
         $itemViewAttributes = is_callable($this->itemViewAttributes)
-            ? (array)call_user_func($this->itemViewAttributes, $data, $key, $index, $this)
+            ? (array)call_user_func($this->itemViewAttributes, $context)
             : $this->itemViewAttributes;
 
         foreach ($itemViewAttributes as $i => $attribute) {
             if (is_callable($attribute)) {
-                $itemViewAttributes[$i] = $attribute($data, $key, $index, $this);
+                $itemViewAttributes[$i] = $attribute($context);
             }
         }
 
@@ -289,13 +287,15 @@ protected function renderItems(array $items, \Yiisoft\Validator\Result $filterVa
         foreach (array_values($items) as $index => $value) {
             $key = $keys[$index];
 
-            if ('' !== ($before = $this->renderBeforeItem($value, $key, $index))) {
+            $itemContext = new ListItemContext($value, $key, $index, $this);
+
+            if ('' !== ($before = $this->renderBeforeItem($itemContext))) {
                 $rows[] = $before;
             }
 
-            $rows[] = $this->renderItem($value, $key, $index);
+            $rows[] = $this->renderItem($itemContext);
 
-            if ('' !== ($after = $this->renderAfterItem($value, $key, $index))) {
+            if ('' !== ($after = $this->renderAfterItem($itemContext))) {
                 $rows[] = $after;
             }
         }
@@ -314,20 +314,18 @@ protected function renderItems(array $items, \Yiisoft\Validator\Result $filterVa
      *
      * If {@see afterItem} is not a closure, `null` will be returned.
      *
-     * @param array|object $data The data to be rendered.
-     * @param mixed $key The key value associated with the data.
-     * @param int $index The zero-based index of the data.
+     * @param ListItemContext $context context of the item to be rendered.
      *
      * @return string call result when {@see afterItem} is not a closure.
      *
      * {@see afterItem}
      */
-    private function renderAfterItem(array|object $data, mixed $key, int $index): string
+    private function renderAfterItem(ListItemContext $context): string
     {
         $result = '';
 
         if (!empty($this->afterItem)) {
-            $result = (string)call_user_func($this->afterItem, $data, $key, $index, $this);
+            $result = (string)call_user_func($this->afterItem, $context->data, $context->key, $context->index, $context->widget);
         }
 
         return $result;
@@ -338,20 +336,18 @@ private function renderAfterItem(array|object $data, mixed $key, int $index): st
      *
      * If {@see beforeItem} is not a closure, `null` will be returned.
      *
-     * @param array|object $data The data to be rendered.
-     * @param mixed $key The key value associated with the data.
-     * @param int $index The zero-based index of the data.
+     * @param ListItemContext $context context of the item to be rendered.
      *
      * @return string call result or `null` when {@see beforeItem} is not a closure.
      *
      * {@see beforeItem}
      */
-    private function renderBeforeItem(array|object $data, mixed $key, int $index): string
+    private function renderBeforeItem(ListItemContext $context): string
     {
         $result = '';
 
         if (!empty($this->beforeItem)) {
-            $result = (string)call_user_func($this->beforeItem, $data, $key, $index, $this);
+            $result = (string)call_user_func($this->beforeItem, $context->data, $context->key, $context->index, $context->widget);
         }
 
         return $result;
diff --git a/tests/ListView/BaseTest.php b/tests/ListView/BaseTest.php
@@ -9,6 +9,7 @@
 use Yiisoft\Definitions\Exception\InvalidConfigException;
 use Yiisoft\Definitions\Exception\NotInstantiableException;
 use Yiisoft\Factory\NotFoundException;
+use Yiisoft\Yii\DataView\ListItemContext;
 use Yiisoft\Yii\DataView\ListView;
 use Yiisoft\Yii\DataView\Tests\Support\Assert;
 use Yiisoft\Yii\DataView\Tests\Support\TestTrait;
@@ -122,7 +123,7 @@ public function testItemViewAsCallable(): void
             HTML,
             ListView::widget()
                 ->itemView(
-                    fn (array $data) => '<div>' . $data['id'] . '</div><div>' . $data['name'] . '</div>' . PHP_EOL
+                    fn (ListItemContext $context) => '<div>' . $context->data['id'] . '</div><div>' . $context->data['name'] . '</div>' . PHP_EOL
                 )
                 ->dataReader($this->createOffsetPaginator($this->data, 10))
                 ->render(),
@@ -426,10 +427,10 @@ public function testClosureForItemViewAttributes(): void
             HTML,
             ListView::widget()
                 ->itemView(dirname(__DIR__) . '/Support/view/_listview.php')
-                ->itemViewAttributes(static fn (array $data, $key, $index, $widget) => [
-                    'data-item-id' => $data['id'],
-                    'data-item-key' => $key,
-                    'data-item-index' => $index,
+                ->itemViewAttributes(static fn (ListItemContext $context) => [
+                    'data-item-id' => $context->data['id'],
+                    'data-item-key' => $context->key,
+                    'data-item-index' => $context->index,
                 ])
                 ->dataReader($this->createOffsetPaginator($this->data, 10))
                 ->separator(PHP_EOL)
@@ -456,7 +457,7 @@ public function testItemViewAttributesWithClosure(): void
             ListView::widget()
                 ->itemView(dirname(__DIR__) . '/Support/view/_listview.php')
                 ->itemViewAttributes([
-                    'class' => static fn(array $data, $key, $index) => "id-{$data['id']}-key-{$key}-index-{$index}",
+                    'class' => static fn(ListItemContext $context) => "id-{$context->data['id']}-key-{$context->key}-index-{$context->index}",
                 ])
                 ->dataReader($this->createOffsetPaginator($this->data, 10))
                 ->separator(PHP_EOL)
@@ -482,8 +483,8 @@ public function testClosureForItemViewAttributesWithClosure(): void
             HTML,
             ListView::widget()
                 ->itemView(dirname(__DIR__) . '/Support/view/_listview.php')
-                ->itemViewAttributes(static fn (array $data, $key, $index) => [
-                    'class' => static fn(array $data, $key, $index) => "id-{$data['id']}-key-{$key}-index-{$index}",
+                ->itemViewAttributes(static fn (ListItemContext $context) => [
+                    'class' => static fn(ListItemContext $context) => "id-{$context->data['id']}-key-{$context->key}-index-{$context->index}",
                 ])
                 ->dataReader($this->createOffsetPaginator($this->data, 10))
                 ->separator(PHP_EOL)

Original file line number	Diff line number	Diff line change
`@@ -173,13 +173,13 @@ public function itemViewTag(?string $tag): self`
`173`	`173`	`* signature:`
`174`	`174`	`*`
`175`	`175`	* ```php
`176`		`- * function ($data, $key, $index, $widget)`
	`176`	`+ * function (ListItemContext $context)`
`177`	`177`	* ```
`178`	`178`	`* Also, each attribute value can be a function too, with the same signature as in:`
`179`	`179`	`*`
`180`	`180`	* ```php
`181`	`181`	`* [`
`182`		`- * 'class' => static fn($data, $key, $index, $widget) => "custom-class-{$data['id']}",`
	`182`	`+ * 'class' => static fn(ListItemContext $context) => "custom-class-{$context->data['id']}",`
`183`	`183`	`* ]`
`184`	`184`	* ```
`185`	`185`	`* @return ListView`
`@@ -223,13 +223,11 @@ public function viewParams(array $viewParams): self`
`223`	`223`	`/**`
`224`	`224`	`* Renders a single data model.`
`225`	`225`	`*`
`226`		`- * @param array\|object $data The data to be rendered.`
`227`		`- * @param mixed $key The key value associated with the data.`
`228`		`- * @param int $index The zero-based index of the data array.`
	`226`	`+ * @param ListItemContext $context`
`229`	`227`	`*`
`230`	`228`	`* @throws ViewNotFoundException If the item view file doesn't exist.`
`231`	`229`	`*/`
`232`		`- protected function renderItem(array\|object $data, mixed $key, int $index): string`
	`230`	`+ protected function renderItem(ListItemContext $context): string`
`233`	`231`	`{`
`234`	`232`	`$content = '';`
`235`	`233`
`@@ -242,9 +240,9 @@ protected function renderItem(array\|object $data, mixed $key, int $index): strin`
`242`	`240`	`$this->itemView,`
`243`	`241`	`array_merge(`
`244`	`242`	`[`
`245`		`- 'data' => $data,`
`246`		`- 'index' => $index,`
`247`		`- 'key' => $key,`
	`243`	`+ 'data' => $context->data,`
	`244`	`+ 'index' => $context->index,`
	`245`	`+ 'key' => $context->key,`
`248`	`246`	`'widget' => $this,`
`249`	`247`	`],`
`250`	`248`	`$this->viewParams`
`@@ -253,16 +251,16 @@ protected function renderItem(array\|object $data, mixed $key, int $index): strin`
`253`	`251`	`}`
`254`	`252`
`255`	`253`	`if ($this->itemView instanceof Closure) {`
`256`		`- $content = (string)call_user_func($this->itemView, $data, $key, $index, $this);`
	`254`	`+ $content = (string)call_user_func($this->itemView, $context);`
`257`	`255`	`}`
`258`	`256`
`259`	`257`	`$itemViewAttributes = is_callable($this->itemViewAttributes)`
`260`		`- ? (array)call_user_func($this->itemViewAttributes, $data, $key, $index, $this)`
	`258`	`+ ? (array)call_user_func($this->itemViewAttributes, $context)`
`261`	`259`	`: $this->itemViewAttributes;`
`262`	`260`
`263`	`261`	`foreach ($itemViewAttributes as $i => $attribute) {`
`264`	`262`	`if (is_callable($attribute)) {`
`265`		`- $itemViewAttributes[$i] = $attribute($data, $key, $index, $this);`
	`263`	`+ $itemViewAttributes[$i] = $attribute($context);`
`266`	`264`	`}`
`267`	`265`	`}`
`268`	`266`
`@@ -289,13 +287,15 @@ protected function renderItems(array $items, \Yiisoft\Validator\Result $filterVa`
`289`	`287`	`foreach (array_values($items) as $index => $value) {`
`290`	`288`	`$key = $keys[$index];`
`291`	`289`
`292`		`- if ('' !== ($before = $this->renderBeforeItem($value, $key, $index))) {`
	`290`	`+ $itemContext = new ListItemContext($value, $key, $index, $this);`
	`291`	`+`
	`292`	`+ if ('' !== ($before = $this->renderBeforeItem($itemContext))) {`
`293`	`293`	`$rows[] = $before;`
`294`	`294`	`}`
`295`	`295`
`296`		`- $rows[] = $this->renderItem($value, $key, $index);`
	`296`	`+ $rows[] = $this->renderItem($itemContext);`
`297`	`297`
`298`		`- if ('' !== ($after = $this->renderAfterItem($value, $key, $index))) {`
	`298`	`+ if ('' !== ($after = $this->renderAfterItem($itemContext))) {`
`299`	`299`	`$rows[] = $after;`
`300`	`300`	`}`
`301`	`301`	`}`
`@@ -314,20 +314,18 @@ protected function renderItems(array $items, \Yiisoft\Validator\Result $filterVa`
`314`	`314`	`*`
`315`	`315`	* If {@see afterItem} is not a closure, `null` will be returned.
`316`	`316`	`*`
`317`		`- * @param array\|object $data The data to be rendered.`
`318`		`- * @param mixed $key The key value associated with the data.`
`319`		`- * @param int $index The zero-based index of the data.`
	`317`	`+ * @param ListItemContext $context context of the item to be rendered.`
`320`	`318`	`*`
`321`	`319`	`* @return string call result when {@see afterItem} is not a closure.`
`322`	`320`	`*`
`323`	`321`	`* {@see afterItem}`
`324`	`322`	`*/`
`325`		`- private function renderAfterItem(array\|object $data, mixed $key, int $index): string`
	`323`	`+ private function renderAfterItem(ListItemContext $context): string`
`326`	`324`	`{`
`327`	`325`	`$result = '';`
`328`	`326`
`329`	`327`	`if (!empty($this->afterItem)) {`
`330`		`- $result = (string)call_user_func($this->afterItem, $data, $key, $index, $this);`
	`328`	`+ $result = (string)call_user_func($this->afterItem, $context->data, $context->key, $context->index, $context->widget);`
`331`	`329`	`}`
`332`	`330`
`333`	`331`	`return $result;`
`@@ -338,20 +336,18 @@ private function renderAfterItem(array\|object $data, mixed $key, int $index): st`
`338`	`336`	`*`
`339`	`337`	* If {@see beforeItem} is not a closure, `null` will be returned.
`340`	`338`	`*`
`341`		`- * @param array\|object $data The data to be rendered.`
`342`		`- * @param mixed $key The key value associated with the data.`
`343`		`- * @param int $index The zero-based index of the data.`
	`339`	`+ * @param ListItemContext $context context of the item to be rendered.`
`344`	`340`	`*`
`345`	`341`	* @return string call result or `null` when {@see beforeItem} is not a closure.
`346`	`342`	`*`
`347`	`343`	`* {@see beforeItem}`
`348`	`344`	`*/`
`349`		`- private function renderBeforeItem(array\|object $data, mixed $key, int $index): string`
	`345`	`+ private function renderBeforeItem(ListItemContext $context): string`
`350`	`346`	`{`
`351`	`347`	`$result = '';`
`352`	`348`
`353`	`349`	`if (!empty($this->beforeItem)) {`
`354`		`- $result = (string)call_user_func($this->beforeItem, $data, $key, $index, $this);`
	`350`	`+ $result = (string)call_user_func($this->beforeItem, $context->data, $context->key, $context->index, $context->widget);`
`355`	`351`	`}`
`356`	`352`
`357`	`353`	`return $result;`