Forem: david duymelinck

My 2 cents on the Spatie guidelines agent skills

david duymelinck — Sat, 18 Apr 2026 06:41:37 +0000

I saw on Laravel-news a post about Spatie guidelines. Because other peoples guidelines are always a chance to learn something new, I thought it would be fun to read through them and provide comments.
I'm going to focus on the PHP/Laravel guidelines.

The PHP agent skill is split up in two files where most of the information in SKILL.md is repeated in spatie-laravel-php-guidelines.md. This seems a waste of tokens.

Use camelCase for non-public-facing strings

I assume the model(s) don't always follow that rule of PSR-12. It is not explicitly mentioned, so it can only be inferred by reading the examples.

Use short nullable notation: ?string not string|null

This is explicitly mentioned in PSR-12.

I understand the reasoning behind the rule because of the other PHP functionality using the question mark to signal null like $client?->address and $client ?? new Client().

My own take is to use the long notation to be consistent with the cases where null is a part of three or more options, string|int|null. It is one less place where your mind needs to make the switch that a question mark means null.

Use typed properties, not docblocks

I'm all for documenting using code. It is one of the reasons I'm against using array shapes in docblocks. When the shape is that important use a type.

Use constructor property promotion when all properties can be promoted

With the existence of a variable arguments list this is a bit of a tricky guideline.
A variable arguments list is a more solid way to pass input than an array.
So when a model follows that rule, all none variable properties aren't going to get promoted?

Document iterables with generics:
/** @return Collection<int, User> */

A better way would be to create a specific collection type for the Eloquent model output. It used to be more (too much?) effort but with code generation it is not going to matter.

Always import classnames in docblocks; never use fully qualified names:

This is good advice!

Happy path last: handle error conditions first, success case last

While it is a good rule, it is not always possible.

if (! $user) {
    return null;
}

if (! $user->isActive()) {
    return null;
}

In the same code block with ternary examples this looks very drawn out.

if($user?->isActive() === null) {
  return null;
}

I understand it is an example of multiple if's over multiple branches. But reducing the if's in a function is also a good goal.

// Ternary instead of else
$condition
    ? $this->doSomething()
    : $this->doSomethingElse();

For me this looks like using match when it is better to use switch.
While the ternary operator is not explicitly bound to a return. The PHP documentation suggests that is the most likely use case.
Else isn't that bad that it needs to be avoided by any means.

Use tuple notation: [Controller::class, 'method']

This assumes the controller is very likely to have constructor dependency injection, while it is better to use method dependency injection.
The method dependency injection makes it also possible to use new Controller()->method(...) which is more robust than the method as a string.
In the few cases constructor dependency injection is the best solution, the tuple notation can be used.

Stick to CRUD methods (index, create, store, show, edit, update, destroy)

I understand the rule from a consistency perspective. On the other hand it is very restrictive.
When the controllers are only CRUD vessels, is Laravel the right solution?

Use config() helper, avoid env() outside config files

Solid rule!

Put output before processing an item (easier debugging):

$items->each(function (Item $item) {
    $this->info("Processing item id `{$item->id}`...");
    $this->processItem($item);
});

$this->comment("Processed {$items->count()} items.");

It assumes there is a build-in way to add debug information. As far as I know that is not default.

Class constants also use PascalCase:

This is not compatible with PSR-2.

Conclusion

An agent skill is hard to get right because different models can interpret information in another way.
The skills will work with the model(s) Spatie is using, and that is why some of the guidelines may look a bit out of place.

Like with any other guidelines, they are opinionated. And because we all have our own opinions there are parts where we don't agree.
But the nice thing about agent skills is that they are easy to change to your own liking.

Are routing files a thing of the past in PHP?

david duymelinck — Fri, 17 Apr 2026 03:42:09 +0000

The one link that got my attention in this weeks The Weekly Drop was PHP Attributes Can Be Used for Route Definition and Discovery

As a long time user of Symfony this feels like Drupal is catching up, and I'm all for it. The Drupal developers are really embracing attributes. The first time I noticed it is when they started using it for hooks.

Next to the Route attribute the change also allows the use of invokable controllers. From the Drupal article:

namespace Drupal\router_test\Controller;

use Drupal\Core\Controller\ControllerBase;
use Symfony\Component\Routing\Annotation\Route;

/**
 * Test controller.
 */
#[Route(
  '/test_class_attribute',
  'test_class_attribute',
  requirements: ['_access' => 'TRUE']
)]
class TestClassAttribute extends ControllerBase {

  /**
   * Provides test content.
   */
  public function __invoke() {
    return ['#markup' => 'Testing __invoke() with a Route attribute on the class'];
  }

}

I see quite a few people using single route controllers. And to me it doesn't make sense having to name a method when PHP provides a way to invoke a class with a single public method.

With Symfony, Tempest and now Drupal offering attribute based routing, it looks like Laravel is the biggest framework that doesn't uses attributes for routing.
Laravel already has middleware attributes. This is one of the parts of the routing that is heavily used.

There is a third party package that makes it possible to use attributes for routing.
And you can use it with the Laravel middleware attributes.
This shows it could be a core feature.

It would be amazing when the frameworks could create a standard for the routing attributes. This would make it possible to use controllers in multiple PHP solutions with a few changes or a framework discovery feature.

What is your route attribute use? When you use a router config file, what is stopping you from using attributes?

future PHP: partial function application

david duymelinck — Wed, 15 Apr 2026 13:06:52 +0000

Have you ever written something like this:

function a(int $one, int $two) {
  return $one + $two;
}

function addFive(int $one) {
   return a($one, 5);
}
// or
$addFive = fn(int $one) => a($one, 5);

With partial function application this will reduce to $addFive = a(?, 5);.

Nested functions will be a bit more readable.

$slug = fn(str $str) => strtolower(implode('-',str_word_count($str,1)));
// versus
$slug = strtolower(implode('-',word_count(?,1)));

And a great benefit will be seen in pipe operator code.

$slug = $str
|> (fn($str) => str_word_count($str,1))
|> (fn($str) => implode('-',$str))
|> (fn($str) => strtolower($str));
// versus
$slug = $str |> str_word_count(?,1) |> implode('-', ?) |> strtolower(?);

An extra benefit of the partial function application implementation is that it adds the static keyword to the the closure it creates.
For the people that don't know, adding the static keyword improves performance.

Beside the question mark, an elipsis is also an partial function application placeholder. This is most beneficial for functions or methods with at least three arguments.

function a(int $one, int $two, int $three) {
  return $one + $two + $three;
}

$minimumFive = a(5, ...);
// alternative
$mimimumFive = a(5, ?, ?);

$minimumFive(6,7);

On the one hand having the question marks makes it clear what the signature of the underlying function is. On the other hand developers are lazy typists.

If you want more information read the RFC. This will be in PHP 8.6.

I think additions like this make PHP a fun language to work with.

Anyone else noticed the changes on the site? - A reader time graph in the stats - A pill design for the tabs above the feed. The reader graph is humbling on some of the posts, but I tink it is a great addition

david duymelinck — Tue, 14 Apr 2026 05:53:54 +0000

Yasumi alternative

david duymelinck — Sun, 12 Apr 2026 08:49:45 +0000

While I did my deep dive on PHP dates I found the Yasumi library.

I like the library a lot but for me it came with a few to many restrictions.
So instead of improving the library I started my own based on the work the Yasumi already did.

The restrictions that made start my own library

Yasumi is focused on holidays. With holidays most people think of days were they don't need to work.
There are a lot of day in the year that have a meaning for people without the no-work connotation. And that is one of the aspects I wanted in a dates library.

Yasumi also focuses on days while there are also periods that have meaning. I'm thinking of lent for Christians, Ramadam for Muslims. I do think those have a place in a library too.

On the technical side I found it strange you can only select a single provider. What if you want the christmas of multiple countries?

$usa = Yasumi\Yasumi::create('USA', (int) date('Y'));
$canada = Yasumi\Yasumi::create('Canada', (int) date('Y'));

$christmasses = [
   $usa->getHoliday('christmas'),
   $canada->getHoliday('christmas'),
];

It feels excessive to instantiate multiple classes.

While I browsed the code I found that provider relations are hardcoded.
You can't get the Australian capital territory dates without the Australian dates.

So the design of the alternative library already has a few points to explore.

Designing the library

The providers are mostly geographical, so it makes sense to put the dates in a Region.
There are also other providers like ChristianHolidays and CommonHolidays. Christians live on earth so with a bit of bending the definition of a region a religion can be a type of a region.
For common holidays that seems more like a helper class than an actual provider people are going to use. So for my library I will not create it.

A Region should stand alone, and should have the option to call related regions.
A Region day or period should be unique.
A Region should have a method to fetch the dates with a filtering option.

A Day should contain a Region identification, a date and one or more significance types.

A Period is a collection of Day objects with the meta information about the successiveness of the days.
To make it easier to work with the Period there should be first and last item methods.

There should be a class that makes it easier to work with multiple Region object at once.

Status of the library

After four days of thinking and letting AI do the boring parts I have pushed the first commits on the repository.

As you can see the Region implementations are enumns.
An enum made more sense than a class because all Region dates are finite, and an enum is meant to group finite constants.
An enum is not extendable, so that restriction leaves no room for hardcoded relations.
I added an All case to each enum to make it more contextual when using the methods. USA::All->get((int) date('Y')); creates less confusion than USA::IndependenceDay->get((int) date('Y'));

Like Yasumi all regions have the dates in their timezone. For the religious regions the timezone is UTC, because that made the most sense.

I already provided a multiple regions class, but for now that is more a prove of concept than a workable item.

Next steps

The effort of Sacha Telgenhof and the other Yasumi contributers is enormous. And I wanted to have all the dates from Yasumi before I released something there are still parts were the library is still a mess.

One of the things I only decided yesterday is that when a Day has a holiday that is not the day itself, due to falling in an weekend or being pushed later by another holiday, it should be a part of the Day instance instead of being another Day.
The Yasumi library filters those dates by removing the HolidaySubsitute instances. I think that way of working is wastefull because most of the information is the same for the two instances.
So that will require a massive rewrite.

Another decision I made to be fast is to have a NotableTypeCollection as a property of Day, because I wanted the option to have one or more significance bound to a date. For example Christmas is in most western countries a Christian event but also an official holiday. For me one is not less important than than the other.
The Yasumi library has an TYPE_OTHER significance option, and that doesn't sit right by me.
I want the dates to have all their most specified significance.
So that is going to be a research work to get it right as best as possible. I have no doubt I'm going to make mistakes. But that is why I build the library in public.

What I learned from the Yasumi library

Use DateImmutable, I seen too many cloned temporary variables instances to think DateTime is the best way to define a date.

South Korea is the country with the most rules involving dates.

There are a lot of weird rules for holidays.

There are quite a few countries that don't have Saturday and Sunday as their weekend.

It was fun to really get into all that information, and I will continue to expand my knowledge working on my library.

Dates and periods in PHP

david duymelinck — Wed, 08 Apr 2026 11:01:54 +0000

After seeing the following post

Recca Tsai

Apr 6

League Period: A Swiss Army Knife for Time Intervals in PHP

#backend #opensource #php #programming

Comments 1

4 min read

The deep dive instinct in me wanted to explore more about PHP date handling.

The thing that put me over the edge to start it is easter_date. Especially the workaround for the timezone.

The basics

I hope everyone has moved away from most of the date/time functions and uses the DateTime or even better the DateTimeImmutable classes.

$year = 2026;
$month = 4;

// old
$lastDayOfMonth = date('d', strtotime("last day of $year-$month"));
// new
$lastDayOfMonth = new DateTimeImmutable("last day of $year-$month")->format('d');
// alternative
$lastDayOfMonth = cal_days_in_month(CAL_GREGORIAN, $month, $year);

The alternative function comes from the calendar extension. Most of the times this extension is added to PHP. And it provides a few useful functions, like easter_day I mentioned before. But be aware that it could be missing.

To manipulate the date there are the add and sub methods.

$year = 2026;
$month = 4;

$firstDayOfMonth = new DateTimeImmutable("$year-$month-1");
$lastDayOfMonth = $firstDayOfMonth->add(DateInterval::createFromDateString("1 month - 1 day"));

The example is a long way to get the last day of the month. It does introduce the DateInterval class.

The DateInterval class is useful when periods come into play.

$year = 2026;
$month = 4;

$firstDate = new DateTimeImmutable("$year-$month-23")->add(new DateInterval('P1M'));
$secondDate = new DateTimeImmutable("$year-$month-14");

echo $firstDate->diff($secondDate)->format('%r%a') . ' days between both dates'; 
// -39 days between both dates

More advanced

The Period library that started my curiosity provides a nicer way of working with periods, but PHP also provides a DatePeriod class.

$year = 2026;
$month = 4;
// library
$period = Period::fromMonth($year, $month);

$period->startDate;
$period->endDate;
$period->dateInterval();

foreach ($period->dateRangeForward(new DateInterval('P1D')) as $datepoint) {
    $datepoint->format('Y-m-d');
}

//  PHP
$period = $period = new DatePeriod(new DateTimeImmutable("$year-$month-1"), new DateInterval('P1D'), new DateTimeImmutable("last day of $year-$month"));

$period->start;
$period->end;
$period->interval;

foreach($period as $datepoint) {
    $datepoint->format('Y-m-d');
}

Where the Period library shines is by providing shortcuts and comparison functions.
But if you don't need all those functions a Dateperiod child class can make the code easier to work with.

class ComparableDatePeriod extends DatePeriod
{
    public static function createMonth(int $year, int $month): static {
        return new static(new DateTimeImmutable("$year-$month-1"), new DateInterval('P1D'), new DateTimeImmutable("last day of $year-$month"));
    }

    public static function withInterval(DateTimeImmutable $start, DateInterval $interval): static  {
        return new static($start, new DateInterval('P1D'), $start->add($interval));
    }

    public function containsDay(DateTimeImmutable $day) : bool {
        foreach($this as $d) {
            if($d == $day) {
                return true;
            }
        }

        return false;
    }

    public function containsPeriod(ComparableDatePeriod $period) {
        $hasBeginAndEnd = 0;

        foreach($this as $day) {
            if($day == $period->start) {
                $hasBeginAndEnd++;
            }

            if($day == $period->end) {
                $hasBeginAndEnd++;
            }
        }

        return $hasBeginAndEnd == 2;
    }
}


$year = 2026;
$month = 4;
$period = ComparableDatePeriod::createMonth($year, $month);

$period->containsDay(new DateTimeImmutable("$year-5-1"));

$period->containsPeriod(ComparableDatePeriod::withInterval(new DateTimeImmutable("$year-$month-4"), new DateInterval('P1M')));

Conclusion

The relative formats in PHP are very powerful because they not only provide a more human way of setting the date, but it also comes with date calculations.

Next time people suggest the Carbon library as the default, think of what the application needs before adding it.

Creating a Symfony Tui application

david duymelinck — Mon, 06 Apr 2026 06:28:33 +0000

After my first post about Symfony Tui, I really wanted to kick the tires of the component.

The idea

Non technical people don't like it when applications give them too much rules. And one of the biggest offenders for me are markdown driven applications.
So I wanted to make an application where they can add a directory where the markdown files are stored.

For the interface there are two parts, the filesystem part and the editor part.
The filesystem part has a filetree and an option to add new files. A sub function of the filetree is the possibility to delete a file.
The editor part has two tabs; markdown and frontmatter. It is possible to switch between them. And by pressing return the content of both editors is saved to the selected file in the filetree.

The good

The command does not have a lot of content, because I could extract the TUI code to a separate class.

Working with containers feels like divitis, but I would have never suspected that it would one day feel like a good thing.

$markdownTab = new TextWidget('Markdown');
$markdownTab->setId(self::MARKDOWN_TAB_ID);
$markdownTab->addStyleClass('bold');
$frontmatterTab = new TextWidget('Frontmatter')->setId(self::FRONTMATTER_TAB_ID);

$tabs = new ContainerWidget();
$tabs->setStyleClasses(['flex-row', 'gap-1']);
$tabs->setId(self::CONTENT_TABS_ID);
$tabs->add($markdownTab);
$tabs->add($frontmatterTab);

$markdownEditor = new EditorWidget()->setId(self::MARKDOWN_EDITOR_ID);
$markdownEditor->onSubmit($this->saveEditorsToFile(...));
$frontmatterEditor = new EditorWidget()->setId(self::FRONTMATTER_EDITOR_ID);
$frontmatterEditor->setStyleClasses(['hidden']);
$frontmatterEditor->onSubmit($this->saveEditorsToFile(...));

$editors = new ContainerWidget();
$editors->setId(self::CONTENT_EDITORS_ID);
$editors->add($markdownEditor);
$editors->add($frontmatterEditor);

$content = new ContainerWidget();
$content->setId(self::CONTENT_ID);
$content->setStyleClasses(['flex-col', 'gap-1']);
$content->add($tabs);
$content->add($editors);

This is my poor mans attempt of a tabs widget, which is coming in a future Tui component PR.

The style classes are working because the Tui component comes with a TailwindStylesheet. To use the class you can add it to the Tui constructor as an argument or use the addStyleSheet method.
As I mentioned in my previous post if you like the class extend it and add your own rules, to have the best of both worlds.

Having the option to set ids for each widget is great. As you can see in the example I'm using class constants to keep them organized.

The on method and the more specified onX methods make it easy to add widget and TUI behavior.

The bad

Because the TUI runs in an eventloop some of the actions are going to require the need to dispatch them in order to see the change instantly.
As far as I figured it out all the methods from the widgets that can dispatch are private.

In my case I wanted to update the filetree as soon as a new file is submitted or when a file got deleted.

$newFile = new InputWidget();
$newFile->setId(self::NEW_FILE_ID);
$newFile->setPrompt('New File (can contain path): ');
$newFile->onSubmit(function(SubmitEvent $event) {
    if($event->isEmpty()) {
        return;
    }

    $input = $event->getValue();

    if(!str_ends_with($input, '.md')) {
       $input .=  '.md';
    }

    touch($this->source . '/' . $input);

    $event->getTarget()->setValue('');

    $sourceFiles = $this->tui->getById(self::SOURCE_FILES_ID);
    $sourceFiles->onFileAction();
    $this->tui->handleInput(self::NAV_SOURCE_FILES);
});

I needed to create a child class of SelectListWidget to add the onFileAction method.

public function onFileAction() : void
{
    $items = $this->getSourceFiles();

    $this->myItems = $items;
    $this->myItemsCount = count($this->myItems);

    $this->setItems($items);

    $selectedItem = $this->myItems[0] ?? null;
    if (null !== $selectedItem) {
       $this->dispatch(new SelectionChangeEvent($this, $selectedItem));
    }
}

As you can see there is more going in the method than just a dispatch.
But it feels like there is an easier way to get it working.
Of course there is also the possibility I'm just doing it wrong.

The ugly

I don't think it is completely the blame of the Tui component but shortcuts are the straw that broke the camel's back for me.

I'm using PHPStorm and a WSL debian terminal to manually test my application.

I needed to add a whole slew of shortcuts as a line in the command just to remember them myself.

Shortcuts: ctrl+b -> filetree (return to display content, ctrl+i -> delete file) ; ctrl+d -> new file (return to create) ; ctrl+e -> markdown ; ctrl+r -> frontmatter (both editors return to save) ; ctrl+j -> quit.'

I wanted similar shortcuts close to each other, or in the case of ctrl+d and ctrl+b look alike.

And then I started testing the editors.

My first eyebrow raise came from using ctrl+k to focus the frontmatter editor. It did focus but it also cleared the content.
To be honest I only had a single line of frontmatter.
It wasn't until I tried ctrl+m to figure out the editor also uses the ctrl+k shortcut.

My next test was adding more lines. Now that I was aware of the editor shortcuts I found out it is shift+return. That doesn't work for me.
So I tried other keys in combination with return, and If discovered there is a combination that deletes the selected file in the filetree while the editor is the focused widget. The shortcut for deleting a file is ctrl+i, and I wasn't even close pressing i.

Conclusion

Frontend is hard with all those limitations, that is why I rather do backend work.
But it was a fun time trying to create something with a new toy.

The full code is on Github. I didn't want to make it a repository because it is just for now code.
There are many parts left undeveloped like creating files in a directory and showing the error and success messages.

While Javascript and Python based CLI tools are ruling the world, I do think with the Tui component PHP has found an answer.

Exploring the Symfony Tui component

david duymelinck — Sat, 04 Apr 2026 16:35:27 +0000

I had seen the Symfony Tui component announcement, but I just got the time to start to explore it.

Setup

To explore the component fast I checked out the PR.
Added "App\\" : "src/App" to composer.json.
Created a command, TuiTestCommand, in the App directory, and a bin/console file with a console application and the command.

In the following sections I'm going to take baby steps to understand how the component works.

Returning a text

The standard way to return a text is $output->writeln('Hello world!');

To do this with the Tui component this is:

use Symfony\Component\Tui\Tui;
use Symfony\Component\Tui\Widget\TextWidget;

// in the command
$tui = new Tui();

$tui->add(new TextWidget('Hello World!'));

$tui->onTick(fn() => $tui->stop());

$tui->run();

Because the component is meant to create rich interactive experiences it uses a bit more code to make it run.

You can look at the Tui class as an agent. You can give it rules and when called it runs those rules.
Do I have AI brain? Before AI I would probably bring up the Node event loop.

Once you call the run method, the loop starts.
So if the stop method is never called the only possibility to get out of the loop is closing the CLI.
In an actual application getting out of the loop will be less janky than in this example.

You could create a bin/MyAwesomeCodingAgent by setting the Tui code containing command as the default.

Styled text

The default way to add styling to a text is by adding faux tags.

$output->writeln('<fg=red;options=bold>Hello World!</>');

In the Tui component the way of working with CSS is mimicked. Underneath it still uses the suffix and prefix codes, but that is not our problem anymore.

use Symfony\Component\Tui\Style\Style;

// in command

$redBoldStyle = new Style()->withColor('red')->withBold();

$text = new TextWidget('Hello World!');
$text->setStyle($redBoldStyle);

This method is good for one-off cases. But when you want a bit more maintainability and consistency it is better to create a StyleSheet.

use Symfony\Component\Tui\Style\StyleSheet;

// in command

$stylesheet = new StyleSheet([
  '.red-bold' => new Style()->withColor('red')->withBold(true),
]);

$tui->addStyleSheet($stylesheet);

$text = new TextWidget('Hello World!');
$text->addStyleClass('red-bold');

For the purpose of the test I added the StyleSheet object to the command, but in an actual application I would create a SomeCommandStyleSheet or a BrandStyleSheet that contains all the possible styles. Or both, there is no reason they shouldn't be composable.

Input

The default of adding an input to a command is:

$helper = new QuestionHelper();
$question = new Question('Please enter your email: ','');
$question->setValidator(function ($answer) {
   if (trim($answer) == '') {
      throw new \RuntimeException('Email address cannot be empty');
   }
   return $answer;
});

$email = $helper->ask($input, $output, $question);

$output->writeln("Email submitted: {$email}");

Every time the user hits return without a value the question is being re-displayed together with the error text.

$tui = new Tui();

$emailInput = new InputWidget();
$emailInput->setPrompt('Please enter your email: ');
$emailInput->on(SubmitEvent::class, function (SubmitEvent $event) use ($tui, $output) {
    $email = $event->getValue();
    $statusText = $tui->getById('status-text');

    if ($event->isEmpty()) {
        $statusText->setText('Email address cannot be empty.');
    } else {
        $tui->stop();

        $output->writeln("Email submitted: {$email}");
    }
});

$tui->add($emailInput);

$statusText = new TextWidget('');
$statusText->setId('status-text');
$statusText->setStyle(new Style()->withColor('red')->withBold());

$tui->add($statusText);

$tui->run();

The thing that became clear to me when creating the input code is that the InputInterface and OutputInterface are not tied to the Tui widgets like the helper classes we got used to.

Because of the widgets is feels more like building an HTML page than working with a text interface. So I'm very exited about the upcoming PR that makes it possible to use Twig templates.

The on method brings me back to the jQuery days.
And because of the event binding the input will only take the two lines initial lines on the screen, which is better that with the helper validation.

I barely scratched the surface, but I didn't want to make the post too long. Let me know if you want to see more of the Tui component.

Agentic PHPUnit output

david duymelinck — Fri, 03 Apr 2026 06:16:07 +0000

I was made a aware of PAO. And while it think it is a good tool I think we can do better by making it more useful for an LLM.

The package has options for PHPUnit, Pest and ParaTest. I'm only going to focus on PHPUnit, version 12 in particular.

The setup

PHPUnit has an option to add extensions. The best way to let PHPUnit know your extension is in the phpunit.xml file.

<extensions>
    <bootstrap class="Tests\Extensions\AgentAwareOutputExtension"/>
</extensions>

To detect when PHPunit is run inside an agent I used the shipfastlabs/agent-detector library (I saw it in PAO). This library uses well known config variables to detect multiple agents. Because I'm trying out Mistral Vibe now I added a new script to composer.json.

"test:agent": "AI_AGENT=1 vendor/bin/phpunit"

While PAO uses json as output, I want to use markdown.
From the documentation I got that it doesn't show the errors. Which strikes me as odd because you want your coding agent to be able to fix the failing tests, not? So that is on my todo list.

The code

In the PHPUnit I saw an example where the used a intermediate class to collect the needed data, so that is what I did.

class TestDataCollector
{
    public function __construct(
        public int $failed = 0,
        public int $passed = 0,
        public int $total = 0,
        public array $messages = [],
    )
    {}

    public function write() : void
    {
        $text = '# Test results'. PHP_EOL . PHP_EOL;
        $text .= '## Summary' . PHP_EOL. PHP_EOL;
        $text .= 'failed: ' . $this->failed . PHP_EOL;
        $text .= 'passed: ' . $this->passed . PHP_EOL;
        $text .= 'total: ' . $this->total . PHP_EOL;

        if(count($this->messages) > 0) {
            $text .=  PHP_EOL . '## Failed tests' . PHP_EOL. PHP_EOL;
            $text .= '| Test | Message |' . PHP_EOL;
            $text .= '| --- | --- |' . PHP_EOL;

            foreach($this->messages as $message) {
                $text .= '| ' . $message['test'].' | ' . $message['message'] . ' |' . PHP_EOL;
            }
        }


        fwrite(STDOUT, $text);
    }
}

In the constructor I setup all the properties I needed to for PHPUnit to manipulate them based on the status of the tests.

The write method is used to display the result of the tests.
I choose to use concatenation to make it easy to maintain.

Next up is the extension, the glue that holds the different parts together.

use AgentDetector\AgentDetector;
use PHPUnit\Runner\Extension\Extension;
use PHPUnit\Runner\Extension\Facade;
use PHPUnit\Runner\Extension\ParameterCollection;
use PHPUnit\TextUI\Configuration\Configuration;
use Tests\Extensions\Subscribers\FailSubsrciber;
use Tests\Extensions\Subscribers\ErrorSubscriber;
use Tests\Extensions\Subscribers\TestsDoneSubscriber;
use Tests\Extensions\Subscribers\PassSubsrciber;

class AgentAwareOutputExtension implements Extension
{
    public function bootstrap(Configuration $configuration, Facade $facade, ParameterCollection $parameters): void
    {
        if ($configuration->noOutput()) {
            return;
        }

        $agentDetector = new AgentDetector();

        if (!$agentDetector->detect()->isAgent) {
            return;
        }

        $facade->replaceOutput();
        $facade->replaceProgressOutput();
        $facade->replaceResultOutput();

        $testDataCollector = new TestDataCollector();

        $facade->registerSubscribers(
            new PassSubsrciber($testDataCollector),
            new FailSubscriber($testDataCollector),
            new ErrorSubscriber($testDataCollector),
            new TestsDoneSubscriber($testDataCollector),
        );
    }
}

A better way would be to have the extension in its own directory, but for the purpose of the test I kept the directory structure flatter.

The Extension has a single method bootstrap, which mirrors the configuration in phpunit.xml.

PHPUnit has a --no-output CLI option that is why the first lines in bootstrap exist.

The AgentDetector lines are, as you can guess, to create a guard when an AI agent is not detected.

The replace methods are a bit unfortunately named because they prevent the display of the default output.

PHPUnit has quite a few Subscriber interfaces for all the events that can happen. So it is up to us to pick the ones we need.

use PHPUnit\Event\Test\Passed;
use PHPUnit\Event\Test\PassedSubscriber;
use Tests\Extensions\TestDataCollector;

class PassSubsrciber implements PassedSubscriber
{

    public function __construct(private TestDataCollector $testDataCollector)
    {}

    public function notify(Passed $event): void
    {
        $this->testDataCollector->passed++;
        $this->testDataCollector->total++;
    }
}

Because I don't need much data you will see most subscribers have little content.

use PHPUnit\Event\Test\Failed;
use PHPUnit\Event\Test\FailedSubscriber;
use Tests\Extensions\TestDataCollector;

class FailSubscriber implements FailedSubscriber
{

    public function __construct(private TestDataCollector $testDataCollector)
    {}

    public function notify(Failed $event): void
    {
        $this->testDataCollector->failed++;
        $this->testDataCollector->total++;

        $this->testDataCollector->messages[] = [
          'test' => $event->test()->className().'::'.$event->test()->methodName(),
          'message' => $event->throwable()->message(),
        ];
    }
}

The main difference between this subscriber and the next one is that this catches the failed tests and the next one the PHP errors.

use PHPUnit\Event\Test\Errored;
use PHPUnit\Event\Test\ErroredSubscriber;
use Tests\Extensions\TestDataCollector;

class ErrorSubscriber implements ErroredSubscriber
{

    public function __construct(private TestDataCollector $testDataCollector)
    {}

    public function notify(Errored $event): void
    {
        $this->testDataCollector->failed++;
        $this->testDataCollector->total++;

        $this->testDataCollector->messages[] = [
            'test' => $event->test()->className().'::'.$event->test()->methodName(),
            'message' => $event->throwable()->message(),
        ];
    }
}

The last subscriber is where the output happens.

use PHPUnit\Event\TestRunner\Finished;
use PHPUnit\Event\TestRunner\FinishedSubscriber;
use Tests\Extensions\TestDataCollector;

class TestsDoneSubscriber implements FinishedSubscriber
{

    public function __construct(private TestDataCollector $testDataCollector)
    {}

    public function notify(Finished $event): void
    {
        $this->testDataCollector->write();
    }
}

And this can now give an example output of

# Test results

## Summary

failed: 1
passed: 24
total: 25

## Messages

| Test | Message |
| --- | --- |
| App\Tests\AnswerTest::testFail | Failed asserting that false is true. |

Conclusion

Even if you don't need to format the output for AI agents I think you now have a better idea of what is possible.

Don't just git worktree

david duymelinck — Sat, 28 Mar 2026 06:03:19 +0000

I saw with the 2026 update of Jetbrains PHPStorm they are in on the git worktree hype.

I understand that it is a version control feature that creates less friction when there are multiple agents running and changing code.

The thing I don't understand is why would you think it is a great idea to let multiple agents change the same code parts?
If you are in charge of a team isn't it the first thing to divide the tasks so that they are isolated?
When they are not isolated isn't that a recipe for merge conflicts?

AI development feels like knowing to walk for years, and suddenly forgetting to do it because you can drive a car now.

The time animals could talk

Before AI exploded there were, and still are, many people that favored thunk based development. The main goal is to have less branches and if there are branches they should be short lived.

While I do think it is a great concept, like any other concept the usage depends on the conditions.
I have been in situations where clients asked for features and forget about them for weeks or months. I'm not comfortable dragging a feature along for months while keeping on with maintenance of the application.
When they decide to make feature a priority again, the first thing is to asset how much more work it is to get the feature code into the current codebase. It is a cost as a consequence of their behavior.

So feature branches can still be a valid solution while thunk based development is the default way of working.

Enter AI agents

An example I got from Claude Haiku:

Agent 1 writing documentation in one worktree
Agent 2 writing tests in another worktree
Agent 3 refactoring code in a third worktree

Agent 1 and 2 could be combined in my opinion.
Even if the documentation overlaps with the tests, why would it be a problem to use the same branch?
I'm the boss of the commits for now, but even if you let an agent commit the documentation files and the test files they don't overlap, right?

When you need to refactor code while maintaining the application, wouldn't you do that gradually?
And if a big bang refactor need to happen, wouldn't that take the priority over the other work?

Another question I have is who is checking the worktrees?
All fine that agents creates worktrees but in the end the worktrees need to be merged.
Isn't this the same scenario than the client forgetting about features for a period of time?

Now all together

Moving on I think we need to build on what we have learned working with human teams and use the parts that apply when AI agents are thrown into the mix.

If your situation needs git worktrees use them, just be sure that is the best option for your workflow.

https://batsov.com/articles/2026/03/09/emacs-and-vim-in-the-age-of-ai/ I gravitated to IDE's because of the GUI parts. I'm not a die hard terminal user. But with TUI's becoming better I'm rethinking my IDE use.

david duymelinck — Sat, 14 Mar 2026 09:08:15 +0000

Emacs and Vim in the Age of AI | (think)

It’s tough to make predictions, especially about the future. – Yogi Berra

batsov.com

Is good file naming becoming a thing of the past?

david duymelinck — Mon, 09 Mar 2026 13:54:17 +0000

As developers we heard for years naming is important.

The reason I write the post is the SOUL.md file, but lets go over the other bad naming choices AI companies made.

AGENTS.md

As I see it the file is the entry point for a coding agent to start exploring the project.

For years we are using README.md for the human entry point to our projects.
So why not go for AI-README.md or CODING-AGENT.md?

.project

To separate the coding agent permissions and other files from the project most of the coding agents use .project as one of the names they recognize. The other common name is the solution name, like .claude or .codex.

Why not use .ai? And in there one or more sub-directories can be added for solution specific things.

SOUL.md

The file as I see it is used to set agent boundaries.

The main gripe I have with that naming is that it humanizes AI. I think we all agree AI as it is now is not sentient. So it is even lower on the scale than an animal. So why give it a thing of ourself we can't even define ourselves?

CONSTITUTION.md seems like a more appropriate name.

llms.txt

While it is not a coding agent related file. I want to include it because the extension doesn't fit the content. The content is markdown.

This is even a bigger violation than generic naming.

Time for a body that governs the AI file naming?

AI isn't a language or a public asset like HTML, it is something in between.
The only thing is certain that AI is not going away, so we have to make long term plans.

The biggest problem will be to get the AI companies on board because they want to set their own standards.

Because LLM's and coding agents read every file you feed them, my solution at the moment is making the files and directories with my preferred naming explicit, for example as a system prompt.
The problem with this method is that the naming schemes will explode, because most people have their opinion about the names.

I feel when the naming is bad for those files/directories, how much are we going to care about the naming of the code files and even worst the code itself?
Or is this just a me problem?

PS: 5 days later I realize AI is the biggest misnaming so it really starts at the source. Having knowledge and the ability to learn isn't the full definition of intelligence. Understanding is the part that is missing, and it is the one that brings the two other parts together.