Better typing of exceptions

Author: Alkarex

README.md

@@ -89,7 +89,7 @@ try {
 
 	// Navigation methods for existing cells
 	$cell = $row->getFirstCell();
-	$cell = $row->getCell('D4');
+	$cell = $row->getCellOrNull('D4');
 	$cell = $cell->getPreviousCell();
 	$cell = $cell->getNextCell();
 	$cell = $row->getLastCell();

phpstan.neon

@@ -22,5 +22,10 @@ parameters:
 		strictCalls: true
 		switchConditionsMatchingType: true
 		uselessCast: true
+	exceptions:
+		check:
+			missingCheckedExceptionInThrows: true
+			tooWideThrowType: true
+		implicitThrows: false
 includes:
 	- vendor/phpstan/phpstan-strict-rules/rules.neon

src/XlsxFastEditor.php

@@ -22,12 +22,15 @@ public function __construct(XlsxFastEditor $editor, int $sheetNumber, \DOMElemen
 		$this->c = $c;
 	}
 
+	/**
+	 * @throws XlsxFastEditorXmlException
+	 */
 	private function getXPath(): \DOMXPath
 	{
 		if ($this->xpath === null) {
 			$dom = $this->c->ownerDocument;
 			if ($dom === null) {
-				throw new XlsxFastEditorInputException("Internal error accessing cell {$this->name()}!");
+				throw new XlsxFastEditorXmlException("Internal error accessing cell {$this->name()}!");
 			}
 			$xpath = new \DOMXPath($dom);
 			$xpath->registerNamespace('o', XlsxFastEditor::_OXML_NAMESPACE);
@@ -47,6 +50,7 @@ public function name(): string
 
 	/**
 	 * Column name (e.g., `'D'`).
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function column(): string
 	{
@@ -88,6 +92,7 @@ public function getNextCell(): ?XlsxFastEditorCell
 
 	/**
 	 * Access the parent row of the cell.
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function getRow(): XlsxFastEditorRow
 	{
@@ -100,6 +105,7 @@ public function getRow(): XlsxFastEditorRow
 
 	/**
 	 * Read a formula in the given worksheet at the given cell location.
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function readFormula(): ?string
 	{
@@ -119,10 +125,9 @@ private function value(): ?string
 		$vs = $this->c->getElementsByTagName('v');
 		if ($vs->length > 0) {
 			$v = $vs[0];
-			if (!($v instanceof \DOMElement)) {
-				throw new XlsxFastEditorXmlException("Error querying XML value for cell {$this->name()}!");
+			if ($v instanceof \DOMElement) {
+				return $v->nodeValue;
 			}
-			return $v->nodeValue;
 		}
 		return null;
 	}
@@ -141,14 +146,21 @@ public function readFloat(): ?float
 
 	/**
 	 * Read the date/time value of the cell, if any.
+	 * @throws XlsxFastEditorFileFormatException
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function readDateTime(): ?\DateTimeImmutable
 	{
 		$value = $this->readFloat();
 		if ($value === null) {
 			return null;
 		}
-		return XlsxFastEditor::excelDateToDateTime($value, $this->editor->getWorkbookDateSystem());
+		try {
+			return XlsxFastEditor::excelDateToDateTime($value, $this->editor->getWorkbookDateSystem());
+		} catch (\InvalidArgumentException $iaex) {
+			// Never happens
+			return null;
+		}
 	}
 
 	/**
@@ -166,6 +178,8 @@ public function readInt(): ?int
 	/**
 	 * Read the string value of the cell,
 	 * compatible with the shared string approach.
+	 * @throws XlsxFastEditorFileFormatException
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function readString(): ?string
 	{
@@ -188,6 +202,8 @@ public function readString(): ?string
 
 	/**
 	 * Read the hyperlink value of the cell, if any.
+	 * @throws XlsxFastEditorFileFormatException
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function readHyperlink(): ?string
 	{
@@ -196,12 +212,17 @@ public function readHyperlink(): ?string
 		if (!is_string($rid) || $rid === '') {
 			return null;
 		}
-		return $this->editor->_getHyperlink($this->sheetNumber, $rid);
+		try {
+			return $this->editor->_getHyperlink($this->sheetNumber, $rid);
+		} catch (\InvalidArgumentException $iax) {
+			throw new XlsxFastEditorXmlException("Error querying XML fragment for hyperlink in cell {$this->name()}!", $iax->getCode(), $iax);
+		}
 	}
 
 	/**
 	 * Clean the cell to have its value written.
 	 * @return \DOMElement The `<v>` value element of the provided cell, or null in case of error.
+	 * @throws XlsxFastEditorXmlException
 	 */
 	private function initCellValue(): \DOMElement
 	{
@@ -224,9 +245,13 @@ private function initCellValue(): \DOMElement
 		}
 		if ($v === null) {
 			// There was no existing <v>
-			$v = $this->c->ownerDocument === null ? null : $this->c->ownerDocument->createElement('v');
+			try {
+				$v = $this->c->ownerDocument === null ? null : $this->c->ownerDocument->createElement('v');
+			} catch (\DOMException $dex) {
+				throw new XlsxFastEditorXmlException("Error creating value for cell {$this->name()}!", $dex->code, $dex);
+			}
 			if ($v == false) {
-				throw new XlsxFastEditorXmlException('Error creating value for cell!');
+				throw new XlsxFastEditorXmlException("Error creating value for cell {$this->name()}!");
 			}
 			$this->c->appendChild($v);
 		}
@@ -237,6 +262,7 @@ private function initCellValue(): \DOMElement
 	/**
 	 * Write a formulat, without changing the type/style of the cell.
 	 * Removes the formulas of the cell, if any.
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function writeFormula(string $value): void
 	{
@@ -260,9 +286,13 @@ public function writeFormula(string $value): void
 
 		$dom = $this->c->ownerDocument;
 		if ($dom === null) {
-			throw new XlsxFastEditorInputException("Internal error accessing cell {$this->name()}!");
+			throw new XlsxFastEditorXmlException("Internal error accessing cell {$this->name()}!");
+		}
+		try {
+			$f = $dom->createElement('f', $value);
+		} catch (\DOMException $dex) {
+			throw new XlsxFastEditorXmlException("Error creating formulat for cell {$this->name()}!", $dex->code, $dex);
 		}
-		$f = $dom->createElement('f', $value);
 		$this->c->appendChild($f);
 
 		$this->editor->_clearCalcChain();
@@ -272,8 +302,8 @@ public function writeFormula(string $value): void
 	/**
 	 * Write a number, without changing the type/style of the cell.
 	 * Removes the formulas of the cell, if any.
-	 *
 	 * @param int|float $value
+	 * @throws XlsxFastEditorXmlException
 	 */
 	private function writeNumber($value): void
 	{
@@ -286,6 +316,7 @@ private function writeNumber($value): void
 	 * Write a float, without changing the type/style of the cell.
 	 * Removes the formulas of the cell, if any.
 	 * @param float $value
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function writeFloat(float $value): void
 	{
@@ -296,6 +327,7 @@ public function writeFloat(float $value): void
 	 * Write an integer, without changing the type/style of the cell.
 	 * Removes the formulas of the cell, if any.
 	 * @param int $value
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function writeInt(int $value): void
 	{
@@ -305,6 +337,8 @@ public function writeInt(int $value): void
 	/**
 	 * Write a string, without changing the type/style of the cell.
 	 * Removes the formulas of the cell, if any.
+	 * @throws XlsxFastEditorFileFormatException
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function writeString(string $value): void
 	{
@@ -319,6 +353,8 @@ public function writeString(string $value): void
 	 * Replace the hyperlink of the cell, if that cell already has an hyperlink.
 	 * Warning: does not support the creation of a new hyperlink.
 	 * @return bool True if the hyperlink could be replaced, false otherwise.
+	 * @throws XlsxFastEditorFileFormatException
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function writeHyperlink(string $value): bool
 	{
@@ -327,6 +363,10 @@ public function writeHyperlink(string $value): bool
 		if (!is_string($rId) || $rId === '') {
 			return false;
 		}
-		return $this->editor->_setHyperlink($this->sheetNumber, $rId, $value);
+		try {
+			return $this->editor->_setHyperlink($this->sheetNumber, $rId, $value);
+		} catch (\InvalidArgumentException $iax) {
+			throw new XlsxFastEditorXmlException("Error querying XML fragment for hyperlink in cell {$this->name()}!", $iax->getCode(), $iax);
+		}
 	}
 }

src/XlsxFastEditorCell.php

@@ -3,7 +3,7 @@
 namespace alexandrainst\XlsxFastEditor;
 
 /**
- * Errors related to invalid user inputs.
+ * Errors related to user inputs such as accessing unexisting cells.
  */
 final class XlsxFastEditorInputException extends \Exception
 {

src/XlsxFastEditorInputException.php

@@ -31,12 +31,15 @@ public function number(): int
 		return (int)$this->r->getAttribute('r');
 	}
 
+	/**
+	 * @throws XlsxFastEditorXmlException
+	 */
 	private function getXPath(): \DOMXPath
 	{
 		if ($this->xpath === null) {
 			$dom = $this->r->ownerDocument;
 			if ($dom === null) {
-				throw new XlsxFastEditorInputException("Internal error accessing row {$this->number()}!");
+				throw new XlsxFastEditorXmlException("Internal error accessing row {$this->number()}!");
 			}
 			$xpath = new \DOMXPath($dom);
 			$xpath->registerNamespace('o', XlsxFastEditor::_OXML_NAMESPACE);
@@ -115,9 +118,16 @@ public function getFirstCell(): ?XlsxFastEditorCell
 	 * set to `XlsxFastEditor::ACCESS_MODE_AUTOCREATE` to auto-create the cell.
 	 * @return XlsxFastEditorCell|null A cell, potentially `null` if the cell does not exist and `$accessMode` is set to `XlsxFastEditor::ACCESS_MODE_NULL`
 	 * @phpstan-return ($accessMode is XlsxFastEditor::ACCESS_MODE_NULL ? XlsxFastEditorCell|null : XlsxFastEditorCell)
+	 * @internal
+	 * @throws \InvalidArgumentException if `$cellName` has an invalid format
+	 * @throws XlsxFastEditorInputException optionally if the corresponding cell does not exist, depending on choice of `$accessMode`
+	 * @throws XlsxFastEditorXmlException
 	 */
 	public function getCell(string $cellName, int $accessMode = XlsxFastEditor::ACCESS_MODE_NULL): ?XlsxFastEditorCell
 	{
+		if (!ctype_alnum($cellName)) {
+			throw new \InvalidArgumentException("Invalid cell reference {$cellName}!");
+		}
 		$xpath = $this->getXPath();
 		$cs = $xpath->query("./o:c[@r='$cellName'][1]", $this->r);
 		$c = null;
@@ -131,7 +141,11 @@ public function getCell(string $cellName, int $accessMode = XlsxFastEditor::ACCE
 		if ($c === null && $accessMode === XlsxFastEditor::ACCESS_MODE_AUTOCREATE) {
 			// The cell <c> was not found
 			$dom = $xpath->document;
-			$c = $dom->createElement('c');
+			try {
+				$c = $dom->createElement('c');
+			} catch (\DOMException $dex) {
+				throw new XlsxFastEditorXmlException("Error creating cell {$this->sheetNumber}/{$cellName}!", $dex->code, $dex);
+			}
 			if ($c === false) {
 				throw new XlsxFastEditorXmlException("Error creating cell {$this->sheetNumber}/{$cellName}!");
 			}
@@ -155,6 +169,40 @@ public function getCell(string $cellName, int $accessMode = XlsxFastEditor::ACCE
 		return new XlsxFastEditorCell($this->editor, $this->sheetNumber, $c);
 	}
 
+	/**
+	 * Get the cell of the given name, or null if if does not exist.
+	 * @param $cellName Cell name such as `B4`
+	 * @return XlsxFastEditorCell|null A cell, potentially `null` if the cell does not exist
+	 * @throws \InvalidArgumentException if `$cellName` has an invalid format
+	 * @throws XlsxFastEditorXmlException
+	 */
+	public function getCellOrNull(string $cellName): ?XlsxFastEditorCell
+	{
+		try {
+			return $this->getCell($cellName, XlsxFastEditor::ACCESS_MODE_NULL);
+		} catch (XlsxFastEditorInputException $iex) {
+			// Will not happen
+			return null;
+		}
+	}
+
+	/**
+	 * Get the cell of the given name, or autocreate it if it does not already exist.
+	 * @param $cellName Cell name such as `B4`
+	 * @return XlsxFastEditorCell A cell
+	 * @throws \InvalidArgumentException if `$cellName` has an invalid format
+	 * @throws XlsxFastEditorXmlException
+	 */
+	public function getCellAutocreate(string $cellName): XlsxFastEditorCell
+	{
+		try {
+			return $this->getCell($cellName, XlsxFastEditor::ACCESS_MODE_AUTOCREATE);
+		} catch (XlsxFastEditorInputException $iex) {
+			// Will not happen
+			throw new XlsxFastEditorXmlException('Internal error with getCell!', $iex->getCode(), $iex);
+		}
+	}
+
 	/**
 	 * Get the last existing cell for a given line.
 	 * @return XlsxFastEditorCell|null The last cell of the given line if it exists, null otherwise.

src/XlsxFastEditorRow.php

@@ -3,7 +3,7 @@
 namespace alexandrainst\XlsxFastEditor;
 
 /**
- * Errors related to XML manipulation.
+ * Errors related to XML manipulation, indicating that the XLSX document is internally damaged.
  */
 final class XlsxFastEditorXmlException extends XlsxFastEditorException
 {

src/XlsxFastEditorXmlException.php

@@ -3,7 +3,7 @@
 namespace alexandrainst\XlsxFastEditor;
 
 /**
- * Errors related to ZIP operations.
+ * Errors related to ZIP operations, indicating that the external structure of the XLSX document is damaged or with invalid disc access rights.
  * Returns error codes from https://php.net/ziparchive.open
  */
 final class XlsxFastEditorZipException extends XlsxFastEditorException

src/XlsxFastEditorZipException.php

@@ -60,7 +60,7 @@
 	assert($xlsxFastEditor->getRow($sheet1, 1)?->getFirstCell()?->name() === 'A1');
 	assert($xlsxFastEditor->getRow($sheet1, 2)?->number() === 2);
 	assert($xlsxFastEditor->getRow($sheet1, 3)?->getLastCell()?->name() === 'F3');
-	assert($xlsxFastEditor->getRow($sheet1, 4)?->getCell('D4')?->name() === 'D4');
+	assert($xlsxFastEditor->getRow($sheet1, 4)?->getCellOrNull('D4')?->name() === 'D4');
 	assert($xlsxFastEditor->getLastRow($sheet1)?->number() === 4);
 
 	assert(XlsxFastEditor::cellOrderCompare('B3', 'AA23') < 0);