phalcon/cphalcon · error · Phalcon\Forms\Exceptions\YamlExtensionRequired

YamlLoader requires the "yaml" PHP extension (pecl/yaml)

Error message

YamlLoader requires the "yaml" PHP extension (pecl/yaml)

What it means

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()'.

Source

Thrown at phalcon/Forms/Loader/YamlLoader.zep:53

    /**
     * @param string $source YAML string or path to a YAML file
     */
    public function __construct(string source)
    {
        let this->source = source;
    }

    /**
     * @phpstan-return array<int, array<string, mixed>>
     * @throws Exception
     */
    public function load() -> array
    {
        var definitions, loader, source;

        if !this->phpExtensionLoaded("yaml") {
            throw new YamlExtensionRequired();
        }

        let source = this->source;

        if is_file(source) && is_readable(source) {
            let definitions = yaml_parse_file(source);
        } else {
            let definitions = yaml_parse(source);
        }

        if typeof definitions !== "array" {
            throw new YamlSchemaNotArray();
        }

        let loader = new ArrayLoader(definitions);

        return loader->load();
    }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Install the extension: apt-get install libyaml-dev && pecl install yaml, then enable extension=yaml.so
2. On packaged images (Debian/Alpine), install the distro php-yaml package and restart PHP-FPM
3. If YAML support is optional, fall back to JsonLoader or ArrayLoader

Example fix

# before — Dockerfile
FROM php:8.3-fpm
# yaml extension missing; YamlLoader throws YamlExtensionRequired

# after
FROM php:8.3-fpm
RUN apt-get update \
    && apt-get install -y libyaml-dev \
    && pecl install yaml \
    && docker-php-ext-enable yaml

if (!extension_loaded('yaml')) {
    // fail with a clear, actionable message during bootstrap, not at render time
    throw new \RuntimeException(
        'The yaml extension is required for YamlLoader; install it with: pecl install yaml'
    );
}

$defs = (new \Phalcon\Forms\Loader\YamlLoader($source))->load();

try {
    $defs = (new \Phalcon\Forms\Loader\YamlLoader($source))->load();
} catch (\Phalcon\Forms\Exceptions\YamlExtensionRequired $e) {
    // degrade to JSON schema or disable YAML-driven forms
    $defs = (new \Phalcon\Forms\Loader\JsonLoader($fallbackJsonPath))->load();
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Yaml extension is not loaded
• This class requires the openssl extension for PHP
• YAML form schema must parse to an array
• This class requires the gettext extension for PHP
• Configuration file {fileName} cannot be loaded

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/fb3cdad12146c2bf. Report an issue: GitHub.