DEV Community: Matteo Barbero

[Boost]

Matteo Barbero — Wed, 16 Sep 2026 08:32:13 +0000

Matteo Barbero

Aug 31

Finding the Commit That Introduced a Laravel Bug with Pest and Git Bisect

#laravel #git #testing #php

4 min read

Inside the Laravel 13 Scheduler: From Cron Entry to Event Execution

Matteo Barbero — Wed, 16 Sep 2026 06:25:53 +0000

Laravel's scheduler replaces a crontab full of application commands with one entry that wakes the framework every minute. The individual tasks stay in the codebase, where they can be reviewed, tested, and deployed with the rest of the application.

That is the useful promise described in the Laravel 13 task scheduling documentation. It also hides quite a lot of work. By the time an Artisan command runs, Laravel has built an in-memory schedule, evaluated cron expressions and application state, checked filters and locks, started foreground or background processes, and dispatched events that other parts of the application can observe.

This article follows that path through Laravel 13. It assumes you already know how to define a scheduled task and concentrates on what the framework does after you run schedule:run. The source links point to Laravel's 13.x branch as it stood on September 12, 2026. If you are investigating a production application, compare them with the exact framework version installed in composer.lock.

The cron entry is only a wake-up call

The server still needs an external process to start Laravel. On a traditional Linux server, the documented cron entry is:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Cron knows nothing about reports:generate, emails:send, or any closure registered by the application. Its responsibility ends after starting php artisan schedule:run in the correct project directory. Running crontab -l therefore shows the launcher, not Laravel's task definitions.

Those definitions usually live in routes/console.php:

use App\Jobs\RefreshSearchIndex;
use Illuminate\Support\Facades\Schedule;

Schedule::command('reports:generate')->hourly();
Schedule::job(new RefreshSearchIndex)->everyTenMinutes();
Schedule::exec('/usr/local/bin/archive-reports')->dailyAt('02:00');
Schedule::call(new DeleteExpiredInvitations)->daily();

Laravel 13 also supports defining them with withSchedule() in bootstrap/app.php. Packages and application bootstrapping may register more events, so routes/console.php is the conventional location, not the scheduler's storage mechanism.

There is no schedule table for schedule:run to query. FoundationServiceProvider binds Illuminate\Console\Scheduling\Schedule as a singleton for the current application process. When that singleton is resolved, the console kernel creates a Schedule, applies its timezone and cache store, and the application's definitions add Event or CallbackEvent instances to its internal $events array.

The singleton distinction matters when reading commands such as schedule:run and schedule:list. Both receive a Schedule from the service container, but two Artisan invocations are two separate PHP processes. Each boots the application and reconstructs its own in-memory schedule.

What a scheduled definition becomes

The fluent API produces two main event shapes.

Schedule::command() and Schedule::exec() create an Illuminate\Console\Scheduling\Event. An Artisan command is converted into a command line that can later be executed as a process. A system command is already in that form.

Schedule::call() creates a CallbackEvent, a subclass of Event that invokes a closure, callable, or invokable object through Laravel's service container. Schedule::job() also creates a CallbackEvent; its callback dispatches the supplied job through Laravel's bus. If the job implements ShouldQueue, the scheduler's work is the dispatch, while a queue worker performs the job itself.

Every event carries more than a cron expression. It can contain a timezone, environment constraints, when() and skip() callbacks, overlap and single-server settings, output configuration, before and after hooks, a description, and a sub-minute repeat interval. The scheduler evaluates these attributes in stages rather than with one boolean check.

How `schedule:run` selects due events

The command is implemented by Illuminate\Console\Scheduling\ScheduleRunCommand. Its handle() method receives four dependencies from the container:

public function handle(
    Schedule $schedule,
    Dispatcher $dispatcher,
    Cache $cache,
    ExceptionHandler $handler,
)

The schedule supplies events, the dispatcher emits lifecycle events, the cache stores pause and interrupt signals, and the exception handler reports task failures. The first selection is short:

$events = $this->schedule->dueEvents($this->laravel);

Schedule::dueEvents() wraps the registered events in a collection and filters it through each event's isDue() method. In Laravel 13, isDue() checks three things:

public function isDue($app)
{
    if (! $this->runsInMaintenanceMode() && $app->isDownForMaintenance()) {
        return false;
    }

    return $this->expressionPasses()
        && $this->runsInEnvironment($app->environment());
}

expressionPasses() obtains the current time through Laravel's Date facade, converts it to the event timezone when one is configured, and asks dragonmantank/cron-expression whether the five-part expression is due. The environment check accepts the event when it has no environment restriction or when the current application environment appears in its configured list.

This produces a collection of temporally due events. It does not prove that they will execute.

Due does not mean runnable

After dueEvents(), the main command loop applies the remaining gates in a deliberate order.

First, Laravel checks whether scheduled processing has been paused. Laravel 13 provides schedule:pause and schedule:continue, which store the state in the application cache. A task is skipped while paused unless it has been marked with evenWhenPaused().

Next, filtersPass() evaluates the callbacks registered through when() and skip(). All when() callbacks must return a truthy value, while every skip() callback must remain false. Laravel dispatches ScheduledTaskSkipped when the pause check or these filters reject an event.

Then onOneServer() is considered. Schedule::serverShouldRun() asks the scheduling mutex to acquire a cache lock based on the event's mutex name and the scheduler's start minute. In a multi-server deployment, only the process that acquires this lock continues to the event. All scheduler nodes must use a shared, lock-capable cache for this coordination to work as intended.

Only after those checks does ScheduleRunCommand call runEvent(). A compact view of the path is:

registered event
    -> maintenance mode, cron expression, environment
    -> scheduler pause
    -> when() and skip() filters
    -> onOneServer() scheduling mutex
    -> withoutOverlapping() event mutex
    -> execute callback or command process

withoutOverlapping() belongs one level lower. Event::run() attempts to acquire the event mutex and returns early if another execution still owns it. This mutex prevents two executions of the same task from overlapping over time; the onOneServer() scheduling mutex chooses one server for a particular due minute. They solve different concurrency problems and use different lock names and lifetimes.

By default, the overlap mutex expires after 1,440 minutes. The value is a safety net for a process that terminates without releasing its lock, not a recommended task duration. Laravel normally releases the mutex when a foreground event finishes, and it can release it on supported termination signals. A stale lock can be cleared with php artisan schedule:clear-cache, but doing so while the original task is still running removes the protection against overlap.

Callback events require a name before withoutOverlapping() or onOneServer() can be used. Their default mutex identity would otherwise not distinguish anonymous callbacks reliably:

Schedule::call(new RefreshPartnerData)
    ->name('refresh-partner-data')
    ->withoutOverlapping()
    ->onOneServer()
    ->everyFiveMinutes();

What `runEvent()` actually coordinates

runEvent() prepares a readable command summary, then wraps execution in a console task. Before delegating to the event, it dispatches ScheduledTaskStarting and records a start time. When Event::run() returns, it dispatches ScheduledTaskFinished with the elapsed time.

For a normal Event, the work continues inside Event::run():

Acquire the overlap mutex when required.
Register signal-aware mutex cleanup.
Invoke callbacks registered with before().
Build and execute the command process.
Store its exit code.
Invoke the appropriate after, success, and failure callbacks.
Release the overlap mutex in a finally block.

The command is executed from the application's base path using Symfony Process. Foreground output is redirected to the configured destination, /dev/null by default on Unix-like systems and NUL on Windows. sendOutputTo() and appendOutputTo() replace that destination, while the email-output methods arrange to read the captured output after execution.

A CallbackEvent inherits the surrounding lifecycle but replaces process execution with a container call. Returning exactly false from the callback becomes exit code 1; other returned values become exit code 0. An exception is captured, converted to a failed exit code for cleanup, and then rethrown so ScheduleRunCommand can dispatch ScheduledTaskFailed and report it through Laravel's exception handler.

For foreground commands, a non-zero exit code is also turned into an exception after the finished event has been dispatched. ScheduledTaskFinished therefore means that execution returned, not that it succeeded. Listeners may observe both ScheduledTaskFinished and ScheduledTaskFailed for a foreground command that exits unsuccessfully. The failure is caught and reported inside runEvent(), allowing the scheduler loop to continue with later events.

One smaller detail is easy to miss when building monitoring around scheduler events: the pause and filter checks explicitly dispatch ScheduledTaskSkipped, while the overlap check happens inside Event::run() after ScheduledTaskStarting. The event records skippedBecauseOverlapping, but the outer command has already entered its execution lifecycle.

Sequential and background execution

Events due at the same time run sequentially in the order they were registered. If the first foreground command takes five minutes, later events in that schedule:run process wait five minutes before they start. Meanwhile, cron may start another scheduler process at the next minute boundary. Laravel does not place one global mutex around the complete schedule:run command, so concurrency should be controlled on the tasks that need it.

For independent command or system-command events, runInBackground() avoids blocking the loop:

Schedule::command('analytics:aggregate')
    ->hourly()
    ->runInBackground();

Background execution is available only for events created through command() and exec(), not closures or invokable callbacks. CommandBuilder constructs a platform-specific shell command that starts the task asynchronously. On completion, that shell command invokes Laravel's hidden schedule:finish command with the event mutex name and actual exit code.

ScheduleFinishCommand boots a fresh Laravel process, rebuilds the schedule, locates the matching event, calls its finish() method, and dispatches ScheduledBackgroundTaskFinished. The rebuild is another reason scheduled definitions should be deterministic and inexpensive to register.

Why one cron entry can run tasks every second

Cron still starts Laravel once per minute. Sub-minute scheduling works because schedule:run may remain alive for the rest of that minute.

If the due collection contains an event configured with everySecond(), everyTenSeconds(), or another repeat interval below one minute, Laravel enters repeatEvents(). The loop runs until the end of the minute captured when ScheduleRunCommand was constructed. On each pass it:

checks the interrupt signal;
checks whether each event's repeat interval has elapsed;
rechecks maintenance and pause state;
reevaluates when() and skip() filters;
repeats single-server coordination when configured;
sleeps for 100 milliseconds before polling again.

A slow foreground task inside this loop delays later repetitions. The Laravel documentation therefore recommends that sub-minute schedules dispatch queued jobs or start background commands, keeping the scheduler itself free to maintain timing:

Schedule::job(new DeleteExpiredSessions)->everyTenSeconds();

Schedule::command('metrics:sample')
    ->everyTenSeconds()
    ->runInBackground();

There is also a deployment consequence. A scheduler process already inside the loop continues using the code loaded before the deployment. Running php artisan schedule:interrupt after the new release is live sets a cache signal that asks the old loop to stop. The next cron invocation boots the new code.

For local development, php artisan schedule:work keeps a foreground worker alive and invokes the scheduler every minute. It is a development convenience, not a replacement for a production process manager or platform scheduler.

Inspecting the schedule Laravel actually built

crontab -l can only confirm that the external launcher exists. To inspect the application-level events produced during the current boot, use:

php artisan schedule:list

ScheduleListCommand receives its own process-local Schedule instance and wraps either events() or eventsForEnvironments() in a collection. Laravel 13 exposes four useful options:

--timezone=          Display times in this timezone
--environment=*     Display tasks configured for an environment
--next               Sort tasks by their next due date
--json               Return machine-readable JSON

Without --next, events remain in definition order. With --environment=production, Laravel filters by the event's configured environment list; it does not temporarily change APP_ENV or evaluate whether the event is due now.

The JSON representation contains these fields:

expression
command
description
next_due_date
next_due_date_human
timezone
has_mutex
repeat_seconds
environments

There are a few useful limits to that output.

next_due_date is the next time allowed by the cron expression and, for an active sub-minute window, the repeat interval. It does not predict maintenance mode, pause state, when() and skip() results, overlap locks, or which server will acquire an onOneServer() mutex. It is the next temporal opportunity, not a guarantee that the task will execute.

The timezone field is the selected display timezone, which defaults to config('app.timezone'). Laravel may convert the displayed cron expression to that timezone, and one event can produce multiple displayed expressions when a day boundary makes the conversion more complex.

has_mutex performs a live EventMutex::exists() check. It reports whether the event mutex exists at the moment the list is generated; it is not a boolean copy of the withoutOverlapping configuration and does not describe the separate scheduling mutex used by onOneServer().

Finally, schedule:list lists scheduled events, not every Artisan command registered with the application. Use php artisan list for the latter. When you need to execute one registered scheduled event directly, Laravel also provides:

php artisan schedule:test

Without --name, it presents an interactive selection. schedule:test --name=reports:generate can select a uniquely matching scheduled Artisan command. The test command forces a normally background event to run in the foreground, which is useful for observing its output, but it is still real execution against the current application environment.

A practical way to debug a task that did not run

The internal order suggests a more precise checklist than starting with cron syntax alone.

Use crontab -l, your platform dashboard, or process-manager configuration to confirm that something invokes schedule:run every minute from the correct release directory.
Run php artisan schedule:list --next -v in the same environment and release. Confirm that the event exists, its cron expression is correct, and its next due time uses the timezone you expect.
Check maintenance mode, APP_ENV, scheduler pause state, and any when() or skip() callbacks.
Inspect the cache store used for withoutOverlapping() and onOneServer(). A local cache on each node cannot coordinate multiple servers.
Check the task's configured output, Laravel logs, and listeners for scheduler lifecycle events.
Use schedule:test only when running the task immediately is safe.

The distinction to keep throughout the investigation is simple: registered, due, eligible, started, and completed are different states. Laravel's scheduler moves an event through them one check at a time.

Laravel 13 scheduler source map

The relevant implementation is small enough to read directly:

Schedule stores events and provides the fluent entry points.
Event handles command execution, hooks, output, exit codes, and overlap mutexes.
CallbackEvent executes closures, callables, invokable objects, and scheduled job dispatches.
ScheduleRunCommand selects and coordinates due events.
ScheduleListCommand renders the schedule reconstructed for the current process.
CommandBuilder creates foreground and background shell commands.
ScheduleFinishCommand completes background events in a new Artisan process.

The public scheduling API remains compact because these classes divide the work carefully. The cron daemon wakes Laravel. The application reconstructs the schedule. isDue() handles time, maintenance mode, and environment, then the runner applies operational constraints before the event deals with locking and execution. Once those boundaries are visible, both the source and the failures seen in production become much easier to reason about.

Finding the Commit That Introduced a Laravel Bug with Pest and Git Bisect

Matteo Barbero — Mon, 31 Aug 2026 11:52:00 +0000

A shipping quote API should charge EUR 5.90 for a domestic parcel weighing up to and including one kilogram. Instead, it returns EUR 9.90 when the weight is exactly 1,000 grams.

I prepared a small Laravel playground repository with this bug and a deliberately long commit history. The application is simple enough to follow, while the history makes it useful for trying a debugging technique that also works on much larger projects: combining a focused Pest test with git bisect.

Reproducing the shipping price bug

Clone and prepare the repository, then start Laravel's development server on port 8001:

git clone https://github.com/maiobarbero/laravel-pest-bisect.git
cd laravel-pest-bisect
composer setup
php artisan serve --port=8001

In another terminal, request a quote for a 1,000-gram domestic parcel:

curl --request POST http://localhost:8001/api/shipping/quote \
    --header 'Content-Type: application/json' \
    --data '{"weight_grams":1000,"zone":"domestic"}'

The response identifies the parcel as small, but returns 990 in price_cents:

{
    "weight_grams": 1000,
    "zone": "domestic",
    "price_cents": 990,
    "currency": "EUR",
    "weight_band": "small"
}

We know the expected price is 590 cents, and we know the current version is wrong. What we don't know yet is which commit changed the behaviour.

One option is to check out each earlier commit, repeat the request, and continue until the response changes. This is manageable with a handful of commits. With hundreds or thousands of commits, it becomes slow enough that it is rarely a practical approach.

How Git bisect narrows the search

git bisect uses a binary search through the commit history. We give Git one commit where the behaviour is broken and one older commit where it still works. Git checks out a commit near the middle and asks whether that revision is good or bad, then discards the half of the range that cannot contain the regression.

The number of candidates is roughly halved after every check. Searching 1,000 commits therefore takes about 10 checks in the ideal case, rather than testing every commit one by one.

The check can be performed manually, but this example has a behaviour we can express as an automated test. That allows Git to run the entire search for us.

Turning the bug into a Pest test

Create tests/Feature/ShippingQuoteTest.php with a feature test for the one-kilogram boundary:

<?php

namespace Tests\Feature;

use Illuminate\Foundation\Testing\TestCase;

uses(TestCase::class);

it('applies the small parcel tariff up to one kilogram included', function () {
    $this->postJson('/api/shipping/quote', [
        'weight_grams' => 1000,
        'zone' => 'domestic',
    ])
        ->assertOk()
        ->assertJsonPath('price_cents', 590);
});

The test calls the real API route and records the expected behaviour in one place. Run it by filtering the suite with the test filename:

php artisan test --filter=ShippingQuote

It fails on the current revision because the endpoint returns 990 instead of 590. This failure is useful beyond confirming the bug: a passing test exits with status code 0, while a failing test exits with a non-zero status. git bisect run uses that status to classify every revision automatically as good or bad.

Keep the new test uncommitted while running the bisect. It needs to remain in the working tree as Git checks out each revision in the search range. Before starting, check git status and make sure there are no unrelated changes that could affect the result.

Running the automated bisect

Start a bisect session and mark the current commit as bad:

git bisect start
git bisect bad

For this playground, commit 06bc68c5 is a known good revision. It contains the shipping quote endpoint before the regression was introduced:

git bisect good 06bc68c5

Git now has both ends of the range. Pass the focused Pest command to git bisect run:

git bisect run php artisan test --filter=ShippingQuote

Git repeatedly checks out a candidate commit and runs the test. A pass moves the good boundary forward; a failure moves the bad boundary backward. It continues until only the first failing revision remains:

9e8d96614e62c10f47efd915614836b8b42c74e9 is the first bad commit
commit 9e8d96614e62c10f47efd915614836b8b42c74e9
Author: Maio Barbero
Date:   Mon Aug 31 10:15:17 2026 +0200

    26 refactor shipping prices using a match expression

 app/Services/ShippingPriceCalculator.php | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)
bisect found first bad commit

The search points to commit 9e8d966, a refactor of ShippingPriceCalculator. Its diff contains the boundary mistake:

return match (true) {
    $weightGrams < 1000 => 590,
    $weightGrams <= 5000 => 990,
    default => 1590,
};

The small-parcel condition changed from <= 1000 to < 1000. A parcel weighing exactly 1,000 grams no longer matches the first arm and falls through to the medium price. The rest of the refactor is unrelated to the failure.

Once the investigation is complete, leave bisect mode and return to the branch and commit that were checked out before the search:

git bisect reset

At this point the failing Pest test has done two jobs. It found the regression in the existing history, and it can remain in the suite as a boundary test to prevent the same comparison error from returning after the fix.

AI Skills for Project Management

Matteo Barbero — Fri, 08 May 2026 05:29:00 +0000

After completing the DelftX project management course in TU Delft's Engineering Project Management series, the idea that stayed with me was not a template, a checklist, or a new way to make a Gantt chart look more impressive.
It was simpler than that: before you manage a project, you need to understand what kind of complexity you are actually dealing with.

That sounds obvious until you look at how many projects are managed as if all complexity were the same thing.
More tasks? Add more planning.
More uncertainty? Add more meetings.
More stakeholders? Add a RACI and hope it survives contact with reality.

Sometimes that works. Often it does not.
The problem is that "this project is complex" is not a diagnosis. It is only a warning light.

The TOE framework developed by TU Delft researchers gave me a better way to think about that warning light. TOE stands for Technical, Organizational, and External complexity.

The framework was developed to help project teams grasp complexity in large engineering projects and adapt the front-end development phase accordingly. The published paper behind it is Grasping project complexity in large engineering projects: the TOE framework.

I kept thinking about how useful this would be inside an AI-assisted workflow.
Not because AI should manage the project for you.
Because AI is useful when it is forced to structure messy thinking, and project complexity is usually very messy thinking.

So I built two new skills:

They live in the same my-ai-workflow repository as the rest of my AI workflow skills.

The core idea: not all complexity asks for the same response

The mistake I see often, including in my own thinking, is treating complexity as a single number.
We say a project is "simple", "complicated", or "very complex", then we jump straight to a management response.

That loses the interesting part.

A project can be technically complicated but organizationally stable.
Another project can be technically simple but politically unpredictable.
Another one can have both: many technical interfaces and stakeholders who are still negotiating what success even means.

Those are not the same project.
They should not be managed in the same way.

The TOE framework helps by separating complexity into three families.

Technical complexity is about the content of the project: goals, scope, technology, tasks, dependencies, quality requirements, disciplines involved, and technical risks.
In software terms, this is where we find things like legacy integrations, unclear architecture boundaries, strict performance requirements, many work packages, unfamiliar infrastructure, or unknown delivery methods.

Organizational complexity is about the internal project organization: team size, resource availability, contracts, trust, roles, methods, tools, funding sources, schedules, and coordination across disciplines or locations.
In software teams, this often shows up as unclear ownership, unavailable specialists, misaligned delivery methods between teams, pressure to hit a date that was chosen before discovery, or contract structures that reward the wrong behavior.

External complexity is about the context around the project: external stakeholders, approvals, political influence, market instability, regulatory pressure, dependencies outside the team, strategic pressure, public trust, and other external risks.
In a product or platform context, this may be customers with conflicting expectations, compliance deadlines, procurement constraints, partner APIs, legal uncertainty, or leadership changes that alter priorities halfway through the work.

The useful part is not the labels themselves.
The useful part is that they stop you from pretending a technical solution can fix an organizational problem, or that a weekly status report can resolve an unstable external context.

Detail complexity and dynamic complexity

The other distinction I wanted the skills to preserve is the difference between detail complexity and dynamic complexity.

Detail complexity is about the number of parts and the structure between them.
Many components, many interfaces, many work packages, many actors, many dependencies, many contracts.
This kind of complexity often benefits from control: decomposition, interface registers, baselines, dependency maps, quality criteria, clear ownership, decision gates.

Dynamic complexity is about change, uncertainty, and unpredictability.
Stakeholders shift position.
Scope moves.
The market changes.
The regulator clarifies something late.
The team learns that the original solution path does not work.
The facts are incomplete and the project cannot simply be decomposed into stable pieces.

Dynamic complexity needs more than control.
It needs interaction: shared problem framing, short feedback cycles, scenario exploration, visible assumptions, alignment sessions, escalation paths, and repeated reassessment.

This creates four broad management postures:

Low detail and low dynamic complexity: keep it simple.
High detail and low dynamic complexity: use systems management and control.
Low detail and high dynamic complexity: use interactive management and connecting work.
High detail and high dynamic complexity: use dynamic management, combining control with interaction.

That last category is where many real projects live.
The risk is overcorrecting in one direction.
Too much control, and the project becomes rigid exactly when it needs to learn.
Too much interaction, and everyone keeps talking while decisions never land.

Why this belongs in an AI workflow

AI-generated project plans are often too tidy.
They look coherent because they are formatted well, not because the underlying diagnosis is correct.

That is the danger.
A model can produce a confident plan from a weak description.
It can turn uncertainty into bullet points so smoothly that you forget the uncertainty was still there.

The TOE structure gives the model friction.
It forces the conversation to separate the type of complexity from the action taken in response to it.
It also makes confidence visible. A low-confidence hotspot is not ignored just because the model cannot fully prove it. If it could affect approval, trust, compliance, delivery feasibility, or project value, it deserves attention.

This is the same principle behind my earlier AI-assisted workflow: the AI can accelerate the production of artifacts, but the judgment remains yours.
For project management, the artifact is not code, a PRD, or an issue list.
It is a clearer picture of the project before the plan hardens.

Skill 1: `project-complexity-mapper`

The first skill is diagnostic.
It takes a rough project description, messy notes, or a partially formed idea and turns it into a structured complexity assessment.

By default it runs as a fast complexity scan.
That means it does not walk through every TOE element one by one. It reads the description, infers likely hotspots, asks only the few questions that would materially change the diagnosis, and marks confidence where evidence is thin.

If the project is high-risk, expensive, politically sensitive, or already showing signs of failure, it can switch to a complete TOE assessment.
That mode uses the full 47-element TOE checklist and scores each element from 1 to 5: none, little, some, substantial, or very much.

The mapper is deliberately not an action planner.
It produces a diagnosis, not a backlog.

The output includes:

A summary of the assessment mode and top complexity hotspots.
Findings by Technical, Organizational, and External category.
Scores for TOE contribution, detail complexity, dynamic complexity, severity, impact, and confidence.
An overall quadrant for the project.
Separate hotspot quadrants, because one average score hides too much.
A Mermaid quadrant chart to visualize where the main hotspots sit.
Management-fit guidance.
A handoff table that another skill can consume.

The handoff table matters.
It makes the next step traceable.
The action planner should not invent a generic project-management checklist. It should act on the diagnosed hotspots.

Skill 2: `project-complexity-action-planner`

The second skill starts where the mapper stops.
It reads the diagnosis, especially the handoff table, management fit, hotspot quadrants, and findings by category. Then it converts those hotspots into a practical intervention plan.

The important word is intervention.

This is not a full project schedule.
It is not a Gantt chart.
It is not a ticket breakdown.

An intervention is a management action chosen because a specific hotspot needs it.
If a project has high technical detail complexity around integrations, an intervention might be an interface register, a prototype for the riskiest API, or a dependency map with clear owners.
If the hotspot is external and dynamic, the intervention might be a stakeholder alignment session, a scenario review, or an approval map.
If the hotspot is both detailed and dynamic, the intervention should combine control and connection, for example a requirements baseline with a controlled discovery window, or decision gates paired with assumption reviews.

The action planner sequences work into three horizons:

Now: actions that clarify uncertainty, prevent blockage, or create needed control immediately.
Next: actions that depend on first facts, decisions, or alignment.
Later: actions to reassess after a phase change, pilot, procurement decision, design freeze, or other major shift.

It also assigns owner roles, not names, unless names are provided.
That keeps the output useful across teams: project manager, sponsor, product owner, technical lead, integration lead, contract manager, legal or compliance lead, stakeholder lead, steering committee.

The final output includes an intervention backlog, sequencing logic, decision gates, reassessment triggers, risks in the plan, and a short handoff for execution.

Why I split it into two skills

I could have made one skill that diagnoses complexity and creates a plan in one pass.
That would have been faster.
It would also have been worse.

Diagnosis and action are different mental moves.
When they happen at the same time, the model tends to rush toward advice.
The format becomes a polished recommendation before the project has been understood.

Splitting the workflow keeps the first skill honest.
Its job is to say, "Here is where complexity appears to be coming from, here is how severe it looks, here is how confident we are, and here is the management posture that seems to fit."

Only after that does the second skill ask, "Given that diagnosis, what should we do first?"

That separation mirrors how I want to work with AI in general.
Do not let the model skip the thinking artifact.
Make the thinking artifact reviewable.
Then use it as input to the next step.

How I would use it

I would start with a project description written in normal language.
No template.
No forced structure.

Something like:

We need to migrate a legacy reporting system into a new platform.
The old system is used by three departments, each with different reporting definitions.
The source data comes from two internal APIs and one external vendor.
The deadline is connected to a contract renewal, but the scope is still moving.
The engineering team understands the new platform, but nobody fully owns the old reporting logic.

Then I would run the mapper and read the output critically.
The important questions are not "Do I like this report?" but:

Did it classify the real hotspots?
Did it confuse technical complexity with organizational complexity?
Did it miss an external dependency?
Are the low-confidence findings actually important?
Are we averaging away a hotspot that needs separate attention?

If the diagnosis looks useful, I would pass the handoff into the action planner in a new session with clear context window.
Then I would review the intervention backlog with the same skepticism.

Every action should trace back to a hotspot.
If an action does not trace back to a hotspot, it is probably generic advice.
If a high-severity hotspot has no action, the plan is probably incomplete.
If a dynamic hotspot only gets control artifacts, the plan is probably too rigid.
If a high-detail hotspot only gets workshops, the plan is probably too vague.

The output should become a conversation artifact for the team, not a decree from the machine.

When this is useful

I see this being useful before a project execution plan, before a large PRD, before a replatforming effort, before a vendor integration, before a compliance-heavy feature, or when a project already feels stuck but the reason is not obvious.

It is especially useful when people disagree about what the problem is.
One person says the project is technically hard.
Another says the scope keeps changing.
Another says the real blocker is approvals.
Another says the team does not have the right people.

All of those can be true.
The TOE framework gives you a way to hold those truths separately instead of collapsing them into one vague complaint.

It also helps with AI-assisted development because it sits upstream of implementation.
If the project is organizationally unstable, breaking work into better tickets will not fix it.
If the external context is volatile, a perfect architecture diagram will not make the decision process predictable.
If the technical interfaces are unclear, more stakeholder alignment will not define the API contract by itself.

Different complexity asks for different management behavior.

When I would not use it

I would not use this for every task.

If the work is small, local, and well understood, this is overhead.
If one person can explain the scope, implement it, test it, and ship it without meaningful dependencies, a TOE scan is probably unnecessary.

I also would not use it to justify a decision that has already been made.
That is one of the easiest ways to misuse AI: ask for a framework, feed it selective context, and receive a professional-looking confirmation.

And I would be careful using it without the people who actually understand the project.
Complexity is subjective and dynamic.
Different actors see different risks because they sit in different parts of the system.
The skill can structure the conversation, but it cannot replace the conversation.

The human part

The most valuable output of these skills is not the table.
It is the disagreement the table makes visible.

If a stakeholder says a hotspot is scored too high, good.
Ask why.
If the technical lead says the integration risk is understated, good.
Update the diagnosis.
If the sponsor thinks the external pressure is a value opportunity rather than only a risk, good.
That belongs in the management fit.

The goal is not to make project complexity disappear.
Some complexity cannot be removed.
Some complexity should not be removed, because it is tied to project value.

The goal is to stop managing every project with the same reflex.

Control where the project needs control.
Connect where the project needs interaction.
Reassess when the context changes.
And keep the judgment with the humans who are accountable for the work.

The skills

The two skills are available in my AI workflow repository:

They are not meant to sell a methodology.
They are my attempt to encode a useful way of thinking so I can reuse it, challenge it, and improve it over time.

My AI-Assisted workflow

Matteo Barbero — Wed, 15 Apr 2026 07:17:46 +0000

You open a chat, describe what you want, iterate on the output, and ship something that more or less works. It feels fast.
The features work, technically. But nobody, including me, fully understood what is there. Edge cases nobody thought to handle, architecture that made sense in the moment but didn't survive contact with the next feature. A growing sense that I was building faster and understanding less.

The problem I kept running into was this: how do you get the speed benefits of AI assistance without losing the clarity and intentionality that makes software maintainable?
The short answer is that the real work happens before the coding starts.

The core idea: thinking in writing, not in code

What is AI actually good at? Implementation. What is it genuinely bad at? Figuring out what you actually want, catching the assumptions you forgot to make explicit, and telling you when your mental model of the problem is wrong.
That's your job. It will always be your job.

The single most valuable shift I made was treating every feature as a thinking problem first and an implementation problem second. The workflow is designed to force that thinking to happen before any code is written, and to use AI to stress-test it, not to skip it.

This workflow has been adapted to work with me from Mark Pocock's skills.

The workflow

Step 1: Free-form plan

Everything starts with a document I write myself, in plain language, with no required structure. I describe the problem, my initial thinking about the solution, the constraints I'm aware of, and the things I'm uncertain about. This is not a deliverable, nobody reads it but me. Its only purpose is to get the thinking out of my head and into a form I can examine.

The quality of everything downstream depends entirely on the quality of this step. A vague plan produces a vague PRD, which produces vague issues, which produces code that technically runs but doesn't do what you meant.

Step 2: PRD via `write-a-prd`

The free-form plan becomes the input to a structured interview process. The skill explores the codebase to understand the current state of things, then interviews me relentlessly about every aspect of the plan, walking down each branch of the design tree, resolving dependencies between decisions one by one.
This is the step where bad ideas get caught. Not because the AI is smarter than me, but because being forced to answer specific questions about your own plan reveals the places where you were hand-waving. "How does this behave when the user isn't authenticated?" "What happens if this operation partially fails?" "You said this replaces the existing feature, what happens to users who depend on the current behavior?"

The output is a structured PRD file containing a problem statement, a solution description, an extensive list of user stories, implementation decisions (modules, interfaces, schema changes, API contracts), module design, testing decisions, and explicit out-of-scope items. Everything is explicit.
The user stories are the backbone of everything that follows. They need to be specific enough that acceptance criteria can be derived from them unambiguously downstream, not at this stage, but when scope is defined at the issue level.

Step 3: Issues via `prd-to-issues`

The PRD becomes a set of issues using vertical slices, tracer bullets that cut through every integration layer end-to-end rather than horizontal slices of a single layer. A slice that only touches the database, or only touches the UI, is not a valid slice. Each issue should deliver a narrow but complete path that is demoable or verifiable on its own.
Each issue is classified as either AFK (the AI can implement and the change can be merged without human interaction) or HITL (a human decision is required at some point during implementation). Preferring AFK over HITL wherever possible keeps the work moving without becoming a bottleneck on my attention.

Before anything is written, the skill presents the proposed breakdown and asks: does the granularity feel right, are the dependency relationships correct, should anything be merged or split? Issues are written in dependency order so that cross-references between them use real numbers.

Each issue contains a concise description of the end-to-end behaviour, a "how to verify" section describing exactly how to confirm the slice is complete, acceptance criteria in Given/When/Then format including error cases, a list of blockers, and references back to the user stories it addresses.
Everything lives in files. I work across different platforms, sometimes GitHub, sometimes GitLab, and keeping the workflow file-based means it doesn't depend on any particular tool.

Step 4: Tasks via `issues-to-tasks`

Each issue is broken down into concrete, ordered tasks, one task per focused AI session. The constraint is deliberate: if a task can't be completed in a single session, it's too large.
The skill explores the specific parts of the codebase touched by the issue, identifies existing patterns to follow, and produces a task list with types (WRITE, TEST, MIGRATE, CONFIG, REVIEW), explicit outputs, and dependency order. Schema before logic, logic before API, API before UI, tests interleaved rather than batched at the end.

The key design decision in the task descriptions: they are written as instructions to the AI that will execute them, not as notes to a human developer. Each task specifies which files to touch, which existing patterns to follow, and what the output looks like when done. No code snippets, just intent, not implementation.

Step 5: The handoff to code

Each task description is a self-contained prompt. When I'm ready to implement a task, I open a fresh session and paste the task description along with the parent issue for context. The task description was written for this purpose, it specifies scope, references the right files and patterns, and defines what done looks like.
Fresh context per task is intentional. Long sessions with accumulated context tend to drift: the model starts making decisions based on what it already did rather than what the task requires. Starting clean with a well-scoped task consistently produces better output than continuing a long session.
For REVIEW tasks, the ones flagged as requiring a human decision, I stop, make the decision, update the task file with the outcome, and continue. These are the moments where the workflow earns its keep: the decision is made deliberately, in context, not buried in a long generation.

Step 6: Code review via `code-review`

Every PR goes through a structured six-pass review before merge. The passes cover logic errors, operation ordering, bad practices, security, magic strings and values, and pattern improvements.

Operation ordering deserves particular attention in AI-generated code. Models tend to produce code that does the right things but sometimes in the wrong sequence: sending a notification before committing a transaction, writing an audit log after the action it should record, mutating state before validating input. These bugs are easy to miss in review because the code looks correct at a glance.

The review runs on a file or diff, not on the whole feature. Scope is deliberately narrow, catching issues at the PR level is far cheaper than finding them later.

Step 7: Final audit via `final-audit`

At the end of a feature, a cross-cutting audit looks at things that can only be evaluated across the whole implementation. Not individual bugs, those should have been caught per PR, but systemic issues: inconsistencies between modules, patterns that were introduced early and replicated incorrectly everywhere, security assumptions that hold in isolation but break down across the full surface area.

The audit reads the full implementation before flagging anything, which is the point. It groups findings by severity, gives an explicit overall verdict on whether the feature is safe to leave in production, and asks for approval before making any changes. Unsupervised fixes on already-merged code are riskier than fixes made during development.

What this workflow is not

It is not fast to set up. The planning and PRD steps take real time, and the temptation to skip them in favour of going straight to code is constant. The workflow only pays off if you genuinely believe that thinking time before coding is cheaper than debugging time after.

It is also not a replacement for engineering judgement. The AI will suggest reasonable things at every step that are wrong for your specific situation. The review steps, where you evaluate the breakdown before anything is created, exist precisely because the AI's output needs to be validated against knowledge it doesn't have: your team's conventions, your users' actual behavior, the parts of the codebase that have hidden complexity.

The underlying principle

Every step in this workflow has the same structure: AI produces something, you review it with full context, then it gets created. The AI accelerates the production. The review is yours, always.

The workflow is designed to make that review as effective as possible, by ensuring that when you're evaluating an issue, you have a PRD to check it against; when you're evaluating a task, you have an issue to check it against; and when you're reviewing code, you have acceptance criteria to check it against.

The skills

Now if you read this article to the end you at least deserve a link with my skills.
Check my GitHub repo.

How to test Filament resources | Laravel Personal Finance Dashboard

Matteo Barbero — Thu, 19 Feb 2026 09:41:59 +0000

Now that we have our resources set up, it's time to ensure they work as expected—and stay that way. In this lesson, we're going to write feature tests for our BankAccount, Budget, and Category resources. We'll focus particularly on ensuring that users can only see their own data.

Setting up Pest

First, we need to add Pest to our project. Pest is a testing framework with a focus on simplicity and elegance.

composer require pestphp/pest --dev --with-all-dependencies
php artisan pest:install

We also need to make sure our User model is ready for Filament testing. To properly simulate a Filament user in our tests, our User model should implement the FilamentUser contract. This ensures that when we use actingAs, the user is correctly recognized as having access to the panel.

Update app/Models/User.php:

use Filament\Models\Contracts\FilamentUser;
// ...

class User extends Authenticatable implements FilamentUser
{
    // ...

    public function canAccessPanel(\Filament\Panel $panel): bool
    {
        return true;
    }
}

You can view the setup and model changes in this commit.

Testing the Bank Account Resource

Let's start with the BankAccountResource. We want to verify that we can:

Render the page.
List bank accounts belonging to the user.
NOT list bank accounts belonging to other users.
Create, edit, and delete accounts.

Create a new test file: tests/Feature/Filament/Resources/BankAccountResourceTest.php.

Rendering and Listing

We use actingAs($user) to sign in as a user, and then access the page URL.

use App\Filament\Resources\BankAccounts\Pages\ManageBankAccounts;
use App\Models\BankAccount;
use App\Models\User;
use Livewire\Livewire;
use function Pest\Laravel\actingAs;

it('can render page', function () {
    $user = User::factory()->create();

    actingAs($user)
        ->get(ManageBankAccounts::getUrl())
        ->assertSuccessful();
});

it('can list bank accounts', function () {
    $user = User::factory()->create();
    $bankAccount = BankAccount::factory()->for($user)->create();

    Livewire::actingAs($user)
        ->test(ManageBankAccounts::class)
        ->assertCanSeeTableRecords([$bankAccount]);
});

Testing Scope (The "Other User" Test)

This is a critical test. We create a user and another user. We expect the current user effectively not to see the other user's record.

it('cannot see other users bank accounts', function () {
    $user = User::factory()->create();
    $otherUser = User::factory()->create();
    $otherBankAccount = BankAccount::factory()->for($otherUser)->create();

    Livewire::actingAs($user)
        ->test(ManageBankAccounts::class)
        ->assertCanNotSeeTableRecords([$otherBankAccount]);
});

Actions: Create, Edit, Delete

Filament provides excellent helpers to test actions directly.

it('can create bank account', function () {
    $user = User::factory()->create();

    Livewire::actingAs($user)
        ->test(ManageBankAccounts::class)
        ->mountAction('create')
        ->setActionData([
            'name' => 'My Main Bank',
            'balance' => '1000.50',
        ])
        ->callMountedAction()
        ->assertHasNoActionErrors();

    assertDatabaseHas('bank_accounts', [
        'user_id' => $user->id,
        'name' => 'My Main Bank',
        'balance' => 100050, // Value as integer thanks to our Caster
    ]);
});

Notice how we assert the database has the value 100050 because of our logic handling money as integers!

You can see the full test suite for the Bank Account resource in this commit.

Budget and Category Resources

The tests for BudgetResource and CategoryResource follow the exact same pattern. We need to ensure that detailed actions like creating and editing work, but most importantly, we must verify the scoping rules.

For example, the Category tests ensure that a user can only edit their own categories.

You can check the implementation for the Budget resource tests here and the Category resource tests here.

Running the Tests

Finally, let's run our test suite to see everything green!

php artisan test

You should see an output confirming that all resource tests are passing:

PASS Tests\Feature\Filament\Resources\BankAccountResourceTest
✓ it can render page
✓ it can list bank accounts
✓ it cannot see other users bank accounts
...

🎓 Build this App & Get Certified (Free)

If you found this guide helpful, you can build the entire application from scratch with my free course.

What you'll learn:

🏗️ Advanced Laravel Architecture
📊 Building Dashboards with FilamentPHP
💰 Handling Money professionally in code

→ Join other students on maiobarbero.dev

Happy coding!

How to build a Voice-to-Text App with Laravel AI SDK

Matteo Barbero — Wed, 11 Feb 2026 08:39:27 +0000

Stop Writing Boilerplate: Build a Voice-to-Text App with Laravel AI SDK

If you are a PHP developer, you have likely looked at AI integration with a mix of excitement and fatigue. Excitement for the possibilities, but fatigue from WRITING THE SAME BOILERPLATE code to handle multipart requests, API keys, and error handling for OpenAI or Anthropic.

The new Laravel AI SDK changes this. It turns complex AI interactions into fluid, Laravel-style syntax.

In this guide, we won't just talk about it—we will build a functional Voice-to-Text application in under 10 minutes. I call mine "Dettami", but you can call yours whatever you want.

Let's write some code.

Prerequisites

Laravel 10+ (or the latest version)
PHP 8.2+
An OpenAI API Key

Step 1: Install the SDK

First, forget about guzzlehttp/guzzle manual calls. Pull in the first-party package.

composer require laravel/ai

Once installed, publish the configuration file. This is where you will define your "drivers" (OpenAI, Gemini, Mistral, etc.).

php artisan install:ai

Add your key to your .env file:

OPENAI_API_KEY=...

Step 2: Define the Route

We need a single endpoint to accept the audio file. In your routes/web.php or routes/api.php:

use App\Http\Controllers\TranscribeAudioController;

Route::post('/transcribe', TranscribeAudioController::class)->name('transcribe');

Step 3: The Logic (Where the Magic Happens)

This is the part that usually hurts. Handling file uploads + external API calls is often messy.

Create your controller:

php artisan make:controller TranscribeAudioController --invokable

Now, look at how clean this solution is using the Transcription facade. We don't need to manually construct a POST request to https://api.openai.com/v1/audio/transcriptions. The SDK does it for us.

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Storage;
use Laravel\AI\Facades\Transcription;

class TranscribeAudioController extends Controller
{
    public function __invoke(Request $request)
    {
        $request->validate([
            'audio' => 'required|file|mimes:webm,mp3,wav'
        ]);

        $file = $request->file('audio');

        // 1. Save the file temporarily
        // We need a physical path to pass to the SDK
        $path = $file->store('temp_recordings');
        $fullPath = Storage::path($path);

        try {
            // 2. Transcribe with one fluent method chain
            // The SDK automatically uses your configured default driver
            $text = Transcription::fromPath($fullPath, $file->getMimeType())
                ->generate();

            // 3. Cleanup
            Storage::delete($path);

            return response()->json([
                'success' => true,
                'text' => (string) $text,
            ]);

        } catch (\Throwable $e) {
            // Log the error and return a user-friendly message
            return response()->json(['error' => 'Transcription failed'], 500);
        }
    }
}

Why this matters

Notice line 27: Transcription::fromPath(...).
That is the abstraction we have been waiting for. It removes the cognitive load of remembering specific API parameters for every different provider. Today you use OpenAI, tomorrow you switch to Gemini—the code stays strictly the same.

Step 4: The Frontend (The "Recorder")

For the frontend, you don't need a heavy React app. A simple Blade view with vanilla JS covers it perfectly.

The core requirement is the browser's MediaRecorder API. Here is the pseudo-code for what your JavaScript needs to do:

Request Microphone access (navigator.mediaDevices.getUserMedia).
Record chunks of audio into a Blob.
Send that Blob to our Laravel endpoint via FormData.

Here is a glimpse of the UI I built for this:

Summary

We just built a fully functional Voice-to-Text backend in about 20 lines of code.

The Laravel AI SDK respects your time. It handles the "plumbing" so you can focus on building the actual product.

If you want to inspect the full source code for the demo project "Dettami", check the repository here:
GitHub: maiobarbero/dettami

Keep moving forward.

How to create a resource in Filament v5 | Laravel Personal Finance Dashboard

Matteo Barbero — Tue, 10 Feb 2026 07:15:52 +0000

👋 Note: This article is an excerpt from my Free Laravel & Filament Finance Course.
The full course includes code-along lessons, quizzes, and a Completion Certificate.

👉 Start the Free Course & Get Certified

The First Filament Admin Panel

We have our database structure. It's solid, typed, and waiting for data. But a database without an interface is like a library without doors, secure, but useless.

Today, we build the doors.

We are going to create our first Filament Resources. In Filament, a "Resource" is the static representation of an entity in your admin panel. It describes how your model looks in a table, how it behaves in a form, and how it relates to the rest of your application.

We will start with something fundamental: Categories.

1. Creating the Category Resource

Filament provides a powerful artisan command to generate resources. We want our categories to be manageable quickly, without navigating away from the list. We want a "Simple Resource", one that handles Creating, Reading, Updating, and Deleting (CRUD) all on a single page using modals.

Run this command:

php artisan make:filament-resource Category --simple

This generates two key files:

app/Filament/Resources/CategoryResource.php: The definition of the table and form.
app/Filament/Resources/CategoryResource/Pages/ManageCategories.php: The page controller that handles the actions.

You can see the initial structure in this commit.

If you visit /admin/categories now, you might see a form with a User dropdown. This is technically correct, a category belongs to a user, but practically wrong. When I create a category, it should be mine. I shouldn't have to select myself from a list.

2. Scoping and Context

We have two problems to solve:

Visibility: I can see categories belonging to other users.
Creation: I have to manually select the user.

Fixing Visibility

To ensure I only see my records, we strictly scope the Eloquent query used by the resource. We override the getEloquentQuery method in CategoryResource.php.

public static function getEloquentQuery(): \Illuminate\Database\Eloquent\Builder
{
    return parent::getEloquentQuery()->where('user_id', auth()->id());
}

Now, the table will only ever load records where user_id matches the logged-in user.

Fixing Creation

Next, we clean up the form. In CategoryResource::form(), remove the user_id input completely. We don't want the user to worry about it.

But the database needs that ID. So, we inject it programmatically.

In app/Filament/Resources/CategoryResource/Pages/ManageCategories.php, we modify the CreateAction. We use mutateFormDataUsing to intercept the form submission and add the current user's ID before it hits the database.

protected function getHeaderActions(): array
{
    return [
        CreateAction::make()
            ->mutateDataUsing(function (array $data): array {
                $data['user_id'] = auth()->id(); // <--- This implies the user
                return $data;
            }),
    ];
}

We also remove the user column from the table to keep it clean.

You can view the specific changes to scope the data in this commit.

3. Bank Accounts

Money needs a home. Let's apply the exact same logic to Bank Accounts.

Generate the resource: php artisan make:filament-resource BankAccount --simple.
Scope the query in BankAccountResource.
Inject the user_id in ManageBankAccounts.

If you check your database or use artisan tinker, you'll notice our MoneyCast is working silently in the background. When you type "1000" in the balance field, it's stored as 100000 (cents) in the database, assuming you treated the input as a distinct number.

Wait, there's a nuance here. Our form is currently generic. Later, we'll want to ensure we are handling decimals correctly in the UI so the user types "10.00" and we store "1000". For now, we are trusting the raw input.

Check the implementation of the Bank Account resource here.

4. Budgets and Presentation

Finally, let's tackle Budgets. This is where Filament's UI components really shine.

Generate the resource:

php artisan make:filament-resource Budget --simple

Budgets have a type (Reset or Rollover). In our database, this is an Enum string. In Filament, we want to visualize this instantly using colors.

The Badge Column

In BudgetResource.php, we can use a TextColumn but format it as a badge.

TextColumn::make('type')
    ->badge()
    ->color(fn (BudgetType $state): string => match ($state) {
        BudgetType::Reset => 'success',
        BudgetType::Rollover => 'warning',
    })
    ->searchable(),

This simple chaining transforms a boring text string into a vibrant, communicative UI element.

Formatting Money

We also want to display the budget amount as actual currency, not just a raw number. Filament has a dedicated money formatter.

TextColumn::make('amount')
    ->money('EUR')
    ->sortable(),

This creates a polished, professional look immediately.

You can explore the Budget resource implementation in this commit, and see how we refined the badge colors here.

Conclusion

We now have three functional pillars of our personal finance application:

Categories to label our spending.
Bank Accounts to store our wealth.
Budgets to control our impulses.

And importantly, they are completely private to the logged-in user.

In the next lesson, we will test our first Resources. Keep building.

🎓 Build this App & Get Certified (Free)

If you found this guide helpful, you can build the entire application from scratch with my free course.

What you'll learn:

🏗️ Advanced Laravel Architecture
📊 Building Dashboards with FilamentPHP
💰 Handling Money professionally in code

→ Join other students on maiobarbero.dev

Testing the New Laravel AI SDK: Building 'Dettami' a voice-to-text app

Matteo Barbero — Sat, 07 Feb 2026 13:46:06 +0000

The landscape of AI integration in PHP has just shifted. With the release of the Laravel AI SDK, what used to require complex API wrangling or third-party packages is now a first-party citizen of the framework we love.

I couldn't resist. I had to take it for a spin.

The result is Dettami (Italian for "Dictate to me"), a simple web app that records your voice and transcribes it instantly. And when I say "simple," I mean it. The speed at which I went from laravel new to a working prototype was exhilarating.

The Goal: Frictionless Audio Transcription

I wanted to build something tangible. Not just a "Hello World" for AI, but a feature I would actually use: a quick way to record thoughts and get them as text.

Here is what the interface looks like. Clean, focused, and ready to listen.

The Implementation

Installing the SDK was the first step, and as you'd expect from the Laravel ecosystem, it was seamless.

composer require laravel/ai

But the real magic happened in the controller. In the past, handling audio uploads, converting formats, and sending them to an API like OpenAI's Whisper or Google's Speech-to-Text involved a fair bit of boilerplate. You had to manage the file, ensure the format was correct, build the multipart request, handle the response...

With the Laravel AI SDK, the complexity vanishes. It abstracts the "how" and lets you focus on the "what."

Here is the core logic from my Dettami controller. Look at how expressive it is:

public function __invoke(Request $request)
{
    if ($request->hasFile('audio')) {
        $file = $request->file('audio');

        // Store the file temporarily
        $path = $file->storeAs('dettami', 'recording.webm');
        $fullPath = Storage::path($path);

        try {
            // The magic happens here. One fluents line.
            $transcription = Transcription::fromPath($fullPath, 'audio/webm')
                ->generate();

            // Clean up
            Storage::delete($path);

            return response()->json([
                'success' => true,
                'transcription' => (string) $transcription,
            ]);
        } catch (\Throwable $e) {
            // ... error handling
        }
    }
}

That's it. Transcription::fromPath(...) -> generate().

The SDK handles the heavy lifting of communicating with the configured AI provider. It feels native. It feels right.

The Frontend Experience

For the frontend, I kept it simple using Blade and vanilla JavaScript with the MediaRecorder API. The goal was to provide immediate feedback. You click record, you speak, you get text.

Beyond Transcription: Translation

The power of this SDK doesn't stop at transcription. Once you have the text, the possibilities are endless. You can summarize it, rewrite it, or—as I experimented with—translate it.

Because the SDK provides a unified interface for these operations, adding a translation step is just as trivial as the transcription itself. Whether you are using OpenAI, Anthropic, or Gemini, the code remains consistent and clean.

Reflections

Building Dettami was a reminder of why I love this framework. It respects my time. The Laravel AI SDK isn't just a wrapper; it's an opinionated, elegant way to bring intelligence into your applications without the headache.

For architects and developers, this means we can stop worrying about connecting to AI and start worrying about what we can build with it. Ideally, the barrier to entry has been lowered to the floor.

If you haven't tried it yet, fire up a terminal.

composer require laravel/ai

And build something amazing. You can find the full source code for Dettami on GitHub. I recommend starting with this commit to see the transcription logic in isolation.

Keep moving forward.

Laravel Personal Finance Dashboard: creating the database

Matteo Barbero — Thu, 05 Feb 2026 07:59:55 +0000

👋 Note: This article is an excerpt from my Free Laravel & Filament Finance Course.
The full course includes code-along lessons, quizzes, and a Completion Certificate.

👉 Start the Free Course & Get Certified

Creating the Database

Every great application stands on the shoulders of a solid data model. If the database schema isn't right, everything else, from your eloquently written controllers to your beautiful Filament resources, will feel like fighting gravity.

In this lesson, we are going to define the core entities of our Personal Finance application. We aren't just creating tables; we are defining the vocabulary of our domain.

The Entities

Our application needs to track money moving in and out. To do that effectively, we need four primary concepts:

Bank Accounts: Where the money lives.
Categories: How we classify the money (e.g., "Utilities", "Dining Out").
Budgets: Our financial goals or limits.
Transactions: The heart of the system, the actual record of spending or earning.

Generating the Artifacts

Laravel makes scaffolding these incredible easy. We need a Model, a Migration, a Factory, and a Seeder for each of our entities. Instead of running four commands per entity, we can use the -mfs flags.

Run the following commands in your terminal:

php artisan make:model Category -mfs
php artisan make:model Budget -mfs
php artisan make:model BankAccount -mfs
php artisan make:model Transaction -mfs

You should see a flurry of green success messages. We now have our files ready to be sculpted.

A Note on "Down" Methods

Open up one of your new migration files. You'll see an up method and a down method.

I'm going to ask you to do something that might feel rebellious: delete the down method.

Why? In this project, we are adopting a Fix Forward strategy. In a production environment with real data, rolling back a migration (especially one that drops columns or tables) is destructive and risky. If we make a mistake in a migration that has already run, we don't roll it back, we create a new migration to fix the issue. This keeps our database history linear and truthful.

So, go ahead and remove public function down(): void from all your new migration files. It clarifies our intent: we only move forward.

Defining the Schema

Let's define the structure of our tables.

1. Enums

Before we get to the tables, we need a way to define the type of a Budget. Is it a fixed budget that we reset every month? Or is it a rolling budget that we keep track of over time? Let's use a PHP Enum for this to ensure type safety.

php artisan make:enum Enums/BudgetType

Edit app/Enums/BudgetType.php:

<?php

namespace App\Enums;

enum BudgetType: string
{
    case Reset = 'reset';
    case Rollover = 'rollover';

    public function getLabel(): string
    {
        return match ($this) {
            self::Reset => 'Reset',
            self::Rollover => 'Rollover',
        };
    }
}

2. Migrations

Now, let's fill in our up methods.

create_categories_table.php
Categories are simple. They have a name and belong to a user.

Schema::create('categories', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('name');
    $table->timestamps();

    $table->unique(['user_id', 'name']);
});

create_budgets_table.php
A budget tracks a limit for a specific period.

Schema::create('budgets', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('name');
    $table->integer('amount')->default(0);
    $table->string('type')->default('fixed');
    $table->timestamps();
    $table->unique(['user_id', 'name']);
});

create_bank_accounts_table.php
Represents a physical or digital account.

Schema::create('bank_accounts', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('name');
    $table->unsignedBigInteger('balance')->default(0);
    $table->timestamps();

    $table->unique(['user_id', 'name']);
});

create_transactions_table.php
The center of our universe. Links everything together.

Schema::create('transactions', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->foreignId('bank_account_id')->constrained()->cascadeOnDelete();
    $table->string('description');
    $table->foreignId('category_id')->constrained()->cascadeOnDelete();
    $table->foreignId('budget_id')->constrained()->cascadeOnDelete();
    $table->date('date');
    $table->text('note')->nullable();
    $table->unsignedInteger('amount');
    $table->timestamps();
});

[!TIP]
Notice we store money as integers (cents) rather than floats or decimals. Floating point math can be imprecise. storing $10.00 as 1000 is deeply robust.

3. The Money Cast

Since we are storing money as integers (cents) but want to work with it as standard units (dollars/euros) in our code, let's create a custom Cast. This encourages consistency across our application.

Run:

php artisan make:cast MoneyCast

Update app/Casts/MoneyCast.php:

<?php

namespace App\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use Illuminate\Database\Eloquent\Model;

class MoneyCast implements CastsAttributes
{
    /**
     * Cast the given value.
     *
     * @param  array<string, mixed>  $attributes
     */
    public function get(Model $model, string $key, mixed $value, array $attributes): mixed
    {
        return $value / 100;
    }

    /**
     * Prepare the given value for storage.
     *
     * @param  array<string, mixed>  $attributes
     */
    public function set(Model $model, string $key, mixed $value, array $attributes): mixed
    {
        return (int) round($value * 100);
    }
}

4. The Models

Now we breathe life into our schemas by defining relationships and behaviors in our Models.

User.php
The user owns everything.

// ... imports
use Illuminate\Database\Eloquent\Relations\HasMany;

class User extends Authenticatable
{
    // ... traits

    // ... fillable & hidden

    public function bankAccounts(): HasMany
    {
        return $this->hasMany(BankAccount::class);
    }

    public function categories(): HasMany
    {
        return $this->hasMany(Category::class);
    }

    public function budgets(): HasMany
    {
        return $this->hasMany(Budget::class);
    }

    public function transactions(): HasMany
    {
        return $this->hasMany(Transaction::class);
    }
}

Category.php

class Category extends Model
{
    /** @use HasFactory<\Database\Factories\CategoryFactory> */
    use HasFactory;

    protected $fillable = [
        'user_id',
        'name',
    ];

    public function user(): \Illuminate\Database\Eloquent\Relations\BelongsTo
    {
        return $this->belongsTo(User::class);
    }

    public function transactions(): \Illuminate\Database\Eloquent\Relations\HasMany
    {
        return $this->hasMany(Transaction::class);
    }
}

Budget.php
Here we treat our type as an Enum and amount with our new MoneyCast.

class Budget extends Model
{
    /** @use HasFactory<\Database\Factories\BudgetFactory> */
    use HasFactory;

    protected $fillable = [
        'user_id',
        'name',
        'amount',
        'type',
    ];

    protected function casts(): array
    {
        return [
            'type' => \App\Enums\BudgetType::class,
            'amount' => \App\Casts\MoneyCast::class,
        ];
    }

    public function user(): \Illuminate\Database\Eloquent\Relations\BelongsTo
    {
        return $this->belongsTo(User::class);
    }

    public function transactions(): \Illuminate\Database\Eloquent\Relations\HasMany
    {
        return $this->hasMany(Transaction::class);
    }
}

BankAccount.php

class BankAccount extends Model
{
    /** @use HasFactory<\Database\Factories\BankAccountFactory> */
    use HasFactory;

    protected $fillable = [
        'user_id',
        'name',
        'balance',
    ];

    protected function casts(): array
    {
        return [
            'balance' => \App\Casts\MoneyCast::class,
        ];
    }

    public function user(): \Illuminate\Database\Eloquent\Relations\BelongsTo
    {
        return $this->belongsTo(User::class);
    }

    public function transactions(): \Illuminate\Database\Eloquent\Relations\HasMany
    {
        return $this->hasMany(Transaction::class);
    }
}

Transaction.php
The nexus. Note the mass assignment protection and casting.

class Transaction extends Model
{
    /** @use HasFactory<\Database\Factories\TransactionFactory> */
    use HasFactory;

    protected $fillable = [
        'user_id',
        'bank_account_id',
        'category_id',
        'budget_id',
        'description',
        'amount',
        'note',
        'date',
    ];

    protected function casts(): array
    {
        return [
            'amount' => \App\Casts\MoneyCast::class,
        ];
    }

    public function user(): \Illuminate\Database\Eloquent\Relations\BelongsTo
    {
        return $this->belongsTo(User::class);
    }

    public function bankAccount(): \Illuminate\Database\Eloquent\Relations\BelongsTo
    {
        return $this->belongsTo(BankAccount::class);
    }

    public function category(): \Illuminate\Database\Eloquent\Relations\BelongsTo
    {
        return $this->belongsTo(Category::class);
    }

    public function budget(): \Illuminate\Database\Eloquent\Relations\BelongsTo
    {
        return $this->belongsTo(Budget::class);
    }
}

Seeding and Verification

With our structure defined, let's spin up the database.

First, update your DatabaseSeeder.php to call the new seeders:

class DatabaseSeeder extends Seeder
{
    use WithoutModelEvents;

    /**
     * Seed the application's database.
     */
    public function run(): void
    {
        $this->call(UserSeeder::class);
        $this->call(CategorySeeder::class);
        $this->call(BudgetSeeder::class);
        $this->call(BankAccountSeeder::class);
        $this->call(TransactionSeeder::class);
    }
}

(We'll cover Factories in depth in a future lesson, but for now, ensure your factories create dummy data).

Then, run:

php artisan migrate:fresh --seeder

Now, let's verify our work using Tinker, the best tool for checking your data reality.

php artisan tinker

Try fetching a user and their transactions:

$user = \App\Models\User::first();
$user->transactions()->get();

If you see a Collection of Transaction models, congratulations. You have successfully mapped the physical world of finance into your digital domain.

Finally, before we commit, let's make sure our code style is impeccable.

./vendor/bin/pint

Keep moving forward.

🎓 Build this App & Get Certified (Free)

If you found this guide helpful, you can build the entire application from scratch with my free course.

What you'll learn:

🏗️ Advanced Laravel Architecture
📊 Building Dashboards with FilamentPHP
💰 Handling Money professionally in code

→ Join other students on maiobarbero.dev

Laravel Personal Finance Dashboard: setting up the project with Filament v5

Matteo Barbero — Tue, 03 Feb 2026 08:33:26 +0000

👋 Note: This article is an excerpt from my Free Laravel & Filament Finance Course.
The full course includes code-along lessons, quizzes, and a Completion Certificate.

👉 Start the Free Course & Get Certified

Starting a new project is always a mix of excitement and anxiety. The blank slate. Infinite possibilities. But today, we're not just writing code; we're building a tool for financial freedom. A system that serves us, tailored to our specific needs, without the bloat of generic SaaS products.

In this first lesson, we will lay the foundation. We are going to build a robust, modern application using strictly typed Laravel 12 and the elegant Filament admin panel.

Let's get our hands dirty.

1. The Foundation

First, let's create our canvas. Open your terminal and breathe in that new project smell.

laravel new laravel_filament_personal_finance

We want a clean slate, so when promoted, select:

No starter kit: We are building this artisan-style.
Pest: For testing. It’s elegant and expressive.
SQLite: Simplify the infrastructure. For a personal tool, it's fast, zero-conf, and easy to backup.
Init Git repo: Yes. Version control is non-negotiable.

Once the command finishes, navigate into your new fortress:

cd laravel_filament_personal_finance
composer install

Verify that the heart is beating:

php artisan serve

Visit http://localhost:8000. You should see the default Laravel splash screen. We are live.

View the initial setup commit

2. Supercharging with AI

I believe in leveraging every tool available to maintain flow. We'll add Laravel Boost, an MCP server that acts as a bridge between our app and AI agents. Think of it as giving your AI pair programmer direct sensory access to your codebase.

composer require laravel/boost --dev

Initialize it:

php artisan boost:install

When prompted, select your IDE or specific configuration. This will generate a configuration block like this (the below one is the Google Antigravity configuration):

{
    "mcpServers": {
        "laravel-boost": {
            "command": "/usr/bin/php",
            "args": [
                "/home/<your-username>/<path-to-project>/artisan",
                "boost:mcp"
            ]
        }
    }
}

Now, your AI assistant can understand your project structure, run artisan commands, and debugging becomes a conversation rather than a struggle.

View the Boost configuration commit

3. The Admin Panel

We don't want to spend weeks building authentication views and CRUD tables from scratch. We want to focus on the logic of our finances. Enter Filament v5. It’s the gold standard for TALL stack admin panels.

Install it via composer:

composer require filament/filament:"^5.0"

Now, install the panel. We'll call ours admin.

php artisan filament:install --panels

Enter admin when asked for the ID.

This scaffolds the entire admin infrastructure. It's almost magical how much time this saves us.

View the Filament setup commit

4. First Access

Reference without access is useless. Let's create an admin user to unlock the gates.

php artisan make:filament-user

Follow the prompts to set your name, email, and password. Then, restart your server if it's not running:

php artisan serve

Navigate to /admin. Login with your new credentials.

You are now looking at the control center of your future financial system. It's empty now, but soon it will be the source of truth for your wealth.

We have a running application, a powerful admin interface, and the AI tooling to help us build faster. The structure is set. In the next lesson, we will start modeling the domain.

Happy coding!

🎓 Build this App & Get Certified (Free)

If you found this guide helpful, you can build the entire application from scratch with my free course.

What you'll learn:

🏗️ Advanced Laravel Architecture
📊 Building Dashboards with FilamentPHP
💰 Handling Money professionally in code

→ Join other students on maiobarbero.dev

How to set up a global .gitignore

Matteo Barbero — Wed, 07 May 2025 06:33:13 +0000

If you work with multiple Git repositories, you’ve likely run into the frustration of ignoring the same files (like .DS_Store, Thumbs.db, or your IDE settings) over and over again. Fortunately, Git allows you to define a global .gitignore file that applies to all repositories on your system. This is done through the core.excludesfile configuration option.

In this article, I'll walk you through how to set up a global .gitignore file using git config.

🎯 Why Use a Global .gitignore?

Some files are specific to your system or development environment and should never be committed to any project. Examples include:

macOS system files (.DS_Store)
Windows thumbnails (Thumbs.db)
IDE configs (.idea/, .vscode/)
Log files (*.log)
Local environment files (.env)

Instead of duplicating the same ignore rules in every repo, a global .gitignore keeps things DRY (Don't Repeat Yourself).

🛠 Step-by-Step Setup

1. Create the Global .gitignore File

Start by creating a .gitignore_global file in your home directory (or anywhere you prefer):

touch ~/.gitignore_global

Then, edit it and add the rules you want:

# macOS
.DS_Store

# Windows
Thumbs.db

# IDEs
.vscode/
.idea/

# Logs
*.log

# Env files
.env

2. Configure Git to Use the Global File

Tell Git to use this file globally:

git config --global core.excludesfile ~/.gitignore_global

You can verify it worked with:

git config --global core.excludesfile

This should output the path you just set.

DEV Community: Matteo Barbero

[Boost]

Finding the Commit That Introduced a Laravel Bug with Pest and Git Bisect

Inside the Laravel 13 Scheduler: From Cron Entry to Event Execution

The cron entry is only a wake-up call

What a scheduled definition becomes

How schedule:run selects due events

Due does not mean runnable

What runEvent() actually coordinates

Sequential and background execution

Why one cron entry can run tasks every second

Inspecting the schedule Laravel actually built

A practical way to debug a task that did not run

Laravel 13 scheduler source map

Finding the Commit That Introduced a Laravel Bug with Pest and Git Bisect

Reproducing the shipping price bug

How Git bisect narrows the search

Turning the bug into a Pest test

Running the automated bisect

AI Skills for Project Management

The core idea: not all complexity asks for the same response

Detail complexity and dynamic complexity

Why this belongs in an AI workflow

Skill 1: project-complexity-mapper

Skill 2: project-complexity-action-planner

Why I split it into two skills

How I would use it

When this is useful

When I would not use it

The human part

The skills

My AI-Assisted workflow

The core idea: thinking in writing, not in code

The workflow

Step 1: Free-form plan

Step 2: PRD via write-a-prd

Step 3: Issues via prd-to-issues

Step 4: Tasks via issues-to-tasks

Step 5: The handoff to code

Step 6: Code review via code-review

Step 7: Final audit via final-audit

What this workflow is not

The underlying principle

The skills

How to test Filament resources | Laravel Personal Finance Dashboard

Setting up Pest

Testing the Bank Account Resource

Rendering and Listing

Testing Scope (The "Other User" Test)

Actions: Create, Edit, Delete

Budget and Category Resources

Running the Tests

🎓 Build this App & Get Certified (Free)

How to build a Voice-to-Text App with Laravel AI SDK

Stop Writing Boilerplate: Build a Voice-to-Text App with Laravel AI SDK

Prerequisites

Step 1: Install the SDK

Step 2: Define the Route

Step 3: The Logic (Where the Magic Happens)

Why this matters

Step 4: The Frontend (The "Recorder")

Summary

How to create a resource in Filament v5 | Laravel Personal Finance Dashboard

The First Filament Admin Panel

1. Creating the Category Resource

2. Scoping and Context

Fixing Visibility

Fixing Creation

3. Bank Accounts

4. Budgets and Presentation

The Badge Column

Formatting Money

Conclusion

🎓 Build this App & Get Certified (Free)

Testing the New Laravel AI SDK: Building 'Dettami' a voice-to-text app

The Goal: Frictionless Audio Transcription

The Implementation

The Frontend Experience

Beyond Transcription: Translation

Reflections

How `schedule:run` selects due events

What `runEvent()` actually coordinates

Skill 1: `project-complexity-mapper`

Skill 2: `project-complexity-action-planner`

Step 2: PRD via `write-a-prd`

Step 3: Issues via `prd-to-issues`

Step 4: Tasks via `issues-to-tasks`

Step 6: Code review via `code-review`

Step 7: Final audit via `final-audit`