{"record":{"id":"780762b598f7d0b1","repo":"PHPOffice/PhpSpreadsheet","slug":"invalid-parameter-passed-formula","errorCode":null,"errorMessage":"Invalid parameter passed: formula","messagePattern":"Invalid parameter passed: formula","errorType":"exception","errorClass":"PhpOffice\\PhpSpreadsheet\\Calculation\\Exception","httpStatus":null,"severity":"error","filePath":"src/PhpSpreadsheet/Calculation/FormulaParser.php","lineNumber":71,"sourceCode":"    private string $formula;\n\n    /**\n     * Tokens.\n     *\n     * @var FormulaToken[]\n     */\n    private array $tokens = [];\n\n    /**\n     * Create a new FormulaParser.\n     *\n     * @param ?string $formula Formula to parse\n     */\n    public function __construct(?string $formula = '')\n    {\n        // Check parameters\n        if ($formula === null) {\n            throw new Exception('Invalid parameter passed: formula');\n        }\n\n        // Initialise values\n        $this->formula = trim($formula);\n        // Parse!\n        $this->parseToTokens();\n    }\n\n    /**\n     * Get Formula.\n     */\n    public function getFormula(): string\n    {\n        return $this->formula;\n    }\n\n    /**\n     * Get Token.","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/PHPOffice/PhpSpreadsheet/blob/65b080eef4d9fd11a5796135ab145883e5c3d6a6/src/PhpSpreadsheet/Calculation/FormulaParser.php#L53-L89","documentation":"FormulaParser's constructor rejects an explicit null formula with a plain Calculation\\Exception ('Invalid parameter passed: formula') - not an Excel error string, so it escapes as a real PHP exception. The ?string signature exists only so the '' default works; null is treated as a programming error. The parser tokenizes whatever string it gets, including non-formula text, so only null trips this guard.","triggerScenarios":"new FormulaParser(null); new FormulaParser($cell->getValue()) on a never-written cell (getValue() returns null); passing getOldCalculatedValue() which is null before the first calculation.","commonSituations":"Iterating a sheet and parsing whatever getValue() returns without checking the cell holds content; header/blank-row processing; import scripts over sparse sheets where many cells are untouched.","solutions":["Default the value: new FormulaParser($formula ?? '')","Skip cells with no content: if ($cell->getValue() === null) continue;","Skip non-formula cells explicitly: if (!$cell->isFormula()) continue;","Type-check before parsing: only construct the parser for non-empty strings"],"exampleFix":"// before\n$parser = new FormulaParser($sheet->getCell($coord)->getValue()); // throws on blank cell\n\n// after\n$formula = $sheet->getCell($coord)->getValue();\n$parser = new FormulaParser(is_string($formula) ? $formula : '');","handlingStrategy":"validation","validationCode":"$formula = $cell->getValue();\n$parser = new FormulaParser(is_string($formula) ? $formula : '');","typeGuard":"function isParseableFormula(mixed $value): bool\n{\n    return is_string($value);\n}","tryCatchPattern":"use PhpOffice\\PhpSpreadsheet\\Calculation\\Exception as CalcException;\n\ntry {\n    $parser = new FormulaParser($input ?? '');\n} catch (CalcException $e) {\n    // 'Invalid parameter passed: formula' - should be unreachable if null is defaulted\n}","preventionTips":["Never pass getValue() results to FormulaParser without a null/string check","Skip blank cells with $cell->getValue() === null before parsing","Use isFormula() to filter to actual formulas when rewriting"],"tags":["phpspreadsheet","php","excel","formula-parser","null-check","constructor"],"backgroundTag":"null-argument-rejected","analyzedSha":"65b080eef4d9fd11a5796135ab145883e5c3d6a6","analyzedAt":"2026-08-17T05:40:41.646Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}