Our take on AI here is to aim it at the support agent, not the customer. The human owns the conversation. The model makes the reply a little cleaner and a little faster. There There is in private beta, and you can apply for early access at there-there.app.

We're building There There with Laravel and Inertia. One package we've come to rely on is Laravel Wayfinder. It generates typed TypeScript functions for every route and controller in your Laravel app, so the frontend talks to the backend without a single hardcoded URL. This post is about why that matters.

Using Wayfinder

A React codebase quickly fills up with URL strings. Every fetch, every form action, every link points to a route by way of a template literal. Then you rename a route in Laravel, or add a required parameter, and nothing breaks at compile time. You find out in production, or when a teammate clicks the wrong thing.

Wayfinder fixes this by generating a function per named route. You import it and call .url() to build the URL.

Here's a snippet from our team membership toggle.

import {
    add as addTeamMember,
    remove as removeTeamMember,
} from '@/routes/app/settings/workspace/teams/members';

removeTeamMember.url({ team: team.ulid, user: member.ulid });
addTeamMember.url({ team: team.ulid, user: member.ulid });

Two things are worth pointing out. First, the parameters are type-checked. If you rename the user route parameter to member, TypeScript catches every caller. Second, the route names map cleanly to import paths, so finding them is just autocomplete.

Wayfinder also generates a typed function per controller. We use that when we talk to an endpoint via plain fetch, outside of an Inertia visit. Here's the retry action for a failed outbound message.

import MessageRetryController from '@/actions/App/Http/Controllers/Tickets/MessageRetryController';

await fetch(
    MessageRetryController.url({ ticket: current.ulid, message: message.ulid }),
    { method: 'POST' },
);

Same deal. The URL is type-safe, the parameters are checked, and renaming the controller in PHP breaks the TypeScript build rather than production.

To make all of this work, we hook Wayfinder into Vite. Here's the relevant bit of our vite.config.js.

import { wayfinder } from "@laravel/vite-plugin-wayfinder";

export default defineConfig({
    plugins: [
        // ...
        wayfinder(),
    ],
});

The plugin watches your Laravel routes and controllers during development, and regenerates the typed functions whenever something changes. Imports stay in sync with your backend without any manual step.

In closing

Wayfinder has shaved a whole category of bug off our work. No more grep-the-codebase when a route changes, no more "why is this fetch returning 404", no more arguing about trailing slashes. You write the route in Laravel, import it in TypeScript, and the two stay honest with each other.

You can read more about it in the Wayfinder repo on GitHub. And if you'd like to try There There yourself, we're in private beta right now and you can apply for early access at there-there.app.

A lot of the fun is on the AI side. We're not using it to replace support agents, we're using it to make them faster. The human reads the ticket, thinks, and clicks a button. The model pulls up relevant history, drafts a reply, tags the ticket, closes a duplicate. There There is in private beta right now, and you can apply for early access at there-there.app.

The whole AI layer is built on the new Laravel AI SDK. It's been a joy to work with, and I'd like to walk through how we use it.

Using the Laravel AI SDK

Everything starts with an agent class. Ours is called ThereThereAgent. It declares which model to use, what the system prompt looks like, which tools the model can call, and what conversation history to replay.

Here's a trimmed version.

use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

#[Temperature(0.3)]
#[MaxSteps(10)]
class ThereThereAgent implements Agent, Conversational, HasTools
{
    use Promptable;

    public function __construct(
        protected Workspace $workspace,
        protected User $user,
        protected ?Ticket $contextTicket = null,
        protected array $conversationHistory = [],
    ) {}

    public function model(): string
    {
        return config('ai-pricing.default.name');
    }

    public function instructions(): string
    {
        return view('prompts.ai.there-there-agent-system', [
            'workspace' => $this->workspace,
            'user' => $this->user,
            'contextTicket' => $this->contextTicket,
        ])->render();
    }

    public function tools(): iterable
    {
        return [
            new ChangeTicketStatusTool($this->workspace),
            new AssignTicketTool($this->workspace),
            new AddNoteToTicketTool($this->workspace),
            new ManageTicketTagsTool($this->workspace),
        ];
    }
}

A few things I like here. The #[Temperature] and #[MaxSteps] attributes are declarative. No wiring through constructor parameters, no config file. The instructions() method renders a Blade view, which means our system prompt is a regular template with includes and partials. And tools() returns an iterable, so we can turn tools on and off depending on context.

Tools are where it gets fun. Each one is a class the model can decide to call, with a typed JSON schema so arguments are validated before they hit our code. Here's the tool that changes a ticket's status.

class ChangeTicketStatusTool implements Tool
{
    use FindsTicketsInWorkspace;

    public function __construct(protected Workspace $workspace) {}

    public function description(): string
    {
        return 'Change the status of a ticket. Use this when the agent asks to close, reopen, or mark a ticket as spam.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'ticket_subject' => $schema->string()->description('The subject, title, or ULID of the ticket.')->required(),
            'contact_email' => $schema->string()->description('The contact email on the ticket.')->required(),
            'new_status' => $schema->string()->description('The new status: open, closed, or spam.')->required(),
        ];
    }

    public function handle(Request $request): string
    {
        $status = TicketStatus::tryFrom($request['new_status'] ?? '');

        if (! $status) {
            return 'Invalid status. Must be one of: open, closed, spam.';
        }

        $ticket = $this->findTicket($request['ticket_subject'], $request['contact_email']);

        if (! $ticket) {
            return 'Could not find a matching ticket.';
        }

        app(ChangeTicketStatusAction::class)->execute($ticket, $status);

        return json_encode([
            'result' => 'success',
            'ticket' => $ticket->displayTitle(),
            'new_status' => $status->label(),
        ]);
    }
}

description() is what the model reads when deciding whether to call this tool. schema() returns the typed JSON schema the model has to match. handle() runs the tool and returns a string that goes back into the model's context. We return JSON on success so the model has structured data to refer to when it writes its final reply.

Notice we don't do heavy lifting inside the tool. The actual work is delegated to ChangeTicketStatusAction, a regular domain action. The tool is just an AI-facing adapter over code we already had.

Calling the agent from an action is a couple of lines.

$agent = new ThereThereAgent(
    workspace: $workspace,
    user: $user,
    contextTicket: $agentChat->contextTicket,
    conversationHistory: $agentChat->getConversationHistoryExcludingLatest(),
);

return $this->streamingService->stream($agent, $messageForAi, $agentChat);

We hand the agent off to our streaming service, which turns the SDK's response stream into events the frontend can consume. That's another post.

TODO: short video of the Ask There There agent picking up a message, calling a tool like changing a ticket status, and replying.

In closing

The Laravel AI SDK has hit a sweet spot for our use case. The agent and tool abstractions are simple, the Blade-backed prompt is a joy to edit, and the typed schema means the model rarely mangles its arguments. We've barely scratched the surface of what it can do.

You can read more in the Laravel AI SDK repo. And if you'd like to try There There yourself, we're in private beta right now and you can apply for early access at there-there.app.

There There, the helpdesk we're building, is built exactly like that. Tickets, messages, members, custom sidebar sections, all of it crosses the bridge. We'd go insane maintaining those types by hand. So we don't. There There is in private beta right now, and you can apply for early access at there-there.app.

Two Spatie packages make this painless. spatie/laravel-data shapes outgoing payloads into typed PHP classes, and spatie/laravel-typescript-transformer turns those classes into TypeScript definitions at build time. Let me show what that looks like in practice.

Keeping types in sync

A payload starts life as a Data class. Here's our MemberData, which we send down every time we render the member detail page.

use Spatie\LaravelData\Data;
use Spatie\TypeScriptTransformer\Attributes\TypeScript;

#[TypeScript]
class MemberData extends Data
{
    public function __construct(
        public int $id,
        public string $ulid,
        public string $name,
        public string $email,
        public ?string $avatar_url,
        public WorkspaceMemberRole $role,
        public string $joined_at,
        public bool $restricted_channel_access = false,
    ) {}

    public static function fromPivotUser(User $user): self
    {
        return new self(
            id: $user->id,
            ulid: $user->ulid,
            name: $user->name,
            email: $user->email,
            avatar_url: $user->getAvatarUrlWithFallback(),
            role: WorkspaceMemberRole::from($user->pivot->role),
            joined_at: $user->pivot->created_at->toIso8601String(),
            restricted_channel_access: (bool) $user->pivot->restricted_channel_access,
        );
    }
}

The #[TypeScript] attribute is the opt-in. Any PHP class that carries it is picked up by the transformer. The constructor properties become the TypeScript type, including the enum WorkspaceMemberRole, the nullable string, and the boolean with a default.

The transformer itself is a regular Laravel package with a config file. Here's the relevant part of ours.

return [
    'auto_discover_types' => [
        app_path(),
    ],

    'transformers' => [
        SpatieStateTransformer::class,
        EnumTransformer::class,
        DataTypeScriptTransformer::class,
        DtoTransformer::class,
    ],

    'default_type_replacements' => [
        Carbon\Carbon::class => 'string',
    ],

    'output_file' => resource_path('js/types/generated.d.ts'),
];

Three things worth knowing. auto_discover_types scans app/ for any annotated class. transformers handles data classes, DTOs, enums, and Spatie state machines. default_type_replacements lets you swap PHP types for their TypeScript equivalents, which is how every Carbon date becomes a plain string on the frontend.

When the transformer runs, it writes resources/js/types/generated.d.ts. For our MemberData, the output looks like this.

declare namespace App.Domain.Settings.Data {
    export type MemberData = {
        id: number;
        ulid: string;
        name: string;
        email: string;
        avatar_url: string | null;
        role: App.Domain.Workspace.Enums.WorkspaceMemberRole;
        joined_at: string;
        restricted_channel_access: boolean;
    };
}

The namespace mirrors the PHP namespace. The property shapes line up with the constructor. Enums are cross-referenced to their own generated types, so renaming an enum case in PHP propagates to every TypeScript caller.

You could regenerate this file manually with php artisan typescript:transform, but we wire it into Vite so it happens whenever a data class or enum changes.

handleHotUpdate({ file }) {
    if (isServe && file.endsWith('.php') && (file.includes('/Data/') || file.includes('/Enums/'))) {
        generate();
    }
},

That snippet sits inside a small custom Vite plugin. When the dev server is running and a PHP file under Data/ or Enums/ changes, we shell out to php artisan typescript:transform and the frontend types update in place. No manual step, no stale definitions.

There's a simpler option in v3 of spatie/laravel-typescript-transformer: the package includes a built-in watch mode. After installing chokidar, run php artisan typescript:transform --watch. We're on v2.6, whose typescript:transform command has no --watch option, so the Vite plugin above handles changes for us.

Here's what that looks like in the editor. The fields from MemberData show up as TypeScript suggestions:

In closing

This setup has erased a whole category of papercut. We rename a PHP property, the TypeScript compiler lights up on every frontend caller. We add a field, it's available to autocomplete in seconds. The two sides stay honest.

You can find the packages on GitHub: laravel-data and laravel-typescript-transformer. And if you'd like to try There There yourself, we're in private beta right now and you can apply for early access at there-there.app.

This is a small pattern, but it's one of those things that makes a codebase nicer to live in. There There is in private beta right now, and you can apply for early access at there-there.app.

Exceptions that explain themselves

The conventional answer for a domain error is something like throw new InvalidArgumentException("Only notes can be deleted"). It works, the test passes, the user sees a 500 page. But then three months later you try to catch just this specific error and you can't, because InvalidArgumentException is thrown from a dozen other places.

Our pattern is one class per domain error, with a static factory method per reason. Here's the one that fires when someone tries to delete a message that isn't a note.

namespace App\Domain\Tickets\Exceptions;

use App\Domain\Tickets\Models\Message;
use Exception;
use Illuminate\Contracts\Debug\ShouldntReport;

class CouldNotDeleteMessage extends Exception implements ShouldntReport
{
    public static function onlyNotesCanBeDeleted(Message $message): self
    {
        return new self("Could not delete message id {$message->id} of type {$message->type->value}. Only messages of type `note` can be deleted.");
    }
}

Two things worth calling out. The static method name spells out the failure reason in English, which makes the throw site read like a sentence: throw CouldNotDeleteMessage::onlyNotesCanBeDeleted($message). And the method takes the typed context as a parameter, which makes the message impossible to build without the relevant data.

Here's the throw site, inside our DeleteNoteAction.

class DeleteNoteAction
{
    public function execute(Message $message): void
    {
        if (! $message->isNote()) {
            throw CouldNotDeleteMessage::onlyNotesCanBeDeleted($message);
        }

        // ... delete the note
    }
}

When the throw site is this readable, you don't need a comment explaining what went wrong. The exception name, the method name, and the message all agree with each other.

The ShouldntReport marker is a small Laravel convention. We implement it so these exceptions don't end up in our error tracker. They're expected domain errors, not bugs, and they surface through user action. Keeping them out of the error log makes the signal there actually signal.

If a domain has several failure modes, we add methods. Our CouldNotInviteMember class has half a dozen static factories, one per reason the invitation couldn't be sent. Every throw site is a one-liner that tells you exactly what went wrong.

In closing

Custom exceptions look like over-engineering until the first time you need to catch one. Then they look like the obvious move. And because every exception class is tiny, they don't add much weight to the codebase.

If you'd like to see how the rest of There There is put together, we're in private beta right now and you can apply for early access at there-there.app.

A quick reminder on our angle. After two decades of running our own customer support, we wanted a helpdesk where AI makes support agents faster, not one that tries to replace them. The human reads, thinks, and directs. The model drafts and retrieves in real time while they watch. There There is in private beta right now, and you can apply for early access at there-there.app.

Streaming from Laravel to React

The obvious way to hand an LLM response to the browser is to wait for it to finish, then render the whole thing. That's easy, but it makes the agent feel sluggish. What we actually want is for the reply to appear word by word, and for the agent's own reasoning (like which tool it's calling) to be narrated along the way.

The Laravel AI SDK exposes each step of a conversation as a typed event. We iterate over that stream and emit newline-delimited JSON for the frontend, one line per event.

Here's the core of our AgentStreamingService.

public function stream(Agent&HasTools $agent, string $message, AgentChat $chat): StreamedResponse
{
    return response()->stream(function () use ($agent, $message, $chat): Generator {
        yield from $this->streamAgent($agent, $message, $chat);
    }, 200, [
        'Content-Type' => 'application/x-ndjson',
        'Cache-Control' => 'no-cache',
    ]);
}

private function streamAgent(Agent&HasTools $agent, string $message, AgentChat $chat): Generator
{
    set_time_limit(120);

    $fullContent = '';
    $toolCalls = [];

    foreach ($agent->stream($message) as $event) {
        if ($event instanceof ToolCall) {
            yield json_encode(['type' => 'tool_call', 'tool_name' => $event->toolCall->name])."\n";
        }

        if ($event instanceof TextDelta) {
            $fullContent .= $event->delta;
            yield json_encode(['type' => 'delta', 'content' => $event->delta])."\n";
        }

        if ($event instanceof ToolResult) {
            $toolCalls[] = [
                'name' => $event->toolResult->name,
                'arguments' => $event->toolResult->arguments,
                'result' => $event->toolResult->result,
            ];
        }
    }

    $chat->messages()->create([
        'role' => MessageRole::Assistant,
        'content' => $fullContent,
        'tool_calls' => $toolCalls ?: null,
    ]);

    yield json_encode([
        'type' => 'done',
        'html' => $this->parser->buildFinalHtml($fullContent),
    ])."\n";
}

A few things are worth calling out. response()->stream() accepts a generator and flushes each yield to the client immediately, which is the whole trick for server-pushed progress. We type the events (delta, tool_call, done) so the frontend can tell a text chunk apart from a tool invocation. And we persist the finished message to the database in the same pass. The stream itself is the source of truth, and the persisted copy is what we rehydrate the next time the user opens the chat.

On the frontend we consume the stream with plain fetch. No library needed, no SSE framing to worry about. Here's the hook we use, trimmed to the bits that matter.

const response = await fetch(sendUrl, {
    method: 'POST',
    headers: { ...csrfHeaders(), 'Content-Type': 'application/json' },
    body: JSON.stringify(buildBody(text, html)),
    signal: controller.signal,
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop() ?? '';

    for (const line of lines) {
        processLine(line);
    }
}

if (buffer.trim()) {
    processLine(buffer);
}

The buffer pattern is the only thing you have to get right. A single reader.read() call can hand you a partial line, a whole line, or several lines at once. We split on \n, keep the last (possibly incomplete) chunk in buffer, and flush it at the end. Every completed line is one of our events.

Dispatching each event to state is a short switch.

if (event.type === 'tool_call') {
    setMessages((prev) => updateLastStreaming(prev, {
        toolStatus: formatToolName(event.tool_name),
    }));
} else if (event.type === 'delta') {
    setMessages((prev) => updateLastStreaming(prev, (last) => ({
        content: last.content + event.content,
        toolStatus: null,
    })));
} else if (event.type === 'done') {
    setMessages((prev) => updateLastStreaming(prev, {
        html: event.html,
        isStreaming: false,
    }));
}

When a tool_call arrives, we show a small "Looking up tickets" label above the still-streaming reply. When deltas start landing, we clear the tool label and append to the message content. When done arrives, we swap in the server-rendered HTML and flip the streaming flag off. The whole round-trip feels like the agent is typing in front of you.

TODO: short video of the Ask There There agent replying to a question, with a "Looking up tickets" label appearing briefly and then the tokens streaming in.

In closing

There are heavier ways to do this. Server-sent events, websockets, a full streaming library on each side. For a chat interface, none of it is necessary. A generator on the server, NDJSON on the wire, and a small buffer loop on the client is about a hundred lines end to end, and it behaves exactly like a proper streaming LLM chat should.

You can read more about the events the SDK emits in the Laravel AI SDK repo. And if you'd like to try There There yourself, we're in private beta right now and you can apply for early access at there-there.app.

That post ended with a promise that we'd find more uses for Jev. Here are two we have since added to There There: smart conditions for workflows, and automatic assignment to a team or person.

Describing a workflow condition in plain language

Workflows already let you match a subject, sender, or message body against text. That works when the words are predictable. A customer asking for a refund can also write "I was charged twice", "Could you reverse this payment?", or something in another language. A list of keywords gets long quickly.

With a smart condition, you describe what should match. Here's one of the example workflows in our local app:

The condition says "The customer asks for a refund or to cancel a payment." When it matches, the workflow adds a private note asking us to review the payment. The note is fixed text. We turn the description into a Jev Boolean question:

public static function question(string $description): Boolean
{
    return new Boolean(
        "The incoming message matches this workflow description: {$description}",
        [
            'true' => 'The incoming message fits the description.',
            'false' => 'The incoming message does not fit the description.',
        ],
    );
}

This question joins the spam and auto-reply questions from the first post in the same inbound classification request. The answer is stored with the message, and the workflow reads its probability from there. It doesn't call Jev again when the workflow runs.

The editor also lets you try a sample email or an existing ticket and see the score before you enable the workflow. Here, a customer asking about a duplicate charge gets a strong match:

Only incoming email is checked. Jev gets the subject, sender, and message text, not the whole ticket history.

Letting Jev choose who should handle a ticket

When a ticket comes in, we need to get it to the right person. At Spatie, one person might handle billing questions, while someone else is better placed to help with a browser issue or a design question. We know who can handle what. The hard part is translating every way a customer might describe a problem into fixed routing rules.

In a workflow, you select the people Jev may choose from and add a short description of what each handles. Here, Dries handles frontend issues, Jef takes billing questions, Jimi handles design, and Zuzana picks up general support:

We ask Jev a Choice question with the people selected in the workflow. It chooses from that list, with one extra option for when nobody fits:

$response = Classification::of($state)
    ->questions(['assignee' => new Choice(
        $instructions,
        [
            ...collect($options)
                ->map(fn (Team|User $assignee) => $candidates->descriptionFor($assignee))
                ->all(),
            'None of these' => 'None of the others clearly fits this ticket.',
        ],
    )])
    ->timeout(10)
    ->classify();

We only assign when Jev has a clear favorite. Sending a vague ticket to the wrong person creates an unnecessary hand-off, so when nobody clearly fits, the action makes no change. Another workflow can pick it up later.

Before asking Jev, we remove disabled members and anyone who can't access the ticket's channel. The same approach can assign a team, with its own list and descriptions. Team and person assignment are separate actions, so choosing a team doesn't restrict which people Jev can choose from. Spam and automatic replies are skipped before either assignment action runs.

In closing

These additions make our workflows a lot more flexible. We can describe what we're looking for in plain language and route matching tickets to the people best placed to help. The workflow still decides what happens next.

If you missed the first part, read how we detect spam and auto-replies with Jev. You can also read the workflow conditions and workflow actions docs, or try There There.

How Jev is different from an LLM

Jev is made by TypeSafe. An LLM generates text: you ask it something, it writes an answer, and if you want structured data back you have to ask for it and hope. Jev doesn't generate anything. You give it some state and a question, and it gives you back a number.

TypeSafe calls these System One models. They read natural language like an LLM does, but instead of writing a reply they pick between answers that you define up front. The probabilities are calibrated, which means they're trained against real outcomes, so across a batch of answers a 0.9 should be right about nine times out of ten.

In practice that means no prose to parse, and no prompt asking the model to please respond with valid JSON.

The Syntax folks made a video explaining it:

Noul, Choice and Score

You define what the answers can be using one of three question types.

A Noul is a yes or no question. The answer is a single number: the probability that the answer is yes. Here's how you ask one:

use Laravel\Ai\Classification;
use Laravel\Ai\Classification\Boolean;

$result = Classification::of('I have asked three times now. Can I please talk to a real person?')
    ->question('urgent', new Boolean('Does this request need an immediate response?'))
    ->classify();

$result['urgent']->probability;            // 0.94
$result['urgent']->isTrue(threshold: 0.8); // true

Notice that you get back 0.94 instead of true. You decide where the cutoff is, which means you can set a different one per question.

A Choice picks one option out of a set that you name. Here's an example:

use Laravel\Ai\Classification\Choice;

$result = Classification::of('My card was charged twice for order A-104. Please refund the duplicate.')
    ->question('department', new Choice('Which team should handle this request?', [
        'billing' => 'Payments, invoices, and refunds',
        'technical' => 'Bugs, outages, and integrations',
        'sales' => 'Pricing, plans, and upgrades',
    ]))
    ->classify();

$result['department']->choice;                   // 'billing'
$result['department']->probabilityOf('billing'); // 0.87
$result['department']->confidence;               // 0.82

Next to the option it picked, you also get a probability for every option, and a confidence score that tells you how concentrated those probabilities were.

A Score rates something against levels that you describe yourself. You could ask how frustrated a customer is, where 0 is calm, 1 is frustrated and 2 is very angry. The answer can land between two levels, so a 1.4 is a perfectly good answer.

The state doesn't have to be a string. When a decision depends on more than one thing, you can pass an array so every part has a name:

Classification::of([
    'subject' => 'Duplicate charge',
    'message' => 'My card was charged twice for order A-104.',
    'order' => ['id' => 'A-104', 'charges' => [49, 49]],
    'refund_policy' => 'Duplicate charges are eligible for a refund.',
])->question('refund_due', new Boolean('The policy entitles this customer to a refund.'))
    ->classify();

That's still one state, even though it holds a message, an order and a policy.

You configure Jev like any other provider in config/ai.php, with a TYPESAFE_API_KEY in your env file.

The problem we wanted to solve

You might have noticed that we launched There There yesterday as well, our new helpdesk. A lot of the mail that arrives in a helpdesk isn't from a customer. Out-of-office replies, bounces, subscription confirmations, DMARC reports. You don't want those in your inbox, and you don't want to pay an LLM to write a title and a summary for each one.

Some of that mail says what it is in the headers. Auto-Submitted, an empty return path, a sender called mailer-daemon. Checking those costs nothing, so we do that first.

Plenty of mail servers don't set those headers. For those we had a list of subject prefixes: Automatische Antwort, Réponse automatique, Out of office, in fifteen languages. Nine more for bounces. On top of that, rules so that a customer asking a question about auto-replies didn't get treated as one.

Every time we found mail that the list missed, we added another string to it.

Replacing the list

The header checks still run first. Everything they can't answer goes to Jev.

We describe each question once, as a case on an enum that also carries its own threshold. That way adding a fourth question is a single case instead of an edit in four files.

enum InboundJudgement: string
{
    case IsAutoResponse = 'is_auto_response';
    case IsBounce = 'is_bounce';
    case IsSpam = 'is_spam';

    public function question(): Boolean
    {
        return match ($this) {
            self::IsAutoResponse => new Boolean(
                'A system sent this mail on its own, rather than a person choosing to write to us.',
                [
                    'true' => 'Sent on a trigger with no human involved at send time: out-of-office
                        notices, delivery reports, ticket acknowledgements, subscription
                        confirmations, digests and alerts. Wording composed in advance still counts',
                    'false' => 'A person sat down and sent this. Still false when a contact form or
                        chat widget wrapped their words in a template and added lines such as Name,
                        E-mail or Subject',
                ],
            ),
            self::IsSpam => new Boolean(
                'This mail is unsolicited bulk mail, a scam, or phishing rather than a genuine
                    message from a customer.',
                [
                    'true' => 'Cold sales outreach, marketing blasts, scams, phishing, or anything
                        the recipient never asked for',
                    'false' => 'A real person writing about the product, their account, or their own
                        support request, however brief or badly written',
                ],
            ),
            // ...
        };
    }

    public function threshold(): float
    {
        return match ($this) {
            self::IsAutoResponse => 0.75,
            self::IsBounce, self::IsSpam => 0.9,
        };
    }
}

Those true and false descriptions are optional, but I'd recommend writing them. They do more work than the question above them.

All the questions the headers couldn't answer go out in one request. Jev reads the state once and answers them in parallel, and you only pay for input tokens, so asking three questions costs the same as asking one. Here's the action that does it:

public function execute(Message $message, Ticket $ticket, Workspace $workspace): void
{
    $judgements = array_filter(
        InboundJudgement::cases(),
        fn (InboundJudgement $judgement) => ! $judgement->settledByHeaders($message),
    );

    if ($judgements === []) {
        return;
    }

    try {
        $response = Classification::of([
            'subject' => $ticket->subject,
            'from_name' => $message->author_name,
            'from_email' => $message->author_email ?? $ticket->contact?->email,
            'message' => Str::limit($message->body_text, 10_000),
        ])
            ->questions($this->questionsFor($judgements))
            ->timeout(10)
            ->classify();

        $verdicts = $this->verdicts($judgements, $response);
    } catch (Throwable $exception) {
        Log::warning('Could not classify an inbound message.', [
            'message_id' => $message->id,
            'error' => $exception->getMessage(),
        ]);

        return;
    }

    $message->updateQuietly([...$verdicts, 'classification' => $response->answers]);
}

There are two things in there I'd suggest copying. The whole call sits in a try block that logs the problem and moves on, because a classification is a nice to have and it shouldn't be able to break the mail pipeline it's helping. And we truncate the message, because an inbound mail can be megabytes long and nothing past the first part of it changes what the mail is.

Turning the answers into booleans is where each question's own threshold is applied. We store the raw probabilities next to them, so we can change a threshold later and see what it would have done:

private function verdicts(array $judgements, ClassificationResponse $response): array
{
    $verdicts = [];

    foreach ($judgements as $judgement) {
        $answer = $response->answer($judgement->value);

        $verdicts[$judgement->value] = $answer->isTrue($judgement->threshold());
    }

    return $verdicts;
}

Those verdicts are stored on the message. When a customer builds a workflow in There There with an "Is spam" condition, checking that condition reads a single column and doesn't call Jev at all.

In closing

I like that Jev does one small thing. It gives you a number and leaves the rest of the decisions in your own code, where you can read them and write tests for them.

It's also fast and cheap enough that you don't really have to think about it. Classifying a mail with three questions at once takes 639ms, and we get around 48 per second when we run them in parallel. We didn't spend any time tuning that, so I'm sure you could get more out of it, but for what we're doing it's fast enough. Jev costs $0.042 per million input tokens and output tokens are free, which for us comes down to four hundredths of a cent per mail, or about 36 cents a month.

We have a list of other places where we want to use this in There There, and in our other products. Expect more Jev powered features soon.

If you want to read more, there are the TypeSafe docs and the Laravel AI SDK. And if you'd like to see the spam detection at work, you can try There There.

The basics

Here's a typical setup in a controller:

use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::partial('name'),
        AllowedFilter::exact('status'),
    )
    ->get();

With that in place, the package wires up two filters that clients can use through the query string.

A request to /users?filter[name]=john runs:

SELECT * FROM users WHERE LOWER(name) LIKE '%john%'

A request to /users?filter[status]=active runs:

SELECT * FROM users WHERE status = 'active'

And a request to /users?filter[name]=john&filter[status]=active runs:

SELECT * FROM users
WHERE LOWER(name) LIKE '%john%'
  AND status = 'active'

Multiple filters in the URL are joined with AND. That's the default and it's what you want most of the time.

The word "allowed" in allowedFilters is doing real work. If a client tries to filter by something you haven't whitelisted, the package throws an InvalidFilterQuery exception instead of silently ignoring it or, worse, letting it through. So a request to /users?filter[email]=acme.com against the controller above results in:

Spatie\QueryBuilder\Exceptions\InvalidFilterQuery
Requested filter(s) `email` are not allowed.
Allowed filter(s) are `name, status`.

The exception has a 400 Bad Request status code, so by default Laravel renders it as a clean error response to the client. You don't have to do anything special to get this behavior.

The new bit: grouping filters

Now imagine you want a single search box that matches across multiple columns. The user types "john" and you want to find rows where either the name or the email contains that value.

Before v7.3.0, you'd reach for a custom callback filter:

$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::exact('status'),
        AllowedFilter::callback('q', function ($query, $value) {
            $query->where('name', 'LIKE', "%{$value}%")
                ->orWhere('email', 'LIKE', "%{$value}%");
        }),
    )
    ->get();

Looks fine at a glance. But a request to /users?filter[status]=active&filter[q]=john runs:

SELECT * FROM users
WHERE status = 'active'
  AND name LIKE '%john%'
   OR email LIKE '%john%'

Spot the bug. The OR binds looser than the AND, so this matches every row whose email contains "john", including inactive users. To fix it, you have to wrap the callback's wheres in their own nested closure. It's an easy thing to forget, and it silently returns wrong data when you do.

In v7.3.0, this becomes a one-liner. Here's how you register a group filter:

$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::groupOr('q', [
            AllowedFilter::partial('name'),
            AllowedFilter::partial('email'),
        ]),
    )
    ->get();

A request to /users?filter[q]=john now runs:

SELECT * FROM users
WHERE (LOWER(name) LIKE '%john%' OR LOWER(email) LIKE '%john%')

The value john is passed to every member of the group, and the conjunction joins them. There's also AllowedFilter::groupAnd() if you want all members to match instead.

Combining group filters with regular filters

Groups compose cleanly with the rest of your filters. Here's a setup that has both a top-level status filter and a group:

$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::exact('status'),
        AllowedFilter::groupOr('q', [
            AllowedFilter::partial('name'),
            AllowedFilter::partial('email'),
        ]),
    )
    ->get();

A request to /users?filter[status]=active&filter[q]=john runs:

SELECT * FROM users
WHERE status = 'active'
  AND (LOWER(name) LIKE '%john%' OR LOWER(email) LIKE '%john%')

The whole group is wrapped in its own parentheses, so the OR can never leak into the status clause. That's the bug pattern that used to bite people who rolled their own callback filter for cross-column search.

You can also register multiple independent groups. Each one becomes its own wrapped scope, and they're joined with AND between them. The members can be any AllowedFilter type, so you can mix partial, exact, scope, and other filters in the same group.

In closing

The upgrade is fully non-breaking. All existing filter behavior is unchanged. The new feature is documented in the filtering docs, and the pull request by Birtan Taşkın has the full reasoning behind the design.

This is one of the many packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.

We just released v4, which adds a few things worth talking about. Let me walk you through them.

Generating slugs with an attribute

For most models, slug generation is mechanical. Pick a source field, pick a destination field, done. In v4, you can express that with an attribute on the model.

use Spatie\Sluggable\Attributes\Sluggable;
use Illuminate\Database\Eloquent\Model;

#[Sluggable(from: 'title', to: 'slug')]
class Post extends Model
{
}

That's it. No trait, no getSlugOptions() method. Save a Post and the package fills in the slug:

$post = Post::create(['title' => 'ActiveRecord is awesome']);

$post->slug; // "activerecord-is-awesome"

Self-healing URLs

Picture this. You publish a new post titled "Anouncing v4 of laravel-sluggable". The slug becomes anouncing-v4-of-laravel-sluggable, you share the link, a few people bookmark it. Five minutes later you notice the missing n and fix the title. The slug regenerates to announcing-v4-of-laravel-sluggable, and now everyone who clicked the first version hits a 404.

The usual answer is a redirects table: store the old slug, forward it to the new one. It works, but every rename adds a row, and after a while it's another moving piece to maintain.

Self-healing URLs solve this differently. The route key combines the slug with the primary key, so the slug is decorative and the id is what actually identifies the record.

use Spatie\Sluggable\Attributes\Sluggable;
use Spatie\Sluggable\HasSlug;
use Illuminate\Database\Eloquent\Model;

#[Sluggable(from: 'title', to: 'slug', selfHealing: true)]
class Post extends Model
{
    use HasSlug;
}

If your post has slug hello-world and id 5, the URL becomes /posts/hello-world-5. Rename the post to Greetings, World and the canonical URL becomes /posts/greetings-world-5. Old links keep working because the package can still find the record by id, and it sends a permanent redirect to the new canonical URL.

The redirect status code is 308 Permanent Redirect. In v3 it was 301. The reason for the change is that 301 is allowed to silently downgrade PUT, PATCH, and DELETE to GET when followed, which gets you a 405 Method Not Allowed if the new URL doesn't accept GET. 308 keeps the method intact.

Overridable actions

Slug generation and the self-healing URL format are now expressed as three actions: one for generating the slug, one for building the self-healing route key, and one for parsing it back out. All three can be swapped through config/sluggable.php. The example below customizes the two self-healing actions; the slug generator stays on its default behavior.

The use case I had in mind was self-healing URLs that put the id first. Say you want /posts/5-hello-world instead of /posts/hello-world-5. Extend the default builder action and put the identifier in front:

namespace App\Sluggable;

use Spatie\Sluggable\Actions\BuildSelfHealingRouteKeyAction;

class IdFirstBuildAction extends BuildSelfHealingRouteKeyAction
{
    public function execute(string $slug, int|string $identifier, string $separator): string
    {
        if ($slug === '') {
            return (string) $identifier;
        }

        return "{$identifier}{$separator}{$slug}";
    }
}

The extractor needs the inverse logic. The default action looks for the last separator, because slugs can contain the separator themselves, so swap it for one that reads the identifier from the front:

namespace App\Sluggable;

use Illuminate\Support\Str;
use Spatie\Sluggable\Actions\ExtractIdentifierFromSelfHealingRouteKeyAction;

class IdFirstExtractAction extends ExtractIdentifierFromSelfHealingRouteKeyAction
{
    public function execute(string $value, string $separator): array
    {
        $identifier = Str::before($value, $separator);

        if ($identifier === $value || ! ctype_digit($identifier)) {
            return ['slug' => $value, 'identifier' => null];
        }

        return [
            'slug' => Str::after($value, $separator),
            'identifier' => $identifier,
        ];
    }
}

Str::before returns the original string when the separator isn't present, which is how the no-separator case is detected. The ctype_digit check rejects values where the prefix isn't numeric, so models with non-numeric primary keys like ULIDs need to swap that for a regex.

Wire both into the config and you're done:

// config/sluggable.php
'build_self_healing_route_key' => App\Sluggable\IdFirstBuildAction::class,
'extract_identifier_from_self_healing_route_key' => App\Sluggable\IdFirstExtractAction::class,

The full reference, including a simpler uppercase variant and a custom slug generator, lives in the overriding actions docs.

A bundled Boost skill

Laravel Boost is an MCP server from the Laravel team that exposes your application's installed packages and versions to your AI assistant, so prompts produce code that fits your stack instead of generic Laravel snippets. Packages can bundle their own Boost skills, and Boost discovers them automatically.

This package ships with a sluggable-development skill that walks your assistant through adding a sluggable model: picking the source field, deciding whether you need self-healing URLs, generating the migration, and dropping the attribute or trait on the model. If you have Boost installed, this is the easiest way to add a new sluggable model to your project.

In closing

You can find the package on GitHub and the full documentation on our docs site. Coming from v3? The upgrade guide covers the breaking changes (mostly minimum versions and a callable to Closure migration).

This is one of many packages we've built at Spatie. If you want to support our open source work, consider picking up one of our paid products.

We just released Laravel Mobile Pass, a package that lets you generate those Apple and Google passes from a Laravel app and send updates to already issues passes.

Together with the package, we also published a demo site where you can create Apple Wallet passes and push an update so you can see it all working on your own iOS device.

Dan Johnson and I have been working on it for a while. Let me walk you through what it can do.

A simple example

Here's the shortest useful thing you can build with it. An Apple Wallet boarding pass for a flight:

use Spatie\LaravelMobilePass\Builders\Apple\AirlinePassBuilder;
use Spatie\LaravelMobilePass\Enums\BarcodeType;

$mobilePass = AirlinePassBuilder::make()
    ->setOrganizationName('Artisan Airways')
    ->setSerialNumber('ART-103')
    ->setDescription('Boarding Pass')
    ->addHeaderField('flight-no', 'ART103', label: 'Flight')
    ->addHeaderField('seat', '66F')
    ->addField('departure', 'ABU', label: 'Abu Dhabi International')
    ->addField('destination', 'LHR', label: 'London Heathrow')
    ->addSecondaryField('name', 'Mary Smith')
    ->setBarcode(BarcodeType::Pdf417, 'ART-103-66F')
    ->save();

Calling save() gives you back a MobilePass model. Nothing is written to disk. The whole pass (fields, images, barcode, the lot) lives as a row in the mobile_passes table that ships with the package.

Handing the pass to a user

So in the example above, the $mobilePass variable contains MobilePass Eloquent model. It plays nice with the parts of Laravel you already know. Here are a few ways you can use it to send a mobile pass to a user

Return it straight from a controller. The model implements Responsable, so the package takes care of signing and serving the .pkpass file.

// in a controller
return $mobilePass;

Attach it to an outgoing mail. The model also implements Attachable, which means you can drop it into a Mailable's attachments() method and Laravel figures out the rest.

class FlightBooked extends Mailable
{
    public function __construct(public MobilePass $mobilePass) {}

    public function attachments(): array
    {
        return [$this->mobilePass];
    }
}

The user taps through, sees the pass preview in Apple Wallet, and taps Add.

Apple then calls back to your app to register the device against the pass. The package handles that endpoint and stores the registration. That link between pass and device is what lets you push updates later.

Pushing a live update

Here's the part I like most. If a seat gets reassigned or a gate changes, you can update the pass from your app and the version on the user's phone updates within a minute, without them doing anything.

$mobilePass->updateField('seat', '13A');

Under the hood, the package dispatches a job that notifies Apple through APNs. Apple pings the device. The device fetches the new version from your server. Wallet swaps the old pass for the new one.

Now this all happens silently, without warning the user. If you want the user to see a notification when the value changes, pass a changeMessage:

$mobilePass->updateField(
    'seat',
    '13A',
    changeMessage: 'Your seat was changed to :value',
);

Very cool! If you tap that notification, you,'ll notice that Passbook highlights what was changed.

Google Wallet is supported too

Google Wallet works a little differently. Google wants you to declare a Class once (a shared template for a batch of passes) and then issue individual Objects against that class. The package covers both.

use Spatie\LaravelMobilePass\Builders\Google\EventTicketPassBuilder;
use Spatie\LaravelMobilePass\Enums\BarcodeType;

$mobilePass = EventTicketPassBuilder::make()
    ->setClass('spring-tour-2026')
    ->setAttendeeName('Mary Smith')
    ->setSection('Floor A')
    ->setRow('12')
    ->setSeat('24')
    ->setBarcode(BarcodeType::Qr, 'TICKET-12345')
    ->save();

Returning $mobilePass from a controller does the right thing on either platform. Android users get redirected to the Google Wallet save URL. iPhone users get the .pkpass download. The Responsable implementation picks the right response for the platform the pass was built for.

A few more things worth knowing

Picture the boarding pass from earlier. You hand it to the user three days before the flight. They install it and promptly forget it exists. An hour before departure, or the moment they walk into the airport, the pass drifts onto their lock screen without them doing anything. By the time they reach the gate, their thumb is already on it.

That trick is called pass relevance, and wiring it up is two calls on the builder:

$builder
    ->addLocation(latitude: 25.2528, longitude: 55.3644)
    ->setRelevantDate($flight->departs_at);

The location turns on the geofence. The date turns on the clock. Combine both and Wallet shows the pass at the right place and the right moment. It's the small thing that makes a Wallet pass feel like it belongs on the device instead of inside an email.

Passes don't need to stick around once they've served their purpose. When a coupon has been redeemed or a ticket is from last night, call expire() on the model and Wallet greys it out and drops it from the lock screen:

$mobilePass->expire();

If you issue Google Wallet passes, you probably want to know when someone actually saves one to their Wallet, or later removes it. Google pings your app on both events. The package listens for those callbacks and fires regular Laravel events you can subscribe to:

Event::listen(GoogleMobilePassSaved::class, function (GoogleMobilePassSaved $event) {
    // $event->mobilePass is now on the user's Wallet
});

Drop in a listener if you want to record activations, send a thank-you email, or kick off any other flow. It's the kind of integration that would otherwise involve reading Google's callback spec and signing JWTs by hand. You shouldn't have to.

Try it live

We put up a demo at mobile-pass-demo.spatie.be. Pick a pass type on the landing page, scan the QR code with your iPhone, install the pass, and hit the simulate-change button. Your Wallet pulls the new version a moment later. The full source of the demo app is on GitHub if you want to see how everything ties together.

In closing

At Laracon India 2025, Dan Johnson showed me a prototype he had been hacking on for generating Apple Wallet passes. I loved the idea, we decided to team up, and this package is what came out the other end. It took a while to get here, but we finally gave it the polish we wanted.

Mobile passes aren't new. Apple shipped Wallet (back then called Passbook) with iOS 6 in 2012, and Google followed with their own Wallet passes a few years later.

Given the two have been around for that long, I was surprised nobody had built a solid Laravel package around either platform yet. Luckily there's one now. Hope you like it!

The code is on GitHub. The full documentation is at spatie.be.

This is one of the many packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.

We care about using AI in a particular way. It should help support agents write better replies, not substitute for them. The human stays in charge of the conversation, and the model does the unglamorous work of drafting, rephrasing, and suggesting links. There There is in private beta right now, and you can apply for early access at there-there.app.

We're building There There with Laravel and Inertia, and we lean heavily on the latest features Inertia v3 brings. This post is about another one: prefetching on hover.

Using prefetch on hover

In a helpdesk, a support agent flips between views constantly. My open tickets, unassigned, waiting, spam, team views, custom filters. Every switch triggers a fresh page load against a different filter. If each switch blocks on a round-trip, the sidebar starts to feel like dead weight.

Inertia v3 has a built-in prefetching API that covers this neatly. Instead of waiting for the click, we fetch the view's data as soon as the cursor hovers over the link, and keep the result in a short-lived cache so the actual navigation feels instant.

Here's the core of our sidebar view link.

<Link
    href={buildViewUrl(view)}
    prefetch="hover"
    cacheFor="30s"
    preserveState={isOnTickets}
    preserveScroll={isOnTickets}
>
    <Icon className="size-4" />
    <span>{view.label}</span>
</Link>

prefetch="hover" is the whole mechanism. After the cursor sits on the link for 75ms, Inertia fires the underlying request in the background. When the agent actually clicks, the response is already in memory, and the page swaps without a network wait.

cacheFor is where the real tuning happens. The default is 30 seconds. For our ticket views, that's a sweet spot: long enough that flipping back and forth feels free, short enough that the counts don't go visibly stale. You can push it higher for more static lists, or drop it to "0" for views where freshness matters more than speed.

Here it is in action. The cursor hovers, Inertia warms the cache in the background, and the click lands on data that's already there.

One small gotcha is worth flagging. When an agent navigates away from a view, you often want to cancel any in-flight requests so you don't paint stale data. The obvious call is router.cancelAll(), but that also cancels prefetches that are happily warming the cache for views the agent is about to visit.

Inertia v3 lets you scope that. Here's how we cancel the active visit without touching prefetches.

router.cancelAll({ async: false, prefetch: false });

The flags tell Inertia to keep background prefetches and async visits (like an infinite scroll) alive, while cancelling the normal page visit. The agent gets an immediate navigation and the sidebar stays primed for the next move.

In closing

Prefetching on hover is one of those features that costs almost nothing to turn on and changes how the app feels. One prop, a cache duration, and you're done. The cancellation scoping is the one detail worth knowing about, because without it you'll undo your own optimisation the first time you navigate away from a view.

You can read more in the Inertia v3 prefetching guide. And if you'd like to try There There yourself, we're in private beta right now and you can apply for early access at there-there.app.

One thing we care about in particular is using AI to help humans craft better responses, not to replace them. The agent stays in charge of the conversation. The model just helps them reply faster and a little sharper. There There is in private beta right now, and you can apply for early access at there-there.app.

We're building There There with Laravel and Inertia, and we lean heavily on the latest features Inertia v3 brings. In this post I'd like to give one example: optimistic updates.

Using optimistic updates

A support agent toggles a lot of small things in the course of a day. Adding a tag to a ticket, granting a teammate access to a channel, flipping a workflow on or off. Each of those is a single click that triggers a server round-trip.

If the UI waits for that round-trip before showing the change, the app feels sluggish. Not broken, just slow. And in a tool you live in all day, that compounds.

Inertia v3 ships with a first-class optimistic updates API that handles this nicely. Instead of waiting on a response, we immediately update the UI to reflect the change and let Inertia roll it back if the request fails.

Here's how it looks on our member detail page. An admin can toggle whether a teammate belongs to a team. The list of teams comes in as a prop, and we render a switch next to each one.

{teams.map((team) => (
    <div key={team.id}>
        <span>{team.name}</span>
        <Switch
            checked={team.is_member}
            onCheckedChange={() => handleToggleTeam(team)}
        />
    </div>
))}

When the switch is flipped, handleToggleTeam runs.

function handleToggleTeam(team) {
    const optimistic = router.optimistic((props) => ({
        teams: props.teams.map((t) =>
            t.id === team.id ? { ...t, is_member: !t.is_member } : t,
        ),
    }));

    if (team.is_member) {
        optimistic.delete(removeTeamMember.url({
            team: team.ulid,
            user: member.ulid,
        }), { preserveScroll: true });

        return;
    }

    optimistic.post(addTeamMember.url({
        team: team.ulid,
        user: member.ulid,
    }), {}, { preserveScroll: true });
}

The function we pass to router.optimistic receives the current props and returns the keys we want to patch. Inertia applies that patch immediately, so the toggle in the UI flips before the request leaves the browser. When the response comes back, Inertia merges the real server props on top.

I like the chained style here because the same optimistic patch can lead to either a post or a delete. We capture the optimistic builder once and pick the verb after.

Here it is in action. The toggle flips immediately, and the request happens in the background.

For simpler cases there's a second style. You pass optimistic straight as an option to the verb. Here's our workflow toggle:

function handleToggle(workflow) {
    router.patch(workflowToggle.url(workflow.ulid), {}, {
        optimistic: (props) => ({
            workflows: props.workflows.map((w) =>
                w.id === workflow.id ? { ...w, is_enabled: !w.is_enabled } : w,
            ),
        }),
    });
}

Same idea. You describe the patched shape, hand it to Inertia, and let it deal with the rest.

If the server returns a non-2xx response, Inertia reverts the optimistic change automatically. There's no manual restore code to write. Validation errors land where you'd expect, and only the keys you touched in the callback are snapshotted, so unrelated state stays untouched. Concurrent requests each carry their own snapshot, which means a slow request won't undo a faster one that already returned.

In closing

Optimistic updates used to mean keeping a parallel copy of state, reverting it on rejection, and reasoning carefully about race conditions. With Inertia v3, you describe the next state and that's it. The whole interaction is about ten lines.

You can read the official documentation in the Inertia v3 optimistic updates guide. And if you'd like to try There There yourself, we're in private beta right now and you can apply for early access at there-there.app.

Why we built Scotty

Even though services like Laravel Cloud make it possible to never think about servers again, I still prefer deploying to my own servers for some projects. I know my way around them, I can pick whichever server provider I want, and I have full control over the environment.

Tools like Laravel Forge have built-in deploy functionality, and it works well. But I've always preferred running deploy scripts manually from my terminal. I want to see exactly what's happening while it runs, and when something goes wrong, I want to be staring at the output the moment it happens, not clicking through a web UI to find a log.

For years, I used Laravel Envoy for this. It does the job, but I wanted nicer output while tasks are running, and the ability to pause execution mid-deploy. Envoy uses a Blade-based file format, which works fine for us. But not everyone wants to write Blade syntax for their deploy scripts. So Scotty also offers a plain bash format for people who prefer that.

Scotty was built with the help of AI, using the Envoy codebase as a source. Even though Scotty is a rebuild from scratch, in spirit it is a fork of Envoy. Credits to Laravel for providing the foundation. You can read the full acknowledgement in the Scotty repo.

Using Scotty

Defining tasks and deploying

You define your tasks in a Scotty.sh file. It's just plain bash with some annotation comments. Your editor highlights it correctly, you get full shell support out of the box. Here's what that looks like:

#!/usr/bin/env scotty

# @servers remote=deployer@your-server.com

# @task on:remote
deploy() {
    cd /var/www/my-app
    git pull origin main
    php artisan migrate --force
}

Deploy with a single command:

scotty run deploy

Scotty connects to your server, runs each task in order, and shows you what's happening in real time. Each task displays its name, a step counter, elapsed time, and the command currently being executed. When everything finishes, you get a summary table with timing for each step.

These screenshots are from deploying this very blog. You can find the deploy file on GitHub.

If a task fails, its output is shown and execution stops right there so you can investigate.

Writing plain bash instead of Blade

In addition to being able to read Envoy.blade.php files, Scotty introduces a new Scotty.sh format. Every line is real bash. Tasks are just bash functions with a # @task annotation that tells Scotty which server to run them on. Macros group tasks into a sequence. Variables are plain bash variables, available everywhere.

Because it's all valid bash, you can use helper functions, computed values like $(date +%Y%m%d-%H%M%S), and any shell construct you'd normally use. No Blade directives, no PHP @setup blocks, no {{ $variable }} interpolation.

You can also pass variables from the command line. Running scotty run deploy --branch=develop makes $BRANCH available in your tasks. The key is automatically uppercased.

You can list all available tasks and macros with scotty tasks:

Pausing, resuming, and pretending

You can press p at any time during execution to pause after the current task finishes. Press Enter to resume, or Ctrl+C to cancel. This is handy when you want to check something on the server mid-deploy before continuing.

There's also a pretend mode (scotty run deploy --pretend) that shows you exactly which SSH commands would be executed without actually running them. And a summary mode (scotty run deploy --summary) that hides task output and only shows results.

Validating your setup with doctor

Before your first deploy to a new server, you can run scotty doctor to validate your setup. It checks that your file parses correctly, verifies SSH connectivity to each server, and confirms that tools like php, composer, node, and git are available on the remote machine.

Migrating from Envoy

If you're already using Laravel Envoy, Scotty can read your Envoy.blade.php file directly. No changes needed. Just run scotty run deploy and it works. From there, you can gradually migrate to the Scotty.sh format if you want to, or keep using Blade.

If you're new to all of this, the Your first deploy script page in the docs walks you through everything step by step.

In closing

Scotty gives you a clean, modern way to run deploy scripts and other SSH tasks from your terminal. Plain bash, beautiful output, and full control over every step.

You can find the full documentation on our docs site and the source code on GitHub. This is one of the many tools and packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.

In Flare, Mailcoach, and Oh Dear we use it to build audit logs, so we can track what users are doing: who changed a setting, who deleted a project, who invited a team member. If you need something similar in your app, this package makes it easy.

This major release requires PHP 8.4+ and Laravel 12+, and brings a cleaner API, a better database schema, and customizable internals. Let me walk you through what the package can do and what's new in v5.

Using the package

At its core, the package lets you log what happens in your application. The simplest usage looks like this:

activity()->log('Look mum, I logged something');

You can retrieve all logged activities using the Activity model:

use Spatie\Activitylog\Models\Activity;

$lastActivity = Activity::all()->last();

// returns 'Look mum, I logged something'
$lastActivity->description;

Most of the time you want to know two things: what was affected, and who did it. The package calls these the subject and the causer. You can also attach custom properties for any extra context you need:

activity()
   ->performedOn($article)
   ->causedBy($user)
   ->withProperties(['via' => 'admin-panel'])
   ->log('edited');

$lastActivity = Activity::all()->last();

// the article that was edited
$lastActivity->subject;

// the user who edited it
$lastActivity->causer;

// 'admin-panel'
$lastActivity->getProperty('via');

The Activity model provides query scopes to filter your activity log:

Activity::forSubject($newsItem)->get();
Activity::causedBy($user)->get();
Activity::forEvent('updated')->get();
Activity::inLog('payment')->get();

// or combine them
Activity::forSubject($newsItem)
    ->causedBy($user)
    ->forEvent('updated')
    ->get();

Automatic model event logging

Imagine you want to track whenever a model is created, updated, or deleted. Just add the LogsActivity trait to your model. In v5, that's all you need for basic logging:

use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Concerns\LogsActivity;

class NewsItem extends Model
{
    use LogsActivity;
}

That's it. No getActivitylogOptions() method needed. Now imagine you also want to track which attributes changed. Override the method and tell it what to watch:

use Spatie\Activitylog\Support\LogOptions;

class NewsItem extends Model
{
    use LogsActivity;

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

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
            ->logOnly(['name', 'text']);
    }
}

Now when you update a news item, the package tracks exactly what changed:

$newsItem->name = 'updated name';
$newsItem->save();

$activity = Activity::all()->last();
$activity->attribute_changes;
// [
//     'attributes' => [
//         'name' => 'updated name',
//         'text' => 'Lorem',
//     ],
//     'old' => [
//         'name' => 'original name',
//         'text' => 'Lorem',
//     ],
// ]

You can log all fillable attributes with logFillable(), all unguarded attributes with logUnguarded(), or use logAll() combined with logExcept() to log everything except sensitive fields like passwords.

If you only want to see what actually changed rather than all tracked attributes, chain logOnlyDirty().

Running code before an activity is saved

When a model event is logged, you can hook into the process by defining a beforeActivityLogged() method on your model:

class NewsItem extends Model
{
    use LogsActivity;

    public function beforeActivityLogged(Activity $activity, string $eventName): void
    {
        $activity->properties = $activity->properties->merge([
            'ip_address' => request()->ip(),
        ]);
    }
}

This runs right before the activity is persisted, giving you a chance to enrich it with extra data.

Customizable action classes

The core operations of the package (logging activities and cleaning old records) are now handled by action classes. You can extend these and swap them in via config.

For example, say you want to save activities to the queue instead of writing them to the database during the request. Extend the action and override the save() method:

use Spatie\Activitylog\Actions\LogActivityAction;

class QueuedLogAction extends LogActivityAction
{
    protected function save(Model $activity): void
    {
        dispatch(new SaveActivityJob($activity->toArray()));
    }
}

Then tell the package to use your custom action in config/activitylog.php:

'actions' => [
    'log_activity' => QueuedLogAction::class,
],

You can also override transformChanges() to manipulate the changes array before saving. Here's an example that redacts password changes so they never end up in your activity log:

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Arr;
use Spatie\Activitylog\Actions\LogActivityAction;

class RedactSensitiveFieldsAction extends LogActivityAction
{
    protected function transformChanges(Model $activity): void
    {
        $changes = $activity->attribute_changes?->toArray() ?? [];

        Arr::forget($changes, ['attributes.password', 'old.password']);

        $activity->attribute_changes = collect($changes);
    }
}

Buffering activities

Say you have an endpoint that updates product prices in bulk. Each product update triggers a model event, and each model event logs an activity. With 200 products, that's 200 INSERT queries just for activity logging.

foreach ($products as $product) {
    // each update triggers an activity INSERT query
    $product->update(['price' => $newPrices[$product->id]]);
}

With buffering enabled, the package collects all those activities in memory during the request and inserts them in a single bulk query after the response has been sent to the client. Your user gets a fast response, and the database does one insert instead of 200.

Buffering is off by default. You can enable it in the config/activitylog.php config file. No other code changes needed. All existing logging code (both automatic model event logging and manual activity()->log() calls) will be buffered automatically.

Under the hood, the ActivityBuffer class collects activities in an array and inserts them all at once when flushed:

class ActivityBuffer
{
    protected array $pending = [];

    public function add(Model $activity): void
    {
        $this->pending[] = $this->prepareForInsert($activity);
    }

    public function flush(): void
    {
        if (empty($this->pending)) {
            return;
        }

        $modelClass = Config::activityModel();
        $modelClass::query()->insert($this->pending);

        $this->pending = [];
    }
}

The service provider takes care of flushing the buffer at the right time:

protected function registerActivityBufferFlushing(): void
{
    // flush after the response has been sent
    $this->app->terminating(fn () => app(ActivityBuffer::class)->flush());

    // flush after each queued job
    $this->app['events']->listen(
        [JobProcessed::class, JobFailed::class],
        fn () => app(ActivityBuffer::class)->flush(),
    );

    // safety net if the application terminates unexpectedly
    register_shutdown_function(function () {
        try {
            app(ActivityBuffer::class)->flush();
        } catch (\Throwable) {
        }
    });
}

One thing to be aware of: buffered activities won't have a database ID until the buffer is flushed. If you need to read back the activity ID immediately after logging, don't enable buffering.

This works with Octane (the buffer is a scoped binding, so it resets between requests) and queues out of the box.

In closing

v5 doesn't bring a lot of new features, but it modernizes the package, cleans up the internals, and makes the things that were hard to customize in v4 easy to swap out. If you're upgrading from v4, be aware that there are quite a few breaking changes. Check the upgrade guide for the full list.

You can find the complete documentation at spatie.be/docs/laravel-activitylog and the source code on GitHub.

This is one of the many packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.

Our query builder takes care of all of that. It reads query parameters from the URL, translates them into the right Eloquent queries, and makes sure only the things you've explicitly allowed can be queried.

// GET /users?filter[name]=John&include=posts&sort=-created_at

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name')
    ->allowedIncludes('posts')
    ->allowedSorts('created_at')
    ->get();

// select * from users where name = 'John' order by created_at desc

This major version requires PHP 8.3+ and Laravel 12 or higher, and brings a cleaner API along with some features we've been wanting to add for a while.

Let me walk you through how the package works and what's new.

Using the package

The idea is simple: your API consumers pass query parameters in the URL, and the package translates those into the right Eloquent query. You just define what's allowed.

Say you have a User model and you want to let API consumers filter by name. Here's all you need:

use Spatie\QueryBuilder\QueryBuilder;

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name')
    ->get();

Now when someone requests /users?filter[name]=John, the package adds the appropriate WHERE clause to the query:

select * from users where name = 'John'

Only the filters you've explicitly allowed will work. If someone tries /users?filter[secret_column]=something, the package throws an InvalidFilterQuery exception. Your database schema stays hidden from API consumers.

You can allow multiple filters at once and combine them with sorting:

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name', 'email')
    ->allowedSorts('name', 'created_at')
    ->get();

A request to /users?filter[name]=John&sort=-created_at now filters by name and sorts by created_at descending (the - prefix means descending).

Including relationships works the same way. If you want consumers to be able to eager-load a user's posts:

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name', 'email')
    ->allowedIncludes('posts', 'permissions')
    ->allowedSorts('name', 'created_at')
    ->get();

A request to /users?include=posts&filter[name]=John&sort=-created_at now returns users named John, sorted by creation date, with their posts eager-loaded.

You can also select specific fields to keep your responses lean:

$users = QueryBuilder::for(User::class)
    ->allowedFields('id', 'name', 'email')
    ->allowedIncludes('posts')
    ->get();

With /users?fields=id,email&include=posts, only the id and email columns are selected.

The QueryBuilder extends Laravel's default Eloquent builder, so all your favorite methods still work. You can combine it with existing queries:

$query = User::where('active', true);

$users = QueryBuilder::for($query)
    ->withTrashed()
    ->allowedFilters('name')
    ->allowedIncludes('posts', 'permissions')
    ->where('score', '>', 42)
    ->get();

The query parameter names follow the JSON API specification as closely as possible. This means you get a consistent, well-documented API surface without having to think about naming conventions.

What's new in v7

Variadic parameters

All the allowed* methods now accept variadic arguments instead of arrays.

// Before (v6)
QueryBuilder::for(User::class)
    ->allowedFilters(['name', 'email'])
    ->allowedSorts(['name'])
    ->allowedIncludes(['posts']);

// After (v7)
QueryBuilder::for(User::class)
    ->allowedFilters('name', 'email')
    ->allowedSorts('name')
    ->allowedIncludes('posts');

If you have a dynamic list, use the spread operator:

$filters = ['name', 'email'];
QueryBuilder::for(User::class)->allowedFilters(...$filters);

Aggregate includes

This is the biggest new feature. You can now include aggregate values for related models using AllowedInclude::min(), AllowedInclude::max(), AllowedInclude::sum(), and AllowedInclude::avg(). Under the hood, these map to Laravel's withMin(), withMax(), withSum() and withAvg() methods.

use Spatie\QueryBuilder\AllowedInclude;

$users = QueryBuilder::for(User::class)
    ->allowedIncludes(
        'posts',
        AllowedInclude::count('postsCount'),
        AllowedInclude::sum('postsViewsSum', 'posts', 'views'),
        AllowedInclude::avg('postsViewsAvg', 'posts', 'views'),
    )
    ->get();

A request to /users?include=posts,postsCount,postsViewsSum now returns users with their posts, the post count, and the total views across all posts.

You can constrain these aggregates too. For example, to only count published posts:

use Spatie\QueryBuilder\AllowedInclude;
use Illuminate\Database\Eloquent\Builder;

$users = QueryBuilder::for(User::class)
    ->allowedIncludes(
        AllowedInclude::count(
            'publishedPostsCount',
            'posts',
            fn (Builder $query) => $query->where('published', true)
        ),
        AllowedInclude::sum(
            'publishedPostsViewsSum',
            'posts',
            'views',
            constraint: fn (Builder $query) => $query->where('published', true)
        ),
    )
    ->get();

All four aggregate types support these constraint closures, making it possible to build endpoints that return computed data alongside your models without writing custom query logic.

A perfect match for Laravel's JSON:API resources

Laravel 13 is adding built-in support for JSON:API resources. These new JsonApiResource classes handle the serialization side: they produce responses compliant with the JSON:API specification.

You create one by adding the --json-api flag:

php artisan make:resource PostResource --json-api

This generates a resource class where you define attributes and relationships:

use Illuminate\Http\Resources\JsonApi\JsonApiResource;

class PostResource extends JsonApiResource
{
    public $attributes = [
        'title',
        'body',
        'created_at',
    ];

    public $relationships = [
        'author',
        'comments',
    ];
}

Return it from your controller, and Laravel produces a fully compliant JSON:API response:

{
    "data": {
        "id": "1",
        "type": "posts",
        "attributes": {
            "title": "Hello World",
            "body": "This is my first post."
        },
        "relationships": {
            "author": {
                "data": { "id": "1", "type": "users" }
            }
        }
    },
    "included": [
        {
            "id": "1",
            "type": "users",
            "attributes": { "name": "Taylor Otwell" }
        }
    ]
}

Clients can request specific fields and includes via query parameters like /api/posts?fields[posts]=title&include=author. Laravel's JSON:API resources handle all of that on the response side.

The Laravel docs explicitly mention our package as a companion:

Laravel's JSON:API resources handle the serialization of your responses. If you also need to parse incoming JSON:API query parameters such as filters and sorts, Spatie's Laravel Query Builder is a great companion package.

So while Laravel's new JSON:API resources take care of the output format, our query builder handles the input side: parsing filter, sort, include and fields parameters from the request and translating them into the right Eloquent queries. Together they give you a full JSON:API implementation with very little boilerplate.

In closing

To upgrade from v6, check the upgrade guide. The changes are mostly mechanical. Check the guide for the full list.

You can find the full source code and documentation on GitHub. We also have extensive documentation on the Spatie website.

This is one of the many packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.

Previous versions required Meilisearch as the search engine. That works well, but it means running a separate service.

With v3, your application's own database is all you need. It supports SQLite, MySQL, PostgreSQL, and MariaDB out of the box, and it's the new default.

Let me walk you through it.

Using Laravel Site Search

First, install the package via composer:

composer require spatie/laravel-site-search

Next, you should publish and run the migrations:

php artisan vendor:publish --tag="site-search-migrations"
php artisan migrate

Then, create a search profile. The package provides an artisan command for this:

php artisan site-search:create-profile

This will ask you for the name and URL of the site you want to index. Once configured, crawl the site:

php artisan site-search:crawl

That's it. No Meilisearch to install, no external service to configure. The package uses your existing database. Under the hood, the crawling is powered by our own spatie/crawler package, which recently got a major update as well.

The Search class provides a fluent API for querying your index:

use Spatie\SiteSearch\Search;

$searchResults = Search::onIndex('my-site')
    ->query('laravel middleware')
    ->get();

You can limit the number of results:

$searchResults = Search::onIndex('my-site')
    ->query('laravel middleware')
    ->limit(10)
    ->get();

Or paginate them, which integrates with Laravel's built-in pagination:

$searchResults = Search::onIndex('my-site')
    ->query('laravel middleware')
    ->paginate(20);

Each result is a Hit object with properties like url, pageTitle, entry, and description. You can also get a highlighted snippet where matching terms are wrapped in <em> tags:

foreach ($searchResults->hits as $hit) {
    echo $hit->url;
    echo $hit->title();
    echo $hit->highlightedSnippet();
}

The database driver

The biggest addition in v3 is the DatabaseDriver. Instead of relying on Meilisearch, it stores all indexed documents in a site_search_documents table in your own database and uses each database engine's native full-text search capabilities.

For SQLite, it creates FTS5 virtual tables with porter stemming and unicode support. BM25 is used for relevance ranking, and highlighted snippets are generated natively by FTS5.

For MySQL and MariaDB, it sets up FULLTEXT indexes and uses boolean mode search. Highlighting is handled in PHP after the query.

For PostgreSQL, the driver creates tsvector columns with GIN indexes. It uses ts_rank() for relevance scoring and ts_headline() for generating highlighted snippets. Content is weighted so that matches in headings rank higher than matches in the body text.

All supported databases provide stemming (so "running" matches "run"), prefix matching ("auth" matches "authentication"), relevance ranking, and highlighted search results with matching terms wrapped in <em> tags.

Since the database driver is the new default, getting started requires no configuration beyond what you already have. Install the package, run the migration, set up a search profile, and you're ready to crawl.

Meilisearch is still supported. If you're already using Meilisearch or need its advanced features like synonyms and custom ranking rules, nothing changes for you. The Meilisearch driver is still fully supported. You can switch between drivers by setting the default_driver in the config or per search profile via the driver_class attribute.

// config/site-search.php

'default_driver' => \Spatie\SiteSearch\Drivers\MeiliSearchDriver::class,

We use it ourselves

We're using laravel-site-search in production on several of our own sites. The search on freek.dev, the documentation search on Oh Dear, and the documentation search on Mailcoach are all powered by this package.

The source code of freek.dev is open source, so you can see exactly how the package is integrated. The Livewire search component handles querying and displaying results. The search profile configures the crawler and determines which pages should be indexed. A custom indexer cleans up page titles before storing them. And the config file ties it all together, specifying which CSS selectors and URLs to ignore during indexing.

In closing

With v3, laravel-site-search no longer requires any external dependencies. Install it, point it at your site, and search. If you're using MySQL, PostgreSQL, SQLite, or MariaDB, you already have everything you need.

You can find the full documentation on the documentation site. The source code is available on GitHub.

This is one of the many packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.

Our spatie/invade package provides a tiny invade function that lets you read, write, and call private members on any object.

You probably shouldn't reach for this package often. It's most useful in tests or when you're building a package that needs to integrate deeply with objects you don't control.

Let me walk you through how it works.

Using invade

Imagine you have a class with private members:

class MyClass
{
    private string $privateProperty = 'private value';

    private function privateMethod(): string
    {
        return 'private return value';
    }
}

If you try to access that private property from outside the class, PHP will stop you:

$myClass = new MyClass();

$myClass->privateProperty;
// Error: Cannot access private property MyClass::$privateProperty

With invade, you can get around that. Install the package via composer:

composer require spatie/invade

Now you can read that private property:

// returns 'private value'
invade($myClass)->privateProperty;

You can set it too:

invade($myClass)->privateProperty = 'changed value';

// returns 'changed value'
invade($myClass)->privateProperty;

And you can call private methods:

// returns 'private return value'
invade($myClass)->privateMethod();

The API is clean and reads well. But the interesting part is what happens under the hood. Before we look at the package code, there's a PHP rule you need to know about first.

How it works under the hood

Let me walk you through how the package works internally. We'll first look at the old approach using reflection, and then the current solution that uses closure binding.

The first version: reflection

In v1 of the package, we used PHP's Reflection API to access private members. Here's what the Invader class looked like:

class Invader
{
    public object $obj;
    public ReflectionClass $reflected;

    public function __construct(object $obj)
    {
        $this->obj = $obj;
        $this->reflected = new ReflectionClass($obj);
    }

    public function __get(string $name): mixed
    {
        $property = $this->reflected->getProperty($name);
        $property->setAccessible(true);

        return $property->getValue($this->obj);
    }
}

When you create an Invader, it wraps your object and creates a ReflectionClass for it. When you try to access a property like invade($myClass)->privateProperty, PHP triggers the __get magic method. It uses the reflection instance to find the property by name, calls setAccessible(true) on it, and then reads the value from the original object. The setAccessible(true) call tells PHP to skip the visibility check for that reflected property. Without it, trying to read a private property through reflection would throw an error, just like accessing it directly.

This worked fine, but it required creating a ReflectionClass instance and calling setAccessible(true) on every property or method you wanted to access. In v2, we replaced all of this with a much simpler approach using closures. To understand how, we first need to look at a lesser-known PHP visibility rule.

Private visibility is scoped to the class

In PHP, private visibility is scoped to the class, not to a specific object instance. Any code running inside a class can access the private properties and methods of any instance of that class.

Here's a concrete example:

class Wallet
{
    public function __construct(
        private int $balance
    ) {
    }

    public function hasMoreThan(Wallet $other): bool
    {
        // This works: we can read $other's private $balance
        // because we're inside the Wallet class scope
        return $this->balance > $other->balance;
    }
}

$mine = new Wallet(100);
$yours = new Wallet(50);

// returns true
$mine->hasMoreThan($yours);

Notice how hasMoreThan reads $other->balance directly, even though $balance is private. This compiles and runs without errors because the code is running inside the Wallet class. PHP doesn't care which instance the property belongs to. As long as you're in the right class scope, all private members of all instances of that class are accessible.

This is the foundation that makes v2 of the invade package work. If you can get your code to run inside the scope of the target class, you get access to its private members. PHP closures give us a way to do exactly that.

How closures can change their scope

PHP closures carry the scope of the class they were defined in. But the Closure::call() method lets you change that. It temporarily rebinds $this inside the closure to a different object, and it also changes the scope to the class of that object.

$readBalance = fn () => $this->balance;

$wallet = new Wallet(100);
// returns 100
$readBalance->call($wallet);

Even though $balance is private, this works. The ->call($wallet) method binds the closure to the $wallet object and puts it in the Wallet class scope. When PHP evaluates $this->balance, it sees that the code is running in the scope of Wallet, so it allows the access.

This is the entire trick that invade v2 is built on. Now let's look at the actual code.

The current Invader class

When you call invade($object), it returns an Invader instance that wraps your object. The current version of the Invader class is surprisingly small:

class Invader
{
    public function __construct(
        public object $obj
    ) {
    }

    public function __get(string $name): mixed
    {
        return (fn () => $this->{$name})->call($this->obj);
    }

    public function __set(string $name, mixed $value): void
    {
        (fn () => $this->{$name} = $value)->call($this->obj);
    }

    public function __call(string $name, array $params = []): mixed
    {
        return (fn () => $this->{$name}(...$params))->call($this->obj);
    }
}

That's the entire class. No reflection, no complex tricks. Just PHP magic methods and closures.

When you write invade($myClass)->privateProperty, the invade function creates a new Invader instance. PHP can't find privateProperty on the Invader class, so it triggers __get('privateProperty'). The __get method creates a short closure fn () => $this->{$name} and calls it with ->call($this->obj). As we just learned, this binds $this inside the closure to your original object and puts the closure in that object's class scope. PHP then evaluates $this->privateProperty inside the scope of MyClass, and the private access is allowed.

The __set method uses the same pattern, but assigns a value instead of reading one:

(fn () => $this->{$name} = $value)->call($this->obj);

The $value variable is captured from the enclosing scope of the __set method, so it's available inside the closure.

For calling private methods, __call follows the same approach:

return (fn () => $this->{$name}(...$params))->call($this->obj);

The closure calls the method by name, spreading the parameters. Since ->call() binds the closure to the target object, PHP sees this as a call from within the class itself, and the private method becomes accessible.

In closing

The invade package is a fun example of how PHP closures and scope binding can bypass visibility restrictions in a clean way. It's a small trick, but understanding why it works teaches you something interesting about how PHP handles class scope and closure binding.

The original idea for the invade function came from Caleb Porzio, who first introduced it as a helper in Livewire to replace a more verbose ObjectPrybar class. We liked the concept so much that we turned it into its own package.

Just remember: use it sparingly. It works great in tests or when you're building a package that needs deep integration with objects you don't control. In your regular project code, you probably don't need invade.

You can find the package on GitHub. This is one of the many packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.

We originally created this package after DigitalOcean lost one of our servers. That experience taught us the hard way that you should never rely solely on your hosting provider for backups. The package has been actively maintained ever since.

Taking backups

With the package installed, taking a backup is as simple as running:

php artisan backup:run

This creates a zip of your configured files and databases and stores it on your configured disks. You can also back up just the database or just the files:

php artisan backup:run --only-db
php artisan backup:run --only-files

Or target a specific disk:

php artisan backup:run --only-to-disk=s3

In most setups you'll want to schedule this. In your routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('backup:run')->daily()->at('01:00');

Listing and monitoring backups

To see an overview of all your backups, run:

php artisan backup:list

This shows a table with the backup name, disk, date, and size for each backup.

The package also ships with a monitor that checks whether your backups are healthy. A backup is considered unhealthy when it's too old or when the total backup size exceeds a configured threshold.

php artisan backup:monitor

You'll typically schedule the monitor to run daily:

Schedule::command('backup:monitor')->daily()->at('03:00');

When the monitor detects a problem, it fires an event that triggers notifications. Out of the box the package supports mail, Slack, Discord, and (new in v10) a generic webhook channel.

Cleaning up old backups

Over time backups pile up. The package includes a cleanup command that removes old backups based on a configurable retention strategy:

php artisan backup:clean

The default strategy keeps all backups for a certain number of days, then keeps one daily backup, then one weekly backup, and so on. It will never delete the most recent backup. You'll want to schedule this alongside your backup command:

Schedule::command('backup:clean')->daily()->at('02:00');

What's new in v10

v10 is mostly about addressing long-standing community requests and cleaning up internals.

The biggest change is that all events now carry primitive data (string $diskName, string $backupName) instead of BackupDestination objects. This means events can now be used with queued listeners, which was previously impossible because those objects weren't serializable. If you have existing listeners, you'll need to update them to use $event->diskName instead of $event->backupDestination->diskName().

Events and notifications are now decoupled. Events always fire, even when --disable-notifications is used. This fixes an issue where BackupWasSuccessful never fired when notifications were disabled, which also broke encryption since it depends on the BackupZipWasCreated event.

There's a new continue_on_failure config option for multi-destination backups. When enabled, a failure on one destination won't abort the entire backup. It fires a failure event for that destination and continues with the rest.

Other additions include a verify_backup config option that validates the zip archive after creation, a generic webhook notification channel for Mattermost/Teams/custom integrations, new command options (--filename-suffix, --exclude, --destination-path), and improved health checks that now report all failures instead of stopping at the first one.

On the internals side, the ConsoleOutput singleton has been replaced by a backupLogger() helper, encryption config now uses a proper enum, and storage/framework is excluded from backups by default.

The full list of breaking changes and migration instructions can be found in the upgrade guide.

In closing

You can find the complete documentation at spatie.be/docs/laravel-backup and the source code on GitHub.

This is one of the many packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.

Let me walk you through what the package can do and what's new in v8.

Generating a sitemap by crawling

The simplest way to use the package is to point it at your site and let it crawl every page.

use Spatie\Sitemap\SitemapGenerator;

SitemapGenerator::create('https://example.com')->writeToFile($path);

That's it. The generator will follow all internal links and produce a complete sitemap.xml. You can filter which URLs end up in the sitemap using the shouldCrawl callback.

SitemapGenerator::create('https://example.com')
    ->shouldCrawl(function (string $url) {
        return ! str_contains(parse_url($url, PHP_URL_PATH) ?? '', '/admin');
    })
    ->writeToFile($path);

Creating a sitemap manually

If you'd rather have full control, you can build the sitemap yourself.

use Carbon\Carbon;
use Spatie\Sitemap\Sitemap;
use Spatie\Sitemap\Tags\Url;

Sitemap::create()
    ->add(Url::create('/home')
        ->setLastModificationDate(Carbon::yesterday())
        ->setChangeFrequency(Url::CHANGE_FREQUENCY_YEARLY)
        ->setPriority(0.1))
    ->add(Url::create('/contact'))
    ->writeToFile($path);

You can also combine both approaches: let the crawler do the heavy lifting, then add extra URLs on top.

SitemapGenerator::create('https://example.com')
    ->getSitemap()
    ->add(Url::create('/extra-page'))
    ->writeToFile($path);

Adding models directly

If your models implement the Sitemapable interface, you can add them to the sitemap directly.

use Spatie\Sitemap\Contracts\Sitemapable;
use Spatie\Sitemap\Tags\Url;

class Post extends Model implements Sitemapable
{
    public function toSitemapTag(): Url | string | array
    {
        return route('blog.post.show', $this);
    }
}

Now you can pass a single model or an entire collection.

Sitemap::create()
    ->add($post)
    ->add(Post::all())
    ->writeToFile($path);

Automatic sitemap splitting

Large sites can easily exceed the 50,000 URL limit that the sitemap protocol allows per file. New in v8, you can call maxTagsPerSitemap() on your sitemap, and the package will automatically split it into multiple files with a sitemap index.

Sitemap::create()
    ->maxTagsPerSitemap(10000)
    ->add($allUrls)
    ->writeToFile(public_path('sitemap.xml'));

If your sitemap contains more than 10,000 URLs, this will write sitemap_1.xml, sitemap_2.xml, etc., and a sitemap.xml index file that references them all. If your sitemap stays under the limit, it just writes a single file as usual.

XSL stylesheet support

Sitemaps are XML files, and they look pretty rough when opened in a browser. Also new in v8, you can attach an XSL stylesheet to make them human-readable.

Sitemap::create()
    ->setStylesheet('/sitemap.xsl')
    ->add(Post::all())
    ->writeToFile(public_path('sitemap.xml'));

This works on both Sitemap and SitemapIndex. When combined with maxTagsPerSitemap(), the stylesheet is automatically applied to all split files and the index.

In closing

Under the hood, we've upgraded the package to use spatie/crawler v9.

You'll find the complete documentation on our docs site. The package is available on GitHub.

This is one of the many packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.

Throughout the years, the API had accumulated some rough edges. With v9, we cleaned all of that up and added a bunch of features we've wanted for a long time.

Let me walk you through all of it!

Using the crawler

The simplest way to crawl a site is to pass a URL to Crawler::create() and attach a callback via onCrawled():

use Spatie\Crawler\Crawler;
use Spatie\Crawler\CrawlResponse;

Crawler::create('https://example.com')
    ->onCrawled(function (string $url, CrawlResponse $response) {
        echo "{$url}: {$response->status()}\n";
    })
    ->start();

The callable gets a CrawlResponse object. It has these methods

$response->status();        // int
$response->body();          // string
$response->header('some-header');  // ?string
$response->dom();           // Symfony DomCrawler instance
$response->isSuccessful();  // bool
$response->isRedirect();    // bool
$response->foundOnUrl();    // ?string
$response->linkText();      // ?string
$response->depth();         // int

The body is cached, so calling body() multiple times won't re-read the stream. And if you still need the raw PSR-7 response for some reason, toPsrResponse() has you covered.

You can control how many URLs are fetched at the same time with concurrency(), and set a hard cap with limit():

Crawler::create('https://example.com')
    ->concurrency(5)
    ->limit(200) // will stop after crawling this amount of pages
    ->onCrawled(function (string $url, CrawlResponse $response) {
        // ...
    })
    ->start();

There are a couple of other on closure callbacks you can use:

Crawler::create('https://example.com')
    ->onCrawled(function (string $url, CrawlResponse $response, CrawlProgress $progress) {
        echo "[{$progress->urlsProcessed}/{$progress->urlsFound}] {$url}\n";
    })
    ->onFailed(function (string $url, RequestException $e, CrawlProgress $progress) {
        echo "Failed: {$url}\n";
    })
    ->onFinished(function (FinishReason $reason, CrawlProgress $progress) {
        echo "Done: {$reason->name}\n";
    })
    ->start();

Every on callback now receives a CrawlProgress object that tells you exactly where you are in the crawl:

$progress->urlsProcessed;  // how many URLs have been crawled
$progress->urlsFailed;     // how many failed
$progress->urlsFound;      // total discovered so far
$progress->urlsPending;    // still in the queue

The start() method now returns a FinishReason enum, so you know exactly why the crawler stopped:

$reason = Crawler::create('https://example.com')
    ->limit(100)
    ->start();

// $reason is one of: Completed, CrawlLimitReached, TimeLimitReached, Interrupted

Each CrawlResponse also carries a TransferStatistics object with detailed timing data for the request:

Crawler::create('https://example.com')
    ->onCrawled(function (string $url, CrawlResponse $response) {
        $stats = $response->transferStats();

        echo "{$url}\n";
        echo "  Transfer time: {$stats->transferTimeInMs()}ms\n";
        echo "  DNS lookup: {$stats->dnsLookupTimeInMs()}ms\n";
        echo "  TLS handshake: {$stats->tlsHandshakeTimeInMs()}ms\n";
        echo "  Time to first byte: {$stats->timeToFirstByteInMs()}ms\n";
        echo "  Download speed: {$stats->downloadSpeedInBytesPerSecond()} B/s\n";
    })
    ->start();

All timing methods return values in milliseconds. They return null when the stat is unavailable, for example tlsHandshakeTimeInMs() will be null for plain HTTP requests.

Throttling the crawl

I wanted the crawler to a well behaved piece of software. Using the crawler at full speed and with large concurrency could overload some servers. That's why throttling is a polished feature of the package.

We ship two throttling strategies. The first one is FixedDelayThrottle that can give a fixed delay between all requests.

// 200ms between requests
$crawler->throttle(new FixedDelayThrottle(200)); 

AdaptiveThrottle is a strategy that adjusts the delay based on how fast the server responds. If the server responds fast, the minimum delay will be low. If the server responds slow, we'll automatically slow down crawling.

$crawler->throttle(new AdaptiveThrottle(
    minDelayMs: 50,
    maxDelayMs: 5000,
));

Testing with fake()

Like Laravel's HTTP client, the crawler now has a fake to define which response should be returned for a request without making the actually request.

Crawler::create('https://example.com')
    ->fake([
        'https://example.com' => '<html><a href="/about">About</a></html>',
        'https://example.com/about' => '<html>About page</html>',
    ])
    ->onCrawled(function (string $url, CrawlResponse $response) {
        // your assertions here
    })
    ->start();

Using this faking helps to keep your tests executing fast.

Driver-based JavaScript rendering

Like in our Laravel PDF, Laravel Screenshot, and Laravel OG Image packages, Browsershot is no longer a hard dependency. JavaScript rendering is now driver-based, so you can use Browsershot, a new Cloudflare renderer, or write your own:

$crawler->executeJavaScript(new CloudflareRenderer($endpoint));

In closing

I'm usually very humble, but think that in this case I can say that our crawler package is the best available crawler in the entire PHP ecosystem.

You can find the package on GitHub. The full documentation is available on our documentation site.

This is one of the many packages we've created at Spatie. If you want to support our open source work, consider picking up one of our paid products.