DEV Community: Eduardo Lázaro

True Randomness in Laravel with Lararand

Eduardo Lázaro — Mon, 31 Aug 2026 02:19:10 +0000

Here is a line of PHP that deals a card from a tarot deck. It is wrong.

$card = ord(random_bytes(1)) % 78;

Not wrong in the way a linter finds. It returns a number between 0 and 77 every single time. It never throws. Every test you would think to write about it passes: the range is right, the values are distinct, the distribution looks fine if you eyeball a hundred draws.

It is wrong in the way that only shows up if you count.

The arithmetic

A byte holds 256 values. A deck holds 78. 256 is not a multiple of 78.

The largest multiple that fits is 234, which is 78 × 3. So bytes 0 to 233 cover the deck three times, evenly, no argument. And then there are 22 bytes left over: 234 to 255. Those wrap around and land on cards 0 to 21 a fourth time.

Count it up:

22 cards appear 4 times per 256 bytes
56 cards appear 3 times per 256 bytes

That is 22 × 4 + 56 × 3 = 256. The books balance, and 22 of your 78 cards come up 33% more often than the other 56. Forever. In production. Silently.

If you are dealing tarot, The Fool through The Devil are favoured over everything after them. If you are running a raffle, the first 22 ticket holders are. If you are picking a shard, one in three of them gets a third more traffic than the rest.

Why no test catches it

Because the tests you naturally write are about the shape of the answer, and the shape is perfect.

$this->assertGreaterThanOrEqual(0, $card);
$this->assertLessThan(78, $card);

Passes. Always will.

The test that catches it has to be about the distribution, and it has to be exhaustive rather than statistical. A statistical test of a 33% skew on 22 of 78 outcomes needs a lot of samples before it fires, and it will be flaky when it does.

The exhaustive one is easy once you see it. Feed every byte value through and count:

$counts = array_fill(0, 78, 0);

foreach (range(0, 255) as $byte) {
    $counts[$byte % 78]++;
}

// [4, 4, 4, ... 3, 3, 3]

Twenty-two fours and fifty-six threes, staring at you.

The fix, and why it belongs in one place

Rejection sampling. Throw away the bytes that land in the uneven tail and draw again:

$limit = intdiv(256, 78) * 78;   // 234

do {
    $byte = ord(random_bytes(1));
} while ($byte >= $limit);

$card = $byte % 78;

Now every one of the 78 outcomes gets exactly three of the 234 surviving bytes. The cost is a redraw on 22 of 256 bytes, 8.6% of the time, and the answer is right.

The important part is not the four lines. It is that they should exist once in a codebase, not in every place that turns bytes into a number. The bug is not hard. The bug is that it is invisible, so every function that rediscovers it has an even chance of rediscovering it wrongly, and none of them will tell you.

The same mistake, wearing a different hat

Shuffling has an identical trap.

// Wrong
for ($i = 0; $i < $n; $i++) {
    $j = random_int(0, $n - 1);
    [$a[$i], $a[$j]] = [$a[$j], $a[$i]];
}

That swaps each position with any position. It looks more random than the correct version, which is exactly why people write it. It produces nⁿ execution paths spread over n! possible orderings, and for every n above 2 those do not divide. Some permutations come out more often than others.

The correct version swaps with a position at or below the current one, walking down:

for ($i = $n - 1; $i > 0; $i--) {
    $j = below($i + 1);          // 0..$i, unbiased
    [$a[$i], $a[$j]] = [$a[$j], $a[$i]];
}

Same class of bug. Same silence. nⁿ over n! is the modulo bias again with more steps.

Why I ended up writing a package

I was building a tarot site where the whole claim is that nobody arranged the outcome. That put two problems on the table at once.

The first is the one above: the arithmetic has to be right, and it has to be right in one place.

The second is stranger, and it is the actual reason the package exists. For most software, random_int is the correct and final answer. It is the system CSPRNG, it is what every session id on the box already rests on, it costs nothing, and it cannot be down. If you are choosing a shard or picking a placeholder avatar, stop reading, you are done.

But sometimes the origin of the randomness is part of what you are selling. A draw someone could contest. A shuffle a regulator asks about. And there:

"Our lottery runs on quantum vacuum noise measured at the Australian National University" is a sentence you can put in front of a customer.

"We called random_int" is not, even though it is a better answer technically.

The ANU publishes a free endpoint that measures vacuum fluctuations. random.org sells atmospheric noise. Both are real, both are lovely, and both introduce a problem you did not have five minutes ago: a draw that fails in front of a customer is worse than one drawn locally.

So the source became a config line:

'chain' => ['anu_public', 'anu_quantum', 'random_org', 'system'],

Tried left to right, first one that answers serves the bytes. The last entry is the one with nothing underneath it: put system there and a draw can never fail, leave it out and a draw fails loudly when every provider does. Which of those you want is a real decision, and it should be visible in a config file rather than hidden behind a boolean called fallback that secretly means "the CSPRNG".

The package

It is lararand, MIT, PHP 8.2 and Laravel 12.

composer require edulazaro/lararand

use EduLazaro\Lararand\Facades\Rand;

Rand::below(78);          // 0 to 77, no modulo bias
Rand::int(1, 6);          // both ends included
Rand::distinct(6, 49);    // six of 49, no repeats
Rand::shuffle($deck);     // an actual permutation
Rand::one($items);

One contract, and it is bytes. Everything else is derived by the package, because the derivation is where the bug lives.

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

AI agents in Laravel with Laragents

Eduardo Lázaro — Thu, 27 Aug 2026 16:56:54 +0000

Creating a call to an AI model is the easy part. A request, a JSON body, a content field on the way back. If that were the work, nobody would need a package.

The work is everything around it, and it is the same work in every product that ships an assistant: a loop that runs your tools and knows when to stop, conversations that survive their own context window, memory that outlives a session, rules somebody wrote that outrank whatever the model feels like doing, and agents that fire on your events instead of waiting to be typed at.

I wrote all of that twice, in two applications, and the second time I extracted it. It is called laragents.

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

The loop

A model that can call tools does not answer in one go. It asks for a tool, you run it, you hand back the result, it asks for another, and eventually it writes prose. That cycle is the thing.

$response = $loop->run(
    messages: $compressor->buildHistory($session, $systemPrompt),
    model: 'gpt-4.1-mini',
    session: $session,
    context: ToolContext::make(['organization' => $org, 'user' => $user]),
    tools: $registry->definitions(),
);

Two things in there are not obvious until they cost you something.

The iteration cap. A model that keeps reformulating the same failing search will loop until something times out, and every turn is billed.
The empty-streak guard, which is the more interesting one. The cap stops the spiral, but it stops it in the worst way: several calls spent and no answer. So after two consecutive tool results that found nothing, the loop appends a hint telling the model to say so rather than search again.

How it decides a result is empty is the part I like. A package cannot know what your tools return, so it reads the shape: a result carrying items, results, matches or whatever you configure is a search and gets judged. A result carrying none of those says nothing either way, which matters more than it sounds. A tool that files a document neither found nor failed to find anything, so it must not reset the streak. One bookkeeping call between two dead searches would otherwise hide the spiral completely.

Tools are yours

A tool talks about your domain, so the package does not bring any. It brings the class:

class ListProperties extends Tool
{
    public function name(): string
    {
        return 'list_properties';
    }

    public function description(): string
    {
        return 'List the properties on the market for this office. '
             . 'Does not book viewings: use schedule_viewing for that.';
    }

    protected function schema(): array
    {
        return ['max_price' => JsonSchema::integer()->description('Upper bound in euros.')];
    }

    public function execute(array $args, ToolContext $context): array
    {
        $office = $context->require('office');

        return ['items' => $office->properties()->where('price', '<=', $args['max_price'])->get()->toArray()];
    }
}

That second sentence in the description is worth more than the rest of it. Models pick neighbouring tools when the boundary is unstated.

The two parameters are two different trust levels, and this is the one thing I would want a reader to take away. $args is what the model asked for: text a language model produced, possibly steered by whatever the user pasted into the chat. $context is what your application put there. Take identity and scope from the second, never the first.

Why a bag and not typed parameters? Because the application this came from declared its tools as execute(array $args, ?CaseModel $case, Organization $org), which is two application models nailed into an interface implemented by 95 tools. Adding a third piece of context meant editing all 95, and no package can ever host that signature: a package cannot know what a case is.

Conversations that do not grow forever

Every turn replays the whole conversation, so a chat that goes well gets more expensive per turn until it hits the context limit and stops working entirely.

$messages = $compressor->buildHistory($session, $systemPrompt);

Under the token budget, everything goes verbatim. Over it, the older turns are summarised once by a cheap model and the summary is reused from then on.

Two deliberate refusals in there. It never compresses the most recent turns, whatever the budget says, because that is where the thread of the exchange lives and a summary of "what we just said" is where these systems get vague. And it never touches tool calls or their results: those belong to the turn that produced them, and replaying them across turns is how a loop starts re-reading its own plumbing.

Memory, which is the part that gets skipped

A conversation ends and everything it established goes with it. The user explained their situation on Tuesday and explains it again on Thursday.

Memories hang off three axes, and keeping them apart is what makes the table reusable:

tenant      whose it is: the firm, the workspace, the account
memorable   what it is about: a case, a project. NULL = the tenant as a whole
memory      who it applies to. NULL = everyone in that scope

The third one reads like access control and is not. Showing María's preference to Juan is not a leak, it is worse: the model starts behaving with Juan as if he were María. "María prefers bullet points" is not confidential, it simply does not apply to anybody else.

Writing them is a queued job, because it is another model call and charging the user's reply for the privilege of remembering it is how a chat gets slow. It fires when history compression happens, which is when a substantial amount has been said, and on a scheduled sweep for conversations that stopped before ever getting that far. Without the second one you remember long conversations and forget short ones, and short ones are most of them.

Reading them is one line, and it is the line people forget:

$prompt = implode("\n\n", array_filter([
    Rule::promptBlock($session),
    'You are the assistant of an estate agency.',
    Memory::promptBlock($session),
]));

Without it the table fills up and is never read, which looks exactly like the feature being disappointing rather than absent.

Rules

Same three axes, opposite treatment. A memory is distilled and weighed. A rule is written by a person and sent verbatim, at the top, worded as an order.

Rules answer a question that comes up in every product with an assistant in it: where does "our firm always does X" live? Not in the system prompt, because that is one string for everybody and this varies per tenant. Not in memory, because memory is weighed and might not surface. Not in a tool, because it is not an action.

They go above your own prompt, and memories below it. A directive buried under a wall of remembered context stops reading as a directive.

Agents that nobody opens

Agent::create([
    'tenant_type'    => 'organization', 'tenant_id' => $org->id,
    'name'           => 'Document triage',
    'system_prompt'  => 'Read the document, classify it, flag what is missing.',
    'event_triggers' => ['document.uploaded'],
    'allowed_tools'  => ['read_document', 'classify_document'],
    'config'         => ['model' => 'gpt-4.1-mini', 'max_tasks_per_day' => 200],
]);

app(AgentTrigger::class)->fire('document.uploaded', $document->organization, $document);

Or on a cron expression, checked from the last run rather than against the current minute, so a tick lost to a deploy is picked up next time instead of skipped for ever.

Two guards that exist because of two specific bad afternoons. A debounce, because observers fire on every save and one logical change written in three statements is three events, three answers and three invoices. And a daily ceiling, because an agent wired to an event its own tools cause is a loop, and the debounce does not save you there since each iteration is a genuinely new subject.

What it deliberately is not

Not a provider wrapper. There are two clients, OpenAI and Anthropic, and they exist because the loop needs something to call. If you want fifteen providers behind one interface, laravel/ai is the framework's own answer and is better at it than this will be. What laravel/ai does not have is any of the above: no memory, no rules, no schedules, no compression.

Not a metering package. There is a UsageRecorder contract and an adapter for larameter, and out of the box it records nothing, because a package should not start refusing calls because you have not wired your billing yet. Metering usually arrives bundled inside an AI package and that is the wrong place for it: you should not have to install an LLM client to meter a form submission.

Not opinionated about your models. Everything polymorphic is your morph alias, never the package's word. A scope you call matter is addressed as "matter" everywhere, including in the prompt that asks the model which scope a memory belongs to. Nothing has to be translated into our vocabulary, and nothing gets dropped for failing to translate.

Redaction, and the part everybody forgets

Turn on PII anonymisation and the conversation is tokenised on the way out and restored on the way back, tool arguments included, so your tools query the database with real values rather than searching for «AP_1» and finding nothing.

Most of these features are not providad by Laravel AI, so it's the main reason for this package.

👉 Source: github.com/edulazaro/laragents
👉 Documentation: edulazaro.com/portfolio/laragents

Instant search engine indexing in Laravel with LaraIndexNow

Eduardo Lázaro — Wed, 26 Aug 2026 06:03:49 +0000

You publish a post and then you wait. Your sitemap says here is everything I have, come back whenever, and the crawler comes back whenever. The page might there invisible for days.

IndexNow flips that around. It is a small protocol: you publish a key file on your domain, then POST the URLs that changed. Bing, Yandex, Seznam, Naver and Yep consume it, and one submission to the shared endpoint reaches all of them. Google does not participate, so this complements your sitemap, it does not replace it. If that alone rules it out for you, stop reading here.

Laraindexnow wires the protocol into Eloquent. You describe which records deserve a URL and under what conditions, and the package works out when to submit. This post walks through the whole thing.

How to Install

composer require edulazaro/laraindexnow
php artisan vendor:publish --tag=indexnow-config
php artisan indexnow:key --file

The last command generates a key, writes INDEXNOW_KEY to your .env the way key:generate writes APP_KEY, and drops the key file into public/. That file is the whole authentication story: if you can publish at https://yourdomain.com/{key}.txt, the domain is yours. There is no account to open.

The package also serves that URL through a route, so the file is optional. Generate it anyway: the web server hands a real file over without booting the framework, so it keeps answering while php artisan down returns a 503 for every route.

Then confirm it is reachable before you rely on it:

php artisan indexnow:verify

An unreachable key file is behind almost every rejection from the endpoint, and the endpoint itself tells you nothing useful about which half failed.

Tracking a model

use EduLazaro\IndexNow\Facades\IndexNow;

IndexNow::track(Post::class)
->url('blog.show')
->when('published');

That is the whole integration. No trait, no interface, nothing added to the model.

url() takes a route name and resolves it with the record bound to it, which covers most models. Anything that already looks like a URL is left alone, and a closure handles the rest:

->url('blog.show') // route('blog.show', $post)
->url('/about') // taken literally
->url(fn (Post $post) => route('blog.show', $post->slug))

There is also affects(), for the other URLs a write leaves out of date. Publishing a post changes the post page, but it also changes the index and the category listing:

->affects(['blog.index', fn (Post $post) => route('blog.category', $post->category)])

Conditions are the whole API

An attribute named on its own has to hold something true, and whenNot() is the opposite. Truth is read the way PHP reads it, so 1, "1" and true all pass while 0, "0", null and "" do not. A tinyint(1) column with no boolean cast comes back from MySQL as 1, and the same attribute is true when you just assigned it in PHP. Both have to read the same way, or your conditions work on a fresh record and not on a reloaded one.

->when('published') // holds something true
->whenNot('spam') // holds something false
->when('status', 'published') // holds that value
->when('comment_count', '>', 5) // compared
->whenIn('status', ['published', 'featured'])
->when(fn (Post $post) => $post->published_at?->isPast())

A counter reads nicely as a flag, so when('comment_count') is "has at least one".

Conditions on one registration combine with AND. Every one of them has to hold.

What actually triggers a submission

The package asks one question on every write. Did this record belong in the index before it, and does it belong after?

Before	After	Submitted
no	no	no
no	yes	yes, it entered the index
yes	yes	only if a content attribute changed
yes	no	yes, it left the index

That last row is the one people forget. A record leaving the index matters as much as one entering it: the URL now 404s or turns noindex, and the engines should be told to go and look. The same goes for a deleted record, and for a changed slug, where both the old URL and the new one go out.

The third row is where you keep the noise down. Not every write is a content change, and some applications rewrite half a table on a schedule:

->ignoring(['view_count', 'stats_cache', 'search_index', 'last_seen_at'])

A scheduled command that recomputes cached counters across a large table is the case that bites: without that list every row it touches counts as a content change, and one run becomes thousands of submissions. With it, the run is silent and a real edit still goes out.

Transitions, when the state is not enough

Sometimes the interesting thing is not what the record holds but what just happened to it:

->whenBecame('status', 'published') // it just took that value
->whenLeft('comment_count', 0) // it stopped holding zero
->whenIncrements('comment_count') // a number went up
->whenChanged('title', 'body', 'cover') // these changed, whatever the values

whenChanged() is the precise way to say what counts as content, and it is the inverse of ignoring(): a whitelist instead of a blacklist. If forgetting one column would flood the endpoint, prefer the whitelist.

Several ways in

Here is the case that breaks a single condition set. Say a page is worth indexing once it is approved and has at least one comment. Either half can be the one that arrives last: approval can come first and the comment later, or the other way round, and no single AND describes both.

Call track() again for the same model and you get a second registration. Registrations combine with OR: a write is submitted when any of them wants it.

IndexNow::track(Post::class)
->url('blog.show')
->whenLeft('comment_count', 0) // a comment arrived, already approved
->when('approved');

IndexNow::track(Post::class)
->url('blog.show')
->whenBecame('approved', true) // approval arrived, comments already there
->when('comment_count');

Writing that as one registration does not work: the two transitions would have to happen in the same write, which never does. The model is observed once however many registrations it has, and a URL two of them resolve is submitted once.

Submitting once, and remembering it

sets() writes an attribute on the record after its URL has been handed over. Put the same attribute in the conditions and the record drops out of the registration the moment it is written. Submitted once, ever, however many times you save it afterwards:

IndexNow::track(Post::class)
  ->url('blog.show')
  ->whenNot('index_now_sent')
  ->when('published')
  ->sets('index_now_sent');

Two things to know. The write is quiet, because a normal save would fire another event and the record, having just left the conditions, would go out a second time. And it means handed over, not accepted by a search engine: the buffer carries URLs and nothing else, so by the time a submission succeeds or fails there is no record left to point back at. Listen for SubmissionFailed if a failure has to undo it.

A flag like this is the wrong tool when a page should be resubmitted after an edit, since a written record never comes back. For that, declare the edit as its own registration with whenChanged().

The gap you need to know about

Eloquent events do not fire for query builder writes. This publishes a hundred posts and submits nothing:

Post::where('scheduled_for', '<=', now())->update(['published' => true]);

No model is instantiated, so no observer runs. That is Eloquent, not this package, and the answer is indexnow:sync:

php artisan indexnow:sync Post --limit=1000 --dry-run

It walks the table, evaluates the same conditions the observer uses, and submits what matches. There is no second copy of the rule to keep in step. Pair it with sets() and each pass only picks up what is left, which makes a backfill of a large table resumable. A dry run never writes.

The other direction is seeding and importing, where you want the writes but not the noise:

IndexNow::withoutSubmissions(function () {
    Post::factory()->count(50_000)->create();
});

Buffering, queueing and deduplication

Model events do not send HTTP requests. They push URLs into a cache backed buffer and schedule one delayed job to drain it, so saving a hundred rows produces one request rather than a hundred.

The same URL is not submitted twice within the deduplication window. Editing a post five times in ten minutes is one submission. Keep that window short, an hour by default: it is an anti-bounce measure, not a record of what is already indexed, and a long window swallows real edits. Publish at 09:00 with a 24 hour window and the correction you make at 15:00 never goes out.

Retries live on the job. A 429 is released with the endpoint's own Retry-After, and a 5xx backs off at 1, 5 and 15 minutes. A rejected key or a malformed URL is never retried, because retrying will not fix it.

Testing

$fake = IndexNow::fake();

$post->update(['status' => 'published']);

$fake->assertSubmitted(route('blog.show', $post->slug));
$fake->assertSubmittedCount(1);
$fake->assertNothingSubmitted();

fake() swaps the transport and bypasses the queue, so assertions work without a worker.

Not from your laptop

Submissions only happen in the environments listed in the config, production by default. That guard is what stops a development machine from asking search engines to crawl URLs that resolve on localhost, and it is the first thing to check when nothing is going out.

For a staging machine that should exercise the whole path without talking to the endpoint, set driver to null and log to log. To stop submissions in production without deploying, set INDEXNOW_ENABLED=false and clear the config cache.

Wrapping up

That is the surface. track() to register, url() to name the page, conditions to say when it counts, a second track() when there is more than one way in, and indexnow:sync for everything Eloquent never saw.

👉 Package on Packagist.
👉 Source on GitHub.

Written against version 1.4. If you try it and something is missing, open an issue.

Credits, plans and quotas in Laravel with Larameter

Eduardo Lázaro — Mon, 24 Aug 2026 03:21:48 +0000

If your app sells an allowance, a number of credits a month, or a number of documents, or a number of anything. Whatever it is, you end up writing a balance somewhere, a reset when the period rolls over, a check before the expensive call, and a usage screen that has to agree with all of it.

None of that is hard on its own. What gets you is that the pieces drift. The plan says a thousand a month, the reset runs on the first of the month, the subscription renews on the 18th, and the screen sums a table that the charging code stopped writing to two features ago. And then somebody adds a weekly cap and now there are two numbers per plan to keep consistent, times seven plans.

So after repeating the same on many apps, just created Larameter. It's basically what you see in Claude or OpenAI subscription plans. It meters credits against a plan, enforces ceilings on things that exist rather than things that are spent, and works out which plan an account is on instead of storing it.

How to install

Just install the package via composer as usually:

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

Then add the trait to whatever you bill. An organisation, a user, a workspace: the package does not care, and it does not need a column on your table.

use EduLazaro\Larameter\Concerns\HasCredits;

class Organization extends Model
{
    use HasCredits;
}

The account row appears the first time you touch it.

What are allowances

One period is rarely enough. A monthly figure alone lets a bad afternoon eat the month, so you want a weekly cap on top, and maybe a per-session one. Declare those windows once:

'windows' => [
    'session' => ['minutes' => 300, 'anchor' => 'rolling', 'share' => 0.04],
    'weekly'  => ['days' => 7,      'anchor' => 'fixed',   'share' => 0.25],
    'monthly' => ['months' => 1,    'anchor' => 'fixed',   'share' => 1],
],

And then a plan grants 1 figure, which every window takes a share of:

'plans' => [
    'free' => ['credits_monthly' => 1_000],
    'pro'  => ['credits_monthly' => 50_000, 'limits' => ['members' => 25]],
],

50,000 a month is 12,500 a week and 2,000 a sitting, and raising the plan raises all 3 at once. The alternative, a figure per window per plan, is 7 plans times 3 numbers to keep consistent: the day somebody doubles the monthly and forgets the weekly, the weekly quietly becomes the binding constraint and nothing tells you.

The tightest window is the one that binds. A window with no share narrows nothing. Declare no windows at all and you have opted out of allowance metering entirely: usage is still recorded, nothing is refused, and only purchased credits mean anything.

Rolling and fixed are not interchangeable

Here is a description of the basic usage window terms:

anchor decides when the next window starts, and picking the wrong one is the kind of bug users write in to complain about.
rolling starts the moment credits are next spent after the old one expired, so the full length is always available. That is what a session wants: on a fixed grid, starting 10 minutes before a boundary hands somebody 10 minutes, and it reads as the product having robbed them.
fixed sits on a grid laid down from the first window and moves on whether it is used or not. That is what a week wants, because when does my week reset needs an answer that is not depends when you last stopped. A dormant account gets 1 allowance back on its return, not 4.

One rule that falls out of this and matters more than it looks: asking never opens a window. For a rolling window the row is the clock, so an expired one is reported as full without being restarted. Otherwise opening the app to check your balance would burn the session before a word was typed.

Nothing to synchronise

There is no webhook here, and nothing to call when a subscription renews. A billing period and a credit window are separate clocks and neither has to know about the other:

The window resets on its own grid, lazily, the next time credits are charged. An account whose month began on the 28th resets on the 28th, for ever, without anybody telling it to.
The plan is worked out on every request. Stop paying and the provider stops finding a subscription, so the allowance drops to whatever the next provider says. Pay 4 days late and it comes back mid-window.

Tying them together would break the ordinary case rather than improve it: an annual subscription usually grants a monthly allowance, and a window anchored to the billing period would reset it once a year.

Charging: a price by name, or a rate per unit

2 doors. An action has a fixed price:

$org->credits()->charge('create_form', actor: $user);

And consumption is priced per unit in and out:

$org->credits()->meter('gpt-4o', 'token', $inputTokens, $outputTokens);

Everything is expressed in credits, rates included:

'prices' => ['create_form' => 2, 'send_email' => 1],

'rates' => [
    'gpt-4o' => ['input' => 25_000, 'output' => 100_000],
],

That reads as 25,000 credits per million input tokens. What a credit is worth in money is your business and the package never asks.

2 behaviours that read in opposite directions, on purpose. An action you never priced is free, because a package should not invent a price for something you did not write down. A metered unit you never priced still costs something, because the alternative is that metering an unknown model is free and the gap only shows up on your provider's invoice.

Before you spend, you can ask:

$org->credits()->allows();               // 1 credit?
$org->credits()->allows(250);            // 250?
$org->credits()->allows('send_email');   // enough for what that costs?
$org->credits()->price('send_email');    // what it costs
$org->credits()->meterPrice('gpt-4o', $in, $out);  // the same, uncharged

Charging itself does not refuse. An account with nothing left records the overdraft rather than leaving a turn half done, and the difference stays visible: every usage row stores the split between credits_from_plan and credits_from_purchased, and when they add up to less than credits, that gap is the overdraft.

What you sell sits outside every window

Top-ups are not consumption, so they cannot be expressed as a sum of what was spent. They are their own table:

$org->credits()->deposit(5_000, reason: 'purchase', source: $payment);
$org->credits()->deposit(500, reason: 'gift', note: 'launch promo');
$org->credits()->deposit(-200, reason: 'adjustment', note: 'duplicate charge');

Purchased credits survive every reset, and — this is the part that matters — what they pay for is not counted against the windows. You run out of session, you buy more, you carry on, and your week has not moved meanwhile.

The balance is stored rather than summed, which once you sell credits is not an optimisation but the model itself. It stays checkable anyway, because the deposits table is the ledger, and that is what you want the first time somebody asks why an account has 5,000 credits.

Plans are dynamically resolved

Add HasPlans and the plan is resolved by a list of providers, tried in order, first answer wins.

use EduLazaro\Larameter\Concerns\HasCredits;
use EduLazaro\Larameter\Concerns\HasPlans;

class Organization extends Model
{
    use HasCredits, HasPlans;
}

'plan_providers' => [
    PlanProviders\ForcedPlanProvider::class,    // a column of yours, set by hand
    PlanProviders\CashierPlanProvider::class,   // the subscription, by price id
    PlanProviders\StoredPlanProvider::class,    // credits()->setPlan(), then the default
],

The order is the policy. Forced before Cashier means a plan somebody set by hand for a partner or a demo beats what Stripe thinks, because a person decided it deliberately. CashierPlanProvider is inert without Cashier installed, so an app that only sells bundles pays nothing for leaving it there. For Paddle or anything else, implement the contract and add it to the list.

$org->plan()->handle;              // 'pro'
$org->plan()->exists;              // false when no provider answered
$org->plan()->allows('api_access');
$org->plan()->is('pro');

You can also point the package at your own plans file, so the commercial half of a plan lives next to the metered half:

'plans_from' => 'plans.tiers',

Using meters to set ceilings

Credits are spent and come back. Seats and projects are different: a standing count of what exists, and the plan says how many at once.

php artisan make:meter MemberMeter Organization

class MemberMeter extends Meter
{
    public string $handle = 'members';

    public function count(): int
    {
        return $this->meterable->members()->count();
    }
}

List it on the model, and ask:

class Organization extends Model
{
    use HasCredits, HasMeters;

    protected array $meters = [MemberMeter::class, ProjectMeter::class];
}

$org->quota()->allows('members');       // room for one more?
$org->quota()->allows('members', 4);    // inviting 4 at once
$org->quota()->summary();               // the usage screen

A meter is a class and not a number you pass in, and that is the whole point. The app this came from had a 1-seat plan, showed it on the usage screen, and never checked it when inviting: the cap was enforced for projects and forgotten for members, because enforcing it meant every caller had to remember to count first. Once counting lives in a class, no caller can forget.

A resource with no meter is unlimited, and so is a limits key you never listed. These are restrictions, and a package you just installed should not start refusing to create users on its own opinion. -1 is unlimited explicitly, which is not the same as 0.

The usage screen

Reading a window never opens one, so a screen is free to ask for all of them:

foreach ($org->credits()->windows() as $window) {
    $window->key;            // 'weekly'
    $window->allowance();    // 12_500
    $window->used();         // 12_000
    $window->remaining();    // 500
    $window->percentUsed();  // 96.0
    $window->startedAt();    // what to count from, per person or per feature
    $window->endsAt();       // the Monday coming, or null if none is running
}

endsAt() is not what the row says once a fixed window has expired. The grid went on without it, so a row claiming a Monday 3 weeks back answers with the Monday ahead, which is the only answer a screen can show.

Wrapping up

An allowance per window with 1 figure per plan, top-ups that outlive every reset, ceilings enforced by classes that know how to count, and a plan resolved on every request instead of stored and synchronised. Your billing keeps the parts that are yours (what a credit costs, what a plan is worth, who gets a courtesy account... etc) and stops re-implementing the parts that are the same in every project.

👉 The package: packagist.org/packages/edulazaro/larameter
👉 The source: github.com/edulazaro/larameter

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