5.4 is the LTS, and its job is to carry as much of 6.0’s feature set as possible while keeping 5.x compatibility intact. It’s also the first Symfony release that actually understands PHP 8.1 features.

Enum support

PHP 8.1 introduced native enums. Symfony 5.4 embraces them immediately:

enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

The EnumType form type renders enums as select fields, no custom transformers needed. The validator understands backed enums. The serializer maps enum values to their backing type and back. Three components updated in one shot, which meant migrating codebases from pseudo-enum constants to real PHP 8.1 enums was actually pretty smooth.

Security voter cache

The CacheableVoterInterface lets voters that always abstain on a given attribute signal that to the security system, which can then skip them on subsequent checks. For apps with many voters, the gain on permission checks adds up fast. Small change, noticeable in practice.

Messenger matures further

Messenger batch processing (handling multiple messages in a single transaction instead of one by one) is now stable. Rate limiting per transport. Dead letter queues get better tooling. After years as “experimental”, Messenger in 5.4 is finally the async foundation you can bet on for serious workloads.

Console grew a tab key

Symfony 5.4 ships shell autocompletion for all commands. Press Tab and the shell suggests command names, argument values, and option values. For built-in commands this works out of the box. For custom commands, add a complete() method:

use Symfony\Component\Console\Completion\CompletionInput;
use Symfony\Component\Console\Completion\CompletionSuggestions;

public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
{
    if ($input->mustSuggestOptionValuesFor('format')) {
        $suggestions->suggestValues(['json', 'xml', 'csv']);
    }
}

No interface required, just the method and Symfony picks it up. The community also went through all built-in commands (debug:router, cache:pool:clear, secrets:remove, lint:twig, and a dozen more) to add completions before the release.

Routes can be aliases now

The routing component now supports aliasing: one route can point to another. The obvious use case is renaming a route without breaking anything that still generates URLs with the old name.

# config/routes.yaml
admin_dashboard:
    path: /admin

# legacy name kept during transition
dashboard:
    alias: admin_dashboard
    deprecated:
        package: 'acme/my-bundle'
        version: '2.3'

Generating a URL with dashboard still works, but fires a deprecation notice. Clean rename paths for bundles that need to maintain public route names while moving on.

Exceptions map to HTTP status codes in config

Before 5.4, mapping an exception class to an HTTP status code meant implementing HttpExceptionInterface or writing a listener. Now it’s just a YAML entry:

# config/packages/framework.yaml
framework:
    exceptions:
        App\Exception\PaymentRequiredException:
            status_code: 402
            log_level: warning
        App\Exception\MaintenanceException:
            status_code: 503
            log_level: info

The exception doesn’t need to implement anything. The framework reads the map, sets the status code, logs at the configured level. Handy for domain exceptions that have no business knowing about HTTP.

Two new validator constraints

5.4 adds Cidr and CssColor to the Validator component.

Cidr validates network notation — IP address plus subnet mask — with control over which IP version to accept and bounds on the mask value:

#[Assert\Cidr(version: 4, netmaskMin: 16, netmaskMax: 28)]
private string $allowedSubnet;

CssColor validates that a string is a valid CSS color. Useful for theme editors, CMS config, or any UI that lets users pick colors:

#[Assert\CssColor(
    formats: Assert\CssColor::HEX_LONG,
    message: 'The accent color must be a 6-digit hex value.',
)]
private string $accentColor;

Nested PHP attributes for validation constraints

Symfony 5.2 added validator constraints as PHP attributes, but PHP 8.0 had a hard limit on nested attributes. Complex constraints like All, Collection, or AtLeastOneOf were impossible to express in attribute syntax alone. PHP 8.1 lifted that restriction, and 5.4 makes the most of it:

use Symfony\Component\Validator\Constraints as Assert;

class CartItem
{
    #[Assert\All([
        new Assert\NotNull(),
        new Assert\Range(min: 1),
    ])]
    private array $quantities;

    #[Assert\AtLeastOneOf(
        constraints: [new Assert\Email(), new Assert\Url()],
        message: 'Must be a valid email or URL.',
    )]
    private string $contact;
}

No annotation doc-blocks, no XML mapping. Pure PHP 8.1 attributes all the way down.

Dependency injection: three things worth knowing

Tagged iterators can now be injected into service locators, which previously only accepted explicit service lists. Union type autowiring works when both sides of the union resolve to the same service, which is common with serializer interfaces:

public function __construct(
    private NormalizerInterface & DenormalizerInterface $serializer
) {}

#[SubscribedService] replaces the automatic introspection that ServiceSubscriberTrait did implicitly. It’s now an explicit attribute on methods, which makes the dependency visible without any magic:

use Symfony\Contracts\Service\Attribute\SubscribedService;

class SomeService implements ServiceSubscriberInterface
{
    #[SubscribedService]
    private function router(): RouterInterface
    {
        return $this->container->get(__METHOD__);
    }
}

Messenger: attributes, worker state, and service reset

Messenger handlers can drop the MessageHandlerInterface in favor of #[AsMessageHandler], which also lets you bind a handler to a specific transport and set its priority, all without touching YAML:

#[AsMessageHandler(fromTransport: 'async', priority: 10)]
class ProcessOrderHandler
{
    public function __invoke(ProcessOrder $message): void { /* ... */ }
}

Worker state is now inspectable via WorkerMetadata inside event listeners, useful when you have workers on multiple transports and need to know which one fired a given event.

Long-running workers accumulate state across messages: entity manager buffers, in-memory caches, open connections. The new reset_on_message option takes care of resetting all resettable services between messages:

framework:
    messenger:
        reset_on_message: true

Serializer: collect errors instead of throwing

Deserializing external JSON into a typed DTO used to throw on the very first type mismatch. The COLLECT_DENORMALIZATION_ERRORS option changes that: all type errors get collected into a PartialDenormalizationException, so you can return a proper 400 with a full list of field-level problems:

try {
    $dto = $serializer->deserialize($request->getContent(), OrderDto::class, 'json', [
        DenormalizerInterface::COLLECT_DENORMALIZATION_ERRORS => true,
    ]);
} catch (PartialDenormalizationException $e) {
    return $this->json(
        array_map(fn($err) => ['path' => $err->getPath(), 'expected' => $err->getExpectedTypes()], $e->getErrors()),
        400
    );
}

The serializer’s default context can also be set globally in YAML, so you stop passing the same options on every call.

Language negotiation out of the box

Two new framework options handle the Accept-Language header without custom listeners:

framework:
    enabled_locales: ['en', 'fr', 'de']
    set_locale_from_accept_language: true
    set_content_language_from_locale: true

With this in place, Symfony reads the browser’s preferred language, picks the best match from enabled_locales, sets the request locale, and adds a Content-Language header to the response. The {_locale} route attribute still takes precedence when present.

Translation: extraction, not update

The translation:update command is renamed to translation:extract. The old name sticks around as deprecated. The distinction matters: the command never writes to a database, it extracts translatable strings from source files. The new name finally says what it does.

lint:xliff also gains a --format=github option that outputs errors as GitHub Actions annotations, so translation lint failures show up as PR review comments instead of getting buried in log output.

Controller shortcuts pruned

Three AbstractController shortcuts are deprecated: getDoctrine(), dispatchMessage(), and the generic get() method for pulling arbitrary services from the container. The direction is explicit constructor injection. For getDoctrine() specifically:

// before
$em = $this->getDoctrine()->getManager();

// after — inject it directly
public function __construct(private EntityManagerInterface $em) {}

Request::get() is also deprecated. It searched route attributes, query string, and POST body in an undocumented order, which was a great way to get surprising results. Use $request->query->get(), $request->request->get(), or $request->attributes->get() and be explicit about where the value comes from.

The Path utility class

The Filesystem component gets a Path class ported from webmozart/path-util. It handles the awkward cases that dirname() and realpath() fumble:

use Symfony\Component\Filesystem\Path;

Path::canonicalize('../config/../config/services.yaml'); // '../config/services.yaml'
Path::getDirectory('C:/');                               // 'C:/' (dirname() returns '.')
Path::getLongestCommonBasePath([
    '/var/www/project/src/Controller/FooController.php',
    '/var/www/project/src/Controller/BarController.php',
    '/var/www/project/src/Entity/User.php',
]);
// '/var/www/project/src'

Useful whenever your code deals with paths that cross OS boundaries or involve relative segments.

Smaller things that add up

debug:dotenv shows which .env files were loaded and what value each variable resolves to. The first thing you reach for when environment-specific behavior is acting up.

The String component adds trimPrefix() and trimSuffix() for removing known prefixes or suffixes without writing a substr calculation:

u('file-image-0001.png')->trimPrefix('file-');    // 'image-0001.png'
u('template.html.twig')->trimSuffix('.twig');      // 'template.html'

DomCrawler gets innerText(), which returns only the direct text of a node, excluding child elements. text() returns everything including nested text; innerText() returns just the node’s own content. Small difference, but it matters when scraping.

The RateLimiter component extends its interval support to perMonth() and perYear(), for apps that need to limit events over longer windows: newsletter sends, API quota resets, annual plan limits.

The Finder component now respects .gitignore files in all subdirectories when you call ignoreVCSIgnored(true), not just the root. Child directory rules override parent rules, exactly like git itself.

The LTS window

5.4 gets bug fixes until November 2024 and security fixes until November 2025. The migration from 5.4 to 6.4 (the next LTS) is intentionally smooth: fix the 5.4 deprecation warnings, and the 6.x jump is mechanical.

The deprecation layer in 5.4 points at everything 6.0 removes: the remaining pieces of the old security system, ContainerAwareTrait, and a handful of legacy form and serializer patterns.

Enums

This is the one that changes codebases the moment you upgrade. Before 8.1, PHP enumerations were either class constants, strings, or integers with nothing enforcing them:

// before: nothing stops Status::INVALID from being passed
const ACTIVE = 'active';
const INACTIVE = 'inactive';

// after
enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

function activate(Status $status): void { ... }

PHP enums are objects, not scalars. They support methods, interfaces, and constants. Backed enums (with a string or int value) serialize cleanly and map to database columns naturally. Pure enums (no backing type) enforce domain concepts without worrying about serialization.

The immediate effect: every status field, every finite set of states in every codebase I maintain became an enum candidate. The type system finally has a native way to express the thing every PHP project has been faking for years.

Fibers

Fibers are a cooperative concurrency primitive: you can pause and resume execution of a function, yielding control without threads.

$fiber = new Fiber(function(): void {
    $value = Fiber::suspend('first');
    echo "Resumed with: {$value}\n";
});

$result = $fiber->start();    // 'first'
$fiber->resume('hello');      // "Resumed with: hello"

Fibers are the foundation async libraries like ReactPHP and Amp have needed from the runtime for a while. For most application developers the direct API matters less than the libraries built on top of it, but understanding fibers explains what those libraries are doing underneath.

:pencil2: Readonly properties

8.0 brought constructor promotion. 8.1 adds readonly:

class User {
    public function __construct(
        public readonly int $id,
        public readonly string $name,
    ) {}
}

A readonly property can be written exactly once, during initialization. After that, any write throws an Error. Combined with constructor promotion, value objects and DTOs become concise and actually mean what they say.

First-class callable syntax

$fn = strlen(...);
$fn = $this->process(...);
$fn = MyClass::create(...);

... after a callable creates a Closure without Closure::fromCallable() boilerplate. Useful when passing methods as callbacks.

8.1 is precise. Enums alone justify the upgrade.

Intersection types

Union types landed in 8.0. Intersection types follow in 8.1. Where a union says “one of these”, an intersection says “all of these”:

function process(Countable&Iterator $collection): void {
    foreach ($collection as $item) { /* ... */ }
    echo count($collection);
}

One constraint: intersection types can’t be mixed with union types in the same declaration (that arrives in 8.2 as DNF types). But this already unlocks precise type-checking for objects that must satisfy multiple interfaces at once, a pattern frameworks use constantly that had to stay untyped until now.

The never return type

A function that never returns (it always throws or exits) now has a type to say so:

function redirect(string $url): never {
    header("Location: {$url}");
    exit();
}

function fail(string $message): never {
    throw new \RuntimeException($message);
}

The practical benefit: static analyzers can prove that code after a never function is unreachable, and callers know there’s no return value to handle. Before this, it lived in docblocks with no enforcement.

Final class constants

Before 8.1, any subclass could quietly override a parent’s class constant. Now you can put a stop to that:

class Base {
    final public const VERSION = '1.0';
}

class Child extends Base {
    // Fatal error: Cannot override final constant Base::VERSION
    public const VERSION = '2.0';
}

Relatedly, interface constants are now overridable by implementing classes by default. A separate behavior fix that had been inconsistent since interfaces were introduced.

new in initializers

Default parameter values used to be restricted to scalars and arrays. 8.1 drops that restriction:

class Logger {
    public function __construct(
        private Handler $handler = new NullHandler(),
    ) {}
}

function createUser(
    Validator $validator = new DefaultValidator(),
): User { /* ... */ }

Same goes for attribute arguments and static variable initializers. Which means dependency injection with sensible defaults no longer needs a null check and lazy instantiation inside the method body.

Array unpacking with string keys

Array unpacking via the spread operator only worked with integer-keyed arrays before 8.1. String keys work now too:

$defaults = ['color' => 'red', 'size' => 'M'];
$custom = ['size' => 'L', 'weight' => '200g'];

$merged = [...$defaults, ...$custom];
// ['color' => 'red', 'size' => 'L', 'weight' => '200g']

Later keys override earlier ones. Same behavior as array_merge(), but expressed inline. Performance difference is marginal; readability difference is not.

fsync and fdatasync

Two functions that had no good reason to be missing from a filesystem-oriented language:

$fp = fopen('/tmp/important.dat', 'w');
fwrite($fp, $data);
fsync($fp);   // flush OS buffers to physical storage
fclose($fp);

fdatasync() does the same but skips metadata sync when you only care about the data being durable. Both return false on failure. If you’re writing anything that needs crash safety, you needed these.

Passing null to non-nullable built-in parameters

A quieter but consequential change: built-in functions that accept strings, integers, etc. have always silently swallowed null and coerced it. In 8.1, that starts emitting a deprecation notice.

str_contains("foobar", null);
// Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated

This aligns built-in functions with user-defined functions, which already refused nullable arguments for non-nullable parameters. PHP 9.0 turns this into a hard error. If you’re passing null into string functions, now is a better time to fix it than during a production incident.

MySQLi exceptions by default

Before 8.1, MySQLi failed silently unless you explicitly called mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT). That’s now the default:

// This throws \mysqli_sql_exception on connection failure in 8.1
// Previously returned false and set an error you had to check manually
$connection = new mysqli('localhost', 'user', 'wrong_password', 'db');

Every codebase that catches MySQLi errors by checking return values needs to be reviewed. The silent failures that caused hard-to-diagnose bugs now throw exceptions, which is the right behavior, just potentially surprising if you hit it mid-upgrade.