{"record":{"id":"39c394e6c93b1553","repo":"PHPOffice/PhpSpreadsheet","slug":"invalid-a1-format-cell-reference","errorCode":null,"errorMessage":"Invalid A1-format Cell Reference","messagePattern":"Invalid A1-format Cell Reference","errorType":"exception","errorClass":"PhpOffice\\PhpSpreadsheet\\Exception","httpStatus":null,"severity":"error","filePath":"src/PhpSpreadsheet/Cell/AddressHelper.php","lineNumber":140,"sourceCode":"            }\n        }\n        unset($value);\n\n        //    Then rebuild the formula string\n        return implode('\"', $temp);\n    }\n\n    /**\n     * Converts an A1 format cell address to an R1C1 format cell address.\n     * If $currentRowNumber or $currentColumnNumber are provided, then the R1C1 address will be formatted as a relative address.\n     */\n    public static function convertToR1C1(\n        string $address,\n        ?int $currentRowNumber = null,\n        ?int $currentColumnNumber = null\n    ): string {\n        if (1 !== preg_match(Coordinate::A1_COORDINATE_REGEX, $address, $cellReference)) {\n            throw new Exception('Invalid A1-format Cell Reference');\n        }\n\n        if ($cellReference['col'][0] === '$') {\n            // Column must be absolute address\n            $currentColumnNumber = null;\n        }\n        $columnId = Coordinate::columnIndexFromString(ltrim($cellReference['col'], '$'));\n\n        if ($cellReference['row'][0] === '$') {\n            // Row must be absolute address\n            $currentRowNumber = null;\n        }\n        $rowId = (int) ltrim($cellReference['row'], '$');\n\n        if ($currentRowNumber !== null) {\n            if ($rowId === $currentRowNumber) {\n                $rowId = '';\n            } else {","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/PHPOffice/PhpSpreadsheet/blob/65b080eef4d9fd11a5796135ab145883e5c3d6a6/src/PhpSpreadsheet/Cell/AddressHelper.php#L122-L158","documentation":"Cell\\AddressHelper::convertToR1C1() first validates the input against Coordinate::A1_COORDINATE_REGEX (optionally $-absolute like '$B$3'). Anything that is not a single A1 cell address - a range ('A1:B2'), a bare column ('A'), reversed garbage ('1A'), a defined name, an empty string - throws PhpOffice\\PhpSpreadsheet\\Exception 'Invalid A1-format Cell Reference'.","triggerScenarios":"AddressHelper::convertToR1C1('A1:B2') (range instead of single cell); convertToR1C1('1A') or convertToR1C1('AB') or convertToR1C1(''); passing an R1C1 string ('R2C3') by mistake; defined names or sheet-qualified refs ('Sheet1!A1') reaching the function unsplit.","commonSituations":"Converting addresses from user input or CSV columns without normalizing; looping over extracted range strings instead of their individual cells; forgetting to strip sheet prefixes before conversion; direction confusion between the two converters.","solutions":["Validate first with the same rule the library uses: preg_match(Coordinate::A1_COORDINATE_REGEX, $address)","Split ranges into cell pairs via Coordinate::extractAllCellReferencesInRange() and convert each cell","Strip sheet-qualified prefixes ('Sheet1!A1' -> 'A1') and trim whitespace/$ handling before converting","Wrap in try/catch PhpOffice\\PhpSpreadsheet\\Exception and reject bad addresses explicitly"],"exampleFix":"// before\nforeach (['A1:B2', 'C3'] as $a) { AddressHelper::convertToR1C1($a); } // 'A1:B2' throws\n\n// after\nuse PhpOffice\\PhpSpreadsheet\\Cell\\Coordinate;\nforeach (['A1:B2', 'C3'] as $a) {\n    foreach (Coordinate::extractAllCellReferencesInRange($a) as $cell) {\n        $r1c1 = AddressHelper::convertToR1C1($cell);\n    }\n}","handlingStrategy":"validation","validationCode":"use PhpOffice\\PhpSpreadsheet\\Cell\\Coordinate;\n\nif (!preg_match(Coordinate::A1_COORDINATE_REGEX, $address)) {\n    throw new InvalidArgumentException(\"not a single A1 address: $address\");\n}\n$r1c1 = AddressHelper::convertToR1C1($address);","typeGuard":"function isSingleA1Address(string $s): bool\n{\n    return (bool) preg_match(\\PhpOffice\\PhpSpreadsheet\\Cell\\Coordinate::A1_COORDINATE_REGEX, $s);\n}","tryCatchPattern":"try {\n    $r1c1 = AddressHelper::convertToR1C1($addr);\n} catch (\\PhpOffice\\PhpSpreadsheet\\Exception $e) {\n    // 'Invalid A1-format Cell Reference' -> normalize input (strip sheet prefix,\n    // split ranges) and retry, or reject\n}","preventionTips":["Convert ranges cell-by-cell after Coordinate::extractAllCellReferencesInRange()","Strip 'Sheet1!' prefixes and trim whitespace before converting","Never feed bare columns ('A'), defined names, or empty strings","Reuse Coordinate::A1_COORDINATE_REGEX for pre-validation so rules stay in sync"],"tags":["phpspreadsheet","cell-reference","a1","r1c1","address-conversion","validation"],"backgroundTag":"invalid-cell-reference","analyzedSha":"65b080eef4d9fd11a5796135ab145883e5c3d6a6","analyzedAt":"2026-08-17T05:40:41.646Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}