PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Calculation\Exception

Invalid parameter passed: formula

Error message

Invalid parameter passed: formula

What it means

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.

Source

Thrown at src/PhpSpreadsheet/Calculation/FormulaParser.php:71

    private string $formula;

    /**
     * Tokens.
     *
     * @var FormulaToken[]
     */
    private array $tokens = [];

    /**
     * Create a new FormulaParser.
     *
     * @param ?string $formula Formula to parse
     */
    public function __construct(?string $formula = '')
    {
        // Check parameters
        if ($formula === null) {
            throw new Exception('Invalid parameter passed: formula');
        }

        // Initialise values
        $this->formula = trim($formula);
        // Parse!
        $this->parseToTokens();
    }

    /**
     * Get Formula.
     */
    public function getFormula(): string
    {
        return $this->formula;
    }

    /**
     * Get Token.

View on GitHub (pinned to 65b080eef4)

Solutions

  1. Default the value: new FormulaParser($formula ?? '')
  2. Skip cells with no content: if ($cell->getValue() === null) continue;
  3. Skip non-formula cells explicitly: if (!$cell->isFormula()) continue;
  4. Type-check before parsing: only construct the parser for non-empty strings

Example fix

// before
$parser = new FormulaParser($sheet->getCell($coord)->getValue()); // throws on blank cell

// after
$formula = $sheet->getCell($coord)->getValue();
$parser = new FormulaParser(is_string($formula) ? $formula : '');
Defensive patterns

Strategy: validation

Validate before calling

$formula = $cell->getValue();
$parser = new FormulaParser(is_string($formula) ? $formula : '');

Type guard

function isParseableFormula(mixed $value): bool
{
    return is_string($value);
}

Try / catch

use PhpOffice\PhpSpreadsheet\Calculation\Exception as CalcException;

try {
    $parser = new FormulaParser($input ?? '');
} catch (CalcException $e) {
    // 'Invalid parameter passed: formula' - should be unreachable if null is defaulted
}

Prevention

When it happens

Trigger: new FormulaParser(null); new FormulaParser($cell->getValue()) on a never-written cell (getValue() returns null); passing getOldCalculatedValue() which is null before the first calculation.

Common situations: 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.

Related errors

AI-assisted analysis of PHPOffice/PhpSpreadsheet@65b080eef4 (2026-08-17). Data as JSON: /api/errors/780762b598f7d0b1. Report an issue: GitHub.