DEV Community: Eduardo Lázaro

Move business logic out of your Laravel controllers with Laractions

Eduardo Lázaro — Sat, 08 Aug 2026 10:09:59 +0000

Sometimes you have a controller method that started small and did not stay that way. You validate the request, create a record, then fired a couple of side effects, return a response, ect.

Every one of those steps is real work, and none of it belongs in the controller, but that is where it lands because the controller is where the request arrives.

Laractions is a small package for moving that work into single-purpose classes. This post is a straight refactor: one fat controller method pulled apart into an action you can call from anywhere.

How to install

Install via Composer. The service provider auto-registers and there is nothing to publish to get going:

composer require edulazaro/laractions

The controller we are cleaning up

Take this store method. It works, and it is the kind of method that grows a new responsibility every sprint.

public function store(Request $request)
{
    $data = $request->validate([
        'email' => 'required|email',
        'plan'  => 'required|string',
    ]);

    $subscription = Subscription::create($data);
    Mail::to($subscription->email)->send(new SubscriptionStarted($subscription));
    activity()->log("subscription {$subscription->id} created");

    return redirect()->route('subscriptions.index');
}

The controller's job is to turn a request into a response. Creating the subscription and firing the side effects is business logic, and three other places will eventually want to reuse it.

Extract it into an action

Generate an action. The generator drops the Action suffix, since App\Actions already says what the class is.

php artisan make:action CreateSubscription

namespace App\Actions;

use EduLazaro\Laractions\Action;

class CreateSubscription extends Action
{
    public function handle(array $attributes): Subscription
    {
        $subscription = Subscription::create($attributes);

        Mail::to($subscription->email)->send(new SubscriptionStarted($subscription));
        activity()->log("subscription {$subscription->id} created");

        return $subscription;
    }
}

Now the controller shrinks back to its actual job.

public function store(Request $request)
{
    $data = $request->validate([
        'email' => 'required|email',
        'plan'  => 'required|string',
    ]);

    CreateSubscription::create()->run($data);

    return redirect()->route('subscriptions.index');
}

create() resolves the action through the container, so if it needed a mailer or a billing client you would type-hint it in the constructor and get it injected. run() calls handle(). Because handle() here takes a single array parameter, the validated $data array is passed through whole as that argument, which is why run($data) just works.

Passing arguments however you have them

That single-array call is one of three ways run() forwards to handle(). If handle() took discrete parameters instead, all of these would land the same way:

$action->run('a@b.com', 'pro');                       // positional
$action->run(email: 'a@b.com', plan: 'pro');          // named
$action->run(['email' => 'a@b.com', 'plan' => 'pro']); // keyed by parameter name

The one rule to remember: a single array parameter receives the array whole, the attribute-bag call from the refactor above, while a concrete typed parameter such as handle(File $file) receives the value, not the array around it.

Bind an action to a model

When an action is about a specific record, generate it against the model and it gets a typed property for that record.

php artisan make:action CancelSubscription --model=Subscription

namespace App\Actions\Subscription;

class CancelSubscription extends Action
{
    protected Subscription $subscription;

    public function handle(string $reason): void
    {
        $this->subscription->update(['status' => 'cancelled', 'reason' => $reason]);
    }
}

Add the HasActions trait to the model and register the actions it owns in an $actions array, keyed by a short name. That key is how you call them.

class Subscription extends Model
{
    use HasActions;

    protected array $actions = [
        'cancel' => CancelSubscription::class,
    ];
}

Now you run the action straight off the model instance by its key, which is the form I use everywhere:

$subscription->action('cancel')->run('customer request');

The model injects itself into the action's $subscription property, so handle() reads $this->subscription directly, and run() executes it synchronously right there, with no queue involved. If you would rather not register a key, pass the class name instead and it resolves the same way:

$subscription->action(CancelSubscription::class)->run('customer request');

Let the action validate its own input

An action can carry its own rules in a $rules array, checked against the resolved arguments before handle() runs. On failure it throws the same ValidationException a form request throws, so the action guards itself even when it is called from a console command or a test that never went through HTTP validation.

class CreateSubscription extends Action
{
    protected array $rules = [
        'email' => 'required|email',
        'plan'  => 'required|string',
    ];

    public function handle(array $attributes): Subscription
    {
        // ...
    }
}

When you want it in the background

The same action can queue itself. Swap run() for dispatch() and it goes onto the queue as a job, with queue(), delay() and retry() to tune it.

CreateSubscription::create()
    ->queue('default')
    ->dispatch($data);

In practice I run everything synchronously with run() and reach for a dedicated queued Job when I want background work, but if a given action is a clean unit to defer, dispatch() is right there.

Wrapping up

If you liked this way of working aand want to collaborate with the development of Laractions, PRs are welcome 😊

👉 Package on Packagist: https://packagist.org/packages/edulazaro/laractions
👉 Source on GitHub: https://github.com/edulazaro/laractions

Model field keepers in Laravel with Larakeep

Eduardo Lázaro — Sat, 08 Aug 2026 10:09:39 +0000

Most Laravel models have a few fields nobody types in. A total summed from line items, a slug, a search_text blob, a cached count. Something has to compute them, and that something usually ends up wedged into an observer or spread across the model until both are hard to read.

Larakeep gives that computation a home. A Keeper is a small class that knows how to produce one or more of a model's fields, and the model runs it with a single call. This is the whole package, feature by feature.

How to install

One Composer package, and the service provider auto-registers.

composer require edulazaro/larakeep

Nothing to publish. A keeper is a plain class, and the wiring is a trait plus an attribute.

What a keeper is

A keeper holds the formulas for a model's derived fields, one method per field, and nothing else. It sits deliberately close to an action but aims at a different job: an action performs an operation, a keeper fills a field. Where an action might send an email, a keeper computes the total that gets stored on the invoice.

Writing a keeper

Generate one with the artisan command. The keeper takes the model in its constructor, and by convention it is created for the model whose name it carries, so InvoiceKeeper targets Invoice.

php artisan make:keeper InvoiceKeeper

Each field maps to a method named get followed by the PascalCase of the column, so a total column is filled by getTotal() and amount_due by getAmountDue().

namespace App\Keepers;

use App\Models\Invoice;

class InvoiceKeeper
{
    public function __construct(private Invoice $invoice) {}

    public function getTotal(): int
    {
        return $this->invoice->items->sum('amount');
    }

    public function getAmountDue(): int
    {
        return $this->getTotal() - $this->invoice->paid;
    }
}

A method just returns the value. It does not assign it and it never touches the database; it is only the formula.

Binding a keeper to the model

Add the HasKeepers trait to the model and attach the keeper with the #[KeptBy] attribute.

use EduLazaro\Larakeep\Concerns\HasKeepers;
use EduLazaro\Larakeep\Attributes\KeptBy;
use App\Keepers\InvoiceKeeper;

#[KeptBy(InvoiceKeeper::class)]
class Invoice extends Model
{
    use HasKeepers;
}

The attribute is repeatable, so a model can carry several keepers, each owning different fields. If you prefer to keep the model clean, register the same binding in a service provider's boot() instead.

Invoice::keep(InvoiceKeeper::class);

Filling the fields

Call process() with a field name and the keeper's matching method runs, assigning its return value to the model attribute. Pass an array to fill several at once, and because process() returns the model, you chain the save.

$invoice->process('total');
$invoice->process(['total', 'amount_due'])->save();

The one thing to keep in mind is that closing save(). process() sets the attributes in memory and hands the model back, but it does not persist anything on its own. The natural place to call it is the model's saving observer, so the derived fields are always current right before a write.

Fields that take arguments

A method can take arguments. Suffix it with With and pass the arguments as an array to processWith().

public function getTotalWith(string $currency): int
{
    // ...
}

$invoice->processWith('total', ['EUR']);

The arguments go in as an array, one element per parameter.

Other verbs, not just get

get is only the default prefix. Name a method with any verb, say refreshTotal(), and run it through processTask() with that verb.

public function refreshTotal(): int
{
    // ...
}

$invoice->processTask('refresh', 'total');
$invoice->processTask('refresh', ['total', 'amount_due']);

Its argument-taking cousin is processTaskWith('refresh', 'total', ['EUR']), the same as processWith() with an explicit verb. This is handy when one keeper computes the same field in more than one way.

Wrapping up

That is Larakeep end to end: a keeper class holding the formulas, #[KeptBy] to bind it, and process() to run those formulas into the model's attributes before you save.

The derived-field logic lives in one place per model instead of living on random unwanted places through an observer.

👉 Package on Packagist: https://packagist.org/packages/edulazaro/larakeep
👉 Source on GitHub: https://github.com/edulazaro/larakeep

Book meetings in Laravel with Wireschedule

Eduardo Lázaro — Sat, 08 Aug 2026 09:03:00 +0000

Sometimes you want your visitors to be able to book a call or a demo with you, and you might not want to pay for Calendy or to use external widgets.

You might also want the booking data in your own database, not leaving for someone else's dashboard, and you want the booking to actually plug into your app's pipeline instead of being a dead-end iframe.

Wireschedule is a self-hosted meeting scheduler for Laravel that does exactly that. Availability lives in config, bookings land in your own table, and the UI is a Livewire component you drop in. Here is the fast path to getting it running and wired into your own logic.

How to install

It is a normal Composer package, and the service provider registers its migration for you, so there is nothing to publish just to run it.

composer require edulazaro/wireschedule
php artisan migrate

The only manual step is the stylesheet. Import it into your CSS bundle or the widget shows up unstyled.

@import '../../vendor/edulazaro/wireschedule/resources/css/wireschedule.css';

There is no separate JS build. The Livewire view ships its own inline Alpine, so it uses the Livewire and Alpine you already have. Requirements are PHP 8.2+, Laravel 11+ and Livewire 3.

How to use it

Drop the Blade component wherever people should book. The event you pass is a key you will define in config in a second.

<x-wireschedule event="demo" />

Pick the look once on the root element. Wireschedule shares one theme attribute with the rest of the wire* family, and the CSS ships eleven themes including studio, minimal, brutalist, glass and neon.

<html data-wire-theme="studio">

Now shape the demo event. Publish the config and open it up.

php artisan vendor:publish --tag=wireschedule-config

Each event is a weekly availability map plus a few booking rules. The map is keyed by ISO weekday, 1 for Monday through 7 for Sunday, and each day is a list of HH:MM ranges. duration and buffer are minutes, days_ahead is the booking horizon, and min_notice is the minimum minutes ahead someone can book.

'timezone' => 'Europe/Madrid', // organiser zone; availability is read here, stored UTC
'events' => [
    'demo' => [
        'label' => 'Demo',
        'duration' => 30,
        'buffer' => 0,
        'days_ahead' => 21,
        'min_notice' => 120,
        'availability' => [
            1 => [['10:00', '14:00'], ['16:00', '18:00']],
            5 => [['10:00', '14:00']],
        ],
    ],
],

The component renders the available dates, the free slots for the selected date, and a short name and email form, saving a booking on confirm.

Wiring the booking into your pipeline

This is the part that makes it more than a form. After a successful save, the Scheduler dispatches a wireschedule-booked Livewire event carrying the new booking id. Listen for it in a parent Livewire component and fire whatever follow-up you need, like pinging your team channel or syncing a CRM.

use Livewire\Attributes\On;

class BookingPage extends Component
{
    #[On('wireschedule-booked')]
    public function onBooked(int $id): void
    {
        // notify your team, push to a CRM, dispatch a job...
    }
}

Because the booking is a row in your database, you read it back with plain Eloquent. The model ships scopes so the common query stays short.

use EduLazaro\WireSchedule\Models\Booking;

Booking::ofType('demo')->confirmed()->upcoming()->orderBy('starts_at')->get();

If the person was logged in when they booked, Wireschedule captures them automatically through a polymorphic booker relation, so you can attribute the booking to an account with no extra work. For a guest it is just null.

$booking->booker; // the authenticated user who booked, or null

Timezones and double-booking are handled

You do not have to think about either of these, which is half the reason to use it. The visitor's browser timezone is detected client side and used to display the slots, then everything is persisted in UTC with the visitor's zone stored on the row, so your availability config stays in your own timezone and the maths just works.

Double-booking is blocked at two layers: a unique (event_type, starts_at) index on the table, plus a re-check that the slot is still free at confirm time, so two concurrent requests cannot grab the same slot.

Good to know

The event prop is locked, and on mount the component runs abort_unless against the event config. If you pass an event key that is not defined under wireschedule.events, the component 404s instead of rendering an empty widget. Just define the event in the config before you point the component at it and you are fine.

👉 Package on Packagist: https://packagist.org/packages/edulazaro/wireschedule
👉 Source on GitHub: https://github.com/edulazaro/wireschedule

Store and search chunks in Laravel with Meilisearch and Larameili

Eduardo Lázaro — Fri, 07 Aug 2026 01:52:49 +0000

Many times, you have to split documents into chunks, embed them, and push them into Meilisearch. Now the chunks live in the index and only in the index. There is no reason to keep a copy in your database: nothing joins a chunk, nothing edits one by hand, and the only question you ever ask is which chunks are relevant to this query, within this filter.

The awkward part is querying them from Laravel. Scout wants to mirror an Eloquent model into the index, which is backwards here. So you end up talking to the raw Meilisearch client, building filter strings by hand and mapping arrays back into something usable.

Larameili is for exactly this. It gives a Meilisearch index an Active Record model, so the chunks read like Eloquent even though they never touch your database.

How to install

As usually, use composer, and the service provider auto-registers:

composer require edulazaro/larameili

It reads the same MEILISEARCH_HOST and MEILISEARCH_KEY your app already uses.

The model is the index

A model maps to one index. Declare the index name, the fields to filter on, and an embedder if you want hybrid search.

namespace App\Meili;

use EduLazaro\Larameili\Meili;

/**
 * @property string $id
 * @property int    $document_id
 * @property string $content
 * @property string $type
 */
class Chunk extends Meili
{
    protected static string $index = 'chunks';

    protected static array $searchable = ['content'];
    protected static array $filterable = ['document_id', 'type'];

    protected static array $embedders = [
        'default' => ['source' => 'openAi', 'model' => 'text-embedding-3-small'],
    ];
}

Push the settings

The $filterable and $embedders you declared live in code until you sync them to the engine. List the model in config/larameili.php and run the command, which creates the index and applies the settings.

php artisan meili:sync

Import the chunks in bulk

An importer sends thousands of chunks. import() streams them in batches and waits for each one, so a long import never outruns the engine, and it is memory-safe over a generator.

Chunk::import($documentChunks, batchSize: 500);

There are also insert(), updateMany() for partial updates, and deleteWhere() to drop a document's chunks by filter.

Chunk::deleteWhere("document_id = {$document->id}");

Search, keyword then hybrid

The query builder compiles to Meilisearch parameters and hydrates the hits back into Chunk models. Start with a keyword search inside a filter.

$hits = Chunk::query()
    ->where('type', 'body')
    ->search('cancellation policy');

Because the index has an embedder, semantic() turns it into a hybrid search: Meilisearch runs the keyword and the vector search together and fuses the rankings. 0 is keyword only, 1 is vector only.

$hits = Chunk::query()
    ->where('type', 'body')
    ->semantic(0.7)
    ->search('how do I get my money back');

Filter and paginate

Filters map to Meilisearch's syntax, and paginate() returns a Laravel LengthAwarePaginator with an exact total, so it drops straight into a Blade view.

$page = Chunk::query()
    ->whereIn('document_id', [1, 2, 3])
    ->where('type', 'body')
    ->paginate(20);

$page->total();   // exact
$page->links();

Back to the Eloquent record

A chunk belongs to a Document that does live in your database. Meilisearch has no joins, so this is a resolver: it looks the Eloquent model up by the foreign key stored on the chunk.

use EduLazaro\Larameili\Relations\BelongsToEloquent;

class Chunk extends Meili
{
    public function document(): BelongsToEloquent
    {
        return $this->belongsToEloquent(Document::class, foreignKey: 'document_id', ownerKey: 'id');
    }
}

Read it as a property and it resolves lazily. Eager-load it on a search with with(), so every hit is resolved in one query instead of one per hit.

$hits = Chunk::query()
    ->semantic(0.7)
    ->with('document')                 // one whereIn for every hit
    ->search('how do I get my money back');

$hits->first()->document->title;       // a normal Eloquent model

And that's it

The chunks stay in Meilisearch, where they belong, and you query them with a model instead of a raw client: filters, hybrid search, pagination, and a link back to the records that do live in your database. Your relational schema keeps the entities that earn a table, and the search documents stop pretending to be one of them.

👉 Package on Packagist: packagist.org/packages/edulazaro/larameili
👉 Source on GitHub: github.com/edulazaro/larameili

Add toast messages in Laravel with Wiretoast

Eduardo Lázaro — Thu, 06 Aug 2026 09:53:00 +0000

Fire toast notifications in Laravel from PHP, Alpine and plain JavaScript with one notify call, plus positioning, auto-dismiss and grouping, and no CSS framework in your bundle

Here is a problem I hit on every project. A Livewire action finishes and I need to tell the user it worked, but the toast library I grabbed assumes Tailwind, or ships its own huge runtime, or only works from JavaScript when half my triggers actually live in PHP. Wiretoast is my answer to that, and this post is the fast path to using it.

The problem

You want to fire a toast from PHP, from Alpine, and from plain JavaScript with the same call, and you do not want to drag a CSS framework into your bundle to get it.

How to install

Start with Composer, then wire up the assets. I bundle with Vite, so I import the package CSS and JS into my entry files.

// resources/js/app.js
import '@wiretoast/js/wiretoast.js';
import '@wiretoast/css/wiretoast.css';

That @wiretoast alias is optional, and you set it up by pointing Vite at the vendor resources folder so the imports stay short.

// vite.config.js
resolve: {
    alias: {
        '@wiretoast': path.resolve(__dirname, 'vendor/edulazaro/wiretoast/resources'),
    },
},

Then the component goes once into your layout, and on the Vite path it injects no tags of its own.

<x-wiretoast />

How to use it

The fastest possible win is a one-liner in a Livewire component right after something succeeds. The helper is a component macro named notify, registered for you when Livewire is present.

$this->notify('Profile updated', 'success');

Under the hood that dispatches a notify browser event, which is exactly what Alpine fires too. So the same toast from a purely front-end button looks like this.

<button @click="$dispatch('notify', { message: 'Copied', type: 'info' })">
    Copy link
</button>

The five types you can pass are success, error, warning, info and neutral, and a message can be a plain string or an object with a title and a message when you want a heading.

Positioning and auto-dismiss

Every toast takes an options object as the third argument, and the keys I reach for most are position, timeout and progress.

$this->notify('Heads up', 'warning', [
    'position' => 'bottom-center',
    'timeout'  => 3000,
    'progress' => true,
]);

There are seven positions available: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right and center. A timeout of 0 makes the toast persist until it is closed by hand, and progress set to true draws a countdown bar that pauses while the pointer is over the toast.

Collapsing repeated toasts

If an action can fire many times in a row, stacking ten identical toasts is just noise. Set group to true and same-type messages fold into one.

window.notify('Item added', 'success', { group: true });

There is also a legacy shorthand, where passing true as the third argument on the Livewire helper means the same thing.

$this->notify('Item added', 'success', true);

Switching themes and dark mode

The visual style is chosen with the theme prop, and eleven themes are bundled, running from minimal to synthwave. You set it on the component.

<x-wiretoast theme="soft" />

Dark mode follows the operating system by default through prefers-color-scheme, and you can force a mode with the mode prop when you want deterministic output.

<x-wiretoast mode="dark" />

Do not mix the two install paths

This is the one thing that will bite you, so it is worth saying plainly. When you bundle with Vite the component injects no tags by design, which is why you import the CSS and JS yourself. If you instead publish the assets with vendor:publish --tag=wiretoast-assets, that is the moment you add :assets="true" to the component so it emits the link and script for you. Doing both, importing through Vite and passing :assets="true", loads everything twice.

Links

Wiretoast is MIT licensed and open source.

📌 You can see it in action here.

👉 Packagist: https://packagist.org/packages/edulazaro/wiretoast
👉 GitHub: https://github.com/edulazaro/wiretoast

Create multilanguage apps in Laravel with Laratext

Eduardo Lázaro — Thu, 06 Aug 2026 08:52:28 +0000

You have a Laravel app in English and you need it in Spanish too. The built-in __() helper works, but it forces an awkward trade. Either your templates are full of __('some.dotted.key') you cannot read, or they hold the full sentence and every reworded string breaks its own translation. And either way you still write the Spanish by hand.

Laratext fixes both. You name each string with a key and a readable default in one call, and a scan command translates the missing ones into every language you support. Here it is, simplest first.

How to install

One Composer package, then publish the config file.

composer require edulazaro/laratext
php artisan vendor:publish --tag="texts"

Step 1: name your strings

Replace your hardcoded strings, or your __() calls, with text() in PHP and @text in Blade. You pass a key and the English text as the default.

<h1>@text('home.hero_title', 'Find your next home')</h1>
<button>@text('common.save', 'Save changes')</button>

$message = text('billing.trial_over', 'Your trial has ended.');

The key is what the translation is stored under, so you reword the English later without breaking anything, and the English stays right there in the template so it reads cleanly. Dynamic values use Laravel's :name placeholders and survive translation intact.

@text('cart.summary', 'You have :count items.', ['count' => $cart->count()])

Step 2: point it at a translator

Open the config/texts.php the publish step created. List the languages you support and pick the service that translates them. OpenAI, Google and Claude are built in.

'default_translator' => 'openai',

'languages' => [
    'en' => 'English',
    'es' => 'Spanish',
],

The OpenAI translator reads its key from that config, which pulls OPENAI_API_KEY from your env by default.

OPENAI_API_KEY=sk-...

The other two work the same way with their own keys. To translate through Claude instead, set default_translator to claude, which reads ANTHROPIC_API_KEY and runs on the Messages API with prompt caching, so repeated batches in a single scan reuse the cached instructions.

Step 3: scan and translate

Now run the scan. It reads every text() and @text call across your PHP and Blade files, finds the keys missing from Spanish, translates just those through the configured service, and writes them to lang/es.json.

php artisan laratext:scan --write

Your English is the source, taken from app.locale, and every language in the config is a target. Before a real run, --dry lists what it would add and --diff shows the changes. You can also override the service for one run with --translator=claude. Later, when you reword an English string, --resync retranslates the keys whose source actually changed instead of only the brand-new ones.

php artisan laratext:scan --dry
php artisan laratext:scan --write --translator=claude
php artisan laratext:scan --write --resync

One honest note: the OpenAI, Google and Claude translators all make real API calls, so a scan of a large app costs money on the provider side. Run --dry first, and translate one language at a time with --lang=es, if you want to keep it tight.

Writing your own translator

If none of the three built-in services fits, the translator is just an interface. Generate one.

php artisan make:translator DeepLTranslator

You get a class extending the package's Translator base. Implement translate(), which takes one string and the target languages and returns the translations keyed by language code.

namespace App\Translators;

use EduLazaro\Laratext\Contracts\TranslatorInterface;
use EduLazaro\Laratext\Translator;

class DeepLTranslator extends Translator implements TranslatorInterface
{
    public function translate(string $text, string $from, array $to): array
    {
        $results = [];

        foreach ($to as $language) {
            $results[$language] = $this->deepl($text, $from, $language);
        }

        return $results;
    }
}

Because it extends Translator, you also get batchTranslate, which chunks a big set of strings into safe batches before sending. If your API takes many strings at once, override translateMany to translate a batch in one request rather than one call per string. Then add the class to the translators list in config/texts.php and select it with --translator=deepl.

Wrapping up

That is a whole second language: name each string once with @text('key', 'English'), configure a translator, and run one scan to fill the rest. Swap the translator when you outgrow the defaults.

👉 Package on Packagist: https://packagist.org/packages/edulazaro/laratext
👉 Source on GitHub: https://github.com/edulazaro/laratext

Turn Claude Code into a Laravel expert with LaraClaude

Eduardo Lázaro — Thu, 06 Aug 2026 00:29:37 +0000

Claude Code writes PHP in Laravel quite well, but it starts every session as a generalist. It does not know your project has three hundred migrations that should be thirty, that a @foreach two files over is firing an N+1, or that your modals follow one specific pattern. You end up re-explaining the same context constantly.

LaraClaude packages that context as slash commands. It is a Claude Code plugin with over thirty Laravel skills, each a /lc: command. Install it once and you have audits, scaffolders and cleanup tools that already know Laravel. Here are the ones I run most.

How to install

LaraClaude installs through Claude Code's plugin system. Add the marketplace once, then install, so you get updates later:

/plugin marketplace add edulazaro/laraclaude
/plugin install laraclaude@edulazaro

Or grab it directly from GitHub:

/plugin install github:edulazaro/laraclaude

You need Claude Code and a Laravel project. That is it for most skills; a couple that hit a live database also want Docker.

Audit before you change anything

Most skills default to a read-only report and only touch files when you add fix, so start by looking. /lc:find-n-plus-one scans your Blade views, Livewire components and controllers for a relationship accessed inside a loop, traces it back to the query that built the collection, and tells you the exact with() to add.

/lc:find-n-plus-one

/lc:security-audit is the other one I run on any project I inherit. It looks for SQL injection, XSS, mass-assignment and secrets committed to the repo, and like most fixable skills it takes a preview flag before it changes anything.

/lc:security-audit                 # report
/lc:security-audit fix --dry-run   # preview the fixes
/lc:security-audit fix             # apply, with confirmation

Clean up what has piled up

Every long-lived Laravel app accumulates migration cruft: a create followed by twenty add_column and change_column files. /lc:consolidate-migrations groups them by table, classifies each table as safe to merge or not, and folds the ALTERs back into the original create while leaving data migrations alone.

/lc:consolidate-migrations              # analyze
/lc:consolidate-migrations fix --dry-run

It refuses to run against a production database and asks before deleting anything, which is the behavior you want from something rewriting your schema history. /lc:dead-code is its companion for the code side: unused classes, methods, routes and views.

Scaffold to your conventions, not a generic stub

The generators read how your project already does things instead of emitting a boilerplate stub. /lc:volt-component writes a Livewire Volt single-file component with the PHP block, validation and @text() strings in place and a single root element.

/lc:volt-component UserProfile

/lc:generate-crud goes wider and produces the whole stack for a model, migration through views, and /lc:generate-action creates a Laractions action and registers it on the model. There is even /lc:generate-scraper, which reads a real page and fills a Larascraper class from its actual markup.

Understand an unfamiliar app

Two I reach for on a codebase I do not know yet. /lc:model-diagram renders a Mermaid ER diagram of your Eloquent models and their relationships, which is the fastest way to see how everything connects.

/lc:model-diagram

And /lc:analyze-model Property dumps one model completely: its relationships, casts, scopes, observers and the problems it notices. When something is already broken at runtime, /lc:analyze-error takes the stacktrace and finds the root cause rather than the symptom.

Wrapping up

LaraClaude is over thirty of these, from /lc:deploy-checklist to /lc:api-docs, all following the Agent Skills standard so they are just Markdown you can read. It turns the Laravel context you keep re-explaining into commands Claude Code runs on demand.

👉 On GitHub at https://github.com/edulazaro/laraclaude

Add tags and categories to any model with Laraterms

Eduardo Lázaro — Thu, 06 Aug 2026 00:28:42 +0000

Sometimes you need tags on a model. The usual answer is a tags table, a pivot, a slug and a belongsToMany, and you write it again in the next project with slightly different columns. Laraterms replaces that with a config entry and a trait, and it comes with the parts you normally bolt on later: hierarchy, per-tenant isolation and translations.

This is the simple path first, then the two features you reach for next.

How to install

One package, its config and two migrations.

composer require edulazaro/laraterms
php artisan vendor:publish --tag=laraterms-config
php artisan vendor:publish --tag=laraterms-migrations
php artisan migrate

Step 1: define a taxonomy

A taxonomy is a kind of label, declared in config/laraterms.php. Start with a flat tags taxonomy; the file already ships one you can keep.

'taxonomies' => [
    'tags' => [
        'hierarchical'        => false,
        'max_terms_per_model' => null,
        'scope'               => 'tenant',
    ],
],

Step 2: tag a model

Add the HasTerms trait and the model can hold terms. Attaching is find-or-create: pass a label, and the term is created the first time and reused afterwards.

use EduLazaro\Laraterms\Concerns\HasTerms;

class Post extends Model { use HasTerms; }

$post->attachTerm('Laravel', 'tags');
$post->attachTerms(['Laravel', 'PHP'], 'tags');
$post->syncTerms(['Laravel', 'Vue'], 'tags');   // replace the tag set
$post->termsIn('tags');                          // read them back

Filtering by tag is a query scope, so it composes with the rest of your query.

Post::whereHasTerm('laravel', 'tags')->get();
Post::whereHasAllTerms(['laravel', 'tutorial'], 'tags')->get();

Hierarchical categories

Set hierarchical => true on a taxonomy and its terms form a tree. Read the whole tree in one query, and walk a term's ancestry.

'categories' => [
    'hierarchical'        => true,
    'max_terms_per_model' => 1,
    'scope'               => 'tenant',
],

use EduLazaro\Laraterms\Support\TermTree;

$tree = TermTree::for('categories');   // roots with children, one query
$term->breadcrumb(' > ');              // "Tech > Web > Laravel"

The max_terms_per_model => 1 above is enforced: attaching a second category throws a TooManyTermsException instead of quietly allowing two.

Keeping tenants apart

The scope => 'tenant' in each taxonomy means terms are isolated per tenant, which is the feature you would otherwise hand-roll with an organization_id on every query. Tell Laraterms how to find a model's tenant once, in a service provider.

use EduLazaro\Laraterms\Facades\Laraterms;

Laraterms::resolveScopeUsing(fn ($model) => $model->organization);

Now a tag created in one organization is invisible to another, and the same label in two organizations is two separate terms. For taxonomies that really are shared across everyone, like languages, set scope => 'global' instead.

Wrapping up

That is tags, categories and tenant isolation without a single pivot table of your own: a config entry per taxonomy, the HasTerms trait, and attach and query calls. It also does translations and cross-locale search on the same two tables when you need them.

👉 Package on Packagist: https://packagist.org/packages/edulazaro/laraterms
👉 Source on GitHub: https://github.com/edulazaro/laraterms

Add Livewire modals in Laravel with Wiremodal

Eduardo Lázaro — Wed, 05 Aug 2026 09:53:00 +0000

Wiremodal is a framework-agnostic modal package for Laravel, which allows to handle modals, so you don't have co configure them in all your projects.

It ships a few Livewire-side helpers that make exactly this pleasant. This post is the Livewire integration end to end: opening and closing from PHP, delivering a payload on open, the one trap to avoid, and the optional form panel for when a modal happens to be a form.

How to install

Pull the package in and get the assets onto the page.

composer require edulazaro/wiremodal
php artisan vendor:publish --tag=wiremodal-assets

The service provider auto-registers and there is no config file. Point your layout at the published files:

<link rel="stylesheet" href="{{ asset('vendor/wiremodal/css/wiremodal.css') }}">
<script src="{{ asset('vendor/wiremodal/js/wiremodal.js') }}" defer></script>

If you bundle with Vite, skip the publish and import straight from the vendor directory instead, so a package update flows through without re-publishing anything:

/* resources/css/app.css */
@import "../../vendor/edulazaro/wiremodal/resources/css/wiremodal.css";

// resources/js/app.js
import '../../vendor/edulazaro/wiremodal/resources/js/wiremodal.js';

Opening and closing from Livewire

Define the modal once with the <x-wiremodal> component, give it a name, and fill the body and footer slots. Here is a delete confirmation:

<x-wiremodal name="confirm-delete" title="Delete record?" size="sm">
    <x-slot:body>
        <p>This action cannot be undone.</p>
    </x-slot:body>
    <x-slot:footer>
        <button type="button" data-wm-dismiss>Cancel</button>
        <button type="button" wire:click="destroy">Delete</button>
    </x-slot:footer>
</x-wiremodal>

The Cancel button carries data-wm-dismiss, and any element with that attribute closes the modal it sits in, so you never write a cancel handler. To open and close from the component itself, use the macros the package registers on every Livewire component:

public function confirmDelete(): void
{
    $this->openModal('confirm-delete');
}

public function destroy(): void
{
    // delete the record...
    $this->closeModal('confirm-delete');
}

That is the whole open and close cycle from the server, and there is nothing to import: openModal and closeModal are macros wiremodal adds for you.

Handing the modal a payload

A confirmation needs no data, but most modals do: the row you clicked. openModal() takes a second argument, and Wiremodal delivers it to the modal through a wiremodal:opened event whose detail is { name, data }, fired on both the modal element and window. You read it with a one-line Alpine handler.

public function view(int $id): void
{
    $task = Task::findOrFail($id);

    $this->openModal('task-detail', [
        'id'    => $task->id,
        'title' => $task->title,
    ]);
}

<x-wiremodal name="task-detail" title="Task" size="md"
    x-data="{ task: {} }"
    @wiremodal:opened.window="if ($event.detail.name === 'task-detail') task = $event.detail.data || {}">
    <x-slot:body>
        <p x-text="task.title"></p>
    </x-slot:body>
    <x-slot:footer>
        <button type="button" data-wm-dismiss>Close</button>
    </x-slot:footer>
</x-wiremodal>

The if ($event.detail.name === ...) guard matters because the event fires on window for every modal, so each one only reacts to its own payload. The panel fills with the right row the instant it opens.

The positional-dispatch trap

There is one mistake worth calling out, because it fails silently. Do not skip the macro and dispatch the browser event yourself with a positional string:

// Silently never opens the modal
$this->dispatch('open-wiremodal', 'task-detail');

Livewire wraps that positional string into an array, so the browser receives e.detail = ['task-detail']. Wiremodal's parser accepts a bare string or an object with a name key, never an array, so the modal just never opens and no error is thrown. The openModal() and closeModal() macros exist precisely to avoid this, since they dispatch with named arguments under the hood. If you ever dispatch by hand, use the named form:

$this->dispatch('open-wiremodal', name: 'task-detail', data: ['id' => 42]);

When the modal is a form

Everything above works for any modal. When the modal happens to be a form and you want native submission, the Enter key and a real submit button, add as="form". It renders the panel as a <form> instead of a <div>, so wire:submit fires on submit and the autofocus attribute is honored.

<x-wiremodal name="edit-task" title="Edit task" size="md"
    as="form" wire:submit="save"
    x-data
    @wiremodal:opened.window="
        if ($event.detail.name === 'edit-task') {
            $wire.set('editingId', $event.detail.data.id);
            $wire.set('title', $event.detail.data.title);
        }
    ">
    <x-slot:body>
        <label>
            Title
            <input type="text" wire:model="title" autofocus>
        </label>
    </x-slot:body>
    <x-slot:footer>
        <button type="button" data-wm-dismiss>Cancel</button>
        <button type="submit">Save</button>
    </x-slot:footer>
</x-wiremodal>

public ?int $editingId = null;
public string $title = '';

public function save(): void
{
    Task::findOrFail($this->editingId)->update(['title' => $this->title]);
    $this->closeModal('edit-task');
}

You open it exactly as before with openModal('edit-task', [...]); the only difference is as="form" turning the panel into a real form so Enter and the submit button drive wire:submit. Without it you would hang a wire:click on the Save button instead. That is the point: the form is one prop, not the price of entry.

Sizes and persistent modals

Two props round it out. size takes one of eleven named widths and defaults to 2xl (42rem), running from xs (20rem) to 7xl (80rem); a value outside the catalog throws an InvalidArgumentException at render, so a typo fails loudly instead of producing a wrong-sized box.

Use fullscreen to fill the viewport. And persistent makes a modal ignore overlay clicks and the ESC key, so a wizard step or a you must choose prompt only closes through an explicit data-wm-dismiss button or a programmatic closeModal().

<x-wiremodal name="preview" size="4xl">
<x-wiremodal name="finish-checkout" title="Confirm order" persistent>

👉 Package on Packagist: https://packagist.org/packages/edulazaro/wiremodal
👉 Source on GitHub: https://github.com/edulazaro/wiremodal

GDPR cookie consent in Laravel with Wirecookies

Eduardo Lázaro — Sun, 02 Aug 2026 12:17:00 +0000

Ship a compliant cookie banner in Laravel and actually gate analytics and marketing scripts on the user's choice, using the wirecookies-saved event and a plain localStorage object as the consent gate.

Wirecookies is a Laravel package which handles the cookies consent for you. It gives you a consent banner and a preferences modal from a single Blade tag, and, more usefully, it hands you a plain localStorage object and a browser event you can use as the gate for your analytics and marketing scripts. This article is built around that gate, not around how the banner looks.

One thing to get out of the way first, because it will bite you otherwise: Wirecookies ships no JavaScript of its own and uses wiremodal's JS to open the preferences modal. If you skip the wiremodal import in the install steps, the banner still shows and Accept all / Reject all still work, but the Configure button and the floating re-open button silently do nothing, with no error in the console. Do the JS step.

How to install

Pull the package in with Composer. The service provider is auto-discovered, so there is nothing to register.

composer require edulazaro/wirecookies

Wirecookies depends on edulazaro/wiremodal, which Composer pulls in for you. Now import the stylesheet in resources/css/app.css, after a wire* base (wiremodal or wiretoast) that defines the theme tokens.

/* resources/css/app.css */
@import '../../vendor/edulazaro/wiremodal/resources/css/wiremodal.css';
@import '../../vendor/edulazaro/wirecookies/resources/css/wirecookies.css';

Then bundle wiremodal's JS. This is the step that makes the Configure and re-open buttons work, so do not skip it.

// resources/js/app.js
import '../../vendor/edulazaro/wiremodal/resources/js/wiremodal.js';

How to use it

Drop the single Blade component once, near the end of your layout.

<x-wirecookies :policy-url="route('cookies')" />

First-time visitors get a bottom banner after a short delay. When they choose Accept all, Reject all, or save from the Configure modal, the banner is replaced by a floating button that reopens the preferences panel so they can change their mind later. That is the whole UI. The interesting part is what it writes down.

Gating scripts on consent

This is the reason to reach for a real consent tool instead of a static banner. Wirecookies stores the choice as a plain object in localStorage under the key cookie-preferences, shaped like this:

{ "essential": true, "analytics": false, "marketing": false, "functional": false }

So on the page load you read that object and only boot analytics if the user actually said yes.

const prefs = JSON.parse(localStorage.getItem('cookie-preferences') || '{}');

if (prefs.analytics) {
    // load Google Analytics, Plausible, whatever
}

That covers returning visitors who already decided. For the first visit, or when someone changes their choice in the modal, there is nothing in storage yet at load time, so you also listen for the moment they save. Wirecookies dispatches a wirecookies-saved event that bubbles up to window, and its detail is the preferences object.

window.addEventListener('wirecookies-saved', (e) => {
    if (e.detail.analytics) {
        // enable analytics now that they opted in
    }
    if (e.detail.marketing) {
        // fire marketing pixels
    }
});

Between those two, the load-time read and the save-time event, you have a complete gate. Scripts stay dormant until the matching category is true, and they light up the instant the user grants it, without a page reload. There is no package API to learn for any of this: it is a localStorage key and a DOM event, both of which you already know how to use.

Configuring the categories

The categories are defined in config, so publish it if you want to change them.

php artisan vendor:publish --tag=wirecookies-config

That drops config/wirecookies.php, where each category carries behavior only. essential is required and can never be turned off; the rest are opt-in with a default of false, which is what keeps everything switched off until the user acts.

'categories' => [
    'essential'  => ['required' => true,  'default' => true],
    'analytics'  => ['required' => false, 'default' => false],
    'marketing'  => ['required' => false, 'default' => false],
    'functional' => ['required' => false, 'default' => false],
],

The keys here (analytics, marketing, and so on) are the same keys you read off the preferences object in the gate above, which is what ties the config to your JavaScript. The visible label and description for each category come from the translation files, so you do not hard-code copy in config.

Pointing at your cookie policy

The other config key you will touch is the link to your policy. policy_url accepts a single string used for every language.

'policy_url' => '/cookies',

If your policy lives at a different path per language, pass an array keyed by locale and Wirecookies picks the right one from app()->getLocale().

'policy_url' => ['es' => '/cookies', 'en' => '/en/cookies'],

Set it to null and the link is hidden entirely. Every config key also has a matching component prop (policy-url, delay, categories, storage-key) if you would rather override it per render than edit the config file. The strings themselves ship in Spanish and English out of the box and follow the app locale, with a fallback to app.fallback_locale.

Wrapping up

The banner is the part everyone sees, but the part that keeps you compliant is refusing to load tracking until consent exists. Wirecookies makes that a two-line job: read cookie-preferences from localStorage on load, listen for wirecookies-saved on window, and gate each script on the category it needs. No account, no external script, no tracking of its own, just a plain object in the browser and an event you can hook.

📌 You can see Wirecookies in action at Crowd Legal.

👉 Package on Packagist: https://packagist.org/packages/edulazaro/wirecookies
👉 Source on GitHub: https://github.com/edulazaro/wirecookies

Localized routes in Laravel with Laralang

Eduardo Lázaro — Sat, 01 Aug 2026 16:46:46 +0000

Translating the text in a Laravel app is one problem, and allowing localized URLs is a different one. You want /dashboard in English and /es/panel in Spanish, both real routes that resolve, appear in route:list, and can be linked without knowing which language the visitor is on. Doing it by hand means a route group per language, duplicated definitions, and locale detection glued on top.

Laralang does that half. You declare a route once, list the languages, and it registers one real route per locale, names them, and keeps route() working. Here is the whole thing, including the parts that are easy to get wrong.

Install

composer require edulazaro/laralang
php artisan vendor:publish --tag="locales"

Publishing is not optional in practice. The config ships with a single locale, and both the middleware and the URL generator read the list from there, so until you fill it in your other languages are not recognised.

// config/locales.php
'locales' => ['en', 'es', 'fr'],

'prefixes' => [
    'en' => '',    // default language, no prefix
    'es' => 'es',  // /es/...
    'fr' => 'fr',  // /fr/...
],

Two rules about prefixes that save a debugging session.

The unprefixed language is config('app.locale'), not the first item in the array. If your app runs in Spanish, APP_LOCALE=es is what makes /contacto live at the root and /en/contact carry a prefix.

A value is the literal prefix, and without one the locale code is used. A missing key, null and an empty string all count as no value, so only the default language can end up at the root and two locales can never fight over the same URLs.

Declare a localized route

Swap Route::get for LocalizedRoute::get. The second argument is the locale list. A bare locale reuses the base path, and 'locale' => 'translated-path' gives that language its own URL.

use EduLazaro\Laralang\LocalizedRoute;

LocalizedRoute::get('dashboard', [
    'en',
    'es' => 'panel',
], [DashboardController::class, 'index'])->name('dashboard');

That registers /dashboard and /es/panel. Everything you chain applies to every generated route, so middleware, where constraints and the rest work as usual. There is a method per verb (get, post, put, patch, delete, options, any) plus match.

Resources work too, and this is where a package like this usually gives up:

use EduLazaro\Laralang\LocalizedResource;

LocalizedResource::make('photos', [
    'en',
    'es' => ['uri' => 'fotos', 'verbs' => ['create' => 'crear', 'edit' => 'editar']],
], PhotoController::class)->only(['index', 'show']);

Laravel's own resource registrar builds the routes, so only(), except(), names(), shallow() and scoped() keep working and apply to every language at once. You get /photos/create and /es/fotos/crear, and both are named photos.create under their locale.

Route names carry the locale

Every generated route is named {locale}.{name}, and there is no route registered under the bare name. Be explicit when you need a specific language:

route('es.dashboard');   // /es/panel
route('en.dashboard');   // /dashboard

And use the plain name everywhere else:

route('dashboard');      // whatever the current locale is

That works because Laralang replaces Laravel's URL generator. route('dashboard') looks for es.dashboard when the app locale is Spanish, and falls back to a route literally named dashboard if there is no localized one, which is what lets you mix Route::get and LocalizedRoute::get in the same app without thinking about it.

Active states in navigation keep working too, because routeIs() understands the naming:

request()->routeIs('dashboard');      // true on en.dashboard and on es.dashboard
request()->routeIs('es.dashboard');   // true only when you are on the Spanish one

Translated slugs, not just translated paths

This is where it stops being cosmetic. Route model binding accepts a different column per locale, so each language resolves its own slug:

LocalizedRoute::get('property/{property:slug_en}', [
    'en' => 'property/{property:slug_en}',
    'es' => 'propiedad/{property:slug_es}',
    'fr' => 'propriete/{property:slug_fr}',
], [PropertyController::class, 'show'])->name('properties.show');

/propiedad/piso-en-el-centro and /en/property/flat-in-the-centre hit the same controller with the same model, resolved through a different column. And because route() picks the localized route for the current locale, route('properties.show', $property) builds the right URL with the right slug without any branching in your views.

A package that registers a single route with a dynamic locale prefix cannot express this: there is one definition, so there is one binding field.

Every URL of the current page, in one call

Language switchers, hreflang tags and multi locale sitemaps are all the same question: what is this page called in the other languages?

@foreach(Laralang::alternates() as $locale => $url)
    <link rel="alternate" hreflang="{{ $locale }}" href="{{ $url }}" />
@endforeach

alternates() carries the current route parameters over, so dynamic segments survive, and it only returns the locales that actually have a route registered. A page that exists in two of your three languages produces two links instead of a dead one.

Groups and prefixes

The locale prefix always goes first, even inside a prefixed group:

Route::prefix('admin')->group(function () {
    LocalizedRoute::get('dashboard', [
        'en',
        'es' => 'tablero',
    ], [AdminController::class, 'index'])->name('admin.dashboard');
});

// /admin/dashboard
// /es/admin/tablero

Detecting the locale

Every route created by LocalizedRoute already carries the SetRouteLocale middleware, so the localized routes need no wiring. The middlewares matter for everything else: plain routes, and any part of the app with no locale in the path.

SetRouteLocale reads the locale from the route name or the URL prefix, and stores it in the session.
SetSessionLocale applies whatever the session holds. This is the one for an admin panel where the language is a user setting, not part of the URL.
SetBrowserLocale picks the best match from Accept-Language on first visit.
SetSmartLocale combines them: prefix when there is one, session or browser when there is not.

They are idempotent, so stacking them is safe.

Two behaviours worth knowing before they surprise you.

The default locale prefix is stripped with a 301. A request to /en/contact when English is the default redirects to /contact, so each page has one canonical URL.

Livewire and AJAX requests take the session path. Those hit an endpoint with no locale prefix, so SetRouteLocale delegates to the session, which the previous full page load already wrote. If a Livewire component ever renders in the wrong language while the page around it is fine, that session value is the thing to inspect.

Rescuing URLs before they 404

A URL gets shared without its prefix, or with the wrong one. /servicios reaches an app running in English, /es/services reaches one that expects the Spanish path. Both are a 404 by default, and both are a page you already have.

// config/locales.php
'fallback' => true,

Requested	Rescued to
`/servicios`	`/es/servicios`
`/fr/servicios`	`/es/servicios`
`/es/services`	`/services`

It only runs once the router has already failed, so normal traffic costs nothing, and the candidate URL is handed to the router rather than compared as a string, so routes with parameters are rescued too. Locales are tried with the default one first, so the destination depends only on the path and never on the visitor, which is what makes a permanent redirect safe here.

If your app has its own fallback route, leave the config off and call LocalizedRoute::fallback() yourself before it: Laravel runs the first fallback registered.

Prefixing every language

By default the main language lives at the root. Give it a prefix of its own and that stops:

'prefixes' => [
    'en' => 'en',   // /en/about
    'es' => 'es',   // /es/sobre-nosotros
],

Nothing is registered at / any more, so turn the fallback on and the root sends visitors to their own language, taken from their stored choice and then from Accept-Language. That one is a 302 with Vary: Accept-Language, never a 301, because the destination depends on who is asking and a permanent redirect would be cached and pin a single language for everyone behind it.

Decide this before going live. Permanent redirects get cached by browsers and CDNs and are never re-checked, so changing the shape of your URLs later leaves returning visitors following redirects to pages that no longer exist. The package bounds that window with an explicit lifetime you control:

'redirect_max_age' => 86400,

Signed URLs that survive translation

A signed URL is built from the full URL, so a link generated in Spanish and validated in a request that switched to English fails the signature check. There is a signed_localized middleware for exactly that: it reads the locale from the route name, sets it, and then runs Laravel's own validation.

LocalizedRoute::get('/verify-email/{id}/{hash}', [
    'en' => '/verify-email/{id}/{hash}',
    'es' => '/verificar-email/{id}/{hash}',
], [VerifyEmailController::class, 'verify'])
    ->middleware(['signed_localized'])
    ->name('verification.verify');

Ziggy

If Ziggy 2 is installed, Laralang swaps its Blade route generator so the routes of the current locale are also published under their unprefixed name. route('dashboard') in JavaScript then behaves like it does in PHP, and a plain route already using that name is never overwritten.

Wrapping up

That is localized routing done: one declaration per page, translated paths and translated slugs, resources included, route() that follows the current language, hreflang in one call, and a fallback that rescues the URLs you would otherwise lose.

It runs on PHP 8.2 to 8.5 and Laravel 11, 12 and 13, with every combination tested on each push.

👉 Package on Packagist: https://packagist.org/packages/edulazaro/laralang
👉 Source is on GitHub: https://github.com/edulazaro/laralang

If you are coming from another localization package, the repo has a migration guide for mcamara/laravel-localization and another for niels-numbers/laravel-localizer.

Collecting user feedback in Laravel with Wirebug

Eduardo Lázaro — Sat, 01 Aug 2026 05:56:58 +0000

Add a feedback widget to an existing Laravel app and end up with a queryable inbox, with automatic technical context and no design work.

The goal for this post is small. Adding a feedback widget to your Laravel app, having a queryable inbox of reports sitting in your own database. No design work, no third-party service, no schema you have to write yourself.

The package doing the work is Wirebug. It drops a widget into your app that lets users report a bug, a suggestion or anything else, attaches an optional screenshot or screen recording, and collects the technical context automatically. Every report is a plain Eloquent row you can read however you like.

How to install

Wirebug is a Composer package, and it registers its own migration, so there is nothing to publish before you can run it.

composer require edulazaro/wirebug
php artisan migrate

It needs PHP 8.2+, Laravel 11+ and Alpine.js on the page. You also import the CSS in your bundle, wiremodal first and wirebug second, since wirebug builds on wiremodal's styles.

@import '../../vendor/edulazaro/wiremodal/resources/css/wiremodal.css';
@import '../../vendor/edulazaro/wirebug/resources/css/wirebug.css';

If your widget only lives behind a login, publish the config and lock the endpoint down. The submit route ships with web and a throttle by default, and you add auth yourself.

php artisan vendor:publish --tag=wirebug-config

// config/wirebug.php
'route' => [
    'enabled'    => true,
    'path'       => 'wirebug',
    'middleware' => ['web', 'auth', 'throttle:10,1'],
],

How to use it

The integration is one Blade component. Put it in a layout and pick the shared theme once on the root element.

<html data-wire-theme="studio">
    ...
    <x-wirebug />

Because attachments matter for this angle, the first thing worth configuring is where they go. Screenshots and recordings are written through Laravel's Storage, and the report row keeps only the path, so pointing them at S3 or an S3-compatible R2 disk instead of the local filesystem is a config change and nothing else.

// config/wirebug.php
'uploads' => [
    'disk'   => 's3',       // any disk from config/filesystems.php
    'path'   => 'wirebug',
    'max_kb' => 5120,       // 5 MB screenshot cap
],

The screenshot accepts jpg, png, gif and webp. SVG is rejected on purpose, since an uploaded SVG is an XSS vector and there is no reason to accept one for a bug report.

Reading the reports

This is the part the whole post is building toward. A report is an EduLazaro\WireBug\Models\BugReport, and the model ships the scopes you need to build a triage screen with no extra code. A fresh report has a status of new, so an inbox of things you have not looked at yet is one line.

use EduLazaro\WireBug\Models\BugReport;

$inbox = BugReport::new()->latest()->get();

Filtering by type

The selector offers a few report types, and you filter by them with ofType. There is one trap to know about. The type keys are bug, idea and other, and the middle one is labelled "Suggestion" in the UI, so the query for suggestions is ofType('idea'), not ofType('suggestion').

$bugs        = BugReport::ofType('bug')->get();
$suggestions = BugReport::ofType('idea')->get();   // not 'suggestion'

Who sent it

Each report has a polymorphic reporter relation. It resolves through your app's morph map, so it hands you back whatever model actually submitted the report, a User, a Client, or whatever you have mapped. For a guest who was not logged in, it is simply null.

foreach ($inbox as $report) {
    $who = $report->reporter?->name ?? 'Guest';
}

Reaching a guest who left no account

Because a guest has no reporter to attach, Wirebug shows non-authenticated visitors an optional email field so you can still reply. Authenticated users never see it, since you already know who they are. That field is on by the ask_guest_email config flag, and the value lands on the report row for you to read next to the null reporter.

What gets captured automatically

Every report carries technical context that the user never typed. Wirebug records the current URL, the user agent, the viewport, the app locale and the referer, which together are usually enough to reproduce a problem without a single follow-up question. The whole block is behind the capture_context config flag, so if you would rather not store any of it you flip one boolean.

The recording and wire:navigate

Wirebug can capture a screen recording using the browser's native getDisplayMedia and MediaRecorder, capped by config at ninety seconds, fifty megabytes and a two megabit bitrate. Nothing records until the user clicks, and the record button only shows up on desktop browsers that support the API.

The one operational detail to know is that the recording lives in the page's JavaScript context. It survives wire:navigate navigation, so a user can keep recording as Livewire swaps pages, but a hard reload throws the context away and ends the recording. That is a browser limit, not something to work around.

When a submit succeeds, Wirebug dispatches a wirebug-sent event on window, which is a convenient place to fire a toast or a tracking call. Add the component, point the disk where you want it, and you have a feedback inbox you can query with Eloquent.

👉 Package on Packagist: https://packagist.org/packages/edulazaro/wirebug
👉 Source on GitHub: https://github.com/edulazaro/wirebug