{"record":{"id":"8b2357267ff61896","repo":"octobercms/october","slug":"the-dimension-field-code-must-have-the-oc-field-p","errorCode":null,"errorMessage":"The dimension field code must have the oc_field_ prefix\n                and can only contain Latin letters, numbers and underscores.","messagePattern":"The dimension field code must have the oc_field_ prefix\n                and can only contain Latin letters, numbers and underscores\\.","errorType":"exception","errorClass":"SystemException","httpStatus":null,"severity":"error","filePath":"modules/dashboard/classes/ReportDimensionField.php","lineNumber":111,"sourceCode":"    }\n\n    /**\n     * Returns the database column name if it was provided in the constructor.\n     * @return ?string\n     */\n    public function getColumnName(): ?string\n    {\n        return $this->columnName;\n    }\n\n    /**\n     * Validates a dimension field code.\n     * @throws SystemException if the code is invalid.\n     */\n    public static function validateCode(string $code)\n    {\n        if (!preg_match('/^oc_field_[a-z][a-zA-Z0-9_]*$/', $code)) {\n            throw new SystemException('The dimension field code must have the oc_field_ prefix\n                and can only contain Latin letters, numbers and underscores.');\n        }\n    }\n\n    /**\n     * Determines if the field is sortable\n     * @return bool Returns true if the field is sortable.\n     */\n    public function getIsSortable()\n    {\n        return $this->sortable;\n    }\n\n    /**\n     * Determines if the field is filterable\n     * @return bool Returns true if the field is filterable\n     */\n    public function getIsFilterable()","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/octobercms/october/blob/b608633a7e8922487d91a8161499020121c3b3bf/modules/dashboard/classes/ReportDimensionField.php#L93-L129","documentation":"validateCode() enforces the field code pattern ^oc_field_[a-z][a-zA-Z0-9_]*$: the literal 'oc_field_' prefix, then a lowercase letter, then any mix of letters (either case), digits, and underscores. It runs both from the ReportDimensionField constructor and from ReportDimensionFilter when filtering by a dimension field, so the same rule applies everywhere field codes appear.","triggerScenarios":"Codes like 'status' (no prefix), 'oc_field_Status' (first character after the prefix is uppercase), 'oc_field_1status' (starts with a digit), 'oc_field_' (nothing after the prefix), or 'oc_field_my-field' (hyphen) all fail preg_match and throw.","commonSituations":"Migrating legacy field identifiers into the oc_field_ namespace; machine-generated codes that start with a digit; assuming camelCase is allowed everywhere (only allowed after the first character — the character right after the prefix must be lowercase).","solutions":["Prefix the code with oc_field_ and make the first character after the prefix a lowercase letter: oc_field_status, oc_field_orderStatus are valid","For auto-generated codes, normalize first: lcfirst($name) after stripping invalid characters","Remember only the FIRST character must be lowercase — subsequent characters may be uppercase or digits"],"exampleFix":"// before\n$field = new ReportDimensionField('Status', 'Status');\n\n// after\n$field = new ReportDimensionField('oc_field_status', 'Status');","handlingStrategy":"type-guard","validationCode":"$code = 'oc_field_' . lcfirst(preg_replace('/[^a-zA-Z0-9_]/', '', $rawName));\nif (!ReportDimensionField::isValidCode($code)) { // see typeGuard\n    throw new InvalidArgumentException(\"Invalid dimension field code '{$code}'\");\n}","typeGuard":"function isValidDimensionFieldCode(string $code): bool\n{\n    return (bool) preg_match('/^oc_field_[a-z][a-zA-Z0-9_]*$/', $code);\n}","tryCatchPattern":null,"preventionTips":["Centralize field-code generation in one helper that enforces the prefix and lowercase first letter","Only the character right after oc_field_ must be lowercase; later characters may be camelCase or digits","Test the generator with adversarial inputs: leading digits, hyphens, unicode, empty strings"],"tags":["php","dashboard","report","dimension","field","identifier","regex"],"backgroundTag":"invalid-identifier-format","analyzedSha":"b608633a7e8922487d91a8161499020121c3b3bf","analyzedAt":"2026-08-21T04:24:57.515Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}