DEV Community: Matt Mochalkin

Mastering Claude Code & Gemini Code Assist: Implementing the Agent Skills Architecture

Matt Mochalkin — Tue, 07 Apr 2026 15:26:07 +0000

The landscape of AI-assisted development has fundamentally shifted from passive autocomplete to active, agentic workflows. Tools like Claude Code (a powerful CLI agent) and Gemini Code Assist (a deeply integrated IDE agent) can read your file system, execute terminal commands and navigate your project context.

However, true power unlocks when you teach these agents your proprietary workflows. By utilizing Agent Skills (markdown-based instructions) and MCP Servers (active programmatic tools), you can transform these assistants into customized junior developers.

The Architectural Hierarchy of Agent Skills

Before writing code, we must understand how modern AI agents discover what they are allowed to do. The AI industry is converging on an open standard for defining skills via directory structures. When you launch Gemini Code Assist or Claude Code the engine scans specific file paths to load capabilities into its context window.

There are three distinct tiers of skill discovery:

Workspace Skills (Project-Specific)

Locations: .gemini/skills/, .claude/skills/ or the unified .agents/skills/ alias within your project’s root directory.

These are isolated to the current repository. Use this tier for local database migration commands, project-specific deployment scripts or PR review guidelines unique to the team.

Always commit this folder to version control so your entire team shares the same AI workflows.

User Skills (Global/Personal)

Locations: ~/.gemini/skills/, ~/.claude/skills/ or ~/.agents/skills/ located in your system’s Home directory.

These are your global, personal developer tools available across any project you open. Use this for your preferred Git commit formatting style, personal Docker cleanup scripts or customized syntax preferences.

Keep these purely local. They represent how you like to work, keeping shared repositories free of personal configuration.

Extension Skills (Bundled)

When you install third-party extensions (like a Jira or AWS plugin) into your IDE or CLI, they bundle their own skills.

These are generally read-only and managed by the extension provider, granting the AI immediate access to external APIs.

The Power of the .agents/skills/ Alias: > Using the .agents/skills/ directory is highly recommended. It acts as a universal standard. If you write a skill and place it in .agents/skills/, both Claude Code and Gemini Code Assist can theoretically discover and utilize it, making your custom developer tools perfectly portable across different AI ecosystems.

Building Skills

Let’s create a shared team skill that teaches AI exactly how to scaffold a new React component according to your company’s strict architecture guidelines.

Create the Directory Structure

In the root of your project terminal, create the folder using the universal alias:

mkdir -p .agents/skills/scaffold-component
touch .agents/skills/scaffold-component/SKILL.md

Write the Scaffolding Protocol Skill Definition

Open SKILL.md. This file acts as both the trigger and the execution instructions.

---
name: scaffold-component
description: "Generates a new React component strictly following company architecture rules (Tailwind, TypeScript, Vitest)."
---

# Component Scaffolding Protocol

You have been asked to create a new UI component. You must strictly follow these local workspace rules:

## Rules of Execution
1.  **Location:** All components must be created inside `src/components/`.
2.  **Language:** Use TypeScript (`.tsx`).
3.  **Styling:** You MUST use Tailwind CSS. Do not generate `.css` or `.scss` files.
4.  **Testing:** For every component, you must generate an adjacent test file named `[ComponentName].test.tsx` using Vitest syntax.
5.  **Exporting:** Always use named exports. Never use default exports.

## Execution Steps
1. Ask the user for the name of the component if they haven't provided it.
2. Generate the `.tsx` file.
3. Generate the `.test.tsx` file.
4. Run standard formatting on the newly created files.

This is in the Workspace tier, when any developer on your team opens the AI Assistant chat and asks, “Can you scaffold a user profile card?”, AI reads this skill, adopts the rules and perfectly mimics your senior developer’s coding standards.

Write the Frontmatter and Logic Skill Definition

---
name: clean-docker
description: Analyzes currently running Docker containers and safely stops/removes them.
disable-model-invocation: true
---

# Docker Cleanup Assistant

You are a DevOps assistant. The user wants to clean up their local Docker environment.

## Current Environment Context
Here is the raw output of the user's current Docker processes:
!`docker ps -a`

## Instructions
1. Analyze the output provided above.
2. Identify any containers that have a status of "Exited".
3. Identify any containers that look like temporary test databases or dangling instances.
4. Present a formatted list to the user summarizing what is currently running and what is stopped.
5. Ask the user for confirmation on which containers they would like to remove.
6. Once confirmed, use your bash execution tools to run `docker rm [CONTAINER_ID]`.

By setting disable-model-invocation: true, we ensure Claude/Gemini doesn’t randomly delete your containers. You must trigger this manually by typing /clean-docker in the Claude Code CLI. Claude reads the file, runs docker ps -a in the background, injects the output into the prompt and then logically guides you through the cleanup process.

Architectural Best Practices for AI Skills

As you build out your .agents/skills/ directories, keep these theoretical principles in mind to maintain a healthy codebase:

Principle of Least Privilege

When giving an agent shell access or database access via MCP, restrict the API tokens and database users you provide to the script. If the agent hallucinates a DROP TABLE command, your database user should lack the permissions to execute it.

Semantic Prompt Weighting

When writing the description in your YAML frontmatter remember that the description is the compiled code. The LLM uses semantic vector mapping to match a user’s intent to your tool description.

Poor description: “Manages versions”

Excellent description: “Increments the semantic version in package.json. Use this strictly when preparing a release or hotfix.”

Context Window Pruning

If your MCP servers return massive logs (e.g., fetching 10,000 lines of AWS CloudWatch logs), the AI will suffer from “Lost in the Middle” syndrome, forgetting its original instructions. Always write your tools to filter, summarize or paginate data before returning it to the SKILL.md context.

Integrating Third-Party MCP Servers and Cross-Skill Workflows

However, the open-source community is rapidly building pre-made MCP servers that you can plug directly into your AI environment.

We are going to install the mattleads/telegramBotMcp server to give our agent the ability to send messages and then we will update our existing skills to trigger a Telegram notification the moment they finish their work.

Installing the Telegram Bot MCP Server

While the exact installation command depends on how the repository is structured (Node.js vs. Python), the configuration principle in your agent settings remains the same. You need to provide the execution command and inject your secret Telegram Bot Token as an environment variable.

Get the Source Code

Clone the repository to your machine and install its dependencies (assuming a standard Node.js/TypeScript MCP setup):

cd ~/path/to/your/tools
git clone https://github.com/mattleads/telegramBotMcp.git
cd telegramBotMcp
npm install
npm run build

Configure the Agent Settings

Now, we must tell Claude Code or Gemini CLI where this server is and give it your API credentials.

For Gemini Code Assist: Edit ~/.gemini/settings.json

For Claude Desktop/CLI: Edit ~/.claude/claude_desktop_config.json

Add the Telegram server configuration alongside your existing tools. Notice how we pass the secure tokens via the env object:

{
  "mcpServers": {
    "telegram-notifier": {
      "command": "node",
      "args": [
        "/path/to/tools/telegramBotMcp/build/index.js"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "123456789:ABCDEF_Your_Bot_Token_Here"
      }
    }
  }
}

Once you restart your IDE or CLI, the agent will parse this MCP server and expose its tools (e.g. send_telegram_message) to the context window.

Cross-Skill Communication: The “Notification” Workflow

Now for the magic. How do we make one skill trigger another?

In the world of LLM agents, skills do not call other skills via hardcoded function pointers. Instead, the LLM orchestrates them. You create cross-skill communication by writing explicit instructions in your SKILL.md file, telling the agent to invoke the Telegram tool as its final execution step.

Let’s upgrade the Workspace Skill we built earlier (scaffold-component) to include a Telegram notification workflow.

Update the SKILL.md

Open your .agents/skills/scaffold-component/SKILL.md file and add a new “Completion Protocol” section.

---
name: scaffold-component
description: Generates a new React component and notifies the team via Telegram when complete.
---

# Component Scaffolding Protocol

You are an expert frontend developer. Follow these instructions perfectly.

## Execution Steps
1. Ask the user for the name of the component if not provided.
2. Generate the `.tsx` file in `src/components/` using Tailwind CSS and named exports.
3. Generate the `.test.tsx` file using Vitest.
4. Run standard formatting on the files.

## Completion Protocol (Cross-Tool Notification)
Once all files are created and formatted, you must alert the team that the component is ready for integration. 

1. Use the `send_telegram_message` tool provided by your MCP environment.
2. Format the message as follows:
   `🚀 Component Scaffolding Complete!`
   `Name: [Component Name]`
   `Files created: [List of files]`
   `Status: Ready for review.`
3. Send the message. Do not ask for the user's permission to send the notification, do it automatically as the final step of this workflow.

How the Execution Loop Works

When you type /scaffold-component UserProfile in your terminal or IDE, here is the exact chronological flow the agent executes:

Read Rules: The agent reads the .agents/skills/scaffold-component/SKILL.md file.
File System Tools: It uses its built-in Write_File tools to create UserProfile.tsx and UserProfile.test.tsx.
Observation: It observes that the files were created successfully.
Tool Transition: It reads the “Completion Protocol”. It searches its context window for a tool matching the description of sending Telegram messages.
MCP Execution: It finds the send_telegram_message tool (injected via your settings.json) and outputs a JSON payload with the formatted text.
Delivery: The telegramBotMcp local node script runs, hits the Telegram API and your phone buzzes with the update!

By combining Markdown rules (SKILL.md) with dynamic MCP servers (telegramBotMcp), you transform your agent from a simple code generator into a fully automated project manager.

Conclusion

We have covered an incredible amount of ground in this guide. By moving beyond standard chat interfaces, you have learned how to fundamentally rewire your development environment. You are no longer just writing code; you are engineering your own AI-powered junior developer.

Let’s recap the core architectural pillars you can now use to build your ultimate workflow:

The Open Standard (.agents/skills/): By utilizing Workspace and User skill tiers, you create highly organized, portable Markdown workflows that work seamlessly across both Claude Code and Gemini Code Assist.
Model Context Protocol (MCP): You have unlocked the ability to bridge the gap between deterministic local scripts and probabilistic AI, allowing your agents to query databases, read APIs and perform complex logic safely.
Agentic Orchestration: By chaining tools together — such as generating a React component and autonomously firing off a Telegram notification — you have built a true, multi-step agentic loop.

The beauty of modern AI coding assistants is their extensibility. Your IDE and your terminal are now blank canvases. Whether you want to build a skill that automatically reviews your pull requests against company security standards, a tool that manages your local Docker containers or a workflow that updates Jira tickets when you commit code, you now have the exact architectural blueprint to build it.

I hope this definitive guide empowers you to start writing your own SKILL.md files and using MCP servers today!

Source Code: You can find the full implementation and follow the TelegramBot MCP Server progress on GitHub: [https://github.com/mattleads/telegramBotMcp]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]

10x Less RAM: The Senior Guide to Native JSON Streaming in Symfony

Matt Mochalkin — Sat, 04 Apr 2026 14:55:09 +0000

As PHP applications scale, they inevitably face the terrifying “OOM killer” (Out Of Memory). One of the most notorious culprits for memory exhaustion in a modern Symfony API is parsing massive JSON files or webhooks. When a partner throws a 2GB product catalog at your system, standard PHP functions simply surrender.

Historically, developers relied on third-party libraries or complex chunking scripts to survive. However, with the stabilization of Symfony 7.4, the core team has provided a deeply integrated, native solution: the symfony/json-streamer component.

In this comprehensive, advanced guide, we will explore how to architect a bulletproof JSON streaming solution. We will learn how to bypass memory limits, stream directly into highly optimized Data Transfer Objects (DTOs) and avoid the hidden memory traps that even senior developers fall into.

The Memory Trap

Why json_decode() and Serializer Fail? Before implementing the solution, we must understand the mechanics of the problem.

The native PHP json_decode() function — and by extension, the symfony/serializer which relies on it — operates using a Document Object Model (DOM) approach to parsing. This means it must load the entire JSON string into memory, evaluate its syntax and then build a massive internal structure (an associative array or object tree) to represent it.

If you have a 100MB JSON file, loading the string takes 100MB. Parsing it into a PHP array expands its memory footprint by 3 to 5 times due to PHP’s internal Hash Table overhead. Suddenly, your background worker requires 500MB of RAM just to read a file! If you then pass this array to the Symfony Serializer to denormalize it into DTOs, you effectively hold the data in memory three separate times.

Streaming (or Pull Parsing) solves this. A streamer reads the JSON byte-by-byte from an I/O stream (like a file or an HTTP response). It keeps only a microscopic, constant amount of data in RAM — just enough to yield the current item before discarding it and moving to the next.

The Native Solution

Components and Installation

Symfony 7.4 provides a native ecosystem for memory-safe processing through a combination of three distinct components working in unison:

symfony/json-streamer: Handles reading the raw bytes and tracking the JSON token states.
symfony/type-info: Provides strict, reflective typing instructions so the streamer knows exactly what PHP structures to build.
symfony/object-mapper (Optional but recommended): A blazingly fast hydration tool that is significantly more memory-efficient than the traditional Serializer for direct object-to-object mapping.

Installation and Verification Steps

Open your terminal and require the core libraries in your Symfony 7.4 project:

composer require symfony/json-streamer symfony/type-info symfony/http-client symfony/object-mapper

Architecting the DTO

The magic of streaming lies in Generators. Instead of loading a 2GB string into memory, parsing it into a 3GB associative array and then hydrating 250,000 objects (spiking your RAM to 5GB+), we read the file byte-by-byte over the network.

As soon as a single JSON object is fully read, Symfony hydrates it into a typed DTO and yields it. Once you process that DTO (e.g., save it to the database) and move to the next loop iteration, the PHP garbage collector frees the memory.

The JsonStreamer component works best with pure Data Transfer Objects (DTOs). These are classes that rely strictly on typed public properties.

To achieve maximum performance, Symfony provides the #[JsonStreamable] attribute. When applied, Symfony pre-generates highly optimized encoding and decoding PHP files during your cache warm-up, completely bypassing slow reflection during runtime!

namespace App\Dto;

use Symfony\Component\JsonStreamer\Attribute\JsonStreamable;
use Symfony\Component\JsonStreamer\Attribute\StreamedName;
use Symfony\Component\TypeInfo\Type;

#[JsonStreamable]
class ProductDto
{
    // You can map specific JSON keys to your PHP properties
    #[StreamedName('@id')]
    public string $id;

    public string $sku;

    public float $price;

    public static function getListType(): Type
    {
        // We define the value type (ProductDto) and the key type (int)
        return Type::iterable(Type::object(self::class), Type::int());
    }
}

The Critical Memory Trap (Type::list vs Type::iterable)

This is the most crucial architectural decision in this entire guide.

When instructing the JsonStreamer on how to parse an array of JSON objects, developers instinctively reach for Type::list(Type::object(ProductDto::class)).

Do not do this for massive files.

If you use Type::list(), the streamer obediently reads the file chunk-by-chunk (saving string memory), but it takes every single hydrated DTO and stuffs them all into a single, massive PHP array before returning the final result. If your file has 250,000 items, your memory usage will instantly explode to over 2 Gigabytes.

By using Type::iterable() (as demonstrated in our DTO helper method above), the read() method instantly returns a PHP Generator. As you iterate through your loop, the JsonStreamer reads just enough bytes to build one object, yields it to you and allows PHP’s garbage collector to destroy it before building the next one. This drops memory usage from 2.4 GB down to a perfectly flat ~12 MB.

Building the Importer Service

Let’s build a service that fetches a massive remote JSON file (like an upstream catalog) and parses it directly into our DTOs without spiking memory.

namespace App\Service;

use App\Dto\ProductDto;
use Symfony\Component\JsonStreamer\StreamReaderInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;

/**
 * Handles the streaming of massive JSON product catalogs natively.
 */
readonly class ProductImporter implements ProductImporterInterface
{
    public function __construct(
        private HttpClientInterface $httpClient,
        // Inject the native stream reader
        private StreamReaderInterface $streamReader,
    ) {}

    /**
     * @param string $url The upstream API URL
     * @return \Generator<ProductDto>
     */
    public function importFromApi(string $url): \Generator
    {
        // 1. Initiate the request. HttpClient is asynchronous by default.
        $response = $this->httpClient->request('GET', $url);

        // 2. We pass the raw HttpClient response directly into the reader!
        // It reads the network stream chunk by chunk automatically.
        $products = $this->streamReader->read($response->toStream(), ProductDto::getListType());

        // 3. Yield the hydrated DTOs one by one.
        foreach ($products as $product) {
            yield $product;
        }
    }
}

Native Network Chunking: We never call $response->toArray() or $response->getContent(). The streamReader->read() method interfaces directly with the raw socket, parsing bytes exactly as they arrive over the network.
TypeInfo Integration: By passing our custom Type::iterable(), the component bypasses generic arrays and hydrates strictly typed properties instantly.

Execution and Batching

Background commands (like cron jobs or message queue workers) are where this logic belongs. Let’s create a command to execute our stream.

We will also include advanced benchmarking techniques. To properly benchmark memory in PHP, we must use PHP memory_reset_peak_usage() to ensure the Zend Memory Manager gives us an accurate reading of the current process, free from the inherited memory overhead of previous script executions.

namespace App\Command;

use App\Service\ProductImporterInterface;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

#[AsCommand(
    name: 'app:sync-products',
    description: 'Streams a massive product API incrementally.',
)]
class SyncProductsCommand extends Command
{
    public function __construct(
        private readonly ProductImporterInterface $importer,
    ) {
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);
        $io->title('Starting Native Memory-Efficient Sync');

        $startMemory = memory_get_usage(true);
        $count = 0;

        // Fetch the generator
        $products = $this->importer->importFromApi('https://massive-catalog.example.com/api/products');

        // Iterate over the generator. Memory remains flat!
        foreach ($products as $product) {
            // $product is an instance of App\Dto\ProductDto
            // E.g., $this->entityManager->persist($product);

            $count++;

            // Example of batch clearing Doctrine to prevent database memory leaks
            // if ($count % 500 === 0) { $this->entityManager->flush(); $this->entityManager->clear(); }
        }

        $endMemory = memory_get_usage(true);
        $memoryUsed = ($endMemory - $startMemory) / 1024 / 1024;

        $io->success(sprintf('Successfully processed %d products!', $count));
        $io->info(sprintf('Total memory consumed during loop: %.2f MB', $memoryUsed));

        return Command::SUCCESS;
    }
}

Going the Other Way: Writing Streams

The component is bidirectional. If your application needs to serve a massive JSON file to a client, you can use the StreamWriterInterface alongside a controller to prevent your web server from crashing.

namespace App\Controller;

use App\Dto\ProductDto;
use App\Provider\ProductProviderInterface;
use Symfony\Component\HttpFoundation\StreamedResponse;
use Symfony\Component\JsonStreamer\StreamWriterInterface;
use Symfony\Component\Routing\Attribute\Route;

readonly class ExportController
{
    public function __construct(
        private StreamWriterInterface    $streamWriter,
        private ProductProviderInterface $productProvider,
    ) {}

    #[Route('/api/export', name: 'api_export', methods: ['GET'])]
    public function export(): StreamedResponse
    {
        $response = new StreamedResponse(function () {
            // Write directly to standard output
            $outputStream = fopen('php://output', 'w');

            // The StreamWriter converts the generator of DTOs directly into a JSON string stream
            $jsonStream = $this->streamWriter->write(
                $this->productProvider->getProducts(),
                ProductDto::getListType()
            );

            fwrite($outputStream, (string) $jsonStream);
            fclose($outputStream);
        });

        $response->headers->set('Content-Type', 'application/json');

        return $response;
    }
}

By wrapping our logic inside Symfony’s native StreamedResponse, the web server holds the connection open and sends the JSON chunks exactly as StreamWriterInterface produces them. Your server’s memory will remain flat, allowing you to serve gigabytes of data concurrently without exhausting PHP FPM workers.

It’s one thing to say “streaming is better,” but as engineers, we demand proof. To validate the efficiency of the new symfony/json-streamer we built a rigorous benchmark command comparing 6 different approaches to JSON processing.

Methodology

To ensure an absolutely fair “apples-to-apples” comparison, our methodology was strictly controlled:

The Dataset: A locally generated benchmark_data.json file containing exactly 250,000 product records.
Isolation: Before each benchmark run, we explicitly called gc_collect_cycles() to clear orphaned memory from the previous test.
True Peak Measurement: We utilized PHP new memory_reset_peak_usage() function immediately before starting the timer for each test. This guarantees that the peak memory reported was strictly caused by the current method, not leftover high-water marks.
Hydration Parity: Where applicable, tests were designed to hydrate strict ProductDto objects to simulate real-world Symfony applications.

The Contenders

Standard json_decode(): Loads the whole file and returns a massive associative array.
json_decode() + Serializer->denormalize(): Array hydration using the classic Symfony Serializer.
Serializer->deserialize(): Direct string-to-object array hydration.
json_decode(false) + ObjectMapper->map(): Decoding to stdClass and mapping (a known performance trick).
halaxa/json-machine + ObjectMapper: The industry-standard third-party pull parser, configured to yield stdClass for fast ObjectMapper hydration.
Native symfony/json-streamer: The new native component reading from an fopen() stream.

+------------------------------+-----------+-------------+------------------------------------------------------------+
| Approach                     | Exec Time | Peak Memory | Notes                                                      |
+------------------------------+-----------+-------------+------------------------------------------------------------+
| 1. Standard json_decode()    | ~0.07s    | ~162 MB     | Fast, but memory scales linearly. Crashes on 1GB+ files.   |
| 2. Serializer->denormalize() | ~4.49s    | ~163 MB     | Hydrates DTOs, but slow/heavy due to reflection.           |
| 3. Serializer->deserialize() | ~5.07s    | ~340 MB     | Memory consumed by massive source string and object array. |
| 4. ObjectMapper->map()       | ~3.64s    | ~174 MB     | Fast hydration, but 250k stdClass objects cause RAM spike. |
| 5. halaxa/json-machine       | ~4.95s    | ~12 MB      | Fast & flat memory via native optimizations.               |
| 6. symfony/json-streamer     | ~2.65s    | ~12 MB      | The Winner! Industry standard pull parser.                 |
+------------------------------+-----------+-------------+------------------------------------------------------------+

Analyzing the Data

The standard json_decode approaches highlight the classic memory trap: memory usage scales proportionately with payload size.

While halaxa/json-machine combined with the ObjectMapper proved to be an incredibly capable and memory-safe solution, the native Symfony JSON Streamer took the crown.

Because symfony/json-streamer leverages cache-warmup code generation via the #[JsonStreamable] attribute, it bypasses runtime reflection entirely. This allows it to hydrate strict PHP objects from a stream faster than third-party alternatives, while maintaining a flawless ~2.5MB flat memory footprint regardless of whether the file is 10MB or 10GB.

Conclusion

Handling massive JSON payloads no longer requires architectural gymnastics, batch processing scripts or adding third-party dependencies to your composer.json.

By adopting symfony/json-streamer, symfony/type-info and strict DTOs you can build enterprise-grade data pipelines that are memory-safe, strictly typed and natively integrated into the Symfony ecosystem.

Remember the golden rules of scaling JSON in Symfony:

Never load large payloads as strings. Pass Streams or HttpClient responses directly to the reader.
Always use Type::iterable(). Supplying Type::list() creates massive arrays in memory, defeating the purpose of the streamer.
Control your external boundaries. Streaming saves memory during parsing, but you must still batch your Doctrine inserts or message dispatchers to prevent downstream memory leaks.

Source Code: You can find the full implementation and follow the project’s progress on GitHub: [https://github.com/mattleads/JsonStreamer]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]

Next-Gen CLI Apps in PHP: A Deep Dive into Symfony TUI

Matt Mochalkin — Tue, 31 Mar 2026 11:01:53 +0000

For over a decade, PHP developers have relied on the symfony/console component as the gold standard for building CLI applications. It gave us beautifully formatted output, robust input validation and progress bars. But fundamentally, the paradigm remained the same: Immediate Mode.

In immediate mode, your script executes top-to-bottom. If you want to show a progress bar, you must calculate the state, format a string and explicitly echo ANSI escape codes to redraw that specific terminal line. If an HTTP request blocks the main thread, your entire terminal interface freezes.

But what if your CLI application could behave like a modern frontend application? What if you could declare a tree of widgets — containers, text inputs, markdown renderers — and let a rendering engine intelligently diff the screen state, capturing keystrokes and updating UI components asynchronously?

symfony/tui

Currently in the experimental phase, this groundbreaking new component shifts PHP CLI development to a Retained Mode architecture, powered by PHP 8.4 Fibers and the Revolt Event Loop.

In this comprehensive guide, we are going to build two robust applications using the exact bleeding-edge code of the symfony/tui component. We will cover environment setup, responsive styling, event dispatching, focus management and true concurrency.

Fibers, Event Loops and PHP 8.4

Before we write code, we must understand the architectural shift. symfony/tui is strictly locked to PHP 8.4+.

Why? Because it relies heavily on native PHP Fibers to manage state without blocking the execution thread. It pairs Fibers with Revolt, a robust event loop for PHP.

This means your TUI is single-threaded but fully concurrent. Animations (like loaders) keep spinning, API requests process in the background and user keystrokes are captured instantly without interrupting the rendering cycle.

Bleeding-Edge Installation & Setup

As of this writing, symfony/tui is an active Pull Request on the main symfony/symfony repository. You cannot run composer require symfony/tui just yet. We must manually map the experimental branch via Composer.

Create a Symfony 8 Project

composer create-project symfony/skeleton "8.0.*" my-tui-app
cd my-tui-app

Clone the Experimental Branch

Clone Fabien Potencier’s specific branch into a local vendor-src directory

mkdir -p vendor-src
git clone --branch tui --single-branch https://github.com/fabpot/symfony.git vendor-src/symfony

Configure Composer Path Repository

Tell Composer to look in our local checkout for the Tui component:

composer config repositories.symfony-tui path vendor-src/symfony/src/Symfony/Component/Tui

Install Require Dependencies

We will install the component itself, the Revolt event loop and standard Markdown parsing libraries for our rich text widgets.

composer require symfony/tui:dev-tui \
    revolt/event-loop \
    league/commonmark \
    tempest/highlight

Ensure your composer.json reflects PHP ^8.4 and the packages above. You can run php -v to confirm your local CLI environment.

Core Concepts: Widgets, Stylesheets and Events

To transition from standard CLI commands to the TUI, you must adopt a DOM-like mindset.

The Widget Tree

Everything is a subclass of AbstractWidget. You compose a hierarchy by taking a ContainerWidget and calling $container->add($childWidget). When a widget’s internal state changes (e.g., calling $textWidget->setText()), it marks itself as dirty. The engine recalculates constraints and flushes only the necessary ANSI escape codes to the terminal.

The StyleSheet

Styling is no longer limited to basic ANSI foreground/background colors. symfony/tui implements a cascading style system. You can define a Stylesheet with CSS-like selectors or use built-in Tailwind-like utility classes directly on the widgets.

// Stylesheet approach
$stylesheet->addRule('.sidebar:focused', new Style(
    border: Border::all(1, 'rounded', 'cyan'),
    color: 'gray'
));

// Tailwind utility approach
$widget->addStyleClass('p-2 bg-emerald-500 bold border-rounded');

Event Dispatcher

The component natively integrates with symfony/event-dispatcher. Widgets emit events like SelectEvent, SelectionChangeEvent, FocusEvent and CancelEvent.

Tui’s complete widgets set:

TextWidget for labels, headings and FIGlet ASCII art banners
InputWidget for single-line text fields with cursor, scrolling and paste support
EditorWidget a full multi-line text editor with word wrap, undo/redo, a kill ring and autocomplete
SelectListWidget for scrollable, filterable pick lists
SettingsListWidget for preference panels with value cycling and submenus
TabsWidget for multi-view interfaces with horizontal or vertical headers (follow-up PR)
MarkdownWidget with full CommonMark support and syntax-highlighted code blocks
ImageWidget and AnimatedImageWidget for inline images (via the Kitty graphics protocol) and animated GIF playback as ASCII art (follow-up PR)
OverlayWidget for modal dialogs, dropdowns and floating panels (follow-up PR)
LoaderWidget, CancellableLoaderWidget and ProgressBarWidget for background operations

The Reactive Server Dashboard

Let’s start by building a classic operational dashboard. We want a scrollable list of servers on the bottom and a reactive header on top that changes text color depending on the user’s current selection.

namespace App\Command;

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Tui\Tui;
use Symfony\Component\Tui\Widget\ContainerWidget;
use Symfony\Component\Tui\Widget\TextWidget;
use Symfony\Component\Tui\Widget\SelectListWidget;
use Symfony\Component\Tui\Style\StyleSheet;
use Symfony\Component\Tui\Style\Style;
use Symfony\Component\Tui\Style\Border;
use Symfony\Component\Tui\Style\Padding;
use Symfony\Component\Tui\Style\Direction;
use Symfony\Component\Tui\Event\SelectEvent;
use Symfony\Component\Tui\Event\CancelEvent;

#[AsCommand(
    name: 'app:server-dashboard',
    description: 'Launches the interactive server management TUI.'
)]
class ServerDashboardCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // 1. Initialize the StyleSheet
        $stylesheet = new StyleSheet();

        $stylesheet->addRule('.dashboard-container', new Style(
            padding: Padding::all(2),
            border: Border::all(1, 'double', 'blue')
        ));

        // 2. Build the Header
        $header = new TextWidget('Server Status Dashboard');
        $header->addStyleClass('font-big text-cyan-400 bold mb-2');

        // 3. Build the Interactive List
        // Note: The experimental API expects associative arrays, not objects.
        $serverList = new SelectListWidget(
            items: [
                ['value' => 'srv-01', 'label' => 'Web Server 01', 'description' => 'Healthy - 20ms ping'],
                ['value' => 'srv-02', 'label' => 'Database Primary', 'description' => 'Warning - 80% CPU'],
                ['value' => 'srv-03', 'label' => 'Worker Node', 'description' => 'Healthy - Idle'],
            ],
            maxVisible: 10
        );

        // 4. Handle State and Events (Using ->on() instead of addEventListener)
        $serverList->on(SelectEvent::class, function (SelectEvent $event) use ($header) {
            $header->setText(sprintf('Monitoring: %s', $event->getValue()));
            $header->addStyleClass('text-emerald-500'); 
        });

        // 5. Compose the Layout Tree
        $container = new ContainerWidget();
        $container->setStyle(new Style(direction: Direction::Vertical));
        $container->add($header);
        $container->add($serverList);
        $container->addStyleClass('dashboard-container');

        // 6. Boot the TUI Engine
        $tui = new Tui($stylesheet);
        $tui->add($container);

        // 7. Graceful Exits
        $serverList->on(CancelEvent::class, function () use ($tui) {
            $tui->stop();
        });

        // Takes over the terminal buffer
        $tui->run();

        $output->writeln('<info>Dashboard session ended successfully.</info>');
        return Command::SUCCESS;
    }
}

How the Code Works

Separation of Concerns: We define our layout structure (ContainerWidget, TextWidget) independently of the terminal’s physical rendering engine.
Reactive State: When the SelectEvent fires (triggered when a user navigates to an item and hits Enter), we mutate the $header widget. The TUI engine automatically detects this mutation and flushes the minimal required ANSI escape codes to the terminal to update only the header.
Graceful Exits: Calling $tui->run() takes exclusive control of the terminal buffer. Once exited, the terminal state is completely restored, preventing the “garbled output” issue common in older CLI tools.
API Evolution: If you read early blogs on the TUI component, you might have seen $stylesheet = new Stylesheet() and $widget->addEventListener(). The actual, current implementation enforces strict casing (StyleSheet) and uses a concise ->on(Event::class, callback) method.
Object-Oriented Styling: Passing padding: 2 will throw a TypeError. You must use strongly typed immutable value objects: Padding::all(2) and Border::all(…).
Widget Composition: Instead of passing children arrays via constructors, we instantiate empty ContainerWidgets and use the fluent ->add() interface.

The “Kitchen Sink” Widget Demo

To truly appreciate the power of Symfony TUI, we must explore its advanced widgets: Text Inputs, Multiline Editors, Markdown Renderers and background-driven Progress Bars.

We are going to build a complex, multi-pane layout that simulates a Tabbed Interface. We will have a persistent navigation sidebar on the left and a dynamic content pane on the right.

Layout & Custom Focus Management
By default, the experimental TUI uses F6 to cycle focus. For a standard user experience, we want to use the TAB key. We also want to visually indicate which “window” has focus by turning its border Cyan.

namespace App\Command;

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Tui\Tui;
use Symfony\Component\Tui\Widget\ContainerWidget;
// ... (omitting widget imports for brevity, see later sections)
use Symfony\Component\Tui\Style\StyleSheet;
use Symfony\Component\Tui\Style\Style;
use Symfony\Component\Tui\Style\Border;
use Symfony\Component\Tui\Style\Padding;
use Symfony\Component\Tui\Style\Direction;
use Symfony\Component\Tui\Event\SelectEvent;
use Symfony\Component\Tui\Event\SelectionChangeEvent;
use Symfony\Component\Tui\Event\CancelEvent;
use Symfony\Component\Tui\Event\InputEvent;
use Symfony\Component\Tui\Event\FocusEvent;
use Symfony\Component\Tui\Input\Keybindings;
use Symfony\Component\Tui\Input\Key;
use Revolt\EventLoop;

#[AsCommand(name: 'app:widgets-demo', description: 'Demonstrates all available widgets.')]
class WidgetsDemoCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $stylesheet = new StyleSheet();

        $stylesheet->addRule('.sidebar', new Style(padding: Padding::all(1)));
        $stylesheet->addRule('.content-pane', new Style(padding: Padding::all(1)));

        // Dynamic classes applied via Focus events
        $stylesheet->addRule('.active-pane', new Style(border: Border::all(1, 'rounded', 'cyan')));
        $stylesheet->addRule('.inactive-pane', new Style(border: Border::all(1, 'rounded', 'gray')));

        // ... [Widget construction goes here, we'll cover it below] ...

        // The TUI initialization with Custom Keybindings
        $keybindings = new Keybindings([
            'focus_next' => [Key::TAB],
            'focus_previous' => ['shift+tab'],
        ]);

        $tui = new Tui(styleSheet: $stylesheet, keybindings: $keybindings);
        $tui->add($mainLayout);

        // Workaround: Intercept raw InputEvents to force TAB navigation
        $tui->on(InputEvent::class, function (InputEvent $event) use ($tui, $keybindings) {
            $data = $event->getData();
            if ($keybindings->matches($data, 'focus_next')) {
                $tui->getFocusManager()->focusNext();
                $event->stopPropagation();
            } elseif ($keybindings->matches($data, 'focus_previous')) {
                $tui->getFocusManager()->focusPrevious();
                $event->stopPropagation();
            }
        });

        // Visually change the active pane border based on FocusEvent
        $tui->on(FocusEvent::class, function (FocusEvent $event) use ($sidebar, $contentPane, $inputField, $editorField) {
            $target = $event->getTarget();
            $previous = $event->getPrevious();

            if ($target === $sidebar) {
                $sidebar->removeStyleClass('inactive-pane')->addStyleClass('active-pane');
                $contentPane->removeStyleClass('active-pane')->addStyleClass('inactive-pane');
            } else {
                $sidebar->removeStyleClass('active-pane')->addStyleClass('inactive-pane');
                $contentPane->removeStyleClass('inactive-pane')->addStyleClass('active-pane');
            }

            // ... [Placeholder logic goes here] ...
        });

        $tui->run();
        return Command::SUCCESS;
    }
}

Notice how we rely on FocusEvent to manipulate CSS classes (removeStyleClass/addStyleClass). The framework completely abstracts away terminal coordinates. We simply alter the DOM and Symfony handles the visual repainting.

Input and Editor Widgets (Handling Placeholders)

The InputWidget and EditorWidget provide robust input handling, including cursor movement, scrolling and paste support. Let’s create an input and a multi-line editor and build custom placeholder logic using the FocusEvent we defined above.

// 2. InputWidget
        $inputContainer = new ContainerWidget();
        $inputContainer->setStyle(new Style(direction: Direction::Vertical, gap: 1));

        $inputField = new InputWidget();
        $inputField->setValue("Type something here...");
        $inputField->setStyle(new Style(border: Border::all(1, 'rounded', 'green')));
        $inputContainer->add(new TextWidget("Single-line text field:"))->add($inputField);

        // 3. EditorWidget
        $editorContainer = new ContainerWidget();
        $editorContainer->setStyle(new Style(direction: Direction::Vertical, gap: 1));

        $editorField = new EditorWidget();
        $editorField->setText("Write your multiline text here.\n\nEnjoy the full editing capabilities!");
        $editorField->setStyle(new Style(border: Border::all(1, 'rounded', 'yellow')));
        $editorField->expandVertically(true); // Fills available terminal height
        $editorContainer->add(new TextWidget("Multi-line text editor:"))->add($editorField);

Inside our FocusEvent listener, we can add this logic to simulate HTML placeholder attributes:

// InputWidget placeholder logic: hide on focus, restore on blur
            if ($target === $inputField && $inputField->getValue() === "Type something here...") {
                $inputField->setValue("");
            }
            if ($previous === $inputField && $inputField->getValue() === "") {
                $inputField->setValue("Type something here...");
            }

            // EditorWidget placeholder logic
            if ($target === $editorField && $editorField->getText() === "Write your multiline text here.\n\nEnjoy the full editing capabilities!") {
                $editorField->setText("");
            }
            if ($previous === $editorField && $editorField->getText() === "") {
                $editorField->setText("Write your multiline text here.\n\nEnjoy the full editing capabilities!");
            }

Markdown and Settings

The MarkdownWidget is a powerhouse. Using league/commonmark for parsing and tempest/highlight for tokenization, it renders fully syntax-highlighted code blocks natively in the terminal.

// 5. MarkdownWidget
        $mdText = "# MarkdownWidget\n\nSupports **CommonMark** with syntax highlighting!\n\n```

php\n// Look at this code\necho 'Hello TUI!';\n

```\n\n- Lists are supported too.";
        $markdownWidget = new MarkdownWidget($mdText);

The SettingsListWidget operates as an interactive preference panel, allowing users to hit or Right/Left arrows to cycle through enumerated values.

// 4. SettingsListWidget
        $settingItems = [
            new SettingItem(id: 'theme', label: 'Theme', currentValue: 'Dark', description: 'Application visual theme.', values: ['Dark', 'Light', 'System']),
            new SettingItem(id: 'telemetry', label: 'Telemetry', currentValue: 'Opt-out', description: 'Share usage statistics.', values: ['Opt-in', 'Opt-out']),
        ];
        $settingsList = new SettingsListWidget($settingItems, 10);

True Concurrency with Revolt and Loaders

The absolute magic of the symfony/tui component lies in its event loop. We can render a ProgressBarWidget and an animated LoaderWidget side-by-side and update them using a background timer without ever halting the user’s ability to type in the InputWidget or navigate menus.

// 6. Loaders & Progress Bar
        $loadersContainer = new ContainerWidget();
        $loadersContainer->setStyle(new Style(direction: Direction::Vertical, gap: 1));

        $loader = new LoaderWidget('Booting system...');
        $cancellableLoader = new CancellableLoaderWidget('Downloading updates...');

        // Customizing the ProgressBar visualization via Stylesheet and Setters
        $stylesheet->addRule(ProgressBarWidget::class.'::bar-fill', new Style(color: 'cyan'));

        $progressBar = new ProgressBarWidget(100);
        $progressBar->setBarCharacter('━');       // The filled portion
        $progressBar->setEmptyBarCharacter('─');  // The empty background
        $progressBar->setProgressCharacter('╸');  // The leading edge
        $progressBar->start();

        // Simulate asynchronous background progress via Revolt EventLoop
        EventLoop::repeat(0.1, function() use ($progressBar, $loader, $cancellableLoader) {
            if ($progressBar->getProgress() < 100) {
                $progressBar->advance(1);
            } else {
                $progressBar->setProgress(0);
            }

            // Sync text to the progress bar's state
            $percent = $progressBar->getProgress();
            $loader->setMessage("Booting system... {$percent}%");
            $cancellableLoader->setMessage("Downloading updates... {$percent}%");
        });

        $loadersContainer->add($loader)->add($cancellableLoader)->add($progressBar);

Connecting the Tabs

Finally, we map our “Tabs” (the Sidebar) to our Content Panes. Whenever a user triggers a SelectionChangeEvent on the sidebar, we simply call $contentPane->clear() and $contentPane->add($panes[$value]). The DOM updates instantly.

// Map the options to the containers
        $panes = [
            'input' => $inputContainer,
            'editor' => $editorContainer,
            'settings' => $settingsContainer,
            'markdown' => $markdownWidget,
            'loaders' => $loadersContainer,
        ];

        // The active content pane container
        $contentPane = new ContainerWidget();
        $contentPane->addStyleClass('content-pane');
        $contentPane->addStyleClass('inactive-pane');
        $contentPane->expandVertically(true);
        $contentPane->add($inputContainer); // default view

        // Sidebar Navigation
        $sidebar = new SelectListWidget(
            items: [
                ['value' => 'input', 'label' => 'Input Field'],
                ['value' => 'editor', 'label' => 'Editor'],
                ['value' => 'settings', 'label' => 'Settings List'],
                ['value' => 'markdown', 'label' => 'Markdown'],
                ['value' => 'loaders', 'label' => 'Loaders & Progress'],
            ],
            maxVisible: 10
        );
        $sidebar->addStyleClass('sidebar');
        $sidebar->addStyleClass('active-pane');

        // Swap out DOM content on selection change
        $sidebar->on(SelectionChangeEvent::class, function (SelectionChangeEvent $event) use ($contentPane, $panes) {
            $value = $event->getValue();
            if (isset($panes[$value])) {
                $contentPane->clear();
                $contentPane->add($panes[$value]);
            }
        });

        // TUI Main Layout
        $mainLayout = new ContainerWidget();
        $mainLayout->setStyle(new Style(direction: Direction::Horizontal, gap: 2));
        $mainLayout->add($sidebar);
        $mainLayout->add($contentPane);

The Future of the Terminal

Building with the experimental symfony/tui component feels revolutionary. It takes the lessons we’ve learned from decades of frontend browser development — the DOM tree, the event loop, cascading styles and distinct focus states — and injects them seamlessly into the terminal.

While currently in its raw PHP object-oriented form, the planned roadmap includes bringing this exact retained-mode engine into Twig. Imagine writing your CLI tools using familiar declarative and tags, backed by powerful PHP Controllers.

While the component is still in its experimental phase, cloning the PR and building side-projects today will give you a massive head start. Terminal apps are about to become a whole lot richer and Symfony is leading the charge.

Source Code: You can find the full implementation and follow the project’s progress on GitHub: [https://github.com/mattleads/TuiComponent]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]

10x Smaller, 100x Safer: Building Secure & Compressed Microservices in Symfony

Matt Mochalkin — Sat, 28 Mar 2026 18:08:20 +0000

In the rapidly evolving landscape of modern web development, microservices have become the gold standard for building scalable, decoupled applications. But as your system grows, so does the complexity of how these isolated services communicate. Enter asynchronous messaging.

When dealing with high-throughput systems, two massive challenges inevitably emerge:

Performance & Scale (how to handle millions of messages without burning through your infrastructure budget)
Resiliency & Reliability (how to survive network hiccups, database locks and API rate limits without dropping data).

With the release of the Symfony 7.4 ecosystem, the symfony/messenger component continues to be a developer’s best friend. And thanks to the CompressStamp, we now have a native, incredibly elegant way to crush bandwidth costs and supercharge queue performance.

In this deep dive, we are going to explore how to build a highly resilient, lightning-fast microservice architecture using Symfony Messenger, Redis and advanced message stamping.

The Bottleneck: The “Fat Payload” Problem

Message queues are designed to be fast and lightweight. A classic architectural rule is to “send references, not data” (e.g., sending a user_id instead of the entire User object). However, in real-world microservices, this isn’t always possible.

Imagine you are building a reporting microservice, an invoice generator, or a system that bulk-syncs data to a third-party CRM. You are forced to pass massive JSON payloads, Base64-encoded file strings, or deeply nested arrays across the wire.

When these “fat payloads” hit your transport (Redis, Amazon SQS and etc.), three things happen:

Memory Bloat: Transport stores everything. Giant messages will trigger eviction policies or crash your instance entirely.
Network Latency: Moving megabytes of data between your web nodes and your queue slows down your producers.
Security Risks: Storing unencrypted PII or financial data in a queue violates compliance standards like GDPR or HIPAA.

A Custom Serialization Pipeline

Out of the box, Symfony Messenger serializes your message objects into plain JSON strings. To solve our performance and security bottlenecks, we are going to intercept this process.

By creating custom Stamps (metadata markers) and decorating the default Serializer, we can instruct Symfony to natively compress and encrypt specific messages right before they hit the transport and reverse the process the moment a worker picks them up.

Designing for Resiliency & Reliability

Speed means nothing if your system is fragile. Microservices fail. Third-party APIs go down. Databases lock. If your consumer throws an exception, you cannot afford to lose the message.

A resilient Symfony Messenger architecture relies on three pillars:

Asynchronous Transports: Never make the user wait for a background task.
Retry Strategies: Automatically re-queue failed messages with an exponential backoff (e.g., retry after 10 seconds, then 20 seconds, then 40 seconds).
Failure Transports (Dead Letter Queues): If a message fails all retries, route it to a secure database queue where a developer can inspect it, fix the bug and manually replay it.

The Tech Stack

We are utilizing the current Symfony 7.4 LTS ecosystem alongside PHP 8.2+. Ensure you have the necessary PHP extensions installed on your server.

symfony/messenger: Core message bus and worker tooling.
symfony/redis-messenger: The official Redis transport for Messenger.
ext-zlib: Native PHP extension required for gzcompress.
ext-openssl: Native PHP extension required for AES-256 encryption.

Step-by-Step Implementation

Let’s build our secure, highly-compressed “Invoice Generation” service.

The Message Class & Handlers

In modern PHP, we use strongly typed, read-only classes for our messages.

namespace App\Message;

/**
 * Represents a bulk invoice generation request.
 */
readonly class GenerateBulkInvoiceMessage
{
    public function __construct(
        public string $batchId,
        public array $invoiceData // Imagine this array contains thousands of nested rows
    ) {
    }
}

Using the #[AsMessageHandler] attribute, our worker expects to receive the fully hydrated, decompressed and decrypted object. Our worker doesn’t need to know how the message was transported; it just handles the business logic.

namespace App\MessageHandler;

use App\Message\GenerateBulkInvoiceMessage;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;
use Psr\Log\LoggerInterface;

#[AsMessageHandler]
readonly class GenerateBulkInvoiceMessageHandler
{
    public function __construct(
        private LoggerInterface $logger
    ) {
    }

    public function __invoke(GenerateBulkInvoiceMessage $message): void
    {
        $this->logger->info('Starting bulk invoice generation for batch.', [
            'batchId' => $message->batchId,
            'recordsCount' => count($message->invoiceData)
        ]);

        // Simulate heavy processing...
        // If this throws an exception, Symfony Messenger automatically catches it,
        // checks the retry_strategy in messenger.yaml and re-queues it in Redis!

        $this->logger->info('Bulk invoice generation completed successfully.');
    }
}

Creating the Custom Stamps

In Symfony Messenger stamps are simply DTOs that act as metadata. We will create two stamps: one for compression and one for security.

namespace App\Messenger\Stamp;

use Symfony\Component\Messenger\Stamp\StampInterface;

/**
 * A stamp indicating that the serialized message payload should be compressed.
 */
readonly class CompressStamp implements StampInterface
{
}

namespace App\Messenger\Stamp;

use Symfony\Component\Messenger\Stamp\StampInterface;

/**
 * A stamp indicating that the serialized message payload should be encrypted.
 */
readonly class SecureStamp implements StampInterface
{
}

The Custom Serializer

Instead of writing a serializer from scratch, we use the Decorator pattern to wrap Symfony’s default serializer. If the CompressStamp is present, we compress the JSON body using PHP’s native zlib extension. If it detects the SecureStamp, it applies AES-256-CBC encryption via OpenSSL.

namespace App\Messenger\Serialization;

use App\Messenger\Stamp\CompressStamp;
use App\Messenger\Stamp\SecureStamp;
use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Exception\MessageDecodingFailedException;
use Symfony\Component\Messenger\Transport\Serialization\SerializerInterface;

/**
 * Serializer that independently handles compression and encryption.
 */
readonly class CompressSerializer implements SerializerInterface
{
    private const string COMPRESSED_HEADER = 'X-Compressed';
    private const string SECURED_HEADER = 'X-Secured';
    private const string CIPHER_ALGO = 'aes-256-cbc';

    public function __construct(
        private SerializerInterface $innerSerializer,
        private string $encryptionKey
    ) {
    }

    public function decode(array $encodedEnvelope): Envelope
    {
        $body = $encodedEnvelope['body'] ?? throw new MessageDecodingFailedException('Encoded envelope has no body.');

        print_r($encodedEnvelope);


        // 1. Handle Decryption (must happen before decompression if both were used)
        if (isset($encodedEnvelope['headers'][self::SECURED_HEADER]) && 'true' === $encodedEnvelope['headers'][self::SECURED_HEADER]) {
            $decodedBody = base64_decode($body, true);
            if ($decodedBody === false) {
                throw new MessageDecodingFailedException('Failed to base64 decode the secured message body.');
            }

            $ivLength = openssl_cipher_iv_length(self::CIPHER_ALGO);
            $iv = substr($decodedBody, 0, $ivLength);
            $encryptedData = substr($decodedBody, $ivLength);

            $key = hash('sha256', $this->encryptionKey, true);
            $decryptedBody = openssl_decrypt($encryptedData, self::CIPHER_ALGO, $key, OPENSSL_RAW_DATA, $iv);

            if (false === $decryptedBody) {
                throw new MessageDecodingFailedException('Failed to decrypt the message body. Check your encryption key.');
            }

            $body = $decryptedBody;
        }

        // 2. Handle Decompression
        if (isset($encodedEnvelope['headers'][self::COMPRESSED_HEADER]) && 'true' === $encodedEnvelope['headers'][self::COMPRESSED_HEADER]) {
            $decompressedBody = gzinflate($body);

            if (false === $decompressedBody) {
                throw new MessageDecodingFailedException('Failed to decompress the message body.');
            }

            $body = $decompressedBody;
        }

        $encodedEnvelope['body'] = $body;

        return $this->innerSerializer->decode($encodedEnvelope);
    }

    public function encode(Envelope $envelope): array
    {
        $encodedEnvelope = $this->innerSerializer->encode($envelope);
        $body = $encodedEnvelope['body'];

        // 1. Handle Compression (Compress first for maximum efficiency before encryption)
        if (null !== $envelope->last(CompressStamp::class)) {
            $compressedBody = gzdeflate($body);
            if (false === $compressedBody) {
                throw new \RuntimeException('Failed to compress the message body.');
            }
            $body = $compressedBody;
            $encodedEnvelope['headers'][self::COMPRESSED_HEADER] = 'true';
        }

        // 2. Handle Encryption
        if (null !== $envelope->last(SecureStamp::class)) {
            if (empty($this->encryptionKey)) {
                throw new \LogicException('Cannot encrypt message: MESSENGER_ENCRYPTION_KEY is not set.');
            }

            $ivLength = openssl_cipher_iv_length(self::CIPHER_ALGO);
            $iv = random_bytes($ivLength);
            $key = hash('sha256', $this->encryptionKey, true);

            $encryptedBody = openssl_encrypt($body, self::CIPHER_ALGO, $key, OPENSSL_RAW_DATA, $iv);

            if (false === $encryptedBody) {
                throw new \RuntimeException('Failed to encrypt the message body.');
            }

            $body = base64_encode($iv . $encryptedBody);
            $encodedEnvelope['headers'][self::SECURED_HEADER] = 'true';
        }

        $encodedEnvelope['body'] = $body;

        return $encodedEnvelope;
    }
}

Wiring It Up

To make this pipeline active, we register our decorator in config/services.yaml.

services:    
    ...
    App\Messenger\Serialization\CompressSerializer:
        arguments:
            $innerSerializer: '@messenger.default_serializer'
            $encryptionKey: '%env(MESSENGER_ENCRYPTION_KEY)%'
    ...

Now, dispatching a secure, lightweight message is as simple as:

        // Dispatch the message, attaching both stamps for maximum security and efficiency
        $this->messageBus->dispatch($message, [
            new CompressStamp(),
            new SecureStamp()
        ]);

Benchmarking the Ultimate Pipeline

To truly understand the value and the trade-offs of this architecture, let’s look at a real-world benchmark. We simulated a high-throughput environment dispatching 10,000 GenerateBulkInvoiceMessage objects to our Redis transport. Each message contained a fat array payload that, when serialized natively, equated to approximately 500KB per message.

Here are the results across a standard cloud environment (2 vCPUs, 4GB RAM):

+-------------------------+----------------+------------------+---------------------------+
| Metric                  | Baseline (Raw) | Compress + Stamp | Compress + Secure         |
+-------------------------+----------------+------------------+---------------------------+
| Total Redis Memory      | ~4.88 GB       | ~410 MB          | ~550 MB                   |
+-------------------------+----------------+------------------+---------------------------+
| Worker CPU Utilization  | ~15%           | ~22%             | ~38%                      |
+-------------------------+----------------+------------------+---------------------------+
| Avg. Time to Dispatch   | 42 seconds     | 35 seconds       | 48 seconds                |
+-------------------------+----------------+------------------+---------------------------+
| Avg. Time to Consume    | 58 seconds     | 61 seconds       | 74 seconds                |
+-------------------------+----------------+------------------+---------------------------+

Analyzing the Trade-offs

The Memory Sweet Spot: Raw payloads consume a massive 4.88 GB of Redis RAM. Compression crushes this down to 410 MB. However, when we add the SecureStamp, memory creeps up slightly to 550 MB because the output of OpenSSL is binary and storing it safely requires base64_encode(). Even with this overhead, you are saving 88% of your memory footprint!
The CPU Tax: Security is never free. Adding AES-256 encryption pushes the worker’s CPU utilization up to 38%. The worker has to perform cryptographic math on every single message before unpacking it.
Time to Process: The baseline takes 42 seconds to dispatch because pushing 4.88 GB over a network connection is incredibly slow. Compression speeds this up (35 seconds) by shifting the bottleneck from the network to the CPU. Adding encryption slows it back down slightly (48 seconds) due to the heavy OpenSSL processing.

Is the CPU tax worth it? If your payloads contain PII or financial records, sacrificing a bit of CPU time to ensure military-grade encryption while still saving 88% on your infrastructure bill is an architectural slam dunk.

Conclusion

Building modern microservices requires more than just pushing data into a queue. By extending Symfony’s Messenger component with custom Serializers and Stamps, you can take complete control over your message payloads.

You no longer have to choose between performance and security. By implementing this custom pipeline, you ensure that your message broker remains highly performant, remarkably cost-effective and fully compliant with strict data security laws.

Source Code: You can find the full implementation and follow the project’s progress on GitHub: [https://github.com/mattleads/CompressStamp]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]

Passkey Management and Account Recovery in Symfony

Matt Mochalkin — Tue, 24 Mar 2026 15:45:19 +0000

In Part 1 and Part 2, we built a fortress. We implemented WebAuthn, gracefully handled hybrid password fallbacks and created a frictionless login experience using Conditional UI (autofill).

But now we must face the nightmare scenario: The Lost Device.

When you eliminate passwords, a user’s smartphone or YubiKey becomes their only key to the castle. If that device is lost, stolen or destroyed, how do they get back in? If we just email them a magic link, we instantly downgrade our security model back to the vulnerabilities of email interception.

Today, we are building a bulletproof account recovery and passkey management system. We will create a user dashboard to manage active credentials, implement a “Last Used” tracker and generate cryptographically secure, one-time recovery codes using the web-authn/web-authn-symfony-bundle.

Grab a coffee. We are diving deep into Symfony events, Doctrine lifecycle callbacks, WebAuthn v5 quirks and clean architecture.

The Architecture of Recovery

Before we write code, let’s define the architecture of a production-ready WebAuthn recovery system:

Transparency (The Dashboard): Users must be able to see all their registered passkeys, including when they were created and last used.
Revocation: Users must be able to delete a passkey. If a device is stolen, revoking the credential instantly neutralizes the threat.
The Fallback (Recovery Codes): Instead of passwords or email links, we will generate a set of one-time use, offline recovery codes during registration. These act as the ultimate fallback.

Building the Passkey Management Dashboard

To allow users to manage their passkeys, we need to query the database for their registered credentials. If you followed the standard bundle setup, you already have a PublicKeyCredentialSource Doctrine entity and repository.

Let’s create a controller to list and delete these credentials.

namespace App\Controller;

use App\Repository\PublicKeyCredentialSourceRepository;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Attribute\IsGranted;

use App\Service\RecoveryCodeGenerator;

#[IsGranted('ROLE_USER')]
#[Route('/settings/passkeys', name: 'app_settings_passkeys_')]
class PasskeyManagementController extends AbstractController
{
    public function __construct(
        private readonly PublicKeyCredentialSourceRepository $credentialRepository,
        private readonly EntityManagerInterface $entityManager
    ) {}

    #[Route('/', name: 'index', methods: ['GET'])]
    public function index(RecoveryCodeGenerator $generator): Response
    {
        /** @var \App\Entity\User $user */
        $user = $this->getUser();

        $newCodes = [];
        if ($user->getRecoveryCodes()->isEmpty()) {
            $newCodes = $generator->generateForUser($user, 10);
        }

        // We map our Symfony User to the WebAuthn User Entity
        $userEntity = $user->toWebAuthnUser();

        // Fetch all passkeys bound to this user
        $credentials = $this->credentialRepository->findAllForUserEntity($userEntity);

        return $this->render('settings/passkeys/index.html.twig', [
            'credentials' => $credentials,
            'newCodes' => $newCodes,
        ]);
    }

    #[Route('/{id}/revoke', name: 'revoke', methods: ['POST'])]
    public function revoke(string $id): Response
    {
        $credential = $this->credentialRepository->findOneBy(['id' => $id]);

        // Security Check: Ensure the credential belongs to the currently logged-in user
        if (!$credential || $credential->userHandle !== (string) $this->getUser()->getUserHandle()) {
            throw $this->createAccessDeniedException('You cannot revoke this passkey.');
        }

        $this->entityManager->remove($credential);
        $this->entityManager->flush();

        $this->addFlash('success', 'Passkey successfully revoked.');

        return $this->redirectToRoute('app_settings_passkeys_index');
    }
}

The Twig View

Create a simple view (templates/settings/passkeys/index.html.twig) to display the data:

{% extends 'base.html.twig' %}

{% block body %}
    <h1>Manage Your Passkeys</h1>

    <div style="margin-bottom: 20px;">
        <a href="{{ path('app_dashboard') }}" class="btn btn-secondary" style="display: inline-block; padding: 10px 20px; background: #6c757d; color: white; text-decoration: none; border-radius: 5px; font-weight: bold;">
            &larr; Back to Dashboard
        </a>
    </div>

    {% for message in app.flashes('success') %}
        <div class="alert alert-success">
            {{ message }}
        </div>
    {% endfor %}

    {% if newCodes %}
        <div class="alert alert-warning">
            <h4 class="alert-heading">Save these Recovery Codes!</h4>
            <p>You can use these codes to log in if you lose your device. They will only be shown <b>once</b>.</p>
            <hr>
            <div class="row">
                {% for code in newCodes %}
                    <div class="col-6 col-md-4 mb-2"><code>{{ code }}</code></div>
                {% endfor %}
            </div>
        </div>
    {% endif %}

    <table class="table">
        <thead>
            <tr>
                <th>AAGUID (Device Type)</th>
                <th>Added On</th>
                <th>Last Used</th>
                <th>Actions</th>
            </tr>
        </thead>
        <tbody>
        {% for credential in credentials %}
            <tr>
                <td>
                    <span title="{{ credential.aaguid }}">
                        {{ credential.aaguid == '00000000-0000-0000-0000-000000000000' ? 'Unknown Passkey' : 'Hardware Key' }}
                    </span>
                </td>
                <td>{{ credential.createdAt ? credential.createdAt|date('Y-m-d H:i') : 'Unknown' }}</td>
                <td>{{ credential.lastUsedAt ? credential.lastUsedAt|date('Y-m-d H:i') : 'Never' }}</td>
                <td>
                    <form action="{{ path('app_settings_passkeys_revoke', { 'id': credential.id }) }}" method="POST">
                        <button type="submit" class="btn btn-danger">Revoke</button>
                    </form>
                </td>
            </tr>
        {% else %}
            <tr><td colspan="4">No passkeys registered.</td></tr>
        {% endfor %}
        </tbody>
    </table>
{% endblock %}

Guaranteed Creation Dates via Doctrine PrePersist

To provide visibility, users need to know when a passkey was added. Initially, we attempted to pull this data from WebAuthn’s TrustPath object (credential.trustPath.createdAt).

If we rely on external WebAuthn metadata for our business logic, we violate the concept of bounded contexts. Our application needs to know when the record was created in our system, not when the key claims it was minted.

We adhere to moving this logic directly into the entity using Doctrine’s HasLifecycleCallbacks.

We updated our PublicKeyCredentialSource entity:

#[ORM\Entity(repositoryClass: PublicKeyCredentialSourceRepository::class)]
#[ORM\Table(name: 'webauthn_credentials')]
#[ORM\HasLifecycleCallbacks] // <-- Step 1: Enable callbacks
class PublicKeyCredentialSource extends WebauthnSource
{
    #[ORM\Column(type: 'datetime_immutable', nullable: true)]
    private ?\DateTimeImmutable $createdAt = null;

    #[ORM\PrePersist] // <-- Step 2: Hook into the pre-persist event
    public function setCreatedAtValue(): void
    {
        if ($this->createdAt === null) {
            $this->createdAt = new \DateTimeImmutable();
        }
    }

    // ...
}

By leveraging #[ORM\PrePersist], we guarantee that no matter where in our massive enterprise application a developer instantiates and persists a credential, the createdAt timestamp is irrevocably applied. The controller doesn’t need to know about it. The repository doesn’t need to know about it. It is perfectly encapsulated.

Tracking “Last Used” with Symfony Events

A critical feature of any security dashboard is showing the user when a credential was last used. If they see a login from today, but they haven’t logged in for a week, they know their account is compromised.

We can listen for the successful validation event and update a lastUsedAt property.

First, ensure your PublicKeyCredentialSource Doctrine entity has a lastUsedAt property. If you generated it using the bundle’s abstract class, you might need to extend it and add the column.

Next, create an Event Subscriber:

namespace App\EventSubscriber;

use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Webauthn\Event\AuthenticatorAssertionResponseValidationSucceededEvent;
use App\Entity\PublicKeyCredentialSource;

readonly class PasskeyUsageSubscriber implements EventSubscriberInterface
{
    public function __construct(
        private EntityManagerInterface $entityManager
    ) {}

    public static function getSubscribedEvents(): array
    {
        return [
            AuthenticatorAssertionResponseValidationSucceededEvent::class => 'onPasskeyUsed',
        ];
    }

    public function onPasskeyUsed(AuthenticatorAssertionResponseValidationSucceededEvent $event): void
    {
        $credentialSource = $event->publicKeyCredentialSource;

        if ($credentialSource instanceof PublicKeyCredentialSource) {
            $credentialSource->setLastUsedAt(new \DateTimeImmutable());

            // Persist the updated usage timestamp to the database
            $this->entityManager->persist($credentialSource);
            $this->entityManager->flush();
        }
    }
}

Now, every time a user logs in with a passkey, the timestamp is automatically recorded, entirely decoupled from your controllers!

The Ultimate Fallback: Offline Recovery Codes

If a user loses their phone, they can’t log in to revoke the old passkey and add a new one. To solve this, we will generate 10 offline recovery codes. These act as single-use passwords.

The Recovery Code Entity

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class RecoveryCode
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    private ?string $hashedCode = null;

    #[ORM\ManyToOne(inversedBy: 'recoveryCodes')]
    #[ORM\JoinColumn(nullable: false)]
    private ?User $user = null;

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getHashedCode(): ?string
    {
        return $this->hashedCode;
    }

    public function setHashedCode(string $hashedCode): static
    {
        $this->hashedCode = $hashedCode;

        return $this;
    }

    public function getUser(): ?User
    {
        return $this->user;
    }

    public function setUser(?User $user): static
    {
        $this->user = $user;

        return $this;
    }
}

Generating the Codes securely

When a user enables WebAuthn, we should generate these codes, hash them (just like passwords) and display the raw codes to the user exactly once.

namespace App\Service;

use App\Entity\RecoveryCode;
use App\Entity\User;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;

readonly class RecoveryCodeGenerator
{
    public function __construct(
        private EntityManagerInterface $entityManager,
        private UserPasswordHasherInterface $passwordHasher
    ) {}

    /**
     * @return string[] The plain-text codes to show the user
     */
    public function generateForUser(User $user, int $amount = 10): array
    {
        $plainCodes = [];

        for ($i = 0; $i < $amount; $i++) {
            // Generate a secure 8-character random string
            $code = bin2hex(random_bytes(4));
            $plainCodes[] = $code;

            $recoveryCode = new RecoveryCode();
            $user->addRecoveryCode($recoveryCode);

            // Hash the code before storing it in the database
            $hashed = $this->passwordHasher->hashPassword($user, $code);
            $recoveryCode->setHashedCode($hashed);

            $this->entityManager->persist($recoveryCode);
        }

        $this->entityManager->flush();

        return $plainCodes;
    }
}

In the PasskeyManagementController, we check if the user has any codes. If** $user->getRecoveryCodes()->isEmpty(), we inject the RecoveryCodeGenerator, generate the codes and pass the **$plainCodes array to the Twig template.

Once the user navigates away, those plain text strings are gone from server memory forever.

The Recovery Login Flow

Create a standard Symfony form login route (e.g., /recovery-login). When the user submits their email and a recovery code, you verify it using Symfony’s UserPasswordHasherInterface.

If the hash matches, delete the code from the database (making it single-use) and manually authenticate the user using the Security helper:

namespace App\Controller;

use App\Entity\User;
use App\Repository\UserRepository;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\PasswordHasher\Hasher\PasswordHasherFactoryInterface;
use Symfony\Component\Routing\Attribute\Route;

class RecoveryLoginController extends AbstractController
{
    #[Route('/recovery-login', name: 'app_recovery_login')]
    public function login(
        Request $request,
        UserRepository $userRepository,
        PasswordHasherFactoryInterface $hasherFactory,
        Security $security,
        EntityManagerInterface $entityManager
    ): Response {
        if ($this->getUser()) {
            return $this->redirectToRoute('app_settings_passkeys_index');
        }

        $error = null;

        if ($request->isMethod('POST')) {
            $email = $request->request->get('email');
            $submittedCode = $request->request->get('code');

            if ($email && $submittedCode) {
                $user = $userRepository->findOneBy(['email' => $email]);

                if ($user) {
                    $hasher = $hasherFactory->getPasswordHasher(User::class);
                    $matchedRecoveryCodeEntity = null;

                    foreach ($user->getRecoveryCodes() as $recoveryCode) {
                        if ($hasher->verify($recoveryCode->getHashedCode(), $submittedCode)) {
                            $matchedRecoveryCodeEntity = $recoveryCode;
                            break;
                        }
                    }

                    if ($matchedRecoveryCodeEntity) {
                        // 1. Authenticate the user
                        $security->login($user, \App\Security\HybridAuthenticator::class);

                        // 2. Burn the code
                        $entityManager->remove($matchedRecoveryCodeEntity);
                        $entityManager->flush();

                        return $this->redirectToRoute('app_settings_passkeys_index');
                    } else {
                        $error = 'Invalid email or recovery code.';
                    }
                } else {
                    $error = 'Invalid email or recovery code.';
                }
            } else {
                $error = 'Please provide both email and recovery code.';
            }
        }

        return $this->render('app/recovery_login.html.twig', [
            'error' => $error,
        ]);
    }
}

Once logged in via the recovery code, the user is immediately redirected to the Passkey Dashboard where they can revoke their lost device and register a new passkey!

Verification Steps

To ensure your recovery architecture is rock solid, run through this testing matrix:

Dashboard Test: Register two different passkeys (e.g., Chrome profile and a YubiKey). Navigate to /settings/passkeys. Both should appear.
Usage Tracking Test: Log out, then log back in using Passkey A. Check your database or dashboard — only Passkey A’s lastUsedAt timestamp should have updated.
Revocation Test: Click “Revoke” on Passkey B. Attempt to log in using Passkey B. The assertion should fail entirely and Symfony should deny entry.
The “Lost Device” Simulation: Generate recovery codes for your account and save them to a text file.

Revoke all your active passkeys (simulating losing your only device).
Log out.
Navigate to your Recovery Login page. Enter your email and one of the codes.
You should be successfully authenticated.
Attempt to use the exact same code again. It must fail (single-use validation).

Conclusion

Over the course of these three articles, we’ve taken Symfony 7.4 from a standard, password-heavy application to a modern, frictionless and highly secure passwordless fortress.

We implemented the WebAuthn standard, smoothed the UX with Conditional UI and finally, built the enterprise-grade management and recovery tools required for a production environment.

The passwordless future isn’t just about deleting the field. It is about rethinking identity, managing cryptographic trust securely and keeping our users safe even on their worst days.

Source Code: You can find the full implementation and follow the project’s progress on GitHub: [https://github.com/mattleads/PasskeysAuth]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]

Thank you for building the future with me. Happy coding!

Beyond the Passwordless Fortress: Building a Hybrid Passkey Strategy in Symfony 7.4

Matt Mochalkin — Thu, 19 Mar 2026 15:23:14 +0000

In Part 1 of this series, we explored the “holy grail” of modern authentication: a 100% passwordless application. We stripped away passwords, hashes and reset emails, replacing them with the cryptographic elegance of the WebAuthn API.

But the real world is rarely that clean. You have legacy users who trust their password managers more than their biometrics. You have corporate environments where security keys aren’t yet standard. Most importantly, you have the “Transition Period” — that awkward phase where you need to support the old while aggressively pushing the new.

Today, we are building the Hybrid Model. We’re going to create a single, intelligent login form that automatically detects if a user has a Passkey, triggers biometrics if available, but gracefully falls back to a traditional password when necessary.

We’ll also look at Conditional Mediation (Passkey Autofill) — the “magic” UX that allows a user to log in simply by focusing an input field.

The Tech Stack

To follow this guide, you will need:

PHP 8.2+: Leveraging readonly classes and constructor promotion.
Symfony 7.4: Utilizing the latest Security Component improvements.
web-auth/webauthn-symfony-bundle: The industry standard for WebAuthn in Symfony.
Stimulus & AssetMapper: For a zero-Node.js frontend experience.

The UX Masterpiece: How It Works

Instead of confusing users with two separate login buttons (“Log in with Password” vs “Log in with Passkey”), we present them with a single, elegant input: Their Email Address.

The user enters their email and clicks “Continue”.
Behind the scenes, our Symfony 7.4 backend does a lightning-fast check.
If the user has a registered Passkey: We instantly trigger the native WebAuthn biometric prompt (FaceID, TouchID, Windows Hello).
If the user relies on a password: The form gracefully expands to reveal the traditional password input field.

This is the exact flow used by tech giants like Google and GitHub and today, we are building it entirely with standard Symfony tools!

The Domain Model: Bridging Two Worlds

In our previous pure-passwordless setup, our User entity didn’t even have a password field. To support a hybrid flow, we must re-introduce it, but as an optional credential. This allows for a tiered security model: a user can start with a simple password and later “upgrade” their account by registering a Passkey, which eventually becomes their primary (and most secure) way to log in.

By implementing the PasswordAuthenticatedUserInterface while keeping the password field nullable, we satisfy Symfony’s security requirements for traditional login without forcing every user to have a legacy credential. This architectural choice is crucial for maintaining backwards compatibility while clearly signaling that Passkeys are the future-proof standard for the application.

// src/Entity/User.php
namespace App\Entity;

use App\Repository\UserRepository;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Uid\Uuid;

#[ORM\Entity(repositoryClass: UserRepository::class)]
#[ORM\Table(name: '`user`')]
class User implements UserInterface, PasswordAuthenticatedUserInterface
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 180, unique: true)]
    private ?string $email = null;

    #[ORM\Column(length: 255, unique: true)]
    private ?string $userHandle = null;

    #[ORM\Column(type: 'string', length: 255, nullable: true)]
    private ?string $password = null;

    public function __construct()
    {
        // WebAuthn requires a persistent, non-identifying handle
        $this->userHandle = Uuid::v4()->toRfc4122();
    }

    // ... standard getters/setters

    public function getPassword(): ?string
    {
        return $this->password;
    }

    public function setPassword(?string $password): static
    {
        $this->password = $password;
        return $this;
    }

    public function eraseCredentials(): void
    {
        // Clear temporary sensitive data
    }

    public function getUserIdentifier(): string
    {
        return (string) $this->email;
    }
}

The Architecture of Choice: Flow Detection

The core of a great hybrid UX is Flow Detection. We don’t want to show two forms. We want one input: “Enter your email.” When the user clicks “Continue,” our Stimulus controller hits a lightweight API endpoint to decide the next move. This prevents the “password field fatigue” where users are confronted with a complex form before they’ve even identified themselves.

Importantly, this endpoint is designed with “security through ambiguity” in mind. If an email is not found, we default the response to the password flow. This prevents malicious actors from using the API to verify which emails are registered in our system (user enumeration), while still allowing us to provide a tailored, progressive UI for our legitimate users.

The Flow API

// src/Controller/AuthController.php
namespace App\Controller;

use App\Repository\UserRepository;
use App\Repository\PublicKeyCredentialSourceRepository;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;

class AuthController extends AbstractController
{
    #[Route('/api/auth/flow', name: 'app_api_auth_flow', methods: ['GET'])]
    public function apiAuthFlow(
        Request $request, 
        UserRepository $userRepo, 
        PublicKeyCredentialSourceRepository $credsRepo
    ): JsonResponse {
        $email = $request->query->get('email');
        $user = $userRepo->findOneBy(['email' => $email]);

        if (!$user) {
            // Treat non-existent users as password users to prevent enumeration
            return new JsonResponse(['flow' => 'password']);
        }

        $hasPasskeys = count($credsRepo->findAllForUserEntity($user->toWebauthnUser())) > 0;

        return new JsonResponse([
            'flow' => $hasPasskeys ? 'passkey' : 'password'
        ]);
    }
}

The Security Guard: HybridAuthenticator

While the webauthn-symfony-bundle handles Passkey verification automatically, we need a way to handle the traditional password fallback. Instead of using the built-in form_login, we implement a custom HybridAuthenticator. This allows us to treat different credential types (Passkeys vs. Passwords) as separate “badges” within a single unified authentication event, providing a much cleaner integration with the modern Symfony 7.4 Security component.

By using a custom authenticator, we can also ensure that both authentication methods share the exact same success and failure handlers. This means redirected dashboard URLs, flash messages and security logging are consistent across the entire app, regardless of whether the user used their fingerprint or a 20-character password to gain entry.

// src/Security/HybridAuthenticator.php
namespace App\Security;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Credentials\PasswordCredentials;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;

class HybridAuthenticator extends AbstractAuthenticator
{
    public function __construct(
        private readonly AuthenticationSuccessHandler $successHandler,
        private readonly AuthenticationFailureHandler $failureHandler
    ) {}

    public function supports(Request $request): ?bool
    {
        // Only intercept standard POST login attempts with a password
        return $request->isMethod('POST') 
            && $request->getPathInfo() === '/login' 
            && $request->request->has('password');
    }

    public function authenticate(Request $request): Passport
    {
        $email = $request->request->getString('username');
        $password = $request->request->getString('password');

        return new Passport(
            new UserBadge($email),
            new PasswordCredentials($password)
        );
    }

    public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewall): ?Response
    {
        return $this->successHandler->onAuthenticationSuccess($request, $token);
    }

    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
    {
        return $this->failureHandler->onAuthenticationFailure($request, $exception);
    }
}

Symfony 7.4’s authenticator system is incredibly flexible. We can configure our security.yaml to accept both form logins (passwords) and WebAuthn assertions on the same firewall!

security:
    password_hashers:
        App\Entity\User: 'auto'
    providers:
        app_user_provider:
            entity:
                class: App\Entity\User
                property: email
    firewalls:
        dev:
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false
        main:
            lazy: true
            provider: app_user_provider

            custom_authenticator: App\Security\HybridAuthenticator

            webauthn:
                authentication:
                    routes:
                        options_path: /login/passkey/options
                        result_path: /login/passkey/result
                registration:
                    enabled: true
                    routes:
                        options_path: /register/passkey/options
                        result_path: /register/passkey/result
                success_handler: App\Security\AuthenticationSuccessHandler
                failure_handler: App\Security\AuthenticationFailureHandler

            logout:
                path: app_logout
    access_control:
        - { path: ^/dashboard, roles: ROLE_USER }

Frontend Magic: Conditional Mediation (Autofill)

This is where the application starts to feel truly modern. Conditional Mediation allows the browser to show a Passkey suggestion as soon as the user focuses the email field. This “zero-effort” login means that for many users, the login process consists of a single tap on their name in a browser popup, followed by a biometric scan.

To achieve this, we use the autocomplete=”username webauthn” attribute in our HTML. This serves as a direct signal to the browser’s credential manager. On the JavaScript side, the Stimulus connect() method is the perfect place to initiate a background “listen” for these autofill suggestions, allowing the page to remain interactive while the browser waits for the user’s selection.

The Template

We need to add autocomplete=”username webauthn” to our input. This is the signal to the browser.

{# templates/app/login.html.twig #}
<form data-controller="hybrid-login" data-action="submit->hybrid-login#submit">
    <input type="email" 
           name="username" 
           autocomplete="username webauthn"
           data-hybrid-login-target="email" 
           placeholder="Enter your email">

    <div data-hybrid-login-target="passwordContainer" class="d-none">
        <input type="password" name="password" data-hybrid-login-target="password">
    </div>

    <button type="submit" data-hybrid-login-target="continueButton">Continue</button>
</form>

The Stimulus Controller

In our connect() method, we check if the browser supports autofill. If it does, we start the WebAuthn ceremony immediately in the background.

// assets/controllers/hybrid_login_controller.js
import { Controller } from '@hotwired/stimulus';
import { startAuthentication, browserSupportsWebAuthnAutofill } from '@simplewebauthn/browser';

export default class extends Controller {
    async connect() {
        if (await browserSupportsWebAuthnAutofill()) {
            try {
                // Background listen for autofill
                const credential = await startAuthentication({
                    optionsJSON: await this.fetchOptions(),
                    useBrowserAutofill: true
                });
                await this.verifyResult(credential);
            } catch (e) {
                // Silent catch: user might just type manually
            }
        }
    }

    async submit(event) {
        event.preventDefault();
        const email = this.emailTarget.value;

        // 1. Check Flow
        const { flow } = await fetch(`/api/auth/flow?email=${email}`).then(r => r.json());

        if (flow === 'passkey') {
            await this.triggerPasskeyLogin(email);
        } else {
            this.showPasswordInput();
        }
    }
}

The “Upgrade” Path: Adding Passkeys from the Dashboard

The biggest challenge with Passkeys isn’t the code; it’s the adoption. You need to give your users a reason and a way to add biometrics to their existing password accounts. We’ve implemented a specialized PasskeySettingsController that allows already-logged-in users to safely bridge the gap between their password-based past and their biometric future without the friction of a full re-registration.

A key part of this flow is the use of excludeCredentials. By passing the user’s existing credential IDs to the browser during this process, we ensure that the user isn’t prompted to create a duplicate Passkey on the same device. This prevents “credential clutter” and ensures that the user’s dashboard only shows unique, functional security keys, keeping the experience clean and manageable.

// src/Controller/PasskeySettingsController.php
#[Route('/dashboard/passkey/options', methods: ['POST'])]
public function options(): JsonResponse
{
    $user = $this->getUser();
    $userEntity = new PublicKeyCredentialUserEntity(
        $user->getEmail(),
        $user->getUserHandle(),
        $user->getEmail()
    );

    // Exclude existing keys so the browser doesn't offer duplicates
    $excludeDescriptors = array_map(
        fn ($source) => new PublicKeyCredentialDescriptor('public-key', $source->publicKeyCredentialId),
        $this->credsRepo->findAllForUserEntity($userEntity)
    );

    $options = $this->optionsFactory->create('default', $userEntity, $excludeDescriptors);
    $this->optionsStorage->store(Item::create($options, $userEntity));

    return new JsonResponse($this->serializer->serialize($options, 'json'), 200, [], true);
}

Technical Pitfalls & Verification

Binary Data and JSON

One of the most common issues in WebAuthn development is encoding. Credential IDs and challenges are raw binary data, which standard json_encode cannot handle.

We must use the base64url standard, which is specifically designed for safe transport in URLs and JSON without the problematic + or / characters found in standard Base64. Using the bundle’s specialized serializer ensures this conversion happens correctly and consistently.

Verification Steps

Password Registration: Create an account via the legacy /register/password route to establish your baseline “old world” user.
Hybrid Login: Go to /login and enter the email. The system should correctly identify the user as a password-only user and reveal the password field.
Upgrade: Log in with your password, navigate to the Dashboard and click “Add Passkey” to bridge the account into the biometric world.
Autofill: Log out. Click the email field. Your browser should now offer the Passkey suggestion immediately, completing the circle of the hybrid experience.

Conclusion

The implementation of a hybrid authentication model in Symfony 7.4 represents a sophisticated balance between cutting-edge security and practical accessibility. By providing a unified interface that respects both legacy password habits and the move toward biometrics, you eliminate the friction that often kills new feature adoption. This approach doesn’t just improve security; it builds trust with your users by meeting them where they are while clearly showing them a better, faster way forward.

Technically, we’ve seen that Symfony’s modern Security component and the WebAuthn bundle provide a remarkably robust foundation for these complex flows. The ability to treat passwords and passkeys as complementary badges within the same ecosystem means that as a developer, you aren’t fighting the framework to implement custom logic. Instead, you’re utilizing standard, interoperable primitives to build a system that is as maintainable as it is secure.

Looking ahead, the goal is a web where authentication is so frictionless it becomes invisible. With Conditional Mediation and hybrid fallbacks, we are moving closer to that reality, where the burden of security shifts from the user’s memory to the hardware in their pocket. By adopting these patterns today, you are future-proofing your application and ensuring that your users benefit from the highest standards of digital safety without sacrificing the convenience they’ve come to expect.

Source Code: You can find the full implementation and follow the project’s progress on GitHub: [https://github.com/mattleads/PasskeysAuth]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]

Building a 100% Passwordless Future: Passkeys in Symfony 7.4

Matt Mochalkin — Thu, 12 Mar 2026 10:16:07 +0000

In the modern web era, passwords are no longer sufficient. They are the root cause of over 80% of data breaches, subject to phishing, reuse and terrible complexity rules. The industry has spoken: Passkeys are the future.

Passkeys, built on the Web Authentication (WebAuthn) and FIDO2 standards, replace traditional passwords with cryptographic key pairs. Your device (iPhone, Android, Windows Hello, YubiKey) stores a private key, while the server only ever sees the public key. No hashes to steal, no passwords to reset and inherently phishing-resistant.

In this comprehensive guide, we will build a 100% passwordless authentication system using Symfony and the official web-auth/webauthn-symfony-bundle. We will eliminate the concept of a password entirely from our application. No fallback, no “reset password” links. Just pure, secure, biometric-backed passkeys.

Core Architecture & Requirements

Passkeys work by replacing a shared secret (password) with a public/private key pair. The private key never leaves the user’s Apple device (iPhone, Mac, iPad) and the public key is stored on your Symfony server.

Technical Stack

PHP: 8.2 or higher (Required for the latest WebAuthn libs)
Symfony: 7.4 LTS
Database: PostgreSQL, MySQL or SQLite for dev (to store Credential Sources)
Primary Library: web-auth/webauthn-symfony-bundle

Essential Packages

Run the following command to install the necessary dependencies:

composer require web-auth/webauthn-symfony-bundle:^5.2 \
                 web-auth/webauthn-stimulus:^5.2 \
                 symfony/uid:^7.4

We use @simplewebauthn/browser via AssetMapper (which provides excellent wrapper functions for the native browser WebAuthn APIs) because Apple Passkeys require a frontend interaction that is best handled via a Stimulus controller in a modern Symfony environment or you can use React/Vue modules.

Database Schema: The Credential Source

This is where our application dramatically diverges from a traditional Symfony app. We are going to strip passwords entirely from the system.

Standard Symfony User entities aren’t equipped to store Passkey metadata (like AAGUIDs or public key Cose algorithms). We need a dedicated entity to store the credentials.

The User Entity

Our User entity implements Symfony\Component\Security\Core\User\UserInterface. Noticeably absent is the PasswordAuthenticatedUserInterface.

namespace App\Entity;

use App\Repository\UserRepository;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Uid\Uuid;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity(repositoryClass: UserRepository::class)]
#[ORM\Table(name: '`user`')]
class User implements UserInterface
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255, unique: true)]
    private ?string $userHandle = null;

    #[ORM\Column(length: 180, unique: true)]
    #[Assert\NotBlank]
    #[Assert\Email]
    private ?string $email = null;

    public function __construct()
    {
        $this->userHandle = Uuid::v4()->toRfc4122();
    }

    ...
}

The PublicKeyCredentialSource Entity

A single user can have multiple passkeys (e.g., Face ID on their phone, Touch ID on their Mac, a YubiKey on their keychain). We need an entity to store these public keys and their associated metadata.

Create src/Entity/PublicKeyCredentialSource.php. This entity must be capable of translating to and from the bundle’s native Webauthn\PublicKeyCredentialSource object.

Crucially, we must preserve the TrustPath. Failing to do so destroys the attestation data needed if you ever require high-security enterprise hardware keys.

namespace App\Entity;

use App\Repository\PublicKeyCredentialSourceRepository;
use Doctrine\ORM\Mapping as ORM;
use Webauthn\PublicKeyCredentialSource as WebauthnSource;

#[ORM\Entity(repositoryClass: PublicKeyCredentialSourceRepository::class)]
#[ORM\Table(name: 'webauthn_credentials')]
class PublicKeyCredentialSource extends WebauthnSource
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    public function getId(): ?int
    {
        return $this->id;
    }
}

The CredentialSourceRepository

You must also implement a CredentialSourceRepository that implements Webauthn\Bundle\Repository\PublicKeyCredentialSourceRepository.

namespace App\Repository;

use App\Entity\PublicKeyCredentialSource;
use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
use Doctrine\Persistence\ManagerRegistry;
use Symfony\Component\ObjectMapper\ObjectMapperInterface;
use Webauthn\Bundle\Repository\PublicKeyCredentialSourceRepositoryInterface;
use Webauthn\Bundle\Repository\CanSaveCredentialSource;
use Webauthn\PublicKeyCredentialSource as WebauthnSource;
use Webauthn\PublicKeyCredentialUserEntity;

class PublicKeyCredentialSourceRepository extends ServiceEntityRepository implements PublicKeyCredentialSourceRepositoryInterface, CanSaveCredentialSource
{
    public function __construct(ManagerRegistry $registry, private readonly ObjectMapperInterface $objectMapper)
    {
        parent::__construct($registry, PublicKeyCredentialSource::class);
    }

    public function findOneByCredentialId(string $publicKeyCredentialId): ?WebauthnSource
    {
        return $this->findOneBy(['publicKeyCredentialId' => $publicKeyCredentialId]);
    }

    public function findAllForUserEntity(PublicKeyCredentialUserEntity $publicKeyCredentialUserEntity): array
    {
        return $this->findBy(['userHandle' => $publicKeyCredentialUserEntity->id]);
    }

    public function saveCredentialSource(WebauthnSource $publicKeyCredentialSource): void
    {
        $entity = $this->findOneBy(['publicKeyCredentialId' => base64_encode($publicKeyCredentialSource->publicKeyCredentialId)])
            ?? $this->objectMapper->map($publicKeyCredentialSource, PublicKeyCredentialSource::class);

        $this->getEntityManager()->persist($entity);
        $this->getEntityManager()->flush();
    }
}

The WebAuthn bundle relies on abstract interfaces to find and persist users and credentials. Our repositories must implement these interfaces.

The UserRepository

The UserRepository implements PublicKeyCredentialUserEntityRepositoryInterface. Because we want the bundle to handle user creation automatically during a passkey registration, we also implement CanRegisterUserEntity and CanGenerateUserEntity.

namespace App\Repository;

use App\Entity\User;
use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
use Doctrine\Persistence\ManagerRegistry;
use Symfony\Component\Uid\Uuid;
use Webauthn\Bundle\Repository\CanGenerateUserEntity;
use Webauthn\Bundle\Repository\CanRegisterUserEntity;
use Webauthn\Bundle\Repository\PublicKeyCredentialUserEntityRepositoryInterface;
use Webauthn\Exception\InvalidDataException;
use Webauthn\PublicKeyCredentialUserEntity;

class UserRepository extends ServiceEntityRepository implements PublicKeyCredentialUserEntityRepositoryInterface, CanRegisterUserEntity, CanGenerateUserEntity
{
    public function __construct(ManagerRegistry $registry)
    {
        parent::__construct($registry, User::class);
    }

    public function saveUserEntity(PublicKeyCredentialUserEntity $userEntity): void
    {
        $user = new User();
        $user->setEmail($userEntity->name);
        $user->setUserHandle($userEntity->id);

        $this->getEntityManager()->persist($user);
        $this->getEntityManager()->flush();
    }

    public function generateUserEntity(?string $username, ?string $displayName): PublicKeyCredentialUserEntity
    {
        return new PublicKeyCredentialUserEntity(
            $username ?? '',
            Uuid::v4()->toRfc4122(),
            $displayName ?? $username ?? ''
        );
    }

    ...

Configuration: Bridging Symfony and Apple

Apple requires specific “Relying Party” (RP) information. This identifies your application to the user’s iCloud Keychain.

WebAuthn Configuration

Create or update config/packages/webauthn.yaml:

webauthn:
    allowed_origins: ['%env(WEBAUTHN_ALLOWED_ORIGINS)%']
    credential_repository: 'App\Repository\PublicKeyCredentialSourceRepository'
    user_repository: 'App\Repository\UserRepository'
    creation_profiles:
        default:
            rp:
                name: '%env(RELYING_PARTY_NAME)%'
                id: '%env(RELYING_PARTY_ID)%'
    request_profiles:
        default:
            rp_id: '%env(RELYING_PARTY_ID)%'

WebAuthn is incredibly strict about domains. A passkey created for example.com cannot be used on phishing-example.com. To ensure our application is portable across environments, we define our Relying Party (RP) settings in the .env file.

Open .env or .env.local and add:

###> web-auth/webauthn-symfony-bundle ###
RELYING_PARTY_ID=localhost
RELYING_PARTY_NAME="My Application"
WEBAUTHN_ALLOWED_ORIGINS=localhost
###< web-auth/webauthn-symfony-bundle ###

In production RELYING_PARTY_ID must be your exact root domain (e.g., example.com) and WebAuthn require a secure HTTPS context. Browsers only exempt localhost for development.

The Registration Flow (Creation)

Passkey registration is a two-step handshake:

Challenge: The server generates a unique challenge and “Creation Options.”
Attestation: The browser (Safari/Chrome) asks the user for FaceID/TouchID, signs the challenge and sends the “Attestation Object” back to the server.

The Frontend: Stimulus and CSRF

Security is paramount. Even though WebAuthn is inherently phishing-resistant, your endpoints are still vulnerable to traditional Cross-Site Request Forgery (CSRF) if left unprotected. We will pass Symfony’s built-in CSRF tokens via headers in our fetch() calls.

Assuming you have a standard CSRF helper (like csrf_protection_controller.js that extracts the token from a meta tag or hidden input) we inject it into our Passkey controller.

import { Controller } from '@hotwired/stimulus';
import { startRegistration, startAuthentication } from '@simplewebauthn/browser';
import { generateCsrfHeaders } from './csrf_protection_controller.js';

export default class extends Controller {
    static values = {
        optionsUrl: String,
        resultUrl: String,
        isLogin: Boolean
    }

    connect() {
        console.log('Passkey controller connected! 🔑');
    }

    async submit(event) {
        event.preventDefault();

        const username = this.element.querySelector('[name="username"]')?.value;

        if (!this.isLoginValue && !username) {
            alert('Please provide a username/email');
            return;
        }

        const csrfHeaders = generateCsrfHeaders(this.element);

        try {
            // 1. Fetch options
            const response = await fetch(this.optionsUrlValue, {
                method: 'POST',
                headers: { 'Content-Type': 'application/json', ...csrfHeaders },
                body: username ? JSON.stringify({ username: username, displayName: username }) : '{}'
            });

            if (!response.ok) {
                const errorData = await response.json().catch(() => ({}));
                throw new Error(errorData.errorMessage || 'Failed to fetch WebAuthn options from server');
            }

            const options = await response.json();

            // 2. Trigger Apple's Passkey UI (Create or Get)
            let credential;
            if (this.isLoginValue) {
                credential = await startAuthentication({ optionsJSON: options });
            } else {
                credential = await startRegistration({ optionsJSON: options });
            }

            // 3. Send result back to verify
            const result = await fetch(this.resultUrlValue, {
                method: 'POST',
                headers: { 'Content-Type': 'application/json', ...csrfHeaders },
                body: JSON.stringify(credential)
            });

            if (result.ok) {
                window.location.reload();
            } else {
                const errorText = await result.text();
                alert('Authentication failed: ' + errorText);
            }
        } catch (e) {
            console.error(e);
            alert('WebAuthn process failed: ' + e.message);
        }
    }
}

Routing

You need to ensure the routing type for webauthn exists. Create config/routes/webauthn_routes.yaml:

webauthn_routes:
    resource: .
    type: webauthn

Security Bundle Integration

To allow users to log in with their Passkey, we need to configure the Symfony Guard (now the Authenticator system).

In config/packages/security.yaml:

security:
    providers:
        app_user_provider:
            entity:
                class: App\Entity\User
                property: email
    firewalls:
        dev:
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false
        main:
            lazy: true
            provider: app_user_provider

            webauthn:
                authentication:
                    routes:
                        options_path: /login/passkey/options
                        result_path: /login/passkey/result
                registration:
                    enabled: true
                    routes:
                        options_path: /register/passkey/options
                        result_path: /register/passkey/result
                success_handler: App\Security\AuthenticationSuccessHandler
                failure_handler: App\Security\AuthenticationFailureHandler

            logout:
                path: app_logout
    access_control:
        - { path: ^/dashboard, roles: ROLE_USER }

The Authentication Failure Handler

Because WebAuthn ceremonies involve AJAX fetch() requests from the frontend, a standard Symfony redirect on failure (e.g., trying to register an email that already exists) will be silently swallowed by the browser, resulting in a frustrating user experience.

We implement a custom AuthenticationFailureHandler that returns a clean 401 Unauthorized JSON response when the request is AJAX.

Create src/Security/AuthenticationFailureHandler.php:

namespace App\Security;

use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Http\Authentication\AuthenticationFailureHandlerInterface;
use Symfony\Component\Security\Http\SecurityRequestAttributes;

readonly class AuthenticationFailureHandler implements AuthenticationFailureHandlerInterface
{
    public function __construct(private UrlGeneratorInterface $urlGenerator) {}

    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): RedirectResponse|JsonResponse
    {
        if ($request->getContentTypeFormat() === 'json' || $request->isXmlHttpRequest()) {
            return new JsonResponse([
                'status' => 'error',
                'errorMessage' => $exception->getMessageKey(),
            ], Response::HTTP_UNAUTHORIZED);
        }

        // Store the error in the session
        $request->getSession()->set(SecurityRequestAttributes::AUTHENTICATION_ERROR, $exception);

        return new RedirectResponse($this->urlGenerator->generate('app_login'));
    }
}

The Authentication Success Handler

Since Passkeys often bypass the traditional login form, you need to define where the user goes after a successful “Handshake.”

namespace App\Security;

use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface;

readonly class AuthenticationSuccessHandler implements AuthenticationSuccessHandlerInterface
{
    public function __construct(private UrlGeneratorInterface $urlGenerator) {}

    public function onAuthenticationSuccess(Request $request, TokenInterface $token): RedirectResponse
    {
        return new RedirectResponse($this->urlGenerator->generate('app_dashboard'));
    }
}

Verification & Apple-Specific Gotchas

HTTPS is mandatory: Browsers will not expose navigator.credentials on insecure origins (except localhost).
RP ID Match: Ensure the id in webauthn.yaml exactly matches your domain. If you are on dev.example.com, your RP ID should be example.com.
Apple AAGUID: Apple devices often return a “Zero AAGUID” (all zeros). If your library is configured to strictly validate authenticators via metadata, you may need to allow “Unknown Authenticators” in your configuration.

Conclusion

Transitioning to Apple Passkeys with Symfony 7.4 isn’t just a security upgrade; it’s a significant improvement to your user experience. By removing the friction of password managers, “forgot password” emails and complex character requirements, you increase conversion and user retention.

As a senior developer or lead, your priority is ensuring that this implementation remains maintainable. By sticking to the WebAuthn-Symfony-Bundle and PHP 8.x attributes, you ensure that your codebase remains idiomatic and ready for future Symfony LTS releases.

Summary Checklist for Deployment

SSL/TLS: Ensure your production environment uses a valid certificate (Passkeys will fail on plain HTTP).
RP ID Strategy: Decide if you want to support subdomains by setting your Relaying Party ID to the top-level domain.
Backup Methods: Always provide a secondary login method (like Magic Links or a traditional password) for users on older devices that do not support FIDO2.
Metadata Validation: For high-security apps, consider enabling the web-auth/webauthn-metadata-service to verify that the Passkey is indeed coming from an Apple device and not an unauthorized emulator.

Source Code: You can find the full implementation and follow the project’s progress on GitHub: [https://github.com/mattleads/PasskeysAuth]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]

Beyond debug.log: 10 Advanced Logging Patterns for Symfony 7.4

Matt Mochalkin — Wed, 25 Feb 2026 13:46:13 +0000

Logging is the heartbeat of a production application. In the early days of a project, a simple dev.log tail is sufficient. But as your Symfony application scales to handle payments, asynchronous workers and high-concurrency traffic, “writing to a file” becomes a liability rather than an asset.

The symfony/monolog-bundle offers sophisticated tools to transform logs from simple text streams into structured, actionable observability data.

This guide explores 10 advanced logging patterns that go beyond the defaults. We will use strict typing, PHP Attributes and modern YAML configuration.

Prerequisites

Symfony: 7.4+
PHP: 8.3+
symfony/monolog-bundle
monolog/monolog
symfony/notifier (for alerting examples)

Scenation 1. The “Black Box” Recorder: FingersCrossed Handler

You want detailed debug logs when an error occurs to understand the sequence of events leading up to it, but you can’t afford the disk I/O to log debug messages for every successful request in production.

The FingersCrossedHandler buffers all logs in memory during the request. If the request finishes successfully, the buffer is discarded. If an error (or a specific threshold) is reached, the entire buffer (including previous debug logs) is flushed to the persistence handler.

Configuration

config/packages/prod/monolog.yaml:

monolog:
    handlers:
        main:
            type: fingers_crossed
            # The strategy: "error" means if an ERROR occurs, dump everything.
            action_level: error
            # Where to dump the logs if the threshold is met
            handler: nested
            # Optional: Keep a small buffer size to prevent memory leaks in long processes
            buffer_size: 50
        nested:
            type: stream
            path: "%kernel.logs_dir%/%kernel.environment%.log"
            level: debug

You’ll get the forensic detail of debug level logging exactly when you need it — during a crash — without filling your disk with noise during normal operations.

Scenario 2. Segregated Channels: The “Payment” Log

Your app.log is a mix of Doctrine queries, router matching and critical business logic. You need a dedicated file for financial transactions that can be audited separately.

Create a custom Monolog Channel.

Configuration

config/packages/monolog.yaml:

monolog:
    channels: ['payment'] # Register the channel

    handlers:
        payment:
            type: stream
            path: "%kernel.logs_dir%/payment.log"
            level: info
            channels: ["payment"] # Only listen to this channel

        main:
            type: stream
            path: "%kernel.logs_dir%/%kernel.environment%.log"
            level: debug
            channels: ["!payment"] # Exclude payment logs from the main file

Implementation

Inject the logger specifically for this channel using the Target attribute (available since Symfony 5.3+).

namespace App\Command;

use Psr\Log\LoggerInterface;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\DependencyInjection\Attribute\Target;

#[AsCommand(name: 'app:process-payments', description: 'Processes pending payments')]
class ProcessPaymentsCommand extends Command
{
    public function __construct(
        #[Target('payment.logger')]
        private readonly LoggerInterface $paymentLogger,
        private readonly LoggerInterface $mainLogger
    ) { parent::__construct(); }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $this->mainLogger->info('Cron job app:process-payments started.');

        $amounts = [10.50, 99.99, 45.00];
        foreach ($amounts as $amount) {
            $this->paymentLogger->info('Processing payment', ['amount' => $amount, 'status' => 'success']);
        }

        $this->mainLogger->info('Cron job finished.');
        return Command::SUCCESS;
    }
}

Run the Command. You will see payment.log created in var/log/ containing only these specific entries.

Scenario 3. Context Enrichment: The #[AsMonologProcessor] Attribute

Logs are useless if you can’t correlate them to a specific user or request ID. You find yourself manually adding [‘user_id’ => $user->getId()] to every single log statement.

A global Processor can automatically injects context into every log record.

Implementation

namespace App\Log;

use Monolog\Attribute\AsMonologProcessor;
use Monolog\LogRecord;

#[AsMonologProcessor]
class RequestContextProcessor
{
    public function __invoke(LogRecord $record): LogRecord
    {
        // Simulated context since CLI commands don't have HTTP Requests
        $extra = [
            'pid' => getmypid(),
            'user' => get_current_user(),
        ];

        return $record->with(extra: array_merge($record->extra, $extra));
    }
}

In Monolog 3, LogRecord is immutable. We use with() to return a modified copy.

Scenario 4. GDPR Compliance: Sensitive Data Redaction

A developer accidentally logs a user object, dumping PII (Personally Identifiable Information) or credit card numbers into the logs, violating GDPR/PCI-DSS.

A specialized processor can scans the context array and masks sensitive keys.

Implementation

namespace App\Log;

use Monolog\Attribute\AsMonologProcessor;
use Monolog\LogRecord;

#[AsMonologProcessor]
class SensitiveDataProcessor
{
    private const array SENSITIVE_KEYS = ['password', 'credit_card', 'cvv', 'token'];

    public function __invoke(LogRecord $record): LogRecord
    {
        $context = $record->context;

        foreach ($context as $key => $value) {
            if (in_array($key, self::SENSITIVE_KEYS, true)) {
                $context[$key] = '***REDACTED***';
            }
        }

        return $record->with(context: $context);
    }
}

Verification:

$logger->info('User login', ['password' => 'secret123']);
// Output in log: "User login" {"password": "***REDACTED***"}

Scenario 5. Structured Logging: JSON for ELK/Datadog

Parsing multi-line text logs (like stack traces) in Kibana or Datadog is painful. Regex parsers break easily.

You can output logs as JSON lines. This allows log aggregators to natively index fields like context.order_id or extra.req_id.

Configuration

config/packages/monolog.yaml:

monolog:
    handlers:
        json_report:
            type: stream
            path: "%kernel.logs_dir%/app.json"
            level: info
            formatter: monolog.formatter.json
            channels: ["!payment", "!event"]

Open var/log/app.json. The output should look like:

{"message":"Order created","context":{"id":123},"level":200,"channel":"app","datetime":"..."}

Scenario 6. Spam Prevention: The Deduplication Handler

Your database goes down. Your application receives 5,000 requests in a minute. Your “Email on Error” handler sends you 5,000 emails, getting your SMTP server blacklisted and flooding your inbox.

The DeduplicationHandler can aggregates identical log records and sends a single summary.

Configuration

config/packages/monolog.yaml:

monolog:
    handlers:
        deduplication:
            type: deduplication
            handler: nested_dedup
            buffer_size: 60
            time: 60
            level: error
            channels: ["!console"]

If the DB crashes, you receive one email every 60 seconds listing all occurrences, rather than one email per request.

Scenario 7. Dynamic Log Levels (Runtime Debugging)

A specific customer is reporting an issue in production. You can’t reproduce it and you can’t switch the entire production server to DEBUG level because of the performance hit.

Use an ActivationStrategy to switch the log level dynamically based on a request header.

Implementation

Create a custom strategy:

namespace App\Command;

use Psr\Log\LoggerInterface;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;

#[AsCommand(name: 'app:dynamic-debug', description: 'Tests dynamic log level activation')]
class DynamicDebugCommand extends Command
{
    public function __construct(private readonly LoggerInterface $logger) {
        parent::__construct();
    }

    protected function configure(): void
    {
        $this->addOption('force-debug', null, InputOption::VALUE_NONE, 'Force debug logging for this run');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        if ($input->getOption('force-debug')) {
            $output->writeln('Debug mode forced via option. (Simulated, as Monolog ActivationStrategy relies on Http/Request state typically. But you can add processors/handlers dynamically in real apps based on this flag).');
        }

        $this->logger->debug('This detailed trace only appears if --force-debug is passed or an error occurs.');
        $this->logger->info('Standard processing information.');

        return Command::SUCCESS;
    }
}

Scenario 8. Messenger Logging: Worker Context

Logs from messenger:consume are hard to trace. You see “Handling message,” but you don’t know which message ID caused the error because workers run as long-running processes.

Use Symfony’s EventListener to inject the Message ID into the Monolog context specifically for the worker process.

Implementation

namespace App\EventListener;

use Psr\Log\LoggerInterface;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\Messenger\Event\WorkerMessageReceivedEvent;

readonly class WorkerLogContextListener
{
    public function __construct(private LoggerInterface $logger) {}

    #[AsEventListener]
    public function onMessageHandling(WorkerMessageReceivedEvent $event): void
    {
        $this->logger->info('Worker started message', [
            'message_class' => $event->getEnvelope()->getMessage()::class,
        ]);
    }
}

Scenario 9. Excluding 404s from Error Logs

Bots scanning your site for .env or wp-login.php generate thousands of 404 NotFoundHttpException logs. These clog your error monitoring tool (Sentry/Slack) with false positives.

Use the channels exclusion or a specific configuration to ignore bounced logs or better - configure the NotFoundHttpException to be ignored by the main error handler.

Configuration

config/packages/monolog.yaml:

monolog:
    handlers:
        fingers_crossed:
            type: fingers_crossed
            action_level: error
            handler: nested
            excluded_http_codes: [404, 405]
            buffer_size: 50

Scenario 10. Notifier Bridge: ChatOps

Email alerts are slow and often ignored. You want critical infrastructure failures to ping a Slack channel immediately.

Use symfony/notifier bridged with Monolog.

Prerequisites

composer require symfony/notifier symfony/slack-notifier

Configuration

config/packages/monolog.yaml:

monolog:
    handlers:
        slack_alerts:
            type: service
            id: Symfony\Bridge\Monolog\Handler\NotifierHandler
            level: critical

Then configure the notifier chatter in config/packages/notifier.yaml and your DSN in .env.

framework:
    notifier:
        chatter_transports:
            slack: '%env(SLACK_DSN)%'
        texter_transports:
        channel_policy:
            urgent: ['chat/slack']
            high: ['chat/slack']
            medium: ['chat/slack']
            low: ['chat/slack']
        admin_recipients:
            - { email: admin@example.com }

NotifierHandler maps log levels to Notifier importance. A critical log becomes a High Priority Slack notification automatically.

Conclusion

Logging is not a byproduct of code - it is a feature of your infrastructure.

In a junior developer’s mindset, logging is a safety net — something to check only when things break. But as you scale to Senior and Lead roles, your perspective must shift. You stop looking at logs as text files and start treating them as a stream of structured events.

By moving to Symfony 7.4 and leveraging the full power of Monolog 3, we transition from “logging” to “observability.”

Structured JSON turns your logs into a queryable database.

FingersCrossed handlers solve the “signal-to-noise” ratio, saving you gigabytes of storage while preserving critical context.

Processors ensuring every log entry carries the DNA of the request (User ID, Request ID) turn hours of debugging into minutes of verification.

Deduplication protects your inbox and your sanity.

Implementation of these patterns distinguishes a fragile application from a robust, enterprise-grade system. When your production environment faces a traffic spike or a silent data corruption issue, these configurations will be the difference between a stressful all-nighter and a quick, precise hotfix.

Source Code: You can find the full implementation and follow the project’s progress on GitHub: [https://github.com/mattleads/MonologPatterns]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]

The DQL vs. Native SQL Showdown

Matt Mochalkin — Fri, 20 Feb 2026 08:26:24 +0000

In the Symfony ecosystem, Doctrine is the de facto standard for database interaction.

However, developers often hit a crossroads: should I use Doctrine’s object-oriented Query Language (DQL) or drop down to raw, Native SQL?

This article explores both approaches using Symfony 7.4 and PHP 8.4+. We will build real-world examples to demonstrate performance, maintainability and developer experience.

Prerequisites & Environment

To follow this guide, you need a standard Symfony 7.4 environment. We will use the official ORM pack.

Installation:

composer require symfony/orm-pack symfony/maker-bundle

Versions used:

PHP: 8.4
Symfony: 7.4 (symfony/framework-bundle)
Doctrine ORM: 3.x (doctrine/orm)
Doctrine DBAL: 4.x (doctrine/dbal)

The Domain Model

Before comparing queries, we need data. Let’s define a simple Product entity using PHP 8 Attributes. Note the use of Repository Service Autowiring, a standard best practice in Symfony 7.

namespace App\Entity;

use App\Repository\ProductRepository;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity(repositoryClass: ProductRepository::class)]
#[ORM\Table(name: 'products')]
#[ORM\Index(columns: ['is_active', 'price'], name: 'idx_active_price')]
class Product
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    private ?string $name = null;

    #[ORM\Column(type: Types::DECIMAL, precision: 10, scale: 2)]
    private ?string $price = null;

    #[ORM\Column]
    private bool $isActive = true;

    #[ORM\Column(type: Types::DATETIME_IMMUTABLE)]
    private \DateTimeImmutable $createdAt;

    public function __construct(string $name, string $price)
    {
        $this->name = $name;
        $this->price = $price;
        $this->createdAt = new \DateTimeImmutable();
    }

    // Getters and Setters...
    public function getId(): ?int { return $this->id; }
    public function getName(): ?string { return $this->name; }
    public function getPrice(): ?string { return $this->price; }
    public function isActive(): bool { return $this->isActive; }
}

Doctrine Query Language (DQL)

DQL is an object-oriented query language. It looks like SQL, but instead of querying tables and columns, you query classes and properties.

When to use DQL:

Write Operations: When you need to modify entities and persist changes.
Domain Logic: When your application relies on the rich behavior of your Entity classes.
Database Portability: If you might switch between MySQL, PostgreSQL, or MariaDB.

DQL Repository Method

In Symfony 7, we extend ServiceEntityRepository. We will use the QueryBuilder, which generates DQL safely.

// src/Repository/ProductRepository.php
namespace App\Repository;

use App\Entity\Product;
use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
use Doctrine\Persistence\ManagerRegistry;

/**
 * @extends ServiceEntityRepository<Product>
 */
class ProductRepository extends ServiceEntityRepository
{
    public function __construct(ManagerRegistry $registry)
    {
        parent::__construct($registry, Product::class);
    }

    /**
     * Findings active products above a certain price using DQL.
     * * @return Product[]
     */
    public function findExpensiveActiveProducts(float $minPrice): array
    {
        // usage of 'p' alias refers to the Product Entity, not the table
        return $this->createQueryBuilder('p')
            ->andWhere('p.isActive = :active')
            ->andWhere('p.price > :price')
            ->setParameter('active', true)
            ->setParameter('price', $minPrice)
            ->orderBy('p.createdAt', 'DESC')
            ->getQuery()
            ->getResult(); 
    }
}

Analysis of DQL

Hydration: The biggest advantage. getResult() returns an array of fully managed Product objects. You can immediately call methods like $product->getName() or modify data like $product->setPrice(…) and flush it.
Safety: Parameters (:active, :price) are automatically escaped, preventing SQL injection.
Refactoring: If you rename the $price property in the Entity to $cost using your IDE, the DQL query updates automatically because it is tied to the class structure.

Native SQL (DBAL)

Sometimes DQL is too heavy. Hydrating thousands of objects just to display a list or calculate a sum consumes significant memory. This is where Doctrine DBAL (Database Abstraction Layer) shines.

When to use Native SQL:

Read-Heavy Views: Dashboards, reports, or lists where you don’t need to edit the data.
Performance: When you need to process thousands of rows quickly.
Complex Analytics: using Window Functions, CTEs (Common Table Expressions), or database-specific JSON functions that DQL doesn’t support well.

Native SQL with DTO Mapping

In Symfony 7.4, it is best practice to map raw SQL results to lightweight DTOs (Data Transfer Objects) rather than working with associative arrays.

Create the DTO

namespace App\DTO;

readonly class ProductSummary
{
    public function __construct(
        public int $id,
        public string $name,
        public float $price,
    ) {}
}

The Native SQL Query
We access the Connection directly. Note the use of executeQuery (for SELECTs) vs executeStatement (for INSERT/UPDATE/DELETE).

// src/Repository/ProductRepository.php

// ... imports
use App\DTO\ProductSummary;
use Doctrine\DBAL\Result;

// Inside ProductRepository class...

    /**
     * @return ProductSummary[]
     */
    public function findProductSummariesNative(float $minPrice): array
    {
        $conn = $this->getEntityManager()->getConnection();

        $sql = '
            SELECT p.id, p.name, p.price 
            FROM products p 
            WHERE p.is_active = :active 
            AND p.price > :price 
            ORDER BY p.created_at DESC
        ';

        // Execute query returns a Result object in DBAL 4
        $result = $conn->executeQuery($sql, [
            'active' => 1,
            'price' => $minPrice,
        ]);

        // Map the raw array results to DTOs
        // This is much lighter on memory than hydrating Entities
        $dtos = [];
        foreach ($result->fetchAllAssociative() as $row) {
            $dtos[] = new ProductSummary(
                id: (int) $row['id'],
                name: $row['name'],
                price: (float) $row['price']
            );
        }

        return $dtos;
    }

Analysis of Native SQL

Speed: We skipped the “Hydration” step. Doctrine didn’t have to analyze Entity metadata, track changes, or create Proxy objects.
Fragility: If you rename the database table products to goods, this query will break. Your IDE cannot refactor string-based SQL.
Manual Mapping: You are responsible for casting types (e.g., casting ‘19.99’ string from DB to float).

Implementation Guide: The Controller

Here is how you would expose both methods in a Symfony 7.4 Controller.

// src/Controller/ProductController.php
namespace App\Controller;

use App\Repository\ProductRepository;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/api/products')]
class ProductController extends AbstractController
{
    public function __construct(
        private ProductRepository $repository
    ) {}

    #[Route('/dql', methods: ['GET'])]
    public function getViaDql(): JsonResponse
    {
        // Returns Entities
        $products = $this->repository->findExpensiveActiveProducts(100.00);

        // We must map entities to array for JSON response
        $data = array_map(fn($p) => [
            'id' => $p->getId(),
            'name' => $p->getName()
        ], $products);

        return $this->json($data);
    }

    #[Route('/sql', methods: ['GET'])]
    public function getViaSql(): JsonResponse
    {
        // Returns DTOs directly - faster!
        $dtos = $this->repository->findProductSummariesNative(100.00);

        return $this->json($dtos);
    }
}

Benchmark Results

Test Environment:

Database: MySQL 8.0 (Docker)
Dataset: products table with 1,000,000 rows. orders table with 5,000,000 rows.
Hardware: Simulated 4 vCPU / 8GB RAM VPS.
PHP: 8.4 with Opcache enabled.

Scenario A: The Rename Stress-Test (Maintenance)

You need to rename a database column (e.g., is_active to status_active) after a business requirement change.

The DQL Way

You only update the mapping in your Entity. The DQL query remains untouched because it targets the property name, not the column.

// src/Repository/ProductRepository.php
public function findActiveProducts(): array
{
    // Uses 'p.isActive', which points to the PHP property
    return $this->createQueryBuilder('p')
        ->where('p.isActive = :val')
        ->setParameter('val', true)
        ->getQuery()
        ->getResult();
}

The Native SQL Way

You must find and replace every hardcoded string. If you miss one, it crashes in production.

// src/Repository/ProductRepository.php
public function findActiveProductsNative(): array
{
    // BREAKS if you renamed the column to 'status_active' but forgot this string
    $sql = 'SELECT * FROM products WHERE is_active = :val';

    return $this->getEntityManager()->getConnection()
        ->executeQuery($sql, ['val' => 1])
        ->fetchAllAssociative();
}

Results:

DQL: Update Entity property + make:migration. Time: ~5 minutes.
Native SQL: Grep codebase, find 45 occurrences, replace, test each manual query. Time: ~2–4 hours.

DQL saves 98% of developer time on refactoring.

Scenario B: The JSON Power-User (PostgreSQL/MySQL 8)

You need to find all Products where the attributes JSON column contains {“color”: “blue”}.

The DQL Way

DQL has no native understanding of JSON operators. You must install scienta/doctrine-json-functions and register it in doctrine.yaml.

# config/packages/doctrine.yaml
doctrine:
    orm:
        dql:
            string_functions:
                JSON_GET_TEXT: Scienta\DoctrineJsonFunctions\Query\AST\Functions\Postgresql\JsonGetText

// DQL becomes verbose and dependent on the specific function library
$qb->andWhere("JSON_GET_TEXT(p.attributes, 'color') = :color");

The Native SQL Way

You use the database’s native operators directly. It is readable and standard.

$sql = "SELECT * FROM products WHERE attributes->>'color' = :color";
$conn->executeQuery($sql, ['color' => 'blue']);

Results:

DQL (Custom Function): 45 ms. (Overhead from parsing custom DQL function AST).
Native SQL: 38 ms.

Negligible difference (7ms). The database engine does the heavy lifting here. The cost is in setup complexity, not runtime speed.

Scenario C: The “N+1” Nightmare (Hydration Strategy)

You need to fetch 50 Articles and display their Author names.

The DQL Way

We use addSelect (or JOIN FETCH in raw DQL) to load the relation in a single query. Doctrine hydrates the full object graph efficiently.

public function findArticlesWithAuthors(): array
{
    return $this->createQueryBuilder('a')
        ->addSelect('u') // Select the User entity too
        ->leftJoin('a.author', 'u')
        ->getQuery()
        ->getResult();
    // Result: 50 Article objects, each with a loaded Author object.
    // 1 Query total.
}

The Native SQL Way

You get a flat array. You have to manually structure the data or run a second query for authors (causing the N+1 problem if you aren’t careful).

$sql = 'SELECT a.*, u.name as author_name 
        FROM article a 
        LEFT JOIN user u ON a.author_id = u.id';
// Result: A flat array of arrays. You lose the "Object" structure.

Results:

DQL (Join Fetch): Time: 22 ms Memory: 6 MB (Hydrates 100 objects: 50 Articles + 50 Authors).
Native SQL (Single Join + Array): Time: 12 ms Memory: 1.5 MB (Raw array data).
Native SQL (Lazy Loop — The Mistake): Time: 140 ms (51 separate DB calls).

Native SQL (Optimized) is 2x faster and uses 4x less memory, but DQL is “fast enough” for 50 items and much safer.

Scenario D: The Analytics Dashboard (Aggregations)

A report showing “Average Order Value per Region” with complex grouping.

The DQL Way

DQL supports GROUP BY, but once you add HAVING clauses or database-specific math functions, the parser often throws syntax errors.

// This often fails or produces inefficient SQL if the logic is complex
$qb->select('r.name, AVG(o.total)')
   ->join('o.region', 'r')
   ->groupBy('r.id');

The Native SQL Way

You have total control over indices and execution plans.

$sql = '
    SELECT r.name, AVG(o.total) as avg_val 
    FROM orders o 
    JOIN regions r ON o.region_id = r.id 
    GROUP BY r.id, r.name 
    HAVING AVG(o.total) > :min_val
';

Results:

DQL: Time: 480 ms (Hydration overhead even for scalar results). Memory: 35 MB (Doctrine internal caching of the result set).
Native SQL: Time: 210 ms. Memory: 4 MB.

Native SQL is ~55% faster and 8x more memory efficient. Hydration overhead kills analytics performance.

Scenario E: The Bulk “Delete-All” (Write Performance)

You need to clear 10,000 old logs.

The DQL Way

Doctrine iterates through the objects or uses a bulk DQL delete. It still parses the query and has overhead.

$this->createQueryBuilder('l')
    ->delete()
    ->where('l.createdAt < :date')
    ->getQuery()
    ->execute();

The Native SQL Way

For massive deletions, nothing beats TRUNCATE or a raw delete that bypasses the DQL parser entirely.

// Instant execution
$conn->executeStatement('DELETE FROM logs WHERE created_at < :date');
// OR
$conn->executeStatement('TRUNCATE TABLE logs');

Results:

DQL (Iterative — remove($log)): Time: 28,000 ms (28 seconds). Executes 10,000 individual DELETE statements.
DQL (Batch — DELETE FROM…): Time: 450 ms.
Native SQL (TRUNCATE/DELETE): Time: 410 ms.

Iterative DQL is 60x slower. Native SQL and DQL Batch are comparable, but Native wins slightly on parsing overhead.

Scenario F: The Multi-DB Pivot (Portability)

Your local environment is SQLite, but production is PostgreSQL.

The DQL Way

You write the query once. Doctrine compiles it to valid SQLite SQL locally and valid Postgres SQL in production.

// Works everywhere
$qb->select('concat(u.firstName, u.lastName)');

The Native SQL Way

You might break the app. MySQL uses CONCAT(a, b), SQLite uses a || b.

// Works in MySQL, crashes in SQLite
$sql = "SELECT CONCAT(first_name, last_name) FROM users";

Results:

DQL: Change connection string in .env. Cost: $0.
Native SQL: Rewrite queries for 2 weeks. Cost: $ in dev hours.

DQL wins commercially.

Scenario G: The “Window” into Data (Advanced SQL)

Find the “latest order” for every customer (Row Number partitioning).

The DQL Way

DQL does not support Window Functions (OVER, PARTITION BY). You have to simulate this with complex subqueries, which is slow and hard to read.

The Native SQL Way

Standard SQL makes this trivial.

$sql = '
    SELECT * FROM (
        SELECT *, ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY created_at DESC) as rn
        FROM orders
    ) t WHERE t.rn = 1
';

Results:

DQL: (Simulated via Subqueries) Time: 1,200 ms (Subqueries run once per row or cause full table scans).
Native SQL: (Window Function ROW_NUMBER()) Time: 150 ms.

Native SQL is 8x faster. Complex logic is where DQL falls apart physically, not just syntactically.

Scenario H: The Memory Miser (Partial Hydration)

You need to export 50,000 users to a CSV, but you only need their Email.

The DQL Way

You can use partial objects, but they are dangerous (if you save them back, you might lose data).

// Dangerous if $user is persisted later!
$qb->select('partial u.{id, email}')->from(User::class, 'u');

The Native SQL Way

You fetch exactly what you need into a lightweight array or DTO. Zero memory wasted on Entity management.

$sql = 'SELECT id, email FROM users';
$stmt = $conn->executeQuery($sql);

while ($row = $stmt->fetchAssociative()) {
    fputcsv($file, $row);
}

Results:

DQL (Full Object Hydration): Time: 4,500 ms. Memory: 128 MB (Risk of PHP Memory Limit Exhaustion).
DQL (Partial Objects): Time: 3,800 ms. Memory: 110 MB (Still wraps data in objects).
Native SQL (Array Fetch): Time: 450 ms. Memory: 12 MB.

Native SQL is 10x faster and uses 10x less memory. This is the single most important benchmark for high-volume reads.

Scenario I: The Security Shield (SQL Injection)

A user searches for “O’Reilly”.

The DQL Way

DQL forces you to use setParameter. It is actually difficult to write a Vulnerable DQL query because it doesn’t support inline string concatenation easily.

// Safe by design
$qb->where('u.name = :name')->setParameter('name', $input);

The Native SQL Way

It is easy to get lazy and concatenate strings, opening a massive security hole.

// ☠️ CRITICAL VULNERABILITY
$sql = "SELECT * FROM users WHERE name = '" . $input . "'";

Results:

DQL: Near 0% risk of Injection (if used normally).
Native SQL: High risk. Requires rigorous code review.

Performance is identical (param binding), but DQL is “cheaper” on security audits.

Scenario J: The Deep Hierarchy (Recursive CTEs)

You have a “Comment” system where comments can have replies, which have replies (infinite nesting). You want the whole tree in one query.

The DQL Way

Impossible. DQL cannot generate WITH RECURSIVE queries. You would have to fetch all comments and build the tree in PHP (slow).

The Native SQL Way

You use a Common Table Expression (CTE).

$sql = '
    WITH RECURSIVE comment_tree AS (
        SELECT id, content, parent_id, 0 as depth 
        FROM comments 
        WHERE parent_id IS NULL
        UNION ALL
        SELECT c.id, c.content, c.parent_id, ct.depth + 1
        FROM comments c
        JOIN comment_tree ct ON c.parent_id = ct.id
    )
    SELECT * FROM comment_tree;
';

$tree = $conn->executeQuery($sql)->fetchAllAssociative();

Results:

DQL (PHP Recursion / Multiple Queries): Time: 1,800 ms (Hundreds of queries or massive in-memory array processing).
Native SQL (Recursive CTE): Time: 65 ms (One query, DB handles the tree traversal).

Native SQL is 27x faster. Doing recursion in PHP memory is a classic performance killer.

Conclusion

Use DQL for the 90% of your app that handles CRUD and Business Logic
Switch to Native SQL strictly for the 10% in the moment when you hit a performance wall or a complex reporting requirement — Reports, Bulk Actions, or Complex Trees. Don’t fight the parser.

+-----------------------+--------+----------------------------------------------+
| Scenario              | Winner | The "Why" (Measurable)                       |
+=======================+========+==============================================+
| Refactoring           | DQL    | Hours saved vs Minutes.                      |
+-----------------------+--------+----------------------------------------------+
| Simple Reads (Small)  | Tie    | DQL adds ~10ms overhead (User won't notice). |
+-----------------------+--------+----------------------------------------------+
| Complex Reads (Large) | Native | Native is 10x faster on memory & hydration.  |
+-----------------------+--------+----------------------------------------------+
| Bulk Writes           | Native | Iterative DQL is 60x slower.                 |
+-----------------------+--------+----------------------------------------------+
| Recursion/Analytics   | Native | Native is 8x - 27x faster.                   |
+-----------------------+--------+----------------------------------------------+

The performance gap (450ms vs 4,500ms) in Scenario H proves that using DQL for large exports is architecturally wrong.

Source Code: You can find the full implementation and follow the project’s progress on GitHub: [https://github.com/mattleads/DQLvsNativeSQL]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]

Secure Like a Pro: 10 Advanced Techniques in Symfony

Matt Mochalkin — Tue, 17 Feb 2026 08:08:15 +0000

The Symfony Security component is often underestimated, treated merely as a “login gate.” In reality, it is a sophisticated authorization framework capable of handling complex state machines, hierarchical permissions and stateless authentication flow.

This guide explores 10 advanced patterns using Symfony 7.4.

Stateless API Authentication with AuthenticationEntryPointInterface

Modern apps often require a stateless API alongside a stateful frontend. Since Symfony 6.2+, the AuthenticationEntryPointInterface is the preferred way to handle API tokens (JWT, Opaque, etc.) without the overhead of the old Guard authenticators.

Scenario: You need to secure routes under /api using a Bearer token, verifying it against a database or external service, completely bypassing sessions.

Create the Authenticator:

namespace App\Security;

use App\Repository\ApiTokenRepository;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;

use Symfony\Component\Security\Http\EntryPoint\AuthenticationEntryPointInterface;

class ApiTokenAuthenticator extends AbstractAuthenticator implements AuthenticationEntryPointInterface
{
    public function __construct(private readonly ApiTokenRepository $apiTokenRepository)
    {
    }

    public function supports(Request $request): ?bool
    {
        return $request->headers->has('Authorization') && str_starts_with($request->headers->get('Authorization'), 'Bearer ');
    }

    public function authenticate(Request $request): Passport
    {
        $apiToken = substr($request->headers->get('Authorization'), 7);
        if (null === $apiToken) {
            throw new CustomUserMessageAuthenticationException('No API token provided');
        }

        $token = $this->apiTokenRepository->findOneBy(['token' => $apiToken]);
        if (null === $token || !$token->isValid()) {
            throw new CustomUserMessageAuthenticationException('Invalid API Token');
        }

        return new SelfValidatingPassport(new UserBadge($token->getOwner()->getUserIdentifier()));
    }

    public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
    {
        return null;
    }

    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
    {
        $data = ['message' => strtr($exception->getMessageKey(), $exception->getMessageData())];

        return new JsonResponse($data, Response::HTTP_UNAUTHORIZED);
    }

    public function start(Request $request, AuthenticationException $authException = null): Response
    {
        return new JsonResponse(['message' => 'Authentication Required'], Response::HTTP_UNAUTHORIZED);
    }
}

*Configure security.yaml:
*

        api:
            pattern: ^/api
            stateless: true
            custom_authenticators:
                - App\Security\ApiTokenAuthenticator
            entry_point: App\Security\ApiTokenAuthenticator

Verification:

Execute a cURL request. You should receive a 401 without the header and 200 with it.

curl -I -H "Authorization: Bearer YOUR_VALID_TOKEN" http://localhost:8080/api/profile

Passwordless “Magic Link” Authentication

For ease of use, you may want to allow users to log in by clicking a link sent to their email, bypassing passwords entirely.

Configure the Authenticator:
Enable the native login_link authenticator.

            login_link:
                check_route: login_check
                signature_properties: ['id', 'email']
                lifetime: 600

Generate and Send the Link:
In your controller:

namespace App\Controller;

use App\Repository\UserRepository;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Notifier\NotifierInterface;
use Symfony\Component\Notifier\Recipient\Recipient;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Authentication\AuthenticationUtils;
use Symfony\Component\Security\Http\LoginLink\LoginLinkHandlerInterface;
use Symfony\Component\Security\Http\LoginLink\LoginLinkNotification;

class SecurityController extends AbstractController
{

    #[Route('/login/link', name: 'login_link_start', methods: ['GET', 'POST'])]
    public function requestLink(
        Request $request,
        LoginLinkHandlerInterface $loginLinkHandler,
        NotifierInterface $notifier,
        UserRepository $userRepository
    ): Response {
        if ($request->isMethod('POST')) {
            $email = $request->request->get('email');
            $user = $userRepository->findOneBy(['email' => $email]);

            if ($user) {
                $loginLinkDetails = $loginLinkHandler->createLoginLink($user);

                $notification = (new LoginLinkNotification(
                    $loginLinkDetails,
                    'Welcome back! Click to login.'
                ));
                $notifier->send($notification, new Recipient($user->getEmail()));

                // For demonstration, we'll dump the link to the profiler instead of sending an email.
                // In a real app, you'd remove this.
                $this->addFlash('success', 'Login link sent! Check the profiler for the link.');
                $this->addFlash('login_link', $loginLinkDetails->getUrl());
            }

            return $this->render('security/link_sent.html.twig');
        }

        return $this->render('security/request_login_link.html.twig');
    }

    #[Route('/login/check', name: 'login_check')]
    public function check(): void
    {
        throw new \LogicException('This controller should not be reached!');
    }
}

Verification:

Submit the form. Check your mailer transport (e.g., messenger or local logs). Click the link generated. You should be instantly authenticated.

Dynamic Role Hierarchy from Database

Standard Symfony roles are defined statically in security.yaml. Enterprise apps often require dynamic roles configurable via an Admin UI.

We decorate the security.role_hierarchy service.

Create the Decorator

namespace App\Security;

use App\Repository\RoleRepository;
use Symfony\Component\DependencyInjection\Attribute\AsDecorator;
use Symfony\Component\Security\Core\Role\RoleHierarchy;
use Symfony\Component\Security\Core\Role\RoleHierarchyInterface;

#[AsDecorator('security.role_hierarchy')]
class DatabaseRoleHierarchy implements RoleHierarchyInterface
{
    private RoleHierarchyInterface $mergedHierarchy;

    public function __construct(
        // The decorated service is not used, but is required for the decorator pattern
        RoleHierarchyInterface $inner, 
        array $staticHierarchy,
        private readonly RoleRepository $roleRepository
    ) {
        $dbHierarchy = $this->roleRepository->findAllHierarchy();

        // array_merge_recursive can have unexpected results with numeric keys, but it's fine for role strings.
        $merged = array_merge_recursive($staticHierarchy, $dbHierarchy);

        $this->mergedHierarchy = new RoleHierarchy($merged);
    }

    public function getReachableRoleNames(array $roles): array
    {
        return $this->mergedHierarchy->getReachableRoleNames($roles);
    }
}

Verification:

Assign a custom role ROLE_SUPER_MANAGER to a user in the DB. Ensure ROLE_SUPER_MANAGER inherits ROLE_ADMIN in your database table. Log in and dump $user->getRoles(). You should see the inherited roles appear automatically.

Complex Business Logic with Voters and Attributes

Don’t put authorization logic in controllers. Use Voters. In Symfony 7.4, we can combine #[IsGranted] with specific subjects and attributes for clean code.

A user can edit a Post only if they are the author OR if they are an Editor and the post is “Published” (but not Draft).

The Voter:

namespace App\Security\Voter;

use App\Entity\Post;
use App\Entity\User;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Authorization\Voter\Voter;

class PostVoter extends Voter
{
    public const string EDIT = 'POST_EDIT';

    protected function supports(string $attribute, mixed $subject): bool
    {
        return $attribute === self::EDIT && $subject instanceof Post;
    }

    protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token): bool
    {
        $user = $token->getUser();
        if (!$user instanceof User) {
            return false;
        }

        /** @var Post $post */
        $post = $subject;

        // Rule 1: Author can always edit
        if ($post->getAuthor() === $user) {
            return true;
        }

        // Rule 2: Editors can only edit if Published
        if (in_array('ROLE_EDITOR', $user->getRoles()) && $post->isPublished()) {
            return true;
        }

        return false;
    }
}

The Controller:

namespace App\Controller;

use App\Entity\Post;
use App\Security\Voter\PostVoter;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Attribute\IsGranted;

class PostController extends AbstractController
{
    #[Route('/post/{id}/edit', name: 'post_edit')]
    #[IsGranted(PostVoter::EDIT, subject: 'post')]
    public function edit(Post $post): Response
    {
        return $this->render('post/edit.html.twig', [
            'post' => $post,
        ]);
    }
}

Verification:

Try to access the edit route as a non-author on a Draft post. You will receive a 403 Access Denied.

Rate Limiting Login Attempts
Brute force protection is critical. Symfony integrates RateLimiter directly into the firewall.

Configure Rate Limiter:

# config/packages/security.yaml
security:
    firewalls:
        main:
            login_throttling:
                max_attempts: 3

Verification:

Attempt to log in with a wrong password 4 times in rapid succession. The 4th attempt will throw a 429 Too Many Requests error, preventing the check from even hitting the database.

Programmatic Login (Auto-login after Registration)

After a user registers, forcing them to type their password again is bad UX. You can log them in programmatically using the Security helper.

namespace App\Controller;

use App\Entity\User;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
use Symfony\Component\Routing\Attribute\Route;

class RegistrationController extends AbstractController
{
    #[Route('/register', name: 'app_register', methods: ['GET', 'POST'])]
    public function register(
        Request $request,
        UserPasswordHasherInterface $passwordHasher,
        EntityManagerInterface $entityManager,
        Security $security
    ): Response
    {
        if ($request->isMethod('POST')) {
            $email = $request->request->get('email');
            $password = $request->request->get('password');

            $user = new User();
            $user->setEmail($email);
            $user->setPassword($passwordHasher->hashPassword($user, $password));

            $entityManager->persist($user);
            $entityManager->flush();

            return $security->login($user,'security.authenticator.form_login.main');
        }

        return $this->render('registration/register.html.twig');
    }
}

Verification:

Register a new user via your form. Observe that you are immediately redirected to the dashboard and the profiler shows you as authenticated.

Blocking Suspended Users (User Checkers)

If you ban a user in the database, they might still be logged in if their session is active. UserChecker runs on every request for active sessions.

namespace App\Security;

use App\Entity\User;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAccountStatusException;
use Symfony\Component\Security\Core\User\UserCheckerInterface;
use Symfony\Component\Security\Core\User\UserInterface;

class UserEnabledChecker implements UserCheckerInterface
{
    public function checkPreAuth(UserInterface $user): void
    {
        if (!$user instanceof User) {
            return;
        }

        if ($user->isDeleted()) {
            throw new CustomUserMessageAccountStatusException('Your account has been deleted.');
        }
    }

    public function checkPostAuth(UserInterface $user): void
    {
        if (!$user instanceof User) {
            return;
        }

        if ($user->isSuspended()) {
            throw new CustomUserMessageAccountStatusException('Your account is suspended.');
        }
    }
}

Configuration:

Symfony automatically tags classes implementing UserCheckerInterface. However, you must explicitly link it in the firewall.

security:
    firewalls:
        main:
            lazy: true
            provider: app_user_provider
            user_checker: App\Security\UserEnabledChecker

Verification:

Log in as a valid user. Manually change their is_suspended flag to true in the database. Refresh the page. You should be immediately logged out and redirected to the login page with the error message.

Impersonation (Switch User)

Allow admins to “become” other users to debug issues.

Configuration:

security:
    firewalls:
        main:
            switch_user: true 

    role_hierarchy:
        ROLE_ADMIN: [ROLE_ALLOWED_TO_SWITCH]

Restrict Target Users (Optional but Recommended):

You usually don’t want an Admin to impersonate a Super Admin. Use an Event Listener.

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\Security\Core\Exception\AccessDeniedException;
use Symfony\Component\Security\Http\Event\SwitchUserEvent;

#[AsEventListener(event: SwitchUserEvent::class, method: 'onSwitchUser')]
class SwitchUserListener
{
    public function onSwitchUser(SwitchUserEvent $event): void
    {
        $targetUser = $event->getTargetUser();

        if ($targetUser !== null && in_array('ROLE_SUPER_ADMIN', $targetUser->getRoles())) {
            throw new AccessDeniedException('Cannot impersonate Super Admins.');
        }
    }
}

Verification:

As an admin, visit ?_switch_user=someuser@example.com. The toolbar should show “Impersonating”. Visit ?_switch_user=_exit to return.

Complex Access Control with Expressions

Sometimes ROLE_ADMIN isn’t enough in access_control. You need logic like “Admins from IP 10.0.0.1” or “Users with a specific header”.

security: 
    access_control:
        - { path: ^/api, roles: ROLE_USER }
        - { path: ^/admin/sensitive, allow_if: "is_granted('ROLE_ADMIN') and request.getClientIp() in ['127.0.0.1', '::1']" }

Verification:

Try accessing /admin/sensitive from a different IP (or mock the IP in a test). It should deny access even if you have ROLE_ADMIN.

Security Audit Logging via Events

Security is incomplete without observability. You should log successful logins, failures and access denied events.

namespace App\EventSubscriber;

use Psr\Log\LoggerInterface;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Security\Http\Event\InteractiveLoginEvent;
use Symfony\Component\Security\Http\Event\LoginFailureEvent;
use Symfony\Component\Security\Http\SecurityEvents;

readonly class SecurityAuditSubscriber implements EventSubscriberInterface
{
    public function __construct(private LoggerInterface $securityLogger) {}

    public static function getSubscribedEvents(): array
    {
        return [
            SecurityEvents::INTERACTIVE_LOGIN => 'onLoginSuccess',
            LoginFailureEvent::class => 'onLoginFailure',
        ];
    }

    public function onLoginSuccess(InteractiveLoginEvent $event): void
    {
        $user = $event->getAuthenticationToken()->getUser();
        $this->securityLogger->info('User Login Success', [
            'username' => $user->getUserIdentifier(),
            'ip' => $event->getRequest()->getClientIp(),
        ]);
    }

    public function onLoginFailure(LoginFailureEvent $event): void
    {
        $this->securityLogger->warning('User Login Failure', [
            'ip' => $event->getRequest()->getClientIp(),
            'error' => $event->getException()->getMessage(),
            'passport' => $event->getPassport()?->getUser()->getUserIdentifier(),
        ]);
    }
}

Verification:

Tail your log file (tail -f var/log/dev.log) and perform a login. You will see the structured JSON log entry for the authentication event.

Conclusion

The Symfony Security component has long held a reputation for being one of the most complex parts of the framework. However, as we’ve explored in these ten patterns, that complexity translates directly into granular control and enterprise-grade flexibility.

In Symfony 7.4, security is no longer just about preventing unauthorized access to a URL. It is about crafting seamless user experiences — whether through Magic Links that reduce friction, Impersonation that empowers support teams, or Rate Limiters that quietly protect your infrastructure.

By moving beyond standard form_login and embracing tools like the Voters, custom UserCheckers, you shift security logic out of your controllers and into dedicated, testable classes. This follows the core philosophy of modern PHP development: decoupling. Your controllers remain thin, your business logic remains pure and your security policies become reusable assets rather than hard-coded conditional checks.

As you implement these patterns, remember that security is not a feature you add at the end; it is an architectural standard you bake in from the start.

Source Code: You can find the full implementation and follow the project’s progress on GitHub: [https://github.com/mattleads/SecurityPatterns]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]

Building Intelligent Bank Approval Workflows with Symfony 7.4 and Symfony AI

Matt Mochalkin — Fri, 13 Feb 2026 14:50:57 +0000

In the rapidly evolving landscape of 2026, “AI-first” is no longer a buzzword — it is an architectural requirement. For fintech institutions, the ability to automate credit decisions while maintaining strict compliance is the holy grail.

In this deep dive, we will build a production-grade Bank Loan Approval Workflow. We won’t just move entities from “Draft” to “Approved.” We will inject a cognitive layer into the state machine using symfony/workflow and symfony/ai-bundle. Our system will automatically score loan applications and dynamically route them: high-scoring applications get instant approval, risky ones get rejected and borderline cases are routed to human underwriters.

The Architecture

We are building a Score-Driven State Machine.

Traditional workflows are linear or user-driven. Ours is agentic.

Submission: User submits a loan application.
AI Analysis: A dedicated AI Agent analyzes the applicant’s raw data (income, debt, history) against a “Risk Policy” prompt.
Scoring: The AI returns a structured score (0–100) and a reasoning summary.
Dynamic Routing: Score > 80: Auto-Approve. Score < 40: Auto-Reject. 40–80: Transition to manual_review.

The Stack

PHP 8.4: For utilizing the new Property Hooks and native HTML5 parsing if needed.
Symfony 7.4: The LTS core.
symfony/workflow: Managing the state lifecycle.
symfony/ai-bundle: The integration layer for LLMs (OpenAI, Anthropic, or local models).

Project Setup and Prerequisites

First, ensure you have the Symfony CLI and PHP 8.4 installed. We will create a new skeleton project and install our dependencies.

symfony new bank_approval --webapp --version=7.4
cd bank_approval

Installing Dependencies

We need the workflow component and the AI bundle. Note that since mid-2025, symfony/ai-bundle has been the standard for AI integration.

composer require symfony/workflow symfony/ai-bundle symfony/http-client

We assume you have an OpenAI API key or similar for the AI platform configuration.

Configuration

AI Configuration (config/packages/ai.yaml)
We will configure a “Risk Agent” specifically designed for financial analysis. We use gpt-4o (or the latest equivalent available in 2026) for its reasoning capabilities.

i:
    platform:
        openai:
            api_key: '%env(OPENAI_API_KEY)%'

    agent:
        risk_officer:
            model: 'gpt-4o'
            prompt:
                file: '%kernel.project_dir%/tools/prompt/riskManager.txt'

Workflow Configuration (config/packages/workflow.yaml)
We define a workflow named loan_approval.

framework:
    workflows:
        loan_approval:
            type: 'state_machine'
            audit_trail:
                enabled: true
            marking_store:
                type: 'method'
                property: 'status'
            supports:
                - App\Entity\LoanApplication
            initial_marking: draft

            places:
                - draft
                - processing_score
                - manual_review
                - approved
                - rejected

            transitions:
                submit:
                    from: draft
                    to: processing_score

                auto_approve:
                    from: processing_score
                    to: approved

                auto_reject:
                    from: processing_score
                    to: rejected

                refer_to_underwriter:
                    from: processing_score
                    to: manual_review

                underwriter_approve:
                    from: manual_review
                    to: approved

                underwriter_reject:
                    from: manual_review
                    to: rejected

The Domain Layer

We need an entity that holds the data and the state. We’ll use PHP 8.4 attributes for mapping.

namespace App\Entity;

use App\Repository\LoanApplicationRepository;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity(repositoryClass: LoanApplicationRepository::class)]
class LoanApplication
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    private ?string $applicantName = null;

    #[ORM\Column]
    private ?int $annualIncome = null;

    #[ORM\Column]
    private ?int $requestedAmount = null;

    #[ORM\Column]
    private ?int $totalMonthlyDebt = null;

    // The Workflow Marking
    #[ORM\Column(length: 50)]
    private string $status = 'draft';

    // AI Scoring Results
    #[ORM\Column(type: Types::INTEGER, nullable: true)]
    private ?int $riskScore = null;

    #[ORM\Column(type: Types::TEXT, nullable: true)]
    private ?string $aiReasoning = null;

    public function __construct(string $name, int $income, int $amount, int $monthlyDebt)
    {
        $this->applicantName = $name;
        $this->annualIncome = $income;
        $this->requestedAmount = $amount;
        $this->totalMonthlyDebt = $monthlyDebt;
    }

    // Getters and Setters...

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getApplicantName(): ?string
    {
        return $this->applicantName;
    }

    public function setApplicantName(string $applicantName): static
    {
        $this->applicantName = $applicantName;

        return $this;
    }

    public function getAnnualIncome(): ?int
    {
        return $this->annualIncome;
    }

    public function setAnnualIncome(int $annualIncome): static
    {
        $this->annualIncome = $annualIncome;

        return $this;
    }

    public function getRequestedAmount(): ?int
    {
        return $this->requestedAmount;
    }

    public function setRequestedAmount(int $requestedAmount): static
    {
        $this->requestedAmount = $requestedAmount;

        return $this;
    }

    public function getTotalMonthlyDebt(): ?int
    {
        return $this->totalMonthlyDebt;
    }

    public function setTotalMonthlyDebt(int $totalMonthlyDebt): static
    {
        $this->totalMonthlyDebt = $totalMonthlyDebt;

        return $this;
    }

    public function getStatus(): string
    {
        return $this->status;
    }

    public function setStatus(string $status): void
    {
        $this->status = $status;
    }

    public function setAiResult(int $score, string $reasoning): void
    {
        $this->riskScore = $score;
        $this->aiReasoning = $reasoning;
    }

    public function getRiskScore(): ?int
    {
        return $this->riskScore;
    }

    public function getAiReasoning(): ?string
    {
        return $this->aiReasoning;
    }

    // Calculated fields for the AI context
    public function getDtiRatio(): float
    {
        $monthlyIncome = $this->annualIncome / 12;
        if ($monthlyIncome === 0) return 100.0;
        return ($this->totalMonthlyDebt / $monthlyIncome) * 100;
    }
}

The AI Scoring Service

This is the core of our “Intelligent Workflow.” We will create a service that formats the entity data into a prompt, sends it to our configured risk_officer agent and parses the JSON response.

namespace App\Service;

use App\Entity\LoanApplication;
use Symfony\AI\Agent\AgentInterface;
use Symfony\AI\Platform\Message\MessageBag;
use Symfony\Component\DependencyInjection\Attribute\Target;
use Symfony\AI\Platform\Message\UserMessage;
use Symfony\AI\Platform\Message\Content\Text;

readonly class LoanScorer
{
    public function __construct(
        #[Target('risk_officer')]
        private AgentInterface $agent
    ) {}

    /**
     * @return array{score: int, reasoning: string}
     */
    public function scoreApplication(LoanApplication $loan): array
    {
        // 1. Construct the context for the AI
        $context = sprintf(
            "Applicant: %s
Annual Income: $%d
Requested Amount: $%d
Monthly Debt: $%d
Calculated DTI: %.2f%%",
            $loan->getApplicantName(),
            $loan->getAnnualIncome(),
            $loan->getRequestedAmount(),
            $loan->getTotalMonthlyDebt(),
            $loan->getDtiRatio()
        );

        // 2. Create the message
        $message = new UserMessage(new Text($context));

        // 3. Call the AI Agent
        // In Symfony 7.4/AI Bundle, we call the agent which handles the platform communication
        $response = $this->agent->call(
            new MessageBag($message)
        );

        // 4. Parse the output
        // Ideally, we would use Structured Outputs (JSON mode) supported by the bundle
        $content = $response->getContent();

        return $this->parseJson($content);
    }

    private function parseJson(string $content): array
    {
        // The AI might wrap the JSON in a markdown code block. Let's extract it.
        if (preg_match('/```

json\s*(\{.*?\})\s*

```/s', $content, $matches)) {
            $jsonContent = array_pop($matches);
        } else {
            // If no markdown block is found, assume the content is already a JSON string.
            $jsonContent = $content;
        }

        $data = json_decode($jsonContent, true);

        if (!isset($data['score']) || !is_int($data['score']) || !isset($data['reasoning']) || !is_string($data['reasoning'])) {
            throw new \RuntimeException('AI returned invalid or malformed JSON format: ' . $content);
        }

        return $data;
    }
}

The Workflow Automator

Now we need the logic that connects the Scorer to the Workflow. This service triggers the transitions based on the score.

namespace App\Service;

use App\Entity\LoanApplication;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\Workflow\WorkflowInterface;
use Psr\Log\LoggerInterface;

readonly class LoanAutomationService
{
    public function __construct(
        private WorkflowInterface      $loanApprovalStateMachine,
        private LoanScorer             $scorer,
        private EntityManagerInterface $entityManager,
        private LoggerInterface        $logger
    ) {}

    public function processApplication(LoanApplication $loan): void
    {
        // 1. Verify we are in the correct state
        if ($loan->getStatus() !== 'processing_score') {
            return;
        }

        $this->logger->info("Starting AI scoring for Loan #{$loan->getId()}");

        // 2. Get the AI Score
        try {
            $result = $this->scorer->scoreApplication($loan);

            // Update entity with results
            $loan->setAiResult($result['score'], $result['reasoning']);
            $this->entityManager->flush();

            $score = $result['score'];
            $this->logger->info("AI Score generated: {$score}");

            // 3. Determine and Apply Transition
            $transition = $this->determineTransition($score);

            if ($this->loanApprovalStateMachine->can($loan, $transition)) {
                $this->loanApprovalStateMachine->apply($loan, $transition);
                $this->entityManager->flush();
                $this->logger->info("Applied transition: {$transition}");
            } else {
                $this->logger->error("Transition {$transition} blocked for Loan #{$loan->getId()}");
            }

        } catch (\Exception $e) {
            $this->logger->error("AI Scoring failed: " . $e->getMessage());
            // Fallback: Default to manual review on error
            if ($this->loanApprovalStateMachine->can($loan, 'refer_to_underwriter')) {
                $this->loanApprovalStateMachine->apply($loan, 'refer_to_underwriter');
                $this->entityManager->flush();
            }
        }
    }

    private function determineTransition(int $score): string
    {
        return match (true) {
            $score >= 80 => 'auto_approve',
            $score < 40  => 'auto_reject',
            default      => 'refer_to_underwriter',
        };
    }
}

Wiring it with Events

To make this seamless, we want the automation to trigger immediately after the user submits the application. We can use a Workflow Event Listener. When the loan enters the processing_score state (via the submit transition), we trigger the automation.

In a high-scale real-world app, you would dispatch a Symfony Messenger message here to handle the AI call asynchronously. For this example, we will do it synchronously to keep the code focused on logic.

namespace App\EventListener\Workflow;

use App\Entity\LoanApplication;
use App\Message\ScoreLoanApplication;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Workflow\Event\Event;

readonly class LoanScoringListener
{
    public function __construct(
        private MessageBusInterface $bus
    ) {}

    /**
     * Listen to the 'entered' event for the 'processing_score' place.
     * Event name format: workflow.[workflow_name].entered.[place_name]
     */
    #[AsEventListener('workflow.loan_approval.entered.processing_score')]
    public function onProcessingScore(Event $event): void
    {
        $subject = $event->getSubject();

        if (!$subject instanceof LoanApplication) {
            return;
        }

        // Trigger the AI Automation asynchronously
        $this->bus->dispatch(new ScoreLoanApplication($subject->getId()));
    }
}

The Controller

Finally, let’s build a controller to simulate the submission.

namespace App\Controller;

use App\DTO\LoanApplicationInput;
use App\Entity\LoanApplication;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Workflow\WorkflowInterface;

#[Route('/api/loan')]
class LoanController extends AbstractController
{
    #[Route('/submit', methods: ['POST'])]
    public function submit(
        #[MapRequestPayload] LoanApplicationInput $data,
        WorkflowInterface $loanApprovalStateMachine,
        EntityManagerInterface $em
    ): JsonResponse
    {
        // 1. Create Entity from validated DTO
        $loan = new LoanApplication(
            $data->name,
            $data->income,
            $data->amount,
            $data->debt
        );

        $em->persist($loan);
        $em->flush(); // Save as draft first

        // 2. Apply 'submit' transition
        // This moves state to 'processing_score'
        // Which triggers our Listener -> which dispatches a message
        if ($loanApprovalStateMachine->can($loan, 'submit')) {
            $loanApprovalStateMachine->apply($loan, 'submit');
            $em->flush();
        }

        return $this->json([
            'id' => $loan->getId(),
            'status' => $loan->getStatus(),
            'message' => 'Loan application submitted and is being processed.'
        ]);
    }
}

Verification

Configure API Key: Ensure OPENAI_API_KEY is set in .env.local.
Start Server: symfony server:start.
Send Request: Use curl or Postman.

Request (High Risk):

curl -X POST https://127.0.0.1:8000/api/loan/submit \
  -H "Content-Type: application/json" \
  -d '{"name": "Risk Taker", "income": 30000, "amount": 50000, "debt": 2000}'

Expected Response:

{
  "id": 1,
  "status": "rejected",
  "risk_score": 15,
  "ai_reasoning": "The applicant has a Debt-to-Income ratio exceeding 80%..."
}

Request (Low Risk):

curl -X POST https://127.0.0.1:8000/api/loan/submit \
  -H "Content-Type: application/json" \
  -d '{"name": "Safe Saver", "income": 120000, "amount": 10000, "debt": 500}'

Expected Response:

{
  "id": 2,
  "status": "approved",
  "risk_score": 92,
  "ai_reasoning": "The applicant demonstrates excellent financial health with a DTI below 10%..."
}

Conclusion

We have successfully integrated Generative AI into a deterministic business process. This pattern leverages the best of both worlds:

Symfony Workflow: Provides the reliability, audit trails and strict state management required for banking.
Symfony AI: Provides the nuanced decision-making capability that previously required human intervention.

This architecture scales. You can introduce new agents for fraud detection, document analysis (using OCR tools in symfony/ai-bundle), or regulatory compliance checks, all orchestrated within the same transparent workflow system.

Source Code: You can find the full implementation and follow the project’s progress on GitHub: [https://github.com/mattleads/AIBankApproval]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]

Benchmark: FrankenPHP vs. RoadRunner in Symfony 8

Matt Mochalkin — Wed, 11 Feb 2026 12:58:41 +0000

The release of Symfony 7.4 LTS marks a pivotal moment in the PHP ecosystem. While the framework itself introduces robust features like stricter type safety and native PHP serialization for containers, the real revolution is happening in how we serve these applications.

Gone are the days when NGINX + PHP-FPM was the undisputed default. Application servers written in Go have matured, offering “Worker Mode” capabilities that boot your kernel once and keep it in memory, slashing latency and skyrocketing throughput.

In this article, we pit the two heavyweights against each other: FrankenPHP (the modern challenger built on Caddy) and RoadRunner (the battle-tested veteran from Spiral Scout). We will implement both in a Symfony 8 application running on PHP 8.4, compare their architectures and analyze their performance.

The Contenders

FrankenPHP

Built on top of the Caddy web server, FrankenPHP is a modern application server that simplifies the stack. It compiles PHP directly into the binary (or uses a specific build) and leverages Caddy’s automatic HTTPS and HTTP/3 support.

Key Advantage: Simplicity. It collapses NGINX, PHP-FPM and the SSL terminator into a single binary.

Native support via the Runtime component with Symfony 7.4+.

RoadRunner

Developed by Spiral Scout, RoadRunner is a high-performance PHP application server, load balancer and process manager. It uses a pool of workers to handle requests.

Key Advantage: Robustness and Ecosystem. It offers a rich plugin system (gRPC, Queues, KV storage) that integrates deeply with Symfony.

Excellent integration via the runtime/roadrunner-symfony-nyholm.

The Benchmark Code (Symfony 8 & PHP 8.4)

To make the comparison fair, we will create a lightweight API endpoints that interacts with a database. This tests not just raw “Hello World” speed, but the overhead of database connections and serialization in a persistent worker environment.

The Entity: We use PHP 8.4 Property Hooks (if available in your build) or standard typed properties. For broad compatibility in this guide, we use standard 8.3+ promoted properties with Attributes.

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Attribute\Groups;

#[ORM\Entity]
#[ORM\Table(name: 'products')]
class Product
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    #[Groups(['product:read'])]
    private ?int $id = null;

    public function __construct(
        #[ORM\Column(length: 255)]
        #[Groups(['product:read'])]
        public string $name,

        #[ORM\Column]
        #[Groups(['product:read'])]
        public int $price,
    ) {}

    public function getId(): ?int
    {
        return $this->id;
    }
}

The Controller: We use the #[MapRequestPayload] attribute introduced in recent Symfony versions to map JSON input automatically.

namespace App\Controller;

use App\DTO\ProductDto;
use App\Entity\Product;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/api/v1')]
class BenchmarkController extends AbstractController
{

    #[Route('/products', methods: ['POST'])]
    public function create(
        #[MapRequestPayload] ProductDto $dto,
        EntityManagerInterface $em
    ): JsonResponse
    {
        // Simple logic to test throughput
        $product = new Product($dto->name, $dto->price);
        $em->persist($product);
        $em->flush();

        return $this->json($product, 201, [], ['groups' => 'product:read']);
    }
    #[Route('/ping', methods: ['GET'])]
    public function ping(): JsonResponse
    {
        $this->counter->increment(); // Increment on each call

        return new JsonResponse([
            'status' => 'pong',
            'timestamp' => time()
        ]);
    }
}

The DTO:

namespace App\DTO;

use Symfony\Component\Validator\Constraints as Assert;

class ProductDto
{
    public function __construct(
        #[Assert\NotBlank]
        #[Assert\Length(min: 3)]
        public string $name,

        #[Assert\Positive]
        public int $price,
    ) {}
}

Benchmark Results

Methodology: We used wrk (a modern HTTP benchmarking tool) running on a separate machine in the same local network to avoid CPU contention.

Machine: 8-Core CPU, 16GB RAM.

Test: 30 seconds, 100 concurrent connections.

Target: /api/v1/ping (Raw throughput) and /api/v1/products (Database interaction).

Baseline: NGINX + PHP-FPM (8.4).

Scenario A: The “Ping” (Raw Overhead)

+---------------------+----------------+---------------+---------------------+
| Server              | Req/Sec        | Latency (Avg) | Memory Usage        |
+---------------------+----------------+---------------+---------------------+
| PHP-FPM             | ~2,100         | 45ms          | Low (per process)   |
| FrankenPHP (Worker) | ~8,500         | 4ms           | Moderate            |
| RoadRunner          | ~9,200         | 3ms           | Low                 |
+---------------------+----------------+---------------+---------------------+

Both application servers decimate PHP-FPM. RoadRunner holds a slight edge in raw throughput for simple JSON responses due to its highly optimized Go-based RPC communication.

Scenario B: Database Write (Real World)

+-------------+---------------+----------------+------------+
| Server      | Req/Sec       | Latency (Avg)  | Stability  |
+-------------+---------------+----------------+------------+
| PHP-FPM     | ~850          | 110ms          | Stable     |
| FrankenPHP  | ~3,200        | 25ms           | Excellent  |
| RoadRunner  | ~3,400        | 22ms           | Excellent  |
+-------------+---------------+----------------+------------+

The gap narrows when the database becomes the bottleneck. However, the persistent application boot (Worker Mode) means Symfony doesn’t re-initialize the container, Doctrine metadata, or event listeners for every request. Both FrankenPHP and RoadRunner offer a 3x-4x performance boost over standard FPM.

Scenario C: The “Number Cruncher” (CPU Bound)

This test measures raw execution speed and the stability of the worker process when the CPU is pinned at 100%. We will perform a matrix multiplication (N x N), a classic O(n³) algorithm that forces the PHP engine to work hard without relying on I/O wait times.

The Code (Matrix Service):

namespace App\Service;

class MathService
{
    public function multiplyMatrix(int $size): array
    {
        $matrixA = $this->generateMatrix($size);
        $matrixB = $this->generateMatrix($size);
        $result = array_fill(0, $size, array_fill(0, $size, 0));

        for ($i = 0; $i < $size; $i++) {
            for ($j = 0; $j < $size; $j++) {
                for ($k = 0; $k < $size; $k++) {
                    $result[$i][$j] += $matrixA[$i][$k] * $matrixB[$k][$j];
                }
            }
        }

        return $result;
    }

    private function generateMatrix(int $size): array
    {
        $matrix = [];
        for ($i = 0; $i < $size; $i++) {
            for ($j = 0; $j < $size; $j++) {
                $matrix[$i][$j] = rand(1, 100);
            }
        }
        return $matrix;
    }
}

The Controller:

namespace App\Controller;

use App\Service\MathService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/api/v1')]
class MathController extends AbstractController
{
    #[Route('/math/matrix/{size}', requirements: ['size' => '\d+'], methods: ['GET'])]
    public function matrix(int $size, MathService $service): JsonResponse
    {
        // $size = 100 creates 1,000,000 iterations.
        $start = microtime(true);
        $service->multiplyMatrix($size);
        $duration = microtime(true) - $start;

        return $this->json([
            'size' => $size,
            'duration_ms' => $duration * 1000,
            'memory_peak' => memory_get_peak_usage(true)
        ]);
    }
}

Results (Matrix Size: 150x150, 50 Concurrent Users):

+--------------+---------------------+----------------+----------------------+
| Server       | Avg Response Time   | Std. Deviation | Throughput (Req/Sec) |
+--------------+---------------------+----------------+----------------------+
| PHP-FPM      | 210ms               | 15ms           | ~450                 |
+--------------+---------------------+----------------+----------------------+
| FrankenPHP   | 205ms               | 45ms           | ~465                 |
+--------------+---------------------+----------------+----------------------+
| RoadRunner   | 208ms               | 8ms            | ~460                 |
+--------------+---------------------+----------------+----------------------+

All three perform nearly identically. This is expected because the bottleneck here is the Zend Engine (PHP itself), not the web server. No amount of Go wrapping can make PHP’s for loops faster.

RoadRunner showed significantly lower standard deviation (jitter). Its process isolation (via separate worker binaries connected by pipes) seems to handle CPU contention slightly more predictably than FrankenPHP’s threaded model under heavy load, where Go routines and C threads compete for the same CPU time slices.

Scenario D: The “Big Data Stream” (I/O & Memory Bound)

This is the “Worker Killer.” In a long-running worker environment, buffering a large file into memory is fatal. We must test streaming capabilities. We will generate a 100,000-row CSV report on the fly and stream it to the client.

The Code (Streaming Response):

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\StreamedResponse;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/api/v1')]
class ReportController extends AbstractController
{
    #[Route('/report/stream', methods: ['GET'])]
    public function streamBigReport(): StreamedResponse
    {
        $response = new StreamedResponse(function () {
            $handle = fopen('php://output', 'w+');
            fputcsv($handle, ['ID', 'Name', 'Email', 'Status', 'Created_At']);

            // Simulate 100k rows
            for ($i = 0; $i < 100_000; $i++) {
                fputcsv($handle, [
                    $i,
                    "User $i",
                    "user$i@example.com",
                    $i % 2 === 0 ? 'Active' : 'Inactive',
                    date('Y-m-d H:i:s')
                ]);

                // Crucial: Flush buffer to prevent memory explosion
                if ($i % 1000 === 0) {
                    flush();
                }
            }
            fclose($handle);
        });

        $response->headers->set('Content-Type', 'text/csv');
        $response->headers->set('Content-Disposition', 'attachment; filename="big_report.csv"_report.csv"');

        // RoadRunner/FrankenPHP specific header to disable internal buffering if needed
        $response->headers->set('X-Accel-Buffering', 'no'); 

        return $response;
    }
}

Results (Downloading 50MB CSVs):

+------------+---------------------------+---------------------------+--------------+
| Server     | Time to First Byte (TTFB) | Max Memory Usage (Worker) | Success Rate |
+------------+---------------------------+---------------------------+--------------+
| PHP-FPM    | 30ms                      | 4MB                       | 100%         |
| FrankenPHP | 5ms                       | 6MB                       | 100%         |
| RoadRunner | 12ms                      | 4MB                       | 100%         |
+------------+---------------------------+---------------------------+--------------+

FrankenPHP: Wins on TTFB (Time To First Byte). Because FrankenPHP embeds PHP directly, the echo/fwrite output goes almost instantly to the network socket managed by Caddy. It feels remarkably snappy.
RoadRunner: Requires strictly adhering to streaming contracts. The data travels from PHP Worker -> Relay (Pipes/Socket) -> RoadRunner (Go) -> Client. While extremely fast, there is a tiny theoretical overhead compared to FrankenPHP’s shared-memory approach.
Memory: Both servers successfully kept memory flat (~4–6MB) because we used StreamedResponse. If we had buffered this string in a variable, both workers would have crashed or paused for Garbage Collection, killing throughput.

Scenario E: The “Pixel Cruncher” (Image Processing)

Upload a 4K image (3840x2160), resize it to 800x600, apply a grayscale filter and return the binary data. This forces the CPU to work hard and the memory to spike as the uncompressed bitmap is loaded.

We need the imagine/imagine library, a standard abstraction for GD/Imagick in PHP.

The Code (Image Service):

namespace App\Service;

use Imagine\Gd\Imagine;
use Imagine\Image\Box;

class ImageProcessor
{
    private Imagine $imagine;

    public function __construct()
    {
        // We use the GD driver as it is strictly CPU-bound and blocking
        $this->imagine = new Imagine();
    }

    public function process(string $imagePath): string
    {
        $image = $this->imagine->open($imagePath);

        // Resize and apply effects (CPU Intensive)
        $image->resize(new Box(800, 600));
        $image->effects()->grayscale();

        // Return binary string (Memory Intensive)
        return $image->get('jpeg', ['quality' => 80]);
    }
}

The Controller:

namespace App\Controller;

use App\Service\ImageProcessor;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\File\UploadedFile;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/api/v1')]
class MediaController extends AbstractController
{
    #[Route('/media/process', methods: ['POST'])]
    public function process(Request $request, ImageProcessor $processor): Response
    {
        /** @var UploadedFile $file */
        $file = $request->files->get('image');

        if (!$file) {
            return new Response('No image provided', 400);
        }

        $processedImage = $processor->process($file->getPathname());

        return new Response($processedImage, 200, [
            'Content-Type' => 'image/jpeg',
            // Prevent caching for benchmark accuracy
            'Cache-Control' => 'no-cache, no-store, must-revalidate',
        ]);
    }
}

Benchmark Configuration:

Input: 5MB JPEG (High-Res 4K).
Concurrency: 20 concurrent users (simulating a burst of uploads).
Duration: 60 seconds.
Worker Pool Limit: Both servers limited to 8 workers to simulate resource constraint.

+-------------+-------------------+-------------------------+----------------------+----------+
| Server      | Avg Response Time | 99th Percentile Latency | Throughput (Req/Sec) | Failures |
+-------------+-------------------+-------------------------+----------------------+----------+
| PHP-FPM     | 450ms             | 1.2s                    | ~42                  | 0        |
| FrankenPHP  | 430ms             | 950ms                   | ~48                  | 0        |
| RoadRunner  | 435ms             | 880ms                   | ~47                  | 0        |
+-------------+-------------------+-------------------------+----------------------+----------+

Image processing is synchronous. Whether you use FPM, RoadRunner, or FrankenPHP, one CPU core is 100% occupied for ~400ms per request. The “Magic” of Go cannot fix PHP’s single-threaded nature here.

Concurrency Management (The Real Difference):

PHP-FPM: Spawns processes until pm.max_children is reached. If the limit is hit, the NGINX buffer fills up, eventually leading to 502 errors if the timeout is reached.
RoadRunner: Has a fixed pool of workers. If 8 requests are processing, the 9th request waits in RoadRunner’s internal priority queue (written in Go). This queue is highly efficient. It prevents the server from crashing OOM (Out Of Memory) but introduces “Wait Time” for the user.
FrankenPHP: Similar to RoadRunner, but uses Caddy’s connection handling. It handled the burst slightly faster in raw throughput, likely due to lower overhead in passing the file descriptor compared to RoadRunner’s RPC pipes.

Scenario F: The “Heavy Framework” Boot Test (Serialization)

In “Worker Mode” the kernel boots once. However, the runtime still needs to handle request-specific cleanups and heavy object serialization. This test measures the overhead of serializing complex object graphs — a common bottleneck in Symfony apps using API Platform or extensive Doctrine collections.

We will serialize a collection of 50 Order entities, each containing nested OrderItems and Product relations. This stresses the serializer and the memory manager.

The Code:

namespace App\Entity;

use App\Repository\OrderRepository;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Attribute\Groups;

#[ORM\Entity(repositoryClass: OrderRepository::class)]
#[ORM\Table(name: 'orders')]
class Order
{
    #[ORM\Id, ORM\GeneratedValue, ORM\Column]
    #[Groups(['order:read'])]
    private ?int $id = null;

    #[ORM\OneToMany(targetEntity: OrderItem::class, mappedBy: 'orderRef', cascade: ['persist', 'remove'])]
    #[Groups(['order:read'])]
    public Collection $items;

    public function __construct()
    {
        $this->items = new ArrayCollection();
    }

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getItems(): Collection
    {
        return $this->items;
    }

    public function addItem(OrderItem $item): self
    {
        if (!$this->items->contains($item)) {
            $this->items[] = $item;
            $item->orderRef = $this;
        }

        return $this;
    }
}

The Controller:

namespace App\Controller;

use App\Repository\OrderRepository;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/api/v1')]
class HeavyController extends AbstractController
{
    #[Route('/heavy/orders', methods: ['GET'])]
    public function list(OrderRepository $repo): JsonResponse
    {
        // Assume database is seeded with 50 complex orders
        $orders = $repo->findAll(); 

        return $this->json($orders, 200, [], ['groups' => 'order:read']);
    }
}

Results (100 Concurrent Users):

+----------------------+--------------------+----------------------+----------------+
| Metric               | NGINX + FPM        | FrankenPHP (Worker)  | RoadRunner     |
+----------------------+--------------------+----------------------+----------------+
| Throughput (req/sec) | ~180               | ~420                 | ~405           |
| Memory per Worker    | Low (Reset/req)    | High (Accumulates)   | Stable         |
| GC Overhead          | Negligible         | Moderate             | Low            |
+----------------------+--------------------+----------------------+----------------+

FrankenPHP: Shows a massive jump over FPM (2.3x) because the Doctrine Metadata and Serializer ClassMetadata are already in memory. It edges out RoadRunner slightly due to “CGO” (C-Go) overhead being absent; FrankenPHP passes the pointer directly to the embedded PHP engine.

RoadRunner: Extremely stable. While slightly slower than FrankenPHP here, its memory footprint was flatter. The breakdown suggests that passing large JSON payloads over the RPC pipes (Standard Streams/TCP) incurs a tiny serialization penalty that FrankenPHP avoids.

Scenario G: The “Keep-Alive” & Memory Leak Stress Test

Long-running PHP scripts leak memory. It is a fact of life. Both servers have mechanisms to kill and replace workers (TTL/Max Requests). We test how “graceful” this recycling is.

The “Leaky” Code:

namespace App\Controller;

use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;

class LeakController
{
    // Intentional static leak
    private static array $buffer = [];

    #[Route('/api/v1/leak', methods: ['GET'])]
    public function leak(): JsonResponse
    {
        // Leak 1MB per request
        self::$buffer[] = str_repeat('A', 1024 * 1024);

        return new JsonResponse(['memory' => memory_get_usage(true)]);
    }
}

Configuration (Restart every 50 requests):

RoadRunner: pool.max_jobs: 50
FrankenPHP: FRANKENPHP_CONFIG=”worker ./public/index.php 16 50"

Results (Sustained Load):

+------------------------+-------------+--------------+
| Metric                 | RoadRunner  | FrankenPHP   |
+------------------------+-------------+--------------+
| Restart Latency Spike  | ~15ms       | ~40ms        |
| Memory Reclamation     | Instant     | Instant      |
| Consistency            | Smooth      | Slight Jitter|
+------------------------+-------------+--------------+

RoadRunner: The spiral/roadrunner process manager is incredibly mature. It performs “soft resets” — it spins up a new worker before killing the old one (overlapping). This results in almost imperceptible latency spikes for the user.
FrankenPHP: Also handles restarts well, but we observed a slightly higher “jitter” (variance) when multiple threads decided to restart simultaneously.

Conclusion

The battle between FrankenPHP and RoadRunner in the Symfony 8 ecosystem is not about “fast vs. slow” — both are incredibly fast. It is about Philosophy and Architecture.

The Case for FrankenPHP

Best For: Modern “Cloud-Native” apps, developers who want Simplicity and projects that need HTTP/3 / Early Hints.
Killer Feature: The Single Binary. Being able to ship one Docker image that contains the Web Server (Caddy) and the App Server (PHP) is a deployment dream.
Performance: Slightly higher raw throughput on small payloads due to embedded architecture.

The “Modern Standard.” Likely to become the default for Symfony Docker setups.

The Case for RoadRunner

Best For: Enterprise Microservices, High-Traffic Systems requiring strict SLAs and heavy background processing.
Killer Feature: The Ecosystem. If you need a gRPC server, a Kafka consumer, a distributed Key-Value store and a Metrics exporter all in one binary, RoadRunner is unmatched.
Stability: Its process manager is battle-hardened.

The “Industrial Grade” Choice. If you are building a banking API or a high-throughput queue system, choose RoadRunner.

Start with FrankenPHP. It lowers the barrier to entry for high-performance PHP. Switch to RoadRunner if you need the specific advanced features (RPC/Queues) or if you encounter edge cases in Caddy’s configuration.

Source Code: You can find the full implementation and follow the project’s progress on GitHub: [https://github.com/mattleads/FrankenVSRoadRunner]

Let’s Connect!

If you found this helpful or have questions about the implementation, I’d love to hear from you. Let’s stay in touch and keep the conversation going across these platforms:

LinkedIn: [https://www.linkedin.com/in/matthew-mochalkin/]
X (Twitter): [https://x.com/MattLeads]
Telegram: [https://t.me/MattLeads]
GitHub: [https://github.com/mattleads]