Add Dynamic valueBinder Property to Spreadsheet and Readers

Fix #1395, a 2020 issue which had been marked stale and is now re-opened. Static valueBinder property of Cell isn't ideal. It would be more flexible to make it a dynamic property of the spreadsheet. Static property will continue to be used, but dynamic property will be used first if it is set. Readers will also be changed to add a valueBinder property which they pass to the spreadsheet; however, it will make a difference only for Csv/Html/Slk, since the other readers use setValueExplicit which ignores valueBinder.

Documentation is updated in several places to note that dynamic property is preferred over static.

Author: oleibman

docs/topics/Behind the Mask.md

@@ -117,7 +117,10 @@ If you wish to emulate the MS Excel behaviour, and automatically convert string
 
 You can do this by changing the Value Binder, which will then apply every time you set a Cell value.
 ```php
+// Old method using static property
 Cell::setValueBinder(new AdvancedValueBinder());
+// Preferred method using dynamic property since 3.4.0
+$spreadsheet->setValueBinder(new AdvancedValueBinder());
 
 // Set Cell C21 using a formatted string value
 $worksheet->getCell('C20')->setValue('€ -12345.6789');

docs/topics/The Dating Game.md

@@ -257,7 +257,10 @@ $spreadsheet = new Spreadsheet();
 $worksheet = $spreadsheet->getActiveSheet();
 // Use the Advanced Value Binder so that our string date/time values will be automatically converted
 //     to Excel serialized date/timestamps
+// Old method using static property
 Cell::setValueBinder(new AdvancedValueBinder());
+// Preferred method using dynamic property since 3.4.0
+$spreadsheet->setValueBinder(new AdvancedValueBinder());
 
 // Write our data to the worksheet
 $worksheet->fromArray($projectHeading);

docs/topics/accessing-cells.md

@@ -518,15 +518,15 @@ style information. The following example demonstrates how to set the
 value binder in PhpSpreadsheet:
 
 ```php
-/** PhpSpreadsheet */
-require_once 'src/Boostrap.php';
-
-// Set value binder
+// Older method using static property
 \PhpOffice\PhpSpreadsheet\Cell\Cell::setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() );
-
 // Create new Spreadsheet object
 $spreadsheet = new \PhpOffice\PhpSpreadsheet\Spreadsheet();
 
+// Preferred method using dynamic property since 3.4.0
+$spreadsheet = new \PhpOffice\PhpSpreadsheet\Spreadsheet();
+$spreadsheet->setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() );
+
 // ...
 // Add some data, resembling some different data types
 $spreadsheet->getActiveSheet()->setCellValue('A4', 'Percentage value:');
@@ -555,13 +555,20 @@ $stringValueBinder->setNumericConversion(false)
     ->setBooleanConversion(false)
     ->setNullConversion(false)
     ->setFormulaConversion(false);
+// Older method using static property
 \PhpOffice\PhpSpreadsheet\Cell\Cell::setValueBinder( $stringValueBinder );
+// Preferred method using dynamic property since 3.4.0
+$spreadsheet = new \PhpOffice\PhpSpreadsheet\Spreadsheet();
+$spreadsheet->setValueBinder( $stringValueBinder );
 ```
 
 You can override the current binder when setting individual cell values by specifying a different Binder to use in the Cell's `setValue()` or the Worksheet's `setCellValue()` methods.
 ```php
 $spreadsheet = new Spreadsheet();
+// Old method using static property
 Cell::setValueBinder(new AdvancedValueBinder());
+// Preferred method using dynamic property since 3.4.0
+$spreadsheet->setValueBinder(new AdvancedValueBinder());
 
 $value = '12.5%';
 

docs/topics/reading-files.md

@@ -755,14 +755,18 @@ So using a Value Binder allows a great deal more flexibility in the
 loader logic when reading unformatted text files.
 
 ```php
-/**  Tell PhpSpreadsheet that we want to use the Advanced Value Binder  **/
-\PhpOffice\PhpSpreadsheet\Cell\Cell::setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() );
-
 $inputFileType = 'Csv';
 $inputFileName = './sampleData/example1.tsv';
 
 $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType);
 $reader->setDelimiter("\t");
+
+/**  Tell PhpSpreadsheet that we want to use the Advanced Value Binder  **/
+// Old method using static property
+\PhpOffice\PhpSpreadsheet\Cell\Cell::setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() );
+// Preferred method using dynamic property since 3.4.0
+$reader::setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() );
+
 $spreadsheet = $reader->load($inputFileName);
 ```
 
@@ -774,7 +778,7 @@ Loading using a Value Binder applies to:
 Reader    | Y/N |Reader  | Y/N |Reader        | Y/N
 ----------|:---:|--------|:---:|--------------|:---:
 Xlsx      | NO  | Xls    | NO  | Xml          | NO
-Ods       | NO  | SYLK   | NO  | Gnumeric     | NO
+Ods       | NO  | SYLK   | YES | Gnumeric     | NO
 CSV       | YES | HTML   | YES
 
 Note that you can also use the Binder to determine how PhpSpreadsheet identified datatypes for values when you set a cell value without explicitly setting a datatype.

docs/topics/recipes.md

@@ -233,7 +233,10 @@ method that suits you the best. Here are some examples:
 
 ```php
 // MySQL-like timestamp '2008-12-31' or date string
+// Old method using static property
 \PhpOffice\PhpSpreadsheet\Cell\Cell::setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() );
+// Preferred method using dynamic property since 3.4.0
+$spreadsheet->setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() );
 
 $spreadsheet->getActiveSheet()
     ->setCellValue('D1', '2008-12-31');
@@ -599,7 +602,10 @@ when it sees a newline character in a string that you are inserting in a
 cell. Just like Microsoft Office Excel. Try this:
 
 ```php
+// Old method using static property
 \PhpOffice\PhpSpreadsheet\Cell\Cell::setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() );
+// Preferred method using dynamic property since 3.4.0
+$spreadsheet->setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() );
 
 $spreadsheet->getActiveSheet()->getCell('A1')->setValue("hello\nworld");
 ```

src/PhpSpreadsheet/Cell/Cell.php

@@ -112,8 +112,11 @@ public function __construct(mixed $value, ?string $dataType, Worksheet $workshee
                 $dataType = DataType::TYPE_STRING;
             }
             $this->dataType = $dataType;
-        } elseif (self::getValueBinder()->bindValue($this, $value) === false) {
-            throw new SpreadsheetException('Value could not be bound to cell.');
+        } else {
+            $valueBinder = $worksheet->getParent()?->getValueBinder() ?? self::getValueBinder();
+            if ($valueBinder->bindValue($this, $value) === false) {
+                throw new SpreadsheetException('Value could not be bound to cell.');
+            }
         }
         $this->ignoredErrors = new IgnoredErrors();
     }
@@ -232,7 +235,8 @@ protected static function updateIfCellIsTableHeader(?Worksheet $workSheet, self
      */
     public function setValue(mixed $value, ?IValueBinder $binder = null): self
     {
-        $binder ??= self::getValueBinder();
+        // Cells?->Worksheet?->Spreadsheet
+        $binder ??= $this->parent?->getParent()?->getParent()?->getValueBinder() ?? self::getValueBinder();
         if (!$binder->bindValue($this, $value)) {
             throw new SpreadsheetException('Value could not be bound to cell.');
         }

src/PhpSpreadsheet/Reader/BaseReader.php

@@ -2,6 +2,7 @@
 
 namespace PhpOffice\PhpSpreadsheet\Reader;
 
+use PhpOffice\PhpSpreadsheet\Cell\IValueBinder;
 use PhpOffice\PhpSpreadsheet\Exception as PhpSpreadsheetException;
 use PhpOffice\PhpSpreadsheet\Reader\Exception as ReaderException;
 use PhpOffice\PhpSpreadsheet\Reader\Security\XmlScanner;
@@ -56,6 +57,8 @@ abstract class BaseReader implements IReader
 
     protected ?XmlScanner $securityScanner = null;
 
+    protected ?IValueBinder $valueBinder = null;
+
     public function __construct()
     {
         $this->readFilter = new DefaultReadFilter();
@@ -242,4 +245,16 @@ public function listWorksheetNames(string $filename): array
 
         return $returnArray;
     }
+
+    public function getValueBinder(): ?IValueBinder
+    {
+        return $this->valueBinder;
+    }
+
+    public function setValueBinder(?IValueBinder $valueBinder): self
+    {
+        $this->valueBinder = $valueBinder;
+
+        return $this;
+    }
 }

src/PhpSpreadsheet/Reader/Csv.php

@@ -262,6 +262,7 @@ protected function loadSpreadsheetFromFile(string $filename): Spreadsheet
     {
         // Create new Spreadsheet
         $spreadsheet = new Spreadsheet();
+        $spreadsheet->setValueBinder($this->valueBinder);
 
         // Load into this instance
         return $this->loadIntoExisting($filename, $spreadsheet);
@@ -274,6 +275,7 @@ public function loadSpreadsheetFromString(string $contents): Spreadsheet
     {
         // Create new Spreadsheet
         $spreadsheet = new Spreadsheet();
+        $spreadsheet->setValueBinder($this->valueBinder);
 
         // Load into this instance
         return $this->loadStringOrFile('data://text/plain,' . urlencode($contents), $spreadsheet, true);
@@ -391,7 +393,7 @@ private function loadStringOrFile(string $filename, Spreadsheet $spreadsheet, bo
         // Loop through each line of the file in turn
         $delimiter = $this->delimiter ?? '';
         $rowData = self::getCsv($fileHandle, 0, $delimiter, $this->enclosure, $this->escapeCharacter);
-        $valueBinder = Cell::getValueBinder();
+        $valueBinder = $this->valueBinder ?? Cell::getValueBinder();
         $preserveBooleanString = method_exists($valueBinder, 'getBooleanConversion') && $valueBinder->getBooleanConversion();
         $this->getTrue = Calculation::getTRUE();
         $this->getFalse = Calculation::getFALSE();

src/PhpSpreadsheet/Reader/Gnumeric.php

@@ -226,6 +226,7 @@ protected function loadSpreadsheetFromFile(string $filename): Spreadsheet
     {
         // Create new Spreadsheet
         $spreadsheet = new Spreadsheet();
+        $spreadsheet->setValueBinder($this->valueBinder);
         $spreadsheet->removeSheetByIndex(0);
 
         // Load into this instance

src/PhpSpreadsheet/Reader/Html.php

@@ -210,6 +210,7 @@ public function loadSpreadsheetFromFile(string $filename): Spreadsheet
     {
         // Create new Spreadsheet
         $spreadsheet = new Spreadsheet();
+        $spreadsheet->setValueBinder($this->valueBinder);
 
         // Load into this instance
         return $this->loadIntoExisting($filename, $spreadsheet);
@@ -786,6 +787,7 @@ public function loadFromString(string $content, ?Spreadsheet $spreadsheet = null
             throw new Exception('Failed to load content as a DOM Document', 0, $e ?? null);
         }
         $spreadsheet = $spreadsheet ?? new Spreadsheet();
+        $spreadsheet->setValueBinder($this->valueBinder);
         self::loadProperties($dom, $spreadsheet);
 
         return $this->loadDocument($dom, $spreadsheet);