feat(polyfill): detached Worksheet + addSheet, eager alias surface, value binder, IOFactory registration

php/src/EasyExcel/Compat/Cell/StringValueBinder.php

@@ -0,0 +1,120 @@
+<?php
+
+declare(strict_types=1);
+
+namespace EasyExcel\Compat\Cell;
+
+use EasyExcel\Compat\Exception;
+use EasyExcel\Compat\RichText\RichText;
+
+/**
+ * PhpSpreadsheet's StringValueBinder: binds every value as a string unless
+ * conversion for its type is suppressed, in which case the value keeps its
+ * native data type.
+ *
+ * Differences from the real binder, by design:
+ *  - no UTF-8 sanitisation (the Go side stores strings verbatim);
+ *  - setSetIgnoredErrors() is accepted for API parity but has no effect —
+ *    the extension does not model per-cell ignored-error flags.
+ */
+class StringValueBinder extends DefaultValueBinder
+{
+    protected bool $convertNull = true;
+
+    protected bool $convertBoolean = true;
+
+    protected bool $convertNumeric = true;
+
+    protected bool $convertFormula = true;
+
+    protected bool $setIgnoredErrors = false;
+
+    public function setSetIgnoredErrors(bool $setIgnoredErrors = false): self
+    {
+        $this->setIgnoredErrors = $setIgnoredErrors;
+
+        return $this;
+    }
+
+    public function setNullConversion(bool $suppressConversion = false): self
+    {
+        $this->convertNull = $suppressConversion;
+
+        return $this;
+    }
+
+    public function setBooleanConversion(bool $suppressConversion = false): self
+    {
+        $this->convertBoolean = $suppressConversion;
+
+        return $this;
+    }
+
+    public function getBooleanConversion(): bool
+    {
+        return $this->convertBoolean;
+    }
+
+    public function setNumericConversion(bool $suppressConversion = false): self
+    {
+        $this->convertNumeric = $suppressConversion;
+
+        return $this;
+    }
+
+    public function setFormulaConversion(bool $suppressConversion = false): self
+    {
+        $this->convertFormula = $suppressConversion;
+
+        return $this;
+    }
+
+    public function setConversionForAllValueTypes(bool $suppressConversion = false): self
+    {
+        $this->convertNull = $suppressConversion;
+        $this->convertBoolean = $suppressConversion;
+        $this->convertNumeric = $suppressConversion;
+        $this->convertFormula = $suppressConversion;
+
+        return $this;
+    }
+
+    public function bindValue(Cell $cell, mixed $value): bool
+    {
+        if (\is_object($value)) {
+            return $this->bindObjectValue($cell, $value);
+        }
+        if ($value !== null && !\is_scalar($value)) {
+            throw new Exception('Unable to bind unstringable ' . \gettype($value));
+        }
+
+        if ($value === null && $this->convertNull === false) {
+            $cell->setValueExplicit($value, DataType::TYPE_NULL);
+        } elseif (\is_bool($value) && $this->convertBoolean === false) {
+            $cell->setValueExplicit($value, DataType::TYPE_BOOL);
+        } elseif ((\is_int($value) || \is_float($value)) && $this->convertNumeric === false) {
+            $cell->setValueExplicit($value, DataType::TYPE_NUMERIC);
+        } elseif (\is_string($value) && \strlen($value) > 1 && $value[0] === '=' && $this->convertFormula === false && parent::dataTypeForValue($value) === DataType::TYPE_FORMULA) {
+            $cell->setValueExplicit($value, DataType::TYPE_FORMULA);
+        } else {
+            $cell->setValueExplicit((string) $value, DataType::TYPE_STRING);
+        }
+
+        return true;
+    }
+
+    protected function bindObjectValue(Cell $cell, object $value): bool
+    {
+        if ($value instanceof \DateTimeInterface) {
+            $cell->setValueExplicit($value->format('Y-m-d H:i:s'), DataType::TYPE_STRING);
+        } elseif ($value instanceof RichText) {
+            $cell->setValueExplicit($value, DataType::TYPE_INLINE);
+        } elseif ($value instanceof \Stringable) {
+            $cell->setValueExplicit((string) $value, DataType::TYPE_STRING);
+        } else {
+            throw new Exception('Unable to bind unstringable object of type ' . $value::class);
+        }
+
+        return true;
+    }
+}

php/src/EasyExcel/Compat/Spreadsheet.php

@@ -4,6 +4,7 @@
 
 namespace EasyExcel\Compat;
 
+use EasyExcel\Compat\Cell\IValueBinder;
 use EasyExcel\Compat\Worksheet\Worksheet;
 use EasyExcel\Native;
 
@@ -84,6 +85,30 @@ public function setActiveSheetIndexByName(string $worksheetName): Worksheet
         throw new Exception("Workbook does not contain sheet: $worksheetName");
     }
 
+    /**
+     * PhpSpreadsheet parity: attach an externally constructed (detached)
+     * Worksheet. The sheet is created natively under its current title and
+     * inserted at $sheetIndex (appended when null/out of range).
+     */
+    public function addSheet(Worksheet $worksheet, ?int $sheetIndex = null): Worksheet
+    {
+        if ($this->getSheetByName($worksheet->getTitle()) !== null) {
+            throw new Exception(
+                'Workbook already contains a worksheet named "' . $worksheet->getTitle() . '"; rename it first'
+            );
+        }
+        $worksheet->rebindParent($this);
+        Native::addSheet($this->getHandle(), $worksheet->getTitle());
+        if ($sheetIndex === null || $sheetIndex >= \count($this->worksheets)) {
+            $this->worksheets[] = $worksheet;
+        } else {
+            Native::moveSheet($this->getHandle(), $worksheet->getTitle(), $sheetIndex);
+            \array_splice($this->worksheets, $sheetIndex, 0, [$worksheet]);
+        }
+
+        return $worksheet;
+    }
+
     public function createSheet(?int $sheetIndex = null): Worksheet
     {
         $name = $this->nextSheetName();
@@ -166,6 +191,21 @@ public function removeSheetByIndex(int $sheetIndex): void
         \array_splice($this->worksheets, $sheetIndex, 1);
     }
 
+    /** Workbook-level value binder (PhpSpreadsheet >= 2.x); overrides the legacy static Cell binder. */
+    private ?IValueBinder $valueBinder = null;
+
+    public function setValueBinder(?IValueBinder $valueBinder): static
+    {
+        $this->valueBinder = $valueBinder;
+
+        return $this;
+    }
+
+    public function getValueBinder(): ?IValueBinder
+    {
+        return $this->valueBinder;
+    }
+
     private ?Document\Properties $properties = null;
 
     public function getProperties(): Document\Properties