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

@@ -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,

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);
+}

samples/Reader/sampleData/longIntegers.csv

@@ -0,0 +1,6 @@
+"Column 1","Column 2"
+123456789012345678901234,234567890123456789012345
+345678901234567890123456,456789012345678901234567
+567890123456789012345678,678901234567890123456789
+789012345678901234567890,890123456789012345678901
+901234567890123456789012,012345678901234567890123

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)

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)

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;
+    }
+}