Add style and columnWidth options to the ExcelOpenSpoutExporter (#368)

This adds an extra option on `AbstractColumn` to configure options
specific for an exporter. The available options are defined on the
exporter using `DataTableExporterInterface::configureColumnOptions()`.

The style option allows to set the OpenSpout cell style for a column.

The columnWidth sets the column width in the Excel sheet.

Author: mhvis

src/Column/AbstractColumn.php

@@ -107,6 +107,7 @@ protected function configureOptions(OptionsResolver $resolver): static
                 'leftExpr' => null,
                 'operator' => '=',
                 'rightExpr' => null,
+                'exporterOptions' => [],
             ])
             ->setAllowedTypes('label', ['null', 'string'])
             ->setAllowedTypes('data', ['null', 'string', 'callable'])
@@ -123,6 +124,8 @@ protected function configureOptions(OptionsResolver $resolver): static
             ->setAllowedTypes('operator', ['string'])
             ->setAllowedTypes('leftExpr', ['null', 'string', 'callable'])
             ->setAllowedTypes('rightExpr', ['null', 'string', 'callable'])
+            ->setAllowedTypes('exporterOptions', ['array'])
+            ->setInfo('exporterOptions', 'Specific exporter options can be specified here, where the key is the exporter name and the value is an array of options.')
         ;
 
         return $this;
@@ -245,4 +248,13 @@ public function isValidForSearch(mixed $value): bool
     {
         return true;
     }
+
+    /**
+     * @param string $exporterName one of the exporter names as returned by DataTableExporterInterface::getName()
+     * @return array<string, mixed>
+     */
+    public function getExporterOptions(string $exporterName): array
+    {
+        return $this->options['exporterOptions'][$exporterName] ?? [];
+    }
 }

src/Exporter/AbstractDataTableExporter.php

@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * Symfony DataTables Bundle
+ * (c) Omines Internetbureau B.V. - https://omines.nl/
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Omines\DataTablesBundle\Exporter;
+
+use Symfony\Component\OptionsResolver\OptionsResolver;
+
+abstract class AbstractDataTableExporter implements DataTableExporterInterface
+{
+    #[\Override]
+    public function configureColumnOptions(OptionsResolver $resolver): void
+    {
+    }
+}

src/Exporter/Csv/CsvExporter.php

@@ -12,16 +12,17 @@
 
 namespace Omines\DataTablesBundle\Exporter\Csv;
 
-use Omines\DataTablesBundle\Exporter\DataTableExporterInterface;
+use Omines\DataTablesBundle\Exporter\AbstractDataTableExporter;
 
 /**
  * Exports DataTable data to a CSV file.
  *
  * @author Maxime Pinot <[email protected]>
  */
-class CsvExporter implements DataTableExporterInterface
+class CsvExporter extends AbstractDataTableExporter
 {
-    public function export(array $columnNames, \Iterator $data): \SplFileInfo
+    #[\Override]
+    public function export(array $columnNames, \Iterator $data, array $columnOptions): \SplFileInfo
     {
         $filePath = sys_get_temp_dir() . '/' . uniqid('dt') . '.csv';
 

src/Exporter/DataTableExporterCollection.php

@@ -35,6 +35,8 @@ public function __construct(\Traversable $exporters)
 
     /**
      * Finds a DataTable exporter that matches the given name.
+     *
+     * @throws UnknownDataTableExporterException when the exporter with the given name cannot be found
      */
     public function getByName(string $name): DataTableExporterInterface
     {

src/Exporter/DataTableExporterInterface.php

@@ -12,6 +12,8 @@
 
 namespace Omines\DataTablesBundle\Exporter;
 
+use Symfony\Component\OptionsResolver\OptionsResolver;
+
 /**
  * Defines a DataTable exporter.
  *
@@ -22,9 +24,10 @@ interface DataTableExporterInterface
     /**
      * Exports the data from the DataTable to a file.
      *
-     * @param mixed[] $columnNames
+     * @param list<string> $columnNames
+     * @param list<array<string, mixed>> $columnOptions the parsed options for each column
      */
-    public function export(array $columnNames, \Iterator $data): \SplFileInfo;
+    public function export(array $columnNames, \Iterator $data, array $columnOptions): \SplFileInfo;
 
     /**
      * The MIME type of the exported file.
@@ -35,4 +38,12 @@ public function getMimeType(): string;
      * A unique name to identify the exporter.
      */
     public function getName(): string;
+
+    /**
+     * Configures the per-column options available for the exporter.
+     *
+     * The manager will resolve the options using the options array set in
+     * `exporterOptions` of AbstractColumn.
+     */
+    public function configureColumnOptions(OptionsResolver $resolver): void;
 }

src/Exporter/DataTableExporterManager.php

@@ -18,6 +18,7 @@
 use Symfony\Component\HttpFoundation\BinaryFileResponse;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\HttpFoundation\ResponseHeaderBag;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 use Symfony\Contracts\Translation\TranslatorInterface;
 
 /**
@@ -60,27 +61,60 @@ public function setDataTable(DataTable $dataTable): static
     }
 
     /**
-     * @throws UnknownDataTableExporterException
+     * @throws UnknownDataTableExporterException when the exporter cannot be found
      */
     public function getResponse(): Response
     {
-        $exporter = $this->exporterCollection->getByName($this->exporterName);
-        $file = $exporter->export($this->getColumnNames(), $this->getAllData());
+        $file = $this->getExport();
 
         $response = new BinaryFileResponse($file);
         $response->deleteFileAfterSend(true);
-        $response->headers->set('Content-Type', $exporter->getMimeType());
+        $response->headers->set('Content-Type', $this->getExporter()->getMimeType());
         $response->setContentDisposition(ResponseHeaderBag::DISPOSITION_ATTACHMENT, $response->getFile()->getFilename());
 
         $this->dataTable->getEventDispatcher()->dispatch(new DataTableExporterResponseEvent($response), DataTableExporterEvents::PRE_RESPONSE);
 
         return $response;
     }
 
+    /**
+     * @throws UnknownDataTableExporterException when the exporter cannot be found
+     */
+    public function getExporter(): DataTableExporterInterface
+    {
+        return $this->exporterCollection->getByName($this->exporterName);
+    }
+
+    /**
+     * @throws UnknownDataTableExporterException when the exporter cannot be found
+     */
+    public function getExport(): \SplFileInfo
+    {
+        return $this->getExporter()->export($this->getColumnNames(), $this->getAllData(), $this->getColumnOptions());
+    }
+
+    /**
+     * @return list<array<string, mixed>>
+     * @throws UnknownDataTableExporterException when the exporter cannot be found
+     */
+    private function getColumnOptions(): array
+    {
+        $resolver = new OptionsResolver();
+        $this->getExporter()->configureColumnOptions($resolver);
+
+        $options = [];
+        foreach ($this->dataTable->getColumns() as $column) {
+            // For each column, resolve the exporter options set on that column
+            $options[] = $resolver->resolve($column->getExporterOptions($this->exporterName));
+        }
+
+        return $options;
+    }
+
     /**
      * The translated column names.
      *
-     * @return string[]
+     * @return list<string>
      */
     private function getColumnNames(): array
     {

src/Exporter/Excel/ExcelExporter.php

@@ -12,7 +12,7 @@
 
 namespace Omines\DataTablesBundle\Exporter\Excel;
 
-use Omines\DataTablesBundle\Exporter\DataTableExporterInterface;
+use Omines\DataTablesBundle\Exporter\AbstractDataTableExporter;
 use PhpOffice\PhpSpreadsheet\Cell\CellAddress;
 use PhpOffice\PhpSpreadsheet\Cell\Coordinate;
 use PhpOffice\PhpSpreadsheet\Helper;
@@ -25,12 +25,10 @@
  *
  * @author Maxime Pinot <[email protected]>
  */
-class ExcelExporter implements DataTableExporterInterface
+class ExcelExporter extends AbstractDataTableExporter
 {
-    /**
-     * @param mixed[] $columnNames
-     */
-    public function export(array $columnNames, \Iterator $data): \SplFileInfo
+    #[\Override]
+    public function export(array $columnNames, \Iterator $data, array $columnOptions): \SplFileInfo
     {
         $spreadsheet = new Spreadsheet();
         $sheet = $spreadsheet->getSheet(0);

src/Exporter/Excel/ExcelOpenSpoutExporter.php

@@ -12,57 +12,64 @@
 
 namespace Omines\DataTablesBundle\Exporter\Excel;
 
-use Omines\DataTablesBundle\Exporter\DataTableExporterInterface;
+use Omines\DataTablesBundle\Exporter\AbstractDataTableExporter;
 use OpenSpout\Common\Entity\Cell;
 use OpenSpout\Common\Entity\Row;
 use OpenSpout\Common\Entity\Style\Style;
 use OpenSpout\Writer\AutoFilter;
 use OpenSpout\Writer\XLSX\Entity\SheetView;
 use OpenSpout\Writer\XLSX\Writer;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 
 /**
  * Excel exporter using OpenSpout.
  */
-class ExcelOpenSpoutExporter implements DataTableExporterInterface
+class ExcelOpenSpoutExporter extends AbstractDataTableExporter
 {
     /**
-     * @param list<scalar> $columnNames
+     * This is an Excel limitation. See: https://support.microsoft.com/en-us/office/excel-specifications-and-limits-1672b34d-7043-467e-8e27-269d656771c3.
      */
-    public function export(array $columnNames, \Iterator $data): \SplFileInfo
+    public const MAX_CHARACTERS_PER_CELL = 32767;
+
+    #[\Override]
+    public function export(array $columnNames, \Iterator $data, array $columnOptions): \SplFileInfo
     {
         $filePath = sys_get_temp_dir() . '/' . uniqid('dt') . '.xlsx';
 
-        // Style definitions
-        $noWrapTextStyle = (new Style())->setShouldWrapText(false);
-        $boldStyle = (new Style())->setFontBold();
-
         $writer = new Writer();
         $writer->openToFile($filePath);
 
-        // Add header
-        $writer->addRow(Row::fromValues($columnNames, $boldStyle));
+        // Header
+        $writer->addRow(Row::fromValues($columnNames, (new Style())->setFontBold()));
 
         $truncated = false;
-        $maxCharactersPerCell = 32767;  // E.g. https://support.microsoft.com/en-us/office/excel-specifications-and-limits-1672b34d-7043-467e-8e27-269d656771c3
         $rowCount = 0;
 
         foreach ($data as $rowValues) {
+            reset($columnOptions);
             $row = new Row([]);
             foreach ($rowValues as $value) {
+                $options = current($columnOptions);
+                if (false === $options) {
+                    throw new \LogicException('Mismatch in number of row values and number of column options');
+                }
+
                 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);
 
                     // Excel has a limit of 32,767 characters per cell
-                    if (mb_strlen($value) > $maxCharactersPerCell) {
+                    if (mb_strlen($value) > static::MAX_CHARACTERS_PER_CELL) {
                         $truncated = true;
-                        $value = mb_substr($value, 0, $maxCharactersPerCell);
+                        $value = mb_substr($value, 0, static::MAX_CHARACTERS_PER_CELL);
                     }
                 }
 
                 // Do not wrap text
-                $row->addCell(Cell::fromValue($value, $noWrapTextStyle));
+                $row->addCell(Cell::fromValue($value, $this->resolveStyleOption($options['style'], $value)));
+
+                next($columnOptions);
             }
             $writer->addRow($row);
             ++$rowCount;
@@ -73,7 +80,11 @@ public function export(array $columnNames, \Iterator $data): \SplFileInfo
         $sheet->setAutoFilter(new AutoFilter(0, 1,
             max(count($columnNames) - 1, 0), $rowCount + 1));
         $sheet->setSheetView((new SheetView())->setFreezeRow(2));
-        $sheet->setColumnWidthForRange(24, 1, max(count($columnNames), 1));
+
+        // Column widths
+        foreach ($columnOptions as $index => $options) {
+            $sheet->setColumnWidth($options['columnWidth'], $index + 1);
+        }
 
         if ($truncated) {
             // Add a notice to the sheet if there is truncated data.
@@ -84,14 +95,19 @@ public function export(array $columnNames, \Iterator $data): \SplFileInfo
             $writer
                 ->addNewSheetAndMakeItCurrent()
                 ->setName('Notice');
-            $writer->addRow(Row::fromValues(['Some cell values were too long! They were truncated to fit the 32,767 character limit.'], $boldStyle));
+            $writer->addRow(Row::fromValues(['Some cell values were too long! They were truncated to fit the 32,767 character limit.'], (new Style())->setFontBold()));
         }
 
         $writer->close();
 
         return new \SplFileInfo($filePath);
     }
 
+    private function resolveStyleOption(Style|callable $style, mixed $value): Style
+    {
+        return $style instanceof Style ? $style : $style($value);
+    }
+
     public function getMimeType(): string
     {
         return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
@@ -101,4 +117,17 @@ public function getName(): string
     {
         return 'excel-openspout';
     }
+
+    #[\Override]
+    public function configureColumnOptions(OptionsResolver $resolver): void
+    {
+        $resolver
+            ->setDefaults([
+                'style' => (new Style())->setShouldWrapText(false),
+                'columnWidth' => 24,
+            ])
+            ->setAllowedTypes('style', [Style::class, 'callable'])
+            ->setAllowedTypes('columnWidth', ['int', 'float'])
+        ;
+    }
 }

tests/Fixtures/AppBundle/Controller/ExporterController.php

@@ -19,6 +19,7 @@
 use Omines\DataTablesBundle\DataTableFactory;
 use Omines\DataTablesBundle\Exporter\DataTableExporterEvents;
 use Omines\DataTablesBundle\Exporter\Event\DataTableExporterResponseEvent;
+use OpenSpout\Common\Entity\Style\Style;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
@@ -38,8 +39,22 @@ public function exportAction(Request $request, DataTableFactory $dataTableFactor
                 'render' => function (string $value, Person $context) {
                     return '<a href="http://example.org">' . $value . '</a>';
                 },
+                // We also test the exporter specific options
+                'exporterOptions' => [
+                    'excel-openspout' => [
+                        'style' => (new Style())->setFontItalic(),
+                        'columnWidth' => 20,
+                    ],
+                ],
+            ])
+            ->add('lastName', TextColumn::class, [
+                'exporterOptions' => [
+                    'excel-openspout' => [
+                        'style' => fn (mixed $value) => (new Style())->setFontBold(),  // We can also use a callable
+                        'columnWidth' => 30,
+                    ],
+                ],
             ])
-            ->add('lastName', TextColumn::class)
             ->createAdapter(ORMAdapter::class, [
                 'entity' => Person::class,
                 'query' => function (QueryBuilder $builder) {