Forem: Hafiz

Using Ollama with the Laravel AI SDK: Run Local LLMs for Free

Hafiz — Mon, 18 May 2026 05:11:59 +0000

API costs add up fast during AI development. You prompt an agent 50 times debugging a tool, that's 50 API calls. You run your test suite, that's another batch. Multiply that across a team and you're spending real money before shipping anything.

Ollama solves this cleanly. It runs open-source models locally on your machine (Llama 3, Qwen, Mistral, and dozens more) and the Laravel AI SDK treats it as a first-party provider, exactly like OpenAI or Anthropic. Switch between them with a single environment variable. No code changes, no new packages, no API keys.

This post covers the full setup: installing Ollama, configuring it in the Laravel AI SDK, building agents that run locally, and the dev/production workflow that lets you use Ollama locally while shipping with a cloud provider.

What Ollama Does

Ollama is a lightweight tool that downloads and serves open-source language models locally. Once it's running, it exposes an HTTP API on localhost:11434 that the Laravel AI SDK connects to directly.

There's no internet connection required after the initial model download. No rate limits. No costs per token. If you've built your app with the Laravel AI SDK smart assistant tutorial, your existing agents work with Ollama with a one-line change.

The tradeoff is hardware. Larger models need more RAM and a capable GPU to run at acceptable speeds. But for development, smaller models like Llama 3.2:3B run well on any modern developer machine.

Installing Ollama

macOS:

brew install ollama

Or download the macOS app from ollama.com which installs as a menu bar app and starts automatically.

Linux:

curl -fsSL https://ollama.com/install.sh | sh

Windows:
Download the installer from ollama.com. Ollama runs as a background service after installation.

Once installed, verify it's running:

curl http://localhost:11434
# Should return: Ollama is running

Pulling Models

Download a model with ollama pull:

# General purpose, runs on any machine with 4GB+ RAM
ollama pull llama3.2

# Smaller version, 2GB, good for constrained machines
ollama pull llama3.2:1b

# Strong at code-related tasks, good for Laravel AI agents
ollama pull qwen2.5-coder:7b

# Mistral, fast and capable general model
ollama pull mistral

You can list all downloaded models:

ollama list

And test a model from the terminal before wiring it into Laravel:

ollama run llama3.2 "Explain Laravel service containers in one sentence"

For the artisan commands used in this guide, having at least one model pulled before starting saves debugging time.

Configuring the Laravel AI SDK

The SDK ships with Ollama support out of the box. The only .env addition is:

OLLAMA_API_KEY=

Leave the value blank. Ollama doesn't require authentication for local use, but the SDK expects the variable to exist. Add it to your .env and .env.example.

If Ollama is running on the default port, that's all you need. If you've changed the port or are running Ollama on a remote machine, configure the URL in config/ai.php:

'providers' => [
    // ... other providers

    'ollama' => [
        'driver' => 'ollama',
        'key'    => env('OLLAMA_API_KEY', ''),
        'url'    => env('OLLAMA_URL', 'http://localhost:11434/api'),
    ],
],

And in .env:

OLLAMA_URL=http://localhost:11434/api

The default URL is http://localhost:11434/api so for standard setups you don't need to add this. It works without it.

Using Ollama in Your Agents

Two ways to route an agent to Ollama: set it as the default provider for a specific agent class, or override it per-prompt at runtime.

Per-Agent with PHP Attributes

Add #[Provider] and #[Model] attributes to your agent class:

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

#[Provider(Lab::Ollama)]
#[Model('llama3.2')]
class SupportAgent implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a helpful support agent. Answer questions about our product concisely.';
    }
}

Now every time you prompt this agent, it uses Ollama locally:

$response = SupportAgent::make()->prompt('How do I reset my password?');

return (string) $response;

This is the cleanest pattern for development. You write your agent once with Ollama attributes, build and test locally with no API costs, then change the attributes (or override them via .env) when deploying to production.

Overriding Per-Prompt

For one-off local testing without modifying the agent class:

use Laravel\Ai\Enums\Lab;

$response = SupportAgent::make()
    ->prompt('How do I reset my password?', provider: Lab::Ollama, model: 'llama3.2');

This is useful when you want to quickly compare responses between Ollama and a cloud provider without changing the agent configuration.

The Dev/Production Workflow

The cleanest approach is to set a default provider at the application level in config/ai.php, driven by environment variables:

'default' => [
    'text' => [
        'provider' => env('AI_PROVIDER', 'openai'),
        'model'    => env('AI_MODEL', 'gpt-4o'),
    ],
],

Then in your local .env:

AI_PROVIDER=ollama
AI_MODEL=llama3.2

And in production .env (or your Forge/Vapor environment):

AI_PROVIDER=anthropic
AI_MODEL=claude-sonnet-4-5

Zero code changes between environments. Your agents, tools, and structured output stay identical. Only the provider changes. This works well for any agent that doesn't use PHP attribute overrides; those take precedence over the default config.

For agents with explicit #[Provider] attributes, you'd need to either remove the attributes or use a different approach for environment-based switching. The attribute approach is better for agents that should always use a specific provider (a code review agent that truly needs a smart model in all environments). The default config approach is better for general-purpose agents where Ollama in dev and a cloud model in prod makes sense.

Which Models to Use

Not all models are equal, and the right choice depends on what your agent is doing. Here's a practical guide based on common Laravel AI SDK use cases.

Llama 3.2 (3B or 8B) is the safe default for most use cases. The 3B version runs comfortably on any developer machine with 4GB RAM. The 8B version is noticeably better at following complex instructions but needs 8GB. Good for support agents, document summarisation, and general Q&A. Start here if you're not sure.

Qwen 2.5 Coder (7B) is the right choice for agents that work with code. It outperforms Llama on code generation and review tasks despite similar size. If you're building an agent that analyzes PHP files, generates migrations, or reviews code quality, use this one instead.

Mistral (7B) is fast and reliable for instruction-following tasks. If you need quick responses and the task isn't code-heavy, Mistral is worth trying. It tends to be faster than Llama 3.2 at the same quality level.

Avoid very large models (30B+) for development. They're slow on typical developer machines and the speed penalty makes iteration painful. The quality gap between 7B and 30B matters less in development where you're primarily testing tool calls and output format, not production response quality. Save the big models for your production cloud provider.

A practical setup for a Laravel SaaS would be: use llama3.2:8b for general agents and qwen2.5-coder:7b for any agent touching code. Both run on a 16GB machine without issues. If you're on a 8GB machine, use llama3.2:3b for everything and accept slightly weaker instruction following in exchange for speed.

If you've already built a multi-agent system with the SDK, you can route different sub-agents to different Ollama models the same way you'd assign different cloud models, and the AI SDK overview covers the broader SDK capabilities worth knowing before diving into local model optimization.

Embeddings with Ollama

Ollama also works for local embeddings, which means you can do RAG development with zero API costs:

use Laravel\Ai\Facades\Ai;
use Laravel\Ai\Enums\Lab;

$embedding = Ai::embed(
    'How do I cancel my subscription?',
    provider: Lab::Ollama,
    model: 'nomic-embed-text'
);

Pull the embedding model first:

ollama pull nomic-embed-text

nomic-embed-text is a solid local embedding model that produces 768-dimension vectors. For production RAG you'd swap to OpenAI's text-embedding-3-small or a similar cloud model, but for building and testing your vector search logic, Ollama keeps costs at zero.

What Ollama Doesn't Support

The Laravel AI SDK's Ollama integration covers text generation and embeddings. It does not support image generation, text-to-speech, speech-to-text, or file uploads. If your agents use those capabilities, you'll need a cloud provider for those specific features.

This is usually fine for a dev/production split. Most agent logic (tools, structured output, conversation flow) doesn't depend on images or audio. You can run the core agent logic against Ollama locally, and the multimedia features only come into play in staging or production against cloud providers.

Testing Agents That Use Ollama

One thing to be aware of: when running your test suite, you probably don't want tests making real Ollama calls any more than you'd want real OpenAI calls. The SDK's fake testing utilities work regardless of which provider is configured:

it('responds to password reset questions', function () {
    SupportAgent::fake([
        'To reset your password, visit the login page and click "Forgot password".',
    ]);

    $response = SupportAgent::make()->prompt('How do I reset my password?');

    expect((string) $response)->toContain('password');
});

Faking the agent response means your tests are fast, deterministic, and don't depend on Ollama being installed or running. The agent safety post covers more on keeping agent behavior predictable in tests.

The development workflow then becomes: build and iterate against real Ollama locally, run the test suite with faked responses, deploy with cloud providers in production.

Ollama on a Shared Dev Server

If your team uses a shared development server, you can run Ollama there and point everyone's local Laravel instances at it. Just update OLLAMA_URL in each developer's .env:

OLLAMA_URL=http://your-dev-server:11434/api

Make sure Ollama is configured to accept connections from outside localhost on the server:

OLLAMA_HOST=0.0.0.0 ollama serve

This means one machine does the model serving and your team shares it, without everyone needing to pull and run models locally. Useful if some team members are on constrained hardware.

FAQ

Does Ollama work with Laravel AI SDK agents that use tools?

Yes, but model quality matters more for tool use. Some smaller models handle tool calls inconsistently. Llama 3.2 8B is reliable for tool use. If you're seeing missed or malformed tool calls, try a larger or more capable model.

Can I use Ollama in production?

You can if you have dedicated server hardware with enough RAM and ideally a GPU. Most teams use Ollama for local development and testing, then cloud providers in production. The cost and maintenance overhead of running Ollama in production usually outweighs the savings unless you have high volume and a specific privacy requirement.

What's the difference between Ollama and running models via API?

With Ollama, the model runs on your machine. No data leaves your network. With cloud APIs (OpenAI, Anthropic), your prompts are sent to the provider's servers. For development involving sensitive or proprietary data, Ollama is the better choice.

Do I need a GPU?

No. Most models run on CPU, just more slowly. For development iteration a CPU is fine. Responses take 5-15 seconds depending on model size and your hardware. A GPU drops that to under 2 seconds for 7B models.

Can I use Ollama with the sub-agents pattern?

Yes. Each sub-agent can have its own #[Provider(Lab::Ollama)] and #[Model] attributes. The sub-agents guide covers the full pattern; the Ollama attributes drop in without any other changes.

Start Locally

The setup comes down to four steps: install Ollama, pull a model, add OLLAMA_API_KEY= to your .env, and add #[Provider(Lab::Ollama)] to your agent class. After that, you're running AI locally with no API costs and no rate limits while you build.

In production, switch back to OpenAI or Anthropic by changing the provider attribute or your default config. The rest of your code stays exactly the same.

If you're setting this up for a team or have questions about the dev/production split, get in touch.

Laravel CI/CD with GitHub Actions: Tests, Code Quality, and Deployment

Hafiz — Thu, 14 May 2026 05:08:36 +0000

If you're still deploying Laravel by running git pull on the server and crossing your fingers, this post is for you. And if you've got tests but they only run when you remember to run them locally, this post is for you too.

GitHub Actions gives you a free CI/CD pipeline that runs on every push. For Laravel, a complete pipeline means: style checks, static analysis, your test suite, asset builds, and an automated deploy when everything passes. Set it up once and you never think about it again.

This post builds the complete pipeline from scratch. Every step is explained, the full workflow file appears at the end as a copy-paste block, and the deployment section covers three different approaches depending on how you host.

What the Pipeline Does

Before writing any YAML, here's the full flow:

Code quality checks run first. No point running 400 tests if the formatting is broken. Tests run after. Deployment only triggers on the main branch after everything else passes.

Setting Up the Workflow File

GitHub Actions workflows live in .github/workflows/. Create:

.github/
  workflows/
    ci.yml

Start with the trigger and environment:

name: Laravel CI/CD

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  PHP_VERSION: '8.4'
  NODE_VERSION: '20'

This runs on every push to main or develop, and on every pull request targeting main. Adjust the branches to match your workflow.

Step 1: Checkout and PHP Setup

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ env.PHP_VERSION }}
          extensions: mbstring, xml, ctype, json, bcmath, pdo_sqlite
          coverage: none

shivammathur/setup-php is the community standard for PHP in GitHub Actions. Setting coverage: none is important: it skips loading Xdebug, which meaningfully speeds up the setup step. Only enable coverage if you need coverage reports.

pdo_sqlite is in the extensions list because we'll run tests against an in-memory SQLite database, which is faster and simpler than spinning up a MySQL service container.

Step 2: Install Dependencies with Caching

Composer downloads can take a while. Caching the vendor directory means subsequent runs skip the download if composer.lock hasn't changed:

      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
          path: vendor
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-composer-

      - name: Install Composer dependencies
        run: composer install --no-interaction --prefer-dist --optimize-autoloader --no-progress

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install NPM dependencies
        run: npm ci

actions/setup-node@v4 handles npm caching natively when you pass cache: 'npm'. No separate cache step needed.

composer install flags:

--no-interaction: prevents prompts that would hang the CI runner
--prefer-dist: downloads zip archives instead of git clones, faster
--optimize-autoloader: generates an optimized classmap
--no-progress: cleaner output in CI logs

Step 3: Prepare the Laravel Environment

      - name: Copy environment file
        run: cp .env.example .env.ci

      - name: Generate application key
        run: php artisan key:generate --env=ci

      - name: Set directory permissions
        run: chmod -R 755 storage bootstrap/cache

Create a .env.ci file in your repo with CI-specific settings. The critical part is pointing the database at SQLite:

APP_ENV=testing
APP_KEY=
DB_CONNECTION=sqlite
DB_DATABASE=:memory:
CACHE_DRIVER=array
SESSION_DRIVER=array
QUEUE_CONNECTION=sync
MAIL_MAILER=array

Using DB_DATABASE=:memory: means no file gets created, no cleanup needed, and tests run significantly faster. For the artisan commands that reference the database during testing, this just works.

Step 4: Code Style with Laravel Pint

      - name: Check code style with Pint
        run: vendor/bin/pint --test

The --test flag is essential here. Without it, Pint would fix style issues and commit them. You don't want your CI runner making commits. With --test, it exits with code 1 if issues are found, failing the build.

Pint runs first because it's the cheapest check. If someone pushes without running pint locally, CI catches it immediately without burning time on tests.

Step 5: Static Analysis with Larastan

Larastan is PHPStan configured for Laravel. It understands facades, magic methods, relationships, and request properties that vanilla PHPStan would flag as errors:

composer require nunomaduro/larastan --dev

Create phpstan.neon in your project root:

includes:
    - vendor/nunomaduro/larastan/extension.neon

parameters:
    paths:
        - app
    level: 5
    ignoreErrors:
        - '#Call to an undefined method Illuminate\\Database\\Eloquent\\Builder#'

Level 5 is a solid starting point. It catches undefined method calls and type mismatches without being so strict that you spend more time on type annotations than features. In the workflow:

      - name: Run static analysis
        run: vendor/bin/phpstan analyse --memory-limit=512M --no-progress

--memory-limit=512M prevents PHPStan from hitting PHP's memory limit on large codebases.

Step 6: Run the Test Suite

      - name: Run tests
        env:
          DB_CONNECTION: sqlite
          DB_DATABASE: ':memory:'
        run: vendor/bin/pest --parallel

Passing DB_CONNECTION and DB_DATABASE as env vars here ensures they override whatever's in your .env.ci. The --parallel flag runs test files concurrently across available CPU cores. On a 4-core GitHub Actions runner, parallel mode typically cuts test suite time by 50-60%.

If you're still on PHPUnit, replace pest with phpunit.

Step 7: Build Frontend Assets

      - name: Build assets with Vite
        run: npm run build

This step serves two purposes. It catches import errors or missing dependencies that would break the frontend. And in some deployment setups, you'll want to upload the built assets rather than building on the server.

Deployment Options

This is where setups diverge. The approach depends on how you host. Three options, in order of complexity.

Option A: Laravel Forge (Simplest)

Forge has a deploy hook, a URL you trigger to run your deploy script. Copy it from your Forge site's Deployments tab and store it as a GitHub secret:

  deploy:
    needs: build-and-test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

    steps:
      - name: Trigger Forge deployment
        run: curl -s "${{ secrets.FORGE_DEPLOY_HOOK }}"

The needs: build-and-test line means this job only runs if the previous job passed. if: github.ref == 'refs/heads/main' restricts deployment to the main branch. PRs run tests but don't deploy.

This is the lowest-friction option. Forge handles the deploy script, zero-downtime switching, and restart management on the server side.

Option B: SSH Deployment

For VPS deployments not managed by Forge, use appleboy/ssh-action:

      - name: Deploy via SSH
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/myapp
            git pull origin main
            composer install --no-dev --optimize-autoloader
            php artisan migrate --force
            php artisan config:cache
            php artisan route:cache
            php artisan view:cache
            php artisan queue:restart

Add these secrets to your GitHub repository under Settings > Secrets and variables > Actions:

SSH_HOST: your server's IP or domain
SSH_USER: the deploy user (create a dedicated non-root user)
SSH_PRIVATE_KEY: the private key whose public key is in the server's authorized_keys

php artisan migrate --force is required in non-interactive environments. Without --force, Laravel prompts for confirmation before running migrations in production. The queue restart command signals workers to gracefully restart after code is updated, so they pick up the new code rather than continuing to run old code.

Option C: Scotty (SSH Task Runner)

If you prefer defining your deploy steps as reusable scripts rather than inline YAML, Scotty pairs well with this setup. Scotty uses plain bash syntax and gives you better deploy output than raw SSH scripts. The Scotty vs Envoy comparison covers when it's worth the switch.

You'd SSH into the server and run your Scotty deploy task:

      - name: Deploy with Scotty
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/myapp
            git pull origin main
            ./vendor/bin/scotty run deploy

Managing Secrets and Environment Variables

GitHub Secrets are encrypted environment variables stored at the repository level. They're never exposed in logs, even if a step tries to print them. Add them under Settings > Secrets and variables > Actions.

For a typical Laravel CI/CD setup, you'll need:

Secret	Used in
`FORGE_DEPLOY_HOOK`	Forge webhook URL to trigger deployment
`SSH_HOST`	Server IP or hostname for SSH deployment
`SSH_USER`	SSH username
`SSH_PRIVATE_KEY`	Private key content (the full key, not a path)

For SSH_PRIVATE_KEY, copy the full content of your private key file (typically ~/.ssh/id_rsa or ~/.ssh/id_ed25519). Paste the entire thing into the secret value, including the -----BEGIN and -----END lines.

One mistake that trips people up: the .env.example file in your repo gets copied to .env.ci during the workflow, but any variables that are genuinely secret (API keys, payment credentials) should not be in .env.example. Use GitHub Secrets for those and inject them as environment variables in the relevant step:

      - name: Run tests
        env:
          DB_CONNECTION: sqlite
          DB_DATABASE: ':memory:'
          STRIPE_SECRET: ${{ secrets.STRIPE_SECRET }}
        run: vendor/bin/pest --parallel

Never commit real secrets to your repo. Even in private repositories. The Composer dependency audit post covers how supply chain attacks target credentials left in repositories. The same principle applies to your CI configuration.

Adding a Status Badge

Once your workflow is running, you can add a status badge to your README.md. It shows the current state of your main branch pipeline:

![Laravel CI](https://github.com/{owner}/{repo}/actions/workflows/ci.yml/badge.svg)

Replace {owner} and {repo} with your GitHub username and repository name. The badge updates automatically after each run. Green means everything passed, red means something failed. Useful at a glance and signals to contributors that the project takes CI seriously.

Branch Strategy

If you're building a SaaS product on Laravel, a working CI/CD pipeline from the start saves significant pain later. The SaaS with Laravel and Filament guide covers the broader architecture, and this pipeline slots in as the deployment layer on top of it.

A pipeline that runs identically on every branch isn't optimized. Here's a sensible split:

On pull requests (any branch → main): Run Pint, Larastan, and tests. Block merging if anything fails. No deployment.

On push to main: Run everything. Deploy only if all checks pass.

On push to develop: Run checks and tests. No deployment (or deploy to a staging environment if you have one).

The workflow trigger at the top handles this:

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

And the deployment job's if condition handles the rest:

if: github.ref == 'refs/heads/main' && github.event_name == 'push'

The Complete Workflow File

Here's the full .github/workflows/ci.yml for copy-pasting:

name: Laravel CI/CD

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  PHP_VERSION: '8.4'
  NODE_VERSION: '20'

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ env.PHP_VERSION }}
          extensions: mbstring, xml, ctype, json, bcmath, pdo_sqlite
          coverage: none

      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
          path: vendor
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-composer-

      - name: Install Composer dependencies
        run: composer install --no-interaction --prefer-dist --optimize-autoloader --no-progress

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install NPM dependencies
        run: npm ci

      - name: Copy environment file
        run: cp .env.example .env.ci

      - name: Generate application key
        run: php artisan key:generate --env=ci

      - name: Set directory permissions
        run: chmod -R 755 storage bootstrap/cache

      - name: Check code style with Pint
        run: vendor/bin/pint --test

      - name: Run static analysis
        run: vendor/bin/phpstan analyse --memory-limit=512M --no-progress

      - name: Run tests
        env:
          DB_CONNECTION: sqlite
          DB_DATABASE: ':memory:'
        run: vendor/bin/pest --parallel

      - name: Build assets
        run: npm run build

  deploy:
    needs: build-and-test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

    steps:
      - name: Deploy
        # Choose one of the deployment options above and add it here
        run: curl -s "${{ secrets.FORGE_DEPLOY_HOOK }}"

FAQ

Do I need a paid GitHub plan to use GitHub Actions?

No. GitHub Actions is free for public repositories and includes 2,000 minutes per month for private repositories on free plans. Most Laravel projects fit comfortably within that limit. The ubuntu-latest runner costs 1 minute per minute of usage.

What if I don't have Larastan set up yet?

Remove the static analysis step and add it back once you've configured phpstan.neon. Don't skip Pint. It takes 10 seconds to set up and pays off immediately.

Can I run tests against MySQL instead of SQLite?

Yes. Add a MySQL service container to your job, then update the database env vars. The tradeoff is slower pipelines (MySQL startup adds 15-30 seconds) and the added complexity of service container health checks. SQLite in-memory is the right default for most apps.

Why npm ci instead of npm install?

npm ci installs exactly what's in package-lock.json and fails if there are any discrepancies. npm install can update lockfiles silently. In CI you want reproducibility, so npm ci is correct.

My tests pass locally but fail in CI. Where do I start?

Nine times out of ten it's an environment difference. Check: missing PHP extensions, .env.ci values not matching what tests expect, or missing APP_KEY. Add a debug step early in the workflow that runs php artisan about, which surfaces environment details quickly.

Put It in Place

The workflow file goes in .github/workflows/ci.yml. Add .env.ci to your repo with your CI-specific values. Add secrets to your repository settings. Push to a branch, open a pull request, and watch the checks run.

After that, every PR gets a green or red status before it's merged. Every push to main deploys automatically when it passes. You stop thinking about deployment and start thinking about what you're building.

If you're setting this up for the first time and hit a wall, get in touch and we can work through it together.

Laravel AI SDK Sub-Agents: Build Multi-Agent Systems That Actually Scale

Hafiz — Tue, 12 May 2026 05:03:07 +0000

Taylor Otwell shipped sub-agent support to the Laravel AI SDK. The announcement is short: return an agent from another agent's tools() method and the parent can delegate focused tasks to it. But what it unlocks is significant.

Before this, you could simulate sub-agents by wrapping agent() calls inside a tool's handle() method. It worked, and the multi-agent patterns post covers that approach in detail. But it was a workaround. The agent logic lived inside a tool class, not in a proper Agent class with its own instructions, tools, provider config, and context.

Now sub-agents are first-class citizens. This post covers how the new API works and how to build a realistic multi-agent system with it.

What Sub-Agents Actually Are

A sub-agent is a dedicated Laravel AI Agent class that a parent agent can invoke as a tool. The parent delegates work to it exactly the way it would call any other tool. The difference is that the sub-agent runs with full autonomy: its own instructions, its own tool set, its own provider configuration, and its own isolated context window.

This matters for a few reasons.

Isolation. The parent's conversation history doesn't bleed into the sub-agent. The sub-agent starts fresh with just its own instructions and what the parent passes to it. No context pollution, no token waste from irrelevant history.

Specialization. Each sub-agent is a proper PHP class with its own instructions(), tools(), and optional schema(). You can build a billing specialist, a technical support specialist, and an order lookup specialist, each configured precisely for its job.

Model flexibility. A sub-agent can run on a different provider or model than its parent. Route simple queries to a cheap model. Route complex reasoning to a capable one. The parent doesn't know or care.

The API

Before sub-agents, you'd build a multi-agent orchestrator by wrapping agents in tool classes. The workaround looked roughly like this:

class HandleRefundTool implements Tool
{
    public function description(): string
    {
        return 'Process a refund request for a customer.';
    }

    public function handle(Request $request): string
    {
        // Agent logic stuffed inside a tool class
        return (string) agent()
            ->withInstructions('You are a refund specialist...')
            ->prompt($request['query']);
    }

    public function schema(JsonSchema $schema): array
    {
        return ['query' => $schema->string()->required()];
    }
}

This works, but the agent logic is buried in a tool. There's no proper instructions() method, no tools() method, no structured output. It's a second-class agent.

With sub-agents, you return a real Agent class directly from tools():

class CustomerSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a customer support orchestrator. Analyze the customer\'s 
                message and delegate to the appropriate specialist agent.';
    }

    public function tools(): iterable
    {
        return [
            new BillingAgent,
            new TechnicalSupportAgent,
            new OrderAgent,
        ];
    }
}

Each of those is a full Agent class with its own configuration. The SDK handles the delegation. The parent sees them as tools and calls them when it decides the task fits their domain.

Building a Real Example

Let's build a customer support system for a SaaS product. Users send messages. A parent orchestrator agent decides which specialist handles the response.

Start with the sub-agents. Each is a focused specialist.

BillingAgent

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\ProcessRefund;
use App\Ai\Tools\CheckSubscriptionStatus;
use App\Ai\Tools\UpdatePaymentMethod;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class BillingAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a billing specialist. You handle refund requests, 
                subscription changes, and payment issues. Be concise and 
                solution-focused. Always confirm before processing any changes.';
    }

    public function tools(): iterable
    {
        return [
            new ProcessRefund,
            new CheckSubscriptionStatus,
            new UpdatePaymentMethod,
        ];
    }
}

TechnicalSupportAgent

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\QueryKnowledgeBase;
use App\Ai\Tools\CreateSupportTicket;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class TechnicalSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a technical support engineer. Diagnose issues, 
                search the knowledge base for solutions, and escalate 
                to a ticket when the problem requires engineering attention.';
    }

    public function tools(): iterable
    {
        return [
            new QueryKnowledgeBase,
            new CreateSupportTicket,
        ];
    }
}

OrderAgent

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\LookupOrder;
use App\Ai\Tools\TrackShipment;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class OrderAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are an order specialist. Look up order status, 
                track shipments, and resolve delivery issues.';
    }

    public function tools(): iterable
    {
        return [
            new LookupOrder,
            new TrackShipment,
        ];
    }
}

CustomerSupportAgent (the orchestrator)

<?php

namespace App\Ai\Agents;

use App\Models\User;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class CustomerSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function __construct(public User $user) {}

    public function instructions(): string
    {
        return "You are a customer support orchestrator for {$this->user->company_name}. 
                Analyze incoming messages and delegate to the right specialist:
                - BillingAgent: refunds, subscription changes, payment problems
                - TechnicalSupportAgent: bugs, errors, feature questions  
                - OrderAgent: order status, shipping, delivery

                Don't answer questions yourself. Always delegate to the appropriate 
                specialist and return their response directly.";
    }

    public function tools(): iterable
    {
        return [
            new BillingAgent,
            new TechnicalSupportAgent,
            new OrderAgent,
        ];
    }
}

Prompting it from a controller:

public function handle(Request $request)
{
    $response = CustomerSupportAgent::make($request->user())
        ->prompt($request->input('message'));

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

The parent receives the message, decides which specialist fits, delegates to that Agent, and returns the result. You didn't hardcode routing logic. The model figures out the delegation from the instructions.

Using Different Models Per Sub-Agent

This is where sub-agents clearly beat the old workaround. You can configure a different provider or model on each sub-agent using PHP attributes directly on the class.

Simple billing queries don't need a powerful model. Complex technical debugging does. The official API uses the #[Provider] and #[Model] attributes from Laravel\Ai\Attributes:

use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

#[Provider(Lab::OpenAI)]
#[Model('gpt-4o-mini')]
class BillingAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a billing specialist...';
    }

    public function tools(): iterable
    {
        return [new ProcessRefund, new CheckSubscriptionStatus];
    }
}

#[Provider(Lab::Anthropic)]
#[Model('claude-opus-4-5')]
class TechnicalSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a technical support engineer...';
    }

    public function tools(): iterable
    {
        return [new QueryKnowledgeBase, new CreateSupportTicket];
    }
}

The SDK also ships #[UseCheapestModel] and #[UseSmartestModel] convenience attributes if you'd rather let the provider decide which model to use rather than hardcoding a model string:

use Laravel\Ai\Attributes\UseCheapestModel;
use Laravel\Ai\Attributes\UseSmartestModel;

#[UseCheapestModel]
class BillingAgent implements Agent, HasTools { ... }

#[UseSmartestModel]
class TechnicalSupportAgent implements Agent, HasTools { ... }

The parent orchestrator doesn't know or care which model its sub-agents use. Each runs with its own attributes. This is the practical cost-reduction pattern: cheap models for routine work, capable models only where reasoning depth matters.

Sub-Agents with Structured Output

Sub-agents support structured output the same way regular agents do. If you want the BillingAgent to always return a typed response:

class BillingAgent implements Agent, HasTools, HasStructuredOutput
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a billing specialist. Always return structured results.';
    }

    public function tools(): iterable
    {
        return [new ProcessRefund, new CheckSubscriptionStatus];
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'action_taken' => $schema->string()->required(),
            'resolved'     => $schema->boolean()->required(),
            'message'      => $schema->string()->required(),
        ];
    }
}

The parent receives the structured result from the sub-agent and can use it in its own response or pass it directly back to the caller. This is useful when you need predictable shapes in downstream code, not just a string.

Sub-Agents vs Regular Tools vs agent() Helper

The question you'll hit: when does a sub-agent make sense vs a regular tool vs the agent() helper approach?

A regular tool is right when you're executing a deterministic operation. Looking up a database record, calling an API, running a calculation. No LLM needed in the tool itself; just PHP logic.

The agent() helper (covered in the multi-agent patterns guide) is right for quick inline delegation where you don't need a reusable, testable agent class. It's faster to write but harder to test and reuse.

A sub-agent is right when the delegated work itself requires AI reasoning, has its own set of tools, needs different model config, or is complex enough to warrant its own class with proper instructions. If the delegated task would make sense as a standalone agent on its own, it should be a sub-agent.

A practical rule: if the thing you're delegating to could be independently useful in another context (a BillingAgent, a CodeReviewAgent, an OnboardingAgent), make it a sub-agent. If it's a one-off operation that only makes sense in this specific orchestrator, a regular tool is simpler.

When to Reach for Sub-Agents

Sub-agents shine in three specific scenarios.

Domain routing. You have a broad entry point (customer support, document processing, code review) that needs to delegate to specialists. Each specialist has meaningfully different instructions and tools. The orchestrator shouldn't need to know how each domain works. This is the cleanest use case and the one Taylor's tweet shows directly: a parent agent that routes to a RefundAgent without knowing anything about how refunds actually work.

Cost-optimized workflows. Different tasks warrant different model tiers. Route classification and simple lookups to cheaper models. Reserve the expensive models for tasks that actually need reasoning depth. Sub-agents let you encode that decision in configuration rather than in logic. The billing example above uses gpt-4o-mini for straightforward billing queries but claude-opus-4-5 for technical debugging. You set it once per sub-agent class and it applies everywhere that agent is used.

Large context isolation. If each sub-agent starts with a clean context, you avoid burning tokens on conversation history that's irrelevant to the current task. The parent passes only what the sub-agent needs to know. This is particularly useful when you're also dealing with agent safety concerns, a sub-agent with limited context has a smaller blast radius. A billing sub-agent that only sees the billing-related part of the request can't accidentally act on unrelated data it shouldn't have access to.

When to skip sub-agents. Don't reach for them when a single well-prompted agent handles the task cleanly, or when the overhead of multiple LLM calls is disproportionate to the task's complexity. If your use case is a simple chatbot or a single-domain assistant, sub-agents add latency and cost without adding capability. Start simple. The smart assistant tutorial shows what a well-built single-agent system looks like, and a lot of products never need to go beyond that.

The right question is: does the delegated task benefit from having its own dedicated AI reasoning, its own tools, and isolation from the parent's context? If yes, it's a sub-agent. If it's just a database lookup or a deterministic operation, keep it as a regular tool. The tools and memory tutorial covers the regular tool pattern if you need a refresher on when tools are enough.

Passing Context to Sub-Agents

One thing worth knowing: sub-agents are resolved from the container just like top-level agents. That means you can inject dependencies into them through the constructor.

If your BillingAgent needs access to a specific user's subscription data, pass it through:

class CustomerSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function __construct(public User $user) {}

    public function instructions(): string
    {
        return 'You are a customer support orchestrator...';
    }

    public function tools(): iterable
    {
        return [
            new BillingAgent($this->user),
            new TechnicalSupportAgent,
            new OrderAgent($this->user),
        ];
    }
}

And in the BillingAgent:

class BillingAgent implements Agent, HasTools
{
    use Promptable;

    public function __construct(public User $user) {}

    public function instructions(): string
    {
        $plan = $this->user->subscription?->plan ?? 'free';

        return "You are a billing specialist for a {$plan} plan customer. 
                Customer name: {$this->user->name}. 
                Handle refund requests, subscription changes, and billing issues.";
    }

    public function tools(): iterable
    {
        return [
            new ProcessRefund($this->user),
            new CheckSubscriptionStatus($this->user),
        ];
    }
}

The sub-agent's instructions are dynamically built from the injected user. This is a clean pattern when the specialist's behaviour needs to vary by user context (plan level, account age, support tier). The orchestrator passes the relevant model down to each sub-agent that needs it, keeping the routing logic clean and the specialist logic contained.

Don't over-inject. Sub-agents with too many dependencies become hard to test and understand. The goal is focused specialists. If a sub-agent needs more than one or two injected dependencies, that's often a sign it's trying to do too much.

Testing Sub-Agents

The Laravel AI SDK ships full faking support for agents, confirmed in the official docs: "Fake agents, images, audio, transcriptions, embeddings, reranking, and file stores, so you can ship AI features with real test coverage." This applies to sub-agents the same way it applies to top-level agents.

The general approach is to test each sub-agent in isolation with fake responses, then test the orchestrator separately to verify routing behaviour. Sub-agents are just regular Agent classes, so the same testing patterns from the AI SDK tutorial series apply directly.

For the exact faking API syntax, check the Testing section of the Laravel AI SDK docs. The sub-agent tests follow the same structure as single-agent tests. The only difference is you test each class independently rather than the full orchestration chain at once.

FAQ

Do sub-agents share conversation history with the parent?

No. Each sub-agent has isolated context. The parent passes a task to the sub-agent and the sub-agent works from its own instructions. This is by design and is one of the main benefits of the sub-agent pattern over stuffing agent logic into a tool.

Can a sub-agent have its own sub-agents?

Yes. Since a sub-agent is just a regular Agent class, it can return other Agent classes from its own tools() method. You can nest as deeply as you need, though more than two levels of nesting adds latency and complexity quickly. Most use cases are well-served with one level of sub-agents.

Does this work with streaming?

Yes. Sub-agents support streaming the same way top-level agents do. If the parent agent streams, the response from sub-agents flows through naturally.

What Laravel and PHP versions are required?

The Laravel AI SDK requires PHP 8.2+ and Laravel 12 or 13. Sub-agents are part of the same package, so the same requirements apply.

How does billing work with multiple LLM calls?

Each sub-agent invocation is a separate API call, billed separately at whatever rates your configured provider charges. The cost-optimization angle of using cheaper models for simpler sub-agents is real and worth planning upfront, especially for high-volume endpoints.

Start Building

Sub-agents are a clean solution to the complexity ceiling that single-agent systems eventually hit. The orchestrator stays focused on routing. Each specialist stays focused on its domain. Provider costs stay proportionate to task complexity.

The API is exactly what you'd expect from a Laravel feature: one method change, no boilerplate, full PHP class support. If you've already got agents running in your app, adding sub-agents is a refactor, not a rewrite.

If you're building a multi-agent system and want a second opinion on the architecture, get in touch.

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.