twigphp/Twig · error · LogicException

The "deprecation_info" option must be an instance of

Error message

The "deprecation_info" option must be an instance of "%s".

What it means

AbstractTwigCallable's constructor validates the options array passed by subclasses (TwigFunction, TwigFilter, TwigTest). If a 'deprecation_info' option is provided, it must be a DeprecatedCallableInfo instance; anything else triggers this LogicException. The library throws it early so misconfigured callable definitions fail at registration time rather than at render time.

Solutions

Wrap the deprecation data in a DeprecatedCallableInfo instance before passing it as the 'deprecation_info' option.
Remove the 'deprecation_info' option if the callable is not actually deprecated.
Check the package version: 'deprecation_info' requires twig/twig >= 3.15; on older versions use the legacy 'deprecated' options.

Example fix

// before
new TwigFunction('legacy', $fn, ['deprecation_info' => ['package' => 'acme/pkg', 'version' => '2.0']]);
// after
$info = new \Twig\DeprecatedCallableInfo('acme/pkg', '2.0');
new TwigFunction('legacy', $fn, ['deprecation_info' => $info]);

Defensive patterns

Strategy: validation

Validate before calling

if (isset($options['deprecation_info']) && !class_exists(\Twig\DeprecatedCallableInfo::class)) {
    unset($options['deprecation_info']); // legacy Twig: fall back to old options
} elseif (isset($options['deprecation_info']) && !$options['deprecation_info'] instanceof \Twig\DeprecatedCallableInfo) {
    $options['deprecation_info'] = new \Twig\DeprecatedCallableInfo(
        $options['deprecation_info']['package'] ?? '',
        $options['deprecation_info']['version'] ?? ''
    );
}

Type guard

function isValidDeprecationInfo(mixed $v): bool {
    return $v === null || (class_exists(\Twig\DeprecatedCallableInfo::class) && $v instanceof \Twig\DeprecatedCallableInfo);
}

Try / catch

try {
    $fn = new TwigFunction('x', $fn, $options);
} catch (\LogicException $e) {
    // inspect $options['deprecation_info'] and rebuild with a DeprecatedCallableInfo
}

Prevention

Always construct deprecation data with new \Twig\DeprecatedCallableInfo(...), never with arrays.
Only pass 'deprecation_info' when targeting twig/twig >= 3.15.
Keep extension option arrays small and typed; avoid spreading unvalidated config into them.

When it happens

Trigger: Calling new TwigFunction/TwigFilter/TwigTest(..., ['deprecation_info' => <something not a DeprecatedCallableInfo>]), e.g. passing an array of deprecation fields, a string, or null-ish data instead of a DeprecatedCallableInfo object.

Common situations: Migrating from the pre-3.15 'deprecated'/'deprecating_package'/'alternative' options to 'deprecation_info' but passing raw config data instead of constructing DeprecatedCallableInfo; typos in a custom extension's options array.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/AbstractTwigCallable.php:45

    {
        $this->name = $this->dynamicName = $name;
        $this->callable = $callable;
        $this->arguments = [];
        $this->options = array_merge([
            'needs_environment' => false,
            'needs_context' => false,
            'needs_charset' => false,
            'needs_is_sandboxed' => false,
            'is_variadic' => false,
            'always_allowed_in_sandbox' => false,
            'deprecation_info' => null,
            'deprecated' => false,
            'deprecating_package' => '',
            'alternative' => null,
        ], $options);

        if ($this->options['deprecation_info'] && !$this->options['deprecation_info'] instanceof DeprecatedCallableInfo) {
            throw new \LogicException(\sprintf('The "deprecation_info" option must be an instance of "%s".', DeprecatedCallableInfo::class));
        }

        if ($this->options['deprecated']) {
            if ($this->options['deprecation_info']) {
                throw new \LogicException('When setting the "deprecation_info" option, you need to remove the obsolete deprecated options.');
            }

            trigger_deprecation('twig/twig', '3.15', 'Using the "deprecated", "deprecating_package", and "alternative" options is deprecated, pass a "deprecation_info" one instead.');

            $this->options['deprecation_info'] = new DeprecatedCallableInfo(
                $this->options['deprecating_package'],
                $this->options['deprecated'],
                null,
                $this->options['alternative'],
            );
        }

        if ($this->options['deprecation_info']) {

View on GitHub (pinned to a414c3a491)