DEV Community: Eduardo Lázaro

Wirelist: cards, divided lists and grids for Laravel and Livewire

Eduardo Lázaro — Tue, 06 Oct 2026 00:54:00 +0000

A list of cases, tasks or properties is not a table, as each record reads as a card, and forcing it into columns leaves gaps and odd widths.

Wirelist draws those lists. Records as divided rows, separate cards or a grid, each one opening its record, with a row actions menu, load more and the 11 themes of the wire* family. It is built on Wiretables, so tables and lists share their look and sit together on one screen.

Install

It requires Wiretables, which Composer installs with it. Publish both CSS:

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

Load the cores and, if you want one, the theme of the same name from each package. With Vite:

@import "../../vendor/edulazaro/wiretables/resources/css/wiretables-core.css";
@import "../../vendor/edulazaro/wiretables/resources/css/themes/studio.css";
@import "../../vendor/edulazaro/wirelist/resources/css/wirelist-core.css";
@import "../../vendor/edulazaro/wirelist/resources/css/themes/studio.css";

Wiretables' theme file brings the colours both share; Wirelist's adds what only a list needs.

A list

Each record is an item with a title, a muted line and slots around them:

<x-wirelist items="separated">
    @forelse ($cases as $case)
        <x-wirelist.item wire:key="case-{{ $case->id }}" :title="$case->title" :subtitle="$case->company" :href="route('cases.show', $case)">
            <x-slot:badges>
                @foreach ($case->tags as $tag)
                    <span class="badge">{{ $tag->name }}</span>
                @endforeach
            </x-slot:badges>
            <x-slot:aside>
                <span>{{ $case->members_count }} members</span>
                <span class="status">{{ $case->status }}</span>
            </x-slot:aside>
            <x-slot:actions>
                <x-wiretable.menu :label="'Actions of '.$case->title">
                    <x-wiretable.menu-item wire:click="archive({{ $case->id }})" danger>Archive…</x-wiretable.menu-item>
                </x-wiretable.menu>
            </x-slot:actions>
        </x-wirelist.item>
    @empty
        <x-wirelist.empty>No cases yet.</x-wirelist.empty>
    @endforelse
</x-wirelist>

The slots cover what these lists usually carry:

Slot
`leading`	An avatar or an icon; in a grid, the cover image
`badges`	Beside the title: tags, a draft mark, a category
`aside`	On the right: counts, a status, a date
`actions`	The "⋯" menu or a button
`header`	A strip above the record
default	More lines under the subtitle

Three shapes, one markup

The same items draw three different lists:

items="divided", the default, puts every record in one frame with a line between them: a queue or a short dashboard list.
items="separated" draws each record as a card of its own.
layout="grid" puts the cards side by side, as many as fit. The leading slot becomes a cover running edge to edge on top, and the aside lines up at the foot of every card in the row.

Since the markup does not change, a list/grid switch is one Livewire property:

<x-wirelist :layout="$view">…</x-wirelist>

A card that opens without nesting buttons

The usual way to make a whole card clickable is to wrap it in an <a>, and then a delete button ends up inside a link. HTML does not allow it, keyboards and screen readers trip on it, and the click goes to whichever element the browser picks.

With href, Wirelist stretches the title's link over the item instead:

.wtl-item-link::after {
    content: "";
    position: absolute;
    inset: 0;
}

A click anywhere on the card opens the record, while the badges, the aside, the actions and any link or button in the content sit above the stretched link and keep their own clicks. The markup stays valid: the menu is a sibling of the link, never inside it.

On a phone

Lists adapt without configuration: the actions stay beside the title and the aside goes under both. The grid drops to as many columns as fit, down to one.

Load more and sorting

Wiretables' traits work the same with a list:

use EduLazaro\Wiretables\Concerns\WithLoadMore;

$cases = $this->loadMoreFrom(LegalCase::query()->latest());

<x-wirelist>…</x-wirelist>
<x-wiretable.load-more :show="$hasMore" />

The list re-reads from the start on each load, so nothing is repeated or lost when records change meanwhile, and the client cannot ask for more pages than it loaded.

Themes

The theme is the same attribute as the rest of the family:

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

Colours, lines and radius come from Wiretables' --wtb-* variables, so one setting reaches tables and lists alike. The list's own shape lives in --wtl-*:

:root {
    --wtl-item-padding: 14px 20px;
    --wtl-grid-min: 18rem;
    --wtl-cover-ratio: 4 / 3;
}

Links

👉 Source: Wirelist on GitHub
👉 Packagist: Wirelist on Packagist
👉 Documentation: Wirelist Documentation

Wiretables: tables for Laravel and Livewire written in Blade

Eduardo Lázaro — Sun, 04 Oct 2026 22:00:00 +0000

Table packages for Livewire usually define the columns in PHP arrays, which is comfortable until one cell needs something the configuration did not plan for.

Wiretables goes the other way: you write the table in Blade, cell by cell, and the package brings the pieces, their look and the behaviour every list repeats. Columns that hide or stack into cards on a phone, header sorting kept in the URL, load more, a row actions menu nothing cuts off, and the 11 themes of the wire* family. It is pure CSS, so it does not depend on Tailwind or Bootstrap.

Install

It is a regular Laravel package. Require it with Composer and publish the CSS:

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

Load the core and, if you want one, a theme. With Vite, straight from vendor:

@import "../../vendor/edulazaro/wiretables/resources/css/wiretables-core.css";
@import "../../vendor/edulazaro/wiretables/resources/css/themes/studio.css";

Each theme is its own file, so adding themes to the package never makes your CSS bigger. The row menu uses Alpine and its anchor plugin, both bundled with Livewire.

A table

The table is plain Blade: a head slot with the columns, then one row per record:

<x-wiretable>
    <x-slot:head>
        <x-wiretable.th>Event</x-wiretable.th>
        <x-wiretable.th hide="sm" shrink>Status</x-wiretable.th>
        <x-wiretable.th hide="md" shrink>Date</x-wiretable.th>
        <x-wiretable.th actions />
    </x-slot:head>

    @forelse ($projects as $project)
        <x-wiretable.row wire:key="project-{{ $project->id }}">
            <x-wiretable.td>
                <x-wiretable.primary :title="$project->name" :subtitle="$project->email" :href="route('projects.show', $project)">
                    <p class="md:hidden">{{ $project->status }} · {{ $project->date }}</p>
                </x-wiretable.primary>
            </x-wiretable.td>
            <x-wiretable.td hide="sm" shrink>{{ $project->status }}</x-wiretable.td>
            <x-wiretable.td hide="md" shrink>{{ $project->date }}</x-wiretable.td>
            <x-wiretable.td actions>
                <x-wiretable.menu :label="'Actions of '.$project->name">
                    <x-wiretable.menu-item :href="route('projects.show', $project)">Open</x-wiretable.menu-item>
                    <x-wiretable.menu-separator />
                    <x-wiretable.menu-item wire:click="archive({{ $project->id }})" danger>Archive…</x-wiretable.menu-item>
                </x-wiretable.menu>
            </x-wiretable.td>
        </x-wiretable.row>
    @empty
        <x-wiretable.empty colspan="4">Nothing yet.</x-wiretable.empty>
    @endforelse
</x-wiretable>

The first column holds the record and takes the room left; shrink fits the rest to their content. align="right" lines up figures and amounts.

On a phone

A column with hide="md" shows from that breakpoint up, with the same widths as Tailwind's sm, md, lg and xl. Nothing scrolls sideways: what a phone cannot show, the first cell repeats in its slot, as the md:hidden line above does.

When every value matters on a phone too, stack the rows into cards instead:

<x-wiretable stack="md" expandable>
    …
    <x-wiretable.td hide="md" label="Price" align="right">{{ $property->price }}</x-wiretable.td>
</x-wiretable>

Below md each row becomes a card and each cell a line with its label above it. With expandable, the cells with hide fold behind a button in the actions cell; compact keeps the main cells and the actions on one line. On a desktop the table does not change.

Sorting

A header becomes a sort button when you give it a key and the component's current order:

<x-wiretable.th sortable="date" :sort="$sort" :direction="$direction">Date</x-wiretable.th>

The Livewire side is a trait. It keeps sort and direction in the URL, cycles ascending, descending and back to the list's own order, and goes back to the first page:

use EduLazaro\Wiretables\Concerns\WithSorting;

class Projects extends Component
{
    use WithPagination, WithSorting;

    protected function sortable(): array
    {
        return ['date', 'received'];
    }

    public function render()
    {
        $column = ['date' => 'starts_on', 'received' => 'created_at'][$this->sort] ?? null;

        return view('livewire.projects', [
            'projects' => Project::query()
                ->when($column, fn ($query) => $query->orderBy($column, $this->direction))
                ->paginate(25),
        ]);
    }
}

Only the keys sortable() returns are accepted, because the client can send any string and a column name must never come from it.

Load more

For a list that grows instead of paging, WithLoadMore and its button do the work:

use EduLazaro\Wiretables\Concerns\WithLoadMore;

$projects = $this->loadMoreFrom(Project::query()->latest());

<x-wiretable>…</x-wiretable>
<x-wiretable.load-more :show="$hasMore" />

Each read asks for everything up to the current page from the start rather than skipping what was loaded, so a record added or removed meanwhile is never repeated or lost. The page count is locked, so the client cannot ask for a thousand rows at once, and any filter or new order starts again from the first page.

The row menu

Row actions live in x-wiretable.menu, a "⋯" that fits on any screen where a row of buttons would not:

It is moved to <body> and anchored to its button, so a scrolling table, a card or a modal never cuts it off.
It flips upwards near the bottom of the screen and closes on a choice, a click outside or Escape.
menu-item is a link with href or a button otherwise, with an icon in front and danger for what cannot be undone.

A few more options

The table adapts to where it sits with a handful of attributes:

rows="separated" draws each row as a card of its own, with a little room between them.
flush drops the frame for a table inside a card, such as a dashboard panel.
The footer slot holds pagination, totals or the load more button.

Themes

The theme is one attribute on <html>, shared with the rest of the wire* family:

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

There are 11 themes, each with its dark mode through data-wire-theme-mode="dark" or a .dark ancestor. For your own look, override the --wire-* variables for the whole family or --wtb-* for the table:

:root {
    --wtb-text: #1e2a36;
    --wtb-line: #e3e6e1;
    --wtb-row-hover: #f9faf8;
    --wtb-radius: 6px;
}

Lists without columns

When each record reads as a card rather than a row of columns, use Wirelist, built on this package with the same look, menu and load more.

Links

👉 Source: Wiretables on GitHub
👉 Packagist: Wiretables on Packagist
👉 Documentation: Wiretables Documentation

Larasearch: text search in Laravel for Eloquent

Eduardo Lázaro — Sat, 03 Oct 2026 01:49:21 +0000

Most admin panels do not need Elasticsearch to search their lists. They need a search that finds "acme sitges" when the company is Acme and the location is Sitges, that finds "Camión" when you type "camion", and that never shows a user a record they are not allowed to open.

I had a HasSearchText trait copied across six projects, each copy a little different. Larasearch is that trait done once, with what the best copy did and what none of them got right.

Install

It is a regular Laravel package. Require it and run the migration, which creates the table for the global index:

composer require edulazaro/larasearch
php artisan migrate

There is no config file.

Searching a list

Each model keeps its own search_text column. Add it to the table:

Schema::table('projects', function (Blueprint $table) {
    $table->searchable();   // search_text, and a FULLTEXT index on MySQL
});

Then use the trait and name the fields that go into it:

use EduLazaro\Larasearch\Concerns\HasSearch;

class Project extends Model
{
    use HasSearch;

    protected array $searchable = ['event_name', 'company', 'client_name', 'email', 'location'];
}

And search inside any query:

Project::visibleTo($user)
    ->searchText($request->q)
    ->where('status', 'confirmed')
    ->paginate(25);

searchText() is a scope, so it combines with your own scopes, filters and pagination. An empty term leaves the query alone, so a filter can always pass it on without an if.

What a match means

The rules are the same for every model, so a term finds the same records on every screen:

Every word must appear, in any order and in any field: "acme sitges" finds company Acme, location Sitges.
Text is stored and searched the same way, lower case and without accents: "camion" finds "Camión".
LIKE wildcards are escaped: "50%" means fifty per cent, not "50 followed by anything".

On MySQL, whole words of three letters or more go through the FULLTEXT index and match from their start, so "sitg" finds "sitges". Short words, emails and MySQL's stopwords go through LIKE, because the index does not store them and a required word it cannot find returns nothing. "forza horizon 6" still finds Forza Horizon 6.

When the column is written

It is written in the same save as the model, and only when one of the fields changed. Saving a project whose status alone changed costs nothing extra.

It is also written after every saving observer. If an observer fills in a normalized phone on saving, the phone is in the text. Getting this right took two attempts: the first release relied on the order Laravel attaches listeners, and PHP 8.5 changed that order. The text is now written on creating and updating, which Eloquent always fires after every saving listener.

Fields of related models

Searching a project by the name of one of its tasks is a common ask. A field with a dot is read through a relation:

protected array $searchable = ['name', 'client', 'tasks.title', 'owner.name'];

When a task is saved or deleted, or the owner renamed, the project is indexed again. Searchable models in app/Models are found on their own, so this works even when the request or queued job that saves the task never loaded a project.

The global index

A command palette searches everything at once, so it needs a different shape: one table with a row per record. A model joins it when it says how to show itself and who may see it:

protected string $searchableTitle = 'event_name';
protected ?string $searchableSubtitle = 'company';
protected string $searchableRoute = 'projects.show';

public static function searchableFor(User $user): Builder
{
    return static::visibleTo($user);
}

Searching it reads like the lists:

use EduLazaro\Larasearch\Models\Index;

Index::searchText('acme')
    ->in($organization)
    ->for($user)
    ->limit(10)
    ->get();

Each row holds the title and subtitle, so the palette paints results without loading the records. The link is built when read, from the route and the key, so a renamed route leaves nothing stale.

Who sees what

This is the part that is easy to get wrong in a global index, so it is not optional. for($user) asks each model's searchableFor() at search time:

// A task is seen by whoever sees its project.
public static function searchableFor(User $user): Builder
{
    return static::whereIn('project_id', Project::visibleTo($user)->select('id'));
}

Visibility is never stored in the index. Reassigning a project to someone else removes it from the previous person's palette at once, with no reindex. A model in the index without searchableFor() throws an exception instead of showing everything to everyone.

Tenants

Multi-tenant applications need each tenant's rows kept apart before anything else. Say how to find a model's tenant once:

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

Then in($organization) keeps one tenant's rows, in($agency->offices) several. It is explicit on purpose: which tenant a query reads should be visible in the code.

What it cannot catch

Some changes never go through Eloquent: a query builder update(), an import, a pivot attach(). They fire no event, so after them rebuild the text:

php artisan search:reindex

It writes every record again in batches and removes index rows whose record no longer exists.

Links

👉 Source: https://github.com/edulazaro/larasearch
👉 Packagist: https://packagist.org/packages/edulazaro/larasearch
👉 Documentation: https://edulazaro.com/portfolio/larasearch

Wirepicker: a date and date-range picker for Laravel and Livewire

Eduardo Lázaro — Fri, 02 Oct 2026 20:25:52 +0000

Nobody uses <input type="date"> in a real app. It shows the browser's format instead of the page's, it cannot be styled and it has no ranges.

Wirepicker replaces it with one Blade component: single dates and ranges, shortcuts, keyboard, every language, no runtime dependencies. It works with Livewire, with Alpine or with a plain form.

Install

It is a regular Laravel package. Require it with Composer and publish the assets:

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

Then load the CSS and the JS in your layout:

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

Or with Vite, straight from vendor:

@import "../../vendor/edulazaro/wirepicker/resources/css/wirepicker.css";

import '../../vendor/edulazaro/wirepicker/resources/js/wirepicker.js';

One date

Put the component where the input would go and bind it like any field:

<x-wirepicker wire:model="startsOn" />

The property gets a Y-m-d string, or '' when empty.

A range

Add range and bind it to an array with a start and an end:

<x-wirepicker range wire:model.live="period" />

public array $period = ['start' => '', 'end' => ''];

Click both ends in any order. With shortcuts:

<x-wirepicker range wire:model.live="period" :presets="['this-month', 'next-month', 'this-year']" />

Available: today, this-week, next-7-days, this-month, next-month, last-month, this-year.

Without Livewire

Outside Livewire, give it a name and an optional value, and it posts like any other field:

<x-wirepicker name="starts_on" value="2026-10-08" />
<x-wirepicker range name="period" :value="['start' => '2026-10-01', 'end' => '2026-10-31']" />

A range posts period[start] and period[end]. For Alpine, listen to wirepicker:change:

<div x-data="{ date: null }" x-on:wirepicker:change="date = $event.detail.value">
    <x-wirepicker />
</div>

Options

Everything is a prop on the component. These are all of them:

Prop	Default
`range`	`false`	Two dates instead of one
`presets`	`[]`	Shortcuts, range only
`placeholder`	translated	Text while empty
`min`, `max`	none	First and last day that can be picked
`clearable`	`true`	A button to empty it
`name`, `value`	none	For a plain form
`size`	`md`	`sm` for toolbars
`locale`	app locale	Language, format and first day of the week
`week-start`	from the locale	`0` Sunday to `6` Saturday
`id`	none	For `<label for>`

Languages

Months, weekdays, date format and first day of the week come from Intl: es shows 08/10/2026 starting on Monday, en-US shows 10/08/2026 starting on Sunday. No locale files. The few words of its own ship in English and Spanish (vendor:publish --tag=wirepicker-lang to add more).

Keyboard

Arrows move a day or a week, Page Up and Page Down a month, Enter picks, Escape closes.

How it works with Livewire

The point of the package is that it keeps its value through Livewire's requests, which is where most date pickers break. Three decisions make that work:

wire:model goes on hidden fields inside the component. The JS writes them and fires input and change, so there is no glue to write and nothing to initialise: pickers added later just work.
Those fields are <input type="text" hidden>, not type="hidden". On a hidden input the value is the attribute, and Livewire's morph removes it after every request.
The calendar is drawn on <body>, so tables, cards and modals cannot clip it, and it opens above wiremodal modals.

Themes

Same attribute as the rest of the wire* family:

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

11 themes, dark mode with data-wire-theme-mode="dark" or .dark. For your own look, override the --wire-* variables (whole family) or --wp-* (just the picker):

:root {
    --wp-trigger-radius: 0.5rem;
    --wp-day-size: 34px;
}

Links

👉 Source: https://github.com/edulazaro/wirepicker
👉 Packagist: https://packagist.org/packages/edulazaro/wirepicker
👉 Documentation: https://edulazaro.com/portfolio/wirepicker

External APIs as Eloquent models in Laravel with Larasources

Eduardo Lázaro — Fri, 02 Oct 2026 01:01:15 +0000

Every integration starts a client with the endpoints, a function that turns your model into their payload, a column or two to remember what the other side answered, and a job that pushes changes.

Then the second portal arrives and you write it again, because the shape of their JSON is different even though everything around it is identical.

What gets you is not the HTTP. It is the four things around it:

Where the mapping lives.
Where the remote state is cached.
How you know whether what the screen shows is current.
Whose credentials you are using.

Larasources is those four things. A Source is a model-like class that declares the remote resource with fillable fields, casts, accessors, and a mapping from your record.

An Origin is the client that knows how to fetch, save and delete. The cached state lives in one dedicated table instead of leaking into your schema, and nothing about the package assumes the other side is even an API, as one of the apps using it reads a car listing by scraping the page.

How to install

Just install it with composer as usually:

composer require edulazaro/larasources
php artisan migrate

There is no config file to publish and no environment variable to set.

The source: the shape retrieved

A Source looks like a model because it behaves like one, minus the table:

namespace App\Sources;

use EduLazaro\Larasources\Source;
use EduLazaro\Larasources\Attributes\UsesOrigin;
use App\Origins\WeatherOrigin;

#[UsesOrigin(WeatherOrigin::class)]
class WeatherSource extends Source
{
    protected $fillable = ['temperature', 'humidity', 'description'];

    protected $casts = [
        'temperature' => 'float',
        'humidity'    => 'integer',
    ];

    protected function arguments(): array
    {
        return [
            'city_id' => 'external_id', // the origin receives $city->external_id
        ];
    }

    public function getFeelsLikeAttribute(): float
    {
        return $this->temperature - ($this->humidity / 10);
    }
}

The origin: integrating the remote client

The Origin is where the protocol lives, and it never sees your mapping:

namespace App\Origins;

use EduLazaro\Larasources\Origins\Origin;

class WeatherOrigin extends Origin
{
    public static function getAlias(): string
    {
        return 'weather';
    }

    public function fetch(array $arguments = []): array
    {
        return $this->http()
            ->withToken($this->config('api_key'))
            ->get('https://api.example.com/weather/' . $arguments['city_id'])
            ->json();
    }

    public function save(array $data): array
    {
        return $this->http()
            ->withToken($this->config('api_key'))
            ->post('https://api.example.com/weather', $data)
            ->json();
    }
}

Attaching a source to a model

use Illuminate\Database\Eloquent\Model;
use EduLazaro\Larasources\Concerns\HasSources;

class City extends Model
{
    use HasSources;

    protected array $sources = [
        'weather' => WeatherSource::class,
    ];
}

Then read it like anything else:

$weather = $city->source('weather');

$weather->temperature;   // 21.5
$weather->feels_like;    // the accessor, over cached data

Reading serves the cache

Touching an attribute autoloads. It fills from the cached record if there is one, and goes to the origin if there is not.

Asking for live data is explicit, and it refreshes the cache on the way out:

$city->source('weather')->fetch();   // live from the origin, cache refreshed
$city->source('weather')->save();    // push your attributes, then cache
$city->source('weather')->clear();   // drop the cached record

fetch() always writes to the record, and there is no flag to turn that off.

A cache is the local picture of something remote. A live read that leaves the old copy behind turns the next screen into a lie, and nobody gets told.

What the package will not do is expire that cache on its own. Once the record exists, reading attributes never calls the origin again, and you refresh when your app decides to: on a schedule, on a button, when a webhook says something changed.

A TTL that fires on attribute access sounds handy until a listing page paints 20 cards and makes 20 API calls.

The cached record is a plain Eloquent model, so comparing both pictures needs nothing special. What you have stored sits under its attributes key, and fetch() gives you what the service says right now:

$stored = $source->record()->toArray();   // name, variant, origin, attributes, dates
$live   = $source->fetch()->toArray();    // the fields, straight from the service

Writing, and what the service answers

save() builds, pushes, and writes the record after the push returns. That order is the whole design: when the push fails the record is not touched, so the local copy can fall behind the service, which the next write or read fixes, but it never gets ahead of it. A row claiming something exists on the other side when it does not is the failure you never recover from, because nothing ever goes looking for it again.

Failure arrives as an exception, which is what a queued job wants: catch, back off, retry. A screen wants the opposite, so there is a twin that reports instead of throwing:

$result = $property->source('portal')->trySave();

if ($result->failed()) {
    return back()->withErrors($result->message);
}

What counts as a failure is decided inside the origin, never by the package. Returning means the service took the data. Reading a response to guess whether it worked would be the package pretending to understand an API it has never seen.

And some services take the payload and finish with it later, so the origin can say that too:

return new OriginResult(
    status: $response['published'] ? OriginStatus::Saved : OriginStatus::Processing,
    data: $response,
    externalId: $response['id'] ?? null,
);

A processing row is not a lie and not the truth yet. What is pending is a query, and resolving it happens where the latency is yours to spend:

foreach (SourceRecord::processing()->where('updated_at', '<', now()->subHour())->get() as $record) {
    $record->toSource(ListingSource::class)->reconcile();
}

Not on attribute access. A listing page is not the place to discover that forty rows each need an API call.

What the service calls it

Their id for the thing you just created is the one part of a write response worth keeping, and every integration ends up with a column for it: provider_listing_id, beat_id, whatever you named yours. It lives on the record now, reported by the origin and optional, so an app that prefers its own column carries on as before.

It pays twice. The next write knows whether to create or update without you passing anything in:

$id = $this->source->externalId();

And an id coming the other way, in a webhook or a reconciliation listing, finds what it belongs to:

$property = SourceRecord::where('name', 'portal')
    ->where('external_id', $id)
    ->first()?->sourceable;

Arguments come from the record

The map in arguments() says which attribute feeds each argument. The package resolves it before the origin sees anything:

protected function arguments(): array
{
    return ['city_id' => 'external_id'];
}

// the origin receives ['city_id' => 'city-42']

You can also pass them at call time, and those win:

$city->source('weather', ['city_id' => 'custom_id'])->fetch();

An argument can point at another source

An argument does not have to be a value. It can point at a model, or at another source, and then it is a pointer instead of a copy:

$scraped = $article->source('scraped')->fetch();

$article->source('translation')
    ->useArgument('scraped', $scraped)
    ->fetch();

The second origin receives the first one's payload as it is when it reads it. That is a pipeline: scrape into one source, derive from it in another, and nothing copies data from one row to the next. Each row keeps its own signature, so you know whether the scrape changed before paying for the translation again.

Variants, when one source has modes

A property is published for sale and for rent. Each one is a separate listing on the portal side, with its own id. Weather has current and forecast.

Same shape, different mode:

$property->source('portal')->setVariant('sale')->save();
$property->source('portal')->setVariant('rent')->save();

Each variant is cached apart, keyed by sourceable, name and variant. The argument map can point at a different column per variant, which is how two listings on the same portal keep their own external ids.

When the payload arrives before the model

Scrapers run the other way round from APIs. You do not have a record and ask about it. You read a listing, keep what you found, and only then decide what it becomes.

So a source does not need a model. An external id is identity enough:

$scraped = ListingSource::make()->setExternalId($link)->fetch();

$property = Property::create(['reference' => $scraped->reference]);

$scraped->attachTo($property);

SourceRecord::unattached() is what is still waiting for one. Attaching also re-keys the row, because a source's name is how its owner calls it, and that is what makes $property->source('portal') find it from then on.

The credentials belong to the integration

This is the part I would defend hardest, and the reason the package ships no config file.

In a multi-tenant app the API key is not yours. Every tenant connects its own account on the external service, and in some of them each branch carries its own feed code on top. The key lives in a row next to the tenant that owns it.

An env('PROVIDER_API_KEY') has no answer for that. A config block inside the package is a place where that data is never going to be.

So the origin resolves its own settings in one method, and you override it:

protected function config(?string $key = null, mixed $default = null): mixed
{
    $credentials = $this->integration->credentials ?? [];

    return $key ? ($credentials[$key] ?? $default) : $credentials;
}

Leave it alone and it reads larasources.origins.{alias} from a config of your own, which is all a single tenant app with a static key needs.

timeout and retry go through that same method, so they are per integration too. A flaky portal gets three attempts, a strict one gets a shorter timeout, and there is no global setting pretending every origin speaks HTTP.

Bundled origins

Origin          // the base: fetch, save, delete, config, http
RemoteOrigin    // generic REST client
AgentOrigin     // agent-style integrations
ScraperOrigin   // HTML, with a getHtml() helper

ScraperOrigin is the one that surprises people. If the external source is a page and not an API, the Source still describes it as a typed resource with casts and accessors, and the scraping stays inside the Origin.

Testing

Mock the source on the model and the origin is never reached:

$mock = (new WeatherSource())->fill(['temperature' => 22.5, 'humidity' => 60]);

$city->mockSource(WeatherSource::class, $mock);

$city->source('weather')->temperature;   // 22.5, no HTTP

Wrapping up

The remote resource declared once as a typed class. A client that only knows the protocol. A cache in a table of your own that a live read keeps honest, and that never gets ahead of the service. Arguments resolved from the record, or pointing at another source when one feeds the next. Variants for the modes the other side insists on, their own id for the thing when they give you one, and credentials that follow the integration instead of the deployment.

Your integration layer keeps what is actually yours, which is their payload and your mapping, and stops rewriting the rest on every provider.

It needs PHP 8.4+ and Laravel 12+.

👉 Source: github.com/edulazaro/larasources
👉 Packagist: packagist.org/packages/edulazaro/larasources
👉 Documentation: edulazaro.com/portfolio/larasources

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