Return an ExcelException object rather than a string to represent MS Excel formula errors

src/PhpSpreadsheet/Calculation/Calculation.php

@@ -216,7 +216,7 @@ class Calculation
      * Excel constant string translations to their PHP equivalents
      * Constant conversion from text name/value to actual (datatyped) value.
      *
-     * @var string[]
+     * @var mixed[]
      */
     private static $excelConstants = [
         'TRUE' => true,
@@ -3659,6 +3659,10 @@ private function showValue($value)
     private function showTypeDetails($value)
     {
         if ($this->debugLog->getWriteDebugLog()) {
+            if ($value instanceof ExcelException) {
+                return "an Excel {$value->errorName()} Error";
+            }
+
             $testArray = Functions::flattenArray($value);
             if (count($testArray) == 1) {
                 $value = array_pop($testArray);
@@ -3677,14 +3681,14 @@ private function showTypeDetails($value)
             } else {
                 if ($value == '') {
                     return 'an empty string';
-                } elseif ($value[0] == '#') {
-                    return 'a ' . $value . ' error';
                 }
                 $typeString = 'a string';
             }
 
             return $typeString . ' with a value of ' . $this->showValue($value);
         }
+
+        return null;
     }
 
     /**
@@ -4039,9 +4043,11 @@ private function internalParseFormula($formula, ?Cell $pCell = null)
                 $length = strlen($val);
                 if (preg_match('/^' . self::CALCULATION_REGEXP_FUNCTION . '$/miu', $val, $matches)) {
                     $val = preg_replace('/\s/u', '', $val);
+                    $reference = null;
                     if (isset(self::$phpSpreadsheetFunctions[strtoupper($matches[1])]) || isset(self::$controlFunctions[strtoupper($matches[1])])) {    // it's a function
                         $valToUpper = strtoupper($val);
                     } else {
+                        $reference = strtoupper($val);
                         $valToUpper = 'NAME.ERROR(';
                     }
                     // here $matches[1] will contain values like "IF"
@@ -4057,7 +4063,7 @@ private function internalParseFormula($formula, ?Cell $pCell = null)
                         }
                     }
 
-                    $stack->push('Function', $valToUpper, null, $currentCondition, $currentOnlyIf, $currentOnlyIfNot);
+                    $stack->push('Function', $valToUpper, $reference, $currentCondition, $currentOnlyIf, $currentOnlyIfNot);
                     // tests if the function is closed right after opening
                     $ax = preg_match('/^\s*\)/u', substr($formula, $index + $length));
                     if ($ax) {
@@ -4493,7 +4499,7 @@ private function processTokenStack($tokens, $cellID = null, ?Cell $pCell = null)
                                 $result = $matrixResult->getArray();
                             } catch (\Exception $ex) {
                                 $this->debugLog->writeDebugLog('JAMA Matrix Exception: ', $ex->getMessage());
-                                $result = '#VALUE!';
+                                $result = ExcelException::VALUE();
                             }
                         } else {
                             $result = self::FORMULA_STRING_QUOTE . str_replace('""', self::FORMULA_STRING_QUOTE, self::unwrapResult($operand1) . self::unwrapResult($operand2)) . self::FORMULA_STRING_QUOTE;
@@ -4551,7 +4557,7 @@ private function processTokenStack($tokens, $cellID = null, ?Cell $pCell = null)
                         $result = $matrixResult->getArray();
                     } catch (\Exception $ex) {
                         $this->debugLog->writeDebugLog('JAMA Matrix Exception: ', $ex->getMessage());
-                        $result = '#VALUE!';
+                        $result = ExcelException::VALUE();
                     }
                     $this->debugLog->writeDebugLog('Evaluation Result is ', $this->showTypeDetails($result));
                     $stack->push('Value', $result);
@@ -4769,6 +4775,13 @@ private function processTokenStack($tokens, $cellID = null, ?Cell $pCell = null)
 
     private function validateBinaryOperand(&$operand, &$stack)
     {
+        if ($operand instanceof ExcelException) {
+            $stack->push('Error', $operand);
+            $this->debugLog->writeDebugLog('Evaluation Result is ', $this->showTypeDetails($operand));
+
+            return false;
+        }
+
         if (is_array($operand)) {
             if ((count($operand, COUNT_RECURSIVE) - count($operand)) == 1) {
                 do {
@@ -4784,20 +4797,12 @@ private function validateBinaryOperand(&$operand, &$stack)
                 $operand = self::unwrapResult($operand);
             }
             //    If the string is a numeric value, we treat it as a numeric, so no further testing
-            if (!is_numeric($operand)) {
-                //    If not a numeric, test to see if the value is an Excel error, and so can't be used in normal binary operations
-                if ($operand > '' && $operand[0] == '#') {
-                    $stack->push('Value', $operand);
-                    $this->debugLog->writeDebugLog('Evaluation Result is ', $this->showTypeDetails($operand));
-
-                    return false;
-                } elseif (!Shared\StringHelper::convertToNumberIfFraction($operand)) {
-                    //    If not a numeric or a fraction, then it's a text string, and so can't be used in mathematical binary operations
-                    $stack->push('Error', '#VALUE!');
-                    $this->debugLog->writeDebugLog('Evaluation Result is a ', $this->showTypeDetails('#VALUE!'));
-
-                    return false;
-                }
+            if (!is_numeric($operand) && !Shared\StringHelper::convertToNumberIfFraction($operand)) {
+                //    If not a numeric or a fraction, then it's a text string, and so can't be used in mathematical binary operations
+                $stack->push('Error', ExcelException::VALUE());
+                $this->debugLog->writeDebugLog('Evaluation Result is a ', $this->showTypeDetails('#VALUE!'));
+
+                return false;
             }
         }
 
@@ -4992,7 +4997,7 @@ private function executeNumericBinaryOperation($operand1, $operand2, $operation,
                 $result = $matrixResult->getArray();
             } catch (\Exception $ex) {
                 $this->debugLog->writeDebugLog('JAMA Matrix Exception: ', $ex->getMessage());
-                $result = '#VALUE!';
+                $result = ExcelException::VALUE();
             }
         } else {
             if (
@@ -5023,7 +5028,7 @@ private function executeNumericBinaryOperation($operand1, $operand2, $operation,
                     case '/':
                         if ($operand2 == 0) {
                             //    Trap for Divide by Zero error
-                            $stack->push('Error', '#DIV/0!');
+                            $stack->push('Error', ExcelException::DIV0());
                             $this->debugLog->writeDebugLog('Evaluation Result is ', $this->showTypeDetails('#DIV/0!'));
 
                             return false;

src/PhpSpreadsheet/Calculation/Database.php

@@ -145,7 +145,7 @@ private static function getFilteredColumn($database, $field, $criteria)
      *                                        the column label in which you specify a condition for the
      *                                        column.
      *
-     * @return float|string
+     * @return ExcelException|float
      */
     public static function DAVERAGE($database, $field, $criteria)
     {