DEV Community: Hafiz

Building an Audit Log in Laravel with spatie/laravel-activitylog v5

Hafiz — Mon, 11 May 2026 05:29:50 +0000

Every SaaS reaches a point where "who changed that?" stops being a casual question and starts being a support ticket. A team member deletes a project. A setting gets changed and nobody knows when. A user loses access and blames an admin. Without an audit log, you're guessing. And in enterprise deals, the absence of audit logging can be an actual blocker.

spatie/laravel-activitylog has been the go-to solution for this in the Laravel ecosystem for years, with over 48 million Packagist installs. Version 5 shipped in late March 2026, and it's a meaningful upgrade: PHP 8.4+, a cleaner API, a new database schema, and properly swappable internals. This post walks through building a complete audit log system for a Laravel SaaS using v5, from installation to displaying the log in Filament.

If you're already on v4, there's a migration section at the end covering the breaking changes.

What Changed in v5

Freek covered the full list on his blog, but the things that matter most for day-to-day use:

No boilerplate for basic model logging. In v4, adding the LogsActivity trait to a model also required a getActivitylogOptions() method even for the simplest cases. In v5, the trait alone is enough to start logging. You only override getActivitylogOptions() when you need custom behaviour.

New attribute_changes column. The old changes column is replaced by attribute_changes, which stores a cleaner structure with attributes (the new values) and old (the previous values). This means a small schema migration if you're upgrading, but fresh installs get a better foundation.

ActivityEvent enum for type-safe filtering. v5 introduces an ActivityEvent enum so you're not relying on raw strings when filtering by event type:

use Spatie\Activitylog\Enums\ActivityEvent;

Activity::forEvent(ActivityEvent::Created)->get();
Activity::forEvent(ActivityEvent::Updated)->get();
Activity::forEvent(ActivityEvent::Deleted)->get();

Plain strings still work for custom event names. But for the standard events, the enum gives you autocompletion and catches typos at the IDE level rather than at runtime.

Customizable action classes. The core operations (saving activities, cleaning old records) are now action classes you can extend and swap via config. This makes it practical to do things like queue activity saves during a request, or redact sensitive fields before anything hits the database.

Installation

Requires PHP 8.4+ and Laravel 12 or 13. Install the package:

composer require spatie/laravel-activitylog

Publish and run the migrations:

php artisan vendor:publish --provider="Spatie\Activitylog\ActivitylogServiceProvider" --tag="activitylog-migrations"
php artisan migrate

This creates the activity_log table with the new v5 schema. You can find the full list of available artisan commands in the Laravel Artisan Commands reference.

Optionally publish the config file:

php artisan vendor:publish --provider="Spatie\Activitylog\ActivitylogServiceProvider" --tag="activitylog-config"

The config file at config/activitylog.php controls the activity model class, the default log name, the number of days before old records get pruned, and the action classes used internally.

Manual Activity Logging

The simplest usage is logging arbitrary events:

activity()->log('User exported the reports CSV');

More useful is attaching context. You want to know what was affected and who did it:

activity()
    ->performedOn($project)
    ->causedBy($user)
    ->withProperties(['plan' => 'pro', 'via' => 'settings-page'])
    ->log('upgraded plan');

Retrieving logged activities uses the Activity model with a set of built-in query scopes:

use Spatie\Activitylog\Models\Activity;

// All activity for a specific subject
Activity::forSubject($project)->get();

// All activity caused by a user
Activity::causedBy($user)->get();

// Filter by event type
Activity::forEvent('updated')->get();

// Filter by log name (useful when grouping logs by domain)
Activity::inLog('billing')->get();

// Combine scopes
Activity::forSubject($project)
    ->causedBy($user)
    ->latest()
    ->get();

Each Activity record gives you description, subject, causer, event, properties, and attribute_changes. The getProperty() helper reads from the custom properties you attached.

Automatic Model Event Logging

This is where the package earns its place. Add the LogsActivity trait to any Eloquent model and it automatically logs created, updated, and deleted events:

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

class Project extends Model
{
    use LogsActivity;
}

That's all you need for basic logging. Any create, update, or delete on this model now creates an activity record.

To control which attributes get tracked, override getActivitylogOptions():

use Spatie\Activitylog\Support\LogOptions;

class Project extends Model
{
    use LogsActivity;

    protected $fillable = ['name', 'description', 'status', 'owner_id'];

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

logOnly() limits tracking to specific attributes. logOnlyDirty() means only attributes that actually changed get recorded, not everything including updated_at noise. dontSubmitEmptyLogs() skips saving a record when nothing meaningful changed.

When a project gets updated, the activity record's attribute_changes looks like this:

$activity->attribute_changes;
// [
//     'attributes' => [
//         'status' => 'active',
//         'owner_id' => 42,
//     ],
//     'old' => [
//         'status' => 'draft',
//         'owner_id' => 7,
//     ],
// ]

You can also use logAll() combined with logExcept() to track everything except specific fields:

return LogOptions::defaults()
    ->logAll()
    ->logExcept(['remember_token', 'updated_at']);

And logFillable() to automatically track whatever is in the $fillable array, useful when your fillable list is the authoritative record of what users can change:

return LogOptions::defaults()
    ->logFillable()
    ->logOnlyDirty();

In a typical SaaS you'd apply this to several models at once. A project management app might log changes to Project, Team, Invitation, and Role models, each tracking different attributes:

class Team extends Model
{
    use LogsActivity;

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
            ->logOnly(['name', 'owner_id', 'plan'])
            ->logOnlyDirty()
            ->setDescriptionForEvent(fn(string $event) => "Team was {$event}")
            ->dontSubmitEmptyLogs();
    }
}

class Invitation extends Model
{
    use LogsActivity;

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
            ->logOnly(['email', 'role', 'accepted_at'])
            ->logOnlyDirty()
            ->useLogName('invitations');
    }
}

The setDescriptionForEvent() method lets you control the human-readable description that gets stored. The default is just the event name ("updated", "created"), but a more descriptive string is easier to read in an admin panel.

Grouping Activity with Named Logs

By default everything lands in the default log. For a SaaS with distinct domains (billing, security, content), separating into named logs keeps queries focused and makes it practical to surface the right activity in the right UI context.

Set a log name on the model:

class SubscriptionChange extends Model
{
    use LogsActivity;

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
            ->useLogName('billing')
            ->logOnly(['plan', 'status', 'cancelled_at']);
    }
}

Or set it on a manual log call:

activity('security')
    ->causedBy($user)
    ->withProperties(['ip' => request()->ip()])
    ->log('Two-factor authentication disabled');

Then query each log independently:

// Billing events only
Activity::inLog('billing')->latest()->get();

// Security events for a specific user
Activity::inLog('security')
    ->causedBy($user)
    ->latest()
    ->get();

In Filament, add a filter that lets admins switch between log channels:

Tables\Filters\SelectFilter::make('log_name')
    ->label('Log')
    ->options([
        'default'  => 'General',
        'billing'  => 'Billing',
        'security' => 'Security',
    ]),

This pattern avoids the query performance issues that come from filtering a single massive activity_log table by subject type. Named logs give you logical partitioning without needing separate database tables.

Enriching Logs Before They Save

Sometimes you need to attach extra context right before an activity is persisted. The beforeActivityLogged() method on your model runs at that moment:

class Project extends Model
{
    use LogsActivity;

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

This is the right place to add request context, session data, or anything that isn't on the model itself. Don't use model observers for this. The beforeActivityLogged hook runs in the correct position in the activity lifecycle.

Redacting Sensitive Fields

By default, if you log a User model, attribute changes will include whatever fields you track. If that includes anything sensitive, you want to strip it before it hits the database.

Create a custom action class:

namespace App\ActivityLog;

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',
            'attributes.two_factor_secret',
            'old.two_factor_secret',
        ]);

        $activity->attribute_changes = $changes;
    }
}

'actions' => [
    'log_activity' => \App\ActivityLog\RedactSensitiveFieldsAction::class,
],

Now password changes never appear in your logs, regardless of which model triggers them. You can also override save() on the action class to dispatch a queued job instead of writing synchronously, which helps if you're concerned about activity logging adding latency during high-traffic requests. The queue jobs guide covers the patterns that apply here.

Displaying the Activity Log in Filament

An audit log is only useful if someone can actually read it. If you're using Filament, the quickest way is a dedicated resource. If you're building a SaaS admin panel, the Filament admin guide covers the broader setup.

Generate the resource:

php artisan make:filament-resource ActivityLog --view

Then configure the list table in ActivityLogResource.php:

use Spatie\Activitylog\Models\Activity;

public static function getModel(): string
{
    return Activity::class;
}

public static function table(Table $table): Table
{
    return $table
        ->columns([
            Tables\Columns\TextColumn::make('causer.name')
                ->label('User')
                ->searchable()
                ->sortable(),

            Tables\Columns\TextColumn::make('description')
                ->label('Action')
                ->searchable(),

            Tables\Columns\TextColumn::make('subject_type')
                ->label('Subject')
                ->formatStateUsing(fn ($state) => class_basename($state))
                ->sortable(),

            Tables\Columns\TextColumn::make('event')
                ->badge()
                ->color(fn (string $state): string => match ($state) {
                    'created' => 'success',
                    'updated' => 'warning',
                    'deleted' => 'danger',
                    default   => 'gray',
                }),

            Tables\Columns\TextColumn::make('created_at')
                ->label('When')
                ->dateTime()
                ->sortable(),
        ])
        ->defaultSort('created_at', 'desc')
        ->filters([
            Tables\Filters\SelectFilter::make('event')
                ->options([
                    'created' => 'Created',
                    'updated' => 'Updated',
                    'deleted' => 'Deleted',
                ]),
        ])
        ->actions([
            Tables\Actions\ViewAction::make(),
        ]);
}

For the view page, show the attribute_changes as a formatted diff so admins can see exactly what changed:

public static function infolist(Infolist $infolist): Infolist
{
    return $infolist
        ->schema([
            Infolists\Components\TextEntry::make('causer.name')->label('User'),
            Infolists\Components\TextEntry::make('description')->label('Action'),
            Infolists\Components\TextEntry::make('created_at')->label('When')->dateTime(),
            Infolists\Components\KeyValueEntry::make('attribute_changes.attributes')
                ->label('New values'),
            Infolists\Components\KeyValueEntry::make('attribute_changes.old')
                ->label('Previous values'),
        ]);
}

This gives admins a readable before/after comparison for any update event. For larger teams, you'd add subject-specific filters and restrict access to senior roles via Filament's policy integration, which is covered in the full SaaS guide.

Cleaning Up Old Records

Activity logs grow fast. The package ships a built-in command that removes records older than the number of days set in config:

php artisan activitylog:clean

Set the retention period in config/activitylog.php:

'delete_records_older_than_days' => 90,

Schedule it in routes/console.php:

Schedule::command('activitylog:clean')->daily();

90 days is a reasonable default for most SaaS products. If you're in a regulated industry (healthcare, finance), you'll want to check your compliance requirements. Some industries mandate 12+ months of audit history.

Migrating from v4

If you're upgrading an existing project, the breaking changes require attention. These are the ones that will actually affect your code:

PHP and Laravel version requirements. v5 requires PHP 8.4+ and Laravel 12+. If you're on older versions, stay on v4 until you've upgraded.

New database column. v5 introduces an attribute_changes column that replaces the old changes column. Create a migration:

Schema::table('activity_log', function (Blueprint $table) {
    $table->json('attribute_changes')->nullable()->after('properties');
});

You'll need to decide what to do with existing changes data. For most teams, archiving the old column and letting new records use attribute_changes is simpler than trying to migrate the data format.

Relation renames. Two relations changed names:

// v4
$user->activity;         // relation to activities caused by this user
$model->activity;        // relation to activities on this model

// v5
$user->actions;          // renamed
$model->activities;      // renamed

Search your codebase for ->activity and update accordingly.

Accessing changes. The changes() method became a property:

// v4
$activity->changes();

// v5
$activity->changes; // or $activity->attribute_changes

Removed config options. table_name and database_connection were removed from the config file. If you need a custom table or connection, create a custom Activity model with $table and $connection properties, then point activity_model in config to that class.

Removed method: addLogChange(), LoggablePipe, and EventLogBag are gone. If you used these to manipulate the changes array, override transformChanges() on a custom LogActivityAction instead; the pattern is shown in the redacting section above.

Before upgrading, check your composer.json for any secondary packages that depend on spatie/laravel-activitylog. This is good practice any time you're doing major version bumps. The auditing your Composer dependencies post covers the workflow.

Testing Your Activity Log

The package ships with a withoutLogs() helper that's useful in tests where you don't want activity logging to interfere:


it('updates a project', function () {
    $project = Project::factory()->create();

    // Disable logging just for this test
    activity()->disableLogging();
    $project->update(['name' => 'Updated Name']);
    activity()->enableLogging();

    expect($project->fresh()->name)->toBe('Updated Name');
    expect(Activity::count())->toBe(0);
});

When you actually want to assert that activity was logged correctly, test it explicitly:

it('logs when a project status changes', function () {
    $user = User::factory()->create();
    $project = Project::factory()->create(['status' => 'draft']);

    actingAs($user);
    $project->update(['status' => 'active']);

    $activity = Activity::latest()->first();

    expect($activity->causer->id)->toBe($user->id)
        ->and($activity->event)->toBe('updated')
        ->and($activity->attribute_changes['attributes']['status'])->toBe('active')
        ->and($activity->attribute_changes['old']['status'])->toBe('draft');
});

Testing the beforeActivityLogged hook works the same way: update the model and assert the custom property was merged onto the activity record. The hook runs synchronously during the model save, so there's no async complexity to deal with in tests.

One thing worth knowing: if you dispatch activity logging via a queued job (using the custom action class pattern), use Queue::fake() in tests and assert the job was dispatched rather than asserting the activity was saved directly.

FAQ

Does v5 work with Laravel 12 and 13?

Yes. The package requires illuminate/support: ^12.0 || ^13.0, so both are supported. Laravel 11 and older are not supported in v5. Stay on v4 if you haven't upgraded yet.

Can I log activity without a logged-in user?

Yes. When there's no authenticated user, causer is null and the log still saves. This is useful for logging background jobs or system-triggered events. You can also set a causer explicitly with causedBy($model).

How do I log soft-deleted models?

The LogsActivity trait hooks into Eloquent model events including SoftDeleting. As long as your model uses SoftDeletes, the activity log records deleted events automatically. Restores are also captured.

Can I use multiple log channels?

Yes. Use useLogName() in getActivitylogOptions() to route activity to different named logs. Then query with Activity::inLog('billing') or Activity::inLog('security'). Useful when you want separate audit trails for different parts of your app.

How do I prevent logging during imports or seeders?

Call activity()->disableLogging() before the operation and activity()->enableLogging() after. This works in tests, seeders, and bulk import scripts anywhere you need a clean run without filling the activity log with noise.

Build It Once, Thank Yourself Later

Audit logs feel optional until the moment they aren't. A team member makes an unexpected change, a user disputes account history, a compliance requirement surfaces. By then it's too late to add the log retroactively.

The good news is that v5 makes the setup surprisingly lightweight. Add the trait, configure what to track, schedule the cleanup command. That's the core of it. Filament display, sensitive field redaction, and queued saves are all additions you can layer in as your needs grow.

If you're setting up activity logging on a production app and want a second set of eyes on the implementation, get in touch.

Laravel Now Has Native Passkeys: A Complete Guide to laravel/passkeys

Hafiz — Sat, 09 May 2026 07:24:25 +0000

For a long time, adding passkeys to a Laravel app meant reaching for a third-party package, assembling WebAuthn ceremonies by hand, or piecing together a tutorial that assumes you already know what a "relying party ID" is. That's done.

In late April 2026, Laravel shipped laravel/passkeys, a first-party package authored by Taylor Otwell that gives you a complete passkey story out of the box. Server package, npm client, Fortify integration. Three pieces that click together so passwordless auth is boring to wire up, which is exactly what you want from a security feature.

I covered the Spatie passkeys approach back in January, and that's still valid if you're Livewire-heavy or already have that package running. But the native package is the right call for new projects and anything using Fortify. Here's the full setup.

What Ships in laravel/passkeys

The passkey stack has three components that each handle a distinct concern.

laravel/passkeys is the server-side Composer package. It handles WebAuthn ceremonies, manages a passkeys database table, registers routes for login, confirmation, and credential management, and fires events you can hook into. If you need custom authorization logic or your own route definitions, escape hatches are built in.

@laravel/passkeys is the npm client. It handles browser-side ceremony coordination (registration and verification) and ships first-class helpers for React, Vue, and Svelte with SSR-safe hooks so client-only APIs don't fight your framework. The public API is two methods: Passkeys.register() and Passkeys.verify(). That's it.

Fortify integration wires everything together via Features::passkeys() in your app config and a passkeys section in config/fortify.php. Fortify apps get the same endpoints and the PasskeyUser and PasskeyAuthenticatable contracts without reimplementing any glue.

The package is v0.1.0 but that's not a red flag. It's already the default in Laravel's official starter kits and used by Fortify in production. The version number signals that the public API may still evolve, not that the package is unstable.

Installation

Start by pulling in the Composer package:

composer require laravel/passkeys

Publish and run the migrations to create the passkeys table:

php artisan vendor:publish --tag=passkeys-migrations
php artisan migrate

Next, add a secret to your .env for deriving stable opaque user handles. This keeps passkey associations private even if your user IDs are sequential integers:

PASSKEYS_USER_HANDLE_SECRET=your-random-secret-here

Generate a value with:

php artisan key:generate --show

Use that output as your secret. The package falls back to APP_KEY if you leave this blank, but keeping them separate is better practice. If you ever rotate your app key, users won't lose their passkeys. You can find a full reference of available artisan commands in the Laravel Artisan Commands reference.

Configuring Your User Model

Add the PasskeyUser contract and PasskeyAuthenticatable trait to your User model:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Passkeys\Contracts\PasskeyUser;
use Laravel\Passkeys\PasskeyAuthenticatable;

class User extends Authenticatable implements PasskeyUser
{
    use PasskeyAuthenticatable;

    // Rest of your model...
}

The trait assumes your users table has name and email columns. Authenticators show these values in their UI during registration and account selection. displayName falls back from name to email to the auth identifier. Same for username.

If you need different display values, override the methods directly on the model:

public function getPasskeyDisplayName(): string
{
    return $this->full_name ?? $this->email;
}

public function getPasskeyUsername(): string
{
    return $this->email;
}

That's the only change your model needs. No extra migrations, no pivot tables. The passkeys table handles credential storage and links to your user via a standard relationship that PasskeyAuthenticatable sets up for you.

Fortify Integration

If you're using Laravel Fortify, enabling passkeys takes one line in your features array:

use Laravel\Fortify\Features;

'features' => [
    Features::registration(),
    Features::resetPasswords(),
    Features::emailVerification(),
    Features::passkeys(), // Add this
],

Fortify automatically registers the passkey routes and wires up the contracts. Nothing else changes on the server side. Your existing authorization setup with policies and gates stays untouched: passkeys only replace the authentication step, not what happens after it.

The Config File

Publish the config if you need to customize anything:

php artisan vendor:publish --tag="passkeys-config"

The defaults in config/passkeys.php are sensible:

return [
    'relying_party_id' => parse_url(config('app.url'), PHP_URL_HOST),
    'allowed_origins' => [config('app.url')],
    'user_handle_secret' => env('PASSKEYS_USER_HANDLE_SECRET', config('app.key')),
    'timeout' => 60000,
    'guard' => 'web',
    'middleware' => ['web'],
    'management_middleware' => ['password.confirm'],
    'throttle' => 'throttle:6,1',
    'redirect' => '/',
];

A few worth understanding before you change anything.

relying_party_id is your domain, derived from APP_URL. Passkeys are cryptographically bound to this value. If the domain the browser accesses doesn't match, the ceremony fails. Make sure APP_URL reflects the actual domain you're serving, especially in local development.

management_middleware defaults to password.confirm, which means users must re-confirm their password before adding or revoking passkeys. Don't disable this. It's the right friction for a security-critical action. The same principle applies here as with sensitive token operations in Passport vs Sanctum.

throttle limits passkey attempts to 6 per minute. Sensible for production. Adjust it if you have unusual traffic patterns, but don't remove it entirely.

Routes the Package Registers

You don't define any routes yourself. The server package registers these automatically:

POST   /passkeys/register/options   (generate registration challenge)
POST   /passkeys/register           (store the new credential)
POST   /passkeys/verify/options     (generate authentication challenge)
POST   /passkeys/verify             (authenticate with passkey)
DELETE /passkeys/{passkey}          (revoke a specific passkey)

If you need custom route definitions (different middleware, prefixes, or custom controllers), you can disable auto-registration in the config and define them yourself. The underlying action classes are all public and importable, so you're not losing functionality by taking manual control.

How the WebAuthn Flow Works

It helps to see the ceremony before writing the frontend code:

Registration follows the same pattern: browser requests options, authenticator creates a key pair, public key gets stored on your server. Nothing sensitive ever leaves the device. The private key never travels over the network, which is the core security advantage over passwords. No credentials to steal from a database breach.

Frontend Integration (Vue)

Install the npm client:

npm install @laravel/passkeys
npm run build

Here's a Vue 3 component that handles both registration (authenticated users adding a passkey) and login (on the login page):

<script setup>
import { ref } from 'vue'
import { Passkeys } from '@laravel/passkeys'

const registering = ref(false)
const verifying = ref(false)
const error = ref(null)

async function registerPasskey() {
    registering.value = true
    error.value = null

    try {
        await Passkeys.register({ name: 'My Device' })
        // Passkey saved, refresh the list or show a success toast
    } catch (e) {
        error.value = e.message
    } finally {
        registering.value = false
    }
}

async function loginWithPasskey() {
    verifying.value = true
    error.value = null

    try {
        await Passkeys.verify()
        // Redirects automatically on success
    } catch (e) {
        error.value = e.message
    } finally {
        verifying.value = false
    }
}
</script>

<template>
    <div class="space-y-4">
        <!-- Show on profile/settings for authenticated users -->
        <button @click="registerPasskey" :disabled="registering" class="btn">
            {{ registering ? 'Registering...' : 'Add a Passkey' }}
        </button>

        <!-- Show on your login page -->
        <button @click="loginWithPasskey" :disabled="verifying" class="btn">
            {{ verifying ? 'Verifying...' : 'Sign in with Passkey' }}
        </button>

        <p v-if="error" class="text-red-500 text-sm">{{ error }}</p>
    </div>
</template>

Passkeys.register() handles the full browser ceremony: it fetches the challenge from /passkeys/register/options, prompts the authenticator, and POSTs the resulting credential back to the server. Passkeys.verify() does the same for login and then redirects to the path defined in config/passkeys.php → redirect on success.

For React, the import and API are identical. The Svelte helpers follow the same pattern. The package abstracts all the @simplewebauthn/browser ceremony complexity behind a clean two-method interface, which is what you want when you're not trying to become a WebAuthn expert.

Managing Registered Passkeys

Users should be able to see and revoke their passkeys. This matters more than people expect. Users register on their laptop, their phone, and their work machine, then wonder why three entries show up. Give them the tools to clean it up.

A basic controller looks like this:

// PasskeyController.php
use Illuminate\Http\Request;
use Laravel\Passkeys\Models\Passkey;

class PasskeyController extends Controller
{
    public function index(Request $request)
    {
        $passkeys = $request->user()->passkeys()->latest()->get();

        return view('passkeys.index', compact('passkeys'));
    }

    public function destroy(Request $request, Passkey $passkey)
    {
        $this->authorize('delete', $passkey);

        $passkey->delete();

        return back()->with('status', 'Passkey removed.');
    }
}

The passkeys() relationship is defined by the PasskeyAuthenticatable trait. Each Passkey record has a name, created_at, and last_used_at column. Surface all three in the UI so users can tell which device is which and spot ones they don't recognise.

Wire the delete action to the DELETE /passkeys/{passkey} route the package already registered. The management_middleware (password confirm by default) protects both the management view and the delete action, so users need to re-authenticate before making changes.

Comparing to spatie/laravel-passkeys

Both packages use web-auth/webauthn-lib under the hood and get you to the same outcome. The difference is approach.

laravel/passkeys (native) is first-party and stack-agnostic on the frontend. Right choice for new Laravel 11, 12, or 13 projects and anything using Fortify. If you're starting fresh, use this.

spatie/laravel-passkeys ships Livewire components out of the box. If your app is already Livewire-heavy and you have Spatie's package working, there's no reason to migrate. The earlier passkeys guide covers that setup in full.

Don't run both at the same time. They register overlapping routes and you'll get conflicts.

Things to Get Right Before You Ship

A few things that will save you a debugging session:

HTTPS is required. WebAuthn only works on secure origins. For local development, use valet secure (Valet or Herd) or configure SSL in Sail. If APP_URL uses http://, the browser refuses to run the ceremony entirely. No error message. Just silence.

Keep password auth as a fallback. Not every user is on a passkey-capable device. Passkeys should be additive. Don't remove your existing login form. Make it an option alongside the passkey button, not a replacement for it.

Account recovery needs thought. If a user loses access to all their registered devices, how do they get back in? The package doesn't solve this. Email-based recovery or admin-initiated password resets are the standard approaches. Build this flow before you go live.

Multiple passkeys per user are supported by default. Users register on multiple devices, and that's expected. Your management UI (a list with a revoke button per passkey) handles this. Show name, created_at, and last_used_at so users can make sense of what's there.

The management_middleware default is password.confirm. Users re-confirm their password before adding or revoking passkeys. Don't strip it out. It's the same security pattern you'd apply to any sensitive account action.

Local Development

One thing that trips people up: APP_URL in .env must match the domain you're actually accessing in the browser. A mismatch makes the relying party check fail, and the error can be cryptic.

APP_URL=https://myapp.test

If you're on Valet:

valet secure myapp

That's all you need. The package reads APP_URL for its relying party config automatically.

FAQ

Does this work on Laravel 11 and 12, or only 13?

The package requires illuminate/contracts: ^11.0|^12.0|^13.0, so all three versions are supported. You don't need to upgrade to Laravel 13 to use it.

Do I need Fortify to use this?

No. Fortify integration is optional. The server package works standalone: you define your own routes and handle redirects. Features::passkeys() just automates the setup if Fortify is already in your stack.

What if I'm already using spatie/laravel-passkeys?

Stay on Spatie unless you have a specific reason to switch, especially if the Livewire setup is working. If you do migrate, uninstall the Spatie package and remove its service provider first. Don't run both simultaneously.

Is v0.1.0 stable enough for production?

The package is already the default in Laravel's official starter kits and backed by Fortify. The v0.1.0 label means the public API may evolve, not that it's experimental. For new projects, use it without hesitation.

Can I use this without a JavaScript framework?

Yes. The framework-specific helpers (Vue, React, Svelte) are convenience wrappers around the same core API. If you're using Blade without a frontend framework, you can call Passkeys.register() and Passkeys.verify() from a plain <script> block after importing @laravel/passkeys.

Get It Wired Up

Native passkeys is a small, focused addition to any Laravel project. The config is sensible by default, Fortify integration is a single line, and the frontend API is two method calls. If you're starting a new Laravel project today and want passwordless auth, this is the path.

If you're adding passkeys to an existing production app or migrating a complex auth setup, get in touch and we can work through the integration together.

PHP 8.4 Features You're Probably Not Using Yet in Your Laravel App

Hafiz — Fri, 08 May 2026 05:21:57 +0000

If you followed the Laravel 13 upgrade path, you're running PHP 8.4 by now (or you should be, since Laravel 13.3+ pulls in Symfony 8 components that require it). The upgrade guide covers the migration steps, but upgrading your runtime and actually using the new language features are two different things.

Most Laravel developers upgrade PHP, confirm their tests pass, and keep writing the same PHP 8.1-style code they've always written. That works, but you're leaving real improvements on the table. PHP 8.4 shipped six features that directly clean up the kind of code you write in a Laravel app every day.

Here's what each one does, with before and after examples.

1. Property Hooks: Replace Your Getters and Setters

Property hooks let you define get and set behavior directly on a class property. No more writing separate getter and setter methods for simple transformations.

Before (PHP 8.3):

class PriceCalculator
{
    private float $priceInCents;

    public function getPriceInCents(): float
    {
        return $this->priceInCents;
    }

    public function setPriceInCents(float $value): void
    {
        if ($value < 0) {
            throw new \InvalidArgumentException('Price cannot be negative.');
        }
        $this->priceInCents = $value;
    }

    public function getPriceInDollars(): float
    {
        return $this->priceInCents / 100;
    }
}

After (PHP 8.4):

class PriceCalculator
{
    public float $priceInCents {
        set {
            if ($value < 0) {
                throw new \InvalidArgumentException('Price cannot be negative.');
            }
            $this->priceInCents = $value;
        }
    }

    public float $priceInDollars {
        get => $this->priceInCents / 100;
    }
}

The $priceInDollars property is virtual. It doesn't store anything. It computes the value on read from $priceInCents. And the set hook on $priceInCents validates the input without a separate method.

Where this shines in Laravel: service classes, value objects, and DTOs where you'd normally write getters with transformation logic. Note that Eloquent models have their own accessor/mutator system via Attribute::make(), so property hooks don't replace those directly. But for any non-Eloquent class in your app (and you should have plenty), property hooks remove a lot of boilerplate.

2. Asymmetric Visibility: Public Read, Private Write

Before PHP 8.4, if you wanted a property that anyone could read but only the class itself could modify, you had two options: make it private and add a getter, or make it readonly. Both had tradeoffs. readonly can only be set once, which doesn't work if the value changes over the object's lifetime.

Asymmetric visibility solves this cleanly:

Before (PHP 8.3):

class OrderStatus
{
    private string $status = 'pending';

    public function getStatus(): string
    {
        return $this->status;
    }

    public function markAsShipped(): void
    {
        $this->status = 'shipped';
    }
}

// Usage
$order->getStatus(); // 'pending'

After (PHP 8.4):

class OrderStatus
{
    public private(set) string $status = 'pending';

    public function markAsShipped(): void
    {
        $this->status = 'shipped';
    }
}

// Usage
$order->status; // 'pending' - direct access, no getter needed
$order->status = 'cancelled'; // Error: Cannot modify private(set) property

The public private(set) declaration means: anyone can read $status directly, but only the class itself can change it. No getter needed. No readonly restriction. The value can change internally through methods like markAsShipped(), but external code can't tamper with it.

This is ideal for data transfer objects in your Laravel app. API response DTOs (especially if you're following REST API best practices), configuration objects, form data objects. Anywhere you want external code to read properties directly without letting them modify the state.

You can also use public protected(set) to allow child classes to modify the property while keeping external write access restricted.

3. array_find(): Stop Filtering When You Only Need One

PHP has had array_filter() forever, but if you only need the first element that matches a condition, you've been writing this:

Before (PHP 8.3):

$users = [
    ['name' => 'Alice', 'role' => 'admin'],
    ['name' => 'Bob', 'role' => 'editor'],
    ['name' => 'Charlie', 'role' => 'admin'],
];

$firstAdmin = array_values(array_filter(
    $users,
    fn ($user) => $user['role'] === 'admin'
))[0] ?? null;

That's ugly. array_filter processes the entire array, array_values re-indexes it, and the [0] ?? null handles the empty case. Three operations for something that should be one line.

After (PHP 8.4):

$firstAdmin = array_find($users, fn ($user) => $user['role'] === 'admin');

array_find() returns the first matching element and stops iterating. No re-indexing, no null coalescing. If nothing matches, it returns null.

PHP 8.4 also adds three related functions:

array_find_key() returns the key of the first match instead of the value
array_any() returns true if at least one element matches (like Collection::contains() for arrays)
array_all() returns true if every element matches (like Collection::every() for arrays)

In Laravel, you'll mostly use these in places where you're working with raw arrays instead of collections: config processing, middleware logic, job payloads, or anywhere performance matters and you don't want to create a Collection instance just to call ->first().

4. The #[\Deprecated] Attribute

PHP has always had a way to deprecate built-in functions, but there was no native mechanism for marking your own functions, methods, or class constants as deprecated. You'd either put a @deprecated docblock comment (which only IDE-level tools read) or throw a manual trigger_error().

Before (PHP 8.3):

/**
 * @deprecated Use calculateTotal() instead
 */
function calculateSubtotal(array $items): float
{
    trigger_error('calculateSubtotal() is deprecated, use calculateTotal()', E_USER_DEPRECATED);
    return calculateTotal($items);
}

After (PHP 8.4):

#[\Deprecated(message: 'Use calculateTotal() instead', since: '2.0')]
function calculateSubtotal(array $items): float
{
    return calculateTotal($items);
}

The #[\Deprecated] attribute triggers a real E_USER_DEPRECATED notice when the function is called. IDEs like PhpStorm show it with a strikethrough. Static analysis tools like PHPStan and Larastan flag it automatically. And you get a since parameter to track when the deprecation started.

Where this helps in Laravel: if you maintain internal packages, APIs with versioned endpoints, or shared service classes across teams, this is a cleaner way to signal "stop using this" than a docblock that nobody reads.

5. Method Chaining on new Without Parentheses

A small quality-of-life improvement that removes an annoying syntax limitation:

Before (PHP 8.3):

$date = (new DateTime())->format('Y-m-d');
$response = (new JsonResponse($data))->setStatusCode(201);

Those extra parentheses around new ClassName() were required to chain a method call. They look awkward and trip up developers who forget them.

After (PHP 8.4):

$date = new DateTime()->format('Y-m-d');
$response = new JsonResponse($data)->setStatusCode(201);

No wrapping parentheses needed. You can also access properties directly: new Foo()->bar. This is a small change, but it cleans up code in places where you create and immediately use throwaway objects, which happens often in tests, seeders, and one-off scripts.

6. Multibyte String Functions: trim, ltrim, rtrim

PHP finally has multibyte-aware trim functions. If your app handles content in languages like Japanese, Chinese, Arabic, or Korean, you've probably been using workarounds with preg_replace to trim multibyte whitespace characters that trim() ignores.

Before (PHP 8.3):

// Standard trim doesn't handle multibyte whitespace like \u{3000} (ideographic space)
$cleaned = preg_replace('/^\s+|\s+$/u', '', $input);

After (PHP 8.4):

$cleaned = mb_trim($input);

PHP 8.4 adds mb_trim(), mb_ltrim(), and mb_rtrim(). If your Laravel app processes user input from a multilingual audience, these are a direct improvement. Use them in your form request prepareForValidation() methods or in custom Eloquent casts where you clean input before storage.

When to Start Using These

You don't need to refactor your entire codebase. The practical approach:

Use immediately in new code. When you write a new service class, DTO, or value object, use property hooks and asymmetric visibility instead of getters/setters. When you write a new array operation on raw data, reach for array_find() before array_filter().

Refactor gradually. When you touch an existing class for a feature or bug fix, modernize it if it takes less than five minutes. Don't create refactoring PRs that touch 50 files. That's risk for no product value.

Don't touch Eloquent models. Eloquent has its own accessor/mutator system that doesn't need property hooks. And asymmetric visibility conflicts with how Eloquent hydrates properties. Keep Eloquent models using Laravel's patterns.

FAQ

Do property hooks work with Eloquent models?

Not in the way you might expect. Eloquent uses dynamic property access via __get and __set, which doesn't interact cleanly with PHP property hooks. Stick with Eloquent's Attribute::make() for model accessors and mutators. Use property hooks in your service classes, DTOs, form data objects, and other non-Eloquent classes.

Can I use asymmetric visibility with constructor promotion?

Yes. public private(set) string $name works in constructor parameters:

public function __construct(
    public private(set) string $name,
    public protected(set) int $age,
) {}

This gives you a publicly readable, internally writable promoted property in one line.

Do I need to upgrade PHPStan or Larastan for PHP 8.4 features?

PHPStan 2.1+ fully supports property hooks, asymmetric visibility, and the #[\Deprecated] attribute. If you're running an older version, upgrade before adopting these features, otherwise your CI pipeline will flag false positives. Larastan follows PHPStan's version, so updating Larastan pulls in the PHP 8.4 support automatically. If you're also upgrading your testing setup to Pest 4, do both at the same time.

What's the minimum PHP 8.4 version I should run?

PHP 8.4.1 or later. The 8.4.0 release had a few edge-case bugs with property hooks in certain inheritance scenarios that were fixed in 8.4.1. If you're deploying to production, start with the latest 8.4.x patch.

What's Next

PHP 8.4 isn't a small release. Property hooks and asymmetric visibility change how you structure classes in a fundamental way. The new array functions remove patterns you've been copy-pasting for years. And the #[\Deprecated] attribute gives you a tool that PHP itself has had forever but never shared with userland code.

If you haven't upgraded yet, the 4 composer conflicts post walks you through the blockers you'll hit on the way to PHP 8.4 and Laravel 13. And if you're building something with Laravel and want help modernizing your codebase for PHP 8.4, get in touch.

The 4 Composer Conflicts That Block Most Laravel 13 Upgrades (And How to Find Yours)

Hafiz — Wed, 06 May 2026 05:12:23 +0000

Most Laravel apps don't fail upgrades because of breaking changes. They fail because composer update throws a wall of red text and the developer closes the terminal.

Laravel 13 shipped with "zero breaking changes" to application code. That's true. Your routes, controllers, and Eloquent models don't need touching. But your composer.json is a different story. Somewhere in your 30-50 dependencies, there's almost certainly a version constraint that won't resolve against laravel/framework:^13.0. And finding it manually means running composer why-not, reading cryptic output, fixing one conflict, discovering the next, and repeating until you either succeed or give up and decide to "upgrade later."

Four specific conflicts catch most developers. After looking at how these surface in real composer.json files, in GitHub issues, and in r/laravel threads, the same patterns keep showing up. Here's what each one looks like, why it happens, and how to fix it.

1. Your PHP Constraint Is Too Loose

This is the most common blocker and the easiest to miss. Your composer.json probably says something like this:

"require": {
    "php": "^8.1"
}

Laravel 13 requires PHP 8.3 as the minimum. That constraint above technically allows 8.1, 8.2, 8.3, and 8.4. Two things can go wrong here.

First, if your server actually runs PHP 8.2, Composer will refuse to install Laravel 13 regardless of what your composer.json says. The error looks like this:

Your requirements could not be resolved to an installable set of packages.

Problem 1
  - laravel/framework v13.0.0 requires php ^8.3 -> your php version (8.2.28)
    does not satisfy that requirement.

Second, even if your server runs 8.3, a loose constraint like ^8.1 means your app could be deployed on 8.1 or 8.2, where Laravel 13 won't work. Tightening the constraint protects you from that.

The fix: Run php -v on production first. If it returns anything below 8.3, upgrade PHP before touching Composer. Then tighten your constraint to match:

"require": {
    "php": "^8.3"
}

Don't skip this. Every other fix in this post is pointless if your PHP version is too low.

2. The Symfony 8 Surprise

This one is newer and won't hit you on day one. Laravel 13.0 through 13.2 work fine on PHP 8.3. But starting with Laravel 13.3, the framework allows Symfony 8 components (symfony/error-handler, symfony/console) that require PHP 8.4.

If you're on PHP 8.3 and you run composer update after the initial upgrade, you might get hit by this weeks later:

Problem 1
  - laravel/framework v13.3.0 requires symfony/error-handler ^7.4.0 || ^8.0.0
    -> satisfiable by symfony/error-handler[v8.0.8].
  - symfony/error-handler v8.0.8 requires php >=8.4
    -> your php version (8.3.30) does not satisfy that requirement.

The fix: You have two options. Either upgrade to PHP 8.4 (the better long-term choice), or pin Symfony to 7.4 in your composer.json:

composer require symfony/console:"^7.4" symfony/error-handler:"^7.4"

This keeps you on Symfony 7.4 while running Laravel 13.3+. It works, but it's a temporary workaround. PHP 8.4 is where you want to be.

If you're reading the full Laravel 13 upgrade guide, this particular conflict isn't covered there because it appeared after the initial release. It's exactly the kind of thing that catches you between "I upgraded successfully" and "why is production broken after composer update?"

3. Spatie Packages Pinned to Old Major Versions

If you use any Spatie packages (and most Laravel apps do), check their version constraints carefully. Older major versions often don't support Laravel 13. The most common offenders:

spatie/laravel-permission v5 doesn't support Laravel 13. You need at least v6.
spatie/laravel-medialibrary older major versions don't support Laravel 13. Check your installed version against the latest release.
spatie/laravel-activitylog requires at least v4.12 for Laravel 13 support. Earlier v4 releases won't resolve.

The error looks like a typical version mismatch:

Problem 1
  - spatie/laravel-permission v5.11.1 requires illuminate/database ^9.0|^10.0|^11.0|^12.0
    -> found illuminate/database v13.0.0 but it does not match ^9.0|^10.0|^11.0|^12.0.

The fix: Upgrade each Spatie package to the latest major version before upgrading Laravel. Check the GitHub releases page for each one. Most have migration guides. Spatie generally ships Laravel support within days of a new release, and they've even backported Laravel 13 compatibility to some older branches so third-party packages have time to catch up.

One tip: run composer outdated --major to see which packages have major version jumps available. That command shows you the gap without trying to resolve anything.

4. Testing Packages That Quietly Block Everything

PHPUnit and Pest are required by almost every Laravel app, but they sit in require-dev and tend to get ignored during upgrades. They shouldn't be.

Laravel 13 requires phpunit/phpunit:^11.5.50 or ^12.0. If your composer.json still has "phpunit/phpunit": "^10.0", that's a blocker. Same with Pest: you need at least Pest 3.8.5 for Laravel 13 support (earlier 3.x releases pin a PHPUnit version that's too low).

The error often looks something like this, showing up in require-dev where some developers skip reading:

Problem 1
  - phpunit/phpunit 10.5.46 requires sebastian/comparator ^5.0
    -> found sebastian/comparator 6.3.1 but it does not match ^5.0.

That's PHPUnit 10 conflicting with a transitive dependency that Laravel 13's newer Symfony components pull in. It's not obvious at all from the error message.

The fix: Update your testing packages first:

composer require --dev phpunit/phpunit:^12.0

# Or if you use Pest:
composer require --dev pestphp/pest:^3.0

If you've been putting off the Pest 4 migration, now is the time. Pest 4 ships with full Laravel 13 support and a cleaner API.

Or Skip All of This

Every conflict above follows the same pattern: something in your composer.json doesn't match what Laravel 13 expects, and finding it requires running commands, reading error output, and debugging one conflict at a time.

There's a faster way. Paste your composer.json into the Laravel Upgrade Analyzer and it'll show you exactly which dependencies need attention. It checks 33 packages (including PHP version, Symfony components, and testing tools) against Laravel 13's requirements and flags each one as Blocker (stops the upgrade entirely), Breaking (needs a major version bump), or Watch (minor bump, low risk). The whole thing takes about 5 seconds and nothing gets stored.

If you went through the Laravel 12 to 13 upgrade guide and already upgraded, the analyzer still catches stale package versions and constraint mismatches you might have missed.

And if you don't want to deal with any of this yourself, I do Laravel upgrades. Send me your composer.json and I'll scope it.

FAQ

Does the Upgrade Analyzer work for older upgrades like Laravel 11 to 12?

Right now it's focused on Laravel 13 specifically. The rules check PHP version requirements, first-party Laravel packages, and 33 of the most common third-party packages against Laravel 13 compatibility. Support for older upgrade paths may come later.

What if one of my packages isn't in the analyzer's rules?

The analyzer covers 33 packages (25 auto-derived from Packagist, 8 hand-curated). If your package isn't covered, you can check manually by running composer why-not laravel/framework:^13.0 or checking the package's GitHub releases for Laravel 13 support. Found a package that should be included? Let me know and I'll add it.

Is my composer.json stored or shared?

No. The analyzer processes your file server-side and discards it immediately. Nothing is stored, logged, or shared. You can verify this in the page footer.

Filament v5 Multi-Tenancy: The Complete Implementation Guide

Hafiz — Mon, 04 May 2026 05:20:07 +0000

Every SaaS app eventually hits the same question: how do you make one application serve multiple customers with separate data? If you're building with Filament, the answer is closer than you think. Filament ships with a built-in tenancy system that handles tenant switching, automatic resource scoping, registration, and profile management out of the box.

But here's the thing: the docs cover what's available without walking you through the full implementation. You get a list of methods and interfaces, and then you're on your own to wire them together. If you've read the Building a SaaS with Filament guide, you have the foundation. This post picks up where that left off: adding proper multi-tenancy so your users can belong to teams, switch between them, and see only their team's data.

We'll build the full system: tenant model, user relationships, panel configuration, registration, profile editing, automatic scoping, and the security gotchas that trip up most developers.

How Filament's Tenancy Works

Before we write any code, it's worth understanding what Filament means by "multi-tenancy." It's not database-per-tenant isolation (like stancl/tenancy). Filament uses a shared database with a many-to-many relationship between users and tenants.

The mental model: a user belongs to many teams. A team has many users. Every resource (projects, invoices, tickets, whatever you're building) belongs to a team. When a user logs in, they pick a team, and Filament automatically scopes all resources to that team. The user can switch teams from a dropdown in the sidebar.

If your app has a simpler model where each user belongs to exactly one organization (one-to-many), you don't actually need Filament's tenancy system. You can use a global scope and a belongsTo relationship instead. Filament's tenancy is designed for the many-to-many case where users switch between contexts.

Step 1: Create the Tenant Model

Your tenant can be called anything: Team, Organization, Company, Workspace. We'll use Team here. Create the model, migration, and pivot table:

php artisan make:model Team -m
php artisan make:migration create_team_user_table

The Team migration:

Schema::create('teams', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('slug')->unique();
    $table->timestamps();
});

The pivot table:

Schema::create('team_user', function (Blueprint $table) {
    $table->id();
    $table->foreignId('team_id')->constrained()->cascadeOnDelete();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('role')->default('member');
    $table->timestamps();

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

That role column on the pivot is optional, but you'll want it eventually for permissions (owner, admin, member). Adding it now saves a migration later.

Step 2: Set Up the Relationships

The Team model needs a users relationship and the HasName interface so Filament can display the team name in the switcher:

namespace App\Models;

use Filament\Models\Contracts\HasName;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;

class Team extends Model implements HasName
{
    protected $fillable = ['name', 'slug'];

    public function users(): BelongsToMany
    {
        return $this->belongsToMany(User::class)->withPivot('role')->withTimestamps();
    }

    public function getFilamentName(): string
    {
        return $this->name;
    }
}

The User model needs the HasTenants interface. This tells Filament which tenants the user belongs to and whether they can access a specific tenant:

namespace App\Models;

use Filament\Models\Contracts\FilamentUser;
use Filament\Models\Contracts\HasTenants;
use Filament\Panel;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Support\Collection;

class User extends Authenticatable implements FilamentUser, HasTenants
{
    public function teams(): BelongsToMany
    {
        return $this->belongsToMany(Team::class)->withPivot('role')->withTimestamps();
    }

    public function getTenants(Panel $panel): array|Collection
    {
        return $this->teams;
    }

    public function canAccessTenant(Model $tenant): bool
    {
        return $this->teams()->whereKey($tenant)->exists();
    }

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

getTenants() returns the teams the user belongs to. Filament calls this to populate the tenant switcher dropdown. canAccessTenant() is the security gate: it runs on every request to make sure the user actually belongs to the tenant in the URL. Don't skip this. Without it, a user could change the team ID in the URL and access another team's data.

Step 3: Configure the Panel

Open your panel provider (usually app/Providers/Filament/AdminPanelProvider.php) and add the tenant configuration:

use App\Models\Team;
use App\Filament\Pages\Tenancy\RegisterTeam;
use App\Filament\Pages\Tenancy\EditTeamProfile;

public function panel(Panel $panel): Panel
{
    return $panel
        ->default()
        ->id('admin')
        ->path('admin')
        ->login()
        ->registration()
        ->tenant(Team::class, slugAttribute: 'slug')
        ->tenantRegistration(RegisterTeam::class)
        ->tenantProfile(EditTeamProfile::class);
}

The slugAttribute: 'slug' parameter tells Filament to use the slug column in URLs instead of the auto-incrementing ID. Your URLs will look like /admin/acme-corp/projects instead of /admin/1/projects. This is cleaner and doesn't leak information about how many teams exist.

After a user logs in, Filament redirects them to their first team (from getTenants()). If they don't have a team yet, they're sent to the registration page.

Step 4: Build the Registration Page

Create a page that extends RegisterTenant. This is what new users see when they don't belong to any team yet:

namespace App\Filament\Pages\Tenancy;

use App\Models\Team;
use Filament\Forms\Components\TextInput;
use Filament\Forms\Form;
use Filament\Pages\Tenancy\RegisterTenant;
use Illuminate\Support\Str;

class RegisterTeam extends RegisterTenant
{
    public static function getLabel(): string
    {
        return 'Create a Team';
    }

    public function form(Form $form): Form
    {
        return $form->schema([
            TextInput::make('name')
                ->required()
                ->maxLength(255)
                ->live(debounce: 500)
                ->afterStateUpdated(fn ($set, $state) => $set('slug', Str::slug($state))),
            TextInput::make('slug')
                ->required()
                ->unique(Team::class, 'slug')
                ->maxLength(255),
        ]);
    }

    protected function handleRegistration(array $data): Team
    {
        $team = Team::create($data);

        $team->users()->attach(auth()->id(), ['role' => 'owner']);

        return $team;
    }
}

The handleRegistration method creates the team and attaches the current user as the owner. This is where you'd add any onboarding logic: creating default settings, seeding initial data, or sending a welcome notification.

Step 5: Build the Profile Page

The profile page lets users edit their team settings. Same pattern:

namespace App\Filament\Pages\Tenancy;

use Filament\Forms\Components\TextInput;
use Filament\Forms\Form;
use Filament\Pages\Tenancy\EditTenantProfile;

class EditTeamProfile extends EditTenantProfile
{
    public static function getLabel(): string
    {
        return 'Team Settings';
    }

    public function form(Form $form): Form
    {
        return $form->schema([
            TextInput::make('name')
                ->required()
                ->maxLength(255),
        ]);
    }
}

This page is accessible from the tenant menu in the sidebar. Add fields as your team model grows: logo upload, billing email, timezone, whatever your app needs.

Step 6: Add the Tenant Relationship to Your Resources

This is the part most tutorials skip, and it's where data leaks happen.

Every model that belongs to a team needs a team_id column and a belongsTo relationship:

// In your migration
$table->foreignId('team_id')->constrained()->cascadeOnDelete();

// In your model
public function team(): BelongsTo
{
    return $this->belongsTo(Team::class);
}

And the Team model needs the inverse:

// In Team.php
public function projects(): HasMany
{
    return $this->hasMany(Project::class);
}

Filament uses this relationship to automatically scope queries. When a user is viewing the "Acme Corp" team, ProjectResource will only show projects where team_id matches the current tenant. You don't need to add any where clauses or global scopes yourself. Filament handles it.

But you DO need to make sure the team_id gets set when creating new records. The simplest way is a model observer or the creating event:

// In AppServiceProvider boot() or a dedicated observer
use Filament\Facades\Filament;

Project::creating(function (Project $project) {
    if (Filament::getTenant()) {
        $project->team_id = Filament::getTenant()->id;
    }
});

Without this, new records won't have a team_id and will be invisible to the tenant scoping.

The Gotcha That Trips Up Everyone

Filament's automatic scoping works for resource tables and queries. But it does NOT automatically scope form components that load options from the database.

If you have a Select component that pulls options via a relationship() method, those options are not filtered by tenant:

// This will show ALL categories from ALL teams
Select::make('category_id')
    ->relationship('category', 'name')

The official docs are explicit about this. The form components live in a separate package and don't know about tenancy. You need to scope them manually:

Select::make('category_id')
    ->relationship(
        'category',
        'name',
        fn (Builder $query) => $query->whereBelongsTo(Filament::getTenant())
    )

This applies to Select, CheckboxList, Repeater, and SelectFilter. Any component that fetches data from the database through a relationship needs manual scoping. Miss one, and users from Team A will see Team B's categories in their dropdown. That's a data leak.

If you have a lot of these, consider creating a base resource class that overrides the form builder to inject tenant scoping automatically. Or add a global scope to the models themselves, though that can cause issues outside of Filament.

Disabling Tenancy for Specific Resources

Not everything belongs to a team. Settings, plans, or shared lookup tables might be global. You can opt a resource out of tenant scoping:

class PlanResource extends Resource
{
    protected static bool $isScopedToTenant = false;
}

Or flip the default so resources are NOT scoped unless you explicitly opt in:

// In a service provider
use Filament\Resources\Resource;

Resource::scopeToTenant(false);

Then add protected static bool $isScopedToTenant = true; to each resource that should be scoped. This opt-in approach is safer for apps with a mix of global and tenant-specific data.

Controlling the Tenant Switcher

By default, Filament shows a dropdown in the sidebar for switching between teams. You can customize it in several ways.

Add a label above the current tenant name:

use Filament\Models\Contracts\HasCurrentTenantLabel;

class Team extends Model implements HasName, HasCurrentTenantLabel
{
    public function getCurrentTenantLabel(): string
    {
        return 'Active team';
    }
}

Set a default tenant when the user logs in:

// In User.php
public function getDefaultTenant(Panel $panel): ?Model
{
    return $this->teams()->first();
}

And if you want to keep the tenant menu (for profile and billing links) but hide the switcher itself, Filament v5.2 added switchableTenants():

$panel->switchableTenants(condition: false);

This is useful when tenants are selected through other means (like a URL subdomain) and the switcher UI is unnecessary.

Subdomain-Based Tenancy

Instead of path-based URLs (/admin/acme-corp/projects), you can identify tenants by subdomain (acme-corp.yourapp.com):

$panel->tenantDomain('{tenant:slug}.yourapp.com');

One thing to know: when you use a domain parameter for the entire domain, Filament registers a global route parameter pattern that allows dots and hyphens. This might conflict with other panels or routes in your app. Test thoroughly if you have multiple panels.

Applying Middleware to Tenant Routes

If you need to run middleware on all tenant-aware routes (like checking subscription status), use tenantMiddleware:

$panel->tenantMiddleware([
    \App\Http\Middleware\EnsureTeamIsSubscribed::class,
]);

This middleware runs after the tenant is resolved, so you have access to Filament::getTenant() inside it.

Accessing the Current Tenant Anywhere

Use Filament::getTenant() to get the current team in controllers, jobs, notifications, or anywhere else in your app:

use Filament\Facades\Filament;

$team = Filament::getTenant();
$teamName = $team->name;

This returns null outside of a Filament panel context, so check for that in shared code like jobs or API controllers.

FAQ

Can I use Filament's multi-tenancy with separate databases per tenant?

Filament's built-in tenancy uses a shared database with relationship-based scoping. If you need database-per-tenant isolation, look at stancl/tenancy or the FilamentTenancy plugin by TomatoPHP, which bridges stancl/tenancy with Filament panels. These are separate packages, not part of Filament core.

Do I need spatie/laravel-multitenancy alongside Filament's built-in tenancy?

For most cases, no. Filament's tenancy handles the common SaaS pattern (users belong to teams, data is scoped by team) without additional packages. Spatie's package or stancl/tenancy adds features like database isolation, domain identification, and tenant-specific configurations. If your needs are simpler, Filament alone is enough.

What happens when a user doesn't belong to any team?

Filament redirects them to the tenant registration page (if you've configured one with tenantRegistration()). If you haven't configured a registration page, the user will see an error. Always set up a registration page, even if new teams are created by admins. You can restrict who sees the registration page using a middleware or by conditionally setting it in the panel configuration.

How do I invite users to a team?

Filament doesn't include an invitation system out of the box. You'll need to build one yourself or use a package like filament-companies by Andrew Wallo, which includes team invitations, role management, and profile features similar to Laravel Jetstream. The invitation flow typically involves creating an invitation record, sending an email with a signed URL, and attaching the user to the team when they accept.

Is the automatic resource scoping safe for production?

The resource scoping is safe as long as you handle two things: implement canAccessTenant() on your User model (to prevent URL manipulation), and manually scope form components that load options via relationships. If you skip either of these, tenant data can leak. Both are covered in this guide.

What's Next

If you followed the SaaS guide and the admin dashboard guide, multi-tenancy is the natural next step. Your application now supports multiple customers, each with their own data, their own team settings, and the ability to switch between workspaces.

For a deeper look at how multi-tenancy strategies compare at the database level (shared database vs. schema isolation vs. database per tenant), the Laravel Multi-Tenancy post covers the broader architectural decisions.

If you're building a multi-tenant SaaS with Filament and need help with architecture, data isolation, or production deployment, get in touch.

Laravel AI SDK: Add Text-to-Speech and Voice to Your App in 20 Minutes

Hafiz — Fri, 01 May 2026 06:12:17 +0000

Taylor Otwell dropped a one-liner on X yesterday that stopped me mid-scroll:

$audio = Str::of('Hello, Laravel')->toAudio();

That's it. One method call and your string becomes audio. No external SDK wiring, no Guzzle calls, no API response parsing. Just ->toAudio() on a Stringable, the same way you'd call ->upper() or ->slug().

If you've been following the Laravel AI SDK through Part 1 (building a smart assistant) and Part 2 (RAG-powered support bot), you already know how text generation and tool calling work. But there's a whole side of the SDK that most developers haven't touched yet: audio. Text-to-speech generation, voice customization, speech-to-text transcription, queued processing, and testing support are all built in.

Let's build with it.

What You'll Build

By the end of this tutorial, you'll have a Laravel app that can:

Convert any text to natural-sounding audio and store it
Choose between male, female, or specific voice IDs
Coach the AI on how the audio should sound (tone, pace, emotion)
Transcribe uploaded audio files back to text (with speaker detection)
Queue audio generation for background processing
Test everything without hitting a single API

We'll start simple and build up. You don't need any AI experience to follow along.

Setup

If you already have the AI SDK installed from a previous tutorial, skip to the next section. Otherwise:

composer require laravel/ai

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

php artisan migrate

Add your provider credentials to .env. For audio, you need at least one of these:

OPENAI_API_KEY=your-openai-key
ELEVENLABS_API_KEY=your-elevenlabs-key

OpenAI supports both text-to-speech and speech-to-text. ElevenLabs supports both as well, plus Mistral handles transcription. The full provider matrix from the official docs:

Feature	Providers
TTS	OpenAI, ElevenLabs
STT	OpenAI, ElevenLabs, Mistral

That's it for setup. Let's generate some audio.

Your First Audio Generation

The Audio facade gives you a clean, fluent API:

use Laravel\Ai\Audio;

$audio = Audio::of('Your order has been shipped and will arrive by Thursday.')->generate();

The $audio object holds the raw audio content. You can cast it to a string to get the bytes, or store it directly:

// Store on your default disk
$audio->store();

// Store with a specific path and filename
$audio->storeAs('audio', 'order-confirmation.mp3');

// Store on the public disk
$audio->storePublicly();

Want to serve it directly from a controller? Return it as a response:

Route::get('/audio/preview', function () {
    $audio = Audio::of('Welcome to our support line.')->generate();

    return response((string) $audio)
        ->header('Content-Type', 'audio/mpeg');
});

That's a working audio endpoint in five lines. And if you just need a quick one-liner somewhere in your code, the Stringable integration is even shorter:

use Illuminate\Support\Str;

$audio = Str::of('Hello, Laravel')->toAudio();

This is what Taylor tweeted about. The AI SDK registers toAudio() as a method on the Stringable class, so you can chain it alongside ->replace(), ->trim(), or any other string method. It's the same pattern as ->toEmbeddings() for vector search.

Choosing a Voice

The SDK gives you three ways to control the voice:

// Quick gender selection
$audio = Audio::of('Welcome back!')->female()->generate();
$audio = Audio::of('Your package is ready.')->male()->generate();

// Specific voice by ID or name
$audio = Audio::of('Breaking news: Laravel 14 announced.')
    ->voice('alloy')
    ->generate();

OpenAI offers 11+ voices including alloy, ash, coral, echo, fable, nova, onyx, sage, shimmer, and verse. Each has a distinct character. alloy is neutral and balanced, good for most use cases. nova sounds more expressive and warm. onyx has a deeper, more authoritative tone. I'd suggest generating a short sample with each voice before committing to one for production. The difference is noticeable.

If you're using ElevenLabs, you can pass any voice ID from your account, including custom cloned voices. ElevenLabs generally produces more natural-sounding output than OpenAI for longer narration, but OpenAI is faster and cheaper for short clips. The choice depends on what you're building. Quick notifications? OpenAI. Full blog post narrations or product demos? ElevenLabs is probably worth the extra cost.

Style Instructions

This is where things get interesting. The instructions method lets you coach the AI on how the audio should sound:

$audio = Audio::of('Ahoy! Your treasure has arrived!')
    ->female()
    ->instructions('Speak like a friendly pirate captain')
    ->generate();

$audio = Audio::of('We regret to inform you that your account has been suspended.')
    ->male()
    ->instructions('Professional and empathetic, slow pace')
    ->generate();

Think of instructions as a system prompt for voice. You can control tone, pace, emotion, accent style, and delivery. It won't always nail it perfectly (this depends on the provider), but for most use cases it makes a noticeable difference. Try things like "cheerful and upbeat", "calm and measured", or "urgent, like a news anchor".

Five Practical Use Cases

Before we move on, here are patterns I think are worth building:

1. Blog post audio versions. Generate an audio file when a post is published. Store it alongside the post and embed an HTML5 audio player. Accessibility win, and it keeps readers on the page longer.

// In your Post observer or event listener
$audio = Audio::of($post->plain_text_content)
    ->female()
    ->instructions('Conversational and clear, like a podcast host')
    ->generate();

$audio->storeAs('posts', "post-{$post->id}.mp3");

2. Order confirmation voice messages. E-commerce apps can generate a short audio clip summarizing the order and attach it to the confirmation email or display it on the "thank you" page.

3. In-app notifications with voice. Instead of (or alongside) push notifications, generate a short spoken version. Useful for accessibility or for apps used in environments where reading a screen isn't practical.

4. Interactive voice responses. Build a simple IVR system. Use the AI SDK for TTS on the outbound side and transcription on the inbound side. No Twilio SDK needed for the voice generation part.

5. Language learning tools. Generate pronunciation examples dynamically. Pass different instructions for different accents or speaking speeds.

Speech-to-Text Transcription

The SDK handles the reverse direction too. If you have an audio file, turn it into text:

use Laravel\Ai\Transcription;

// From a file on disk
$text = Transcription::fromStorage('recordings/meeting.mp3')->generate();

echo (string) $text; // "Alright team, let's review the Q2 numbers..."

You can also transcribe from a raw file path:

$text = Transcription::fromPath('/tmp/uploaded-audio.webm', 'audio/webm')->generate();

This pairs naturally with file uploads. A typical controller might look like this:

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

    $path = $request->file('audio')->store('temp');

    $text = Transcription::fromPath(
        Storage::path($path),
        $request->file('audio')->getMimeType()
    )->generate();

    Storage::delete($path);

    return response()->json(['text' => (string) $text]);
}

That's a complete speech-to-text endpoint. Twenty lines, including validation and cleanup. Compare that to wiring up the OpenAI API manually with Guzzle, handling multipart uploads, parsing JSON responses, and managing error states. The SDK handles all of that behind a single generate() call.

One thing to watch for: the transcription providers have file size limits. OpenAI's Whisper accepts files up to 25MB. For longer recordings, you'll need to split the audio into chunks first. FFmpeg handles this well, and you can use Laravel's Process facade to run it:

use Illuminate\Support\Facades\Process;

Process::run("ffmpeg -i input.mp3 -f segment -segment_time 300 -c copy chunk_%03d.mp3");

That splits a recording into 5-minute chunks. Transcribe each one and concatenate the results.

Speaker Diarization

For meeting recordings or multi-speaker audio, the SDK supports speaker diarization, which identifies who spoke when. This is useful for automated meeting notes, call center analytics, or podcast transcription workflows.

Not all providers handle diarization the same way. OpenAI's newer GPT-4o Transcribe model supports it natively, but the legacy Whisper model does not. ElevenLabs supports it as well. Check the official AI SDK documentation for the exact method chain and provider requirements, as this feature is still evolving across providers.

Queued Audio Generation

Audio generation takes time, especially for longer text. You don't want users staring at a spinner while their blog post gets narrated. Queue it:

Audio::of($post->plain_text_content)
    ->female()
    ->instructions('Conversational, like a podcast')
    ->generateQueued();

The SDK dispatches a job to your queue system. If you need to do something with the audio after it generates (store it, notify the user), chain a callback:

Audio::of($post->plain_text_content)
    ->female()
    ->generateQueued()
    ->then(function ($audio) use ($post) {
        $audio->storeAs('posts', "post-{$post->id}.mp3");

        $post->update(['has_audio' => true]);
    });

This is the pattern I'd use for blog post narration. Publish the post, dispatch the audio job, and update the post record when the file is ready. The reader sees the audio player appear once it's processed.

Switching Providers

By default, the SDK uses whatever provider you've configured in config/ai.php. But you can switch providers per request:

use Laravel\Ai\Enums\Lab;

// Use ElevenLabs for higher-quality voice
$audio = Audio::of('Premium audio content')
    ->generate(Lab::ElevenLabs);

// Use OpenAI for faster, cheaper generation
$audio = Audio::of('Quick notification')
    ->generate(Lab::OpenAI);

If you've read the AI SDK overview, you'll recognize this pattern. It's the same Lab enum used for text generation. One SDK, one API, multiple providers.

Testing Without API Calls

You don't want your test suite hitting OpenAI's API every time it runs. The SDK has built-in fakes:

use Laravel\Ai\Audio;
use Laravel\Ai\Transcription;

it('generates audio for a new post', function () {
    Audio::fake();

    $post = Post::factory()->create();

    // Your code that generates audio...

    Audio::assertGenerated(function ($audio) {
        return str_contains($audio->text, 'order has been shipped');
    });
});

it('transcribes uploaded audio', function () {
    Transcription::fake();

    // Your code that transcribes...

    Transcription::assertGenerated();
});

Audio::fake() prevents any HTTP requests and lets you assert that generation happened with the right inputs. Same pattern as Http::fake(), Mail::fake(), or Queue::fake(). If you've tested anything in Laravel before, this is familiar.

Production Considerations

A few things I'd think about before shipping audio features to real users.

Cache aggressively. If the same text generates the same audio, store the result and serve it from disk next time. Don't regenerate audio for content that hasn't changed. For blog posts, generate once on publish and serve the stored file forever. Invalidate only when the content is updated.

Handle failures gracefully. API calls fail. Rate limits hit. Provider outages happen. Wrap your audio generation in try/catch blocks and make sure the user experience degrades gracefully when audio isn't available. A missing audio player is better than a 500 error.

try {
    $audio = Audio::of($text)->generate();
    $audio->storeAs('audio', "post-{$id}.mp3");
} catch (\Throwable $e) {
    Log::warning("Audio generation failed for post {$id}", [
        'error' => $e->getMessage(),
    ]);
    // Continue without audio - the post still works
}

Set appropriate timeouts. Longer text takes longer to generate. If you're narrating a 2,000-word blog post, the API might need 15-20 seconds. That's too long for a synchronous request. Use queued generation for anything over a paragraph or two.

Monitor your spending. Both OpenAI and ElevenLabs charge per character. If you have a webhook or background job that generates audio, a bug could run up a surprising bill fast. Set up billing alerts on your provider accounts and consider adding a character count guard in your code.

Costs and Rate Limits

A quick note on pricing, because this comes up every time someone talks about AI in production. As of right now, OpenAI's TTS costs roughly $15 per million characters. For context, a 2,000-word blog post is about 10,000 characters. That's $0.15 per post narrated. ElevenLabs offers 10,000 characters per month on their free tier, with paid plans starting around $5/month for higher quotas and premium voices.

For transcription, OpenAI Whisper costs about $0.006 per minute of audio. A 30-minute meeting transcript runs roughly $0.18.

These costs are low enough for most production use cases, but cache or store your generated audio. Don't regenerate the same content repeatedly.

FAQ

Can I use this without the AI SDK's agent features?

Yes. The Audio and Transcription facades are completely standalone. You don't need to create agents, define tools, or set up conversations. Just composer require laravel/ai, add your API key, and call Audio::of('text')->generate().

Which providers support the `->toAudio()` Stringable method?

The ->toAudio() method uses whatever default provider you've configured for audio in config/ai.php. You can set this to OpenAI or ElevenLabs. The Stringable shortcut doesn't accept provider arguments directly, so configure your preferred provider in the config file.

Does this work with Laravel 12 or only Laravel 13?

The AI SDK works with both Laravel 12 and 13. The ->toAudio() Stringable integration, the Audio facade, and the Transcription class are available in the current stable version of the SDK regardless of which Laravel version you're running.

Can I generate audio in languages other than English?

Yes. Pass your text in any language the provider supports. OpenAI's TTS handles dozens of languages automatically based on the input text. For ElevenLabs, you may need to select a voice trained for your target language, or use their multilingual model.

How long can the input text be?

OpenAI's TTS endpoint accepts up to 4,096 characters per request. For longer content (like a full blog post), you'll need to split the text into chunks and generate separate audio files. Concatenation is straightforward with FFmpeg.

What's Next

Text generation, tool calling, RAG, and now audio. The AI SDK covers a lot of ground from a single composer require. If you haven't tried the text features yet, start with Part 1 and Part 2. If you're already using the SDK and want to explore what Claude Opus 4.7 changes for your AI setup, that post covers the breaking changes and token adjustments you need to know about.

If you're building voice features into a Laravel app and need help with architecture, queue strategies, or production scaling, get in touch.

How to Stop an AI Agent from Destroying Your Laravel App

Hafiz — Wed, 29 Apr 2026 05:26:24 +0000

Last Friday, an AI coding agent running Claude Opus 4.6 inside Cursor deleted a startup's entire production database in 9 seconds. The company was PocketOS, a SaaS platform that car rental businesses depend on daily. The agent was working on a routine credential mismatch in a staging environment. It decided, on its own, to "fix" the problem by deleting a Railway volume. It found an API token in an unrelated file, used it to call Railway's GraphQL API, and wiped the production database along with all volume-level backups in a single API call.

The founder's post went viral. 28,000+ posts on X. Coverage in The Register, Fast Company, Business Standard. The database was eventually recovered, but it took 30+ hours and Railway staff intervening directly.

This isn't an abstract risk anymore. If you're using Claude Code, Cursor, or any AI coding agent on a Laravel project, here are the concrete things you should set up before something like this happens to you.

What actually went wrong at PocketOS

Three failures stacked on top of each other.

First, a Railway API token with root-level permissions was sitting in a file the agent could access. The token was originally created for adding custom domains via the Railway CLI, but Railway scoped it to allow any operation, including destructive ones. The agent found it and used it.

Second, the agent ignored its own project rules. PocketOS had rules in their configuration that explicitly said "NEVER FUCKING GUESS" and "NEVER run destructive/irreversible commands unless the user explicitly requests them." The agent acknowledged these rules existed and violated them anyway.

Third, Railway's API accepted the delete request without any confirmation step. And because Railway stores volume-level backups on the same volume, deleting the volume also deleted the backups.

Any one of these failures alone wouldn't have caused the incident. All three together created a 9-second disaster.

The Laravel-specific safeguards

Here's what you can do in your Laravel project right now. Each safeguard addresses one of the three failure modes above.

1. Lock down Claude Code's permissions with deny rules

This is the single most important thing. Claude Code has a tiered permission system that most developers either don't know about or leave on defaults.

Create .claude/settings.json in your project root:

{
  "permissions": {
    "deny": [
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(railway:*)",
      "Bash(forge:*)",
      "Bash(rm -rf:*)",
      "Bash(DROP DATABASE:*)",
      "Bash(php artisan db:wipe:*)",
      "Bash(php artisan migrate:fresh:*)"
    ],
    "allow": [
      "Read",
      "Edit",
      "Write(app/**)",
      "Write(resources/**)",
      "Write(tests/**)",
      "Write(routes/**)",
      "Write(config/**)",
      "Write(database/migrations/**)",
      "Bash(php artisan test:*)",
      "Bash(php artisan make:*)",
      "Bash(php artisan migrate:*)",
      "Bash(php artisan tinker:*)",
      "Bash(npm run:*)",
      "Bash(composer:*)",
      "Bash(git:*)"
    ],
    "defaultMode": "default"
  }
}

The deny rules are evaluated first, always. No allow rule can override a deny. This means even if Claude Code tries to run curl with an API token it found in your .env or a config file, the command gets blocked before it executes.

The PocketOS agent used curl to call Railway's GraphQL API. A single "Bash(curl:*)" deny rule would have stopped the entire incident.

For a deeper look at how the full Claude Code configuration system works, the complete ecosystem guide covers CLAUDE.md, settings, plugins, and MCP together.

2. Never store production credentials where the agent can read them

The PocketOS agent found a Railway API token in an unrelated file inside the project directory. That's the root cause. The agent can read any file in your working directory and its subdirectories by default.

For Laravel projects, this means:

Your .env file is readable by the agent. If your .env contains production database credentials, API keys with write access, or infrastructure tokens (Railway, Forge, DigitalOcean, AWS), the agent can see them and use them.

The fix is straightforward:

Never put production credentials in your local .env. Use a separate .env.production that only exists on the server and is never committed to the repository. Your local .env should contain only local development values: localhost database, test Stripe keys, local Redis.

If you use Laravel Forge, your production environment variables live in Forge's UI, not in your codebase. Same with Laravel Cloud. The agent never sees them.

For any credentials that must exist locally (third-party API keys for development), use scoped tokens with the minimum permissions possible. A Stripe test key can't delete your production customers. A Railway token scoped to read-only can't delete volumes. If your infrastructure provider doesn't support scoped tokens, that's a problem with the provider, not with you. But know the risk.

3. Add APP_ENV guard clauses to destructive Artisan commands

Laravel's APP_ENV variable is your built-in safety net. Use it.

If you have any custom Artisan commands that perform destructive operations (clearing caches, resetting data, running seed scripts), wrap them with an environment check:

class ResetDemoDataCommand extends Command
{
    protected $signature = 'app:reset-demo-data';

    public function handle(): int
    {
        if (app()->environment('production')) {
            $this->error('This command cannot run in production.');
            return Command::FAILURE;
        }

        // destructive operations here
    }
}

Laravel already does this for migrate:fresh and db:wipe. In production, these commands prompt for confirmation. But if you've ever run Claude Code with --dangerously-skip-permissions or bypassPermissions mode, those confirmation prompts are skipped.

The APP_ENV check inside the command itself is the last line of defense. It runs regardless of how the command was invoked.

For a full list of Artisan commands that are potentially destructive in production, check the reference page. Pay particular attention to db:wipe, migrate:fresh, migrate:reset, queue:flush, and cache:clear.

4. Use read-only database credentials for AI agent sessions

Most developers skip this one. Laravel supports multiple database connections out of the box. You can create a connection specifically for AI agent work that only has SELECT permissions:

// config/database.php
'connections' => [
    'mysql' => [
        // your normal read-write connection
    ],

    'agent_readonly' => [
        'driver' => 'mysql',
        'host' => env('DB_HOST', '127.0.0.1'),
        'database' => env('DB_DATABASE', 'forge'),
        'username' => env('DB_AGENT_USERNAME', 'agent_reader'),
        'password' => env('DB_AGENT_PASSWORD', ''),
        'charset' => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
    ],
],

Then create the MySQL user with restricted permissions:

CREATE USER 'agent_reader'@'%' IDENTIFIED BY 'your-password';
GRANT SELECT ON your_database.* TO 'agent_reader'@'%';
FLUSH PRIVILEGES;

When the AI agent needs to inspect the database (checking schema, reading data for debugging), point it at the read-only connection. The agent physically cannot run DROP TABLE, DELETE FROM, or TRUNCATE because the MySQL user doesn't have those permissions.

This is defense in depth. Even if every other safeguard fails, the database credentials themselves prevent destruction.

5. Scope your CLAUDE.md rules for what the agent should never do

Your CLAUDE.md file (or .cursorrules for Cursor) is the project-level instruction set the agent reads before every session. PocketOS had rules in place. The agent violated them. But rules still matter because they reduce the probability of bad behavior even if they can't eliminate it entirely.

Add a section specifically about destructive operations:

## Safety Rules

- NEVER make HTTP requests to infrastructure APIs (Railway, Forge, DigitalOcean, AWS, Cloudflare)
- NEVER use API tokens found in config files, .env, or anywhere in the codebase for external API calls
- NEVER run commands that delete, drop, truncate, or wipe data
- NEVER modify .env files
- NEVER run `php artisan migrate:fresh` or `php artisan db:wipe`
- If you encounter a credential mismatch or environment issue, STOP and ask the developer. Do not attempt to fix it.
- If a task requires infrastructure changes, describe what needs to change and let the developer do it manually.

These rules aren't enforceable the way deny rules in settings.json are. The agent can still violate them. But combined with the permission system, they create two layers: the permission system blocks the tool call, and the rules reduce the chance the agent even attempts it.

6. Run Claude Code in plan mode for unfamiliar tasks

Claude Code has a plan mode that lets the agent read and reason about code but blocks all writes and executions. It can analyze your codebase, propose changes, and explain what it would do, but it can't actually do anything.

Use plan mode when:

The agent is working on a part of the codebase you're not familiar with
You're debugging a production issue and want the agent's analysis without risk
You're onboarding the agent to a new project and want to see how it reasons before giving it write access

Switch modes with Shift+Tab in your terminal, or set it in settings:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Start in plan mode. Review what the agent proposes. Then switch to default or acceptEdits for the execution phase. This is the equivalent of code review before merge, but for AI agent actions.

7. Isolate your CI/CD credentials from your development environment

If your deploy pipeline uses Forge, Envoyer, or a custom script, those credentials should never be accessible from your local development environment. The PocketOS agent found a Railway CLI token because it was stored in a file within the project directory.

For Laravel projects on Forge:

Forge API tokens live in Forge's web UI, not in your codebase
Deploy scripts run on Forge's servers, not your local machine
SSH keys for deployment should be deploy-specific, not your personal key

For custom deploy pipelines, use Scotty or Envoy with credentials injected at runtime via CI secrets (GitHub Actions secrets, GitLab CI variables), never stored in the repository.

The principle: if a credential can cause damage to production, it should not exist in any file that an AI agent can read during a development session. This applies to Forge tokens, Railway tokens, AWS keys, Cloudflare tokens, and anything else with write access to your infrastructure.

The layered defense model

No single safeguard is enough. The PocketOS incident happened because three things failed simultaneously. Your goal is to stack enough layers that any single failure doesn't reach production.

Here's the stack, from outermost to innermost:

Permission deny rules block the agent from running dangerous commands at all
Credential isolation ensures the agent can't find tokens that would let it reach production infrastructure
Read-only database users prevent data destruction even if the agent somehow connects
APP_ENV guards stop destructive Artisan commands from executing in production
CLAUDE.md rules reduce the probability the agent even attempts dangerous actions
Plan mode gives you review time before any execution happens

If you set up all six, an agent would need to bypass the permission system, find a production credential you didn't isolate, somehow connect with write permissions you didn't grant, get past the environment check, ignore your rules, and do it all outside of plan mode. That's not impossible, but it's a lot of failures that would have to stack simultaneously.

Worth noting: if you're using Claude Code Channels to send commands remotely, the same permission rules apply. A command sent via Telegram still runs through the permission system. But you should be extra careful about which tasks you trigger remotely, since you're not watching the agent's output in real time.

FAQ

Does this apply to Cursor too, or just Claude Code?

Both. The PocketOS incident happened in Cursor, not Claude Code. The permission system described here is Claude Code-specific (.claude/settings.json), but the principles apply to any AI coding agent. For Cursor, use .cursorrules for project rules and check Cursor's own permission settings. The credential isolation, database user, and APP_ENV safeguards are Laravel-level and work regardless of which agent you use.

I use --dangerously-skip-permissions in CI. Is that safe?

Only if the CI environment itself is the containment layer. A purpose-built Docker container with no production credentials, no external network access, and ephemeral storage is fine. The container boundary does the security work. But never use bypassPermissions on your local machine with access to production credentials. That's the exact setup that enabled the PocketOS incident.

Should I stop using AI coding agents entirely?

No. The PocketOS incident involved multiple failures in credential management and infrastructure design, not a fundamental problem with AI agents. Developers with misconfigured CI/CD pipelines have been accidentally deleting production databases since long before AI agents existed. The agent just made it faster. Set up the safeguards, scope your credentials, and keep shipping.

What if I need the agent to run migrations in development?

Allow php artisan migrate but deny php artisan migrate:fresh and php artisan db:wipe. Regular migrations are additive (they run up() methods). migrate:fresh drops all tables and re-runs everything. The distinction matters. Your deny rules in settings.json can be that specific.

How do Claude Code Routines fit into this?

Routines run autonomously on Anthropic's cloud infrastructure with no approval prompts during a run. That means the permission system and your CLAUDE.md rules are the only safeguards. If you're setting up Routines for production work, be even more aggressive with deny rules. A Routine that reviews PRs doesn't need curl access. A Routine that runs tests doesn't need write access to .env. Scope each Routine's permissions to the minimum it needs.

Conclusion

The PocketOS incident is going to keep happening. Not because AI agents are inherently dangerous, but because developers are giving agents access to credentials and infrastructure they shouldn't have. The agent didn't hack into Railway. It used a token that was sitting in a file, exactly the way a developer would.

The fix isn't to stop using agents. It's to stop treating your development environment like it's isolated from production when it isn't. Scope your credentials. Lock down your permissions. Add the guard clauses. And test your safeguards before you need them.

If you're using AI coding agents on a Laravel project and want to make sure your permissions, credentials, and safety layers are right before something goes wrong, get in touch.

Generate Beautiful Open Graph Images for Your Laravel App with One Spatie Package

Hafiz — Mon, 27 Apr 2026 05:22:10 +0000

When someone shares a link to your Laravel app on Twitter, LinkedIn, or Slack, the platform shows a preview image. That image is the Open Graph image. Most Laravel apps either ship without one, ship with the same generic image on every page, or rely on an external service like Cloudinary or a separate Node.js renderer.

Spatie released laravel-og-image to solve this in a way that feels native to Laravel: define your OG image as HTML right inside your Blade views, let the package screenshot it, cache it, and serve it automatically. No external API. No separate CSS pipeline. No extra app.

This is the practical walkthrough I wish I had when I first looked at it. Real-world setup, the gotchas, and the Cloudflare alternative for Forge users without Chromium.

Why this package matters

Most Laravel developers I know fall into one of three buckets when it comes to OG images. They have a single static image used across every page. Or they generate images server-side using something like Browsershot directly, which works but means rebuilding the wheel every project. Or they use an external service which adds latency, cost, and another dependency to monitor.

laravel-og-image is the Laravel-native solution. The killer feature: your OG image template lives on the actual page, so it inherits your existing Tailwind classes, fonts, and Vite assets. No separate stylesheet. No design system duplication. Whatever your site looks like, your OG images can match without effort.

The pattern is borrowed from OGKit by Peter Suhm, but where OGKit is a hosted service, laravel-og-image runs entirely on your own server. Spatie also built it on top of their laravel-screenshot package, which means you can swap drivers between Browsershot (local Chromium) and Cloudflare Browser Rendering depending on your infrastructure.

How it actually works

The mental model is worth getting straight before you install anything. Here's the flow when a social platform crawls one of your pages:

Six steps that matter:

You drop an <x-og-image> Blade component into your view with whatever HTML you want.
The package renders that HTML inside a hidden <template data-og-image> tag on the page. It's invisible to humans.
Middleware automatically injects og:image, twitter:image, and twitter:card meta tags into your <head>.
The image URL contains an md5 hash of your HTML content. Change the content, hash changes, crawlers pick up the new image.
When the image URL is first requested, the package visits your page with ?ogimage appended. This renders only the template content at 1200×630 with your full CSS available.
The screenshot is saved to your public disk and served with Cache-Control headers. Cloudflare or your CDN caches it from there.

That last point matters more than it sounds. Image generation only happens once per unique HTML content. After that you're serving a static JPEG with proper cache headers.

Setting it up on a Laravel app

You need PHP 8.3+, Laravel 12+, and either Node.js with Chromium installed (for the default Browsershot driver) or a Cloudflare account with Browser Rendering enabled.

Install the package (full docs are on Spatie's documentation site):

composer require spatie/laravel-og-image

The package depends on spatie/laravel-screenshot, which depends on Browsershot, which needs Node.js and Chrome/Chromium on the server. If you're on Laravel Forge with a standard Ubuntu droplet, you'll need to install these. On Laravel Cloud, the Browsershot driver isn't an option and you'll need the Cloudflare driver instead (covered below).

Optionally publish the config file if you need to customize defaults:

php artisan vendor:publish --tag="og-image-config"

That's the entire setup. The middleware that injects meta tags registers automatically.

Your first OG image

Open any Blade view that you want to add an OG image to. For a Laravel blog, that's typically resources/views/blog/show.blade.php, the single-post view. Drop in the component:

<x-og-image>
    <div class="w-full h-full bg-slate-900 text-white flex flex-col justify-between p-16">
        <div class="flex items-center gap-4">
            <img src="{{ asset('logo.svg') }}" class="w-16 h-16" alt="hafiz.dev">
            <span class="text-2xl font-semibold">hafiz.dev</span>
        </div>

        <h1 class="text-7xl font-bold leading-tight">
            {{ $post->title }}
        </h1>

        <div class="flex items-center justify-between text-2xl text-slate-400">
            <span>By Hafiz Riaz</span>
            <span>{{ $post->published_at->format('M j, Y') }}</span>
        </div>
    </div>
</x-og-image>

That's it. Refresh the page in your browser and view source. You'll see the package has injected meta tags into your head:

<meta property="og:image" content="https://hafiz.dev/og-image/a3f8c2d1e9b4.jpeg">
<meta property="twitter:image" content="https://hafiz.dev/og-image/a3f8c2d1e9b4.jpeg">
<meta property="twitter:card" content="summary_large_image">

If your page already had OG meta tags from a layout file, remove the og:image, twitter:image, and twitter:card ones. The package handles those automatically. Keep your og:title, og:description, og:type, and any other OG tags. The package only manages the image-related ones.

Previewing without sharing the link 100 times

The most useful debugging tool in this package is the ?ogimage query parameter. Append it to any page URL and you'll see exactly what gets screenshotted, at the configured dimensions, with the page's full CSS:

https://hafiz.dev/blog/your-post-slug?ogimage

This loads in your browser as a 1200×630 viewport showing only your template content. You can iterate on the design directly here, watching it update as you tweak the Blade template. No need to actually fire the screenshot or share the URL on Twitter to see what it looks like.

Design tips that took me too long to learn

A few things I wasted time on that you can skip:

Use w-full h-full on your root element. The template renders inside a 1200×630 viewport. If you don't fill it, you'll get whitespace around your design. This is the most common mistake.

Keep text huge. OG images are viewed as thumbnails on most platforms, often around 500px wide on a phone. Your 7xl Tailwind text becomes legible. Anything smaller than 4xl is hard to read. Test at the actual rendered size before shipping.

Stick to your existing brand. Because the template inherits all your CSS, you can use your existing color tokens, fonts, and components. Don't redesign. Use what's already there.

Avoid background images that load externally. Browsershot waits for network idle by default, but external images add latency. Use solid colors, gradients, or assets served from the same domain. SVG inline is best.

Test in the LinkedIn Post Inspector and Twitter Card Validator before publishing widely. Both have rate limits but they're free. Cache busting on social platforms is a separate problem if you ship a bad image.

Using a Blade view instead of inline HTML

If you want the same OG layout across many pages, or if the template is getting complex, reference a Blade view instead:

<x-og-image view="og-image.post" :data="['title' => $post->title, 'author' => $post->author->name]" />

Then in resources/views/og-image/post.blade.php:

<div class="w-full h-full bg-slate-900 text-white flex flex-col justify-between p-16">
    <h1 class="text-7xl font-bold">{{ $title }}</h1>
    <div class="text-2xl text-slate-400">by {{ $author }}</div>
</div>

The data array becomes the variables available in the view. This pattern is what I'd reach for if you have multiple post types or you want OG images on a documentation site with consistent branding.

Fallback images for pages without templates

What about pages that don't have an explicit <x-og-image> component? Blog index pages, tag listings, your homepage. By default, those pages get no OG image at all. The package lets you define a fallback in your AppServiceProvider:

use Illuminate\Http\Request;
use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::fallbackUsing(function (Request $request) {
        return view('og-image.fallback', [
            'title' => config('app.name'),
            'tagline' => 'Laravel, Claude Code, and shipping fast',
        ]);
    });
}

The closure receives the full Request, so you can use route parameters or model bindings to customize the fallback per URL. Return null to skip the fallback for specific requests. Pages that have an explicit component are never affected.

The Cloudflare driver: when you can't run Chromium

If you're on Laravel Cloud, a serverless platform, or you just don't want to install Chromium on your server, the Cloudflare driver is the answer. It uses Cloudflare's Browser Rendering API to take the screenshot remotely.

To switch to it, configure the screenshot driver in config/screenshot.php after publishing the screenshot config:

'default' => env('SCREENSHOT_DRIVER', 'cloudflare'),

'drivers' => [
    'cloudflare' => [
        'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
        'api_token' => env('CLOUDFLARE_API_TOKEN'),
    ],
],

Then add the Cloudflare credentials to your .env:

SCREENSHOT_DRIVER=cloudflare
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-api-token

Cloudflare's Browser Rendering API has a free tier that's generous enough for most blogs and small SaaS apps. The latency is slightly higher than local Chromium because of the round-trip, but the trade-off is no Chromium dependency on your server.

If you're already on Cloudflare for DNS or CDN, this driver is the path of least resistance.

Pre-generating images so the first share never lags

The first time the OG image URL is hit, the package generates the screenshot. That can take a few seconds, especially with the Cloudflare driver. If you tweet a link to a brand new post, the first crawler might time out before the image is ready.

The fix is to pre-generate the image when the page is published:

use Spatie\OgImage\Facades\OgImage;

class PublishPostAction
{
    public function execute(Post $post): void
    {
        $post->update(['published_at' => now()]);

        dispatch(function () use ($post) {
            OgImage::generateForUrl($post->url);
        });
    }
}

This dispatches a job that generates the image after publishing. By the time anyone shares the URL, the image is already cached on disk. If you're using Laravel Queue Jobs at scale, this slots into your existing queue infrastructure cleanly.

Caching, storage, and clearing old images

By default, generated images are stored on the public disk, served from /og-image/{hash}.jpeg. The hash changes when the underlying HTML changes, so updates work automatically. But that means old images stay on disk forever unless you clean them up.

The package includes an artisan command to clear them:

php artisan og-image:clear

You can find this and the other Artisan commands the package adds in your standard php artisan list output. I run the clear command monthly via the scheduler. The cost of stale images is minimal for a small blog, but if you're running a SaaS with thousands of dynamic pages, regular cleanup keeps your disk under control.

For storage on S3 or another disk, configure it via the facade in AppServiceProvider:

use Spatie\OgImage\Facades\OgImage;

OgImage::format('webp')
    ->size(1200, 630)
    ->disk('s3', 'og-images');

WebP gives smaller file sizes if your CDN supports it. JPEG is the safer default for older crawlers.

When this package isn't the right tool

A few cases where I'd reach for something else:

Static images suffice. If your app has a single OG image used everywhere and it never needs to change, Spatie's package is overkill. Just use a static asset and reference it in your layout.

You need pixel-perfect control over fonts and rendering. Browsershot uses headless Chromium, which is great but not identical to Photoshop. If your design team wants exact rendering parity, generate images in Figma or use a service like Bannerbear.

You're on a free Laravel Cloud tier with strict timeouts. The first generation can be slow. Use the Cloudflare driver and pre-generate aggressively, or fall back to a static image.

You don't have control over the page layout. The package needs to inject meta tags into your <head> and a template into the body. If you're working inside an iframe or a constrained CMS where you can't control these, this won't work.

For everyone else building a Laravel app where shareable URLs matter, this is the right tool.

FAQ

Does this work with Laravel Cloud?

Yes, but only with the Cloudflare driver. Laravel Cloud doesn't include Chromium, so the default Browsershot driver won't work out of the box. Set up Cloudflare Browser Rendering, point the screenshot driver at it, and you're good. Pre-generation via queue jobs is also fine on Laravel Cloud.

How do I make sure social platforms pick up the new image when I update a post?

The image URL contains a hash of your template HTML. When you change the HTML (like updating a post title), the hash changes, so the URL changes, and crawlers fetch the new image automatically. The catch is that platforms like Facebook and LinkedIn cache aggressively. Use their respective debug tools to force a refresh: Facebook Sharing Debugger and LinkedIn Post Inspector.

Can I have different OG images for different page sections without writing custom logic?

Yes. Just place a different <x-og-image> component in each Blade view. Each one generates its own image based on its HTML content. For pages without an explicit component, use the fallback closure to define page-specific defaults based on the request URL or route name.

What happens if Browsershot fails to generate the image?

The package logs the error and the meta tag URL still points to the path it would have been served from. The crawler gets a 404 or 500 response on the image URL. The page itself still loads fine. To handle this gracefully, monitor the og-image queue and alert on failures. If you're using a Laravel monitoring tool like Pulse or Nightwatch, watch for failed jobs related to image generation.

Does this affect page load performance?

No. The component renders an empty hidden <template> tag in your HTML, which adds a few hundred bytes at most. The actual image generation happens out-of-band when the OG URL is requested by a crawler, not when a user loads your page. Your page weight is essentially unchanged.

Conclusion

The whole setup takes about 30 minutes from composer require to a working OG image, including some design iteration. The package does exactly what it advertises, the documentation is solid, and the Cloudflare driver makes it usable on platforms where Chromium isn't an option.

If you're shipping a Laravel app where shareable URLs matter, blog posts, product pages, documentation, this is one of those packages that pays for itself the first time someone retweets your link. Set it up once, design the template once, never think about OG images again.

Building something in Laravel where the marketing layer needs to actually work? Let's talk.

Claude Opus 4.7: What Laravel AI SDK Developers Need to Check Before Upgrading

Hafiz — Fri, 24 Apr 2026 05:44:46 +0000

Claude Opus 4.7 dropped on April 16, 2026. If you're using the Laravel AI SDK with the Anthropic driver, there are breaking API changes that will throw 400 errors in your existing setup the moment you swap the model string. Not deprecation warnings. Not behavior shifts. Actual request failures.

This isn't a "what's new" roundup. It's a migration guide for Laravel developers who already have Anthropic agents in production and want to know exactly what to touch before flipping the switch.

The model string and pricing

Start with the easy bit. The API model ID is claude-opus-4-7. In your Laravel AI SDK agent, that's one line:

#[Provider(Lab::Anthropic)]
#[Model('claude-opus-4-7')]  // was: 'claude-opus-4-6'
class YourAgent implements Agent
{
    use Promptable;
}

Pricing is unchanged from Opus 4.6: $5 per million input tokens, $25 per million output. That said, keep reading before you celebrate, because the new tokenizer changes the effective cost even though the per-token rate didn't.

The three breaking changes that will actually bite you

These apply to the Messages API. If you're using Claude Managed Agents, Anthropic says no breaking API changes are required beyond the model name. But the Laravel AI SDK talks to the Messages API under the hood, so you're affected.

1. The `#[Temperature]` attribute breaks on Opus 4.7

This is the one that will catch most Laravel AI SDK users off guard.

Starting with Opus 4.7, setting temperature, top_p, or top_k to any non-default value returns a 400 error. Not a warning. A hard failure.

The Laravel AI SDK's #[Temperature] attribute passes that value directly to the Anthropic API. So this:

#[Provider(Lab::Anthropic)]
#[Model('claude-opus-4-7')]
#[Temperature(0.7)]  // This will throw a 400 error
class YourAgent implements Agent
{
    use Promptable;
}

Will fail at runtime. The fix is to remove the attribute entirely when using Opus 4.7 with the Anthropic driver:

#[Provider(Lab::Anthropic)]
#[Model('claude-opus-4-7')]
// No #[Temperature] - Anthropic controls this internally on Opus 4.7
class YourAgent implements Agent
{
    use Promptable;
}

Same applies to any code that passes temperature directly through the SDK's fluent interface when calling Anthropic. Omit it.

If you were using temperature: 0 for determinism, note that this never actually guaranteed identical outputs on previous models either. Opus 4.7 just makes it explicit by refusing the parameter.

2. Extended thinking is gone, swap it for adaptive thinking

If you have any agents that used thinking: {type: "enabled", budget_tokens: N}, that now returns a 400 error as well.

Opus 4.7 replaces extended thinking with adaptive thinking. The model decides how much to think based on the task's complexity, guided by the effort level you set. You don't allocate a token budget manually anymore.

For the Anthropic PHP SDK directly, the before/after looks like this:

// Before (Opus 4.6)
$response = $client->messages()->create([
    'model'      => 'claude-opus-4-6',
    'max_tokens' => 64000,
    'thinking'   => ['type' => 'enabled', 'budget_tokens' => 32000],
    'messages'   => [['role' => 'user', 'content' => $prompt]],
]);

// After (Opus 4.7)
$response = $client->messages()->create([
    'model'         => 'claude-opus-4-7',
    'max_tokens'    => 64000,
    'thinking'      => ['type' => 'adaptive'],
    'output_config' => ['effort' => 'high'],
    'messages'      => [['role' => 'user', 'content' => $prompt]],
]);

Adaptive thinking is off by default on Opus 4.7. If you don't set thinking: {type: "adaptive"} explicitly, the model runs without thinking, matching Opus 4.6's default behavior when no thinking was configured. Enable it explicitly when you want it.

3. Thinking content is silently omitted

This one doesn't throw an error, but it can cause a subtle bug if your agent streams reasoning to users or logs thinking blocks.

On Opus 4.7, thinking blocks still appear in the response stream, but their thinking field is empty by default. The previous default was to return summarized thinking text. If you have frontend code or logging that reads reasoning content from the response, it will now receive an empty string without any error telling you why.

To restore visible reasoning, opt in explicitly:

'thinking' => [
    'type'    => 'adaptive',
    'display' => 'summarized',  // default is 'omitted'
],

If you're streaming responses and your UI shows a long pause before output starts, this is the cause. The model is thinking but not emitting visible progress. Set display: 'summarized' and the progress comes back.

The tokenizer change: your bill may go up

Opus 4.7 uses a new tokenizer. The same text now tokenizes to roughly 1x to 1.35x as many tokens as it did on Opus 4.6, varying by content. The per-token price didn't change. The token count for the same input did.

On a small single-turn prompt this is negligible. For multi-turn conversations, long system prompts, or agentic loops with large tool results, the compounding effect is real. A workflow that cost $10/day on Opus 4.6 could cost up to $13.50/day on Opus 4.7 without changing a single line of prompt.

Anthropic recommends updating your max_tokens to give extra headroom, including any context compaction triggers you have set. The 1M context window is unchanged and comes with no long-context premium.

Run your common prompts through /v1/messages/count_tokens on claude-opus-4-7 before and after to see your actual multiplier. It varies by content type, and code-heavy prompts tend to tokenize differently than prose. Dense PHP files and long Blade templates may be closer to the 1.35x ceiling, while short conversational messages sit nearer 1x. Check before you ship.

New features worth actually using

The `xhigh` effort level

Opus 4.7 adds xhigh as a new effort level above high. Anthropic recommends starting with xhigh for coding and agentic use cases, and a minimum of high for most intelligence-sensitive tasks. Lower effort levels (medium, low) trade quality for speed and cost.

This matters practically for the kind of agents covered in the multi-agent patterns post. A research agent that runs for several minutes benefits from xhigh. A quick classification call doesn't need more than medium.

The effort parameter is Messages API only. Claude Managed Agents handles effort automatically.

Task budgets for long agentic loops

This is worth knowing for anyone building workflows like the RAG support bot in part two of the AI SDK tutorial.

A task budget is an advisory token cap across the entire agentic loop, not per request. The model sees a running countdown and uses it to scope and prioritize work. It's distinct from max_tokens, which is a hard per-request cap the model never sees.

// Task budgets require the beta header + output_config
$response = $client->beta()->messages()->create([
    'model'         => 'claude-opus-4-7',
    'max_tokens'    => 128000,
    'output_config' => [
        'effort'      => 'high',
        'task_budget' => ['type' => 'tokens', 'total' => 128000],
    ],
    'messages'      => [['role' => 'user', 'content' => $prompt]],
    'betas'         => ['task-budgets-2026-03-13'],
]);

Use task budgets when you need the model to self-moderate on a token allowance. Skip them for open-ended quality-first tasks where you don't care about scoping. The minimum value is 20k tokens.

High-resolution image support

If your agent processes screenshots, documents, or charts, this matters. Max image resolution went from 1568px to 2576px on the long edge. That's a jump from 1.15MP to 3.75MP. Coordinate mapping is now 1:1 with actual pixels, so no more scale-factor math when using computer use workflows.

High-res images use more tokens though. If you're sending images where the extra detail isn't needed, downsample before sending to avoid unnecessary token cost.

Behavior changes that might need prompt updates

These aren't breaking changes, but they can make existing prompts behave differently.

More literal instruction following. Opus 4.7 will not silently generalize an instruction from one item to another. If your prompt says "summarize the first document," it won't infer you also want the second one summarized. This is actually a net positive for structured workflows, but you might need to be more explicit in prompts that relied on the old model filling in gaps.

Fewer tool calls by default. The model uses reasoning more and makes fewer tool calls at lower effort levels. If your agent is not invoking tools as expected after upgrading, raise the effort level.

Response length calibrates to task complexity. Opus 4.7 doesn't default to a fixed verbosity. Short tasks get shorter responses, complex ones get longer. If you had prompts that said "be concise" to fight verbose defaults, try removing that scaffolding after upgrading and see if it's still needed.

More direct tone. Opus 4.7 is more opinionated and less validation-forward than 4.6. Fewer filler phrases, fewer emoji. For most developer-facing agents this is an improvement. If your product intentionally used a warmer persona, you may need to reinforce that in the system prompt.

Migration checklist

Before upgrading any production agent to claude-opus-4-7:

API breaking changes (fix these first):

[ ] Remove #[Temperature] attribute on all Anthropic agents, or confirm your SDK version handles this automatically
[ ] Search for temperature, top_p, top_k in any direct Anthropic API calls and remove them
[ ] Search for thinking: enabled or budget_tokens patterns and migrate to thinking: adaptive
[ ] Check any code that reads thinking content from responses and add display: "summarized" if needed

Token budget:

[ ] Run your heaviest prompts through count_tokens on claude-opus-4-7 and compare with 4.6
[ ] Update max_tokens to give extra headroom on long agentic loops
[ ] Adjust context compaction triggers if you have them

Behavior validation:

[ ] Run your existing eval suite or a sample of real prompts through Opus 4.7 before switching production traffic
[ ] Check tool-call rates in agentic workflows, raise effort if the model is under-calling
[ ] Review any prompts that relied on the model generalizing instructions across items

Automate the code changes:
Anthropic ships a Claude API skill for Claude Code that applies the model ID swap, breaking parameter changes, and effort calibration across your codebase automatically. In Claude Code, run:

/claude-api migrate this project to claude-opus-4-7

It covers the same steps as the manual checklist above and outputs a list of items to verify manually after. Worth running before you do anything by hand.

Is the upgrade worth it?

For agentic coding workflows: yes, without much debate. Opus 4.7 records 64.3% on SWE-bench Pro and 87.6% on SWE-bench Verified. If you're building agents that write, review, or refactor Laravel code (the kind of thing covered in the complete Laravel AI SDK guide), the improvement on long-horizon autonomy is real.

For simple single-turn assistants: the breaking changes create migration work for no benefit if your use case doesn't involve agentic loops or vision. You can stay on Opus 4.6 for now. The model is not deprecated.

For anything processing images or documents: the resolution jump makes this worth it. 2576px is meaningfully better for reading dense screenshots, technical diagrams, and multi-column PDFs.

FAQ

Do the breaking changes apply if I'm using Claude Managed Agents instead of the Messages API?

No. Anthropic explicitly states that Claude Managed Agents has no breaking API changes for Opus 4.7. You only need to update the model name. The parameter changes described in this post apply to the Messages API, which is what the Laravel AI SDK uses under the hood.

Can I run Opus 4.6 and Opus 4.7 in the same Laravel app?

Yes. The model string is a per-agent attribute in the Laravel AI SDK, so you can point different agents at different models. Keep critical production agents on 4.6, migrate lower-stakes agents first, and validate before switching over.

If I remove #[Temperature], how do I control the model's behavior?

Prompting and the effort parameter. Anthropic's official guidance is to use prompting to guide behavior on Opus 4.7 rather than sampling parameters. If you need more creative outputs, say so in the system prompt. If you need more deterministic outputs, use stricter instructions and structured output schemas.

Will the tokenizer change affect my context window usage?

Yes. With up to 35% more tokens for the same input, you'll hit compaction or truncation thresholds sooner on long conversations. If you have logic that triggers a context summary at a specific token threshold, lower that threshold to compensate for the new tokenizer.

Is temperature still available on other Anthropic models like Haiku 4.5?

Probably, but I wouldn't assume it. The official docs say "Starting with Claude Opus 4.7, setting temperature, top_p, or top_k to any non-default value will return a 400 error," which reads like it's scoped to Opus 4.7 specifically for now. Before removing #[Temperature] from agents running Haiku or Sonnet, check the models overview directly rather than taking my word for it.

Conclusion

The summary is short: three things break, one of them silently. Remove #[Temperature] from Anthropic agents, update the extended thinking syntax if you use it, and check whether anything reads thinking content from responses. After that, Opus 4.7 is a meaningful upgrade for anything involving agentic coding or vision.

Run the migration on a staging environment first, validate with real traffic, then switch production. The /claude-api migrate skill handles most of the mechanical changes automatically.

Building something with the Laravel AI SDK that needs an architecture review before you push to production? Get in touch and let's talk through it.

Claude Code Routines: Put Your Laravel Workflows on Autopilot

Hafiz — Wed, 22 Apr 2026 04:45:27 +0000

The problem with most AI coding workflows is they stop when you do. You close your laptop, the session ends. You're asleep, nothing runs. You come back Monday morning to a pile of unreviewed PRs and no idea whether Friday's deploy is healthy.

Claude Code Routines changes that. They run on Anthropic-managed cloud infrastructure, which means the session keeps going whether your machine is on or not. You write the prompt once, wire up a trigger, and the work happens in the background.

This is a practical guide to getting Routines set up on a real Laravel project. Five concrete use cases, actual prompts, and the gotchas you'll run into before you do.

What Routines are (and what they're not)

A Routine is a saved Claude Code configuration: a prompt, one or more GitHub repositories, and optional MCP connectors, packaged together and triggered automatically. Each run creates a full Claude Code cloud session on Anthropic's infrastructure. Claude clones your repo, does the work, and pushes to a claude/-prefixed branch.

Three things are worth knowing upfront.

First, Routines are different from /loop and Desktop scheduled tasks. /loop runs prompts inside your current terminal session and dies when you close it. Desktop scheduled tasks run on a schedule but need your machine to be on and Claude Code Desktop open. Routines are the only option that runs fully unattended on cloud infrastructure.

Second, this feature is currently in research preview. Behavior, the API shapes, and rate limits may change. That said, it's available right now on Pro, Max, Team, and Enterprise plans with Claude Code on the web enabled at claude.ai/code.

Third, Routines run fully autonomously. No approval prompts during a run. Whatever you write in the prompt is what runs. This is meaningfully different from a normal Claude Code session where you can steer mid-task. If you've used Claude Code Channels to send commands remotely, think of Routines as the version that runs without you sending anything at all.

Option	Where it runs	Machine required?	Survives closing terminal?
`/loop`	Local terminal	Yes	No
Desktop scheduled task	Your machine	Yes	No
Routine	Anthropic cloud	No	Yes

The three trigger types

Every Routine needs at least one trigger. You can also stack them on the same Routine.

Schedule triggers run on a recurring cadence. Hourly is the minimum interval. Daily, weekdays, and weekly are the built-in presets. For something like "every two hours" or "first Monday of the month," you pick the closest preset in the form and then run /schedule update in the CLI to set a specific cron expression after creation.

API triggers give the Routine a dedicated HTTP endpoint. POST to it with a bearer token and optionally pass a text field for run-specific context. This is what makes Routines composable with the rest of your stack: your deploy pipeline, your alerting system, a webhook from Sentry. Any service that can make an authenticated HTTP request can trigger a Routine.

GitHub triggers react to repository events automatically. A PR is opened. A release is published. A labeled PR gets a new commit pushed. You add filters to narrow which events fire: base branch equals main, is draft is false, author contains a specific username.

One Routine can use multiple triggers. A code review Routine might run nightly (for anything opened the day before), fire on every new PR, and be callable via API from your CI pipeline. All three wired to the same prompt.

Five Laravel use cases worth setting up

1. Nightly PR review

The most immediately useful Routine for any active Laravel project. Claude reviews all open PRs opened in the last 24 hours, runs your Pest test suite, flags anything touching auth or database migrations, and leaves inline comments.

Prompt to use:

Review all open pull requests in this repository that were opened in the last 24 hours and have no reviewer assigned.

For each PR:
- Run the Pest test suite and report any failures
- Check that migrations are reversible and include both up() and down() methods
- Flag any raw queries that bypass Eloquent
- Check that jobs implement ShouldQueue and define both $tries and $timeout
- Flag any use of env() outside of config files
- Leave inline review comments for issues found
- Add a summary comment listing all issues, or confirming the PR is clean

Do not approve the PR. Add a "needs-changes" label if any issues are found, and "passed-ai-review" if clean.

Set a schedule trigger for every weekday at 8:00 AM. You start the morning with feedback already posted. Human reviewers can focus on architecture instead of catching env() in the wrong place.

2. Queue health check

Horizon is great but it doesn't catch everything. A nightly Routine can run queue diagnostics on your Laravel project and ping you only when something is actually wrong, not just generate noise.

Using the environment variables available in this session, run the following checks:

1. Run php artisan queue:monitor against all configured queue drivers
2. Check the failed_jobs table for any entries created in the last 24 hours
3. Hit the /horizon/api/stats endpoint and verify Horizon is running and workers are active
4. Check the application log for any CRITICAL or ERROR entries from the last 24 hours

If all checks pass, exit without posting anything.
If any check fails, post a message to the #alerts Slack channel with the failure details and the exact artisan commands to fix it.

You'll need a Slack MCP connector configured and your environment credentials set as environment variables in the cloud environment. For a full list of queue-related Artisan Commands, the reference page is worth bookmarking when you're building out the prompt.

3. Automated code review on PR open

Set a GitHub trigger to fire on pull_request.opened with one filter: is draft is false. This catches every non-draft PR the moment it's opened and runs your team's checklist before a human reviewer even looks at it.

A new pull request has just been opened. Apply our Laravel code review checklist:

- New controllers must use the single-action pattern (one public __invoke method only)
- Form Requests used for all validation, never validate() inside controllers
- No env() calls outside of config files
- No missing $fillable on new Eloquent models
- All new jobs implement ShouldQueue and define $tries and $timeout
- Flag any database queries inside loops (N+1 problem) with the exact file and line
- No direct use of DB::statement() or DB::select() without a comment explaining why

Leave an inline comment for each violation. Post a summary comment at the bottom of the PR. Add label "passed-ai-review" if clean, or "needs-changes" if violations were found. Do not approve or request changes on the PR directly.

The filter matters here. is draft: false means the Routine only fires on PRs that are actually ready for review. You don't want it running every time someone pushes a commit to a draft.

4. Post-deploy smoke test via API

Wire your CD pipeline to trigger a Routine every time a production deploy completes. The Routine runs smoke checks against the new build and posts the result to your release channel.

The API trigger gives you a text field you can use to pass deploy context. From your deploy script:

curl -X POST https://api.anthropic.com/v1/claude_code/routines/trig_01XXXXX/fire \
  -H "Authorization: Bearer YOUR_ROUTINE_TOKEN" \
  -H "anthropic-beta: experimental-cc-routine-2026-04-01" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "Deploy complete. SHA: abc123. Environment: production."}'

Note: the bearer token here is your Routine-specific token, not your Anthropic API key. Generate it from the API trigger setup in the web UI. It's shown once, so store it in your secrets manager immediately.

The Routine prompt can reference the deploy context passed via text:

A production deploy has just completed. The deploy details are in your session context.

Run the following smoke checks:
1. Hit the /health endpoint and verify a 200 response
2. Run php artisan about to confirm the application is responding
3. Run php artisan queue:monitor and report queue status
4. Check the error log for any new CRITICAL entries in the last 5 minutes

Post results to the #deployments Slack channel. Include the deploy SHA from the context. Mark as PASS if all checks succeed, FAIL with details if any check fails.

5. Weekly documentation drift detection

Docs get stale. A weekly Routine that scans merged PRs, compares changed methods against your /docs directory, and opens update PRs when it finds drift handles this automatically.

Scan all pull requests merged in the last 7 days.

For each merged PR:
1. Identify which PHP files changed
2. Check whether the changed public methods or classes are referenced in the /docs directory
3. If documentation references a changed method but looks outdated based on the diff, open a PR against the docs branch with a suggested update

Skip PRs that only changed tests, migrations, config files, or frontend assets. Only flag documentation that references changed public-facing methods or API endpoints.

Schedule it for Sunday at midnight. By Monday morning you have doc update PRs queued, not a manual task sitting in someone's backlog.

Setting up your first Routine

The fastest path is through the web UI. Go to claude.ai/code/routines and click New routine.

Give it a descriptive name. "Nightly PR Review" is better than "Routine 1." Write the prompt. This is the most important part: the Routine runs without you in the loop, so the prompt must be explicit about what to do and what success looks like. Vague prompts produce vague results, and there's no one watching to redirect them.

Select your GitHub repository. Claude clones it fresh at the start of every run, starting from the default branch.

Pick an environment. The Default environment works for most cases. If your Routine needs to call external APIs or read secrets like Sentry tokens or Slack webhooks, create a custom environment first and set those values as environment variables there.

Add your trigger. For a scheduled Routine, pick the frequency. Times are set in your local timezone and converted automatically, so "9:00 AM" fires at 9:00 AM wherever you are, not in some UTC offset you have to calculate.

Review the connectors. All connected MCP connectors are included by default. Remove anything the Routine doesn't actually need. A Routine that only reviews code and opens PRs has no reason to have Linear or Google Drive in scope.

Click Create. Hit Run now on the detail page to test it immediately without waiting for the next scheduled time.

From the CLI, run /schedule in any Claude Code session to create a Routine conversationally. Useful when you know exactly what you want and don't want to click through the web UI. /schedule list shows all your Routines, /schedule update changes one, and /schedule run triggers it immediately.

Branch permissions: the default that catches people

By default, Routines can only push to branches prefixed with claude/. This is intentional. An autonomous agent creating commits on main or develop is risky if the prompt isn't perfectly scoped.

When you add a repository to a Routine, there's an Allow unrestricted branch pushes toggle. Leave it off unless you have a specific need. The claude/ prefix keeps automated work clearly identifiable and makes cleanup straightforward if something goes sideways.

If your Routine is creating PRs that look right but fails on push, this is almost certainly the reason. Enable unrestricted pushes for that repo in the Routine's settings.

The flip side: PRs created by a Routine appear under your GitHub identity. Commits carry your username. Slack messages sent by a Routine's connector use your Slack account. The Routine acts as you, not as a bot account.

Plans and limits

Routines are available on Pro, Max, Team, and Enterprise plans. They draw from your regular Claude Code subscription usage the same way interactive sessions do. There's also a daily cap on how many Routine runs can start per account, visible at claude.ai/settings/usage.

If you hit the daily cap, additional runs are rejected until the window resets. On Team and Enterprise plans with extra usage enabled, Routines continue on metered overage instead.

GitHub event triggers also have per-routine and per-account hourly caps during the research preview. Events beyond the limit are dropped until the window resets. Worth keeping in mind if you're setting up a trigger on a high-volume repository.

When to use GitHub Actions instead

Routines are not a replacement for CI/CD. Running tests on every push, deploying to staging on merge, enforcing security checks before a PR can be merged, anything that needs to block a developer workflow belongs in GitHub Actions. It integrates with branch protections, runs in your own infrastructure, and has native visibility in the PR UI.

Routines are better for background work that doesn't need to gate anything. Review, triage, documentation updates, monitoring. Think of it as the difference between a gatekeeper (CI/CD) and an assistant handling repetitive work in the background.

Also, Routines run with no approval prompts. That's the point, but it's also a risk. Test any Routine with Run now and review what it actually did before leaving it to run unattended. A badly scoped PR review prompt that opens 30 spurious PRs is not a great Monday morning.

The Claude Code ecosystem post covers where Routines fit alongside other pieces like CLAUDE.md, skills, MCP, and the plugin marketplace if you want the full picture.

FAQ

Do Routines work on private repositories?

Yes. Routines clone your connected GitHub repositories, including private ones, as long as you've granted the necessary access via the web setup flow or /web-setup in the CLI. GitHub event triggers specifically require installing the Claude GitHub App on the repository. Repository access via /web-setup is separate and doesn't install the App automatically.

What's the difference between a Routine and a GitHub Action that calls Claude Code?

GitHub Actions run on GitHub's infrastructure, count against your GitHub Actions minutes, and can gate PRs and deployments through required status checks. Routines run on Anthropic-managed infrastructure and count against your Claude Code subscription. Use GitHub Actions when you need to block something. Use Routines for background work that doesn't need to block anything.

Can I share Routines with teammates?

Not currently. Routines belong to your individual claude.ai account and aren't shared. Everything a Routine does through your GitHub identity or connectors appears as you. For team workflows where multiple people need the same automation, each person sets up their own Routine, or you handle it through GitHub Actions with shared secrets.

Can I pass different context on each API trigger call?

Yes. The optional text field in the API request body is passed to the Routine as run-specific context alongside its saved prompt. Pass anything: a Sentry alert body, a deploy SHA, a list of changed files. The Routine receives it as a literal string, so don't send structured JSON expecting it to be parsed. If you need structured data, serialize it yourself and parse it in the prompt instructions.

What happens when a Routine run fails mid-session?

The run session stays visible at claude.ai/code/routines. You can open it, see exactly what Claude did, and continue the conversation manually if needed. The Routine itself keeps running on future triggers. Only that individual run failed.

Conclusion

Routines flip the default. Instead of Claude Code being a tool you actively drive, it becomes something that works in the background while you're focused on other things, or asleep. The nightly PR review alone is worth the setup time on any project with more than one contributor.

Start with one. Set up the nightly PR review, run it manually a few times to tune the prompt, then leave it running. Once you trust it, you'll think of five more things to automate.

Building a Laravel application that needs architectural review or a second set of eyes on code quality? Get in touch and let's talk about what that looks like.

How Laravel Events, Listeners, and Observers Actually Work (And When to Use Each)

Hafiz — Mon, 20 Apr 2026 05:51:50 +0000

A new user registers on your SaaS. You need to send a welcome email, provision their free trial, log the signup event, and notify your Slack channel. Where does that code go?

If the answer is "the controller", your controller is doing too much. If the answer is "a listener that calls a listener that calls another listener", your event system is doing too much. Laravel gives you three distinct tools to get there: Events, Listeners, and Observers. Each one has a clear job. The distinction is worth understanding because reaching for the wrong one creates the kind of coupling you were trying to avoid in the first place.

What Problem Are We Actually Solving?

When a user registers, the naive approach stuffs everything in the controller:

public function store(RegisterRequest $request): RedirectResponse
{
    $user = User::create($request->validated());

    Mail::to($user)->send(new WelcomeEmail($user));
    Trial::provision($user);
    Slack::notify('New signup: ' . $user->email);
    Log::info('User registered', ['id' => $user->id]);

    return redirect('/dashboard');
}

This works. It's also a problem. The controller now knows about mail, trials, Slack, and logging. Add a new onboarding step and you touch the controller. Change how trials work and you touch the controller. Write a test for the controller and you mock four different things.

Events, Listeners, and Observers flip this around. The controller fires a signal ("something happened") and the rest of the application reacts. The controller doesn't know or care what reacts.

Events: The Signal

An event is a plain PHP class that represents something that happened. That's it. It carries data about the occurrence and nothing else.

<?php

namespace App\Events;

use App\Models\User;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class UserRegistered
{
    use Dispatchable, SerializesModels;

    public function __construct(
        public readonly User $user
    ) {}
}

Create one with Artisan:

php artisan make:event UserRegistered

Fire it anywhere in your application:

UserRegistered::dispatch($user);
// or
event(new UserRegistered($user));

An event class should be small. It shouldn't contain methods that do things. It's a data container, not a service. The name should describe what happened in past tense: UserRegistered, OrderShipped, PaymentFailed. If you find yourself writing logic inside an event class, that logic belongs in a listener.

Listeners: What Reacts

A listener receives an event and does something with it. One event can have many listeners. Listeners don't know about each other.

php artisan make:listener SendWelcomeEmail --event=UserRegistered

<?php

namespace App\Listeners;

use App\Events\UserRegistered;
use App\Mail\WelcomeEmail;
use Illuminate\Support\Facades\Mail;

class SendWelcomeEmail
{
    public function handle(UserRegistered $event): void
    {
        Mail::to($event->user)->send(new WelcomeEmail($event->user));
    }
}

Each listener does one job. SendWelcomeEmail sends a welcome email. ProvisionFreeTrial provisions a trial. NotifySlack posts to Slack. Adding a new step means adding a new listener. You don't touch the existing ones.

Auto-Discovery in Laravel 11+

Before Laravel 11, you had to manually register every event and listener in EventServiceProvider::$listen. Laravel 11 removed EventServiceProvider from the default application structure and turned on auto-discovery by default.

Auto-discovery works by scanning app/Listeners/ and looking for handle() methods. If a handle() method type-hints an event class, Laravel automatically wires that listener to the event. No registration required.

// This listener is auto-discovered. No registration needed.
class SendWelcomeEmail
{
    public function handle(UserRegistered $event): void
    {
        // ...
    }
}

This matters because the old approach had a subtle maintenance problem: the $listen array in EventServiceProvider was a second source of truth. You could create a listener, forget to register it, and your code would run without errors. The listener just silently never fired. Auto-discovery eliminates that category of bug entirely.

One listener class can also handle multiple events by defining multiple methods, each type-hinting a different event:

class UserActivityListener
{
    public function handleLogin(Login $event): void
    {
        // Runs on login
    }

    public function handleLogout(Logout $event): void
    {
        // Runs on logout
    }
}

Laravel's scanner picks up both handleLogin and handleLogout automatically because they start with handle and type-hint an event class.

In production, cache the discovered listener manifest so Laravel doesn't scan on every request:

php artisan event:cache

Clear it during deployment with:

php artisan event:clear

If you're on an older Laravel version or want explicit control, you can still register listeners in AppServiceProvider::boot():

use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(
        UserRegistered::class,
        SendWelcomeEmail::class
    );
}

Both approaches work. Auto-discovery is cleaner for new applications. Explicit registration is useful when you need listeners from third-party packages or conditional registration.

Queued Listeners

Sending emails, making HTTP calls, generating reports: these don't need to block the HTTP response. Implement ShouldQueue and Laravel automatically dispatches the listener as a background queue job:

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class SendWelcomeEmail implements ShouldQueue
{
    use InteractsWithQueue;

    public string $queue = 'emails';
    public int $delay = 30; // seconds

    public function handle(UserRegistered $event): void
    {
        Mail::to($event->user)->send(new WelcomeEmail($event->user));
    }

    public function failed(UserRegistered $event, \Throwable $exception): void
    {
        // Handle failure: log it, alert, retry logic, etc.
        Log::error('Welcome email failed', [
            'user' => $event->user->id,
            'error' => $exception->getMessage(),
        ]);
    }
}

The failed() method is important. Queued listeners can fail. Define this method to handle failures gracefully rather than silently losing the email send.

After Database Commit

One common gotcha: a listener fires before the database transaction commits. Your listener reads a user ID, queries the database, and finds nothing because the record doesn't exist yet.

The fix is ShouldHandleEventsAfterCommit:

use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;

class ProvisionFreeTrial implements ShouldQueue, ShouldHandleEventsAfterCommit
{
    public function handle(UserRegistered $event): void
    {
        // Guaranteed to run only after the database transaction commits
        Trial::createFor($event->user);
    }
}

Use this whenever your listener reads from the database and you're dispatching the event inside a transaction.

Observers: Model Lifecycle Hooks

Observers are a different tool for a different job. While events and listeners handle application-level signals, observers handle Eloquent model lifecycle events: creating, created, updating, updated, deleting, deleted, and more.

php artisan make:observer UserObserver --model=User

<?php

namespace App\Observers;

use App\Models\User;

class UserObserver
{
    public function created(User $user): void
    {
        // Runs every time any User is created anywhere in the codebase
    }

    public function updated(User $user): void
    {
        // Runs every time any User is updated
    }

    public function deleted(User $user): void
    {
        // Runs every time any User is deleted
    }
}

Register the observer on the model using the #[ObservedBy] PHP attribute, introduced in Laravel 10.44 and fully supported in Laravel 11, 12, and 13:

<?php

namespace App\Models;

use App\Observers\UserObserver;
use Illuminate\Database\Eloquent\Attributes\ObservedBy;
use Illuminate\Foundation\Auth\User as Authenticatable;

#[ObservedBy([UserObserver::class])]
class User extends Authenticatable
{
    // ...
}

Before this attribute existed, you'd register observers in a service provider:

// AppServiceProvider::boot()
User::observe(UserObserver::class);

Both still work. The #[ObservedBy] attribute is cleaner because the registration lives on the model itself. You can see at a glance that UserObserver is active without hunting through providers.

The Full List of Observer Methods

An observer class can define methods for any of the Eloquent lifecycle events:

class UserObserver
{
    public function retrieved(User $user): void {}   // After fetching from DB
    public function creating(User $user): void {}    // Before insert
    public function created(User $user): void {}     // After insert
    public function updating(User $user): void {}    // Before update
    public function updated(User $user): void {}     // After update
    public function saving(User $user): void {}      // Before create or update
    public function saved(User $user): void {}       // After create or update
    public function deleting(User $user): void {}    // Before delete
    public function deleted(User $user): void {}     // After delete
    public function restoring(User $user): void {}   // Before soft-restore
    public function restored(User $user): void {}    // After soft-restore
}

You don't need to define all of them. Define only the lifecycle hooks your use case actually needs. An observer with one method is perfectly fine.

The creating and updating hooks (before the operation) are useful for validation, transformations, or cancelling the operation by returning false. The created and updated hooks (after the operation) are better for side effects like sending notifications or clearing caches, since you know the database state is settled.

What Goes in an Observer vs a Listener

This is where most developers get confused. The distinction is simpler than it looks:

Use an observer when the behavior should trigger on every instance of a model event, everywhere in the codebase. Audit logging is the clearest example: every time any user is created, updated, or deleted, you want a log entry. An observer is the right place for that.

Use an event and listener when the behavior is specific to a particular business flow. A user registering via the web form should get a welcome email. A user created programmatically by a data import job probably shouldn't. Events give you control over when to fire the signal. Observers fire automatically no matter what.

Here's a practical SaaS breakdown:

Scenario	Tool	Why
Send welcome email on registration	Event + Listener	Only fires when you explicitly dispatch the event
Write to audit log on every User update	Observer	Should always fire, regardless of where the update originates
Provision free trial after signup	Event + Listener (queued)	Business flow specific, benefits from queueing
Clear cache when Post is deleted	Observer	Should always happen when any Post is deleted
Notify Slack on first payment	Event + Listener	Specific business milestone, not every payment creation
Update `last_updated_at` on every Order save	Observer	Always should happen, tightly coupled to model lifecycle

If you're still unsure which to reach for, this decision flow covers most cases:

A Real-World Pattern: User Registration

Here's how all three tools work together in a user registration flow. The controller fires one event. Two listeners react to that event asynchronously. The observer independently handles model-level concerns for every user creation, no matter where it originates.

// Controller stays clean
class RegisterController extends Controller
{
    public function store(RegisterRequest $request): RedirectResponse
    {
        $user = User::create($request->validated());

        UserRegistered::dispatch($user);

        return redirect('/dashboard');
    }
}

// Listener: sends welcome email (queued)
class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event): void
    {
        Mail::to($event->user)->send(new WelcomeEmail($event->user));
    }
}

// Listener: provisions trial (queued, after commit)
class ProvisionFreeTrial implements ShouldQueue, ShouldHandleEventsAfterCommit
{
    public function handle(UserRegistered $event): void
    {
        Trial::createFor($event->user);
    }
}

// Observer: handles model-level concerns for ALL user creation
#[ObservedBy([UserObserver::class])]
class User extends Authenticatable { /* ... */ }

class UserObserver
{
    public function created(User $user): void
    {
        AuditLog::record('user.created', $user->id);
    }

    public function updated(User $user): void
    {
        AuditLog::record('user.updated', $user->id, $user->getDirty());
    }
}

The controller fires one event. Two listeners react to that event in the background. The observer independently logs every user creation, including the one triggered by the controller. Each piece of code does one job and doesn't know about the others.

This pattern scales well in multi-tenant SaaS applications, where the same model events fire across tenants and the observer ensures audit logging is consistent regardless of which flow created the record.

Testing Events and Listeners

Laravel's Event::fake() replaces the event dispatcher with a fake that captures dispatched events without actually running listeners. This is what you want for most feature tests. You want to assert that an event was dispatched, not that a listener ran.

use App\Events\UserRegistered;
use Illuminate\Support\Facades\Event;

test('user registration dispatches UserRegistered event', function () {
    Event::fake();

    $response = $this->post('/register', [
        'name' => 'Hafiz Riaz',
        'email' => 'hafiz@example.com',
        'password' => 'password',
        'password_confirmation' => 'password',
    ]);

    Event::assertDispatched(UserRegistered::class, function ($event) {
        return $event->user->email === 'hafiz@example.com';
    });
});

Test the listener separately by instantiating it directly:

use App\Events\UserRegistered;
use App\Listeners\SendWelcomeEmail;
use App\Models\User;
use Illuminate\Support\Facades\Mail;
use App\Mail\WelcomeEmail;

test('SendWelcomeEmail listener sends welcome email', function () {
    Mail::fake();

    $user = User::factory()->create();
    $event = new UserRegistered($user);

    (new SendWelcomeEmail)->handle($event);

    Mail::assertSent(WelcomeEmail::class, fn ($mail) => $mail->hasTo($user->email));
});

For observers, Event::fake() silences them by default. Model events don't fire when the dispatcher is faked. If you need observers to run inside a fake context, use Event::fakeFor():

test('observer logs user creation', function () {
    // Events are faked, so observers don't run here
    $order = Event::fakeFor(function () {
        return Order::factory()->create();
        // Event::assertDispatched() checks happen inside fakeFor
    });

    // After fakeFor, events and observers run normally
    $order->update(['status' => 'shipped']);
    // Observer fires here
});

You can also fake only specific events, leaving others to run normally:

Event::fake([UserRegistered::class]);
// Only UserRegistered is faked; all other events fire as usual

Artisan Commands Reference

# Create
php artisan make:event UserRegistered
php artisan make:listener SendWelcomeEmail --event=UserRegistered
php artisan make:observer UserObserver --model=User

# List all registered events and listeners
php artisan event:list

# Cache discovered events (run on deployment)
php artisan event:cache

# Clear the event cache
php artisan event:clear

You can find the full list of available Artisan commands in the Laravel Artisan Commands reference.

Common Mistakes

Putting business logic in events. Events are data containers. If you have methods in your event class that query the database or send emails, move that logic to a listener. Keeping events lean also makes them serializable, which matters for queued listeners. Laravel needs to serialize the event to pass it to the queue worker.

Using observers for flow-specific behavior. Observers fire on every model event everywhere. If you want an email sent only when a user registers via the web form, use an event that you dispatch explicitly, not an observer that fires every time a User record is created (including imports, seeds, and tests). Observers are for behavior that should always fire regardless of the origin of the change.

Forgetting event:cache in production. Auto-discovery scans the filesystem on every request unless you cache the manifest. Always run php artisan event:cache during deployment. If you're using Laravel Forge, add it to your deployment script. If you're using a CI/CD pipeline, add it after the composer install step.

Not defining failed() on queued listeners. Queued listeners can fail silently. Define the failed() method to handle errors: log them, send alerts, or retry with different parameters. A queued listener that throws an exception will be retried based on your queue configuration, but without a failed() handler you have no visibility into what failed.

Dispatching events inside database transactions without ShouldHandleEventsAfterCommit. If your listener reads data that the transaction hasn't committed yet, it will fail in subtle ways. Always add ShouldHandleEventsAfterCommit when your listener queries data that the same transaction creates.

Testing with Event::fake() and expecting observers to run. When you call Event::fake(), model observers are also silenced because they rely on the event system internally. If your test needs observer behavior, either use Event::fakeFor() for the specific section that shouldn't fire observers, or don't fake events for the part of the test where observer behavior matters.

FAQ

Should I use Events or Jobs for background tasks?

Both can run code in the background, but the semantics differ. Events signal that something happened and multiple listeners can react. Jobs represent a specific unit of work with one purpose. Use events when you have multiple things that need to react to an occurrence. Use jobs when you have one specific task to run.

Can one listener handle multiple events?

Yes. Type-hint multiple event classes in separate handle* methods, or use union types in a single method. With auto-discovery, Laravel registers each handle* method as a listener for the event it type-hints.

When should I fire an event vs call a method directly?

Fire an event when you want to decouple the caller from what happens next, especially when multiple things need to react, or when the reactions might change in the future. Call a method directly when it's a single, always-present behavior that's tightly coupled to the action.

Do observer methods run inside database transactions?

By default, observer methods run inside the same transaction as the Eloquent operation. If you need the observer to run only after the transaction commits, implement ShouldHandleEventsAfterCommit on the observer class.

What happens to queued listeners if the application crashes before they run?

They stay in the queue. As long as you're using a persistent queue driver like Redis or database, queued jobs survive application restarts. This is one of the advantages of queuing over synchronous execution.

Conclusion

Events signal that something happened. Listeners react to those signals. Observers hook into the Eloquent model lifecycle automatically.

The practical rule: if you want behavior to fire only when you choose to fire it, use events. If you want behavior to fire every time a model changes no matter what, use observers. When in doubt, events with explicit dispatch give you more control.

Think about it from the perspective of a new developer joining your codebase. If they see a UserRegistered::dispatch($user) in the controller, they know exactly where to look for what happens next: the app/Listeners/ directory, or a quick php artisan event:list. If they see an observer on the User model, they know that code runs on every user lifecycle event regardless of where it originates. Both are discoverable. Both have clear intent. That's the point.

The modern Laravel 11+ setup makes this easier. Auto-discovery removes the registration boilerplate. #[ObservedBy] keeps observer registration on the model where it belongs. ShouldHandleEventsAfterCommit handles the transaction timing edge cases that have caught developers off guard for years. And Event::fake() makes the whole system testable without running real side effects.

Start with events and listeners for business flows. Add observers for model lifecycle concerns that should always fire. Keep each piece small and focused. The system scales from a single controller action to a multi-tenant SaaS without the architecture needing to change.

Building something that needs this architecture across a complex codebase? Get in touch.

How I Built a macOS Menu Bar App with NativePHP, Laravel 12 and Livewire 4

Hafiz — Thu, 16 Apr 2026 08:25:31 +0000

Every developer has ignored a break reminder. The notification pops up, you dismiss it in 0.2 seconds without thinking, and two hours later your back hurts and your eyes ache. Notifications don't work. You need something you can't mindlessly dismiss.

So I built ForcedBreak. A macOS menu bar app that shows a full-screen overlay after a configurable interval (25, 45, 60 minutes, whatever you prefer) and makes you complete a physical challenge before you can get back to work. Push-ups. A glass of water. Box breathing. It covers all your monitors. You have to consciously deal with it: complete the challenge, skip it (with a 5-minute penalty), or close it and feel bad about yourself.

The interesting part isn't the concept. It's that I built it entirely with PHP: NativePHP, Laravel 12, Livewire 4, and Tailwind. No Swift. No Objective-C. No raw Electron boilerplate. The app is open source on GitHub and the .dmg for Apple Silicon is available on the releases page.

This post covers the architecture and the four problems that gave me real trouble. If you're building anything with NativePHP, you'll hit at least two of these.

Why NativePHP and Why Laravel 12, Not 13

NativePHP wraps your Laravel app in Electron, giving you access to native macOS APIs through Laravel facades: menu bar, system notifications, window management, screen info. You write PHP and Blade. NativePHP handles the Electron layer.

If you want a proper NativePHP introduction first, I covered the setup basics in Build Your First App with Laravel and NativePHP. This post assumes you have a working NativePHP setup and focuses on the harder parts.

The stack for ForcedBreak:

Layer	Choice	Why
Desktop framework	NativePHP 1.3	Laravel-native desktop apps, no Swift needed
Backend	Laravel 12	Familiar cache, ORM, everything
UI	Livewire 4	Reactive components without writing JavaScript
Styling	Tailwind CSS v4	Dark theme, fast iteration
Database	SQLite	Fully offline, ships with the app

One critical note on the version: NativePHP 1.x requires illuminate/contracts ^10.0|^11.0|^12.0. Laravel 13 internalized illuminate/contracts as part of the framework itself, which breaks this Composer constraint. You can't use Laravel 13 with NativePHP 1.x. Pinning to Laravel 12 is the right call until NativePHP officially ships support.

The Core Architecture: Two Timers, Not One

This is the most important thing to understand before building any NativePHP app that needs background behavior.

The obvious approach is Livewire's wire:poll. Set it to tick every second, decrement a counter, show the result in the menu bar. Simple enough.

It doesn't work. Livewire polling only runs when a browser window is open. A menu bar app lives in the menu bar. The popover window is closed 99% of the time. When the user isn't looking at the popover, wire:poll isn't running. The timer would only tick when the user clicked to open it.

The solution is two separate systems:

Layer 1: The background ticker (authoritative). A dedicated Artisan command runs in an infinite loop as a persistent ChildProcess. It ticks every second, decrements the cache, updates the menu bar label, and triggers the overlay when the timer hits zero. This runs whether the popover is open or not.

Layer 2: Livewire polling (UI only). When the user opens the popover, wire:poll.1000ms reads from the same cache keys and displays the countdown. It never writes to cache. It's a pure reader.

// app/Console/Commands/TickMenuBarLabel.php
public function handle(): void
{
    $lastLabel = '';

    while (true) {
        $start = microtime(true);

        if (!cache()->get('on_break', false)) {
            $secondsLeft = max(0, cache()->get('break_seconds_left', 0) - 1);
            cache()->put('break_seconds_left', $secondsLeft, now()->addHours(2));

            // Only call MenuBar::label() when the value actually changes
            $label = sprintf('%02d:%02d', intdiv($secondsLeft, 60), $secondsLeft % 60);
            if ($label !== $lastLabel) {
                MenuBar::label($label);
                $lastLabel = $label;
            }

            if ($secondsLeft <= 0) {
                $this->openOverlayOnAllScreens();
            }
        }

        $this->sleepUntilNextSecond($start);
    }
}

protected function sleepUntilNextSecond(float $start): void
{
    $elapsed = microtime(true) - $start;
    $remaining = max(0.1, 1.0 - $elapsed);
    usleep((int) ($remaining * 1_000_000));
}

This is registered in NativeAppServiceProvider:

ChildProcess::artisan('app:tick-menubar-label', 'ticker', persistent: true);

The sleepUntilNextSecond() method deserves a mention because the naive version of this loop (just calling sleep(1)) causes 100% CPU usage. sleep(1) blocks for exactly one second but ignores the time the tick itself took. Over time the loop drifts, and under some system conditions it spins. The fix is to measure how long the tick took with microtime(true) and sleep only the remaining microseconds to the next second boundary. It also skips calling MenuBar::label() when the value hasn't changed, which avoids unnecessary HTTP calls to Electron's bridge on every tick.

The persistent: true flag tells NativePHP to restart the process if it crashes. Without it, the ticker dies and the menu bar freezes.

If you've worked with Laravel queue workers running as background daemons, this pattern will feel familiar. The mental model is the same: one authoritative process manages state, and the UI reads from it. The difference here is that the "worker" is an infinite loop command rather than a Horizon worker, because NativePHP's scheduler runs every minute by default and a one-minute resolution isn't good enough for a visible countdown timer.

The reason persistent: true matters is that an infinite loop command can crash. SQLite can throw an exception, a cache operation can fail, or the process can be killed by macOS under memory pressure. Without persistent: true, your menu bar label freezes at whatever time it was showing when the crash happened, and nothing ever triggers the overlay. The user just sits there wondering why the app stopped working. With persistent: true, NativePHP restarts the child process automatically within a few seconds and the timer continues.

This two-layer pattern applies to anything that needs to run when no window is open: timers, background polling, file watchers, scheduled sync tasks. Once you have it working for one thing, you understand the whole model.

Problem 1: The Dual-Database Trap

This one cost me two hours. After I renamed the app, the timer stopped working entirely. No countdown. No overlay. No errors in the logs. Everything appeared fine when I opened the popover.

Here's what was happening.

NativePHP stores its database at:

~/Library/Application Support/{NATIVEPHP_APP_ID}-dev/database/database.sqlite

When I changed NATIVEPHP_APP_ID in .env, NativePHP created a new storage directory with a fresh database file. The old migrations stayed in the old directory. The new database existed at 0 bytes. All cache()->get() and cache()->put() calls silently returned null. The ticker decremented nothing. Nothing happened.

There's a second layer to this: NativePHP doesn't auto-run migrations in dev mode. The file exists but has no tables.

The fix: auto-migrate on every boot in NativeAppServiceProvider:

public function boot(): void
{
    // Auto-migrate ensures the NativePHP database always has tables.
    // Without this, a fresh storage directory silently breaks everything.
    Artisan::call('migrate', ['--force' => true]);
    Artisan::call('db:seed', [
        '--class' => 'ChallengesSeeder',
        '--force' => true,
    ]);

    // ... rest of boot
}

The seeder uses firstOrCreate, so re-running it on every boot is safe.

The broader rule: never change NATIVEPHP_APP_ID without understanding what it does. Your display name is controlled by NATIVEPHP_APP_NAME and can change freely. The app ID determines the storage directory path. Change it and you lose all settings and user data.

To debug this yourself:

sqlite3 ~/Library/Application\ Support/{your-app-id}-dev/database/database.sqlite ".tables"

If you get no output, the database is empty. Copy your local one across and restart.

Problem 2: Not All NativePHP Facades Work From Child Processes

When I added pre-break warning notifications, the code ran without errors. No notification ever appeared.

NativePHP facades communicate with Electron's main process via an HTTP bridge. Some of them work fine from child processes. Others silently fail.

Here's what I found through testing:

Facade	Works from ChildProcess?
`MenuBar::label()`	Yes
`Window::open()`	Yes (with a URL caveat, see next section)
`Screen::displays()`	Yes
`Notification::show()`	No, silently fails

The Notification facade doesn't work from child processes. I tried routing it through a web endpoint as a workaround, where the child process calls an internal HTTP endpoint and that endpoint sends the notification. That also didn't work reliably in my testing.

The pattern I'd suggest before building anything complex with a NativePHP facade: write a quick web route that calls it directly and test in the browser first. If it works there, it will probably work from a child process. If it doesn't work in the browser context, you have a different problem. And if it works in the browser but not in a child process, you've hit this limitation and you'll need to find an alternative approach.

Pre-break notifications are on the v2 list. Once I have more time to investigate the bridge behavior for Notification, I'll add it back in.

Problem 3: URL Resolution in Artisan Context

Window::open() works from child processes, but you have to build the URL yourself.

The default APP_URL in Laravel's .env is http://localhost. NativePHP's PHP server runs on http://127.0.0.1:{dynamic_port}. When the ticker calls Window::open()->route('break.overlay'), it generates http://localhost/break-overlay. Electron tries to load it and gets "Not Found."

The fix: write the actual server URL to a file during boot, then read it in child processes.

// NativeAppServiceProvider::boot()
if (!is_dir(storage_path('app'))) {
    mkdir(storage_path('app'), 0755, true);
}
$port = $_SERVER['SERVER_PORT'] ?? 8100;
file_put_contents(
    storage_path('app/server_url.txt'),
    "http://127.0.0.1:{$port}"
);

Then in the ticker command:

$baseUrl = trim(file_get_contents(storage_path('app/server_url.txt')));
Window::open('break-overlay')->url($baseUrl . '/break-overlay');

Not the most elegant solution, but it works reliably. Since NativeAppServiceProvider::boot() runs before any child process starts, the file is always there when the ticker needs it.

Problem 4: Multi-Screen Overlay

A single Window::open() call opens one window on your primary display. If you have a second monitor, the user can just look over there and keep working.

Screen::displays() returns all connected displays with their bounds. Open one window per display:

$displays = Screen::displays();

foreach ($displays as $i => $display) {
    $bounds = $display['bounds'];
    $windowId = $i === 0 ? 'break-overlay' : "break-overlay-{$i}";

    Window::open($windowId)
        ->url($baseUrl . '/break-overlay')
        ->alwaysOnTop()
        ->titleBarHidden()
        ->position($bounds['x'], $bounds['y'])
        ->width($bounds['width'])
        ->height($bounds['height']);
}

One important gotcha: don't use ->closable(false) on overlay windows. It looks like the right way to prevent accidental dismissal, but it makes Window::close() a no-op. NativePHP calls window.close() under the hood, and when closable is false, Electron ignores it. You'd never be able to close the overlay programmatically.

alwaysOnTop() with titleBarHidden() is enough. The macOS close button is still technically visible, but the user has to make a deliberate choice to click it. That's a different thing from mindlessly swiping away a notification. When the user clicks "I Did It!", the component iterates the same window IDs and closes each one.

Distributing the App

Distributing a NativePHP app outside the Mac App Store is simpler than it sounds. No developer certificate required for direct distribution.

php artisan native:build mac

That produces a .dmg in the dist/ folder. I wrapped this in a build.sh script that handles switching .env to production settings, clearing caches, building assets with npm, running the NativePHP build command, and restoring the dev environment afterward. The whole process takes about 3 minutes on an M2 Mac.

The only thing users have to do after dragging the app to /Applications is run:

xattr -cr /Applications/ForcedBreak.app

This removes the macOS quarantine flag that blocks unsigned apps. It's a standard step for indie Mac apps distributed outside the App Store, safe to run, and you only need to do it once.

Desktop deployment is a different mental model from web apps. There's no server, no zero-downtime concern, no rollback mechanism. You build the .dmg, upload it to GitHub Releases, and users download the new version manually. Much simpler than the deploy pipeline I covered with Scotty and Laravel Envoy, at least for v1.

What I Shipped vs What I Cut

Six features were planned and cut before v1:

Cut feature	Reason
Pre-break notifications	`Notification` facade fails from child processes
Auto-updater	Adds complexity, manual download is fine for now
Onboarding flow	App is self-explanatory
Stats and history charts	Nice to have, not essential for the core concept
Break snooze	Undermines the "forced" nature of the app
iCloud sync	Contradicts the fully offline goal

Every cut made the app ship faster and the core experience sharper. ForcedBreak does one thing: it covers your screens and makes you do a push-up. Everything else is noise until the core concept is proven.

This is the same thing I try to apply when building MVPs for clients. You can read more about how to validate an idea before spending thousands on development, but the short version is: ship the smallest version that tests the assumption. Features can always be added once someone is using it.

What's Next

ForcedBreak v1.0.0 is live now. If you're on an Apple Silicon Mac and want to try it:

Download ForcedBreak v1.0.0 for Apple Silicon →

The source code is on GitHub under MIT. If you find it useful, a star helps others discover it.

For v2, the list is short: get Notification working before breaks (still investigating the child process bridge), add a streak history chart, and build an Intel (x64) version for older Macs.

If you're debugging a stuck NativePHP app, this is the workflow that solved most of my problems:

Check the NativePHP database has tables: sqlite3 ~/Library/Application\ Support/{app-id}-dev/database/database.sqlite ".tables"
Test any NativePHP facade from a web route before using it in a child process
Use curl http://127.0.0.1:8100/dev/force-break to trigger events in the live app, never php artisan tinker
Confirm storage/app/server_url.txt exists and has the correct port

FAQ

Does ForcedBreak work on Intel Macs?

Not yet. The current .dmg is arm64 only (Apple Silicon). An x64 build is on the v2 roadmap.

Can NativePHP build Windows apps?

NativePHP 1.x supports macOS and Linux via Electron. Windows support exists but is less tested in the community. The facades and APIs work the same way in theory.

Why not just build this in Swift?

If you already know Swift, that's valid. NativePHP's advantage is zero context switching. You stay in Laravel, use Eloquent, use the cache, write Blade. For a PHP developer who wants to ship a real desktop app without learning a new language and toolchain, it's the right call.

How large is the final .dmg?

136 MB. That's almost entirely Electron. The actual Laravel app is small, around 500 lines of PHP across models, commands, and Livewire components.

What happens if a user disables all challenges?

The app falls back to the full built-in challenge list. You can disable individual challenges, but the overlay always has something to show. No empty state.

Conclusion

NativePHP is production-ready for focused desktop apps. You don't need Swift. You don't need Objective-C. If you know Laravel, you can ship something real.

The hard part isn't the UI. It's understanding the web context versus the child process context, and what that means for which APIs are available to you. Once that distinction is clear, everything else is just Laravel.

ForcedBreak is available to download on GitHub. If you're building something with NativePHP and hit a wall, get in touch.