{"record":{"id":"fb3cdad12146c2bf","repo":"phalcon/cphalcon","slug":"yamlloader-requires-the-yaml-php-extension-pecl","errorCode":null,"errorMessage":"YamlLoader requires the \"yaml\" PHP extension (pecl/yaml)","messagePattern":"YamlLoader requires the \"yaml\" PHP extension \\(pecl/yaml\\)","errorType":"exception","errorClass":"Phalcon\\Forms\\Exceptions\\YamlExtensionRequired","httpStatus":null,"severity":"error","filePath":"phalcon/Forms/Loader/YamlLoader.zep","lineNumber":53,"sourceCode":"\n    /**\n     * @param string $source YAML string or path to a YAML file\n     */\n    public function __construct(string source)\n    {\n        let this->source = source;\n    }\n\n    /**\n     * @phpstan-return array<int, array<string, mixed>>\n     * @throws Exception\n     */\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    }","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Forms/Loader/YamlLoader.zep#L35-L71","documentation":"YamlLoader::load() needs yaml_parse()/yaml_parse_file(), which only exist when the pecl yaml extension is loaded. It checks extension_loaded('yaml') up front and throws YamlExtensionRequired, giving a clear, catchable error instead of a fatal 'Call to undefined function yaml_parse()'.","triggerScenarios":"Calling (new YamlLoader($yaml))->load() on any PHP build where the yaml extension is not loaded: a different Docker base image, a CI runner, or a PHP upgrade that dropped the extension.","commonSituations":"Works locally (extension installed) but fails in production or CI images; switching to a minimal php:*-fpm-alpine image without php-yaml; ops installing extensions selectively per environment.","solutions":["Install the extension: apt-get install libyaml-dev && pecl install yaml, then enable extension=yaml.so","On packaged images (Debian/Alpine), install the distro php-yaml package and restart PHP-FPM","If YAML support is optional, fall back to JsonLoader or ArrayLoader"],"exampleFix":"# before — Dockerfile\nFROM php:8.3-fpm\n# yaml extension missing; YamlLoader throws YamlExtensionRequired\n\n# after\nFROM php:8.3-fpm\nRUN apt-get update \\\n    && apt-get install -y libyaml-dev \\\n    && pecl install yaml \\\n    && docker-php-ext-enable yaml","handlingStrategy":"validation","validationCode":"if (!extension_loaded('yaml')) {\n    // fail with a clear, actionable message during bootstrap, not at render time\n    throw new \\RuntimeException(\n        'The yaml extension is required for YamlLoader; install it with: pecl install yaml'\n    );\n}\n\n$defs = (new \\Phalcon\\Forms\\Loader\\YamlLoader($source))->load();","typeGuard":null,"tryCatchPattern":"try {\n    $defs = (new \\Phalcon\\Forms\\Loader\\YamlLoader($source))->load();\n} catch (\\Phalcon\\Forms\\Exceptions\\YamlExtensionRequired $e) {\n    // degrade to JSON schema or disable YAML-driven forms\n    $defs = (new \\Phalcon\\Forms\\Loader\\JsonLoader($fallbackJsonPath))->load();\n}","preventionTips":["Add extension_loaded('yaml') to a bootstrap environment check so it fails at startup","Install php-yaml explicitly in Dockerfiles/CI images instead of relying on defaults","If YAML is optional, ship a JSON fallback and switch loaders in a catch"],"tags":["php-extension","yaml","phalcon","forms","environment"],"backgroundTag":"missing-php-extension","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}