twigphp/Twig · error · SyntaxError

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

Error message

The first argument of the "enum_cases" function must be the name of an enum, "%s" given.

What it means

enum_cases() requires its first constant argument to name an existing PHP enum class. After confirming it is a string, Twig calls enum_exists(); if the string is not a loaded enum class, compilation fails with this SyntaxError showing the given value.

Solutions

1. Use the fully qualified enum class name (FQCN) as a string
2. Verify the class exists, is autoloadable, and is declared with 'enum' (PHP 8.1+)
3. Run the class name through class_exists/enum_exists in PHP to confirm before using in templates
4. Check for typos in backslash namespaces within template strings

Example fix

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

<?php
$name = 'App\\Status';
if (!\enum_exists($name)) {
    throw new \InvalidArgumentException("$name is not a loaded enum (check namespace/autoloader)");
}

function isValidEnum(?string $name): bool { return $name !== null && \enum_exists($name); }

try {
    echo $twig->render($template, $ctx);
} catch (\Twig\Error\SyntaxError $e) {
    if (str_contains($e->getMessage(), 'name of an enum')) {
        // verify FQCN, autoload, and PHP >= 8.1
    }
}

When it happens

Trigger: {{ enum_cases('App\\Status') }} where the class does not exist, is not an enum, or is not yet loaded/autoloader-misspelled, e.g. {{ enum_cases('Status') }} without namespace, or passing an enum-like class name that is actually a plain class.

Common situations: Wrong namespace or typo in enum class name; enum defined in a file not autoloadable at compile time; confusing a class or interface with an enum; PHP < 8.1 environments (feature unavailable).

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Enum " " does not exist.
• " " is not an enum.
• The first argument of the "enum_cases" function must be a…
• The first argument of the "enum" function must be a string.
• The first argument of the "enum" function must be the name…

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

Appendix: source

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

            $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)