{"record":{"id":"7e9e6e54ecaa06df","repo":"phalcon/cphalcon","slug":"yaml-form-schema-must-parse-to-an-array","errorCode":null,"errorMessage":"YAML form schema must parse to an array","messagePattern":"YAML form schema must parse to an array","errorType":"exception","errorClass":"Phalcon\\Forms\\Exceptions\\YamlSchemaNotArray","httpStatus":null,"severity":"error","filePath":"phalcon/Forms/Loader/YamlLoader.zep","lineNumber":65,"sourceCode":"     */\n    public function load() -> array\n    {\n        var definitions, loader, source;\n\n        if !this->phpExtensionLoaded(\"yaml\") {\n            throw new YamlExtensionRequired();\n        }\n\n        let source = this->source;\n\n        if is_file(source) && is_readable(source) {\n            let definitions = yaml_parse_file(source);\n        } else {\n            let definitions = yaml_parse(source);\n        }\n\n        if typeof definitions !== \"array\" {\n            throw new YamlSchemaNotArray();\n        }\n\n        let loader = new ArrayLoader(definitions);\n\n        return loader->load();\n    }\n}\n","sourceCodeStart":47,"sourceCodeEnd":73,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Forms/Loader/YamlLoader.zep#L47-L73","documentation":"After yaml_parse()/yaml_parse_file() succeeds, YamlLoader requires the parsed document to be a PHP array; the resulting definitions are handed to ArrayLoader. A YAML root that parses to a scalar (a lone string/number), an empty document (null), or any non-array triggers YamlSchemaNotArray.","triggerScenarios":"A YAML file containing only a scalar or only comments (parses to null); a root-level mapping (key: value) instead of a list of entries; a file whose list items were accidentally dedented.","commonSituations":"Empty or fully commented-out schema files left after refactoring; copying YAML from documentation where the root is a mapping; truncation during a deploy.","solutions":["Make the YAML root a list of mappings — entries start with '- '","Verify the shape before loading: $parsed = yaml_parse_file($path); ensure is_array($parsed)","If the file is intentionally empty, skip loading rather than passing it to YamlLoader"],"exampleFix":"# before — forms.yaml\nversion: 2\nfields:\n  - type: text\n    name: email\n\n# after — forms.yaml\n- type: text\n  name: email\n- type: submit\n  name: send","handlingStrategy":"validation","validationCode":"if (!extension_loaded('yaml')) {\n    throw new \\RuntimeException('pecl/yaml extension required');\n}\n\n$parsed = is_file($source) && is_readable($source)\n    ? yaml_parse_file($source)\n    : yaml_parse($source);\n\nif (!is_array($parsed)) {\n    throw new \\InvalidArgumentException(\n        'YAML form schema must be a list of mappings; root parsed to ' . gettype($parsed)\n    );\n}","typeGuard":"/** @param mixed $parsed */\nfunction isYamlDefinitionList($parsed): bool\n{\n    return is_array($parsed);\n}","tryCatchPattern":"try {\n    $defs = (new \\Phalcon\\Forms\\Loader\\YamlLoader($source))->load();\n} catch (\\Phalcon\\Forms\\Exceptions\\YamlSchemaNotArray $e) {\n    // root is a scalar/empty document; fix or skip the file\n    $logger->warning('Skipping malformed YAML schema: ' . $e->getMessage());\n    $defs = [];\n}","preventionTips":["Keep YAML schema roots as '- '-prefixed lists and verify with a quick yaml_parse check in CI","Treat empty schema files as 'no definitions' and skip loading them","Avoid mixing metadata mappings at the root; put every entry under the list"],"tags":["phalcon","forms","yaml","schema","structure"],"backgroundTag":"schema-validation-failed","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}