{"record":{"id":"4a83d7eed1844711","repo":"PHPOffice/PhpSpreadsheet","slug":"column-references-should-not-be-numeric","errorCode":null,"errorMessage":"Column references should not be numeric.","messagePattern":"Column references should not be numeric\\.","errorType":"exception","errorClass":"PhpOffice\\PhpSpreadsheet\\Exception","httpStatus":null,"severity":"error","filePath":"src/PhpSpreadsheet/Worksheet/Worksheet.php","lineNumber":2562,"sourceCode":"\n        return $this;\n    }\n\n    /**\n     * Insert a new column, updating all possible related data.\n     *\n     * @param string $before Insert before this column Name, eg: 'A'\n     * @param int $numberOfColumns Number of new columns to insert\n     *\n     * @return $this\n     */\n    public function insertNewColumnBefore(string $before, int $numberOfColumns = 1): static\n    {\n        if (!is_numeric($before)) {\n            $objReferenceHelper = ReferenceHelper::getInstance();\n            $objReferenceHelper->insertNewBefore($before . '1', $numberOfColumns, 0, $this);\n        } else {\n            throw new Exception('Column references should not be numeric.');\n        }\n\n        return $this;\n    }\n\n    /**\n     * Insert a new column, updating all possible related data.\n     *\n     * @param int $beforeColumnIndex Insert before this column ID (numeric column coordinate of the cell)\n     * @param int $numberOfColumns Number of new columns to insert\n     *\n     * @return $this\n     */\n    public function insertNewColumnBeforeByIndex(int $beforeColumnIndex, int $numberOfColumns = 1): static\n    {\n        if ($beforeColumnIndex >= 1) {\n            return $this->insertNewColumnBefore(Coordinate::stringFromColumnIndex($beforeColumnIndex), $numberOfColumns);\n        }","sourceCodeStart":2544,"sourceCodeEnd":2580,"githubUrl":"https://github.com/PHPOffice/PhpSpreadsheet/blob/65b080eef4d9fd11a5796135ab145883e5c3d6a6/src/PhpSpreadsheet/Worksheet/Worksheet.php#L2544-L2580","documentation":"insertNewColumnBefore(string $before, int $numberOfColumns = 1) expects a column letter string such as 'B' or 'AC'. The is_numeric() check deliberately rejects numeric strings like '3', because they would otherwise be treated as an unintended (and valid-looking) column name; the numeric counterpart is insertNewColumnBeforeByIndex().","triggerScenarios":"insertNewColumnBefore('2'); insertNewColumnBefore((string) $columnNumber) after computing a numeric index with Coordinate::columnIndexFromString() or a loop counter and forgetting to convert it back to letters.","commonSituations":"Mixed bookkeeping where columns are tracked as integers for range math but passed to the string-based API; (string) casts of ints to satisfy the string type; user-supplied 'column number' input forwarded unchanged.","solutions":["Use the numeric API: $sheet->insertNewColumnBeforeByIndex($index, $count).","Or convert first: Coordinate::stringFromColumnIndex($index) maps 1 to 'A'.","Standardize on one representation (letters or indexes) per code path and convert only at the API boundary."],"exampleFix":"// before\n$colIndex = 4;\n$sheet->insertNewColumnBefore((string) $colIndex); // throws: numeric\n\n// after\n$sheet->insertNewColumnBeforeByIndex($colIndex);\n// or\n$sheet->insertNewColumnBefore(Coordinate::stringFromColumnIndex($colIndex)); // 'D'","handlingStrategy":"type-guard","validationCode":"use PhpOffice\\PhpSpreadsheet\\Cell\\Coordinate;\n\n$column = is_int($columnInput)\n    ? Coordinate::stringFromColumnIndex($columnInput)\n    : $columnInput;\n$sheet->insertNewColumnBefore($column, 2);","typeGuard":"/** Column letters only: 'A'..'Z', 'AA'..; no digits, no '$'. */\nfunction isColumnLetter(string $column): bool\n{\n    return $column !== '' && ctype_alpha($column);\n}","tryCatchPattern":null,"preventionTips":["Pick one column representation per code path; convert with Coordinate::stringFromColumnIndex/columnIndexFromString only at the API boundary.","Use the ...ByIndex methods when your data is numeric.","Never cast an int to string just to satisfy a string parameter."],"tags":["phpspreadsheet","worksheet","insert-column","column-reference","argument-validation"],"backgroundTag":"invalid-column-reference","analyzedSha":"65b080eef4d9fd11a5796135ab145883e5c3d6a6","analyzedAt":"2026-08-17T05:40:41.646Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}