twigphp/Twig · error · SyntaxError

The first argument of the "enum_cases" function must be a…

Error message

The first argument of the "enum_cases" function must be a string.

What it means

The enum_cases() Twig function compiles to <Enum>::cases(). At compile time it checks that its first argument is a constant string literal. If the constant node's value is not a string (e.g. a number or boolean literal), compilation fails with this SyntaxError.

Solutions

Pass the enum class name as a quoted string, e.g. {{ enum_cases('App\\Status') }}
If the enum name is dynamic, pass a runtime variable instead of a literal (runtime validation applies)
Check quoting: '123' vs 123

Example fix

// before (template)
{{ enum_cases(123) }}
// after
{{ enum_cases('App\\Status') }}

Defensive patterns

Strategy: type-guard

Validate before calling

<?php
// before rendering
$value = 123;
if (!is_string($value)) throw new \InvalidArgumentException('enum_cases arg must be a string');

Type guard

function isEnumName(mixed $v): bool { return \is_string($v) && \enum_exists($v); }

Try / catch

try {
    echo $twig->render($template, $ctx);
} catch (\Twig\Error\SyntaxError $e) {
    if (str_contains($e->getMessage(), 'enum_cases')) { /* fix literal type */ }
}

Prevention

Always quote enum class names in templates
Remember enum_cases expects an FQCN string literal, not arbitrary values
Validate enum names with enum_exists() in PHP before templating

When it happens

Trigger: Writing {{ enum_cases(123) }} or {{ enum_cases(true) }} — the first argument is a constant expression but not a string. Note the check only applies to constant arguments; dynamic expressions are evaluated at runtime.

Common situations: Misunderstanding enum_cases as accepting any value; accidentally passing a numeric literal instead of a quoted enum class string.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of twigphp/Twig@a414c3a491 (2026-09-13). Data as JSON: /api/errors/a92e857d54be5e12. Report an issue: GitHub.

Appendix: source

Thrown at src/Node/Expression/FunctionNode/EnumCasesFunction.php:41

        $arguments = $this->getNode('arguments');
        if ($arguments->hasNode('enum')) {
            $firstArgument = $arguments->getNode('enum');
        } elseif ($arguments->hasNode('0')) {
            $firstArgument = $arguments->getNode('0');
        } else {
            $firstArgument = null;
        }

        if (!$firstArgument instanceof ConstantExpression || 1 !== \count($arguments)) {
            parent::compile($compiler);

            return;
        }

        $value = $firstArgument->getAttribute('value');

        if (!\is_string($value)) {
            throw new SyntaxError('The first argument of the "enum_cases" function must be a string.', $this->getTemplateLine(), $this->getSourceContext());
        }

        if (!enum_exists($value)) {
            throw new SyntaxError(\sprintf('The first argument of the "enum_cases" function must be the name of an enum, "%s" given.', $value), $this->getTemplateLine(), $this->getSourceContext());
        }

        $compiler->raw(\sprintf('%s::cases()', $value));
    }
}

View on GitHub (pinned to a414c3a491)