DEV Community: Javier Eguiluz

A Simple Pattern That Makes Sorting in PHP Faster

Javier Eguiluz — Fri, 13 Mar 2026 07:18:02 +0000

Sorting arrays in PHP using a custom sorting criterion is simple thanks to the usort() function. But if you are not careful, it can be much slower than you expect.

Consider this example: you have a list of CSS rules represented as PHP classes and you need to sort them by specificity. Each rule exposes a getSpecificity() method that does some regex work internally. A natural first implementation looks like this:

usort($rules, function (Rule $a, Rule $b): int {
    return $a->getSpecificity() <=> $b->getSpecificity();
});

This code is correct, clean, readable ... and slow.

The hidden performance issue: a comparison sort typically performs n log(n) comparisons. Each comparison requires calling your callback, which in turn computes the sort key for both elements.

In this example, getSpecificity() is recomputed over and over again for the same objects during the sort. For a list of 100 rules, this means hundreds of comparisons and thousands of calls to getSpecificity().

In cases like this when the sort key is expensive to compute, there's a better way to do it.

The three step pattern

The optimization is to compute the expensive key once per element following a three-step pattern: decorate, sort, undecorate:

// Step 1: decorate (compute the expensive key once) and return [$rule, key] pairs
$decorated = array_map(
    static fn (Rule $rule): array => [$rule, $rule->getSpecificity()],
    $rules
);

// Step 2: sort using the cached key
usort($decorated, static fn (array $a, array $b): int => $a[1] <=> $b[1]);

// Step 3: undecorate (extract the original values)
$rules = array_column($decorated, 0);

Now getSpecificity() is called exactly once per rule, during the array_map() pass. The usort() comparisons only deal with integers and the total number of calls to the expensive method goes from O(n log n) to O(n).

This pattern is called the Schwartzian transform, named after Randal L. Schwartz, who popularized it in Perl back in 1994. The core idea comes from a Lisp idiom known as "decorate-sort-undecorate" (DSU).

This concept is language-agnostic: Python's sorted() has a built-in key= parameter that does the same thing, Ruby has sort_by, Haskell has sortOn. PHP does not have a native equivalent, but there's a trick you can use.

The `array_multisort()` trick

The array_multisort() PHP function can sort several arrays at once, or a multi-dimensional array by one or more dimensions. It's not very popular (60k usages on GitHub) compared to other array functions (e.g. 640k array_values() usages, 400k array_pop() usages, etc.), but it's very useful for Schwartzian transforms.

This is how it works. Consider this initial array:

$items = [
    ['category' => 2, 'priority' => 10, 'name' => 'Deploy'],
    ['category' => 1, 'priority' => 20, 'name' => 'Write docs'],
    ['category' => 2, 'priority' => 30, 'name' => 'Run tests'],
    ['category' => 1, 'priority' => 10, 'name' => 'Fix bug'],
];

If you need to sort it by both category (first) and priority (second), you can do this:

// extract the sorting keys first
$categories = array_column($items, 'category');
$priorities = array_column($items, 'priority');

// PHP sorts items ASC by category first and then, inside each
// category group, it sorts items DESC by priority
array_multisort($categories, SORT_ASC, $priorities, SORT_DESC, $items);

After sorting, the $items array is:

[
    ['category' => 1, 'priority' => 20, 'name' => 'Write docs'],
    ['category' => 1, 'priority' => 10, 'name' => 'Fix bug'],
    ['category' => 2, 'priority' => 30, 'name' => 'Run tests'],
    ['category' => 2, 'priority' => 10, 'name' => 'Deploy'],
]

Using array_multisort(), the "decorate, sort, undecorate" pattern becomes as simple as:

$keys = array_map(static fn (Rule $rule): int => $rule->getSpecificity(), $rules);
array_multisort($keys, SORT_ASC, $rules);

A real-world case in Symfony

tijsverkoyen/CssToInlineStyles is a popular PHP library (and an optional Symfony dependency) that converts CSS stylesheets to inline styles. Internally, it sorts CSS rules by specificity before applying them to DOM nodes.

In a real profiling session when running tests on a Symfony app, sortOnSpecificity() appeared in the flame graph with 104,000 calls triggering 126,000 calls to an inner compareTo() method. The sort was costing almost 200 ms out of a total runtime of 4 seconds, which looked excessive.

The original sortOnSpecificity() method used a usort() callback that called getValue() and getOrder() on every comparison:

// original code (simplified)
usort($rules, function (Rule $a, Rule $b): int {
    $aSpecificity = $a->getSpecificity();
    $bSpecificity = $b->getSpecificity();

    if ($aSpecificity->getValue() === $bSpecificity->getValue()) {
        return $a->getOrder() <=> $b->getOrder();
    }

    return $aSpecificity->getValue() <=> $bSpecificity->getValue();
});

The optimization was a direct application of the Schwartzian transform: compute the sortable keys once and let array_multisort() handle the ordering:

$specificityValues = [];
$orders = [];

foreach ($rules as $rule) {
    $specificityValues[] = $rule->getSpecificity()->getValue();
    $orders[] = $rule->getOrder();
}

array_multisort($specificityValues, SORT_ASC, $orders, SORT_ASC, $rules);

After this change, sortOnSpecificity() disappeared from the hot path in the profiler and the wall time improved by roughly 200 milliseconds.

You can see the full change in this pull request: PR #260

When to apply this technique

The Schwartzian transform is recommended only when:

The sort key is expensive to compute (I/O, regex, database queries, complex calculations)
You do not need memoization across multiple sorts. You just want each element's key computed once per sort invocation

If your sort key is a simple property access like $a->name, the overhead of decorating and undecorating is probably not worth it. The transform shines when the key computation has real cost.

✨ If you liked this post, consider sponsoring me on GitHub 🙌

Claude Code for Symfony and PHP: The Setup That Actually Works

Javier Eguiluz — Fri, 27 Feb 2026 07:25:52 +0000

Claude Code is a CLI tool that lets you use AI directly from your terminal to write, edit, and review code in your projects. I've been using it daily to work on PHP applications (Symfony and EasyAdmin) for a long time, and the results have been impressive. But getting there required some trial and error. In this article I'll share the setup, plugins, and workflows that made the difference.

To use Claude Code you'll need an active Claude AI subscription. I'm using the Max subscription ($100/month) but the Pro subscription ($17/month) will work too.

Usage

First, install Claude Code and log in using your account as explained on Claude docs. Now you can use Claude Code in your terminal by running the claude command in your project directory:

$ cd my-symfony-project/
$ claude

Many folks use it that way, but I prefer to use Claude Code inside my IDE. It will still be the same rough CLI-based application, but it will be next to your code and all the clickable file paths in Claude Code output will take you quickly to the related code.

My IDE is PhpStorm, so I use the official Claude Code Plugin developed by Anthropic for JetBrains IDEs (there's also an official plugin for Visual Studio Code). You can find it in the plugin marketplace right inside PhpStorm:

I use Claude Code all the time, so I keep it open as a right sidebar so I can easily focus on code or AI as needed:

One thing you need to know is that Claude Code provides different models. Some are smarter, but because of that they are also slower and more expensive to run (they'll consume your Claude Code limits sooner). You can select your model and its effort level by running the /model command inside Claude Code CLI.

CLAUDE.md / AGENTS.md

This is the most important idea of this article. Imagine that you ask me to implement a Symfony feature but you don't tell me anything about your project conventions. Will I do a good job? Well, maybe I used Yoda conditions and you hate them, maybe I used autowiring and you prefer explicit service registration, etc. If you don't explain how you like your code, you can't expect good code in return. The same happens with AI.

The AGENTS.md file (named exactly like that and stored at the root of your project) describes the "dos and don'ts" when writing code for your application. Before continuing: Claude looks first for a file called CLAUDE.md and all Claude docs mention that file name. However, a file called AGENTS.md will work exactly the same and has an additional benefit: CLAUDE.md only works with Claude but AGENTS.md works with all AIs (Claude, Codex, Gemini, GitHub Copilot, etc.) I recommend you to always use AGENTS.md.

Claude provides the /init command to create a first AGENTS.md in projects that have none. Some people say it doesn't create a good AGENTS.md file. Whether you like the result or not, you'll have to tweak this file and keep doing that continuously. Claude Code creator himself mentioned that he and his team update the AGENTS.md file of their projects all the time. This is key to get good results. You can't get good code with a bad AGENTS.md file.

You should avoid too vague and too specific instructions. Focus on simple and actionable instructions. Use simple language like "do this" or "don't do this" and don't use convoluted messages ("Don't try to avoid not doing foo and bar"):

// WRONG: too vague
* Don't make mistakes
* Check everything well

// WRONG: too specific
* On UserMessageHandler, don't return early
* Use public constants on `app:foo-bar` command

// CORRECT: general and actionable instructions
* Use Yoda conditions: `if (null === $value)`
* Use strict comparisons only (`===`, `!==`)
* Name variables and methods in `camelCase`

In addition to telling how to write good code, in AGENTS.md you must also explain how AI can verify that it wrote good code. Mention the tools you use and how to run them (PHPUnit, PHP-CS-Fixer, PHPStan, custom Makefile tasks, etc.)

For Symfony projects, here are some examples of useful AGENTS.md instructions:

* Use constructor promotion for dependency injection
* Use PHP attributes for routing, mapping, and configuration (never YAML/XML)
* Use Messenger handlers for async operations instead of putting logic in controllers
* [...]
* Run `php bin/console lint:container` to verify the dependency injection container compiles
* Run `php vendor/bin/phpstan analyse` to check for type errors
* Run `php vendor/bin/phpunit` to execute the test suite

If you need inspiration, you can check the AGENTS.md file we use in the EasyAdmin project. We're getting excellent results when using it, but it might not work as well in your project. So, don't copy it entirely, just get inspired and copy the ideas you like.

Plan, Plan, Plan

This is the second most important idea of this article. Claude Code has two main working modes: plan or work. If you are not aware of this, Claude Code will always be in work mode and you'll get mediocre results in complex tasks. Instead, switch Claude Code to plan mode and draft a plan for your bug fix or new feature.

Inside Claude Code CLI (standalone or embedded in your IDE) press [Shift] + [TAB] to cycle through the modes:

Stop when you see ⏸ plan mode on. Now, describe the feature you want to implement or give information about the bug you are trying to fix. Claude will start thinking about it and might ask you questions to clarify some things. I recommend selecting the most capable model of the moment (as of today, Opus 4.6) and setting it at High effort level. A good plan will create great code, so you really want to use the best model possible to create the plan.

When Claude Code finishes the plan, it will present it to you. Review it, and if you have questions or comments about things that don't look right, tell Claude. It will make changes in the plan and present it to you again. Keep asking questions and refining things until you are satisfied.

Creating a Good Plan

What should you use as the prompt to get a good plan? To me, the best approach is to not be too vague and not too specific either. If your prompt is very detailed and you explain how to solve the issue, you're constraining Claude Code to follow your orders instead of proposing its own solutions. Something important is that, when possible, you should mention the key files or directories to look into. This helps Claude Code immensely and produces good plans pretty quickly.

For example, when we added group actions in EasyAdmin 4.26 my prompt was something like this: "We want to add a new feature to group actions in backends. This is mostly for global actions shown at page level, but it should work for per-entity action dropdowns too. There should be two types of group actions: (1) a pure action dropdown where you click on the button and see the available actions; (2) a split-button type that provides a clickable main action and a dropdown with other actions. Use the @templates/components/Button.html.twig component for this new feature (you'll need to update it) and base the design on the Bootstrap split button component."

I didn't mention the specific classes where it should look (e.g. ActionFactory) because in this case it was trivial for AI to find them. If you work on complex tasks and know that the solution should focus on certain classes, mention them explicitly in your prompt. To do so, prepend the @ character to the relative dir/file path (@tests/, @src/Controller/UserController.php, etc.) In this example, I mentioned an existing Twig component because I was certain that it would work for the new feature.

In short, to generate a good plan: don't be vague, don't do too much hand-holding, and make sure to include important clues if you know them (like files/dir to use or look into).

For very complex tasks (think tens of thousands of lines of code) you can spend more than 30 minutes planning. Don't worry, a good plan is the key to getting great code. You are not wasting time, you are actually saving it.

If the planning session is long, you can stop and continue later. Use the /resume command to continue a past Claude Code session. If you ever lose a plan, don't worry. They are all saved in ~/.claude/plans/, so you can quickly find any plan you created.

Context

When you are finally happy with the plan, Claude Code will present several possible actions. My recommendation is to select the first one ("Yes, clear context and auto-accept edits"). After clearing the context, Claude Code will start implementing the plan autonomously. It will create and edit files, run tests, and fix issues on its own. If you selected the "auto-accept edits" option, it won't ask for permission on each change. You can watch the progress in real time and intervene at any point if something goes off track.

Think of the context as the total capacity that AI has for any task. As you plan things, ask questions, or answer Claude Code questions, the context fills up. As of today, Claude provides a context of 1 million tokens (a unit of measure used by AIs which roughly corresponds to three-quarters of a word).

If the context fills up, Claude Code tries to compact the contents, but ultimately results degrade significantly. So, if you planned a complex task and filled up more than 60% of the context, the implementation will probably suffer. That's why it's recommended to always clear the context after the plan, so the implementation work has the full context available.

Whenever you start a new task, run the /clear command inside Claude Code CLI to empty the context and start from scratch.

When Things Go Wrong

Even with a good plan, Claude Code will sometimes produce bad results. Here's how I handle that:

Small mistakes (wrong variable name, missing type hint): just tell Claude Code what's wrong in the chat and it will fix it immediately.
Everything is off: if the implementation went in the wrong direction, don't try to fix it incrementally. Run /clear, go back to plan mode, and refine the plan with what you learned from the failed attempt. This is faster than trying to patch bad code.

The key insight is that fixing a bad plan is always better than fixing bad code. If results are consistently bad, the problem is almost always in the plan or in your AGENTS.md file, not in Claude Code itself.

Plugins, Skills, Commands, Agents, Hooks

Claude Code has many different ways to add capabilities to the tool, such as plugins, agents, skills, and hooks. However, in my opinion, this is where most folks make a mistake. They install too many plugins, skills, agents, and hooks, and they create too many custom ones. Even Claude Code's author mentioned that he doesn't use many of these, so my recommendation is to keep it minimal.

Before installing a plugin, you must register the marketplace where the plugin is distributed from. The official Anthropic marketplace (claude-plugins-official) is enabled by default. It's confusing, but there's another plugin marketplace maintained by Anthropic (anthropics/claude-plugins-official) that has interesting plugins. I recommend adding that second marketplace as follows:

Run the claude command anywhere to start Claude Code CLI
Run the /plugins command inside Claude Code to open the plugin manager
Use the [←] [→] arrows on your keyboard to select the Marketplaces tab
Make sure + Add Marketplace is selected and press <Enter>
Type anthropics/claude-plugins-official and press <Enter> to add it

After adding the second official Anthropic repository, use the keyboard arrows to select each marketplace and click on Browse plugins to see the list of available plugins and install them. This is the list of plugins I recommend installing:

php-lsp: PHP language server (Intelephense) for code intelligence. Strongly recommended. Without it, Claude Code has no understanding of your project's type system: it will hallucinate method names, miss constructor parameters, and use classes that don't exist. With it, Claude Code can navigate your codebase the same way your IDE does
context7: strongly recommended; allows the AI to read up-to-date documentation for popular projects (including Symfony, Doctrine, Twig, and API Platform) without making web searches or browsing their websites
code-review: reviews pull requests using multiple specialized agents
code-simplifier: simplifies and refines code for clarity, consistency, and maintainability
security-guidance: a hook that warns about potential security issues when editing files, including command injection and XSS
playwright: a browser automation and end-to-end testing tool. It allows Claude Code to use a browser to debug issues in your Symfony applications (e.g. rendering issues in Twig templates or JavaScript problems in Stimulus controllers)

That's all. I get excellent results using only these plugins, so I recommend not spending too much time testing and configuring plugins.

About skills, commands and hooks, my recommendation is the same. When you start with Claude Code, don't worry much about them. As you learn to use it, add some custom skills, commands or hooks if you think they'll help you. For example, I have the following custom command (stored in ~/.claude/commands/fix.md) that fixes issues from GitHub repos (I only have to run this inside Claude Code: /fix {the issue number}) because this is something I have to do frequently:

---
allowed-tools: Bash(gh:*)
argument-hint: <issue-number>
description: Inspect a GitHub issue and plan/fix it
---

## Task

Analyze GitHub issue #$1 from this repository and fix it.

## Context

- Repository: !`gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "unknown"`
- Current branch: !`git branch --show-current`

## Steps

1. Fetch the issue: `gh issue view $1`

2. Analyze complexity:
   - **Trivial/Small** (typos, config tweaks, one-file fixes with clear solution): implement directly
   - **Medium/Large** (multiple files, architectural decisions, unclear scope): present a plan first

3. For direct implementation: make the fix, then summarize what was done.

4. For plans: detail the files to modify, proposed approach, and potential risks.

Sub-Agents

This is an important concept but, as Claude Code is getting smarter every day, nowadays it's not that important to manage this manually. For certain tasks, Claude Code launches copies of itself called sub-agents automatically to work on different sub-tasks in parallel. In addition to the performance gain, the main benefit of sub-agents is that each of them can use their own context to complete their job, without filling up the context of the main task.

If you are working on complex tasks, Claude Code might decide to launch sub-agents on its own. But you can also force this by mentioning explicitly in your prompt to "use sub-agents to implement all tasks in parallel". Claude Code recently launched teams as an advanced version of sub-agents. It's still experimental, but it allows you to coordinate multiple Claude Code instances working together as a team, with shared tasks, inter-agent messaging, and centralized management.

For Symfony projects, sub-agents work great when you need to implement related but independent pieces: for example, creating a Messenger handler, its corresponding message class, and the functional test, all at the same time.

Global Settings

If you followed all the above recommendations, you're probably getting good results with Claude Code in your Symfony applications. However, Claude Code is probably annoying you a bit. That's because it asks for permission to do anything: Can I read this file? Can I list the contents of this directory? Can I check the syntax of this file?

Some people add the --dangerously-skip-permissions option when running the claude command. I don't recommend doing this. As its name shows, this is too dangerous in practice. My recommendation is to solve this with global permissions. You can use the ~/.claude/settings.json file to configure settings applied to all Claude Code sessions. For example, this is my configuration that allows all safe commands, bans some dangerous commands, and prevents accessing certain files:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "permissions": {
    "allow": [
      "Bash(cat:*)",
      "Bash(curl:*)",
      "Bash(diff:*)",
      "Bash(echo:*)",
      "Bash(find:*)",
      "Bash(gh:*)",
      "Bash(git:*)",
      "Bash(grep:*)",
      "Bash(head:*)",
      "Bash(ls:*)",
      "Bash(pwd)",
      "Bash(tail:*)",
      "Bash(tree:*)",
      "Bash(wc:*)",
      "Bash(which:*)",
      "Bash(php-cs-fixer:*)",
      "Bash(php:*)",
      "Bash(phpstan:*)",
      "Bash(phpunit:*)",
      "Bash(symfony:*)"
    ],
    "deny": [
      "Bash(rm:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./config/secrets/.*)",
      "Read(./secrets/**)"
    ],
    "defaultMode": "acceptEdits"
  },
  "enabledPlugins": {
    "php-lsp@claude-plugins-official": true,
    "code-simplifier@claude-plugins-official": true,
    "context7@claude-plugins-official": true,
    "code-review@claude-plugins-official": true,
    "security-guidance@claude-plugins-official": true,
    "playwright@claude-plugins-official": true
  },
  "alwaysThinkingEnabled": true
}

In this global configuration file, you can also configure hooks. For example, I use hooks to automatically lint and format files whenever Claude Code creates or edits them. This is especially useful in Symfony projects where you want to enforce coding standards on PHP files and validate YAML configuration files:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "..."
    ],
    "deny": [
      "..."
    ],
    "defaultMode": "acceptEdits"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "case \"$CLAUDE_FILE_PATH\" in *.php) php-cs-fixer fix --quiet \"$CLAUDE_FILE_PATH\" 2>/dev/null || true ;; esac",
            "timeout": 30
          },
          {
            "type": "command",
            "command": "case \"$CLAUDE_FILE_PATH\" in *.yaml|*.yml) php bin/console lint:yaml \"$CLAUDE_FILE_PATH\" ;; esac"
          },
          {
            "type": "command",
            "command": "case \"$CLAUDE_FILE_PATH\" in *.json) python3 -m json.tool \"$CLAUDE_FILE_PATH\" > /dev/null ;; esac"
          }
        ]
      }
    ]
  }
}

Next Steps

If you take away three things from this article, make it these: (1) write a good AGENTS.md file and keep refining it, (2) always plan before you code, and (3) don't overload Claude Code with plugins. That combination alone will get you better results than any amount of tweaking.

As you become a better Claude Code user, read Claude Code Docs to keep improving.

✨ If you liked this post, consider sponsoring me on GitHub 🙌

EasyAdmin 5.0: A New Foundation for Your Admin Backends

Javier Eguiluz — Thu, 26 Feb 2026 07:19:34 +0000

EasyAdmin 5.0.0 has just been released as the new stable version of EasyAdmin.

EasyAdmin follows a development philosophy similar to Symfony. That means EasyAdmin 5.x includes exactly the same features as 4.x. The difference is that 5.x removes everything that was deprecated during the 4.x cycle, providing a cleaner and more future-proof foundation.

EasyAdmin 5.0 raises the minimum Symfony and PHP requirements while still offering broad compatibility. It supports Symfony 6.4, all 7.x and 8.x versions, works with Doctrine ORM 2.x and higher, and requires PHP 8.2 or later.

What Changed in 5.0

All features introduced throughout the 4.x cycle are now the only supported approach in 5.0. Here is a summary of the most relevant changes.

Pretty URLs

In 4.x, you could still use the legacy URL format that this bundle used since day one (e.g. https://example.com/admin?crudAction=edit&crudControllerFqcn=App%5CController%5CAdmin%5cPostCrudController&entityId=3874).
In 5.0, only the pretty URLs are supported (e.g. https://example.com/admin/post/3874/edit), which we introduced in version 4.14.

You do not need to configure anything to use them. They are enabled by default thanks to this Symfony Flex recipe which loads a custom Symfony route loader.

Pretty URLs have been tested in production for over a year. During that time, we fixed edge cases related to menus, custom actions, and more. They are stable and ready for all applications.

Dashboard Definition via Attribute

Instead of relying on Symfony's #[Route] attribute, you now must apply the #[AdminDashboard] attribute to your dashboard class, added in version 4.24:

// BEFORE (4.x)
use Symfony\Component\Routing\Attribute\Route;

class DashboardController extends AbstractDashboardController
{
    #[Route('/admin', name: 'admin')]
    public function index(): Response
    {
        // ...
    }
}

// AFTER (5.x)
use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;

#[AdminDashboard(routePath: '/admin', routeName: 'admin')]
class DashboardController extends AbstractDashboardController
{
    public function index(): Response
    {
        // ...
    }
}

The new attribute supports all route options provided by Symfony and adds its own features. For example, you can customize the format of admin routes and restrict which CRUD controllers are available on each dashboard.

Embedding Symfony Controllers in Your Backend

With the new #[AdminRoute] attribute added in version 4.25 you can integrate any Symfony controller action into your admin backends. This attribute automatically generates the routes required to render your action inside one or more dashboards, reusing the same layout, menus, and visual design as built-in EasyAdmin actions.

Action Improvements

During the 4.x cycle, we shipped several improvements to actions: grouping them in dropdowns and split buttons (version 4.26), showing a custom confirmation message before any action (version 4.28), and configuring a default action triggered when clicking any row on CRUD index pages.

Autocomplete Customization

In version 4.28, we added full control over how autocomplete entries are rendered:

// use callbacks for simple customizations
yield AssociationField::new('category', 'post.category')
    ->setSortProperty('name')
    ->autocomplete(callback: static fn (Category $c): string => sprintf('%s %s', $c->getIcon(), $c->getName()));

// use Twig template fragments for complex customizations with HTML elements
yield AssociationField::new('author', 'post.author')
    ->setSortProperty('fullName')
    ->autocomplete(template: 'admin/post/_author_autocomplete.html.twig', renderAsHtml: true);

Custom Icon Sets

EasyAdmin still uses FontAwesome icons by default, but since version 4.16 you can use any icon set, such as Tabler or Material Icons.

New Twig Components

During the 4.x cycle, we introduced Twig Components for common UI elements. In EasyAdmin 5.x, the long-term goal is to build the entire UI on top of reusable Twig Components, making it easier to compose fully custom admin pages.

Upgrading to 5.x

We strongly recommend upgrading as soon as possible. EasyAdmin 4.x will not receive new features, and future improvements will target 5.x exclusively.

First, ensure your application has no remaining deprecations from 4.x. You can check this in the Symfony profiler or by running your test suite with deprecations treated as errors. Review the EasyAdmin 4.x to 5.x Upgrade Guide for detailed instructions.

Once your project is free of deprecations, update the constraint in your composer.json:

$ composer require easycorp/easyadmin-bundle:^5.0

That is all. Since 5.0 is functionally identical to the latest 4.x release, except for removed deprecated code, no additional changes should be required.

Trying EasyAdmin for the First Time

If you are new to EasyAdmin, getting started takes only a few commands:

$ composer require easycorp/easyadmin-bundle

$ php bin/console make:admin:dashboard
$ php bin/console make:admin:crud

This creates a working admin backend with a dashboard and your first CRUD controller. From there, explore the EasyAdmin documentation to customize fields, actions, filters, and more.

You can also review the EasyAdmin Demo project.

✨ If you enjoyed these features and want to see more like it, consider
sponsoring the EasyAdmin project 🙌💡

New in EasyAdmin 4.28: New Filters, Better Autocomplete, CSP, and Smarter Actions

Javier Eguiluz — Thu, 29 Jan 2026 07:16:18 +0000

EasyAdmin 4.28 is out, and it's packed with features to improve your backends.

Clickable Rows in the Index Page

Here's something users have requested for years: clicking anywhere on a row in the index page now navigates to that entity. By default, it goes to the edit page (or falls back to detail if edit isn't available).

But you have full control:

public function configureCrud(Crud $crud): Crud
{
    return $crud
        // navigate to detail instead of edit
        ->setDefaultRowAction(Action::DETAIL)

        // use a custom action
        ->setDefaultRowAction('review')

        // define a fallback chain (first available action wins)
        ->setDefaultRowAction([Action::DETAIL, 'preview', Action::EDIT])

        // disable row clicks entirely
        ->setDefaultRowAction(null);
}

The behavior is smart: if the configured action isn't available for a specific entity (disabled, no permission, or condition not met), that row simply won't be clickable. Clicks on checkboxes, buttons, links, or other interactive elements within the row work as expected: they don't trigger navigation.

You can set a global default in your dashboard and override it per CRUD controller:

// in your Dashboard: applies to all CRUD controllers
public function configureCrud(): Crud
{
    return Crud::new()->setDefaultRowAction(Action::DETAIL);
}

// in a specific CRUD controller: overrides the dashboard default
public function configureCrud(Crud $crud): Crud
{
    return $crud->setDefaultRowAction(Action::EDIT);
}

Read the docs about default row actions

Content Security Policy (CSP) Support

If you've ever tried to use EasyAdmin with strict CSP headers (especially with NelmioSecurityBundle), you know the frustration: script violations everywhere.

Not anymore. EasyAdmin 4.28 automatically injects nonce attributes when the csp_nonce() Twig function is available (i.e. when NelmioSecurityBundle is installed in your application). Inline onclick handlers have been replaced with data attributes processed by JavaScript. Zero configuration required, it just works.

Thanks to Mikołaj Jeziorny for contributing this feature.

Five New Filters

Filtering by country, currency, language, locale, or timezone used to require creating custom filters. Now they're built-in:

$filters
    ->add(CountryFilter::new('country')->includeOnly(['US', 'CA', 'MX']))
    ->add(CurrencyFilter::new('currency')->preferredChoices(['USD', 'EUR']))
    ->add(TimezoneFilter::new('timezone')->forCountryCode('US'));

All filters display localized names using Symfony's Intl component. They support multi-select, preferred choices at the top of the list, and many other options. Read the docs about the new filters.

Confirmation for Any Action

The delete action has always shown a confirmation dialog. Now you can add the same protection to any action with a single method call:

Action::new('archive', 'Archive')
    // ...
    ->askConfirmation();

This displays a generic confirmation modal. But you can customize the message:

Action::new('publish', 'Publish')
    // ...
    ->askConfirmation('Are you sure you want to publish this article?');

Need dynamic content? Use placeholders that get replaced automatically:

->askConfirmation(
    'Delete %entity_name% #%entity_id%? This cannot be undone.'
)

You can also customize the confirmation button label (instead of the default "Confirm"):

->askConfirmation(
    'Publish this article to production?', 'Yes, publish it'
)

Both parameters support TranslatableInterface objects for full i18n support. And yes, you can now disable confirmation on the delete action if you really want to (though we don't recommend it).

Preferred Choices

When you have dozens of options but users pick the same three 90% of the time, put them at the top:

ChoiceField::new('status')
    ->setChoices([/* many choices */])
    ->setPreferredChoices(['draft', 'published']);

The preferred choices appear first, visually separated from the rest.

Read the docs about preferred choices

Autocomplete Customization

Association fields with many options use autocomplete by default. Until now, the dropdown displayed whatever __toString() returned. Now you can customize how entries are formatted.

Using a callback for simple formatting:

AssociationField::new('author')->autocomplete(
    callback: static fn (User $user) => sprintf('%s (%s)', $user->getFullName(), $user->getEmail()),
);

Using a Twig template for rich HTML formatting:

AssociationField::new('product')->autocomplete(
    template: 'admin/fields/product/autocomplete.html.twig',
    renderAsHtml: true,
);

The template receives the entity as the entity variable. Set renderAsHtml: true only when you trust the content (it disables XSS escaping):

{# templates/admin/fields/product/autocomplete.html.twig #}
<div class="product-option">
    <strong>{{ entity.name }}</strong>
    <span class="text-muted">({{ entity.sku }})</span>
    {% if entity.stock < 10 %}
        <span class="badge badge-danger">Low Stock</span>
    {% endif %}
</div>

Read the docs about autocomplete() customization

✨ If you enjoyed these features and want to see more like it, consider
sponsoring the EasyAdmin project 🙌💡

New in EasyAdmin: Custom Admin Routes

Javier Eguiluz — Mon, 22 Sep 2025 10:02:21 +0000

EasyAdmin lets you create CRUD-based backends with minimal setup: define your entities, add CRUD controllers, get a complete admin interface.

You can extend these CRUD controllers with custom actions (e.g. approve action for users, duplicate action for products, etc.) These custom actions must live inside the CRUD controller, which isn't always practical.

Also, your application has features that don't fit the CRUD pattern and require their own controllers with custom logic. You could always embed external controllers in EasyAdmin, but the integration was clunky. The external controllers were integrated via their Symfony routes from your main menu like this:

yield MenuItem::linkToRoute('Business Stats', 'fa fa-chart-bar', 'business_stats_index', [
    'param1' => 'value1',
    'param2' => 'value2',
]);

But the generated URLs revealed the awkward integration:

/admin?routeName=business_stats_index&routeParams%5Bparam1%5D=value1&routeParams%5Bparam2%5D=value2

The `AdminRoute` Attribute

EasyAdmin 4.25.0 introduces the #[AdminRoute] attribute for seamless Symfony controller integration. Take the following Symfony controller to calculate some business stats:

use App\Stats\BusinessStatsCalculator;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class StatsController extends AbstractController
{
    public function __construct(
        private BusinessStatsCalculator $statsCalculator,
    ) {
    }

    public function index(): Response
    {
        $stats = $this->statsCalculator->getData();
        // ...
    }
}

This is a pure Symfony controller. It doesn't use any EasyAdmin code or feature. Now, add the #[AdminRoute] attribute to your controller action:

use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminRoute;
// ...

class StatsController extends AbstractController
{
    // ...

    #[AdminRoute('/stats', name: 'stats')]
    public function index(): Response
    {
        // ...
    }
}

That's it. The #[AdminRoute] configuration in controllers is appended to the route path/name of the dashboard(s). If your Symfony application defines an admin dashboard with /admin route path and admin route name, this code will add an admin route called admin_stats with path /admin/stats.

Browse to that URL and your custom logic is rendered inside the backend with the same layout and navigation as your CRUD pages. Use the new route to link to the controller from your dashboard menu:

public function configureMenuItems(): iterable
{
    yield MenuItem::linkToRoute('Statistics', 'fa fa-chart-bar', 'admin_stats');
    // ...
}

Click on that menu item and you'll see that the URL is now just /admin/stats, without the previous awkward query parameters.

Composing Routes

Similar to Symfony's #[Route] attribute, #[AdminRoute] supports class-level configuration for common prefixes:

use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminRoute;
// ...

#[AdminRoute('/reports', name: 'reports')]
class ReportController extends AbstractController
{
    #[AdminRoute('/sales', name: 'sales')]
    public function sales(): Response
    {
        // ...
    }

    #[AdminRoute('/inventory', name: 'inventory')]
    public function inventory(): Response
    {
        // ...
    }

    #[AdminRoute('/customers/{id}', name: 'customer')]
    public function customerReport(Customer $customer): Response
    {
        // ...
    }
}

This generates three admin routes:

admin_reports_sales at /admin/reports/sales
admin_reports_inventory at /admin/reports/inventory
admin_reports_customer at /admin/reports/customers/{id}

The routing system concatenates the dashboard prefix, the class-level route, and the action-level route to build the final path and name.

The #[AdminRoute] attribute can also customize the default CRUD route names and paths, giving you complete control over your admin URL structure.

Multi-Dashboard Control

#[AdminRoute] creates one admin route per dashboard. If your application has multiple dashboards, you can control where routes are registered with allowedDashboards (route is created only in these dashboards) and deniedDashboards (route is created in all dashboards except these):

#[AdminRoute(
    '/financial-reports', name: 'financial',
    allowedDashboards: [AdminDashboardController::class]
)]
class FinancialReportController extends AbstractController
{
    // ...
}

#[AdminRoute(
    '/user-reports', name: 'users',
    deniedDashboards: [GuestDashboardController::class, '...']
)]
class UserReportController extends AbstractController
{
    // ...
}

Recap

The #[AdminRoute] attribute solves a common need: keeping your business logic in dedicated controllers while providing a unified admin experience. No more awkward URL parameters. Your controllers stay pure Symfony code, but render like native EasyAdmin pages.

✨ If you enjoyed this feature and want to see more like it, consider
sponsoring the EasyAdmin project 🙌💡

Reusing SVG Icons for Faster Pages

Javier Eguiluz — Mon, 30 Jun 2025 07:54:57 +0000

SVG is an XML-based vector graphics format that supports interactivity and animation. The SVG 1.1 specification spans more than 800 pages, so there's a lot hidden inside.

A little-known SVG feature can make your site faster when you repeat the same SVG images, such as icons.

The Problem: Too Many SVG Images

We recently redesigned the Symfony Packages page that lists every Symfony package (currently 266 and counting) and lets you filter them with a bit of JavaScript.

The page itself is simple, but there is a problem: it is massive. With so many packages, even small elements add up quickly. For example, each package shows five SVG icons. That makes a total of 266 × 5 = 1,330 SVG images, just for icons.

This is not a problem for the total page size. Thanks to HTTP compression, this 1.2MB HTML page only transfers 84KB to clients. However, adding thousands of images slows down parsing and rendering, and it also hurts the JavaScript-based sorting performance.

We could render the SVG icons with <img> elements or as CSS backgrounds, but that approach doesn't let us change the icon's color, a must-have feature in our case. We could also load the list dynamically with JavaScript, but that only defers the rendering performance issue without actually solving it.

Fortunately, SVG defines a feature that allows you to reuse an image as many times as you want within the same HTML page. Our solution displays 1,330 SVG icons while only including 5 SVG definitions in the HTML source.

The Solution: SVG `<use>` Element

Take this GitHub SVG icon from the Simple Icons collection:

<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24">
    <path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"></path>
</svg>

First, add an id attribute to the <path> element inside the <svg>. Let's call it icon-github:

<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24">
    <path id="icon-github" ...></path>
</svg>

Tip
For complex SVG images with multiple elements, wrap everything in a <g> element and add the id attribute to that grouping element.

Now you can reuse this image unlimited times as follows:

<svg viewBox="0 0 24 24" height="16" width="16" aria-hidden="true">
    <use href="#icon-github"></use>
</svg>

The <use> SVG element takes nodes from within an SVG document and duplicates them elsewhere. It clones the referenced nodes and places them where the <use> element appears, without creating a shadow DOM.

That's it. You can reuse the same SVG image unlimited times on the same page without including its contents repeatedly.

Legacy SVG Attributes

If the href attribute in <use> doesn't work in older browsers, fall back to the legacy xlink:href attribute with the same value. To support both modern and legacy browsers, include both attributes (browsers prioritize href):

<svg viewBox="0 0 24 24" height="16" width="16" aria-labelledby="github-icon-title">
    <title id="github-icon-title">Source code</title>
    <use href="#icon-github" xlink:href="#icon-github"></use>
</svg>

Styling of Reused SVG Images

The <use> element clones the referenced content. CSS properties like fill and stroke can cascade from the <svg> instance, but only if they are not already defined on the source graphics.

If the cloned contents are <path d="..." fill="currentColor">, you can override the color with <svg fill="red">. However, if the cloned contents are <path d="..." fill="black">, you can't override the color because the fill="black" on the source path takes precedence.

That's why it's recommended to remove the fill and stroke attributes from the source SVG paths or set them to currentColor so the cloned icons can be styled later.

Creating SVG Sprites

In our web page, we did the following: render icon definitions once in a hidden container, then reference them throughout the page:

<!-- the browser won't display these icons -->
<div style="display: none">
    <svg><path id="icon-github" ...></path></svg>
    <svg><path id="icon-download" ...></path></svg>
    <svg><path id="icon-calendar" ...></path></svg>
    <!-- ... -->
</div>

{% for package in packages %}
    {# ... #}

    <a class="..." href="...">
        <svg viewBox="0 0 24 24" height="16" width="16" aria-hidden="true" class="...">
            <use href="#icon-github"></use>
        </svg>
        Code
    </a>

        {# ... #}
{% endfor %}

Accessibility tip
If an icon appears next to descriptive text (like "Code" in the example above), mark it as decorative with aria-hidden="true" so screen readers can ignore it. If the icon stands alone (e.g., a button without text), make it accessible with a <title> element and aria-labelledby.

While this approach works well, SVG provides a better way of doing it thanks to the <defs> and <symbol> elements. The <defs> element is a container for graphical objects that you want to define once and use later.

The <symbol> element is not rendered directly; it defines graphical template objects that are rendered only when referenced by a <use> element. It also supports its own viewBox and preserveAspectRatio attributes, making it a self-contained, reusable component.

This collection of definitions inside a single SVG is commonly called an SVG sprite: a single file that includes multiple reusable graphics.

You can replace the previous <div>-based container with an inline sprite like this:

<svg style="display: none;">
    <defs>
        <symbol id="icon-github" viewBox="0 0 24 24">
            <path d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303..."></path>
        </symbol>

        <symbol id="icon-download" viewBox="0 0 24 24">
            <path d="..."></path>
        </symbol>

        <symbol id="icon-calendar" viewBox="0 0 24 24">
            <path d="..."></path>
        </symbol>

        <!-- ... -->
    </defs>
</svg>

It's recommended to add the viewBox attribute to each <symbol> so you don't have to repeat it later. Instead, the icon instances only need height and width:

<svg height="16" width="16" aria-hidden="true" class="...">
    <use href="#icon-github"></use>
</svg>

The SVG sprites can also be defined as external files and reference them on any page via its public URL and id value:

<svg width="16" height="16">
    <use href="/path/to/svg-icons-sprite.svg#icon-github"></use>
</svg>

If you reuse the same icons across many pages, put the SVG sprite in its own file so browsers can cache it and boost performance even further.

Key Takeaways

Define each icon once and reuse it with <use> so your DOM stays light and renders faster.
Bundle multiple icons into a <symbol>-based sprite, which can be inlined or loaded from an external, cacheable file.

✨ If you enjoyed this or any of my other articles and want to support my work, consider sponsoring me on GitHub 🙌

How to Make ChatGPT Codex Work with PHP and Symfony

Javier Eguiluz — Thu, 05 Jun 2025 20:51:49 +0000

Codex is a cloud-based coding agent created by OpenAI. It can run multiple tasks in parallel to fix bugs, implement features, suggest improvements, and more. It can even create pull requests on platforms like GitHub.

Although Codex already works well with PHP, providing solid code suggestions and improvements, its most powerful feature is that it can run your code (e.g., executing your test suite) to verify that its proposed changes actually work. This is a game-changer for languages like Python or JavaScript, where code execution is supported out of the box.

PHP, however, is not natively supported for code execution. This article explains how to make Codex work effectively with PHP and Symfony applications, including how to configure it to run your test suite and validate changes automatically.

As of this writing, Codex is available to Plus ($20/month) and Pro ($200/month) ChatGPT users, but not to free-tier users.

Setting Up the Environment

Visit chatgpt.com/codex and follow the on-screen steps to connect Codex to your GitHub repositories. You'll see which repositories you can import directly and which ones require admin approval if you only have limited access.

Before Codex can work with a repository, you need to create an environment for it. An environment defines how Codex interacts with your code.

Go to chatgpt.com/codex/settings/environments and click the Create environment button. Each environment is tied to a single GitHub repository, so you'll need to create one environment per repo.

In the Basic section, choose the GitHub organization and repository of your PHP/Symfony project:

In the Code execution section, configure the following options:

Container image: Codex tasks run your code inside a Docker container. Currently, only the universal image provided by Codex is available. Support for custom images is coming soon. Check the list of default installed packages in the universal image.
Environment variables and Secrets: self-explanatory; covered later in this article.
Setup script: this is the critical part for PHP/Symfony projects. It's used to install PHP, Composer, and other tools not included in the default image. A full example is provided below.
Agent internet access: disabled by default. Enable it only if you absolutely need it (e.g., to download dependencies). Even OpenAI recommends keeping it off. Instead, use the setup script to download everything you need, as explained below.

Setup Script

The setup script runs at the beginning of every task, after the repository is cloned. It's your chance to prepare the environment for PHP/Symfony development and testing. Internet access is always enabled during this step, so you can install dependencies here even if it's disabled later.

Here's a full example I use for Symfony apps. Once you've saved your environment, click Connect interactive terminal to test and debug the script in the actual container Codex will use for tasks.

#!/usr/bin/env bash
# this makes the script strict:
#   -e: exit on any error
#   -u: error on undefined variables
#   -o pipefail: exit if any command in a pipeline fails
set -euo pipefail

# Adds a package repository that provides the latest PHP versions
# (see https://deb.sury.org/ for details)
add-apt-repository -y ppa:ondrej/php
# Updates package lists to get the latest information about available packages
apt-get update

# Install PHP 8.4 and extensions commonly needed for Symfony applications
apt-get install -y \
    php8.4 \
    php8.4-cli \
    php8.4-mbstring \
    php8.4-xml \
    php8.4-intl \
    php8.4-gd \
    php8.4-zip \
    php8.4-curl \
    php8.4-pgsql # this is for PostgreSQL; change this if you use MySQL

# This makes PHP 8.4 available through the global 'php' binary,
# which is expected by many commands
update-alternatives --install /usr/bin/php php /usr/bin/php8.4 84
update-alternatives --set php /usr/bin/php8.4

# Install Composer as a global 'composer' binary following the safest practices
EXPECTED_CHECKSUM="$(curl -fsSL https://composer.github.io/installer.sig)"
curl -fsSL https://getcomposer.org/installer -o composer-setup.php
ACTUAL_CHECKSUM="$(sha384sum composer-setup.php | cut -d ' ' -f 1)"
if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]; then
    echo 'ERROR: Invalid composer installer checksum.' >&2
    rm composer-setup.php
    exit 1
fi
php composer-setup.php --install-dir=/usr/local/bin --filename=composer --quiet
rm composer-setup.php

# Install the PHP dependencies of your project;
# private packages require some more work explained later in this article
composer install

# Show installed versions to check if everything worked
php -v
composer --version

Private Composer Packages

If your project depends on private Composer packages (e.g., from GitHub), you'll need to authenticate Composer.

(1) Create a personal access token: either a classic token or a fine-grained token. Name it something like "OpenAI Codex" and give it read access to the private repositories.

(2) Add the token to Codex: go to your Codex environment settings, scroll to Secrets, and click Add +. Name the secret COMPOSER_AUTH. The value must be a JSON-encoded element with the token that you created earlier. The format is the same as used in the file ~/.composer/auth.json but you must put everything in a single line. For example:

{"github-oauth":{"github.com": "ghp_fs2dWqUilbS0NBeJaWBw3QgIucTO5RyrXV1e"}}

Optionally, you can add a check in your setup script to make sure this secret is set:

#!/usr/bin/env bash
set -euo pipefail

# the script will fail if this env var / secret is not set
: "${COMPOSER_AUTH:?}"

# ...

Using Databases

If your test suite requires a database (e.g., MySQL or PostgreSQL), you'll need to install and configure it in the setup script. Here's how to do it:

First, define the following environment variables: POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB. These can use dummy values for local test databases. Make sure they match the values used in the DATABASE_DSN option of your Symfony application.

Then add these to the top of your script to verify they're defined:

#!/usr/bin/env bash
set -euo pipefail

# make sure the required env vars are defined
: "${COMPOSER_AUTH:?}"
: "${POSTGRES_USER:?}"
: "${POSTGRES_PASSWORD:?}"
: "${POSTGRES_DB:?}"

# ...

Next, install PostgreSQL:

# Update package lists
# ...

# Install PostgreSQL
apt-get install -y --no-install-recommends postgresql-16

# Install PHP and common extensions
# ...

Start PostgreSQL and create the user/database:

# Install Composer
# ...

# Install dependencies
# ...

# Start PostgreSQL
pg_dropcluster --stop 16 main || true
pg_createcluster --start -u postgres 16 main

# Create the PostgreSQL user and database
su postgres -c "createuser -s \"${POSTGRES_USER}\""
su postgres -c "psql -c \"ALTER USER \\\"${POSTGRES_USER}\\\" WITH PASSWORD '${POSTGRES_PASSWORD}';\""
su postgres -c "createdb -O \"${POSTGRES_USER}\" \"${POSTGRES_DB}\""

# (Optional) Verify that the user can log in
# psql -U $POSTGRES_USER -d $POSTGRES_DB

# Show installed versions
# ...
psql --version

General Settings

Before running your first task, visit chatgpt.com/codex/settings/general to configure global settings used across all projects:

Custom instructions: used to customize the behavior of Codex; e.g., "Always use English for code, comments, commits, and branch names", "Use concise branch names prefixed with feat- or bug-", etc.
Branch format: defaults to codex/{feature} but you can change it to {feature} or anything else.

Providing Metadata to Agents

Although optional, adding metadata files can significantly improve how agents like Codex understand and navigate your codebase. These plain-text files describe how
to run tests, what conventions to follow, and more. With good metadata, you'll get more accurate results and fewer mistakes.

There's no universal standard yet, so you'll need one file per agent. In my projects, I use:

<project-root>/AGENTS.md for ChatGPT Codex
<project-root>/CLAUDE.md for Claude AI
<project-root>/.github/copilot-instructions.md for GitHub Copilot

All three files usually share the same content. You can create one file and use symlinks for the others. Claude also supports importing files using:

See @AGENTS.md

You can see a real-world example of the AGENTS.md file I use in one of my projects. As you run tasks, update this file continuously with new instructions to prevent Codex from making the same mistakes again.

Security and Privacy Recommendations

In addition to disabling Agent internet access, you should review the privacy settings at chatgpt.com/codex/settings/data:

Model improvement: enabled by default; allows OpenAI to use your code to improve their models.
Include environments: lets OpenAI learn from your Codex environment settings.

Wrapping Up

Out of the box, ChatGPT Codex doesn't support executing PHP code, which limits its potential. But with the right setup, you can unlock full task automation in Symfony and PHP projects.

Once configured, Codex becomes more than a code reviewer: it becomes a real coding assistant that understands your stack and validates its own changes.

Try it out and leave your comments if you have any question so I can update this article.

✨ If you enjoyed this or any of my other articles and want to support my work, consider sponsoring me on GitHub 🙌

Is Your CSS Logical?

Javier Eguiluz — Tue, 26 Nov 2024 07:54:56 +0000

Take a look at this CSS snippet. What's wrong with it?

p {
    border-top: 2px solid red;
    margin-left: 2rem;
    width: 80ch;
}

Depending on your website audience, there are either zero or three errors. Before explaining which errors, let's set some context.

A Matter of Perspective

When you step onto a boat, you won't hear terms like "left" or "right". That's because the left/right sides of a boat depend on the observer's perspective. Instead, they use "port" and "starboard", unambigous terms that always refer to the same sides of the boat, regardless of your position or the speaker's:

Image created by Pearson Scott Foresman and released into the public domain. Source

The same principle applies to anatomical terms of location, which allow doctors and veterinarians to describe the location of body parts unambiguously, regardless of the relative position of the patient or doctor.

CSS Internationalization

If your web applications are used globally, you must design them to adapt to various linguistic needs. For example, languages like English and Spanish are written from left-to-right (LTR); Arabic and Hebrew are written from right-to-left (RTL); Mongolian and traditional Japanese are written from top to bottom.

So, when you use a CSS declaration like this:

p {
    margin-left: 2rem;
}

Do you mean that (1) you want to add space to the physical left of the paragraph, or (2) you want to add some space before the content starts? For a fully internationalized UI, the correct answer is always (2).

The Logical Solution

You could create separate stylesheets for LTR and RTL languages and load them conditionally. There are even tools like the webpack-rtl plugin that can generate automatically a RTL stylesheet based on the original LTR stylesheet.

However, the best solution would be to apply CSS styles conditionally like this:

p {
    if writing is left-to-right:
        margin-left: 2rem;
    elseif writing is right-to-left:
        margin-right: 2rem;
    elseif writing is top-to-bottom:
        margin-top: 2rem;
    endif
}

You can do this in CSS but with a much simpler syntax:

p {
    margin-inline-start: 2rem;
}

This margin-inline-start property is a logical CSS property which dynamically adjusts based on the user's writing direction. Logical properties work similarly to the port/starboard analogy; they describe layout in a way that is unambiguous across different writing systems.

Logical properties define layout directions using these two terms:

inline: parallel to the flow of text within a line.
block: perpendicular to the flow of text within a line.

This illustration shows the logical positions compared to the physical locations for all the writing modes supported by CSS:

Using logical properties, the initial example shown at the beginning of this article can be rewritten like this:

p {
    border-block-start: 2px solid red;
    margin-inline-start: 2rem;
    inline-size: 80ch;
}

Updating an existing CSS stylesheet to use logical properties might seem daunting at first. However, most of the work involves simply replacing left with inline-start, right with inline-end, top with block-start, and bottom with block-end. Some properties require different renaming; for example, border-bottom-left-radius becomes border-end-start-radius, height becomes block-size, etc.

The effort is well worth it, as this is a future-proof solution that ensures your website is accessible to everyone. For instance, the EasyAdmin project, which I'm involved in, has already updated its stylesheets to use logical properties.

Logical Properties Reference

Here's a reference table of all the logical properties to help you update your own projects:

Physical Property	Logical Property
`border-bottom`	`border-block-end`
`border-bottom-color`	`border-block-end-color`
`border-bottom-left-radius`	`border-end-start-radius`
`border-bottom-right-radius`	`border-end-end-radius`
`border-bottom-style`	`border-block-end-style`
`border-bottom-width`	`border-block-end-width`
`border-left`	`border-inline-start`
`border-left-color`	`border-inline-start-color`
`border-left-style`	`border-inline-start-style`
`border-left-width`	`border-inline-start-width`
`border-right`	`border-inline-end`
`border-right-color`	`border-inline-end-color`
`border-right-style`	`border-inline-end-style`
`border-right-width`	`border-inline-end-width`
`border-top`	`border-block-start`
`border-top-color`	`border-block-start-color`
`border-top-left-radius`	`border-start-start-radius`
`border-top-right-radius`	`border-start-end-radius`
`border-top-style`	`border-block-start-style`
`border-top-width`	`border-block-start-width`
`bottom`	`inset-block-end`
`container-intrinsic-height`	`contain-intrinsic-block-size`
`container-intrinsic-width`	`contain-intrinsic-inline-size`
`height`	`block-size`
`left`	`inset-inline-start`
`margin-bottom`	`margin-block-end`
`margin-left`	`margin-inline-start`
`margin-right`	`margin-inline-end`
`margin-top`	`margin-block-start`
`max-height`	`max-block-size`
`max-width`	`max-inline-size`
`min-height`	`min-block-size`
`min-width`	`min-inline-size`
`overscroll-behavior-x`	`overscroll-behavior-inline`
`overscroll-behavior-y`	`overscroll-behavior-block`
`overflow-x`	`overflow-inline`
`overflow-y`	`overflow-block`
`padding-bottom`	`padding-block-end`
`padding-left`	`padding-inline-start`
`padding-right`	`padding-inline-end`
`padding-top`	`padding-block-start`
`right`	`inset-inline-end`
`top`	`inset-block-start`
`width`	`inline-size`

Learn More

MDN: CSS logical properties and values

✨ If you enjoyed this or my other articles and want to support my work, consider sponsoring me on GitHub 🙌

New in EasyAdmin: Pretty URLs

Javier Eguiluz — Sun, 03 Nov 2024 12:01:19 +0000

The most requested feature for EasyAdmin has just arrived in version 4.14.0.

Since day one, EasyAdmin has used query string parameters to pass the necessary
information for rendering backend pages. This approach created URLs like:

https://example.com/admin?crudAction=edit&crudControllerFqcn=App%5CController%5CAdmin%5CPostCrudController&entityId=3874

While this URL format is ugly, it's functional. Some browsers, like Safari, even
hide most of the URL by default, showing only the hostname, so the impact on
end-users is minimal.

However, starting today, EasyAdmin generates cleaner URLs that look like this:

https://example.com/admin/post/3874/edit

In addition to being the most requested feature, we implemented this change for
two main reasons:

The old, ugly URL leaks internal details about the application, like the namespace of the CRUD controller. This is typically fine, as most backends aren't sharing URLs with external users, but it's not ideal.
Building these ugly URLs with the AdminUrlGenerator class is cumbersome. Now, you can use route names like admin_post_edit or admin_user_index and rely on Symfony's built-in features to generate the URLs.

How to Enable Pretty URLs?

This feature has been designed to work seamlessly with current applications. If
you don't make any changes, the application will still use ugly URLs, and
everything will continue to work as before.

If you'd like to start using pretty URLs now, create the following configuration
file in your application:

# config/routes/easyadmin.yaml
easyadmin:
    resource: .
    type: easyadmin.routes

This configuration enables a custom Symfony route loader, a class that
automatically generates routes in your application. Clear the cache (by running
php bin/console cache:clear or rm -fr var/cache/*) and the application will
begin using pretty URLs. Run the following command to see all the newly generated
routes:

php bin/console debug:router

You can now also update your code to stop building backend URLs with the
AdminUrlGenerator utility and use the new route names directly:

// Before:
$this->adminUrlGenerator()
    // this is only needed if you have ore than 1 dashboard
    ->setDashboard(SomeDashboardController::class)
    ->setController(ProductCrudController::class)
    ->setAction('detail')
    ->setEntityId(321)
    ->generateUrl();

// After:
$this->router->generate('admin_product_detail', ['entityId' => 321]);

The generated routes are composed of three parts: dashboard + crud + action. Each
of these can be customized using the new PHP attributes #[AdminDashboard],
#[AdminCrud], and #[AdminAction]. Read the docs to learn more.

Pretty URLs are still optional in EasyAdmin 4.x versions, but ugly URLs are now
deprecated. Starting in EasyAdmin 5.x (planned for release soon), pretty URLs
will be required.

✨ If you enjoyed this feature and want to see more like it, consider
sponsoring the EasyAdmin project 🙌💡

Generating deterministic UUIDs from arbitrary strings with Symfony

Javier Eguiluz — Wed, 26 Jun 2024 09:26:00 +0000

UUIDs are 128-bit numbers used to identify items uniquely. You've probably seen or used UUIDs in your applications before. They are usually represented as an hexadecimal value with the format 8-4-4-4-12 (e.g. 6ba7b814-9dad-11d1-80b4-00c04fd430c8).

Most developers use random UUIDs, which don't contain any information about where or when they were generated. These are technically called UUIDv4 and they are one of the eight different types of UUIDs available.

Symfony provides the UID component to generate UUIDs:

use Symfony\Component\Uid\Uuid;

// $uuid is an instance of Symfony\Component\Uid\UuidV4
// and its value is a random UUID
$uuid = Uuid::v4();

In this article, we'll focus on UUIDv5, which generates UUIDs based on a name and a namespace. Before diving into it, let's explain the problem they solve.

Imagine that you work on an e-commerce application and need to include the product ID in some URLs (e.g. /show/{productId}/{productSlug}). The product IDs are unique within your application, but it's internal information and you are not comfortable sharing it publicly.

If the product IDs are numbers, then you can use tools like Sqids (formerly known as Hashids) to generate deterministic (and reversible) unique IDs from a given number(s). However, this problem can also be solved with UUIDs.

UUIDv5 generate UUIDs whose contents are based on a given name (any arbitrary string) and a namespace. The namespace is used to ensure that all the names that belong to it are unique within that namespace. The spec defines a few standard namespaces (for generating UUIDs based on URLs, DNS entries, etc.) but you can use any other UUID (e.g. a random UUID) as the namespace:

use Symfony\Component\Uid\Uuid;
// ...

final readonly class ProductHandler
{
    // this value was generated randomly using Uuid::v4()
    private const string UUID_NAMESPACE = '8be5ecb9-1eba-4927-b4d9-73eaa98f8b65';

    // ...

    public function setUuid(Product $product): void
    {
        $namespace = Uuid::fromString(self::UUID_NAMESPACE);
        $product->setUuid(Uuid::v5($namespace, $this->getProductId());
        // e.g. if the productId is 'acme-1234',
        // the generated UUID is 'eacc432f-a7c1-5750-8f9f-9d69cb287987'
    }
}

UUIDv5 roughly performs sha1($namespace.$name) when generating values. This way, the generated UUIDs are not reversible (or guessable by external actors) and are deterministic (they always generate the same UUID for a given string).

If you want to make the public IDs shorter, use any of the methods provided by Symfony to convert UUIDs:

$namespaceAsString = '8be5ecb9-1eba-4927-b4d9-73eaa98f8b65';
$namespace = Uuid::fromString($namespaceAsString);

$name = 'acme-1234';
$uuid = Uuid::v5($namespace, $name);
// (string) $uuid = 'eacc432f-a7c1-5750-8f9f-9d69cb287987'

$shortUuid = $uuid->toBase58();
// $shortUuid = 'VzeJE1ydqWXpJJMwnavj3t'

The UUID spec defines many other types of UUIDs which fit different scenarios. There's even a UUIDv3 which is the same as UUIDv5 but uses md5 hashes instead of sha1. That's why UUIDv5 is preferred over UUIDv3.

Check out the Symfony docs about the different types of UUIDs to know more about them.

DEV Community: Javier Eguiluz

A Simple Pattern That Makes Sorting in PHP Faster

The three step pattern

The array_multisort() trick

A real-world case in Symfony

When to apply this technique

Claude Code for Symfony and PHP: The Setup That Actually Works

Usage

CLAUDE.md / AGENTS.md

Plan, Plan, Plan

Creating a Good Plan

Context

When Things Go Wrong

Plugins, Skills, Commands, Agents, Hooks

Sub-Agents

Global Settings

Next Steps

EasyAdmin 5.0: A New Foundation for Your Admin Backends

What Changed in 5.0

Pretty URLs

Dashboard Definition via Attribute

Embedding Symfony Controllers in Your Backend

Action Improvements

Autocomplete Customization

Custom Icon Sets

New Twig Components

Upgrading to 5.x

Trying EasyAdmin for the First Time

New in EasyAdmin 4.28: New Filters, Better Autocomplete, CSP, and Smarter Actions

Clickable Rows in the Index Page

Content Security Policy (CSP) Support

Five New Filters

Confirmation for Any Action

Preferred Choices

Autocomplete Customization

New in EasyAdmin: Custom Admin Routes

The AdminRoute Attribute

Composing Routes

Multi-Dashboard Control

Recap

Reusing SVG Icons for Faster Pages

The Problem: Too Many SVG Images

The Solution: SVG <use> Element

Legacy SVG Attributes

Styling of Reused SVG Images

Creating SVG Sprites

Key Takeaways

How to Make ChatGPT Codex Work with PHP and Symfony

Setting Up the Environment

Setup Script

Private Composer Packages

Using Databases

General Settings

Providing Metadata to Agents

Security and Privacy Recommendations

Wrapping Up

Is Your CSS Logical?

A Matter of Perspective

CSS Internationalization

The Logical Solution

Logical Properties Reference

Learn More

New in EasyAdmin: Pretty URLs

How to Enable Pretty URLs?

Generating deterministic UUIDs from arbitrary strings with Symfony

The `array_multisort()` trick

The `AdminRoute` Attribute

The Solution: SVG `<use>` Element