Add support for reading and writing formulas

Author: Alkarex

README.md

@@ -3,18 +3,22 @@
 PHP library to make basic but fast read & write operations on existing Excel workbooks.
 
 It handles XLSX/XLSM documents (Microsoft Excel 2007+, Office Open XML Workbook) using fast and simple low-level ZIP & XML manipulations,
-without requiring any library dependency.
+without requiring any library dependency, while minimising unintended side-effects.
 
 ## Rationale
 
-If you need advanced manipulation of Excel documents such as working with formulas and styles,
+If you need advanced manipulation of Excel documents such as working with styles,
 check the [PhpSpreadsheet](https://github.com/PHPOffice/PhpSpreadsheet) library
 (previously [PHPExcel](https://github.com/PHPOffice/PHPExcel/)),
-but for simply reading & writing basic values from existing Excel workbooks, `PhpSpreadsheet` is over an order of magnitude too slow.
+but for simply reading & writing basic values from existing Excel workbooks, `PhpSpreadsheet` is over an order of magnitude too slow,
+and has the risk of breaking some unsupported Excel features such as notes.
 
 There are also libraries to create new Excel documents from scratch, or for just reading some values, but not any obvious one for editing.
 
-`php-xlsx-fast-editor` addresses the need of quickly reading & writing & editing existing Excel documents.
+`php-xlsx-fast-editor` addresses the need of quickly reading & writing & editing existing Excel documents,
+while reducing the risk of breaking anything.
+
+Note that to create a new document, you can just provide a blank Excel document as input.
 
 ## Use
 
@@ -43,13 +47,15 @@ $xlsxFastEditor = new XlsxFastEditor('test.xlsx');
 $worksheetId1 = $xlsxFastEditor->getWorksheetNumber('Sheet1');
 $worksheetId2 = $xlsxFastEditor->getWorksheetNumber('Sheet2');
 
+$fx = $xlsxFastEditor->readFormula($worksheetId1, 'A1');
 $f = $xlsxFastEditor->readFloat($worksheetId1, 'B2');
 $i = $xlsxFastEditor->readInt($worksheetId1, 'C3');
 $s = $xlsxFastEditor->readString($worksheetId2, 'D4');
 
 // If you want to force Excel to recalculate formulas on next load:
 $xlsxFastEditor->setFullCalcOnLoad($worksheetId2, true);
 
+$xlsxFastEditor->writeFormula($worksheetId1, 'A1', '=B2*3');
 $xlsxFastEditor->writeFloat($worksheetId1, 'B2', 3.14);
 $xlsxFastEditor->writeInt($worksheetId1, 'C3', 13);
 $xlsxFastEditor->writeString($worksheetId2, 'D4', 'Hello');

src/XlsxFastEditor.php

@@ -157,12 +157,12 @@ private function getDomFromPath(string $path): \DOMDocument
 	}
 
 	/**
-	 * Access the DOMElement representing a cell value `<v>` in the worksheet.
+	 * Access the DOMElement representing a cell formula `<f>` in the worksheet.
 	 *
 	 * @param int $sheetNumber Worksheet number (base 1)
 	 * @param $cellName Cell name such as `B4`
 	 */
-	private function getV(int $sheetNumber, string $cellName): ?\DOMElement
+	private function getF(int $sheetNumber, string $cellName): ?\DOMElement
 	{
 		if (!ctype_alnum($cellName)) {
 			throw new XlsxFastEditorInputException("Invalid cell reference {$cellName}! ");
@@ -173,11 +173,49 @@ private function getV(int $sheetNumber, string $cellName): ?\DOMElement
 		$xpath = new \DOMXPath($dom);
 		$xpath->registerNamespace('o', self::OXML_NAMESPACE);
 
+		$f = null;
+		$fs = $xpath->query("(//o:c[@r='$cellName'])[1]/o:f");
+		if ($fs !== false && $fs->length > 0) {
+			$f = $fs[0];
+			if (!($f instanceof \DOMElement)) {
+				throw new XlsxFastEditorXmlException("Error querying XML fragment for cell formula {$sheetNumber}/{$cellName}!");
+			}
+		}
+		return $f;
+	}
+
+	/**
+	 * Read a formula in the given worksheet at the given cell location.
+	 *
+	 * @param int $sheetNumber Worksheet number (base 1)
+	 * @param $cellName Cell name such as `B4`
+	 */
+	public function readFormula(int $sheetNumber, string $cellName): ?string
+	{
+		$f = $this->getF($sheetNumber, $cellName);
+		if ($f === null || !is_string($f->nodeValue) || $f->nodeValue === '') {
+			return null;
+		}
+		return '=' . $f->nodeValue;
+	}
+
+	/**
+	 * Access the DOMElement representing a cell value `<v>` in the worksheet.
+	 *
+	 * @param int $sheetNumber Worksheet number (base 1)
+	 * @param $cellName Cell name such as `B4`
+	 */
+	private function getV(int $sheetNumber, string $cellName): ?\DOMElement
+	{
 		if (!ctype_alnum($cellName)) {
 			throw new XlsxFastEditorInputException("Invalid cell reference {$cellName}! ");
 		}
 		$cellName = strtoupper($cellName);
 
+		$dom = $this->getDomFromPath(self::getWorksheetPath($sheetNumber));
+		$xpath = new \DOMXPath($dom);
+		$xpath->registerNamespace('o', self::OXML_NAMESPACE);
+
 		$v = null;
 		$vs = $xpath->query("(//o:c[@r='$cellName'])[1]/o:v");
 		if ($vs !== false && $vs->length > 0) {
@@ -438,6 +476,49 @@ private function initCellValue(\DOMElement $c): \DOMElement
 		return $v;
 	}
 
+	/**
+	 * Write a formulat in the given worksheet at the given cell location, without changing the type/style of the cell.
+	 * Removes the formulas of the cell, if any.
+	 *
+	 * @param int $sheetNumber Worksheet number (base 1)
+	 * @param $cellName Cell name such as `B4`
+	 */
+	public function writeFormula(int $sheetNumber, string $cellName, string $value): void
+	{
+		$c = $this->getCell($sheetNumber, $cellName, true);
+		if ($c === null) {
+			throw new XlsxFastEditorInputException("Internal error accessing cell {$sheetNumber}/{$cellName}!");
+		}
+
+		$value = ltrim($value, '=');
+
+		$vs = $c->getElementsByTagName('v');
+		for ($i = $vs->length - 1; $i >= 0; $i--) {
+			$v = $vs[$i];
+			if ($v instanceof \DOMElement) {
+				$c->removeChild($v);
+			}
+		}
+
+		$fs = $c->getElementsByTagName('f');
+		for ($i = $fs->length - 1; $i >= 0; $i--) {
+			$f = $fs[$i];
+			if ($f instanceof \DOMElement) {
+				$c->removeChild($f);
+			}
+		}
+
+		$dom = $c->ownerDocument;
+		if ($dom === null) {
+			throw new XlsxFastEditorInputException("Internal error accessing cell {$sheetNumber}/{$cellName}!");
+		}
+		$f = $dom->createElement('f', $value);
+		$c->appendChild($f);
+
+		$this->mustClearCalcChain = true;
+		$this->touchWorksheet($sheetNumber);
+	}
+
 	/**
 	 * Write a number in the given worksheet at the given cell location, without changing the type/style of the cell.
 	 * Removes the formulas of the cell, if any.

tests/test.php

@@ -18,36 +18,41 @@
 
 assert($xlsxFastEditor->readFloat($sheet1, 'D2') === 3.14159);
 assert($xlsxFastEditor->readFloat($sheet1, 'D4') === -1.0);
-assert($xlsxFastEditor->readFloat($sheet1, 'E5') === null);
+assert($xlsxFastEditor->readFloat($sheet1, 'e5') === null);
 assert($xlsxFastEditor->readInt($sheet1, 'c3') === -5);
 assert($xlsxFastEditor->readInt($sheet1, 'F6') === null);
-assert($xlsxFastEditor->readString($sheet1, 'B4') === 'naïveté');
+assert($xlsxFastEditor->readString($sheet1, 'b4') === 'naïveté');
 assert($xlsxFastEditor->readString($sheet1, 'F7') === null);
 
 $sheet2 = $xlsxFastEditor->getWorksheetNumber('Sheet2');
 assert($sheet2 === 2);
 
+assert($xlsxFastEditor->readFormula($sheet2, 'c2') === '=Sheet1!C2*2');
 assert($xlsxFastEditor->readFloat($sheet2, 'D2') === 3.14159 * 2);
 assert($xlsxFastEditor->readFloat($sheet2, 'D4') === -1.0 * 2);
 assert($xlsxFastEditor->readInt($sheet2, 'c3') === -5 * 2);
 assert($xlsxFastEditor->readString($sheet2, 'B3') === 'déjà-vu');
 
 // Existing cells
-$xlsxFastEditor->writeString($sheet1, 'B4', 'α');
-$xlsxFastEditor->writeInt($sheet1, 'C4', 15);
-$xlsxFastEditor->writeFloat($sheet1, 'D4', -66.6);
+$xlsxFastEditor->writeFormula($sheet1, 'c2', '=2*3');
+$xlsxFastEditor->writeString($sheet1, 'b4', 'α');
+$xlsxFastEditor->writeInt($sheet1, 'c4', 15);
+$xlsxFastEditor->writeFloat($sheet1, 'd4', -66.6);
 
 // Existing cells with formulas
+$xlsxFastEditor->writeFormula($sheet2, 'c2', '=Sheet1!C2*3');
 $xlsxFastEditor->writeString($sheet2, 'B3', 'β');
 $xlsxFastEditor->writeInt($sheet2, 'C3', -7);
 $xlsxFastEditor->writeFloat($sheet2, 'D3', 273.15);
 
 // Non-existing cells but existing lines
+$xlsxFastEditor->writeFormula($sheet2, 'I2', '=7*3');
 $xlsxFastEditor->writeString($sheet2, 'F2', 'γ');
 $xlsxFastEditor->writeInt($sheet2, 'G3', -7);
 $xlsxFastEditor->writeFloat($sheet2, 'H4', 273.15);
 
 // Non-existing lines
+$xlsxFastEditor->writeFormula($sheet2, 'E11', '=7*5');
 $xlsxFastEditor->writeString($sheet2, 'B10', 'δ');
 $xlsxFastEditor->writeInt($sheet2, 'C9', 13);
 $xlsxFastEditor->writeFloat($sheet2, 'D10', -273.15);
@@ -58,18 +63,22 @@
 
 $xlsxFastEditor = new XlsxFastEditor(__DIR__ . '/copy.xlsx');
 
+assert($xlsxFastEditor->readFormula($sheet1, 'c2') === '=2*3');
 assert($xlsxFastEditor->readString($sheet1, 'B4') === 'α');
 assert($xlsxFastEditor->readInt($sheet1, 'C4') === 15);
 assert($xlsxFastEditor->readFloat($sheet1, 'D4') === -66.6);
 
+assert($xlsxFastEditor->readFormula($sheet2, 'c2') === '=Sheet1!C2*3');
 assert($xlsxFastEditor->readString($sheet2, 'B3') === 'β');
 assert($xlsxFastEditor->readInt($sheet2, 'C3') === -7);
 assert($xlsxFastEditor->readFloat($sheet2, 'D3') === 273.15);
 
+assert($xlsxFastEditor->readFormula($sheet2, 'I2') === '=7*3');
 assert($xlsxFastEditor->readString($sheet2, 'F2') === 'γ');
 assert($xlsxFastEditor->readInt($sheet2, 'G3') === -7);
 assert($xlsxFastEditor->readFloat($sheet2, 'H4') === 273.15);
 
+assert($xlsxFastEditor->readFormula($sheet2, 'E11') === '=7*5');
 assert($xlsxFastEditor->readString($sheet2, 'B10') === 'δ');
 assert($xlsxFastEditor->readInt($sheet2, 'C9') === 13);
 assert($xlsxFastEditor->readFloat($sheet2, 'D10') === -273.15);