Add raw parameter on AdapterInterface and let OpenSpout exporter use it (#366)

* Add raw parameter on AdapterInterface and let OpenSpout exporter use it

This prevents calling normalize() and render() on the column during
export with the ExcelOpenSpoutExporter.

This allows the exporter to decide how PHP values are represented in the
output file.

* Do not cache OptionsResolvers in `AbstractColumn::$resolversByClass`

This fixes a tricky bug. When you initialize a BoolColumn for the second
time, the previously configured OptionsResolver is used. In this
resolver, the default `rightExpr` option value is a callable where $this
refers to the BoolColumn that was created during the first
initialization. This might be a different BoolColumn instance. The call
to $this->getTrueValue() inside the `rightExpr` callable will then
return the wrong value.

I'm not sure if this resolver 'cache' was added after profiling or as a
precautionary measure. If it was just a precaution, I would remove it as
in this commit, as performance optimizations should always only be added
as a result of profiling.

If this was truly done to fix a performance issue, then a different fix
is necessary.

Author: mhvis

src/Adapter/AbstractAdapter.php

@@ -31,7 +31,7 @@ public function __construct()
         $this->accessor = PropertyAccess::createPropertyAccessor();
     }
 
-    final public function getData(DataTableState $state): ResultSetInterface
+    final public function getData(DataTableState $state, bool $raw = false): ResultSetInterface
     {
         $query = new AdapterQuery($state);
 
@@ -41,7 +41,7 @@ final public function getData(DataTableState $state): ResultSetInterface
         $transformer = $state->getDataTable()->getTransformer();
         $identifier = $query->getIdentifierPropertyPath();
 
-        $data = (function () use ($query, $identifier, $transformer, $propertyMap) {
+        $data = (function () use ($query, $identifier, $transformer, $propertyMap, $raw) {
             foreach ($this->getResults($query) as $result) {
                 $row = [];
                 if (!empty($identifier)) {
@@ -51,7 +51,7 @@ final public function getData(DataTableState $state): ResultSetInterface
                 /** @var AbstractColumn $column */
                 foreach ($propertyMap as list($column, $mapping)) {
                     $value = ($mapping && $this->accessor->isReadable($result, $mapping)) ? $this->accessor->getValue($result, $mapping) : null;
-                    $row[$column->getName()] = $column->transform($value, $result);
+                    $row[$column->getName()] = $column->transform($value, $result, raw: $raw);
                 }
                 if (null !== $transformer) {
                     $row = call_user_func($transformer, $row, $result);

src/Adapter/AdapterInterface.php

@@ -31,5 +31,5 @@ public function configure(array $options): void;
     /**
      * Processes a datatable's state into a result set fit for further processing.
      */
-    public function getData(DataTableState $state): ResultSetInterface;
+    public function getData(DataTableState $state, bool $raw = false): ResultSetInterface;
 }

src/Adapter/ArrayAdapter.php

@@ -33,7 +33,7 @@ public function configure(array $options): void
         $this->accessor = PropertyAccess::createPropertyAccessor();
     }
 
-    public function getData(DataTableState $state): ResultSetInterface
+    public function getData(DataTableState $state, bool $raw = false): ResultSetInterface
     {
         // Very basic implementation of sorting
         try {
@@ -64,7 +64,7 @@ public function getData(DataTableState $state): ResultSetInterface
             }
         }
 
-        $data = iterator_to_array($this->processData($state, $this->data, $map));
+        $data = iterator_to_array($this->processData($state, $this->data, $map, $raw));
 
         $length = $state->getLength() ?? 0;
         $page = $length > 0 ? array_slice($data, $state->getStart(), $state->getLength()) : $data;
@@ -77,12 +77,12 @@ public function getData(DataTableState $state): ResultSetInterface
      * @param array<string, string> $map
      * @return \Generator<mixed[]>
      */
-    protected function processData(DataTableState $state, array $data, array $map): \Generator
+    protected function processData(DataTableState $state, array $data, array $map, bool $raw): \Generator
     {
         $transformer = $state->getDataTable()->getTransformer();
         $search = $state->getGlobalSearch() ?: '';
         foreach ($data as $result) {
-            if ($row = $this->processRow($state, $result, $map, $search)) {
+            if ($row = $this->processRow($state, $result, $map, $search, $raw)) {
                 if (null !== $transformer) {
                     $row = call_user_func($transformer, $row, $result);
                 }
@@ -96,13 +96,13 @@ protected function processData(DataTableState $state, array $data, array $map):
      * @param array<string, string> $map
      * @return mixed[]|null
      */
-    protected function processRow(DataTableState $state, array $result, array $map, string $search): ?array
+    protected function processRow(DataTableState $state, array $result, array $map, string $search, bool $raw): ?array
     {
         $row = [];
         $match = empty($search);
         foreach ($state->getDataTable()->getColumns() as $column) {
             $value = (!empty($propertyPath = $map[$column->getName()]) && $this->accessor->isReadable($result, $propertyPath)) ? $this->accessor->getValue($result, $propertyPath) : null;
-            $value = $column->transform($value, $result);
+            $value = $column->transform($value, $result, raw: $raw);
             if (!$match) {
                 $match = (false !== mb_stripos($value, $search));
             }

src/Column/AbstractColumn.php

@@ -24,9 +24,6 @@
  */
 abstract class AbstractColumn
 {
-    /** @var array<string, OptionsResolver> */
-    private static array $resolversByClass = [];
-
     private string $name;
     private int $index;
     private DataTable $dataTable;
@@ -43,21 +40,19 @@ public function initialize(string $name, int $index, array $options, DataTable $
         $this->index = $index;
         $this->dataTable = $dataTable;
 
-        $class = get_class($this);
-        if (!isset(self::$resolversByClass[$class])) {
-            self::$resolversByClass[$class] = new OptionsResolver();
-            $this->configureOptions(self::$resolversByClass[$class]);
-        }
-        $this->options = self::$resolversByClass[$class]->resolve($options);
+        $resolver = new OptionsResolver();
+        $this->configureOptions($resolver);
+        $this->options = $resolver->resolve($options);
     }
 
     /**
      * The transform function is responsible for converting column-appropriate input to a datatables-usable type.
      *
      * @param mixed $value The single value of the column, if mapping makes it possible to derive one
      * @param mixed $context All relevant data of the entire row
+     * @param bool $raw if true, will not normalize the value to string and will not call `AbstractColumn::render()`
      */
-    public function transform(mixed $value = null, mixed $context = null): mixed
+    public function transform(mixed $value = null, mixed $context = null, bool $raw = false): mixed
     {
         $data = $this->getData();
         if (is_callable($data)) {
@@ -66,7 +61,7 @@ public function transform(mixed $value = null, mixed $context = null): mixed
             $value = $data;
         }
 
-        return $this->render($this->normalize($value), $context);
+        return ($raw) ? $value : $this->render($this->normalize($value), $context);
     }
 
     /**

src/Exporter/AbstractDataTableExporter.php

@@ -14,10 +14,18 @@
 
 use Symfony\Component\OptionsResolver\OptionsResolver;
 
+/**
+ * Default implementation for DataTableExporterInterface.
+ */
 abstract class AbstractDataTableExporter implements DataTableExporterInterface
 {
     #[\Override]
     public function configureColumnOptions(OptionsResolver $resolver): void
     {
     }
+
+    public function supportsRawData(): bool
+    {
+        return false;
+    }
 }

src/Exporter/DataTableExporterInterface.php

@@ -46,4 +46,16 @@ public function getName(): string;
      * `exporterOptions` of AbstractColumn.
      */
     public function configureColumnOptions(OptionsResolver $resolver): void;
+
+    /**
+     * Returns whether the exporter supports non-string data.
+     *
+     * The exporter should convert input types to the appropriate output types (e.g. an
+     * int becomes a number type in Excel). Non-supported types should be cast to a
+     * string.
+     *
+     * When this is true, `AbstractColumn::normalize()` and `AbstractColumn::render()`
+     * will not be called.
+     */
+    public function supportsRawData(): bool;
 }

src/Exporter/DataTableExporterManager.php

@@ -90,7 +90,9 @@ public function getExporter(): DataTableExporterInterface
      */
     public function getExport(): \SplFileInfo
     {
-        return $this->getExporter()->export($this->getColumnNames(), $this->getAllData(), $this->getColumnOptions());
+        $exporter = $this->getExporter();
+
+        return $exporter->export($this->getColumnNames(), $this->getAllData($exporter->supportsRawData()), $this->getColumnOptions());
     }
 
     /**
@@ -133,11 +135,11 @@ private function getColumnNames(): array
      * A Generator is created in order to remove the 'DT_RowId' key
      * which is created by some adapters (e.g. ORMAdapter).
      */
-    private function getAllData(): \Iterator
+    private function getAllData(bool $raw): \Iterator
     {
         $data = $this->dataTable
             ->getAdapter()
-            ->getData($this->dataTable->getState()->setStart(0)->setLength(null))
+            ->getData($this->dataTable->getState()->setStart(0)->setLength(null), raw: $raw)
             ->getData();
 
         foreach ($data as $row) {

src/Exporter/Excel/ExcelOpenSpoutExporter.php

@@ -55,9 +55,12 @@ public function export(array $columnNames, \Iterator $data, array $columnOptions
                 }
 
                 if (is_string($value)) {
-                    // The data that we get may contain rich HTML. But OpenSpout does not support this.
-                    // We just strip all HTML tags and unescape the remaining text.
-                    $value = htmlspecialchars_decode(strip_tags($value), ENT_QUOTES | ENT_SUBSTITUTE);
+                    // Previously, we stripped HTML tags and unescaped the value, because the value was passed through
+                    // AbstractColumn::render() which would have escaped special chars and could have added HTML tags.
+                    //
+                    // Now that we have raw data, we don't need to do that anymore.
+                    //
+                    // $value = htmlspecialchars_decode(strip_tags($value), ENT_QUOTES | ENT_SUBSTITUTE);
 
                     // Excel has a limit of 32,767 characters per cell
                     if (mb_strlen($value) > static::MAX_CHARACTERS_PER_CELL) {
@@ -67,7 +70,8 @@ public function export(array $columnNames, \Iterator $data, array $columnOptions
                 }
 
                 // Do not wrap text
-                $row->addCell(Cell::fromValue($value, $this->resolveStyleOption($options['style'], $value)));
+                $style = $this->resolveStyleOption($options['style'], $value);
+                $row->addCell($this->normalizeToCell($value, $style));
 
                 next($columnOptions);
             }
@@ -108,6 +112,25 @@ private function resolveStyleOption(Style|callable $style, mixed $value): Style
         return $style instanceof Style ? $style : $style($value);
     }
 
+    private function normalizeToCell(mixed $value, ?Style $style = null): Cell
+    {
+        if (
+            is_scalar($value)  // (bool, int, float, string)
+            || null === $value
+            || $value instanceof \DateTimeInterface
+            || $value instanceof \DateInterval
+        ) {
+            return Cell::fromValue($value, $style);
+        } else {
+            // Try casting to string, else put an error message in the cell
+            try {
+                return Cell::fromValue((string) $value, $style);
+            } catch (\Throwable $e) {
+                return Cell::fromValue($e->getMessage(), (new Style())->setFontItalic());
+            }
+        }
+    }
+
     public function getMimeType(): string
     {
         return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
@@ -130,4 +153,10 @@ public function configureColumnOptions(OptionsResolver $resolver): void
             ->setAllowedTypes('columnWidth', ['int', 'float'])
         ;
     }
+
+    #[\Override]
+    public function supportsRawData(): bool
+    {
+        return true;
+    }
 }