[9.0] Add column formatter. (#2193)

* Add column formatters.

* Apply fixes from StyleCI

* Add formatColumn test.

* Apply fixes from StyleCI

* Reverse cs.

* Fix doc blocks and exception error message.

Co-authored-by: Arjay Angeles <[email protected]>

Author: yajra

src/Contracts/Formatter.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Yajra\DataTables\Contracts;
+
+interface Formatter
+{
+    /**
+     * @param string $value
+     * @param mixed $row
+     * @return string
+     */
+    public function format($value, $row);
+}

src/DataTableAbstract.php

@@ -10,6 +10,7 @@
 use Illuminate\Support\Traits\Macroable;
 use Psr\Log\LoggerInterface;
 use Yajra\DataTables\Contracts\DataTable;
+use Yajra\DataTables\Contracts\Formatter;
 use Yajra\DataTables\Exceptions\Exception;
 use Yajra\DataTables\Processors\DataProcessor;
 use Yajra\DataTables\Utilities\Helper;
@@ -189,6 +190,29 @@ public function addColumn($name, $content, $order = false)
         return $this;
     }
 
+    /**
+     * @param string|array $columns
+     * @param mixed|\Yajra\DataTables\Contracts\Formatter $formatter
+     * @return $this
+     * @throws \Exception
+     */
+    public function formatColumn($columns, $formatter)
+    {
+        if (is_string($formatter) && class_exists($formatter)) {
+            $formatter = app($formatter);
+        }
+
+        if (! $formatter instanceof Formatter) {
+            throw new \Exception('$formatter must be an instance of '. Formatter::class);
+        }
+
+        foreach ((array) $columns as $column) {
+            $this->addColumn($column . '_formatted', $formatter);
+        }
+
+        return $this;
+    }
+
     /**
      * Add DT row index column on response.
      *

src/Processors/DataProcessor.php

@@ -4,6 +4,7 @@
 
 use Illuminate\Contracts\Support\Htmlable;
 use Illuminate\Support\Arr;
+use Yajra\DataTables\Contracts\Formatter;
 use Yajra\DataTables\Utilities\Helper;
 
 class DataProcessor
@@ -127,9 +128,16 @@ public function process($object = false)
      */
     protected function addColumns($data, $row)
     {
-        foreach ($this->appendColumns as $key => $value) {
-            $value['content'] = Helper::compileContent($value['content'], $data, $row);
-            $data             = Helper::includeInArray($value, $data);
+        foreach ($this->appendColumns as $value) {
+            if ($value['content'] instanceof Formatter) {
+                $column = str_replace('_formatted', '', $value['name']);
+
+                $value['content'] = $value['content']->format($data[$column], $row);
+            } else {
+                $value['content'] = Helper::compileContent($value['content'], $data, $row);
+            }
+
+            $data = Helper::includeInArray($value, $data);
         }
 
         return $data;

tests/Integration/QueryDataTableTest.php

@@ -2,10 +2,12 @@
 
 namespace Yajra\DataTables\Tests\Integration;
 
+use Carbon\Carbon;
 use Illuminate\Database\Query\Builder;
 use Illuminate\Foundation\Testing\DatabaseTransactions;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
+use Yajra\DataTables\Contracts\Formatter;
 use Yajra\DataTables\DataTables;
 use Yajra\DataTables\Facades\DataTables as DatatablesFacade;
 use Yajra\DataTables\QueryDataTable;
@@ -286,6 +288,27 @@ public function it_allows_column_search_added_column_with_custom_filter_handler(
         ]);
     }
 
+    /** @test */
+    public function it_can_return_formatted_columns()
+    {
+        $crawler = $this->call('GET', '/query/formatColumn');
+
+        $crawler->assertJson([
+            'draw'            => 0,
+            'recordsTotal'    => 20,
+            'recordsFiltered' => 20,
+        ]);
+
+        $user = DB::table('users')->find(1);
+        $data = $crawler->json('data')[0];
+
+        $this->assertTrue(isset($data['created_at']));
+        $this->assertTrue(isset($data['created_at_formatted']));
+
+        $this->assertEquals($user->created_at, $data['created_at']);
+        $this->assertEquals(Carbon::parse($user->created_at)->format('Y-m-d'), $data['created_at_formatted']);
+    }
+
     protected function setUp(): void
     {
         parent::setUp();
@@ -296,6 +319,12 @@ protected function setUp(): void
             return $dataTable->query(DB::table('users'))->toJson();
         });
 
+        $route->get('/query/formatColumn', function (DataTables $dataTable) {
+            return $dataTable->query(DB::table('users'))
+                        ->formatColumn('created_at', new DateFormatter('Y-m-d'))
+                        ->toJson();
+        });
+
         $route->get('/query/simple', function (DataTables $dataTable) {
             return $dataTable->query(DB::table('users'))->skipTotalRecords()->toJson();
         });
@@ -376,3 +405,22 @@ protected function setUp(): void
         });
     }
 }
+
+class DateFormatter implements Formatter
+{
+    protected $format;
+
+    public function __construct($format = null)
+    {
+        $this->format = $format;
+    }
+
+    public function format($value, $row)
+    {
+        if ($this->format) {
+            return Carbon::parse($value)->format($this->format);
+        }
+
+        return Carbon::parse($value)->diffForHumans();
+    }
+}