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

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,
+    )
+    {
+    }
+}

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;

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)