{"record":{"id":"4a4c68ba42b6d32f","repo":"PHPOffice/PhpSpreadsheet","slug":"invalid-r1c1-format-cell-reference","errorCode":null,"errorMessage":"Invalid R1C1-format Cell Reference","messagePattern":"Invalid R1C1-format Cell Reference","errorType":"exception","errorClass":"PhpOffice\\PhpSpreadsheet\\Exception","httpStatus":null,"severity":"error","filePath":"src/PhpSpreadsheet/Cell/AddressHelper.php","lineNumber":43,"sourceCode":"\n        return [$rowChar, $colChar];\n    }\n\n    /**\n     * Converts an R1C1 format cell address to an A1 format cell address.\n     */\n    public static function convertToA1(\n        string $address,\n        int $currentRowNumber = 1,\n        int $currentColumnNumber = 1,\n        bool $useLocale = true\n    ): string {\n        [$rowChar, $colChar] = $useLocale ? self::getRowAndColumnChars() : ['R', 'C'];\n        $regex = '/^(' . $rowChar . '(\\[?[-+]?\\d*\\]?))(' . $colChar . '(\\[?[-+]?\\d*\\]?))$/i';\n        $validityCheck = preg_match($regex, $address, $cellReference);\n\n        if (empty($validityCheck)) {\n            throw new Exception('Invalid R1C1-format Cell Reference');\n        }\n\n        $rowReference = $cellReference[2];\n        //    Empty R reference is the current row\n        if ($rowReference === '') {\n            $rowReference = (string) $currentRowNumber;\n        }\n        //    Bracketed R references are relative to the current row\n        if ($rowReference[0] === '[') {\n            $rowReference = $currentRowNumber + (int) trim($rowReference, '[]');\n        }\n        $columnReference = $cellReference[4];\n        //    Empty C reference is the current column\n        if ($columnReference === '') {\n            $columnReference = (string) $currentColumnNumber;\n        }\n        //    Bracketed C references are relative to the current column\n        if ($columnReference[0] === '[') {","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/PHPOffice/PhpSpreadsheet/blob/65b080eef4d9fd11a5796135ab145883e5c3d6a6/src/PhpSpreadsheet/Cell/AddressHelper.php#L25-L61","documentation":"Cell\\AddressHelper::convertToA1() parses an R1C1-style reference against a row/column regex (locale-aware, e.g. '/^(R(\\[?-?\\d*\\]?))(C(\\[?-?\\d*\\]?))$/i'). If the address does not match - missing C part, stray characters, wrong order - it throws PhpOffice\\PhpSpreadsheet\\Exception 'Invalid R1C1-format Cell Reference'. It converts a single R1C1 cell reference to A1 given the current row/column anchor.","triggerScenarios":"convertToA1('R5') or convertToA1('C3') (half a reference); convertToA1('Z5C2'); convertToA1('R5C2X'); localized input when $useLocale expects different row/col initials; passing an A1 string like 'B3' by mistake; empty string input.","commonSituations":"Converting R1C1 formulas from Xlsx/Xml sources or non-Excel tools; accepting R1C1 coordinates from user input or URLs without validation; locale spreadsheets (row/column indicator letters differ, e.g. Cyrillic) processed with the wrong $useLocale flag; mixing up convertToA1/convertToR1C1 direction.","solutions":["Validate/normalize the R1C1 string before calling: full 'R[n]C[m]' with optional signed bracketed offsets","If input may be A1, detect and route to convertToR1C1 instead","Pass correct $currentRowNumber/$currentColumnNumber anchors for relative forms like 'R[1]C[-2]'","Use AddressHelper::R1C1_COORDINATE_REGEX (or a strict '^R...C...$' anchored pattern) for pre-validation; wrap the call in try/catch PhpOffice\\PhpSpreadsheet\\Exception"],"exampleFix":"// before\n$a1 = AddressHelper::convertToA1($ref, 5, 2); // $ref = 'R5' -> throws\n\n// after\nif (Preg::isMatch('/^R(\\[-?\\d+\\]|\\d*)C(\\[-?\\d+\\]|\\d*)$/i', $ref)) {\n    $a1 = AddressHelper::convertToA1($ref, 5, 2);\n} else {\n    throw new InvalidArgumentException(\"Bad R1C1 ref: $ref\");\n}","handlingStrategy":"validation","validationCode":"if (!preg_match('/^R(\\[-?\\d+\\]|\\d*)C(\\[-?\\d+\\]|\\d*)$/i', $ref)) {\n    throw new InvalidArgumentException(\"not an R1C1 reference: $ref\");\n}\n$a1 = AddressHelper::convertToA1($ref, $row, $col);","typeGuard":"function isR1C1Ref(string $s): bool\n{\n    return (bool) preg_match('/^R(\\[-?\\d+\\]|\\d*)C(\\[-?\\d+\\]|\\d*)$/i', $s);\n}","tryCatchPattern":"try {\n    $a1 = AddressHelper::convertToA1($ref, $row, $col);\n} catch (\\PhpOffice\\PhpSpreadsheet\\Exception $e) {\n    // 'Invalid R1C1-format Cell Reference' -> reject input, log ref and anchors\n    throw new InvalidArgumentException($e->getMessage(), 0, $e);\n}","preventionTips":["Anchor-validate external R1C1 input with a strict regex before conversion","Remember both R and C parts are mandatory (R alone or C alone fails)","Set $useLocale correctly for localized row/column initials","Route A1-looking input to convertToR1C1 instead"],"tags":["phpspreadsheet","cell-reference","r1c1","a1","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"}