Use Laravel's remember_token as an invalidation signal for saved account-switching state without maintaining a dedicated token or revocation table.

When building a multi-account switcher, the application needs a way to verify whether a previously saved account entry is still valid before switching into it.

Before adding another token or revocation table to your database, consider whether Laravel already maintains state that can serve as the invalidation signal you need.

Laravel's remember_token on the users table already rotates whenever a user logs out, resets their password, or updates their credentials. You can bind saved account entries to this existing token using an HMAC.

Verifying Saved Accounts with remember_token

Store a signature derived from the user ID, current remember_token, and the application key, rather than storing the raw token:

use App\Models\User;
use Illuminate\Support\Facades\Auth;

// 1. Keep an account available for fast switching in session or local state
$account = [
    'id' => $user->id,

    // Tie this entry to the user's current remember_token
    'hash' => hash_hmac(
        'sha256',
        $user->id . '|' . $user->remember_token,
        config()->string('app.key'),
    ),
];

// 2. Later, before switching to the saved account...
$user = User::findOrFail($account['id']);

// Recreate the expected hash from the user's current remember_token
$expected = hash_hmac(
    'sha256',
    $user->id . '|' . $user->remember_token,
    config()->string('app.key'),
);

// If the remember_token changed, the saved account entry is no longer valid
if (! hash_equals($account['hash'], $expected)) {
    // Invalidate or remove the saved entry instead of switching
    return redirect()->route('login')->with('status', 'Session expired. Please log in again.');
}

// Valid: log into the target account
Auth::login($user);

How It Works

• No raw token storage: The raw remember_token is never stored in the account-switching entry; only the derived HMAC hash is retained.
• Tied to current user state: The derived value depends on the user's active remember_token. When the user logs out (Auth::logout()), changes their password, or cycles tokens, Laravel rotates remember_token.
• Automatic invalidation: Once remember_token changes, recomputing the expected hash produces a different value, causing hash_equals() to fail and rejecting the stale switcher entry.
• Timing-safe comparison: hash_equals() prevents timing attacks when validating the stored hash against the expected value.
• Zero extra database tables: Reuses Laravel's built-in users.remember_token column instead of creating and maintaining a separate revocation table.

A practical comparison of Git Submodules and Git Subtrees to help you choose the right strategy for embedding one repository inside another.

When managing projects that share common libraries, documentation sets, microservices, or reusable UI components, you frequently need to embed one Git repository inside another.

Git provides two distinct mechanisms to handle this:

• Git Submodules: Keep the external repository strictly independent; the parent repository only stores a pointer to a specific commit SHA.
• Git Subtrees: Merge the external repository files and commit history directly into a subdirectory of the parent repository.

1. Git Submodules: Independent Pointer

With submodules, the external project remains an entirely separate repository. The parent repository does not store the files directly; it only tracks the submodule URL and a commit hash in .gitmodules.

Main Repository
├── app/
├── config/
└── packages/shared-lib/  → [Pointer to Commit abc1234 in external repo]

Adding a Submodule

# Add external repo into packages/shared-lib
git submodule add https://github.com/example/shared-lib.git packages/shared-lib

# Stage and commit the .gitmodules and submodule reference
git commit -m "Add shared-lib submodule"

Cloning a Repository with Submodules

When team members clone a repository containing submodules, standard git clone leaves submodule directories empty. They must pass the --recurse-submodules flag:

# Clone parent and initialize all nested submodules
git clone --recurse-submodules https://github.com/example/main-app.git

# Or initialize submodules in an existing clone
git submodule update --init --recursive

Updating a Submodule

To pull the latest changes from the submodule remote branch and update the parent commit pointer:

git submodule update --remote packages/shared-lib
git add packages/shared-lib
git commit -m "Update shared-lib to latest commit"

2. Git Subtrees: In-Tree Merged History

With subtrees, the external repository's files are committed directly into your repository. Collaborators can clone, pull, and edit files normally without needing extra Git flags or submodule commands.

Main Repository
├── app/
├── config/
└── packages/shared-lib/  → [Real files + merged commit history]

Adding a Subtree

# 1. Add the external repository as a remote
git remote add shared-lib https://github.com/example/shared-lib.git

# 2. Add the subtree into packages/shared-lib using --squash
git subtree add --prefix=packages/shared-lib shared-lib main --squash

Pulling Upstream Updates

When the external repository publishes new commits, pull them into the parent project:

git subtree pull --prefix=packages/shared-lib shared-lib main --squash

Pushing Local Changes Upstream

If you make modifications inside packages/shared-lib within the parent repo and want to push those commits back to the original repository:

git subtree push --prefix=packages/shared-lib shared-lib main

3. Side-by-Side Comparison

4. Which One Should You Choose?

Choose Git Submodules if:

• The embedded repository has its own strict release cycle and version tags.
• You want the parent repository to lock onto an exact commit hash.
• Team members and CI pipelines are comfortable initializing submodules (--recurse-submodules).
• The embedded project is large and you want to keep repository clone sizes small.

Choose Git Subtrees if:

• You want a friction-free clone experience for team members and contributors.
• You want the external code to behave like ordinary files inside the repository.
• You frequently edit the embedded files directly alongside your application code.
• You want to avoid detached HEAD states and submodule initialization errors in CI.

5. Common Gotchas

Submodule Gotchas:

• Empty Folders on Clone: Forgetting --recurse-submodules leaves submodule folders blank.
• Uncommitted Pointer Updates: Making changes inside the submodule folder without committing the updated reference in the parent repository causes inconsistent states between team members.
• Detached HEAD: By default, submodules check out detached commits rather than tracking branches.

Subtree Gotchas:

• Longer Commands: Subtree syntax (--prefix, --squash, remote names) requires precise terminal commands.
• Repo Bloat: Importing large repositories with long commit histories increases the size of your parent repository.

Summary

• Use Git Submodules when you need strict commit pinning and want the dependency to remain an isolated external project.
• Use Git Subtrees when you want shared code to live directly in your repository with direct cloning for collaborators.

Cache browser binaries with actions/cache to avoid downloading 150MB+ on every CI run.

Playwright and Puppeteer download full browser binaries (Chromium, Firefox, WebKit) during installation. Without caching, every workflow run downloads these binaries from scratch, adding 30-90 seconds of network time depending on the browser set and runner region.

Cache Playwright Browsers

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci

      - name: Cache Playwright browsers
        id: playwright-cache
        uses: actions/cache@v4
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

      - name: Install Playwright Chromium
        if: steps.playwright-cache.outputs.cache-hit != 'true'
        run: npx playwright install chromium

      - name: Install Playwright system deps
        run: npx playwright install-deps chromium

      - name: Run browser tasks
        run: node scripts/generate-screenshots.js

How This Works

1. actions/cache checks for a cached copy of ~/.cache/ms-playwright matching the lock file hash.
2. On a cache hit, browser binaries are restored in ~5 seconds instead of downloaded in ~60 seconds.
3. The install chromium step is skipped entirely on cache hits.
4. System dependencies (install-deps) must run every time because they install OS-level packages (libnss3, libatk1.0, etc.) that are not persisted across runner instances.

Cache Puppeteer Browsers

Puppeteer stores browsers in a different default location. The pattern is the same with a different cache path:

      - name: Cache Puppeteer browsers
        id: puppeteer-cache
        uses: actions/cache@v4
        with:
          path: ~/.cache/puppeteer
          key: puppeteer-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

      - name: Install Puppeteer browser
        if: steps.puppeteer-cache.outputs.cache-hit != 'true'
        run: npx puppeteer browsers install chrome

Cache Key Strategy

The cache key playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }} ensures:

• OS specificity: Browser binaries are platform-specific. A Linux-cached browser will not work on macOS or Windows runners.
• Version tracking: When playwright or puppeteer is upgraded in package-lock.json, the hash changes, and a fresh download is triggered with the correct browser version.

For monorepos or workspaces with multiple lock files, point hashFiles to the relevant lock file:

key: playwright-${{ runner.os }}-${{ hashFiles('apps/web/package-lock.json') }}

Install Only What You Need

Both Playwright and Puppeteer support installing individual browsers. If your workflow only needs Chromium, skip the rest:

# Playwright: install only Chromium (skip Firefox, WebKit)
npx playwright install chromium

# Puppeteer: install only Chrome
npx puppeteer browsers install chrome

Installing all browsers downloads 400MB+ and triples the cache size. Install only what your workflow actually uses.

Combining Cache with Conditional Steps

If some workflow runs do not need a browser at all, combine caching with conditional execution to skip both the cache restore and the install step:

      - name: Detect if screenshots needed
        id: changes
        run: |
          if git diff --name-only HEAD~1 -- 'src/content/**' | grep -q .; then
            echo "needs_browser=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Cache Playwright browsers
        if: steps.changes.outputs.needs_browser == 'true'
        id: playwright-cache
        uses: actions/cache@v4
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

      - name: Install Playwright Chromium
        if: steps.changes.outputs.needs_browser == 'true' && steps.playwright-cache.outputs.cache-hit != 'true'
        run: npx playwright install chromium

This avoids restoring a 150MB cache on runs that will never use a browser.

Key Points

• Browser binaries are often the largest single download in Node.js CI workflows.
• Cache ~/.cache/ms-playwright (Playwright) or ~/.cache/puppeteer (Puppeteer) using actions/cache.
• Include package-lock.json hash in the cache key so version upgrades trigger a fresh download.
• System dependencies (install-deps) must run on every workflow run, even on cache hits.
• Install only the specific browsers your workflow uses to minimize download and cache size.

Compare generated content against existing files before writing. This prevents unnecessary git diffs, cache invalidation, and downstream rebuilds.

Build scripts that generate HTML, JSON, XML, or other output files often write the result unconditionally, even when the content has not changed. This creates problems in CI pipelines: unchanged files get new timestamps, git status reports false modifications, auto-commit steps push empty diffs, and downstream caches are invalidated for no reason.

The Problem

A typical build script writes output directly:

import fs from 'node:fs';

const html = generatePage(data);
fs.writeFileSync('dist/index.html', html);

If generatePage produces the same HTML as the file already on disk, the write is wasted. Worse, it updates the file's modification timestamp, which can trigger:

• git diff reporting the file as changed (if line endings or encoding differ)
• Downstream tools rebuilding dependents of that file
• CI auto-commit steps creating empty or noise-only commits
• CDN or deployment cache invalidation for files that did not actually change

The Fix: Compare Before Writing

Read the existing file, compare it with the new content, and skip the write when they match:

import fs from 'node:fs';
import path from 'node:path';

function writeIfChanged(filePath, content) {
  try {
    const existing = fs.readFileSync(filePath, 'utf-8');
    if (existing === content) return false;
  } catch {
    // File does not exist yet, proceed with write
  }

  fs.mkdirSync(path.dirname(filePath), { recursive: true });
  fs.writeFileSync(filePath, content);
  return true;
}

Usage in a build script:

const pages = generateAllPages(data);
let written = 0;

for (const [filePath, html] of Object.entries(pages)) {
  if (writeIfChanged(filePath, html)) {
    written++;
  }
}

console.log(`Wrote ${written}/${Object.keys(pages).length} files (rest unchanged)`);

On a typical run where 3 out of 300 pages changed, you will see:

Wrote 3/300 files (rest unchanged)

Apply to Every Generated Output

This pattern works for any generated file type:

// HTML pages
writeIfChanged('dist/tips.html', renderTipsPage(tips));

// JSON search indexes
writeIfChanged('public/search-index.json', JSON.stringify(index));

// XML feeds and sitemaps
writeIfChanged('public/feed.xml', renderRssFeed(posts));
writeIfChanged('public/sitemap.xml', renderSitemap(routes));

CI Auto-Commit: Only Commit When Files Actually Changed

When your workflow auto-commits generated files, the incremental write pattern prevents empty commits:

- name: Generate static assets
  run: node scripts/build.js

- name: Commit generated files if changed
  run: |
    git add -A
    if git diff --cached --quiet; then
      echo "No changes to commit"
    else
      git commit -m "chore: regenerate static assets"
      git push
    fi

Without incremental writes, git diff --cached would always detect changes because every file received a fresh write (and potentially a new timestamp or trailing whitespace difference), leading to commits that contain no meaningful content changes.

Key Points

• Always compare new content with existing files before writing in build scripts.
• Skipping unchanged writes prevents false git diff results, unnecessary cache invalidation, and empty auto-commits.
• The try/catch pattern handles missing files gracefully on first builds.
• This optimization compounds in projects with hundreds of generated files, where only a few change per commit.
• Pair with git diff --cached --quiet in CI to avoid committing when nothing actually changed.

File modification timestamps are unreliable in GitHub Actions. Use git diff to detect actual changes and conditionally skip expensive workflow steps.

Many build tools use file modification timestamps (mtime) to decide what needs rebuilding. This works on local machines because the filesystem tracks when each file was last saved.

In GitHub Actions, actions/checkout resets every file's timestamp to the moment of checkout. A project with 500 files will have all 500 stamped with the exact same time, regardless of when each was actually last modified.

Any script comparing timestamps to decide "has this source changed since the last build?" will answer "yes" for everything, triggering full rebuilds on every single run.

The Problem in Practice

Consider a build script that skips PDF generation when the output is newer than the source:

import fs from 'node:fs';

const srcStat = fs.statSync('template.html');
const outStat = fs.statSync('output.pdf');

if (outStat.mtimeMs > srcStat.mtimeMs) {
  console.log('PDF is up to date, skipping');
  process.exit(0);
}

// ... expensive PDF generation with Puppeteer

Locally, this works perfectly. In CI, both files receive the checkout timestamp, so outStat.mtimeMs equals srcStat.mtimeMs, and the skip condition fails every time.

The Fix: Use git diff

Git tracks actual content changes regardless of filesystem timestamps. Replace mtime checks with git diff:

# .github/workflows/build.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # Need parent commit for diff

      - name: Detect changed files
        id: changes
        run: |
          if git diff --name-only HEAD~1 -- 'src/resume/**' 'templates/resume.html' | grep -q .; then
            echo "resume_changed=true" >> "$GITHUB_OUTPUT"
          fi
          if git diff --name-only HEAD~1 -- 'src/content/**' | grep -q .; then
            echo "content_changed=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Generate PDF Resume
        if: steps.changes.outputs.resume_changed == 'true'
        run: node scripts/generate-pdf.js

      - name: Generate Screenshots
        if: steps.changes.outputs.content_changed == 'true'
        run: node scripts/generate-screenshots.js

Why fetch-depth: 2?

By default, actions/checkout performs a shallow clone with fetch-depth: 1, which only contains the latest commit. git diff HEAD~1 requires the parent commit to exist. Setting fetch-depth: 2 fetches exactly enough history for a single-commit diff.

Handling repository_dispatch and workflow_dispatch

When workflows are triggered by repository_dispatch or workflow_dispatch, there is no new commit to diff against. Handle these triggers explicitly:

- name: Detect changed files
  id: changes
  run: |
    EVENT="${{ github.event_name }}"

    # Dispatch events have no associated commit diff
    if [[ "$EVENT" == "repository_dispatch" || "$EVENT" == "workflow_dispatch" ]]; then
      echo "content_changed=true" >> "$GITHUB_OUTPUT"
      exit 0
    fi

    if git diff --name-only HEAD~1 -- 'src/content/**' | grep -q .; then
      echo "content_changed=true" >> "$GITHUB_OUTPUT"
    fi

For repository_dispatch, you often know which subsystem triggered the event based on the event_type. Use that to set only the relevant flags instead of enabling everything.

The Same Pattern Inside Build Scripts

You can also move the git diff check directly into your build scripts:

import { execSync } from 'node:child_process';

function hasSourceChanged(paths) {
  try {
    const diff = execSync(
      `git diff --name-only HEAD~1 -- ${paths.join(' ')}`,
      { encoding: 'utf-8' }
    ).trim();
    return diff.length > 0;
  } catch {
    // If git diff fails (shallow clone, initial commit), assume changed
    return true;
  }
}

if (!hasSourceChanged(['template.html', 'styles/resume.css'])) {
  console.log('No source changes detected, skipping generation');
  process.exit(0);
}

// ... proceed with expensive work

The try/catch fallback is important. On initial commits, force pushes, or misconfigured shallow clones, git diff HEAD~1 will fail. Defaulting to "changed" ensures the build still runs when change detection is unavailable.

Key Points

• actions/checkout sets all file timestamps to the checkout time, making mtime-based incremental logic unreliable in CI.
• Use git diff --name-only HEAD~1 to detect files that actually changed in the latest commit.
• Set fetch-depth: 2 in actions/checkout so the parent commit is available for diffing.
• Handle repository_dispatch and workflow_dispatch triggers separately, since they have no associated commit diff.
• Always fall back to "assume changed" when git diff fails, so builds are never silently skipped due to detection errors.

Keep query bindings out of QueryException messages while retaining access to the actual bindings.

When a database query fails, Laravel's QueryException message can include the values that were bound to the query.

That can be useful while debugging, but it can also mean sensitive values end up in logs, error trackers, or other places where exception messages are stored.

Laravel 13.27 adds an option to mask those bindings in exception messages.

Before

A failed query can produce an exception message containing the actual value:

SQL: select * from `users` where `email` = 'john@example.com'

That means the query's bound values become part of the exception message.

Laravel 13.27

Enable binding masking on your database connection:

// config/database.php

'connections' => [
    'mysql' => [
        // ...

        'mask_bindings_in_exception_messages' => env('DB_MASK_BINDINGS', false),
    ],
];

Now the exception message keeps the placeholder instead of interpolating the binding:

SQL: select * from `users` where `email` = ?

The bindings are still available

Masking the exception message does not remove the bindings from the query.

You can still access them separately through:

$exception->getBindings();

This gives you a useful separation:

Exception message
    ↓
SQL with ? placeholders

Exception bindings
    ↓
Actual values

So your error message can avoid exposing query values while the actual bindings remain available when you explicitly need them.

Why this is useful

This can be especially useful when exceptions are sent to:

• application logs
• error tracking services
• APM systems
• failed job records
• other external monitoring systems

If query values can contain sensitive or personal information, keeping them out of the exception message reduces the chance of accidentally exposing them through your error reporting pipeline.

Takeaway

Laravel 13.27 gives you more control over what appears in QueryException messages.

If you don't need actual query bindings embedded in your exception messages, enable:

'mask_bindings_in_exception_messages' => env('DB_MASK_BINDINGS', false),

You still have access to the bindings separately through getBindings().

Use .git/info/exclude to ignore personal scratch files, local debug scripts, and notes without polluting your team's shared .gitignore file.

When working on a shared repository, you often create temporary files for local testing: a quick scratchpad (scratchpad.md), a temporary debugging script (debug_local.php), or a folder of personal investigation notes (/notes/).

A common developer habit is adding those personal patterns to the project's root .gitignore file. However, .gitignore is committed and tracked in version control. Adding personal, one-off file patterns creates noisy pull request diffs and forces team members to adopt ignore rules they do not need.

Git provides a built-in repository-local ignore file: .git/info/exclude.

Three Scopes of Git Ignore Rules

Understanding where to place an ignore pattern depends on who needs the rule:

.gitignore
  ↓
Shared project rules (Committed and tracked by the entire team)

.git/info/exclude
  ↓
Personal rules for this clone only (Uncommitted, stored inside .git/)

Global Gitignore (~/.gitignore)
  ↓
Personal rules across all repositories on your machine (e.g. .DS_Store, .vscode/)

How to Use .git/info/exclude

Every Git repository includes a .git/info/exclude file by default. Because it lives inside the .git directory, it is never committed or pushed to remote repositories.

Open the file in your preferred editor:

code .git/info/exclude

Add your personal patterns using standard .gitignore syntax:

# Personal scratchpad and experimental scripts
scratchpad.md
debug_local.php
experimental_*.php

# Local private notes
/personal-notes/

# Local custom test database dump
local_dump.sql

After saving the file, running git status will no longer report matching files under "Untracked files", and running git add . will not accidentally stage them.

Important: .git/info/exclude Only Ignores Untracked Files

Like .gitignore, adding a pattern to .git/info/exclude applies strictly to untracked files.

If a file is already tracked in Git history, adding it to .git/info/exclude will not prevent Git from tracking subsequent changes to it.

If you need to stop tracking a file that was previously committed while keeping your local copy on disk, you must remove it from the Git index:

git rm --cached path/to/file.txt

(Note: git rm --cached stages a deletion in Git history for the next commit, so only use it if the file should truly be removed from the shared repository for all contributors).

Decision Guide: Which Ignore Scope to Use

Summary

• Use .gitignore for shared project ignore rules that every team member needs.
• Use .git/info/exclude to ignore personal scratch files and temporary scripts in a specific repository without modifying committed files.
• Use a global Gitignore (core.excludesFile) for operating system and editor artifacts across all repositories on your machine.

Combine response()->streamDownload(), php://output, and query chunking to stream CSV exports directly to the browser without writing temporary files to disk.

Generating CSV exports often involves writing a temporary file to disk (storage_path('app/temp.csv')), returning a download response, and cleaning up the file afterward. This introduces unnecessary disk I/O and risk of disk space exhaustion.

Using response()->streamDownload(), you can write CSV rows directly to php://output in chunked database batches with minimal memory consumption and zero disk usage.

Invokable Controller Example

namespace App\Http\Controllers;

use App\Models\Product;
use Symfony\Component\HttpFoundation\StreamedResponse;

class ExportProductsController
{
    public function __invoke(): StreamedResponse
    {
        return response()->streamDownload(function (): void {
            $output = fopen('php://output', 'w');

            // Header row
            fputcsv($output, ['SKU', 'Name', 'Price']);

            // Stream records in batches using primary-key pagination
            Product::query()
                ->select(['id', 'sku', 'name', 'price'])
                ->chunkById(500, function ($products) use ($output): void {
                    foreach ($products as $product) {
                        fputcsv($output, [
                            $product->sku,
                            $product->name,
                            $product->price,
                        ]);
                    }
                });

            fclose($output);
        }, 'products.csv', [
            'Content-Type' => 'text/csv',
        ]);
    }
}

Key Technical Details

• php://output: A write-only output stream wrapper that writes directly into PHP's output buffer sent to the HTTP client.
• fputcsv(): Handles escaping of commas, quotes, and newlines natively in PHP.
• chunkById(): Paginates by WHERE id > last_seen_id rather than SQL OFFSET, preventing duplicate or skipped records if the table receives new rows during the export.
• Selective Columns: Always pair chunkById() with explicit select(['id', ...]) to hydrate only necessary columns instead of full model instances.

Fix common navigation bar layout shifts, scrollbar jumps, font width shifts, and theme switcher flickering with clean CSS and HTML patterns.

Navigation bars often suffer from subtle layout shifts during page reloads, theme toggles, and tab switches. Combining a few CSS and HTML techniques eliminates these visual jumps entirely.

1. Lock Root Scrollbar Space and Clip Horizontal Overflow

Navigating between long pages with scrollbars and short pages without scrollbars causes horizontal layout jumps. Use scrollbar-gutter: stable on html with overflow-y: auto, and clip horizontal overflow on body with overflow-x: clip.

/* Reserve scrollbar width globally without forcing a scrollbar track on short pages */
html {
  scrollbar-gutter: stable;
  overflow-y: auto;
}

/* Clip wide horizontal overflow without creating a second scroll container */
body {
  overflow-x: clip;
}

scrollbar-gutter: stable reserves scrollbar space on short pages so layout width remains constant across navigations, while overflow-y: auto avoids rendering an empty scrollbar track when scrolling is not needed.

Use overflow-x: clip instead of overflow-x: hidden on body. Traditional overflow-x: hidden forces browsers to evaluate overflow-y as auto, creating a secondary scroll container on body that causes double vertical scrollbars. overflow-x: clip clips horizontal overflow cleanly without creating a scrolling context.

2. Prevent View Transition Scrollbar Flicker

When using native cross-document View Transitions (@view-transition { navigation: auto; }), browsers render outgoing and incoming page snapshots simultaneously. For a single frame during the transition, the viewport height expands, triggering a temporary scrollbar track.

/* Prevent temporary scrollbar flicker during cross-document view transitions */
::view-transition-group(root),
::view-transition-image-pair(root),
::view-transition-old(root),
::view-transition-new(root) {
  overflow: hidden !important;
}

Setting overflow: hidden on the root view transition pseudo-elements clips snapshot layers to viewport bounds, preventing split-second scrollbar popping during page navigations.

3. Lock Navigation Tab Widths with CSS Grid

Active or hovered navigation tabs often expand in width when text becomes bold or changes color contrast, pushing adjacent tabs left or right. Use CSS Grid overlay with an invisible pseudo-element to reserve bold text dimensions upfront.

<nav class="nav-tabs">
  <a href="/dashboard" class="nav-link active">
    <span class="nav-label" data-text="Dashboard">
      <span>Dashboard</span>
    </span>
  </a>
  <a href="/settings" class="nav-link">
    <span class="nav-label" data-text="Settings">
      <span>Settings</span>
    </span>
  </a>
</nav>

.nav-tabs a {
  display: inline-flex;
  align-items: center;
}

/* Grid overlay sizes container to the widest content layer */
.nav-tabs .nav-label {
  display: inline-grid;
  grid-template-areas: "label";
  align-items: center;
  justify-items: center;
}

.nav-tabs .nav-label::after,
.nav-tabs .nav-label > span {
  grid-area: label;
}

/* Invisible bold pseudo-element reserves max text width */
.nav-tabs .nav-label::after {
  content: attr(data-text);
  font-weight: 700;
  visibility: hidden;
  overflow: hidden;
  user-select: none;
  pointer-events: none;
}

4. Pre-render Theme Toggle Icons in HTML

Swapping sun and moon icons via JavaScript after page load causes visual button flickering. Pre-render both icons directly in static HTML and toggle visibility using CSS theme classes.

<button type="button" class="theme-toggle" aria-label="Toggle theme">
  <!-- Sun icon visible in dark mode -->
  <svg class="hidden dark:block" viewBox="0 0 24 24" width="16" height="16">
    <circle cx="12" cy="12" r="5" fill="currentColor"/>
  </svg>

  <!-- Moon icon visible in light mode -->
  <svg class="block dark:hidden" viewBox="0 0 24 24" width="16" height="16">
    <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" fill="currentColor"/>
  </svg>
</button>

5. Use Opacity for Text Contrast Changes

Changing text color from gray to solid black or white triggers font stem-darkening in browser rendering engines, altering glyph widths by fractions of a pixel. Use constant base colors and toggle opacity instead.

/* Active tab */
.nav-link.active {
  color: #0f172a; /* 100% opacity */
}

/* Inactive tab uses same base color with lower opacity */
.nav-link:not(.active) {
  color: rgba(15, 23, 42, 0.6);
}

Key Takeaways

• Reserve scrollbar width on html with scrollbar-gutter: stable and clip horizontal overflow on body with overflow-x: clip.
• Clip View Transition root pseudo-elements with overflow: hidden to prevent split-second scrollbar popping.
• Reserve space for bold tab labels using display: inline-grid and content: attr(data-text).
• Pre-render all theme toggle states in static HTML to eliminate DOM injection flicker.
• Adjust text opacity rather than hex colors to preserve font glyph vector calculations.

Use repository_dispatch to trigger a workflow in a target repository when commits or PRs land in a source repository.

GitHub Actions workflows are scoped to a single repository by default. To run a workflow in another repository after merging a PR or pushing a commit, use GitHub's repository_dispatch API endpoint.

1. Configure the Target Repository Listener

Add repository_dispatch to the on block in the target repository workflow file:

# .github/workflows/build.yml (target repo)
name: Build Site

on:
  push:
    branches:
      - main
  repository_dispatch:
    types: [content-updated]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Build triggered"

2. Configure the Source Repository Dispatcher

In the source repository, add a workflow step that sends a POST request to GitHub's dispatches endpoint:

# .github/workflows/notify.yml (source repo)
name: Notify Target Repo

on:
  push:
    branches:
      - main

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger target build
        env:
          TOKEN: ${{ secrets.WEBSITE_DISPATCH_TOKEN }}
        run: |
          if [ -z "$TOKEN" ]; then
            echo "WEBSITE_DISPATCH_TOKEN is not set"
            exit 1
          fi
          curl --fail --show-error -X POST \
            -H "Authorization: Bearer $TOKEN" \
            -H "Accept: application/vnd.github.v3+json" \
            https://api.github.com/repos/OWNER/TARGET-REPO/dispatches \
            -d '{"event_type": "content-updated"}'

3. Create and Assign the Access Token

1. Create a Fine-Grained Personal Access Token under GitHub Developer Settings.
2. Select the target repository under Repository Access.
3. Set Contents permission to Read and write.
4. Save the token as WEBSITE_DISPATCH_TOKEN in the source repository's Actions Secrets.

Key Considerations

• The event_type string in the payload must match the array value under types: [...].
• Always pass --fail --show-error to curl so HTTP errors exit with code 1 instead of failing silently.
• Fine-grained tokens limit dispatch access strictly to the targeted repository.

Extend Laravel's Blueprint class with custom macros to standardize and reuse common schema columns across database migrations.

Database migrations frequently repeat the same cluster of audit columns (such as created/updated timestamps, soft deletes, and user foreign keys) across multiple tables.

Using Blueprint::macro(), you can bundle these columns into a single reusable helper method.

Register the Macro

Define your custom macro inside AppServiceProvider::boot():

namespace App\Providers;

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Blueprint::macro('auditFields', function (bool $softDeletes = true) {
            $this->timestamps();

            if ($softDeletes) {
                $this->softDeletes();
            }

            $this->foreignId('created_by')->nullable()->constrained('users');
            $this->foreignId('updated_by')->nullable()->constrained('users');
        });
    }
}

Use Across Migrations

Call the macro directly on $table in any migration:

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->text('content');

            // Injects timestamps, softDeletes, and audit user IDs
            $table->auditFields();
        });
    }
};

Key Points

• Consistency: Guarantees identical column types, nullability, and foreign key constraints across all audited tables.
• Execution Timing: Macros expand into standard column definitions when php artisan migrate runs; they do not retroactively alter already-migrated tables.
• Parametric Flexibility: Add arguments to your macro closure (like $softDeletes = true) to adapt column inclusion per table.

Register reusable query methods directly on the Builder so every model gains access without repeating logic.

Laravel's Macroable trait lets you add methods to the Builder at runtime. Register them in a service provider's boot() method and they become available on any query.

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Support\Facades\DB;

// In AppServiceProvider::boot()
Builder::macro('useIndex', function (string $table, string $index) {
    return $this->from(DB::raw("{$table} WITH (INDEX({$index}))"));
});

Now any model can hint a specific index:

use App\Models\Order;

$orders = Order::query()
    ->useIndex('orders', 'orders_status_created_index')
    ->where('status', 'pending')
    ->get();

• Register on Illuminate\Database\Eloquent\Builder for Eloquent-level macros
• The closure receives $this bound to the current builder instance
• Useful for performance hints that aren't covered by the default query builder API
• Note: The WITH (INDEX(...)) syntax used above is specific to Microsoft SQL Server (T-SQL). MySQL uses FORCE INDEX(...) and PostgreSQL relies on the query planner (no direct index hints). Adjust the macro body to match your database engine.

Placing a return statement inside a try-catch finally block silently overrides exceptions and previous return statements.

A return statement inside a finally block executes regardless of whether an exception was thrown or caught. It silently discards pending exceptions and overwrites return values from try or catch blocks.

// What does guess() return? It returns 'finally'!
function guess(): string
{
    try {
        throw new Exception('Something went wrong');
    } catch (Exception $e) {
        return 'catch';
    } finally {
        return 'finally'; // Silently overrides the catch return!
    }
}

// GOOD: Use finally strictly for resource cleanup
function processOrderClean(): bool
{
    try {
        return true;
    } finally {
        $this->cleanupLocks();
    }
}

• Return inside finally discards thrown exceptions without logging them
• Overwrites return values calculated in try or catch blocks
• Use finally strictly for resource cleanup like closing file handles or releasing locks

Use Rector rules to automatically convert immutable DTOs and value objects into native PHP 8.2 readonly classes.

Manually adding readonly keywords across dozens of data transfer objects (DTOs) and value objects is repetitive.

Rector automates upgrading class declarations across your codebase using AST refactoring.

Configuration

Register ReadOnlyClassRector in rector.php:

// rector.php
use Rector\Config\RectorConfig;
use Rector\Php82\Rector\Class_\ReadOnlyClassRector;

return RectorConfig::configure()
    ->withRules([
        ReadOnlyClassRector::class,
    ]);

What It Refactors

// Before Rector (individual readonly properties):
class UserData
{
    public function __construct(
        public readonly string $name,
        public readonly string $email,
    ) {}
}

// After Rector (PHP 8.2+ native readonly class):
readonly class UserData
{
    public function __construct(
        public string $name,
        public string $email,
    ) {}
}

Key Benefits

• Compiler-Level Immutability: Enforces that all properties cannot be modified after instantiation.
• Cleaner Constructors: Removes repetitive readonly property declarations in favor of a single class-level keyword.
• Safe Automation: Rector verifies property usage before promoting classes, ensuring mutable entities are not broken.

When you expect exactly one matching record, use sole() instead of firstOrFail(). It guards against multiple records by throwing MultipleRecordsFoundException.

When querying unique records, firstOrFail() silently returns the first record even if multiple records match due to data integrity issues. sole() makes sure exactly one record exists.

// Throws ModelNotFoundException if 0, MultipleRecordsFoundException if 2+
$user = User::where('verification_token', $token)->sole();

• Asserts that exactly one record matches criteria
• Catches data integrity anomalies before bad states propagate
• Throws explicit MultipleRecordsFoundException

Use Laravel's Prohibitable trait on custom Artisan commands to selectively block AI agents from running destructive domain operations.

While DB::prohibitDestructiveCommands() protects core database migrations, custom Artisan commands (such as purging inactive tenants or deleting old records) require their own guard so AI coding agents do not execute them automatically.

1. Add Prohibitable to the Command Class

Add the Illuminate\Console\Prohibitable trait to your custom command:

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Console\Prohibitable;

class DeleteInactiveUsersCommand extends Command
{
    use Prohibitable;

    protected $signature = 'users:purge-inactive';

    public function handle(): int
    {
        if ($this->isProhibited()) {
            $this->error('This command is prohibited in this environment.');
            return Command::FAILURE;
        }

        // Execution logic...
        return Command::SUCCESS;
    }
}

2. Prohibit in AppServiceProvider

Prohibit execution when an AI coding agent is detected:

namespace App\Providers;

use App\Console\Commands\DeleteInactiveUsersCommand;
use Illuminate\Support\ServiceProvider;
use Laravel\AgentDetector\Facades\AgentDetector;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Humans can run locally; AI agents are blocked
        DeleteInactiveUsersCommand::prohibit(AgentDetector::detect()->isAgent);
    }
}

Key Points

• Trait Mechanics: Adding use Prohibitable; provides both the static ::prohibit() configuration method and the instance ->isProhibited() check.
• Granular Control: Protects destructive application-specific commands without blanket blocking all Artisan tools.

Laravel's AgentDetector detects whether an AI coding agent is interacting with your app, and PAO optimizes CLI output for agents.

AI coding agents (Cursor, Claude Code, Devin) are now part of regular development workflows. Laravel provides first-party tools to detect agents and optimize terminal output for LLM parsing.

Agent Detection

use Laravel\AgentDetector\Facades\AgentDetector;

$detection = AgentDetector::detect();

if ($detection->isAgent) {
    // Inspect agent name (e.g. 'claude-code', 'cursor', 'devin')
    logger()->info('AI agent session', ['agent' => $detection->name]);
}

How PAO Works

• First-Party: Ships with PAO (laravel/pao) included by default in new Laravel applications.
• Output Optimization: PAO automatically switches verbose Artisan CLI output into compact JSON when an agent is detected.
• Human Invariant: Human developers see standard terminal formatting with zero workflow change.

cursor() hydrates single model instances sequentially using database cursors; lazy() streams records in chunks backed by LazyCollection.

When iterating millions of records, get() exhausts PHP memory limits. cursor() uses PDO cursors to fetch records one by one, while lazy() queries records in chunks while exposing a fluent LazyCollection.

use App\Models\User;

// Cursors: single query, streams 1 instance at a time (lowest memory)
foreach (User::where('active', false)->cursor() as $user) {
    $user->archive();
}

// Lazy: queries in chunks of 1000 under the hood, provides LazyCollection API
User::where('active', false)->lazy(1000)->each->archive();

• cursor() uses a single database connection cursor for minimal RAM usage
• lazy() executes chunked subqueries under the hood and allows collection chaining
• Both prevent loading full datasets into PHP memory at once

Understand offset vs keyset pagination when processing large datasets to avoid missing records during updates.

Updating records inside chunk() modifies the result set, causing offset pagination to skip every second chunk. Use chunkById() or lazyById() when updating query columns.

use App\Models\User;

// BAD when updating filtered column: skips records due to offset shift!
User::where('processed', false)->chunk(100, function ($users) {
    $users->each->update(['processed' => true]);
});

// GOOD: Uses primary key comparison (id > last_id) to avoid skipping
User::where('processed', false)->chunkById(100, function ($users) {
    $users->each->update(['processed' => true]);
});

• chunk() uses OFFSET pagination (vulnerable to skipping if queried fields change)
• chunkById() uses keyset pagination (WHERE id > last_id), safe for updates
• lazyById() provides the same keyset safety wrapped in a LazyCollection

Hiding buttons in Blade or Vue does not restrict access. Always enforce authorization policies in controller or request layers.

Hiding an edit button using @can or v-if only modifies visual presentation. Attackers can submit HTTP requests directly to backend endpoints. Always enforce authorization logic in backend controllers or form requests.

// Blade UI (Visual convenience only)
@can('update', $post)
    <a href="{{ route('posts.edit', $post) }}">Edit Post</a>
@endcan

// Controller Action (Actual Security Layer)
public function update(UpdatePostRequest $request, Post $post)
{
    $this->authorize('update', $post); // Enforces server-side security
    $post->update($request->validated());
}

• UI directive checks like @can are user-experience features, not security guards
• Always enforce $this->authorize() or Policy checks in backend controllers
• Prevents unauthorized HTTP request payload tampering

Use DB::afterCommit() to defer job dispatching until surrounding database transactions complete successfully.

Dispatching queue jobs inside active DB transactions can trigger race conditions where background workers run before the transaction commits. DB::afterCommit() delays side effects until commit finishes.

use Illuminate\Support\Facades\DB;
use App\Jobs\ProcessPayment;

DB::transaction(function () use ($order) {
    $order->save();
    
    // Guarantees worker receives committed database records
    DB::afterCommit(fn () => ProcessPayment::dispatch($order));
});

• Prevents race conditions where queue workers query uncommitted database rows
• Discards callbacks automatically if transaction rolls back
• Can be set on jobs using public $afterCommit = true;

In Laravel and Pest tests, assertDatabaseHas() natively queries nested JSON properties using arrow syntax and accepts backed Enum instances directly.

Testing JSON attributes or PHP backed enums in database assertions requires no manual casting, JSON encoding, or ->value calls.

assertDatabaseHas() natively serializes backed enums and translates arrow notation into database JSON queries.

Code Examples

use App\Enums\UserRole;

// In Pest tests:
assertDatabaseHas('users', [
    'role' => UserRole::Maintainer, // Serializes backed enum automatically
    'settings->theme' => 'dark',    // Queries nested JSON key
    'settings->notifications->email' => true,
]);

// In PHPUnit tests:
$this->assertDatabaseHas('users', [
    'role' => UserRole::Maintainer,
    'settings->theme' => 'dark',
]);

Key Benefits

• Enum Serialization: Passes backed enum instances directly without manual ->value extraction.
• Nested JSON Traversal: Arrow syntax (settings->theme) queries database JSON paths across MySQL, PostgreSQL, and SQLite.
• Framework Agnostic: Works identically in both Pest test functions and PHPUnit test cases.

Enable the Tia Engine in Pest to only re-run tests affected by your latest code changes while replaying cached results for unaffected tests.

Running full test suites on every minor change slows down local feedback loops. While --dirty only checks if test files themselves changed, Pest's Tia Engine analyzes code coverage mapping to identify tests that execute the actual application lines you modified.

1. CLI Usage

Run Pest with the --tia flag:

# Run tests with Test Impact Analysis enabled
./vendor/bin/pest --parallel --tia

On the initial run, Pest records a dependency graph of which tests touch which files. On subsequent runs, it only re-runs affected tests and replays cached results for the rest.

2. Configuration in tests/Pest.php

To avoid typing --tia on every run, configure the Tia Engine fluently inside tests/Pest.php:

// tests/Pest.php

pest()->tia()
    ->locally()   // Run TIA on every local invocation; skipped automatically in CI
    ->baselined() // Fetch shared baseline from CI when no local graph exists
    ->filtered(); // Narrow test runner to affected test files only

• locally(): Recommended. Activates TIA for every local pest run without requiring the --tia flag. In CI (or with --ci), TIA is skipped automatically so pipelines run the full suite.
• always(): Alternative to locally(). Enforces TIA across all environments including CI.
• baselined(): Downloads the shared CI baseline artifact so developers replay immediately on fresh clones.

Key Rules & Requirements

• Coverage Driver: Requires a code coverage driver (PCOV or Xdebug) to build the dependency graph.
• Cosmetic Invariant: Whitespace changes, comments, and docblock edits produce identical hashes, executing zero tests.
• CLI Overrides: Bypass or force TIA anytime using --tia or --no-tia.

Prevent catastrophic accidents like db:wipe or migrate:fresh in production using Laravel's Prohibitable trait and DB::prohibitDestructiveCommands().

Accidentally running migrate:fresh or db:wipe on a production database is catastrophic.

Laravel provides DB::prohibitDestructiveCommands() to block dangerous commands when running in production.

AppServiceProvider Configuration

Add the call inside your AppServiceProvider::boot() method:

namespace App\Providers;

use Illuminate\Support\Facades\DB;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Block destructive migration commands when in production
        DB::prohibitDestructiveCommands(
            $this->app->isProduction()
        );
    }
}

Commands Protected

When prohibited, attempts to run the following commands fail with an exit error code:

• php artisan db:wipe
• php artisan migrate:fresh
• php artisan migrate:refresh
• php artisan migrate:reset

Key Points

• Zero Accidental Overrides: Even passing the --force flag cannot bypass a prohibited command.
• Environment Driven: Passing $this->app->isProduction() keeps local, staging, and automated testing environments fully functional.

strip_tags() removes HTML elements but fails to sanitize inline attributes or malformed HTML payload vectors. Use HTMLPurifier for rich text input.

A common security misconception in PHP is relying on strip_tags() to sanitize user-submitted rich text. It allows attribute payloads like onload= or javascript: URIs through if allowed tags are specified.

use HTMLPurifier;

$purifier = new HTMLPurifier();
$cleanHtml = $purifier->purify($input);

• strip_tags() does not validate tag attributes or execution vectors
• Always escape plain text with e() or Blade's {{ $var }}
• For user-submitted rich text, use reliable HTML sanitizers like HTMLPurifier

Process complex data sequences or multi-stage order checks through Laravel's built-in Pipeline facade to replace massive controller methods.

When processing multi-stage workflows (such as order checkout validation or user onboarding steps), controller actions frequently accumulate deeply nested if statements.

Laravel's Pipeline facade passes an object sequentially through dedicated pipe classes.

The Pipeline Runner

use App\Models\Order;
use App\Pipes\ApplyCoupon;
use App\Pipes\CalculateTax;
use App\Pipes\VerifyStock;
use Illuminate\Support\Facades\Pipeline;

$order = Pipeline::send($draftOrder)
    ->through([
        VerifyStock::class,
        ApplyCoupon::class,
        CalculateTax::class,
    ])
    ->thenReturn();

Anatomy of a Pipe Class

Each pipe implements a handle() method accepting the passable object and a $next closure:

namespace App\Pipes;

use App\Models\Order;
use Closure;

class ApplyCoupon
{
    public function handle(Order $order, Closure $next)
    {
        if ($order->coupon_code) {
            $order->discount = 15.00;
        }

        // Pass the modified object to the next pipe in sequence
        return $next($order);
    }
}

Key Benefits

• Single Responsibility: Each step is an isolated class with one clear focus.
• Easy Reordering: Add, remove, or reorder pipeline stages without touching adjacent logic.
• Testability: Test individual pipeline steps independently with unit tests.

Use a custom Rector rule to automatically strip noisy inline comments and empty docblocks across your codebase while preserving essential PHPDoc annotations.

Codebases often accumulate redundant comments over time: commented-out legacy code, obvious explanations (// set user name), or empty boilerplate docblocks generated by older IDE templates.

Manually reviewing and removing thousands of stale comments across hundreds of files is time-consuming. Using Rector, you can define an AbstractRector rule that strips non-essential comments while retaining critical PHPDoc annotations such as @param, @return, and @throws.

The Rector Implementation

namespace App\Rector;

use PhpParser\Comment;
use PhpParser\Comment\Doc;
use PhpParser\Node;
use Rector\Rector\AbstractRector;
use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;

final class RemoveUnnecessaryCommentsRector extends AbstractRector
{
    // Whitelist specific comment strings or tags you want to keep
    private const ALLOWED_PATTERNS = [
        '@todo',
        '@var',
    ];

    public function getNodeTypes(): array
    {
        return [Node::class];
    }

    public function refactor(Node $node): ?Node
    {
        $comments = $node->getComments();

        if ($comments === []) {
            return null;
        }

        $filtered = [];
        $changed = false;

        foreach ($comments as $comment) {
            if ($comment instanceof Doc) {
                $cleaned = $this->cleanDocBlock($comment);

                if ($cleaned !== $comment->getText()) {
                    if ($cleaned !== '') {
                        $filtered[] = new Doc($cleaned);
                    }
                    $changed = true;
                } else {
                    $filtered[] = $comment;
                }
                continue;
            }

            // Check if regular comment contains allowed keywords
            if ($this->isAllowed($comment->getText())) {
                $filtered[] = $comment;
            } else {
                $changed = true;
            }
        }

        if (! $changed) {
            return null;
        }

        $node->setAttribute('comments', $filtered);

        return $node;
    }

    private function cleanDocBlock(Doc $doc): string
    {
        $lines = preg_split('/\R/', $doc->getText());
        $tags = [];

        foreach ($lines as $line) {
            $line = trim(preg_replace('/^\s*\*\s?/', '', $line));

            if ($line === '') {
                continue;
            }

            // Preserve standard PHPDoc annotations (@param, @return, @throws, etc.)
            if (str_starts_with($line, '@')) {
                $tags[] = $line;
            }
        }

        if ($tags === []) {
            return '';
        }

        return "/**\n * " . implode("\n * ", $tags) . "\n */";
    }

    private function isAllowed(string $text): bool
    {
        foreach (self::ALLOWED_PATTERNS as $allowed) {
            if (str_contains($text, $allowed)) {
                return true;
            }
        }

        return false;
    }

    public function getRuleDefinition(): RuleDefinition
    {
        return new RuleDefinition('Remove redundant inline comments while retaining essential PHPDoc tags', [
            new CodeSample(
                <<<'CODE'
                // Initialize user model
                $user = new User();
                CODE
                ,
                <<<'CODE'
                $user = new User();
                CODE
            ),
        ]);
    }
}

Registering in rector.php

Add the custom rule to your project's Rector configuration:

use App\Rector\RemoveUnnecessaryCommentsRector;
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withRules([
        RemoveUnnecessaryCommentsRector::class,
    ]);

Run the refactoring dry-run to preview changes:

vendor/bin/rector process --dry-run

Summary

• Use AST-based comment manipulation in Rector to systematically clean comment noise across large codebases.
• The rule strips redundant plain comments (// comment) while keeping meaningful docblock tags (@param, @return, @throws).
• Easily extensible to whitelist specific tags or maintenance markers such as @todo.

Use the $deleteWhenMissingModels property on queued jobs to silently discard jobs if their referenced database records were deleted before execution.

When an Eloquent model is passed to a queued job and a user deletes that record before the worker picks up the job, Laravel throws a ModelNotFoundException, causing the job to fail and populate the failed_jobs table.

Setting $deleteWhenMissingModels = true instructs the worker to delete the job silently.

Enabling on Job Classes

namespace App\Jobs;

use App\Models\Post;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class GeneratePostThumbnailJob implements ShouldQueue
{
    use InteractsWithQueue, Queueable, SerializesModels;

    // Silently delete job if the Post model was deleted from database
    public bool $deleteWhenMissingModels = true;

    public function __construct(public Post $post) {}

    public function handle(): void
    {
        // Process thumbnail
    }
}

Summary

• Prevents false-alarm errors in failed_jobs and error tracking tools (Sentry, Bugsnag).
• Silently purges queued tasks when parent models are deleted.
• Standard property provided by the SerializesModels trait.

Use withoutRelations() when passing models to queue jobs to prevent large in-memory relationship graphs from serializing into queue storage.

When dispatching queue jobs that accept an Eloquent model instance, Laravel serializes the model. If the model had dozens of nested relationships eager-loaded in the controller, all those related models are serialized into the queue payload (Redis / Database), causing massive payload bloat.

Calling withoutRelations() strips loaded relations before dispatching.

Basic Usage

use App\Jobs\GenerateUserInvoiceJob;

public function checkout(Order $order)
{
    // $order has heavy loaded relations (items, customer, history)

    // Strips loaded relations so only the primary key is serialized
    GenerateUserInvoiceJob::dispatch($order->withoutRelations());
}

In Job Class Constructors

Alternatively, clean relations in the constructor:

namespace App\Jobs;

use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\SerializesModels;

class ProcessOrderJob implements ShouldQueue
{
    use Queueable, SerializesModels;

    public Order $order;

    public function __construct(Order $order)
    {
        $this->order = $order->withoutRelations();
    }
}

Summary

• Reduces serialized queue payload sizes from megabytes to bytes.
• Prevents Redis command size exceeded or long text column limits in jobs tables.
• Queue workers re-hydrate fresh relationships when needed.

Use queue:work with appropriate sleep configuration or Redis blocking pops to reduce database CPU polling overheads.

Queue workers set to poll databases without sleep configs execute continuous SELECT queries, driving database CPU usage up. Configure appropriate sleep intervals or use Redis queue drivers.

# Wait 3 seconds when queue is empty before polling again
php artisan queue:work --sleep=3 --tries=3 --timeout=90

• --sleep=3 pauses worker polling when no jobs are available
• Reduces CPU usage and database query loads on idle queue workers
• Redis queue driver uses blocking pop operations for instant zero-polling dispatch

The --stop-when-empty-for option keeps queue workers alive for a specific grace period after the queue empties, preventing rapid process churn during bursty workloads.

Running php artisan queue:work --stop-when-empty in serverless environments or container auto-scalers terminates the worker process immediately when no jobs remain. If new jobs arrive seconds later, new processes must spin up continuously.

The --stop-when-empty-for option adds a configurable idle timeout:

# Stops worker immediately once queue is empty
php artisan queue:work --stop-when-empty

# Keeps worker running for 60 idle seconds before exiting
php artisan queue:work --stop-when-empty-for=60

• Prevents process start/stop churn during intermittent job spikes
• Ideal for AWS ECS, Kubernetes HPA, and Serverless worker instances
• Retains database connection pooling while waiting for trailing jobs

Replace whereYear() and whereMonth() on large database tables with whereBetween() date ranges to enable SQL index lookups.

Using whereYear('created_at', 2026) forces database engines (MySQL, PostgreSQL) to wrap the column in an SQL function (WHERE YEAR(created_at) = 2026).

Wrapping indexed columns in functions invalidates database B-Tree indexes, causing full table scans.

The Problem with whereYear()

// ❌ SLOW: SQL function YEAR(created_at) disables database index!
$orders = Order::whereYear('created_at', 2026)->get();

The High-Performance Solution: whereBetween()

Using explicit timestamp boundaries enables the database engine to perform fast range index lookups:

use Carbon\Carbon;

$startOfYear = Carbon::create(2026, 1, 1)->startOfDay();
$endOfYear = Carbon::create(2026, 12, 31)->endOfDay();

// ✅ FAST: Uses standard B-Tree range index lookup
$orders = Order::whereBetween('created_at', [$startOfYear, $endOfYear])->get();

Monthly Queries Example

// Querying a specific month (e.g. October 2026)
$orders = Order::whereBetween('created_at', [
    now()->startOfMonth(),
    now()->endOfMonth(),
])->get();

Summary

• SQL date functions (YEAR(), MONTH()) prevent query optimizers from using column indexes.
• whereBetween('created_at', [$start, $end]) utilizes B-Tree indexes for fast range scans.
• Essential optimization for tables with hundreds of thousands of records.

Use Cache::memo() to combine persistent cache stores with per-request memory caching, preventing repetitive network roundtrips during a single HTTP request.

Calling Cache::get('key') multiple times in a single request still incurs a Redis network roundtrip or database query each time.

Cache::memo() wraps your configured cache store with an in-memory array cache for the duration of the current request:

use Illuminate\Support\Facades\Cache;

// Standard Cache: 3 Redis network roundtrips
$permissions = Cache::get('user.permissions'); // Redis query
$permissions = Cache::get('user.permissions'); // Redis query
$permissions = Cache::get('user.permissions'); // Redis query

// Cache::memo(): 1 Redis query, subsequent calls read from memory
$permissions = Cache::memo()->get('user.permissions'); // Redis query
$permissions = Cache::memo()->get('user.permissions'); // In-memory hit
$permissions = Cache::memo()->get('user.permissions'); // In-memory hit

// Mutations automatically sync the persistent store and invalidate local memory
Cache::memo()->put('user.status', 'active');
Cache::memo()->increment('page.views');

// Works with specific cache stores
Cache::memo('redis')->remember('expensive-report', 3600, fn () =>
    $this->buildReport()
);

• Eliminates redundant cache store queries during heavy request lifecycles
• In-memory values reset automatically at the end of the HTTP request
• Mutation methods (put, increment, forget) keep memory and storage in sync

Use virtualAs() and storedAs() in migrations to create generated database columns for high-speed indexing on JSON attributes.

Querying deep JSON attributes (such as WHERE JSON_EXTRACT(metadata, '$.country') = 'US') cannot use standard B-Tree column indexes, resulting in slow full table scans on large tables.

Generated columns extract values from JSON or string expressions and allow standard indexing.

Creating Generated Columns in Migrations

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('orders', function (Blueprint $table) {
            $table->id();
            $table->json('payload');

            // Virtual column computed on read (MySQL / PostgreSQL / SQLite)
            $table->string('currency')->virtualAs("payload->>'$.currency'");

            // Stored column saved physically on disk for indexing
            $table->decimal('total_amount', 10, 2)->storedAs("payload->>'$.total'");

            // Add standard fast B-Tree index on the generated column!
            $table->index('total_amount');

            $table->timestamps();
        });
    }
};

Querying Naturally in Eloquent

// Fast indexed query on the generated column!
$largeOrders = Order::where('total_amount', '>', 500)->get();

Summary

• virtualAs(): Computes value dynamically during reads without disk storage.
• storedAs(): Computes value on insert/update and stores on disk, allowing standard B-Tree index creation.
• Accelerates heavy queries on JSON payloads by 10x–100x.

Interrupt long-running synchronous PHP callables on any operating system using PHP tick declarations and tick callback functions without requiring the pcntl extension.

In command-line scripts, background jobs, or plugin execution engines, you may need to impose a hard execution timeout on a closure or callable. The standard Unix approach uses pcntl_alarm() or pcntl_fork(), but the pcntl extension is unavailable on Windows environments and in certain shared hosting setups.

Using PHP ticks (declare(ticks=1)), you can implement a cross-platform execution watchdog that monitors elapsed execution time and interrupts runaway code.

The TimeoutGuard Implementation

declare(ticks=1);

class TimeoutException extends Exception {}

class TimeoutGuard
{
    public static function run(callable $callback, float $seconds): mixed
    {
        $start = microtime(true);

        // Tick handler: checks elapsed time on every low-level tick event
        $watchdog = function () use ($start, $seconds): void {
            if ((microtime(true) - $start) > $seconds) {
                throw new TimeoutException("Execution interrupted: timeout of {$seconds}s exceeded");
            }
        };

        register_tick_function($watchdog);

        try {
            return $callback();
        } finally {
            unregister_tick_function($watchdog);
        }
    }
}

Usage Example

Wrap any synchronous task inside TimeoutGuard::run():

try {
    $result = TimeoutGuard::run(function () {
        // Heavy computational task or complex regex matching
        for ($i = 0; $i < 1e7; $i++) {
            sqrt($i);
        }
        return 'Completed';
    }, 0.5); // 500ms limit

    echo "Task finished: {$result}
";
} catch (TimeoutException $e) {
    echo "Execution timed out: " . $e->getMessage() . "
";
}

How It Works

1. declare(ticks=1): Tells the PHP parser to emit a tick event after every single low-level statement execution.
2. register_tick_function(): Registers a lightweight watchdog callback evaluated on each tick.
3. microtime(true) Check: Compares the current timestamp against the initial start time. If the elapsed time exceeds the threshold, it throws a TimeoutException.
4. finally Cleanup: Always unregisters the tick handler when execution finishes (or errors) to avoid overhead in subsequent operations.

When to Use This Pattern

• User-submitted Script Sandboxing: Enforcing computation budgets on dynamic expressions or formula evaluation.
• Cross-Platform CLI Tools: Running timeout-protected commands on both Windows and Linux without conditional pcntl checks.
• Complex Regex Matching: Preventing catastrophic backtracking (ReDoS) from hanging PHP worker processes.

Summary

• Use declare(ticks=1) and register_tick_function() to create a zero-dependency execution timeout watchdog.
• Works across all operating systems including Windows where pcntl is unavailable.
• Always unregister tick callbacks inside a finally block to prevent memory leaks and unwanted background invocation.

Use DB::whenQueryingForLongerThan() to monitor the cumulative time spent in database queries per HTTP request and notify developers of slow requests.

While DB::listen() measures individual query duration, an endpoint that executes 100 fast 5ms queries spends a massive 500ms in SQL without triggering single-query slow thresholds.

DB::whenQueryingForLongerThan() measures the cumulative total database time across an entire request.

Setting Cumulative Query Thresholds

In AppServiceProvider::boot():

namespace App\Providers;

use Carbon\CarbonInterval;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Trigger alert if a single request spends more than 500ms in total database queries
        DB::whenQueryingForLongerThan(CarbonInterval::milliseconds(500), function ($connection) {
            Log::warning("Database query threshold exceeded [{$connection->totalQueryDuration()}ms]", [
                'url' => request()->fullUrl(),
                'user_id' => auth()->id(),
            ]);
        });
    }
}

Summary

• Measures total aggregate SQL duration per HTTP request lifecycle.
• Catches cumulative N+1 query regressions that individual query thresholds miss.
• Accepts CarbonInterval instances for clean threshold definitions.

Extract query filtering logic into invokable scope classes that work interchangeably across Eloquent query builders and Laravel Scout search instances.

Standard Eloquent local scopes (scopeActive(), scopeFilter()) work well for database queries, but they are tightly coupled to the Eloquent Builder instance and cannot be directly invoked on a Laravel Scout search query builder (Post::search()->...).

By creating invokable "Tappable Scope" classes, you can share identical query constraints across both database queries and full-text search pipelines without duplicating logic.

1. Create the Invokable Scope Class

Create a dedicated scope class that accepts either an Eloquent Builder or a Scout Builder:

namespace App\Models\Scopes;

use App\Models\User;
use Illuminate\Database\Eloquent\Builder;
use LaravelScoutBuilder as ScoutBuilder;

final class PublishedScope
{
    public function __construct(
        private ?User $user = null
    ) {}

    public function __invoke(Builder|ScoutBuilder $query): Builder|ScoutBuilder
    {
        return $query
            ->where('is_published', true)
            ->when($this->user, fn ($q) => $q->where('author_id', $this->user->id));
    }
}

2. Using in Model Local Scopes

Apply the scope class inside your model's local scope using $query->tap():

namespace App\Models;

use App\Models\Scopes\PublishedScope;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    public function scopePublished(Builder $query, ?User $user = null): Builder
    {
        return $query->tap(new PublishedScope($user));
    }
}

3. Using in Laravel Scout Search Queries

The same scope class can be piped directly into Scout search queries via ->tap():

use App\Models\Post;
use App\Models\Scopes\PublishedScope;

// Search posts with the same publishing constraints applied
$results = Post::search($searchTerm)
    ->tap(new PublishedScope(auth()->user()))
    ->get();

Why Use Tappable Scopes?

• Dual Compatibility: Operates directly across both standard Eloquent queries and Laravel Scout search pipelines.
• Cross-Model Reuse: Share identical filtering rules across multiple models (e.g. Post, Article, Video) without bloated traits.
• Cleaner Models: Keeps model files lightweight by extracting complex filtering criteria into dedicated, testable classes.

Summary

• Use invokable scope classes paired with ->tap() to share query logic between Eloquent and Scout.
• Keeps search filtering synchronized with database query scopes.
• Eliminates duplicate query logic and keeps model classes lean.

Use $this->travelTo() or freezeTime() in test suites to test date-sensitive logic without slowing down test execution with sleep().

Using sleep() in tests slows down execution suites significantly. Laravel's time travel helpers let you manipulate Carbon's internal clock instantaneously without real-world delays.

test('trial expires after 14 days', function () {
    $user = User::factory()->create(['trial_ends_at' => now()->addDays(14)]);

    // Instantly jump 15 days into the future
    $this->travel(15)->days();

    expect($user->fresh()->hasExpiredTrial())->toBeTrue();
});

• Replaces slow real-time sleep() calls with instant mock clock jumps
• travel(15)->days() moves time forward dynamically
• freezeTime() locks current time to prevent test flickering

When creating integer-backed PHP Enums, index starting from 1 to avoid false-y evaluation bugs in loose comparisons.

In PHP, 0 evaluates as false-y in loose condition checks like empty() or if ($enum->value). Starting integer enum values at 1 prevents accidental false-y evaluation bugs.

Before & After

// ❌ Dangerous: 0 evaluates to false in loose checks
enum Priority: int
{
    case Low = 0;
    case Medium = 1;
    case High = 2;
}

// empty(Priority::Low->value) is true!

// ✅ Recommended: Start indexing at 1
enum Priority: int
{
    case Low = 1;
    case Medium = 2;
    case High = 3;
}

// empty(Priority::Low->value) is false!

Key Benefits

• Prevents False-y Pitfalls: Avoids unexpected truthy/falsy evaluation bugs when inspecting raw enum integer values.
• Database Consistency: Aligns naturally with standard 1-based auto-incrementing database ID conventions.
• Predictable Empty Checks: Ensures empty() or blank() checks on enum values behave intuitively without silent failures.

Document and enforce structured array schemas using PHPDoc array shapes, lists, and non-empty array annotations for static analysis in PHPStan and Psalm.

PHP arrays are versatile: they function as zero-indexed lists, associative maps, and nested dictionary structures. However, using native typehints like function process(array $data) leaves the contents of the array untyped, leading to potential missing key errors or unexpected values at runtime.

By using PHPDoc array shapes and pseudo-types, static analysis tools (like PHPStan and Psalm) and modern IDEs (such as PhpStorm and VS Code) can strictly validate array keys and types without requiring dedicated Data Transfer Objects (DTOs) for every small payload.

1. Defining Exact Array Shapes (array{...})

Array shapes define the exact dictionary schema of an associative array, including expected keys and their individual types:

/**
 * @param array{id: int, name: string, email: string, is_active?: bool} $user
 * @return array{status: string, timestamp: int}
 */
function registerUser(array $user): array
{
    // PHPStan ensures $user['id'], $user['name'], and $user['email'] exist
    $status = $user['is_active'] ?? true ? 'active' : 'pending';

    return [
        'status' => $status,
        'timestamp' => time(),
    ];
}

• Required Keys: id: int, name: string
• Optional Keys (?): is_active?: bool (the key may or may not be present in the array)

2. Zero-Indexed Lists (list<T>)

Standard PHP arrays can have arbitrary or sparse integer keys. When an array is guaranteed to be a contiguous, zero-indexed numerical list (0, 1, 2, ...), use list<T>:

/**
 * @param list<int> $scores
 * @return float
 */
function calculateAverage(array $scores): float
{
    if ($scores === []) {
        return 0.0;
    }

    return array_sum($scores) / count($scores);
}

// Valid list
calculateAverage([90, 85, 95]);

// PHPStan flags non-list associative arrays
calculateAverage(['first' => 90, 'second' => 85]); // Error

3. Associative Key-Value Maps (array<K, V>)

When working with dynamic key-value maps (such as configuration options or lookup tables):

/**
 * @param array<string, mixed> $payload
 * @return string
 */
function serializePayload(array $payload): string
{
    return json_encode($payload, JSON_THROW_ON_ERROR);
}

/**
 * @param array<int, User> $usersById
 */
function notifyUsers(array $usersById): void
{
    foreach ($usersById as $id => $user) {
        // $id is typed as int, $user is typed as User
        $user->sendNotification();
    }
}

4. Non-Empty Arrays (non-empty-array<T>)

If a function requires at least one element to prevent division-by-zero or empty-set errors, declare it with non-empty-array:

/**
 * @param non-empty-array<string> $recipients
 * @return string
 */
function getPrimaryRecipient(array $recipients): string
{
    // Guaranteed to contain at least 1 element; safe from undefined offset
    return $recipients[0];
}

5. Typed Callback Arrays (array<callable>)

When storing or dispatching collections of closures or invokable handlers:

/**
 * @param list<callable(): void> $listeners
 */
function triggerListeners(array $listeners): void
{
    foreach ($listeners as $listener) {
        $listener();
    }
}

triggerListeners([
    fn () => logger()->info('First listener executed'),
    fn () => logger()->info('Second listener executed'),
]);

Summary

• Use array{key: type} to define explicit key requirements and prevent missing array index bugs.
• Use list<T> for contiguous, zero-indexed sequential lists.
• Use array<KeyType, ValueType> for generic maps and associative containers.
• Use non-empty-array<T> to statically assert that an array contains at least one item.

Implement type-safe generic collections, wrapper classes, and utility functions in PHP using PHPDoc template annotations for static analysis engines.

While PHP does not have native language-level generic syntax (like class Collection<T>), static analysis tools such as PHPStan and Psalm provide full generic support via @template annotations.

By annotating wrapper classes and helper functions with @template, you preserve exact object types across transformations and collections without resorting to ambiguous mixed or object returns.

1. Generic Collections and Repositories

Annotate a class with @template T so the items stored inside match the items returned:

/**
 * @template T
 */
class Collection
{
    /** @var list<T> */
    private array $items = [];

    /**
     * @param T $item
     */
    public function add(mixed $item): void
    {
        $this->items[] = $item;
    }

    /**
     * @return list<T>
     */
    public function all(): array
    {
        return $this->items;
    }

    /**
     * @return T|null
     */
    public function first(): mixed
    {
        return $this->items[0] ?? null;
    }
}

Usage with Type Preservation

/** @var Collection<User> $userCollection */
$userCollection = new Collection();
$userCollection->add(new User('Alice'));

// IDE and PHPStan know $user is an instance of User
$user = $userCollection->first();
$userName = $user?->name;

2. Generic Type Constraints (@template T of BaseClass)

You can restrict a generic type parameter to a specific class, interface, or union type using the of keyword:

abstract class Animal
{
    abstract public function speak(): string;
}

class Dog extends Animal
{
    public function speak(): string { return 'Woof'; }
}

class Cat extends Animal
{
    public function speak(): string { return 'Meow'; }
}

/**
 * @template T of Animal
 */
class Shelter
{
    /** @var list<T> */
    private array $residents = [];

    /**
     * @param T $animal
     */
    public function admit(Animal $animal): void
    {
        $this->residents[] = $animal;
    }

    /**
     * @return list<T>
     */
    public function getResidents(): array
    {
        return $this->residents;
    }
}

3. Generic Functions and Utility Methods

Generic functions capture the type passed in arguments and return that exact same type:

/**
 * @template T
 * @param non-empty-array<T> $items
 * @return T
 */
function getFirstItem(array $items): mixed
{
    return $items[array_key_first($items)];
}

// Inferred return type: int
$number = getFirstItem([10, 20, 30]);

// Inferred return type: Product
$product = getFirstItem([new Product('Keyboard'), new Product('Mouse')]);

4. Generic Factory Methods with class-string<T>

When instantiating or resolving classes dynamically by class name, combine @template T with class-string<T>:

/**
 * @template T of object
 * @param class-string<T> $className
 * @return T
 */
function createInstance(string $className): object
{
    return new $className();
}

// $service is statically typed as PaymentGateway, with full autocomplete
$service = createInstance(PaymentGateway::class);

Summary

• Use @template T on classes and functions to capture dynamic types and prevent type degradation to mixed.
• Use @template T of Constraint to enforce class hierarchy or interface boundaries on generic parameters.
• Combine @template T with class-string<T> for strongly typed factory and dependency injection methods.
• Enables compile-time type safety across complex collections and architectures.

Understand what each rule level in PHPStan inspects, from basic syntax errors at Level 0 to strict mixed-type enforcement at Level 9 and Level 10.

PHPStan inspects your PHP code without executing it, discovering subtle type mismatches, dead code, and unhandled edge cases. PHPStan organizes its rule sets into numeric levels ranging from 0 (most lenient) to 10 (maximum strictness).

When adopting PHPStan in existing or greenfield projects, understanding what each level verifies helps you establish progressive static analysis milestones.

Overview of PHPStan Levels

Level-by-Level Code Examples

Level 0: Basic Syntax & Function Calls

Verifies that called classes, functions, and methods exist, and that required parameter counts are satisfied:

class Example
{
    public function run(): void
    {
        $this->unknownMethod(); // Error: Call to an undefined method
    }
}

function calculate(int $a, int $b): int
{
    return $a + $b;
}

calculate(1); // Error: Function calculate() called with 1 parameter, 2 required.

Level 1: Possibly Undefined Variables

Ensures every variable accessed is guaranteed to be defined in all branching paths:

function process(bool $flag): void
{
    if ($flag) {
        $data = 'ready';
    }

    echo $data; // Error: Variable $data might not be defined.
}

Level 2: Unknown Methods on All Expressions

Checks methods and properties on expressions where types are known via annotations or reflection:

class User
{
    public function getName(): string { return 'Alex'; }
}

$user = new User();
$user->getProfilePhoto(); // Error: Call to an undefined method User::getProfilePhoto()

Level 3: Return Types and Property Assignments

Validates that returned values and assigned properties match their type definitions:

class Order
{
    private int $total;

    public function setTotal(string $amount): void
    {
        $this->total = $amount; // Error: Property Order::$total (int) does not accept string.
    }

    public function getInvoiceNumber(): string
    {
        return 12345; // Error: Method getInvoiceNumber() should return string but returns int.
    }
}

Level 4: Dead Code and Redundant Logic

Detects unreachable statements and conditionals that always evaluate to true or false:

function check(User $user): void
{
    if ($user instanceof User) { // Always true
        echo 'Valid';
    }

    return;
    echo 'Unreachable'; // Error: Unreachable statement - code above always returns.
}

Level 5: Argument Type Validation

Verifies that arguments passed to functions match the declared parameter types:

function setDiscount(int $percentage): void {}

setDiscount('20'); // Error: Parameter #1 expects int, string given.

Level 6: Missing Typehints

Requires explicit typehints on function parameters, return types, and properties:

class Report
{
    // Error: Property Report::$records has no type specified.
    private $records;

    // Error: Method generate() has parameter $options with no type specified.
    public function generate($options) {}
}

Level 7: Partially Wrong Union Types

Flags method calls on union types where only some union members implement the method:

class Customer { public function sendInvoice(): void {} }
class Guest {}

function notify(Customer|Guest $recipient): void
{
    // Error: Call to method sendInvoice() on Customer|Guest (Guest does not have method).
    $recipient->sendInvoice();
}

Level 8: Nullable Type Access

Catches potential "Call to a member function on null" errors:

function printLength(?string $input): int
{
    // Error: Cannot call method strlen() with parameter ?string (requires string).
    return strlen($input);
}

Level 9: Strict mixed Evaluation

At Level 9, mixed is treated strictly. You cannot perform operations on mixed values without explicit type narrowing:

function formatData(mixed $value): string
{
    // Error: Cannot call method trim() on mixed. Narrow type with is_string() first.
    return trim($value);
}

Level 10: Strict Explicit mixed Types (PHPStan 2.0+)

PHPStan 2.0 introduces Level 10 (or level: max), which goes beyond Level 9 by prohibiting passing mixed values or returning mixed where specific types are expected, ensuring full end-to-end type safety throughout generic containers and arrays:

/**
 * @param array<string, mixed> $payload
 */
function processPayload(array $payload): string
{
    // Level 10 Error: Parameter #1 $name of function greet() expects string, mixed given.
    return greet($payload['name']);
}

function greet(string $name): string
{
    return "Hello, {$name}!";
}

To satisfy Level 10, explicitly assert or validate the type:

function processPayload(array $payload): string
{
    if (! isset($payload['name']) || ! is_string($payload['name'])) {
        throw new InvalidArgumentException('Expected name to be a string.');
    }

    return greet($payload['name']); // Valid at Level 10
}

Recommended Adoption Strategy

1. Start at Level 1 or 2: Fix baseline undefined variables and non-existent methods in legacy codebases.
2. Advance to Level 5: Add argument type verification to prevent runtime TypeError exceptions.
3. Target Level 8 or Level 10: Ideal for modern, strongly typed Laravel and PHP applications using Larastan.

Summary

• PHPStan levels range progressively from 0 (lenient) to 10 (maximum strictness).
• Levels 1 to 5 catch common runtime bugs without requiring exhaustive PHPDoc annotations.
• Levels 6 to 8 enforce complete type coverage and nullable safety.
• Levels 9 and 10 enforce strict type narrowing on mixed values and array payloads.

Use Response::denyAsNotFound() in policies to return a 404 Not Found response instead of 403 Forbidden, concealing the existence of private resources.

Returning HTTP 403 Forbidden on confidential resources (such as private repositories, draft invoices, or secret project boards) tells attackers that the resource exists, leaking information.

Laravel policies support Response::denyAsNotFound() to return a 404 response directly from authorization checks.

Policy Implementation

namespace App\Policies;

use App\Models\Project;
use App\Models\User;
use Illuminate\Auth\Access\Response;

class ProjectPolicy
{
    public function view(User $user, Project $project): Response
    {
        if ($project->is_confidential && $project->owner_id !== $user->id) {
            // Returns HTTP 404 instead of 403 Forbidden
            return Response::denyAsNotFound('Project not found.');
        }

        return Response::allow();
    }
}

Summary

• Throws a NotFoundHttpException (404) rather than AuthorizationException (403).
• Prevents resource enumeration attacks on private URL identifiers.
• Keeps authorization logic centralized inside Policy classes.

Use Laravel's Pipeline facade to pass objects through sequential pipe classes, keeping complex order processing and data transformations modular.

When an application workflow involves multiple distinct stages (such as validating payment, applying coupons, calculating tax, and generating invoices), stuffing all logic into a single service method creates monolithic, hard-to-test code.

Laravel's Pipeline pattern executes sequential pipes cleanly.

Defining Pipe Classes

Each pipe receives the payload and a $next closure:

namespace App\Pipelines\Orders;

use Closure;

class ApplyDiscountCoupon
{
    public function handle(Order $order, Closure $next)
    {
        if ($order->coupon_code) {
            $order->discount = CouponService::calculate($order);
        }

        return $next($order);
    }
}

Executing the Pipeline

use App\Pipelines\Orders\ApplyDiscountCoupon;
use App\Pipelines\Orders\CalculateTax;
use App\Pipelines\Orders\ProcessStripePayment;
use Illuminate\Support\Facades\Pipeline;

$processedOrder = Pipeline::send($order)
    ->through([
        ApplyDiscountCoupon::class,
        CalculateTax::class,
        ProcessStripePayment::class,
    ])
    ->then(fn ($order) => $order->finalize());

Summary

• Deconstructs complex operations into focused, single-responsibility pipe classes.
• Enables easy reordering, adding, or removing of business steps.
• Uses standard middleware-style handle($passable, Closure $next) signatures.

Enable Model::preventLazyLoading() in local development to automatically throw exceptions whenever a relationship is lazy loaded.

Accidentally accessing relationships inside loops (like $user->posts without User::with('posts')) causes silent N+1 query performance degradation that often goes unnoticed until production traffic spikes.

Model::preventLazyLoading() forces Eloquent to throw an exception when lazy loading occurs.

Enabling in AppServiceProvider

namespace App\Providers;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Throw exceptions locally; log warnings in production
        Model::preventLazyLoading(! $this->app->isProduction());

        // Handle violations in production gracefully
        if ($this->app->isProduction()) {
            Model::handleLazyLoadingViolationsUsing(function ($model, $relation) {
                logger()->warning("Lazy loading [{$relation}] on [{$model::class}] in production.");
            });
        }
    }
}

What Happens When a Relation is Lazy Loaded

Attempted to lazy load [comments] on model [AppModelsPost] but lazy loading is disabled.

Summary

• Catches N+1 query performance bugs during development and test suites.
• Fails fast with descriptive stack traces pointing directly to the offending blade view or loop.
• Supports custom violation handlers for production telemetry.

Automate renaming PHP 8.1+ enum cases from SNAKE_CASE to PascalCase across PHP classes and Blade templates using Rector and an Artisan refactoring script.

When PHP 8.1 backed enums were introduced, many projects originally named enum cases in uppercase snake case (case PENDING_REVIEW;), matching older class constant conventions. Modern PHP and Laravel coding style standards (including PER-CS and Laravel Pint) recommend PascalCase for enum cases (case PendingReview;).

Renaming enum cases across a large production application manually is error-prone. By combining a custom Rector rule with an Artisan Blade updater, you can refactor all enum declarations, references, and Blade view usages automatically.

1. Custom Rector Rule for Enum Cases

namespace App\Rector;

use PhpParser\Node;
use PhpParser\Node\Expr\ClassConstFetch;
use PhpParser\Node\Identifier;
use PhpParser\Node\Stmt\EnumCase;
use PHPStan\Reflection\ReflectionProvider;
use Rector\Rector\AbstractRector;
use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;

final class RenameEnumCasesToPascalCaseRector extends AbstractRector
{
    public function __construct(
        private ReflectionProvider $reflectionProvider
    ) {}

    public function getNodeTypes(): array
    {
        return [EnumCase::class, ClassConstFetch::class];
    }

    public function refactor(Node $node): ?Node
    {
        if ($node instanceof EnumCase) {
            return $this->refactorEnumCase($node);
        }

        if ($node instanceof ClassConstFetch) {
            return $this->refactorEnumCaseFetch($node);
        }

        return null;
    }

    private function refactorEnumCase(EnumCase $node): ?Node
    {
        $oldName = $this->getName($node->name);
        $newName = $this->convertSnakeToPascalCase($oldName);

        if ($oldName !== $newName) {
            $node->name = new Identifier($newName);
            return $node;
        }

        return null;
    }

    private function refactorEnumCaseFetch(ClassConstFetch $node): ?Node
    {
        $objectType = $this->getType($node->class);

        if ($objectType->isEnum()->yes()) {
            $oldName = $this->getName($node->name);
            if ($oldName === 'class' || $oldName === null) {
                return null;
            }

            $newName = $this->convertSnakeToPascalCase($oldName);
            if ($oldName !== $newName) {
                $node->name = new Identifier($newName);
                return $node;
            }
        }

        return null;
    }

    private function convertSnakeToPascalCase(string $name): string
    {
        return str_replace(' ', '', ucwords(str_replace('_', ' ', mb_strtolower($name))));
    }

    public function getRuleDefinition(): RuleDefinition
    {
        return new RuleDefinition('Convert SNAKE_CASE enum cases to PascalCase', [
            new CodeSample(
                'enum Status { case PENDING_PAYMENT; }',
                'enum Status { case PendingPayment; }'
            ),
        ]);
    }
}

2. Refactoring Blade Templates

Because Rector parses PHP files rather than Blade templates, use an Artisan command to update enum case usages inside resources/views/**/*.blade.php:

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\File;

class RefactorBladeEnumsCommand extends Command
{
    protected $signature = 'refactor:blade-enums';
    protected $description = 'Refactor enum cases in Blade views from SNAKE_CASE to PascalCase';

    public function handle(): int
    {
        $views = File::allFiles(resource_path('views'));

        foreach ($views as $file) {
            if ($file->getExtension() !== 'php') {
                continue;
            }

            $content = File::get($file->getRealPath());

            // Match patterns like Status::PENDING_PAYMENT
            $updated = preg_replace_callback('/([A-Z][A-Za-z0-9]+)::([A-Z0-9_]+)/', function ($matches) {
                $class = $matches[1];
                $case = $matches[2];

                if ($case === 'class') {
                    return $matches[0];
                }

                $pascalCase = str_replace(' ', '', ucwords(str_replace('_', ' ', strtolower($case))));
                return "{$class}::{$pascalCase}";
            }, $content);

            if ($content !== $updated) {
                File::put($file->getRealPath(), $updated);
                $this->line("Updated view: " . $file->getRelativePathname());
            }
        }

        $this->info('Blade enum refactoring completed.');
        return Command::SUCCESS;
    }
}

Summary

• Use Rector to safely refactor Enum definitions and PHP references via AST inspection and PHPStan static reflection.
• Run a targeted Blade regex migration script to update template references without manual search-and-replace.
• Standardizes your enum architecture to PascalCase conventions across the entire application.

Use Rector to automatically refactor legacy protected $casts array properties into the modern casts() method across your entire Laravel codebase.

Laravel 11 introduced the casts() method on Eloquent models, allowing fluent cast definitions, class references, and method calls inside model classes.

Rector automates converting legacy protected $casts properties to the new method:

1) app/Models/Post.php

- protected $casts = [
-     'tags' => 'array',
-     'published_at' => 'datetime',
-     'is_featured' => FeaturedStatus::class,
- ];

+ protected function casts(): array
+ {
+     return [
+         'tags' => 'array',
+         'published_at' => 'datetime',
+         'is_featured' => FeaturedStatus::class,
+     ];
+ }

• Runs across hundreds of models in seconds during framework upgrades
• Enables calling static methods directly inside cast definitions (e.g. AsEnumCollection::of(...))
• Eliminates typos in array property names

Cast enum instances nested within JSON or array database columns using Eloquent Attribute accessors and mutators.

Laravel provides first-party enum casting for standard model columns:

protected $casts = [
    'status' => PostStatus::class,
];

However, when an enum value is stored inside a nested JSON object or array column (such as options->status or settings['status']), Laravel's default column casting casts the entire column to an array, leaving the nested enum value as a raw string or integer.

Using Eloquent's Attribute accessor and mutator, you can automatically hydrate and serialize nested enum instances.

Implementing the Nested Enum Cast

namespace App\Models;

use App\Enums\PostStatus;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    protected function options(): Attribute
    {
        return Attribute::make(
            get: function ($value): array {
                $options = json_decode($value ?? '[]', true) ?? [];

                // Hydrate string value to Backed Enum instance
                if (isset($options['status'])) {
                    $options['status'] = PostStatus::tryFrom($options['status']) ?? $options['status'];
                }

                return $options;
            },
            set: function ($value): string {
                $options = is_array($value) ? $value : (json_decode($value, true) ?? []);

                // Serialize Backed Enum instance to scalar value before storing
                if (isset($options['status']) && $options['status'] instanceof PostStatus) {
                    $options['status'] = $options['status']->value;
                }

                return json_encode($options);
            }
        );
    }
}

Practical Usage

You can now interact with nested enum properties as strongly typed objects:

$post = Post::find(1);

// Accessing the nested enum
if ($post->options['status'] === PostStatus::Draft) {
    // Strongly typed enum comparison
}

// Updating the nested enum
$options = $post->options;
$options['status'] = PostStatus::Published;
$post->options = $options;
$post->save();

Summary

• Use Eloquent Attribute::make() to hydrate and serialize enums nested inside JSON attributes.
• Use PostStatus::tryFrom() in the getter to gracefully handle unexpected values without throwing exceptions.
• Ensures strongly typed enum consistency even for schemaless or flexible JSON payloads.

Use Eloquent custom casts (CastsAttributes) to handle complex JSON serialization and Backed Enum arrays cleanly.

When model attributes contain complex JSON structures or collections of Enums, implement CastsAttributes to handle custom database transformation and object hydration.

namespace App\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use App\Enums\Permission;

class PermissionCast implements CastsAttributes
{
    public function get($model, string $key, $value, array $attributes): array
    {
        return array_map(fn ($val) => Permission::from($val), json_decode($value, true) ?? []);
    }

    public function set($model, string $key, $value, array $attributes): string
    {
        return json_encode(array_map(fn ($enum) => $enum->value, $value));
    }
}

• Implements CastsAttributes with get() and set() transformation signatures
• Handles custom JSON encoding and object hydration transparently
• Keeps model classes free of manual JSON encoding logic

Prevent view compilation glitches when running php artisan view:cache on templates using @teleport by registering explicit Blade directives.

When using Livewire or Alpine.js @teleport directives inside Blade templates, running php artisan view:cache in production or CI/CD pipelines can occasionally cause compilation errors or unparsed tags if custom directive compilation is missing from the service container.

You can ensure consistent, error-free view compilation by registering custom Blade compiler directives for @teleport and @endteleport.

The Fix in AppServiceProvider

Add the custom directive registration inside your AppServiceProvider::register() or boot() method:

namespace App\Providers;

use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Blade::directive('teleport', function (string $expression): string {
            return "<template x-teleport="<?php echo e({$expression}); ?>">";
        });

        Blade::directive('endteleport', function (): string {
            return "</template>";
        });
    }
}

Usage in Blade Views

You can now use @teleport cleanly across cached views:

<div x-data="{ open: false }">
    <button @click="open = true">Open Modal</button>

    @teleport('body')
        <div x-show="open" class="modal-backdrop">
            <div class="modal-content">
                <h3>Modal Title</h3>
                <button @click="open = false">Close</button>
            </div>
        </div>
    @endteleport
</div>

Testing View Caching

Run view cache compilation to verify:

php artisan view:clear
php artisan view:cache

All views compile cleanly into cached PHP templates without syntax exceptions.

Summary

• Register explicit @teleport and @endteleport Blade directives in AppServiceProvider to resolve compilation glitches during view:cache.
• Translates cleanly into standard Alpine.js <template x-teleport="..."> elements.
• Prevents production deployment build failures when caching views.

Capture HTTP requests, Artisan CLI commands, and outgoing API responses into a unified audit trail using a single Laravel Event Subscriber.

Applications frequently need to log key lifecycle actions for debugging and compliance. Instead of scattering logging logic across various middleware, commands, and service classes, Laravel Event Subscribers let you listen to multiple framework events from a single centralized class.

The ActivityLogEventSubscriber

namespace App\Listeners;

use Illuminate\Console\Events\CommandFinished;
use Illuminate\Events\Dispatcher;
use Illuminate\Foundation\Http\Events\RequestHandled;
use Illuminate\Http\Client\Events\ResponseReceived;
use Illuminate\Support\Facades\Log;

class ActivityLogEventSubscriber
{
    public function handleHttpRequest(RequestHandled $event): void
    {
        $this->logActivity('RequestHandled', [
            'method' => $event->request->method(),
            'url' => $event->request->fullUrl(),
            'status' => $event->response->getStatusCode(),
            'user_id' => $event->request->user()?->id,
        ]);
    }

    public function handleConsoleCommand(CommandFinished $event): void
    {
        $this->logActivity('CommandFinished', [
            'command' => $event->command,
            'exit_code' => $event->exitCode,
        ]);
    }

    public function handleHttpClientResponse(ResponseReceived $event): void
    {
        $this->logActivity('HttpClientResponse', [
            'url' => (string) $event->request->url(),
            'status' => $event->response->status(),
        ]);
    }

    private function logActivity(string $eventType, array $payload): void
    {
        Log::channel('activity')->info("Activity [{$eventType}]", $payload);
    }

    public function subscribe(Dispatcher $events): array
    {
        return [
            RequestHandled::class => 'handleHttpRequest',
            CommandFinished::class => 'handleConsoleCommand',
            ResponseReceived::class => 'handleHttpClientResponse',
        ];
    }
}

Registering the Subscriber

In Laravel 11+, register the subscriber inside your AppServiceProvider::boot() method (or EventServiceProvider in earlier versions):

namespace App\Providers;

use App\Listeners\ActivityLogEventSubscriber;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::subscribe(ActivityLogEventSubscriber::class);
    }
}

Summary

• Use an Event Subscriber to group related event handlers into a single cohesive class.
• Listen to built-in framework events like RequestHandled, CommandFinished, and ResponseReceived for comprehensive audit logging.
• Decouples monitoring and logging logic from core HTTP controllers and console commands.

Generate unique database slugs in Eloquent by querying the maximum existing numerical suffix directly instead of executing repeated queries in a while loop.

When generating URL slugs for blog posts, products, or articles, collisions occur when two records share the same title ("My First Post").

A frequent implementation uses a while loop that repeatedly queries the database (post-1, post-2, post-3, ...) until an available slug is found. On busy applications with many duplicate titles, this pattern generates dozens of sequential database roundtrips for a single record creation.

You can determine the next unique slug in a single query by inspecting the maximum numeric suffix using SQL functions.

The Efficient Implementation

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Facades\DB;

class Article extends Model
{
    protected static function booted(): void
    {
        static::creating(function (Article $article): void {
            if (empty($article->slug)) {
                $article->slug = static::generateUniqueSlug($article->title);
            }
        });
    }

    public static function generateUniqueSlug(string $title): string
    {
        $baseSlug = str($title)->slug()->value();

        // Check if base slug is already available
        if (static::where('slug', $baseSlug)->doesntExist()) {
            return $baseSlug;
        }

        // Query the maximum existing numeric suffix in a single query
        $maxSuffix = static::query()
            ->where('slug', 'LIKE', "{$baseSlug}-%")
            ->max(DB::raw('CAST(SUBSTRING_INDEX(slug, "-", -1) AS SIGNED)'));

        if ($maxSuffix === null || $maxSuffix <= 0) {
            return "{$baseSlug}-2";
        }

        return "{$baseSlug}-" . ($maxSuffix + 1);
    }
}

How It Works

1. Initial Availability Check: Checks if the clean base slug ("laravel-tips") exists. If available, it returns immediately with 1 simple indexed lookup.
2. SUBSTRING_INDEX Extraction: For duplicate titles, MySQL's SUBSTRING_INDEX(slug, "-", -1) extracts the trailing characters after the last hyphen.
3. CAST(... AS SIGNED): Converts the extracted substring into an integer so the MAX() aggregate computes the numerical maximum rather than alphabetical sorting.
4. Calculated Next Suffix: Increments the maximum found suffix (max + 1), guaranteeing uniqueness without sequential trial-and-error queries.

Performance Comparison

• While Loop Approach: Runs (N) database queries (where (N) is the number of existing collisions).
• Direct Max Calculation: Always runs exactly 2 queries regardless of whether 2 or 2,000 colliding records exist.

Summary

• Avoid while (Model::whereSlug(...)->exists()) loops that create unpredictable N+1 database roundtrips.
• Use SQL string extraction and integer casting to retrieve the maximum numerical suffix in a single lookup.
• Guarantees fast, predictable execution time during bulk imports and high-traffic record creation.

Control system time during testing and development using Carbon::setTestNow() and inspect active time mocks with Carbon::hasTestNow().

When writing unit tests or developing features that rely on temporal calculations (such as subscription renewals, birthday promotions, trial expirations, or grace periods), relying on real system time creates flaky tests that fail depending on the time of day or month.

Carbon provides setTestNow() to lock time to a specific instant, alongside hasTestNow() to verify whether the temporal state is currently mocked.

Freezing Time in Feature Logic

use Carbon\Carbon;

function isBirthdayOfferActive(Carbon $birthday): bool
{
    return Carbon::now()->isSameDay($birthday);
}

// Check without mock time
$userBirthday = Carbon::create(1995, 11, 23);
isBirthdayOfferActive($userBirthday); // Evaluates against real current date

// Freeze application time to a specific target date
Carbon::setTestNow(Carbon::create(2026, 11, 23));

isBirthdayOfferActive($userBirthday); // Returns true!

// Reset back to real system time
Carbon::setTestNow(null);

Checking if Mock Time is Active with hasTestNow()

In custom debug bars, health checks, or safety middleware, you can inspect whether the application is running under a simulated timestamp:

use Carbon\Carbon;

if (Carbon::hasTestNow()) {
    logger()->warning('Application running with mocked Carbon time: ' . Carbon::now()->toDateTimeString());
}

Laravel Test Helpers Under the Hood

Laravel's built-in testing helpers ($this->travelTo(), $this->freezeTime()) interact directly with Carbon::setTestNow():

test('trial expires after 14 days', function () {
    $this->freezeTime();

    $user = User::factory()->create(['trial_ends_at' => now()->addDays(14)]);
    expect($user->hasExpiredTrial())->toBeFalse();

    // Travel forward 15 days
    $this->travel(15)->days();

    expect($user->hasExpiredTrial())->toBeTrue();
});

Summary

• Use Carbon::setTestNow() to freeze time during test executions and verify time-dependent edge cases reliably.
• Always reset mock time with Carbon::setTestNow(null) in test teardown hooks if not using Laravel's test time helpers.
• Use Carbon::hasTestNow() to check if time manipulation is currently active.

Use Livewire 3's #[Renderless] attribute to stream file downloads directly from component actions without triggering unnecessary view re-renders or database queries.

When triggering a file download or CSV export from a Livewire component, Livewire's default lifecycle runs the component's render() method after executing the action.

If your render() method executes complex database queries or chart calculations, running render() during a binary file download wastes server CPU and memory since the HTML response is discarded in favor of the download stream.

Livewire 3 provides the #[Renderless] attribute to execute an action without invoking render().

The Livewire Component

namespace App\Livewire;

use App\Models\Report;
use Livewire\Attributes\Renderless;
use Livewire\Component;
use Symfony\Component\HttpFoundation\StreamedResponse;

class TransactionReports extends Component
{
    public string $startDate = '';
    public string $endDate = '';
    public array $selectedColumns = ['id', 'reference', 'amount', 'created_at'];

    #[Renderless]
    public function exportCsv(): StreamedResponse
    {
        return response()->streamDownload(function (): void {
            $output = fopen('php://output', 'w');

            // Write CSV header
            fputcsv($output, $this->selectedColumns);

            // Stream records in chunks
            Report::query()
                ->when($this->startDate, fn ($q) => $q->where('created_at', '>=', $this->startDate))
                ->when($this->endDate, fn ($q) => $q->where('created_at', '<=', $this->endDate))
                ->select($this->selectedColumns)
                ->chunk(500, function ($rows) use ($output): void {
                    foreach ($rows as $row) {
                        fputcsv($output, $row->toArray());
                    }
                });

            fclose($output);
        }, 'reports.csv', [
            'Content-Type' => 'text/csv',
        ]);
    }

    public function render()
    {
        // Heavy query executed ONLY when rendering HTML UI, NOT during CSV export
        return view('livewire.transaction-reports', [
            'reports' => Report::latest()->paginate(25),
        ]);
    }
}

In the Blade Template

<div>
    <button wire:click="exportCsv" class="btn btn-secondary">
        Export CSV
    </button>
</div>

Summary

• Apply #[Renderless] (or $this->skipRender() in Livewire 2/3) to file export methods in Livewire components.
• Skips the render() lifecycle entirely, preventing redundant database queries and HTML rendering during downloads.
• Combines with response()->streamDownload() for memory-efficient exports directly to the browser.

Automatically assign tenant IDs and restrict Eloquent queries using a reusable BelongsToTeam model trait with model booting and global scopes.

In multi-tenant or team-based SaaS applications, models (such as projects, invoices, and documents) must belong to a specific team, and users must only access records belonging to their active team.

Instead of writing repetitive query scopes and $model->team_id = auth()->user()->team_id assignments in every controller, you can encapsulate multi-tenant behavior in a reusable model trait.

The BelongsToTeam Trait

namespace App\Traits\Models;

use App\Models\Team;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

trait BelongsToTeam
{
    public static function bootBelongsToTeam(): void
    {
        // Automatically set the team_id when creating a new record
        static::creating(function ($model): void {
            if (auth()->check() && empty($model->team_id)) {
                $model->team_id = auth()->user()->team_id;
            }
        });
    }

    protected static function booted(): void
    {
        parent::booted();

        // Apply a global scope to filter queries by active team
        if (auth()->check()) {
            static::addGlobalScope('team', function (Builder $query): void {
                $query->team();
            });
        }
    }

    public function scopeTeam(Builder $query): Builder
    {
        return $query->when(
            auth()->user()?->team_id,
            function (Builder $query, int $teamId): Builder {
                // Prefix column with table name to prevent SQL ambiguity in joins
                return $query->where($this->getTable() . '.team_id', $teamId);
            },
            function (Builder $query): Builder {
                // If the user has no team, prevent data leakage
                abort(403, 'User does not belong to an active team.');
            }
        );
    }

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

Using the Trait on Models

namespace App\Models;

use App\Traits\Models\BelongsToTeam;
use Illuminate\Database\Eloquent\Model;

class Project extends Model
{
    use BelongsToTeam;

    protected $fillable = ['name', 'description'];
}

What This Automates

1. Automatic Assignment: Calling Project::create(['name' => 'API v2']) automatically populates team_id from the authenticated user.
2. Automatic Query Scoping: Calling Project::all() automatically generates WHERE projects.team_id = ?.
3. Join Safety: Using $this->getTable() . '.team_id' ensures joins and hasManyThrough relationships do not encounter "ambiguous column" SQL errors.

Summary

• Use a BelongsToTeam trait to automate tenant ID assignment on creation and filter queries via global scopes.
• Table-prefix column references in query scopes to prevent SQL errors in joins.
• Eliminates manual scoping across controllers and guarantees tenant isolation.

Simplify multi-column wildcard searches across model columns, relationships, and raw SQL expressions using a powerful whereLike macro on the Eloquent Builder.

Searching across multiple attributes frequently leads to verbose and repetitive orWhere query chains in controller code.

By registering a custom whereLike macro on Eloquent's Builder, you can search across model columns, dot-notation relationships (user.name), and custom database expressions (DB::raw()) in a single readable call.

Registering the Macro in AppServiceProvider

namespace App\Providers;

use Illuminate\Contracts\Database\Query\Expression;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Support\Arr;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Builder::macro('whereLike', function ($attributes, string $searchTerm) {
            return $this->where(function (Builder $query) use ($attributes, $searchTerm) {
                foreach (Arr::wrap($attributes) as $attribute) {
                    $query->when(
                        // Check if attribute is a relationship dot-notation string (e.g. 'user.name')
                        ! ($attribute instanceof Expression) && str_contains((string) $attribute, '.'),
                        function (Builder $query) use ($attribute, $searchTerm) {
                            [$relation, $relatedAttribute] = explode('.', (string) $attribute);

                            $query->orWhereHas($relation, function (Builder $query) use ($relatedAttribute, $searchTerm) {
                                $query->where($relatedAttribute, 'LIKE', "%{$searchTerm}%");
                            });
                        },
                        function (Builder $query) use ($attribute, $searchTerm) {
                            // Search on local column or DB::raw expression
                            $query->orWhere($attribute, 'LIKE', "%{$searchTerm}%");
                        }
                    );
                }
            });
        });
    }
}

Usage Example

You can pass single columns, related model fields using dot notation, and formatted raw SQL expressions:

use App\Models\Post;
use Illuminate\Support\Facades\DB;

$search = request('search');

$posts = Post::query()
    ->whereLike([
        'title',
        'description',
        'user.name',
        'user.email',
        DB::raw('CONCAT(user.first_name, " ", user.last_name)'),
        DB::raw('DATE_FORMAT(created_at, "%d/%m/%Y")'),
    ], $search)
    ->with('user')
    ->paginate(15);

How It Works

1. Encapsulated Scope: Wraps the entire search clause in a single $this->where(function ($query) ...) closure so that boolean AND / OR operator precedence is respected when chained with other query filters.
2. Relationship Detection: Automatically detects dot notation ('user.name') and applies orWhereHas subqueries against the related model.
3. Expression Compatibility: Supports DB::raw() expressions without throwing type errors, enabling searches on computed columns and SQL date formats.

Summary

• Use Builder::macro('whereLike') to consolidate multi-attribute wildcard searches into a single expressive method.
• Automatically handles both local table columns and related model attributes via orWhereHas.
• Respects SQL operator grouping and supports raw database expressions.

Use LazilyRefreshDatabase instead of RefreshDatabase to run database transactions only for tests that actually touch the database.

When running large test suites, the traditional RefreshDatabase trait migrates and resets database transactions before every test, even for pure unit tests that only test formatting or calculations without touching SQL.

LazilyRefreshDatabase defers database initialization until a query is executed.

Using LazilyRefreshDatabase in Tests

namespace Tests\Feature;

use Illuminate\Foundation\Testing\LazilyRefreshDatabase;
use Tests\TestCase;

class UserFeatureTest extends TestCase
{
    use LazilyRefreshDatabase;

    test('calculates user discount percentage', function () {
        // Pure calculation: No database query executed, database setup is skipped!
        $discount = (new Calculator)->discount(100, 20);
        expect($discount)->toBe(80);
    });

    test('creates user record in database', function () {
        // First database query triggers lazy transaction setup automatically
        $user = User::factory()->create();
        $this->assertModelExists($user);
    });
}

Summary

• Defer database connection setup until the first SQL query executes.
• Significantly accelerates test suite runtime in hybrid unit/feature suites.
• Drop-in replacement for RefreshDatabase.

Use Factory::recycle() to pass existing parent models to child factories, avoiding duplicate database record creation in test fixtures.

When generating complex test hierarchies (such as creating 10 Posts, each belonging to the same User, or multiple Orders for an existing Customer), child factories create duplicate parent models by default.

recycle() instructs factories to reuse existing model instances rather than creating new ones.

Reusing Existing Models

use App\Models\Post;
use App\Models\User;

$user = User::factory()->create();

// All 5 posts will be assigned to the existing $user instance
$posts = Post::factory()
    ->count(5)
    ->recycle($user)
    ->create();

Recycling Collections of Models

Pass a collection of models to distribute them across child instances:

$users = User::factory()->count(3)->create();

// 20 posts randomly distributed among the 3 existing users
$posts = Post::factory()
    ->count(20)
    ->recycle($users)
    ->create();

Summary

• Prevents duplicate parent records from cluttering test databases.
• Speeds up test execution times by reducing total database insertions.
• Accepts single model instances or model collections.

MySQL prevents updating a table while selecting from it in a subquery. Wrap subqueries in an intermediate alias table.

Executing UPDATE table WHERE id IN (SELECT id FROM table) throws MySQL Error 1093. Work around this by wrapping the subquery in an intermediate derived table alias.

-- ❌ FAILS in MySQL: Error 1093
-- UPDATE users SET status = 'inactive' WHERE id IN (SELECT id FROM users WHERE last_login < '2023-01-01');

-- ✅ WORKS: Intermediate alias subquery
UPDATE users SET status = 'inactive'
WHERE id IN (
    SELECT id FROM (
        SELECT id FROM users WHERE last_login < '2023-01-01'
    ) AS temp_users
);

• MySQL forbids modifying a target table used directly in a subquery clause
• Wrapping subquery in SELECT * FROM (...) AS alias resolves Error 1093
• Alternative: Use JOIN syntax for multi-table updates

Use when(), unless(), and whenEmpty() on Laravel Collections to conditionally apply transformations without breaking method chains.

When processing collections (such as applying search filters or sorting parameters), writing intermediate if blocks breaks the fluent chain and requires temporary variables.

Laravel Collections provide when() and unless() to conditionally execute closures.

Conditional Transformations with when()

$sortBy = request('sort'); // 'price', 'rating', or null
$filterActive = request()->boolean('active_only');

$products = collect($rawProducts)
    ->when($filterActive, function ($collection) {
        return $collection->where('is_active', true);
    })
    ->when($sortBy === 'price', function ($collection) {
        return $collection->sortBy('price');
    })
    ->when($sortBy === 'rating', function ($collection) {
        return $collection->sortByDesc('rating');
    });

Fallback Data with whenEmpty()

When a collection contains no items, whenEmpty() provides a clean fallback closure:

$recipients = collect($users)
    ->whenEmpty(function ($collection) {
        // Fallback to default administrator if no recipients found
        return collect([User::getSystemAdmin()]);
    });

Summary

• Keeps collection transformation logic inside a single readable fluent chain.
• Accepts an optional default callback as the third argument if the condition is false.
• whenEmpty() cleanly handles empty dataset fallbacks.

Enable Http::preventStrayRequests() in test suites to throw exceptions whenever HTTP requests are made without explicit mocks.

In test suites, accidental outbound HTTP requests to real third-party APIs (such as payment gateways, SMS providers, or webhooks) can trigger unwanted real-world charges or fail unpredictably without internet access.

Laravel provides Http::preventStrayRequests() to block all unmocked HTTP traffic.

Enabling in Base TestCase

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use Illuminate\Support\Facades\Http;

abstract class TestCase extends BaseTestCase
{
    protected function setUp(): void
    {
        parent::setUp();

        // Throw an exception if any HTTP request is unhandled by Http::fake()
        Http::preventStrayRequests();
    }
}

What Happens on Stray Requests

If code executes an un-faked HTTP request during a test, Laravel immediately fails with a descriptive RuntimeException:

Attempted request to [https://api.stripe.com/v1/charges] without a matching fake.

Summary

• Guarantees 100% mocked external HTTP interactions in CI/CD pipelines.
• Prevents accidental calls to real production API endpoints during testing.
• Forces developers to declare explicit Http::fake() definitions for all outbound traffic.

Query related models located on different database connections using whereHas() without cross-database join errors.

When your application partitions data across multiple database connections (such as separating analytics logs, multi-tenant tenants, or payment microservices onto different database servers), standard SQL joins between connection tables fail.

Eloquent's whereHas() directly handles relations across different database connections.

Defining Models on Separate Connections

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class Tenant extends Model
{
    protected $connection = 'main_db';

    public function activityLogs(): HasMany
    {
        return $this->hasMany(ActivityLog::class);
    }
}

class ActivityLog extends Model
{
    // Stored on a separate logging database server
    protected $connection = 'logging_db';
}

Querying Across Connections with whereHas()

use App\Models\Tenant;

// Eloquent handles the cross-connection query correctly
$activeTenants = Tenant::whereHas('activityLogs', function ($query) {
    $query->where('created_at', '>=', now()->subDays(7));
})->get();

Summary

• Enables relational querying even when models reside on distinct database servers.
• Uses WHERE EXISTS queries scoped by database name.
• Eliminates manual cross-database ID querying loops.

Define relationships on models where foreign keys are stored as JSON arrays or comma-separated lists rather than traditional single-id foreign keys.

When dealing with legacy schemas or denormalized database designs where a model stores multiple related IDs inside a JSON array column (e.g. [1, 2, 5]), standard Eloquent relationships fail.

Using array column relationship packages or custom query scope join helpers allows direct querying:

use App\Models\Tag;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    protected $casts = [
        'tag_ids' => 'array',
    ];

    // Query products that contain specific tag IDs inside JSON array
    public function scopeWithTag($query, int $tagId)
    {
        return $query->whereJsonContains('tag_ids', $tagId);
    }
}

// Fetch products matching tag array
$products = Product::withTag(5)->get();

• Enables relational queries on denormalized JSON array fields
• Uses database-native whereJsonContains() for optimized index searching
• Ideal for tag lists, permission arrays, and multi-category selections

Replace PHP's native sleep() and usleep() with Laravel's Sleep facade to write testable, fakeable time pauses.

Using native sleep(5) in queue jobs or API polling loops pauses real system execution, causing test suites to run slowly.

Laravel provides the Illuminate\Support\Sleep facade, which supports inspection and faking during tests.

Using Sleep in Application Code

use Illuminate\Support\Sleep;

// Pause for 5 seconds
Sleep::for(5)->seconds();

// Pause for 500 milliseconds
Sleep::for(500)->milliseconds();

// Pause until a specific Carbon timestamp
Sleep::until(now()->addMinutes(2));

Faking Delays in Tests

In unit and feature tests, call Sleep::fake() to bypass real sleep delays and assert that pauses occurred:

use Illuminate\Support\Sleep;

test('it pauses before retrying failed requests', function () {
    // Prevent real sleep delays in tests
    Sleep::fake();

    $service = new PaymentGateway();
    $service->chargeWithRetry($order);

    // Verify sleep occurred without waiting 10 seconds!
    Sleep::assertSlept(fn ($duration) => $duration->totalSeconds === 10);
});

Summary

• Replaces native sleep() and usleep() with expressive fluent units (seconds(), milliseconds()).
• Sleep::fake() eliminates execution pauses in test suites.
• Provides assertions like assertSlept() and assertNeverSlept().

Use CSS Container Queries (@container) to adjust component layouts based on parent container width rather than viewport size.

Media queries (@media) check total screen width, which breaks when a component is placed inside narrow sidebars versus wide main content areas. Container queries adjust styles based on element parent container width.

/* Define container context on parent */
.card-container {
  container-type: inline-size;
}

/* Adjust card layout based on container width */
@container (min-width: 400px) {
  .card {
    display: flex;
    flex-direction: row;
  }
}

• Adapts component layouts based on parent container dimensions instead of viewport width
• Allows building truly self-contained, context-aware UI components
• Supported natively in all modern web browsers

Use DB::listen() in AppServiceProvider to monitor executed queries, log slow operations, and inspect raw SQL bindings during local development.

Debugging database performance bottlenecks requires visibility into every executed query, its execution time, and bound parameters.

Laravel provides DB::listen() to register a callback executed after every database query.

Logging Slow Queries in Development

Add the listener inside AppServiceProvider::boot():

namespace App\Providers;

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        DB::listen(function ($query) {
            // Log any query that takes longer than 100ms
            if ($query->time > 100) {
                Log::warning("Slow Query [{$query->time}ms]: {$query->sql}", [
                    'bindings'   => $query->bindings,
                    'connection' => $query->connectionName,
                ]);
            }
        });
    }
}

Inspecting Query Properties

• $query->sql: The prepared SQL statement (e.g. select * from users where email = ?).
• $query->bindings: Array of bound parameters.
• $query->time: Execution time in milliseconds.
• $query->connectionName: Database connection identifier (e.g. mysql, pgsql).

Summary

• Intercepts all database queries application-wide.
• Enables threshold-based slow query logging.
• Essential tool for identifying missing indexes and unoptimized joins during development.