From c9dc1e6130183515c69ccbaa2cd9d7f19b261474 Mon Sep 17 00:00:00 2001
From: Mark Baker <mark@lange.demon.co.uk>
Date: Sat, 23 Feb 2019 18:40:07 +0100
Subject: [PATCH] String value binder (#901)

* Document calculation caching; and how to disable it and how to flush the cache

* Quoted text for string values beginning with `=`, so that they are still treated as strings and not as formulae

* Warning about assigning cells to variables

* Further warning about assigning cells to variables

* getCell() with a second argument

* Added String Value Binder, and a Reader example demonstrating how to use it

* Ensure value is a string before binding

* Sample file for String Value Binder

* PHPCS moaning about order or use statements

* Order of annotations, that PHPStorm determined, isn't what phpcs says it should be
---
 docs/topics/accessing-cells.md                |  7 +++++
 ...Long_Integers_with_String_Value_Binder.php | 27 ++++++++++++++++
 samples/Reader/sampleData/longIntegers.csv    |  6 ++++
 .../Cell/AdvancedValueBinder.php              |  2 ++
 .../Cell/DefaultValueBinder.php               |  2 ++
 src/PhpSpreadsheet/Cell/StringValueBinder.php | 31 +++++++++++++++++++
 6 files changed, 75 insertions(+)
 create mode 100644 samples/Reader/21_Reader_CSV_Long_Integers_with_String_Value_Binder.php
 create mode 100644 samples/Reader/sampleData/longIntegers.csv
 create mode 100644 src/PhpSpreadsheet/Cell/StringValueBinder.php

diff --git a/docs/topics/accessing-cells.md b/docs/topics/accessing-cells.md
index acf361cd..da8b0c36 100644
--- a/docs/topics/accessing-cells.md
+++ b/docs/topics/accessing-cells.md
@@ -34,6 +34,13 @@ $spreadsheet->getActiveSheet()
     ->setValue('Some value');
 ```
 
+### Creating a new Cell
+
+If you make a call to `getCell()`, and the cell doesn't already exist, then
+PhpSpreadsheet will (by default) create the cell for you. If you don't want
+to create a new cell, then you can pass a second argument of false, and then
+`getCell()` will return a null if the cell doesn't exist.
+
 ### BEWARE: Cells assigned to variables as a Detached Reference
 
 As an "in-memory" model, PHPSpreadsheet can be very demanding of memory,
diff --git a/samples/Reader/21_Reader_CSV_Long_Integers_with_String_Value_Binder.php b/samples/Reader/21_Reader_CSV_Long_Integers_with_String_Value_Binder.php
new file mode 100644
index 00000000..2c80de3b
--- /dev/null
+++ b/samples/Reader/21_Reader_CSV_Long_Integers_with_String_Value_Binder.php
@@ -0,0 +1,27 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Cell\Cell;
+use PhpOffice\PhpSpreadsheet\Cell\StringValueBinder;
+use PhpOffice\PhpSpreadsheet\IOFactory;
+
+require __DIR__ . '/../Header.php';
+
+Cell::setValueBinder(new StringValueBinder());
+
+$inputFileType = 'Csv';
+$inputFileName = __DIR__ . '/sampleData/longIntegers.csv';
+
+$reader = IOFactory::createReader($inputFileType);
+$helper->log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' into WorkSheet #1 using IOFactory with a defined reader type of ' . $inputFileType);
+
+$spreadsheet = $reader->load($inputFileName);
+$spreadsheet->getActiveSheet()->setTitle(pathinfo($inputFileName, PATHINFO_BASENAME));
+
+$helper->log($spreadsheet->getSheetCount() . ' worksheet' . (($spreadsheet->getSheetCount() == 1) ? '' : 's') . ' loaded');
+$loadedSheetNames = $spreadsheet->getSheetNames();
+foreach ($loadedSheetNames as $sheetIndex => $loadedSheetName) {
+    $helper->log('<b>Worksheet #' . $sheetIndex . ' -> ' . $loadedSheetName . ' (Formatted)</b>');
+    $spreadsheet->setActiveSheetIndexByName($loadedSheetName);
+    $sheetData = $spreadsheet->getActiveSheet()->toArray(null, true, true, true);
+    var_dump($sheetData);
+}
diff --git a/samples/Reader/sampleData/longIntegers.csv b/samples/Reader/sampleData/longIntegers.csv
new file mode 100644
index 00000000..166f4a86
--- /dev/null
+++ b/samples/Reader/sampleData/longIntegers.csv
@@ -0,0 +1,6 @@
+"Column 1","Column 2"
+123456789012345678901234,234567890123456789012345
+345678901234567890123456,456789012345678901234567
+567890123456789012345678,678901234567890123456789
+789012345678901234567890,890123456789012345678901
+901234567890123456789012,012345678901234567890123
diff --git a/src/PhpSpreadsheet/Cell/AdvancedValueBinder.php b/src/PhpSpreadsheet/Cell/AdvancedValueBinder.php
index efb8e5ef..4052c23c 100644
--- a/src/PhpSpreadsheet/Cell/AdvancedValueBinder.php
+++ b/src/PhpSpreadsheet/Cell/AdvancedValueBinder.php
@@ -16,6 +16,8 @@ class AdvancedValueBinder extends DefaultValueBinder implements IValueBinder
      * @param Cell $cell Cell to bind value to
      * @param mixed $value Value to bind in cell
      *
+     * @throws \PhpOffice\PhpSpreadsheet\Exception
+     *
      * @return bool
      */
     public function bindValue(Cell $cell, $value = null)
diff --git a/src/PhpSpreadsheet/Cell/DefaultValueBinder.php b/src/PhpSpreadsheet/Cell/DefaultValueBinder.php
index 7cbb6cca..0e6433a4 100644
--- a/src/PhpSpreadsheet/Cell/DefaultValueBinder.php
+++ b/src/PhpSpreadsheet/Cell/DefaultValueBinder.php
@@ -14,6 +14,8 @@ class DefaultValueBinder implements IValueBinder
      * @param Cell $cell Cell to bind value to
      * @param mixed $value Value to bind in cell
      *
+     * @throws \PhpOffice\PhpSpreadsheet\Exception
+     *
      * @return bool
      */
     public function bindValue(Cell $cell, $value)
diff --git a/src/PhpSpreadsheet/Cell/StringValueBinder.php b/src/PhpSpreadsheet/Cell/StringValueBinder.php
new file mode 100644
index 00000000..0552677f
--- /dev/null
+++ b/src/PhpSpreadsheet/Cell/StringValueBinder.php
@@ -0,0 +1,31 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Cell;
+
+use PhpOffice\PhpSpreadsheet\Shared\StringHelper;
+
+class StringValueBinder implements IValueBinder
+{
+    /**
+     * Bind value to a cell.
+     *
+     * @param Cell $cell Cell to bind value to
+     * @param mixed $value Value to bind in cell
+     *
+     * @throws \PhpOffice\PhpSpreadsheet\Exception
+     *
+     * @return bool
+     */
+    public function bindValue(Cell $cell, $value)
+    {
+        // sanitize UTF-8 strings
+        if (is_string($value)) {
+            $value = StringHelper::sanitizeUTF8($value);
+        }
+
+        $cell->setValueExplicit((string) $value, DataType::TYPE_STRING);
+
+        // Done!
+        return true;
+    }
+}