The Problem: A Monolith and a Magic Array

In Twig 3, an extension declared its operators through getOperators(), which returned two nested arrays with a very specific shape:

public function getOperators(): array
{
    return [
        // unary operators
        [
            'not' => ['precedence' => 70, 'class' => NotUnary::class],
        ],
        // binary operators
        [
            '~' => [
                'precedence' => 27,
                'class' => ConcatBinary::class,
                'associativity' => ExpressionParser::OPERATOR_LEFT,
            ],
        ],
    ];
}

Notice what is missing: behavior. The array describes operators, but the code that parses them lived somewhere else, in the Twig\ExpressionParser class: 1,033 lines handling every operator of the language. And not only operators: filters (|), attribute access (.), subscripts ([), function calls ((), the ternary operator, is tests, arrow functions... all of them were pseudo-operators hardcoded in that one sprawling class. An extension could add an operator as data, but it could never change how one parses. The grammar was closed.

Operators Are Now Objects

In Twig 4, getExpressionParsers() returns a list of objects, each one owning everything about its operator: name, precedence, associativity, and the parsing logic itself. Here is a complete extension adding a repeat operator that repeats a string:

use Twig\Extension\AbstractExtension;
use Twig\ExpressionParser\Infix\BinaryOperatorExpressionParser;

final class StringToolsExtension extends AbstractExtension
{
    public function getExpressionParsers(): array
    {
        return [
            new BinaryOperatorExpressionParser(
                RepeatBinary::class, 'repeat', 30,
            ),
        ];
    }
}

The node class compiles to a str_repeat() call:

use Twig\Compiler;
use Twig\Node\Expression\Binary\AbstractBinary;

final class RepeatBinary extends AbstractBinary
{
    public function compile(Compiler $compiler): void
    {
        $compiler
            ->raw('str_repeat(')
            ->subcompile($this->getNode('left'))
            ->raw(', ')
            ->subcompile($this->getNode('right'))
            ->raw(')');
    }
}

And it works like any built-in operator, precedence included:

{{ '-=' repeat 5 }}      {# outputs -=-=-=-=-= #}
{{ 'ab' repeat 2 ~ '!' }} {# outputs abab! #}

The second line is the interesting one: repeat has precedence 30, concatenation has 27, so the repetition binds tighter. No special case anywhere; the numbers decide.

One Loop to Parse Them All

Now, the part I really want to show you. Pratt's idea splits the world in two: prefix parsers know how to start an expression (a literal, a unary -, not, an opening parenthesis), and infix parsers know how to extend one (+, |, ., a function call). Each parser carries a precedence. The whole algorithm is one method, lightly edited here for brevity:

public function parseExpression(int $precedence = 0): AbstractExpression
{
    $token = $this->getCurrentToken();
    if ($parser = $this->getPrefixParser($token)) {
        $this->getStream()->next();
        $expr = $parser->parse($this, $token);
    } else {
        $expr = $this->parseLiteral($token);
    }

    while (($parser = $this->getInfixParser($this->getCurrentToken()))
        && $parser->getPrecedence() >= $precedence
    ) {
        $token = $this->getCurrentToken();
        $this->getStream()->next();
        $expr = $parser->parse($this, $expr, $token);
    }

    return $expr;
}

That's it. A binary operator's parse() method is two lines: parse my right side, build my node:

public function parse(
    Parser $parser, AbstractExpression $left, Token $token,
): AbstractExpression {
    $right = $parser->parseExpression(
        $this->isLeftAssociative()
            ? $this->getPrecedence() + 1
            : $this->getPrecedence()
    );

    return new ($this->nodeClass)($left, $right, $token->getLine());
}

Let's walk through 1 + 2 * 3. The outer call parses 1, sees + (precedence 30), and lets it parse the right side with a minimum precedence of 31. That inner call parses 2, sees * (precedence 60, which is ≥ 31), and recurses again: 2 * 3 becomes a node, the inner call returns it, and + builds 1 + (2 * 3). Now flip the operands: in 1 * 2 + 3, the inner call parses 2, sees + (precedence 30, which is < 61), and stops right there; the outer loop picks + up and builds (1 * 2) + 3. Two integer comparisons, and precedence falls out for free.

Associativity is the + 1 in the snippet above. Left-associative operators ask for strictly higher precedence on their right, so 8 - 2 - 1 becomes (8 - 2) - 1. Right-associative operators ask for their own precedence, so 2 ** 3 ** 2 becomes 2 ** (3 ** 2), which is 512. One character of code, and that is the entire theory of associativity.

Everything Is an Expression Parser

The first version of this work turned operators into objects and kept the rest of the monolith untouched. Then it clicked: operators are a subset of expression parsers. A filter is an infix parser for |. Attribute access is an infix parser for .. A function call is an infix parser for ( applied to a name. The ternary operator, ??, is, arrow functions: parsers, parsers, parsers. Even the humble parenthesized group is a prefix parser for (.

Treating a function call as a binary operator raised a few eyebrows during code review, and I understand why; no mainstream language describes ( that way. But once every construct is a parser with a precedence, they all play by the same rules: one registry, one precedence table, one documentation page, and an extension API that can express any of them. The Twig\ExpressionParser monolith had nothing left to do, and Twig 4.0 deletes it.

One refinement came out of real-world testing: the lexer needs to know which token strings are operators, and a parser's name is not always one of them. When the internal literal parser shipped, its name suddenly clashed with a Craft CMS filter named literal, breaking templates using 'foo'|literal. The fix is the getOperatorTokens() method: each parser declares the token strings it owns, and parsers like literal that own none return an empty list, leaving the name free for your filters.

The Upgrade Path

Twig 3.21 deprecated getOperators(), with extensions still using it triggering "Extension "App\Twig\StringToolsExtension" uses the old signature for "getOperators()", please implement "getExpressionParsers()" instead.". The new method already works on 3.21+, so you can migrate your extensions today and they will run unmodified on both majors.

Fighting Spam with AI

The spam chapter used to call the Akismet API by hand; a fine excuse to learn the HttpClient component, but let's be honest, not how you would solve this problem in 2026. The chapter has been rewritten around Symfony AI: an agent now asks a Large Language Model whether a submitted comment is spam, with a system prompt that constrains its role and its answers.

The chapter uses OpenAI with gpt-5-mini, but the code does not care about the provider: Symfony AI abstracts OpenAI, Anthropic, Google Gemini, Mistral, and even local models via Ollama behind the same platform interface; switch providers and only the configuration changes. Nothing here requires a frontier model either: a task as narrow as spam classification would be perfectly served by a small or specialized model. The calls still happen "out of band" via Messenger, because an expensive call is an expensive call, whether it hits Akismet or a model. And the chapter teaches a design rule I care about: when the model cannot answer, fall back to human moderation. AI should help the admin, never block the guestbook.

Testing with Object Factories

Two changes in the tests chapter. Doctrine fixtures are gone, replaced by Zenstruck Foundry: each test now creates exactly the data set it needs via object factories, with realistic defaults generated by Faker. Tests become independent from each other, and reading a test tells you everything about the data it relies on.

And how do you test code that calls an LLM? You don't, at least not the model: hitting the OpenAI API in a test suite would be slow, expensive, and not even deterministic. The book replaces the platform with Symfony AI's InMemoryPlatform, wrapped in a real Agent so that the application logic is tested for real, including the "model is down" path.

No More Node.js

The styling chapter dropped Webpack Encore for AssetMapper. Importmaps, browser-native modules, no node_modules, no build step. Bootstrap is still there but Node.js disappeared from the book's requirements entirely: the first chapter no longer asks you to install it.

An SPA Feel, without the SPA

Previous editions ended with a Preact single-page application for mobile phones. This edition replaces it with a chapter on Symfony UX: Turbo makes navigation feel instant without full page reloads, Turbo Frames update just a fragment of the page, and a small Stimulus controller previews the comment photo before it is uploaded. The result feels as snappy as an SPA, written with the Twig templates we already have. The API chapter is still there, so when a real mobile application comes knocking, the backend is ready.

Scheduling without Cron

The old cron chapter became the Scheduler chapter. The comment cleanup task is now declared in PHP with the Scheduler component, which means the schedule lives in the code, ships with the application, and deploys with it. No more editing crontabs on production machines; the chapter still explains how the two approaches compare.

SymfonyCloud: From Platform.sh to Upsun

The book deploys to production from the very first chapters, and that has not changed. What changed is the platform underneath: the deployment chapters now target Upsun, the next generation of Platform.sh. If you read a previous edition, the workflow will feel familiar, on purpose: it is still SymfonyCloud from where you stand, the same symfony cloud: commands, a Git push to deploy, one environment per branch. Only the configuration file moved, from .platform.app.yaml to .upsun/config.yaml.

Modern Symfony, Everywhere

Beyond the headline chapters, the whole book has been modernized to the idioms of today's Symfony: the #[Cache] attribute on controllers instead of calls on the Response, #[AsEventListener] instead of event subscribers, #[MapQueryParameter] instead of poking at the Request, invokable console commands with services injected right in __invoke(), and typed Doctrine lifecycle events. The workflow chapter now dumps Mermaid diagrams, which GitHub and GitLab render natively. Small things, but they add up: the code you write in the book is the code you would write in a new project today.

A Book that Runs

This book is executable, and that is still my favorite thing about it. Every edition is validated by tooling that replays the whole journey exactly as a reader would: it builds the guestbook commit by commit, runs the test suite at every step, deploys each of the 27 deployable steps to Upsun and asserts the live pages, and takes the 40 screenshots you see in the book from the running application. If a chapter breaks, the build breaks.

Fun fact: this edition's validation run found a real bug: a twelve-year-old limitation in Symfony's HttpCache that serves file responses with an empty body. The bug itself is next on my list.

Read It Now

The English edition is available online, for free, at symfony.com/book. The code lives on GitHub, with one Git tag per step; check out any tag to compare your code with mine at that exact point of the journey. And if you would rather explore the finished application first, the Symfony CLI sets everything up for you, web server and containers included:

$ symfony new --version=8.1-1 --book guestbook

The book is also available in five languages, fully translated for this edition: French, German, Italian, Japanese, and Russian.

Six years and eight editions later, I still believe the fastest way to learn Symfony is to build something real. Build the guestbook.

Build Semaphores on Any Lock Backend

Contributed by Alexander Schranz in #59202

The Semaphore component limits the number of processes that can access a shared resource at the same time. Until now, its only built-in store was based on Redis, which left applications using other backends without a usable option.

Symfony 8.1 adds a LockStore that builds a semaphore on top of the Lock component, so you can reuse any lock backend (database, filesystem, Redis, etc.). A semaphore with a limit of N is implemented using N individual locks behind the scenes:

use Symfony\Component\Lock\LockFactory;
use Symfony\Component\Lock\Store\FlockStore;
use Symfony\Component\Semaphore\SemaphoreFactory;
use Symfony\Component\Semaphore\Store\LockStore;

$lockFactory = new LockFactory(new FlockStore());
$semaphoreFactory = new SemaphoreFactory(new LockStore($lockFactory));

// allow at most 3 processes to hold this semaphore at the same time
$semaphore = $semaphoreFactory->createSemaphore('thumbnail-generation', 3);
$semaphore->acquire();

When using FrameworkBundle, point the semaphore at a configured lock with the new lock:// DSN:

# config/packages/semaphore.yaml
framework:
    lock:
        default: 'flock'
        redis: '%env(REDIS_DSN)%'
    semaphore:
        default: 'lock://'      # uses the "default" lock
        other: 'lock://redis'   # uses the "redis" lock

Collect Extra Attributes Errors While Deserializing

Contributed by NorthBlue333 in #46654

When deserializing an incoming payload into an object, you can pass the COLLECT_DENORMALIZATION_ERRORS option to gather every type mismatch in a single PartialDenormalizationException instead of failing on the first one. However, attributes that didn't exist on the target class were reported separately, so you couldn't validate everything in one pass.

Symfony 8.1 adds the COLLECT_EXTRA_ATTRIBUTES_ERRORS option, which collects those unexpected attributes together with the type errors:

use Symfony\Component\Serializer\Exception\PartialDenormalizationException;
use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;

try {
    $post = $serializer->deserialize($request->getContent(), BlogPost::class, 'json', [
        DenormalizerInterface::COLLECT_DENORMALIZATION_ERRORS => true,
        DenormalizerInterface::COLLECT_EXTRA_ATTRIBUTES_ERRORS => true,
        AbstractNormalizer::ALLOW_EXTRA_ATTRIBUTES => false,
    ]);
} catch (PartialDenormalizationException $e) {
    // type mismatches (e.g. a string where an int was expected)
    foreach ($e->getNotNormalizableValueErrors() as $error) {
        // $error->getPath(), $error->getExpectedTypes(), ...
    }

    // attributes sent by the client that don't exist on BlogPost
    if (null !== $extraAttributesError = $e->getExtraAttributesError()) {
        $unexpected = $extraAttributesError->getExtraAttributes();
    }
}

The previous getErrors() method is now deprecated; use getNotNormalizableValueErrors() instead.

Use the :has() Selector in CSS Expressions

Contributed by Franck RANAIVO-HARISOA in #49388

The CssSelector component converts CSS selectors into XPath expressions, which is what lets you query the DOM with CSS syntax in the DomCrawler (for example, in functional tests). Symfony 8.1 adds support for the :has() relational pseudo-class, so you can select elements based on their descendants or siblings:

use Symfony\Component\CssSelector\CssSelector;

// <article> elements that contain an <h2> somewhere inside them
CssSelector::toXPath('article:has(h2)');

// <div> elements with a direct child that has the "error" class
CssSelector::toXPath('div:has(> .error)');

This is the same selector now available in all major browsers, and it works everywhere CssSelector is used, including Crawler::filter() in your tests.

Wrap Response Fragments Before Parsing in Tests

Contributed by Hubert Lenoir in #62892

Some endpoints return HTML fragments rather than full documents (for example, an AJAX action that returns a few table rows). When the test client parses a bare <tr> element, the HTML5 parser rewrites or drops it because it isn't valid outside a table, so your assertions run against mangled markup.

Symfony 8.1 adds the wrapContent() method to the test client. It wraps the response body in the structure you provide (using %s as a placeholder) before parsing, without changing the actual HTTP response:

// wrap fragments in a full table so <tr>/<td> elements are parsed correctly
$client->wrapContent('<table>%s</table>');

$crawler = $client->request('GET', '/comments/rows');

// the rows are now available in the crawler as expected
$this->assertCount(3, $crawler->filter('tr'));

Serialize Semaphore Keys Across Processes

Contributed by Paul Clegg in #63059

Sometimes you need to acquire a semaphore in one process and release it in another, for example when a controller starts a long task and a Messenger worker finishes it. That requires passing the semaphore Key to the other process.

Symfony 8.1 makes the Key class serializable and adds a SemaphoreKeyNormalizer so you can serialize keys with the Serializer component too. When using FrameworkBundle, the normalizer is registered automatically:

use Symfony\Component\Semaphore\Key;

// process 1: acquire the semaphore, then serialize its key
$key = new Key('report-generation', 3);
$semaphore = $factory->createSemaphoreFromKey($key, autoRelease: false);
$semaphore->acquire();

$serializedKey = $serializer->serialize($key, 'json');

// process 2: rebuild the semaphore from the key and release it
$key = $serializer->deserialize($serializedKey, Key::class, 'json');
$factory->createSemaphoreFromKey($key)->release();

Restrict the Allowed Values of APP_ENV

Contributed by Vincent Pabst in #63429

The APP_ENV environment variable selects which configuration your application boots with. If it ever holds an unexpected value (a typo like prodution or a leftover CI/CD value), Symfony happily boots into that unknown environment, which can silently disable protections you rely on in production.

Symfony 8.1 lets you declare the list of valid environments via the new getAllowedEnvs() method of MicroKernelTrait. If the current environment is not in the returned list, the kernel throws an exception immediately instead of booting:

// src/Kernel.php
namespace App;

use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;

class Kernel extends BaseKernel
{
    use MicroKernelTrait;

    /**
     * @return list<string> An array of allowed values for APP_ENV
     */
    private function getAllowedEnvs(): array
    {
        return ['prod', 'dev', 'test'];
    }
}

Booting with APP_ENV=staging now fails fast with a clear error instead of starting in an unintended state. When the method returns an empty array, the previous behavior is unchanged and all environments are allowed.

More Clear-Site-Data Directives on Logout

Contributed by Christian Flothmann in #62322

When a user logs out, Symfony can send the Clear-Site-Data HTTP header to tell the browser to wipe locally stored data. Until now, you could only clear cache, cookies, storage and executionContexts.

Symfony 8.1 adds the three remaining directives defined by the specification: clientHints, prefetchCache and prerenderCache:

# config/packages/security.yaml
security:
    firewalls:
        main:
            logout:
                clear_site_data:
                    - 'cookies'
                    - 'storage'
                    - 'clientHints'
                    - 'prefetchCache'
                    - 'prerenderCache'

Reproducible Builds with SOURCE_DATE_EPOCH

Contributed by Charles-Edouard Coste in #62538

When Symfony compiles the service container, it records the build time so caches can be invalidated. Because that value defaults to the current time, two builds from the exact same source code produce slightly different containers, which breaks reproducible builds.

Symfony 8.1 supports the conventional SOURCE_DATE_EPOCH environment variable shared across the reproducible-builds ecosystem. When it's defined, Symfony uses its Unix timestamp as the container build time:

# use the date of the last commit as the build time
$ export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
$ php bin/console cache:clear

If you set the kernel.container_build_time parameter explicitly, it still takes precedence; otherwise Symfony falls back to SOURCE_DATE_EPOCH and then to the current time.

Describe Object Shapes with TypeInfo

Contributed by Benjamin Franzke in #62885

The TypeInfo component models PHP types as objects, allowing other components (and your own code) to reason about them. Symfony 8.1 adds support for object shapes: the exact structure of an object, described by its property names and types.

The StringTypeResolver now understands the object{...} PHPDoc syntax, where a ? suffix marks an optional property:

use Symfony\Component\TypeInfo\TypeResolver\StringTypeResolver;

$resolver = new StringTypeResolver();

// resolves to an ObjectShapeType
$type = $resolver->resolve('object{name: string, age: int, email?: string}');

You can also build the same type programmatically with the new Type::objectShape() factory:

use Symfony\Component\TypeInfo\Type;

$type = Type::objectShape([
    'name' => Type::string(),
    'age' => Type::int(),
    'email' => ['type' => Type::string(), 'optional' => true],
]);

The Problem: A Policy That Didn't Mean What It Said

Take a policy that looks airtight. You list a handful of tags and filters, no functions, no extra tests, and you feel safe:

$policy = new SecurityPolicy(
    allowedTags: ['if', 'for'],
    allowedFilters: ['escape', 'upper'],
    allowedMethods: ['Article' => ['getTitle', 'getBody']],
    allowedProperties: [],
    allowedFunctions: [],
);

Now a template author writes this:

{# tests were never checked, so this ran unchecked #}
{% if 'SOME_SECRET' is constant('SOME_SECRET') %}...{% endif %}

{# functions you never listed, allowed anyway #}
{{ attribute(article, 'getSecret') }}

None of these are in your policy. All of them ran. The sandbox ignored tests entirely, so any test, including constant and any custom one, went through unchecked; and a short list of tags and functions (extends, use, parent, block, attribute) was hardcoded as always allowed regardless of what your policy said.

Nobody likes security tools that are lenient by default; a policy you have to second-guess is worse than no policy, because it gives you false confidence. Twig 4.0 makes the allow-list mean exactly what it says.

Tests Are Now Part of the Sandbox

Tests (the is operator: is even, is defined, is constant(...)) are now a first-class allow-list, alongside tags, filters, and functions. The SecurityPolicy constructor gained a sixth argument for them:

$policy = new SecurityPolicy(
    allowedTags: ['if', 'for'],
    allowedFilters: ['escape', 'upper'],
    allowedMethods: ['Article' => ['getTitle', 'getBody']],
    allowedProperties: [],
    allowedFunctions: [],
    allowedTests: ['prime'],
);

A custom test that is not listed is now rejected like anything else:

{% if number is prime %}...{% endif %}
{# Twig\Sandbox\SecurityNotAllowedTestError:
   Test "prime" is not allowed in "page" at line 1. #}

You don't need to enumerate the safe built-ins, though. The harmless ones (defined, empty, even, odd, iterable, same as, null, divisible by and the rest) are flagged as always allowed, so templates relying on them keep working without a single line of configuration. The one exception is constant, which reaches into the PHP runtime: it must be allow-listed explicitly, like a custom test.

No More Silent Exceptions

The tags and functions that used to be allowed behind your back, extends, use, parent, block, attribute, and the constant test, are no longer special. In 4.0 they obey the policy like everything else: list them if your templates need them, and they are rejected if you don't.

This is the kind of change that needs a preview before a major release, so you can opt into the 4.0 behavior today on 3.x with a single call:

$policy->setStrict(true);

In strict mode, calling one of these without allow-listing it fails right away:

{{ attribute(article, 'getSecret') }}
{# Twig\Sandbox\SecurityNotAllowedFunctionError:
   Function "attribute" is not allowed in "page" at line 1. #}

Turn strict mode on in your test suite, fix what it flags, and your policy is ready for 4.0.

Marking Inherently-Safe Items as Always Allowed

Tightening the default raises a fair question: must every application now re-list dozens of harmless filters like upper or trim? No. Twig 4.0 introduces a way for the author of a callable to declare it safe for any sandbox, so no policy has to opt into it. Set the always_allowed_in_sandbox option on a filter, function, or test:

$twig->addFilter(new TwigFilter('upper', 'strtoupper', [
    'always_allowed_in_sandbox' => true,
]));

For a tag, override isAlwaysAllowedInSandbox() on its token parser:

final class MyTagTokenParser extends AbstractTokenParser
{
    public function isAlwaysAllowedInSandbox(): bool
    {
        return true;
    }

    // ...
}

A marked item skips the sandbox check entirely, so it costs nothing at runtime and never needs to appear in an allow-list. This is a sharp tool, so the documentation spells out the criteria an item must meet to deserve the flag: no new capability, no PHP runtime access, no callable arguments, no template resolution, no output-safety bypass, deterministic output, and a few more. If in doubt, leave the flag off and let the policy decide.

Built-ins Allowed Out of the Box

Twig applies that same flag to its own toolbox. A curated set of built-ins that meet the criteria, the pure value transformations and control-flow tags you use in every template, are always allowed in 4.0:

• Tags: apply, block, do, for, guard, if, macro, set, types, with.
• Filters: abs, batch, capitalize, convert_encoding, default, e, escape, first, format, join, keys, last, length, lower, merge, nl2br, number_format, replace, reverse, round, slice, split, striptags, title, trim, upper, url_encode.
• Functions: cycle, max, min.

Note what is not on the list: map, filter, sort and friends (they take a callable you may want to forbid), include, source and the other template-resolving helpers, random and shuffle (non-deterministic), json_encode and dump (object introspection), constant (PHP runtime access). Those stay under your policy, where they belong.

When you upgrade, you can delete the safe built-ins from your allow-lists; listing a name that is always allowed has no effect, so there is no rush.

The Upgrade Path

As usual, Twig 3.x triggers a deprecation for everything that will break in 4.0. All the fixes work on 3.x, so an application that runs deprecation-free, or that already enables strict mode on its security policy, is ready for the new sandbox.

Convert Between UUIDv7 and UUIDv4

Contributed by Nicolas Grekas in #63593

UUIDv7 identifiers are time-ordered, making them ideal as database primary keys. However, that property also leaks record creation times when you expose those identifiers in APIs. The new Uuid47Transformer class lets you store UUIDv7 internally while emitting UUIDv4-looking identifiers at your application boundaries:

use Symfony\Component\Uid\Uuid47Transformer;
use Symfony\Component\Uid\UuidV7;

// the secret must be at least 16 bytes; longer secrets are hashed automatically
$transformer = new Uuid47Transformer($secret);

$uuid = new UuidV7();
// returns a UuidV4 instance that hides the timestamp information
$external = $transformer->encode($uuid);

// returns the original UuidV7 instance (when using the same secret)
$original = $transformer->decode($external);

The conversion masks the UUIDv7 timestamp with a keyed SipHash-2-4 digest, making it reversible only with the same secret. When using FrameworkBundle, the transformer is registered as a service automatically (using kernel.secret as the key), so you can inject it anywhere by type-hinting Uuid47Transformer.

Convert Scalar Types During Denormalization

Contributed by Jeroen Spee in #52173

Some data formats represent all values as strings (e.g. HTTP query strings or form data). When deserializing XML and CSV contents, Symfony already casts those strings to the int, float or bool types expected by the target properties. In Symfony 8.1, you can enable this behavior for any format via the new ENABLE_TYPE_CONVERSION context option:

use Symfony\Component\Serializer\Normalizer\AbstractObjectNormalizer;
// ...

// all values are strings, as in an HTTP query string
$data = ['age' => '39', 'sportsperson' => '1'];

// 'age' is cast to int and 'sportsperson' to bool to match the Person property types
$person = $serializer->denormalize($data, Person::class, context: [
    AbstractObjectNormalizer::ENABLE_TYPE_CONVERSION => true,
]);

Set the option to false to disable the conversion, even for the xml and csv formats. The option is also available in the serializer context builders.

Configurable Default Action in HTML Sanitizer

Contributed by Adrien Roches in #57653

When the HTML sanitizer finds a tag that is not part of the configuration, it drops the tag and all its children. In Symfony 8.1, you can change this behavior with the new default_action option, which accepts drop (the current default), block (remove the tag but keep its children) and allow:

# config/packages/html_sanitizer.yaml
framework:
    html_sanitizer:
        sanitizers:
            app.post_sanitizer:
                # ...

                # remove unconfigured tags, but keep processing their children
                default_action: 'block'
                # remove <figure> tags and their children entirely
                drop_elements: ['figure']

Reset the Kernel Between FrankenPHP Requests

Contributed by Nicolas Grekas in #64055

In FrankenPHP worker mode, the same kernel instance handles every request for the lifetime of the worker process. This is great for performance, but any state kept by services that don't implement ResetInterface may leak across requests.

Symfony 8.1 adds an opt-in feature: defining the FRANKENPHP_RESET_KERNEL environment variable makes the runtime clone the kernel after each request, so the next one starts with a fresh kernel and container:

# define this env var where you configure your FrankenPHP workers
FRANKENPHP_RESET_KERNEL=1

The default behavior doesn't change: the kernel is still reused across requests unless you set this variable. Resetting the kernel has a measurable throughput cost on "hello world" benchmarks, but it's still several times faster than the classic non-worker mode and it restores full per-request isolation.

Null-Safe Array Access in Expressions

Contributed by Alex Rothberg in #62754

The ExpressionLanguage component supports the null-safe operator for property access (foo?.bar) and method calls (foo?.getBar()). Symfony 8.1 completes the feature with null-safe array access using the same ?.[...] syntax as JavaScript optional chaining:

// before: this throws an exception when getItems() returns null
$expressionLanguage->evaluate('fruit.getItems()[0]', ['fruit' => $fruit]);

// now: this returns null instead of throwing an exception
$expressionLanguage->evaluate('fruit.getItems()?.[0]', ['fruit' => $fruit]);

// you can combine it with the other null-safe operators
$expressionLanguage->evaluate('order?.getItems()?.[0]?.getName()', ['order' => $order]);

Outline-Style Console Blocks

Contributed by Guillaume Van Der Putten in #63546

The success(), error(), warning() and similar SymfonyStyle methods fill the entire line with a background color, which can be hard to read on terminals with custom color schemes or high-contrast accessibility settings. Symfony 8.1 adds outline-style alternatives that display a colored border around the message while keeping the default text color:

// outlined alternatives exist for all the result methods:
// outlineSuccess(), outlineError(), outlineWarning(), outlineNote(),
// outlineInfo() and outlineCaution()
$io->outlineSuccess('Operation completed successfully.');
$io->outlineError('Something went wrong.');

// use outlineBlock() to customize the title and the colors
$io->outlineBlock('Deployment finished in 3.2s', 'Deploy', 'fg=cyan');

Disable Trailing Slash on Prefixed Root Routes

Contributed by vvaswani in #63689

When you apply a prefix to a collection of routes defined with the PHP DSL, the root route of the collection always gets a trailing slash (e.g. /categories/). In Symfony 8.1, the prefix() method accepts a new trailingSlashOnRoot argument (already available in YAML/XML imports) to disable this:

// config/routes.php
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes): void {
    // this generates /categories (instead of /categories/) and /categories/{id}
    $routes->collection('category_')
        ->prefix('/categories', trailingSlashOnRoot: false)
        ->add('index', '/')
        ->add('show', '/{id}');
};

Get Parent Role Names

Contributed by Pierre-Emmanuel CAPEL in #53998

When using hierarchical roles, the getReachableRoleNames() method returns all the roles inherited by the given roles. Symfony 8.1 adds the inverse operation: getParentRoleNames() returns the roles that inherit from the given roles. This is useful for finding which roles can access everything a given role can access.

Consider the following role hierarchy:

# config/packages/security.yaml
security:
    role_hierarchy:
        ROLE_ADMIN: ROLE_USER
        ROLE_SUPER_ADMIN: ROLE_ADMIN

use Symfony\Component\Security\Core\Role\RoleHierarchyInterface;

class RoleService
{
    public function __construct(
        private RoleHierarchyInterface $roleHierarchy,
    ) {
    }

    public function getParentRoles(array $roles): array
    {
        // for ['ROLE_USER'] this returns an array with 'ROLE_USER', 'ROLE_ADMIN'
        // and 'ROLE_SUPER_ADMIN', because those roles inherit ROLE_USER permissions
        return $this->roleHierarchy->getParentRoleNames($roles);
    }
}

Mark Classes as Safe for Twig's Escaper

Contributed by Jérôme Tamarelle in #63929

If a value object wraps pre-escaped or trusted HTML content, you have to apply the raw Twig filter every time you output it in a template. In Symfony 8.1, you can mark the class as safe for Twig's escaper using the new twig.safe_class resource tag, so its output is no longer escaped:

# config/services.yaml
services:
    App\Twig\HtmlString:
        resource_tags:
            - { name: twig.safe_class, strategy: html }

Unlike regular service tags, resource tags are attached to the class itself, not to a service. The strategy option accepts a single escaping strategy or a list of them, and you can tag the same class several times to mark it as safe for multiple strategies.

New ContainerProviderInterface Contract

Contributed by Nicolas Grekas in #63663

Symfony 8.1 adds a minimal ContainerProviderInterface to symfony/service-contracts, providing a standard way for objects to expose their service container:

namespace Symfony\Contracts\Service;

use Psr\Container\ContainerInterface;

interface ContainerProviderInterface
{
    public function getContainer(): ContainerInterface;
}

The console Application class provided by FrameworkBundle implements it (booting the kernel if needed). This enables decoupled use cases such as Messenger parallel workers, which need to bootstrap the application and access the container to resolve the message bus.