Forem: Jozef Môstka

Symfony Messenger: A Great Servant, But a Terrible Master (Or How Asynchrony Cost Me Half My Beard)

Jozef Môstka — Thu, 23 Apr 2026 11:22:07 +0000

I am a long-time Symfony developer. I love the framework. I use it in countless projects—whether they are large corporate systems, smaller work tasks, or my own private pet projects. When the Symfony Messenger component was introduced years ago, I instantly fell in love with it and deployed it pretty much everywhere.

Everything worked like a Swiss watch. At least, that’s what I thought... until recently.

This article is a confession about how I spent three months solving two seemingly completely different, critical issues that ultimately shared one silent killer: untamed asynchrony. And also about how I tore my hair out and lost half my beard while debugging, all while my colleagues were cursing me.

Case One: The Mystery of the Evening Attachment Disappearances

We have a robust ticketing system. It works simply: a user creates a ticket and adds attachments. To avoid making the user wait for the upload, the attachments are processed asynchronously via Messenger, which moves them to Azure folders in the background.

Three months ago, the first report came in: "Sometimes, an attachment gets lost after creating a ticket."

When you looked at the data, you'd find an interesting anomaly. It mostly happened in the evening hours, around 9 PM. The cat-and-mouse game began. We spent a long time examining the code, going through the frontend JavaScript, but we found nothing. So we started adding logging. When that didn't help, we added more logs. And even more.

Finally, after weeks of frustration, we found the crime scene. In our Message Handler, we had this innocent-looking piece of code:


$forum = $this->emRds->getRepository(Forum::class)->find($message->getForumId());

if (!$forum) {
    $logger->log("Forum not found", context: [
        "id"      => $message->getForumTicketFileId(),
        "forumId" => $message->getForumId(),
    ]);
    return null; // Here is the silent killer
}

Why was it there? A protective mechanism. If someone deleted the forum/ticket in the meantime, we didn't want the handler trying to assign files to a non-existent record and throwing exceptions (crashing). Logical, right?

But what was actually happening at 9 PM?
At 9 PM, almost nobody is working in the system. The server is completely idle and has plenty of free resources. When someone created a ticket at that time, Messenger processed the Message instantly. And by instantly, I mean so brutally fast that the handler spun up and finished before the original web request even had time to complete and commit the database transaction with the new forum!

The handler was looking for the forum in the database, but it physically wasn't there yet (the transaction wasn't closed). So the code said to itself: "Ah, the forum doesn't exist, someone probably deleted it. OK, I'm discarding the attachment and exiting." By the time I figured this out, my colleagues—who had spent three months listening to client complaints about lost files—wanted to defenestrate me.

Case Two: The Phantom of the Inventory Documents

As if that weren't enough, I was running into another problem in parallel, in a completely different part of the system.

We process inventory documents. Our CRON connects to a good old Windows SFTP server, downloads an XML file, and sends it (guess via what)—yes, via Messenger—for asynchronous processing.

Once again, a bug was reported: "We are losing inventory documents!"
I look into our monitoring system... no errors, no failed messages. Everything was flashing green.

Round two of the cat-and-mouse game began. I looked for bugs in the code. I gradually added logs. Logging these kinds of asynchronous errors is pure hell. You always forget to put a log exactly where it's needed. So you add it two days later, deploy, and wait for the error to reproduce. In the meantime, you forget about the task because you have a million other things to do, and two weeks later you realize: "Oh, the code can also branch over here, I need to add a log here too."

What was the resolution?
We were connecting to a free version of a SolarWinds SFTP server. This version had one funny limitation: it allowed only one single active connection at any given time. There was no log about this on the server.

My PHP script tried to connect, but if another process was already holding the connection, the SFTP silently rejected it. And what did my code do in the Handler?
To be "defensive," before processing, I double-checked via SFTP just to be sure: "Does this XML file still exist on the server?" Since the connection failed due to the limit, the function returned that the file wasn't there.

And my logic? "Ah, the file isn't there. Probably some other system or an external person deleted it. That's a legitimate use-case. I'm discarding the message, return null."

BOOM. Another critical bug, another three months of stress, lost documents, and my beard half as thick. Basically, it was the exact same mental lapse as the first problem: I ignored a missing resource because I assumed a conscious user action.

The Common Denominator and the Solution

Both problems were of the exact same nature. In both cases, I created a graceful fallback for a situation I thought was a user-caused edge-case (deleting a record). I never dreamed that one problem was caused by excessive server speed and the other by the technical limits of a 1-connection SFTP.

How did I solve it? Very simply.

In both cases, I just turned off asynchrony and let them process synchronously.

For the first problem with the attachments, it could have been solved using a DelayStamp (so the message waits a bit for the DB transaction to complete), but we needed the attachment to be available in the system immediately after the page refresh. Synchronous processing solved that perfectly.

The second case with the SFTP couldn't be solved any other way. Since the server allowed only one connection, parallelization and asynchrony were a bad idea from the very beginning.

Final Takeaways

Symfony Messenger is a truly great servant. It can incredibly speed up application response times and tuck heavy logic away into the background. But it is a damn fast and powerful tool.

If you hand it code that silently "swallows" Not Found states without accounting for Race conditions or the limits of external infrastructure, get ready to spend long nights staring at empty logs.

And if you ever meet me and notice I'm missing a chunk of my beard... at least now you know why. Blame it on asynchrony.

Do you have similar horror stories with asynchronous processing? Share them in the comments so I know I'm not alone in this!

Symfony Asset Mapper: How to Finally Test JavaScript Properly Without the Pain

Jozef Môstka — Mon, 20 Apr 2026 14:26:32 +0000

You know the drill. Symfony Asset Mapper is a great tool. You've gotten rid of Webpack, npm install, and complex build processes. Everything is fast, clean, and modern. And then comes the fateful question: "And how do we actually test this?"

Then comes the reality check. Asset Mapper works on the principle of importmap.php, which your Node.js (and thus most test runners) has no clue about. You try to run a test and you get: ERR_MODULE_NOT_FOUND.

Many people just wave it off and say that testing Asset Mapper is simply impossible, or you have to switch back to a complex frontend stack. But what if I told you there's an elegant solution that bridges both worlds?

The "Aha!" moment: Symlinks as a bridge

My idea was simple: Node.js expects libraries in the node_modules folder. Symfony has them in assets/vendor/ or in vendor/ (for Stimulus bundles). So why not force Node.js to see what Symfony sees, without having to duplicate anything or "hack" the imports?

The solution is a small PHP script that reads your import map and creates a symlink structure in node_modules. Node.js will think everything is installed, while in reality, it will be reading the same files your browser uses.

Step 1: The PHP script that does the magic

Here is a simplified version of our "linker" script. It uses the Symfony Filesystem component for safe file manipulation.

// bin/setup-js-tests.php
require_once __DIR__ . '/../vendor/autoload.php';

use Symfony\Component\Filesystem\Filesystem;

$projectRoot = dirname(__DIR__);
$importmap = require $projectRoot . '/importmap.php';
$fs = new Filesystem();
$nodeModules = $projectRoot . '/node_modules';

if (!$fs->exists($nodeModules)) $fs->mkdir($nodeModules);

foreach ($importmap as $name => $config) {
    $targetDir = $nodeModules . '/' . $name;
    $sourcePath = isset($config['path']) 
        ? $projectRoot . '/' . ltrim($config['path'], './')
        : $projectRoot . '/assets/vendor/' . $name;

    if (!$fs->exists($sourcePath)) continue;

    if (!$fs->exists(dirname($targetDir))) $fs->mkdir(dirname($targetDir));

    if (is_dir($sourcePath)) {
        $fs->symlink($sourcePath, $targetDir);
    } else {
        // If it's a single file, we turn it into a package with index.js
        if (!$fs->exists($targetDir)) $fs->mkdir($targetDir);
        $fs->symlink($sourcePath, $targetDir . '/index.js');
        $fs->dumpFile($targetDir . '/package.json', json_encode([
            'name' => $name, 'type' => 'module', 'main' => 'index.js'
        ]));
    }
}
echo "Imports for JS tests have been successfully linked!\n";

Step 2: Node.js Configuration

Now we need to tell Node.js how to run the tests. We'll use a standard package.json, but with a small improvement: we'll use the pretest hook, which automatically runs our PHP script before every test.

{
  "name": "my-project",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --test tests/js/*.test.mjs",
    "test:watch": "node --watch --test tests/js/*.test.mjs",
    "pretest": "php bin/setup-js-tests.php"
  }
}

Methodology: Why this way?

For testing, we chose the native Node.js test runner (available since version 20). Why?

Zero configuration: No need to install Jest, Vitest, or anything similar.
Speed: It starts instantly.
Reality-based: No complex import mocking. You are testing the exact same files that run in production.

Thanks to symlinks, we can write clean imports in our tests:

import assert from 'node:assert/strict';
import test from 'node:test';
import { myFunction } from '../assets/js/my-function.js';
import { Midi } from '@tonejs/midi'; // This now works!

This approach allows us to follow TDD (Test Driven Development) on the frontend while maintaining the simplicity of Asset Mapper. If you add a new library via importmap:require, just run npm test and everything will be automatically re-linked.

Conclusion

Testing JavaScript in Symfony Asset Mapper is not impossible. All it takes is a small bridge in the form of a PHP script, and you can leverage the power of a modern Node.js environment without having to leave the comfort zone of your PHP framework.

Save time with AssetMapperTestBundle

If you don’t want to maintain the script yourself, I’ve packaged this logic into a small, lightweight Symfony bundle. It handles the symlinking, directory mapping, and single-file package generation automatically.

Check it out on GitHub: tito10047/asset-mapper-test-bundle

You can have your JS tests running in seconds with a single command:
npm test

Give it a try in your project and say goodbye to "missing module" errors. Your code (and your mental health) will thank you. 🍻

How I turned hundreds of thousands of "dumb" SVG icons into a semantic search engine in 7 languages under 20ms (using LLM and Meilisearch)

Jozef Môstka — Tue, 07 Apr 2026 06:54:11 +0000

Every frontend and full-stack developer knows this pain: You're building a UI, you need an icon for "settings", and you type settings into the library's search bar. The result? 0 results. Why? Because the library author named that icon heroicons-outline-cog.

Searching for icons without semantics is like looking for a life partner and the search engine offers you an e-shop with a lifetime warranty on refrigerators.

It frustrated me so much that I decided to build ycon.cc ? a tool that aggregates hundreds of open-source libraries and actually understands what you're looking for. In this article, I'll show you the technical background of how I enriched a massive icon dataset with semantics using AI and how I forced the whole thing to run under 20 milliseconds thanks to Meilisearch.

1. The Problem: Great data, zero context

When designing the architecture, I didn't want to reinvent the wheel and write my own scrapers for every icon library (Tabler, Heroicons, Material Design, etc.). Instead, I took advantage of the amazing open-source project iconify/json.

If you don't know it, it's a gigantic collection of validated, cleaned, and unified open-source icons in a single standardized JSON format. Suddenly, I had nearly 327,000 icons at my disposal without the effort of parsing SVG files.

The structure Iconify provided was clean and functional:

{
  "prefix": "tabler",
  "icons": {
    "car": {
      "body": "<g fill=\"none\" ... />",
      "width": 24,
      "height": 24
    }
  }
}

However, there was one huge catch. This data is built for rendering, not for searching. For a classic search engine, it's a nightmare. If a user searches for the word "vozidlo" or "auto" in Slovak (or Spanish), the system fails. Tagging such a large number of icons manually would take me about three lifetimes.

This is where AI enters the scene.

2. AI Magic: Semantic enrichment

I decided to use GPT-5-nano to breathe semantic life into each icon. The task was clear: look at the icon's name and generate the most accurate synonyms in English.

Here is the prompt that, after many iterations, worked best:

**System / Context:**
    You are an expert UX Copywriter and Linguist specializing in search engine optimization for UI icons. Your goal is to generate highly relevant search keywords (synonyms, related actions, and concepts) for a given list of UI icons.
**Instructions:**
    1. I will provide you with a JSON array of icons. Each icon has an `id`, a `clean_name`, and a `category`.
    2. For each icon, generate a maximum of 6 highly relevant English keywords (`en`) .
    3. Think about **what users would type into a search bar** to find this icon. Include both the physical object (e.g., "magnifying glass") and the associated action/concept (e.g., "search", "find", "zoom").
    4. Do NOT include the original `clean_name` in the tags (I already have it).
    5. Keep keywords short (1-2 words max per keyword). All lowercase.

To save time and money, I didn't send icons to the API one by one, but in batches of 25. This entire process for the full dataset cost me roughly $10 and ran in the background for about 6 hours.

The resulting JSON document, which I saved and prepared for indexing, suddenly looked like this:

{
  "id": "tabler:car",
  "name": "car",
  "keywords": ["vehicle", "auto", "transport", "drive", "machine"],
  "svg_code": "<svg ... />"
}

We had the data. Now it needed to be searchable quickly.

3. Speed: Meilisearch and why I stored SVG in it

As the search engine, I chose Meilisearch (written in Rust). It's built exactly for "typo-tolerance" and lightning-fast responses.

Originally, I pulled the SVG codes of the icons directly from the SQL database when rendering the grid. However, this turned out to be a bottleneck ? with 100 icons per page, it meant either 100 small SELECTs or one large join, which took hundreds of milliseconds with hundreds of thousands of records.

I therefore decided on a radical step: Store the SVG code (in the body attribute) directly in Meilisearch.

While this eliminated the SQL database from the search process, I ran into a new problem: Over-fetching. Meilisearch, by default, returns all attributes in the response. With a pagination of 100 icons, Meilisearch was sending me not only 100 SVG strings but also thousands of generated synonyms (6 words � 7 languages � 100 icons). PHP had to download this gigantic JSON over the network and deserialize it, which again drove latency up.

The solution? A surgical cut via attributesToRetrieve.

Synonyms (keywords) only serve for Meilisearch to find the icon. The frontend doesn't need to see them! In IconSearchService, I modified the search parameters as follows:

$searchParams = [
    'hitsPerPage'          => $query->limit,
    'page'                 => $page,
    'attributesToSearchOn' => ['name', 'clean_name', "keywords.$locale"],
    'attributesToRetrieve' => ['id', 'name', 'body', 'width', 'height'], // We pull only what we need!
];

$result = $index->search($query->query ?: null, $searchParams);

Because I'm pulling the body (SVG code) directly from Meilisearch, I don't need any database query for each icon. At the same time, I excluded the keywords fields, which would unnecessarily bloat the transferred data.

The result? Response time dropped to a stable 15-20 milliseconds.

4. Multilingualism for free: When even "cheap" AI is expensive

Once I had the basic English dataset ready, I thought of another improvement: Why limit it to English? I wanted ycon.cc to be a global tool and support the most well-known world languages.

When calculating the costs for the OpenAI API, I realized that translating hundreds of thousands of icons into 6 more languages would burn money unnecessarily given the massive number of requests. So I started looking for a way to solve it locally, "in my living room".

I chose LibreTranslate ? an open-source translation engine that I ran in Docker directly on my computer. No API keys, no monthly limits, no fees for every token.

To ensure translations were as accurate as possible, I didn't use isolated words in LibreTranslateService, but joined them into small units using implode(', ', $keywords). This gives the translator the necessary context, and the results are much more natural than if I translated each word individually.

I built the entire process on asynchronous processing via Symfony Messenger. The TranslateIconGroupHandler handler gradually took batches of icons and translated them into all activated languages.

// TranslateIconGroupHandler.php - The heart of translations
public function __invoke(TranslateIconGroupMessage $message): void
{
    // ... loading locales from DB ...
    foreach ($localeMap as $localeId => $localeCode) {
        // Idempotency: if we already have the translation, we skip
        if ($this->translationExists($message->iconGroupId, $localeId)) continue;

        // Contextual keyword translation (joined by comma)
        $translated = $this->libreTranslate->translateContextual($message->keywords, $localeCode);

        $translation = new IconGroupTranslation();
        $translation->setTranslatedKeywords($translated);
        $this->entityManager->persist($translation);
    }
    $this->entityManager->flush();
}

As a result, I had support for 7 languages in the system completely for free. The search engine thus understands not only the term "car", but also "auto", "vehicle", or "coche".

5. Developer Experience: Copy-pasting is gone too

Now that we have perfect and fast searching filled with data from iconify, the next step followed. Developers hate manually converting SVG files into components.

In ycon.cc, I therefore implemented the Strategy design pattern, which immediately transforms SVG code (with support for Iconify standards) into the format the developer currently needs (Tailwind classes, Vue/React components, or Symfony UX).


#[AutoconfigureTag('app.icon_code_generator')]
final readonly class SymfonyUxGenerator implements IconCodeGeneratorInterface
{
    public function generate(Icon $icon, ?string $alias = null): iterable
    {
        $prefix = $icon->getIconSet()?->getPrefix() ?? 'unknown';
        $originalName = $icon->getName();
        $iconName = sprintf('%s:%s', $prefix, $originalName);

        $renderName = $alias ?? $iconName;

        if ($alias !== null) {
            yield "Import Icon" => sprintf('<code>php bin/console ux:icon:import %s --as=%s</code>', $iconName, $alias);
        } else {
            yield "Import Icon" => sprintf('<code>php bin/console ux:icon:import %s</code>', $iconName);
        }

        yield "Twig Component" => "<code>".htmlspecialchars(sprintf('<twig:ux:icon name="%s" />', $renderName))."</code>";
        yield "Render Icon" => sprintf('<code>{{ ux_icon(\'%s\') }}</code>', $renderName);
    }
}

Just pick a framework and with one click, you have the code ready in your clipboard.

Conclusion

Transforming a gigantic repository like iconify/json into a fully semantic search tool was exactly the technical adventure why I love programming. The combination of LLM for data-enrichment and Meilisearch for lightning-fast querying is a combo I can only recommend.

If you are currently building a website or application and are tired of remembering exact technical names for icons, I have launched a beta version at ycon.cc.

Try entering a context into the search (e.g., "mute sound" or "add to cart") and let me know in the comments if it found what you expected. I greatly appreciate every piece of feedback (even critical).

Symfony UX: Single Directory Components (SDC) - The Path to Cleaner Architecture Without Tailwind

Jozef Môstka — Wed, 28 Jan 2026 04:39:00 +0000

Frontend development in Symfony has taken a huge leap forward in recent years. Thanks to Symfony UX and Twig Components, we've gained the ability to write reusable components much like in React or Vue. However, the more components you have, the more you encounter one annoying problem: files are scattered across the entire project.

A PHP class in src/Components, a Twig template in templates/components, CSS in assets/styles, and JavaScript somewhere else entirely. When you want to change the color of a button, you're looking at a trip through four different directories.

Some time ago, Hugo Alliaume published a great article A Better Architecture for Your Symfony UX Twig Components, where he proposed the concept of Single Directory Components (SDC). The idea is simple: let's have everything in one folder.

Today, we'll show you how to take this concept to the next level, completely get rid of manual configuration, and maybe even Tailwind.

Why Single Directory Components (SDC)?

If you've ever worked with Angular or Vue, you know that feeling of order. An Alert component is a single folder containing everything essential.

In the SDC approach, it looks like this:

src_component/
└── UI/
    └── Button/
        ├── Button.php           # Logic
        ├── Button.html.twig     # Template
        ├── Button.css           # Styles
        └── Button_controller.js # Interactions (Stimulus)

Main Advantages:

Maintainability: When you no longer need a component, you just delete one folder.
Developer Experience: No context switching between distant folders.
Isolation: Styles and scripts belong only to that one component.

Is Tailwind Passé? The Power of Native CSS and Variables

Lately, there's more and more talk about how, with the arrival of modern CSS features (like CSS variables, nesting, @layer), the need for utility frameworks like Tailwind is decreasing. Articles like The Power of CSS Variables remind us that pure CSS is stronger today than ever before.

The SDC approach plays right into this trend. When you have a CSS file right next to your PHP class, you don't need to write 20 Tailwind classes in your HTML. You can define clean, semantic CSS that uses CSS variables linked directly to PHP logic.

Our Solution: UX SDC Bundle

Hugo's article showed how to set up SDC manually. However, it requires changes to composer.json, Twig configuration, AssetMapper, and Stimulus.

Our bundle tito10047/ux-sdc does it for you. It's a Zero Configuration solution. Just install the bundle and mark the class with an attribute.

#[AsSdcComponent('UI:Button')]
class Button {
    // The bundle automatically finds Button.html.twig, Button.css, and Button_controller.js
}

The "Magic" Inside (Without Performance Loss)

The bundle solves technical challenges that you would have to patch yourself with a manual approach:

Asset Orchestration: CSS and JS files are injected into the page only when the component is actually rendered.
No More "Phantom" Controllers: You don't have to create an empty Stimulus controller just so AssetMapper knows about your CSS. The bundle handles it for you.
HTTP Preload & FOUC: We automatically generate Link headers for HTTP preload. The browser starts downloading CSS even before it starts parsing HTML. This eliminates the annoying flash of unstyled content (FOUC).
Production Performance: Thanks to a compiler pass, no disk scanning happens in production. Everything is pre-prepared in the cache.

Real-world Example: Project "Formalitka"

What does it look like in the real world? Take a look at the project formalitka.mostka.sk. The entire UI kit is built on SDC without a single line of Tailwind.

Let's take their Button component. The PHP class defines properties like color or size. The CSS then processes these properties using variables:

/* Button.css */
@layer components {
    .button {
        background: var(--color-primary);
        color: var(--color-on-primary);
        transition: var(--transition);

        &.button--secondary {
            background: var(--color-secondary);
        }
    }
}

Thanks to SDC, this complex component (containing seal animations, sounds, and special effects) is contained within one directory and is easy to maintain.

How to Get Started?

Installation is lightning fast:

composer require tito10047/ux-sdc

ux_sdc:
    ux_components_dir: '%kernel.project_dir%/src_component'
    component_namespace: 'App\Component'

And add the asset placeholder to your base.html.twig:

<head>
    {{ render_component_assets() }}
</head>

That's it. From this moment on, just create directories and write code.

Performance Under the Microscope: Proof Instead of Promises

When automation and "magic" come into play, the question often arises: What about performance? We put the SDC approach to a stress test with 500 unique components. Here are the key findings from our benchmarks:

Scenario	Classic Approach	SDC Approach	Difference
Warmup (Prod)	583.1 ms	586.2 ms	+3.1 ms
Render (Prod Runtime)	26.5 ms	31.6 ms	+5.1 ms
Render (Dev Runtime)	26.5 ms	88.4 ms	+61.9 ms

What does this mean in practice?

In production, the overhead is almost zero. Thanks to the compiler pass, no disk scanning happens at runtime. Rendering a single component has an overhead of only about 8.8µs, a negligible price for fully automated asset and Stimulus management.
Dev mode is optimized for DX. Instead of having to clear the cache every time a file changes, the bundle in dev mode uses runtime autodiscovery. It scans the disk only for those components that are currently being rendered. This means that if you add a new CSS file or change a Twig template, you see the changes immediately. Thanks to internal metadata caching within a single request, repeated rendering of the same component remains very fast.
Memory Footprint: With 500 components, the bundle consumes about 8MB more memory during container compilation, which is perfectly fine for modern applications.

You can find the full report in our benchmark.md.

The Future and Your Feedback (Version 0.0.1)

This bundle is currently in version 0.0.1. It's an early stage where we're looking for the right path. I wrote this article not only to share our solution but mainly to get feedback from you, the community.

We're interested in:

What do you think about the proposed API?
Is there anything missing that you would expect in an SDC approach?
Do you see any pitfalls in this approach that we've overlooked?

We want this bundle to be built on solid foundations and real developer needs from the first stable version. Every GitHub issue, discussion, or comment moves us forward.

Conclusion

Single Directory Components combined with modern CSS are changing the way we think about Symfony UX. We're getting rid of unnecessary boilerplate code, cleaning up our project structure, and increasing our performance as developers.

Try the UX SDC Bundle and say goodbye to scattered files. The future of Symfony UX is in order and clarity.

The Ultimate Image Solution for Symfony - stop writing srcset manually

Jozef Môstka — Fri, 09 Jan 2026 12:09:12 +0000

Solving the Image Problem in Symfony: Meet PGI

Images are the heaviest part of the modern web. They are responsible for slow page loads, frustrating Cumulative Layout Shift (CLS), and a nightmare developer experience when trying to implement truly responsive designs. If you’ve ever wrestled with complex <picture> tags or manually calculated srcset values for different breakpoints, you know the pain.

Enter PGI (Progressive Image Bundle)—the new standard for image handling in Symfony 6.4 and newer versions.

The Hook: Why Core Web Vitals Changed Everything

Google’s Core Web Vitals—specifically Largest Contentful Paint (LCP) and Cumulative Layout Shift (CLS)—have transformed how we build websites. It’s no longer enough to just "show an image." You need to show it fast, and you must ensure the layout doesn’t jump when the image finally appears.

For many Symfony developers, achieving a perfect 100/100 PageSpeed score while maintaining a clean codebase has felt like a trade-off. You either spend hours writing custom responsive logic or you settle for "good enough" performance. PGI was born to eliminate that trade-off.

Code Showcase: From Messy to Masterful

Let’s look at the difference. A standard responsive image in Twig often looks like this:

<img src="{{ asset('images/hero.jpg') }}" 
     srcset="{{ asset('images/hero_sm.jpg') }} 600w, {{ asset('images/hero_lg.jpg') }} 1200w"
     sizes="(max-width: 600px) 100vw, 50vw"
     width="1200" height="675"
     loading="lazy"
     alt="Hero image">

And that’s just for one aspect ratio. With PGI, you get a clean, Tailwind-inspired syntax:

<twig:pgi:Image 
    src="images/hero.jpg" 
    sizes="sm:12@square md:6@landscape"
    alt="Responsive hero image" 
    preload
/>

Real-world Case: just6words.com

To see PGI in action, let's look at how it handles a single image across different devices using an example from just6words.com.

Instead of writing multiple <img> tags or complex <picture> logic, you define everything in one place:

<twig:pgi:Image 
    src="realcase.jpg" 
    sizes="sm:12@square md:6@landscape" 
    alt="Responsive real-world example"
/>

What happens on different devices?

Mobile (sm): The browser loads a Square (1:1) crop. It takes the full width of the container.
Tablet/Desktop (md+): The browser automatically switches to a Landscape (16:9) crop. The image now occupies only half of the grid (6/12 columns).

Rendered HTML (Clean & Semantic)

PGI generates a single, optimized block of HTML that handles all the heavy lifting, including the Blur Placeholder:

<div class="progressive-image-container" 
     style="--img-width-sm: 640px; --img-aspect-sm: 1; --img-width-md: 384px; --img-aspect-md: 1.7777777777778;" ...>
    <canvas data-tito10047--progressive-image-bundle--progressive-image-target="placeholder" ...></canvas>
    <img src="/realcase.jpg" 
         srcset="/media/cache/640x640/realcase.jpg 640w, /media/cache/384x216/realcase.jpg 384w" 
         sizes="(min-width: 768px) 384px, (min-width: 640px) 640px, 100vw" ...>
</div>

What's happening here?

sm:12@square: Full width on small screens, automatically cropped to 1:1.
md:6@landscape: Half width (6/12 columns) from medium breakpoint, automatically cropped to 16:9.
xl:[430x370]: Need a very specific size for a custom layout? PGI supports arbitrary values directly in the sizes attribute.
preload: PGI automatically injects a <link rel="preload"> into your <head>, optimizing your LCP score instantly.

The "Progressive" in PGI: Blur-up Experience

One of the most satisfying features for users is the built-in Blurhash support. Instead of showing a blank space or a generic spinner, PGI renders a beautiful, ultra-lightweight blurred version of the image immediately.

This "blur-up" technique significantly improves perceived performance. Users see the layout and the context of the image instantly, even on slow connections, while the high-resolution version loads in the background. Once ready, the high-res image smoothly fades in, replacing the placeholder.

Technical Deep Dive: Zero CLS and CSS Magic

How does PGI prevent layout shift? It’s not just about adding width and height attributes. PGI leverages modern CSS aspect-ratio and CSS variables.

When the component renders, it calculates the aspect ratio based on your sizes definition. It then wraps the image in a container that reserves the exact space needed. No more content jumping as images load—even if the image is lazy-loaded or slow to arrive.

Powering the Engine: LiipImagine Integration

PGI doesn't reinvent the wheel for image processing. Instead, it stands on the shoulders of a giant: LiipImagineBundle. By default, PGI can delegate the heavy lifting of resizing and filtering to LiipImagine, allowing you to leverage its full ecosystem.

One of the most powerful features of this synergy is the automatic conversion to modern formats like WebP. With just a few lines of configuration, you can ensure that every image served by PGI is not only perfectly sized but also perfectly compressed.

Example Configuration:

# config/packages/liip_imagine.yaml
liip_imagine:
    default_filter_set_settings:
        format: webp
    webp:
        generate: true

# config/packages/progressive_image.yaml
progressive_image:
    image_configs:
        quality: 75
        post_processors:
            cwebp: { q: 30 }

By using the liip_imagine decorator, PGI automatically routes image requests through LiipImagine's filter system. This means you can use all your existing Liip filters while benefiting from PGI's superior Twig syntax and Zero CLS features.

Under the Hood: The Configuration That Makes It Possible

One of the most praised aspects of PGI is its flexibility. While it works out-of-the-box, the real power lies in its configuration. Let’s break down the most important parts of progressive_image.yaml:

# config/packages/progressive_image.yaml
progressive_image:
    # 1. Responsive Strategy
    responsive_strategy:
        grid:
            framework: tailwind # or bootstrap, or custom
        ratios:
            landscape: "16/9"
            square: "1/1"
            hero: "21/9"

    # 2. Resolvers (Where are your images?)
    resolvers:
        public_files:
            type: "filesystem"
            roots: [ '%kernel.project_dir%/public' ]
        assets:
            type: "asset_mapper"

    # 3. Transparent HTML Caching
    image_cache_enabled: true
    image_cache_service: "cache.app"

1. Responsive Strategy

This is the brain of PGI. By telling the bundle you use Tailwind or Bootstrap, it automatically knows the container widths for every breakpoint. When you say md:6, PGI looks up the md container width, divides it by 2 (6/12 columns), and generates the exact image size needed.

2. Resolvers: File Freedom

Whether you keep your images in the public/ folder or use the modern Symfony AssetMapper, PGI can find them. You can even define a chain resolver to look in multiple places. This is a lifesaver for projects transitioning to newer Symfony features.

3. Performance First: HTML Caching

Generating Blurhash and reading metadata requires CPU power. PGI solves this with transparent HTML caching. Once a component is rendered, the final HTML is stored in your cache. The next time someone visits the page, PGI serves the cached HTML instantly, skipping all PHP logic.

Point of Interest (PoI) Cropping

One of the coolest features is "Smart Cropping." Instead of blindly cropping from the center, you can define a Point of Interest:

<twig:pgi:Image src="team.jpg" pointInterest="75x25" sizes="md:6@square" />

This ensures that the most important part of the image (like a person's face) stays in the frame, regardless of whether it's being cropped to a square, portrait, or landscape ratio.

Why PGI Belongs in Your Next Project

PGI isn't just a wrapper; it's a complete ecosystem for Symfony:

Zero Configuration: Install and it just works with Bootstrap or Tailwind.
Automatic Generation: It generates all required sizes on the fly and caches them.
LiipImagine Integration: It plays nice with existing tools if you need custom filters.
Transparent Caching: It can cache the resulting HTML to avoid re-calculating metadata on every request.

If you are building a modern Symfony application and care about SEO, UX, and your own sanity as a developer, PGI is the missing piece of the puzzle. It’s already powering high-performance sites like just6words.com, helping them achieve near-perfect PageSpeed scores.

Ready to boost your PageSpeed?
Check out PGI on GitHub and join the movement toward a faster, more stable web.