Configure Laravel's Date facade to use CarbonImmutable by default, and automate migrating legacy Carbon calls with Rector.

By default, Carbon instances in PHP are mutable. Modifying a date instance unexpectedly alters the original variable:

$date = now();

$tomorrow = $date->addDay();

// Both variables now point to tomorrow!
echo $date->toDateString();     // 2026-09-04
echo $tomorrow->toDateString(); // 2026-09-04

1. Configure the Date Facade

In AppServiceProvider::boot(), instruct Laravel's Date factory to generate CarbonImmutable instances:

namespace App\Providers;

use Carbon\CarbonImmutable;
use Illuminate\Support\Facades\Date;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Date::use(CarbonImmutable::class);
    }
}

Once configured, all calls through the Date facade as well as Laravel helpers (now(), today()) return immutable instances:

$date = now();

$tomorrow = $date->addDay();

echo $date->toDateString();     // 2026-09-03 (original remains unchanged)
echo $tomorrow->toDateString(); // 2026-09-04

2. The Direct Carbon Trap

While Date::use(CarbonImmutable::class) secures now(), today(), and Date::now(), any code directly calling Carbon::now() or Carbon::parse() bypasses Laravel's date factory and remains mutable:

use Carbon\Carbon;

// ❌ Bypasses Laravel's Date factory; remains mutable
$date = Carbon::parse('2026-09-03');

// ✅ Routes through Date factory; returns CarbonImmutable
$date = Date::parse('2026-09-03');

3. Automate Codebase Migration with Rector

To migrate an existing codebase so all static Carbon calls route through Laravel's Date facade, use CarbonToDateFacadeRector from rector-laravel:

composer require --dev driftingly/rector-laravel

Register the rule in rector.php:

// rector.php
use Rector\Config\RectorConfig;
use RectorLaravel\Rector\StaticCall\CarbonToDateFacadeRector;

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

What Rector Automatically Transforms

// Before Rector:
use Carbon\Carbon;

$now = Carbon::now();
$date = Carbon::parse('2026-01-01');

// After Rector:
use Illuminate\Support\Facades\Date;

$now = Date::now();
$date = Date::parse('2026-01-01');

Key Benefits

• Predictable Date Math: Operations like addDay() or subMonth() always return new instances without mutating source dates.
• Framework Uniformity: Using Date::use(CarbonImmutable::class) guarantees all Eloquent timestamps, cast dates, and helpers share the same immutable behavior.
• Automated Modernization: CarbonToDateFacadeRector removes manual search-and-replace across legacy controllers and services.

Laravel 13.30 automatically normalizes and validates paths in Storage::path(), throwing a PathTraversalDetected exception if a path attempts to escape the configured disk root.

When generating absolute filesystem paths using Storage::path($filePath), Laravel resolves the argument relative to the disk root configured in config/filesystems.php (such as storage/app/private).

If your application accepts file paths from user input without strict sanitization, malicious users can inject directory traversal sequences (../../../) to access sensitive configuration files, environment variables, or operating system secrets.

Laravel 13.30 hardens Storage::path() against path traversal attacks, rejecting any resolved path that escapes the boundary of the configured storage disk.

1. The Vulnerability: Path Traversal via User Input

User-controlled file paths can enter your application through multiple entry points:

• Query parameters (?file=reports/summary.pdf)
• Route parameters (/downloads/{filePath})
• Form request fields (request()->input('attachment'))
• JSON API payloads ({ "export_path": "exports/data.csv" })

Warning for Laravel Versions Prior to 13.30:
In versions before Laravel 13.30, Storage::path() does not validate path boundaries. Passing unvalidated user input containing ../ sequences will silently resolve files outside your disk root. If you are on an older version, you must manually sanitize input using basename() or verify that the resolved realpath() starts within the intended storage directory before reading or serving files.

2. Laravel 13.30: Automatic Path Boundary Enforcement

In Laravel 13.30, Storage::path() normalizes dot segments (. and ..) and validates that the final target path stays strictly inside the configured disk root. If the path tries to break out, Laravel immediately throws PathTraversalDetected.

use Illuminate\Filesystem\PathTraversalDetected;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Storage;

// Malicious payload from query string: ?file=../../../../.env
$requestedFile = $request->query('file');

try {
    // Attempting to resolve a path outside storage/app/private
    $fullPath = Storage::disk('local')->path($requestedFile);
} catch (PathTraversalDetected $e) {
    // Laravel 13.30 halts execution immediately
    abort(400, 'Invalid file path requested.');
}

3. Defense in Depth: Framework Boundary vs. Application Security

While Laravel 13.30 provides essential framework-level protection against filesystem escaping, it is not a substitute for application-level authorization.

Security requires two distinct layers:

Framework Responsibility

• Enforces hard storage boundaries.
• Rejects any path traversal attempt that escapes the configured storage disk root with PathTraversalDetected.

Application Responsibility

• Input Validation: Never pass raw user-supplied strings directly to filesystem APIs without validating against an allowed list or strict pattern.
• Access Authorization: Verify that the authenticated user owns or has permission to view the requested resource (e.g. via Gates or Policies).
• ID-Based Lookups: Prefer database IDs or UUIDs to locate files instead of exposing raw filesystem paths to the client.

4. Best Practice for Serving Private Files

Instead of accepting raw path strings from user input, store file metadata in your database and resolve files using secure model relationships:

use App\Models\Invoice;
use Illuminate\Support\Facades\Gate;

public function download(Invoice $invoice)
{
    // 1. Authorize user access
    Gate::authorize('view', $invoice);

    // 2. Resolve verified path stored internally in the database
    return Storage::disk('local')->download($invoice->storage_path);
}

Summary

• Storage::path() in Laravel 13.30 normalizes path strings and prevents traversal beyond the disk root.
• Throws Illuminate\Filesystem\PathTraversalDetected when a path attempts to escape the storage root.
• If running Laravel versions prior to 13.30, be vigilant and manually validate paths with basename() or realpath() checks.
• Protects against malicious query parameters, route arguments, and JSON payloads.
• Serves as defense in depth alongside proper input validation and user authorization.

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.

Laravel Collections support higher-order messages through dynamic properties, allowing operations like each, map, filter, and groupBy to work directly with an item's property or method without writing boilerplate callbacks.

When manipulating collections in Laravel, developers frequently pass anonymous functions that do nothing more than read a single object property or invoke a single method.

Writing boilerplate closures for simple property forwarding adds unnecessary visual noise.

Laravel provides higher-order messages via proxy properties on collections, allowing you to access item attributes and methods directly on the collection itself.

The Core Concept: Removing Boilerplate Callbacks

Consider grouping a collection of orders by their status:

Before

$orders->groupBy(function (Order $order) {
    return $order->status;
});

After

$orders->groupBy->status;

The closure existed only to access the status property. With higher-order messages, Laravel intercepts the property access and applies it to each item in the collection automatically.

How Higher-Order Messages Work

Higher-order messages are accessed as dynamic properties on the Collection instance ($collection->methodName->target).

Behind the scenes, Laravel returns a HigherOrderCollectionProxy instance. When you access a property or call a method on this proxy, Laravel applies that operation to each item during the collection loop:

$collection->each->markAsVip()
         ↓
HigherOrderCollectionProxy
         ↓
Loops items and invokes $item->markAsVip()

Property Access vs. Method Calls

Depending on the collection method and what each item exposes, higher-order messages can forward either a property access or a method invocation:

1. Reading an Attribute (Property Access)

When accessing model attributes or array keys:

// Sum the total property across all orders
$totalRevenue = $orders->sum->total;

// Group items by category property
$groupedProducts = $products->groupBy->category;

// Sort users by created_at timestamp descending
$recentUsers = $users->sortByDesc->created_at;

2. Invoking an Action (Method Call)

When running a method on each item in the collection:

// Execute markAsVip() on each User instance
$users->each->markAsVip();

// Filter users where isActive() returns true
$activeUsers = $users->filter->isActive();

// Reject expired subscriptions
$validSubscriptions = $subscriptions->reject->isExpired();

Real-World Practical Examples

namespace App\Services;

use App\Models\Invoice;
use App\Models\User;
use Illuminate\Support\Collection;

class BillingService
{
    /**
     * @param Collection<int, User> $users
     */
    public function processVipMembers(Collection $users): void
    {
        // 1. Filter active users
        $activeVips = $users->filter->isVip();

        // 2. Perform an action on each
        $activeVips->each->sendVipNewsletter();
    }

    /**
     * @param Collection<int, Invoice> $invoices
     */
    public function summarizeInvoices(Collection $invoices): array
    {
        return [
            // Group invoices by payment status
            'by_status'     => $invoices->groupBy->status,
            // Calculate total unpaid balance
            'unpaid_total'  => $invoices->filter->isUnpaid()->sum->amount,
            // Find highest single invoice
            'max_invoice'   => $invoices->max->amount,
            // Extract unique customer IDs
            'customer_ids'  => $invoices->unique->customer_id->map->customer_id,
        ];
    }
}

Complete Supported Method Reference

Higher-order messages are supported across 23 Collection methods, organized by category:

// Aggregation: calculate values from a property or method.
$collection->average->property;
$collection->avg->property;
$collection->max->property;
$collection->min->property;
$collection->sum->property;

// Iteration: call methods or transform items without callbacks.
$collection->each->method();
$collection->map->property;
$collection->flatMap->method();

// Filtering: keep, remove, or check items using a property or method.
$collection->contains->method();
$collection->every->method();
$collection->filter->method();
$collection->reject->method();
$collection->some->method();

// Finding & grouping: locate, group, partition, or key items.
$collection->first->method();
$collection->groupBy->property;
$collection->keyBy->property;
$collection->partition->method();
$collection->unique->property;

// Sorting: order items using a property or method.
$collection->sortBy->property;
$collection->sortByDesc->property;

// Skipping & taking: include or skip items based on conditions.
$collection->skipUntil->method();
$collection->skipWhile->method();
$collection->takeUntil->method();
$collection->takeWhile->method();

When to Keep the Closure

Higher-order messages are designed for direct property reads and single method calls. If your callback involves custom logic, comparisons, or multi-step transformations, continue using standard closures:

// Keep a closure when custom business logic or conditionals are needed:
$orders->groupBy(function (Order $order) {
    return $order->total > 1000 ? 'tier_enterprise' : 'tier_standard';
});

// Keep a closure when multiple arguments or external variables are required:
$users->each(function (User $user) use ($notifier, $discountCode) {
    $notifier->sendCustomPromotion($user, $discountCode);
});

The general rule: Use higher-order messages when a callback only forwards a property or method; keep a closure when you need logic.

Summary

• Higher-order messages eliminate boilerplate closures across 23 Laravel Collection methods.
• Accessed via dynamic properties on the collection ($collection->filter->isActive()).
• Supports both property retrieval ($orders->sum->total) and method execution ($users->each->delete()).
• Keeps chained collection pipelines readable and concise without sacrificing clarity.

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.

Laravel 13.27 adds native vector distance query support for MariaDB 11.7+, enabling semantic search and similarity filtering directly through the query builder.

When building AI-powered features (such as semantic document search, recommendation engines, or RAG context retrieval), text is converted into high-dimensional vector embeddings and stored in your database.

Previously, running vector similarity searches in MariaDB required writing database-specific raw SQL statements with VEC_DISTANCE_EUCLIDEAN() or VEC_DISTANCE_COSINE().

Laravel 13.27 brings native vector query methods to MariaDB, allowing you to filter, sort, and calculate vector distances directly through Eloquent and the query builder.

The Query Builder Workflow

use App\Models\Document;

// User search query converted to float array embeddings
$queryEmbedding = [0.0124, -0.0432, 0.0891, ...];

$documents = Document::query()
    // Keep only sufficiently close vectors
    ->whereVectorDistanceLessThan('embedding', $queryEmbedding, maxDistance: 0.5)
    // Order results from closest to farthest
    ->orderByVectorDistance('embedding', $queryEmbedding)
    // Include the computed distance value in results
    ->selectVectorDistance('embedding', $queryEmbedding, as: 'distance')
    ->limit(10)
    ->get();

Vector Query Methods Explained

1. whereVectorDistanceLessThan()

Filters rows where the distance between the stored column vector and the query vector is below a specified threshold:

// Only match documents within 0.4 distance
$query->whereVectorDistanceLessThan('embedding', $queryEmbedding, maxDistance: 0.4);

2. orderByVectorDistance()

Sorts results by proximity to the query embedding. By default, it sorts in ascending order (asc) so the most relevant/closest vectors appear first:

// Closest records first
$query->orderByVectorDistance('embedding', $queryEmbedding, 'asc');

3. selectVectorDistance()

Calculates the exact distance score and attaches it as a virtual attribute on the returned model instance:

$document = Document::query()
    ->selectVectorDistance('embedding', $queryEmbedding, as: 'score')
    ->first();

echo $document->score; // e.g. 0.1428

Practical Scenario: Semantic Knowledge Base Search

User Search: "How do I configure Redis queues?"
     ↓
Embedding API (e.g. OpenAI / Ollama)
     ↓
Float Array: [0.012, -0.045, ...]
     ↓
MariaDB Vector Query (VEC_DISTANCE)
     ↓
Top 5 Relevant Help Articles

namespace App\Http\Controllers;

use App\Models\Article;
use App\Services\EmbeddingService;
use Illuminate\Http\Request;

class ArticleSearchController extends Controller
{
    public function __invoke(Request $request, EmbeddingService $embeddings)
    {
        $queryVector = $embeddings->generate($request->input('q'));

        $articles = Article::query()
            ->whereVectorDistanceLessThan('embedding', $queryVector, maxDistance: 0.45)
            ->orderByVectorDistance('embedding', $queryVector)
            ->selectVectorDistance('embedding', $queryVector, as: 'relevance_distance')
            ->limit(5)
            ->get();

        return response()->json($articles);
    }
}

The database executes the mathematical distance calculations internally using its native vector engine, returning only matching rows to PHP.

Database Requirements

• MariaDB Version: Requires MariaDB 11.7+, which introduces native VECTOR data types and vector distance functions.
• Column Definition: The target column in your migration should be configured to store vector data:

  Schema::create('documents', function (Blueprint $table) {
      $table->id();
      $table->string('title');
      $table->text('content');
      $table->vector('embedding', dimensions: 1536);
      $table->timestamps();
  });

---

## Summary

- Laravel 13.27 brings first-class vector query builder methods to MariaDB 11.7+.
- `whereVectorDistanceLessThan()` filters rows based on distance thresholds.
- `orderByVectorDistance()` sorts records by nearest similarity.
- `selectVectorDistance()` selects the computed score as a model attribute.
- Replaces raw `VEC_DISTANCE_*` SQL clauses with clean, fluent Eloquent methods.

Laravel 13.27 adds totalPendingSize(), totalDelayedSize(), and totalReservedSize() to the Queue facade, making it easy to aggregate queue metrics for dashboards and health checks.

When building admin panels, operational dashboards, or custom health-check endpoints, tracking queue volume across your application is a common requirement.

Prior to Laravel 13.27, Queue::size($queue) only reported pending counts for a single named queue. Getting total metrics across multiple queues required manually querying each individual queue and summing the counts in application code.

Laravel 13.27 introduces dedicated aggregate size helpers directly on the Queue facade.

1. Laravel 13.27 Total Size Helpers

use Illuminate\Support\Facades\Queue;

$pending = Queue::totalPendingSize();
// Jobs waiting to be processed.

$delayed = Queue::totalDelayedSize();
// Jobs intentionally delayed for later.

$reserved = Queue::totalReservedSize();
// Jobs currently reserved by workers.

2. Understanding Each Queue Metric

• totalPendingSize(): The total count of ready jobs waiting in queues to be claimed by worker processes. A sustained spike indicates worker starvation or backlog accumulation.
• totalDelayedSize(): The total count of jobs scheduled with delay() that are waiting for their release timestamp to expire before becoming pending.
• totalReservedSize(): The total count of jobs currently claimed and actively being executed by worker processes.

3. Practical Example: Lightweight Dashboard & Health Endpoints

These helpers make it simple to assemble lightweight queue health payloads without setting up heavy external monitoring packages:

namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Queue;

class QueueMetricsController extends Controller
{
    public function __invoke(): JsonResponse
    {
        $pending  = Queue::totalPendingSize();
        $delayed  = Queue::totalDelayedSize();
        $reserved = Queue::totalReservedSize();

        return response()->json([
            'status'   => $pending > 5000 ? 'degraded' : 'healthy',
            'metrics'  => [
                'pending'   => $pending,
                'delayed'   => $delayed,
                'reserved'  => $reserved,
                'total'     => $pending + $delayed + $reserved,
            ],
            'timestamp' => now()->toIso8601String(),
        ]);
    }
}

4. Querying Specific Connections

By default, the helpers aggregate metrics across the default queue connection. You can target specific connections when running multiple queue backends (like separate Redis and database queues):

use Illuminate\Support\Facades\Queue;

// Query a dedicated Redis queue connection
$redisPending = Queue::connection('redis')->totalPendingSize();

// Query a database fallback connection
$dbDelayed = Queue::connection('database')->totalDelayedSize();

(Note: These helpers provide fast aggregate totals for lightweight reporting. For detailed per-job telemetry, throughput graphs, and runtime tags, use Laravel Horizon or Laravel Pulse.)

Summary

• Queue::totalPendingSize() returns all jobs waiting to be processed.
• Queue::totalDelayedSize() returns all delayed jobs awaiting release.
• Queue::totalReservedSize() returns all jobs actively reserved by workers.
• Avoids manual multi-queue loop-and-sum aggregation.
• Supports chaining connection('name') for multi-backend setups.

Use git cherry-pick to apply specific commits from another branch to your current branch without merging the entire branch history.

When working across multiple feature branches, you often write a useful bug fix, documentation tweak, or isolated utility method on a feature branch that is still in development.

Merging the entire feature branch into main would pull in unfinished work and untested features.

Instead of manually copy-pasting the changes, git cherry-pick allows you to select a specific commit from any branch and apply its diff directly onto your current branch.

The Basic Workflow

# 1. Switch to the target branch that should receive the change
git checkout main

# 2. Apply the specific commit by its hash
git cherry-pick 4ecc3a3

# 3. Push the newly created commit to the remote repository
git push origin main

(Note: 4ecc3a3 is an example commit hash. Replace it with your actual commit SHA from git log.)

What Actually Happens?

feature-branch
    ├── commit A (WIP UI refactor)
    ├── commit B (Bug fix for auth redirect)  ← Need this on main
    └── commit C (WIP checkout page)

git checkout main
git cherry-pick <commit-B-hash>

main
    └── commit B' (New commit with identical diff, new SHA)

When you run git cherry-pick 4ecc3a3:

1. Git extracts the exact patch (diff) introduced by commit 4ecc3a3.
2. It applies those changes onto the working tree of your currently checked-out branch.
3. It creates a new commit with a new commit hash and timestamp on your current branch.

The original commit on the source branch remains untouched.

Cherry-Pick vs. Merge

Use git merge when an entire feature is finished and ready for integration. Use git cherry-pick when you need an isolated fix without bringing over the surrounding branch work.

Handling Conflicts

If the files modified by the cherry-picked commit have diverged significantly on your target branch, Git will pause and flag a conflict.

To resolve and continue:

# 1. Resolve conflict markers in your editor, then stage the resolved files
git add .

# 2. Continue the cherry-pick operation
git cherry-pick --continue

To cancel and return to clean state:

# Aborts the cherry-pick and returns your branch to its pre-cherry-pick state
git cherry-pick --abort

Cherry-Picking Multiple Commits

You can also cherry-pick multiple commits in a single operation:

# Cherry-pick individual non-contiguous commits
git cherry-pick abc1234 def5678

# Cherry-pick a contiguous range of commits (from A up to B, exclusive of A)
git cherry-pick abc1234..def5678

# Cherry-pick a contiguous range including A (inclusive)
git cherry-pick abc1234^..def5678

Practical Scenarios

• Hotfixes on Production Branches: A bug was resolved on main or a develop branch and needs to be backported immediately to a live v1.x release branch.
• Accidental Commits: You accidentally committed a change to the wrong branch. You can cherry-pick it onto the correct branch and reset the original branch.
• Extracted Refactors: While building a long-running feature, you wrote a clean helper method that teammates need immediately on main.

Summary

• git cherry-pick <hash> applies the diff of a specific commit onto your current branch.
• Creates a new commit with its own unique SHA on the active branch without altering the original commit.
• Use git cherry-pick --continue after resolving merge conflicts, or git cherry-pick --abort to cancel.
• Avoids merging unfinished feature branches when only an isolated change is needed.

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.

Laravel 13.26 introduces ProcessIdleTimedOutException to distinguish idle processes from overall runtime timeouts, alongside new testing assertions for execution count and sequence order.

Running external shell processes and CLI commands in Laravel is handled by the Process facade. When managing long-running tasks such as deployment scripts, data exports, or media processing, diagnosing process failures and writing comprehensive automated tests are critical requirements.

Laravel 13.26 improves the Process facade in two core areas:

1. Granular Timeout Exceptions: Differentiating between silent/idle processes and processes that exceed total execution time.
2. Enhanced Process Fakes: New test assertions for process execution count (assertRanCount), sequence ordering (assertRanInOrder), and recorded interaction inspection (recorded()).

1. Overall Timeout vs. Idle Timeout

When executing an external command, two distinct timeout conditions can occur:

• Overall Timeout (timeout): The maximum total duration the process is allowed to run from start to finish.
• Idle Timeout (idleTimeout): The maximum allowed duration without the process emitting any standard output (stdout or stderr).

Before Laravel 13.26, exceeding either limit threw the generic Illuminate\Process\Exceptions\ProcessTimedOutException. In Laravel 13.26, idle timeouts trigger a dedicated exception: Illuminate\Process\Exceptions\ProcessIdleTimedOutException.

Differentiating Process Failures

use Illuminate\Process\Exceptions\ProcessIdleTimedOutException;
use Illuminate\Process\Exceptions\ProcessTimedOutException;
use Illuminate\Support\Facades\Process;

try {
    $result = Process::timeout(600)      // Total runtime limit: 10 minutes
        ->idleTimeout(30)               // Output inactivity limit: 30 seconds
        ->run('./deploy-services.sh');

    if ($result->successful()) {
        logger()->info('Deployment completed successfully.');
    }
} catch (ProcessIdleTimedOutException $e) {
    // The process stopped producing output for 30 seconds (e.g. waiting on a prompt or stuck in deadlock)
    logger()->error('Process stalled with no output: ' . $e->getMessage());
} catch (ProcessTimedOutException $e) {
    // The process continued producing output but exceeded the 10-minute overall limit
    logger()->error('Process exceeded total execution budget: ' . $e->getMessage());
}

This separation allows automated pipelines to take targeted recovery steps, such as terminating unresponsive processes immediately when idle while permitting active, progressing tasks to run up to their total timeout limit.

2. Process Fake Testing Assertions

Laravel's Process::fake() allows tests to mock process execution without executing actual shell commands. Laravel 13.26 adds dedicated assertion methods to inspect execution count, ordering, and recorded instances.

Asserting Execution Count with assertRanCount()

Process::assertRanCount() verifies the exact number of commands invoked during a test:

use Illuminate\Support\Facades\Process;

test('deployment command executes expected subprocesses', function () {
    Process::fake([
        'git pull' => Process::result('Already up to date.'),
        'composer install --no-dev' => Process::result('Installing dependencies...'),
        'php artisan migrate --force' => Process::result('Migrated successfully.'),
    ]);

    $this->artisan('app:deploy');

    // Asserts that exactly 3 processes were executed
    Process::assertRanCount(3);
});

This prevents subtle bugs where an unexpected branching condition executes a command multiple times or skips an intended execution silently.

Asserting Command Sequence with assertRanInOrder()

When external tasks depend on strict chronological execution (such as pulling latest source code before migrating database tables), Process::assertRanInOrder() verifies the exact sequence:

use Illuminate\Support\Facades\Process;

test('build pipeline executes steps in chronological sequence', function () {
    Process::fake();

    $this->artisan('app:build');

    // Asserts commands ran in this exact order
    Process::assertRanInOrder([
        'npm ci',
        'npm run build',
        'php artisan config:cache',
        'php artisan route:cache',
    ]);
});

Inspecting Recorded Results with recorded()

The Process::recorded() method returns a collection of all executed processes and their corresponding result objects. You can also pass a closure to filter and inspect specific process runs:

use Illuminate\Process\PendingProcess;
use Illuminate\Contracts\Process\ProcessResult;
use Illuminate\Support\Facades\Process;

test('inspects specific command payloads', function () {
    Process::fake();

    $this->artisan('reports:generate');

    // Filter recorded interactions
    $exportProcesses = Process::recorded(function (PendingProcess $process, ProcessResult $result) {
        return str_contains($process->command, 'mysqldump');
    });

    expect($exportProcesses)->toHaveCount(1);
});

Summary

• ProcessIdleTimedOutException: Catch output inactivity separately from total runtime timeouts via idleTimeout().
• Process::assertRanCount(): Assert the total number of process invocations in tests.
• Process::assertRanInOrder(): Verify strict chronological command execution order.
• Process::recorded(): Inspect and filter recorded process and result pairs using closures.

In Laravel 13.25, Request::all() now gives submitted input precedence over uploaded files when their keys collide, while file() continues to provide direct access to uploaded files.

When handling incoming HTTP requests containing both structured form fields and uploaded files, Laravel combines input data and file uploads into a unified collection when calling $request->all().

Laravel 13.25 updates the internal merge order inside Request::all() to ensure submitted input values take precedence whenever an input field and an uploaded file share the exact same key.

What Changed?

Under the hood, Laravel combines the input bag ($this->input()) and the uploaded files bag ($this->allFiles()).

Prior to Laravel 13.25, the merge order placed files second:

// Before Laravel 13.25
array_replace_recursive($this->input(), $this->allFiles());

In Laravel 13.25, this order is reversed so input is merged last:

// Laravel 13.25+
array_replace_recursive($this->allFiles(), $this->input());

This ensures submitted input values win collisions across $request->all(), $request->only(), dynamic property access ($request->profile), and array access ($request['profile']).

Example: Colliding Input and Upload Keys

Consider a request containing a nested profile.name text field alongside an uploaded file also named profile.name:

use Illuminate\Http\Request;

$request = Request::create('/', 'POST', [
    'profile' => [
        'name' => 'Punyapal',
    ],
], [], [
    'profile' => [
        'name' => $file,
        'avatar' => $avatar,
    ],
]);

// Before Laravel 13.25
// Files were merged last, so a colliding file replaced the input.
$request->all();
// profile.name => UploadedFile

// Laravel 13.25
// Input is merged last, so the submitted value takes precedence.
$request->all();
// profile.name => 'Punyapal'
// profile.avatar => UploadedFile

// Need the uploaded file? file() still returns it.
$request->file('profile.name');
// UploadedFile

Uploaded Files Remain Accessible via file()

This change only alters key collisions inside $request->all() and related helper methods. Laravel does not discard the uploaded file.

When you need the uploaded file instance, the dedicated $request->file() API is completely unaffected and continues to return the UploadedFile object directly:

$avatar = $request->file('profile.name');

Nested Recursive Merging

Because Laravel uses array_replace_recursive(), precedence only applies to specific keys that collide:

• profile.name exists in both input and files, so the submitted string 'Punyapal' takes precedence in all().
• profile.avatar exists only in the files bag, so it continues to appear in $request->all() as an UploadedFile without interference.

Summary

Request::all() now prefers submitted input values over files when key collisions occur, while $request->file() remains the dedicated way to retrieve uploaded files.

DocSmith is a lightweight PHP tool that compiles Markdown directories into responsive, searchable, SEO-friendly static documentation websites with zero frontend configuration.

Writing technical documentation in Markdown is straightforward, but transforming those files into a searchable, responsive website often introduces complex JavaScript static site generators, node build pipelines, or heavy CMS platforms.

mrpunyapal/docsmith is a native PHP library and standalone CLI tool that compiles a directory of Markdown files directly into clean static HTML pages with built-in dark mode, dual-theme syntax highlighting, search, and AI-ready exports.

You can explore a live example of a site generated with DocSmith at mrpunyapal.github.io/docsmith.

How DocSmith Works

DocSmith follows a straightforward static compilation pipeline:

Markdown Files (docs/)
          ↓
DocSmith Engine
├── Frontmatter parsing and document discovery
├── League CommonMark (GFM) + Phiki syntax highlighting
├── Navigation tree generation and custom ordering
└── Search index, sitemap, and LLM text generation
          ↓
Static HTML Documentation Site (dist/)

1. Source Discovery: Scans your documentation directory and parses YAML frontmatter metadata.
2. Markdown Rendering: Converts Markdown through League CommonMark with GitHub-flavored Markdown extensions.
3. Syntax Highlighting: Renders server-side code syntax highlighting using Phiki with GitHub Light and Dark themes.
4. Site Assembly: Injects navigation, table of contents, search overlays, and responsive mobile drawers.
5. Asset & Metadata Publishing: Emits static assets, search-index.json, sitemap.xml, llms.txt, and .nojekyll.

Installation and Quick Start

DocSmith requires PHP 8.3 or newer and Composer:

composer require --dev mrpunyapal/docsmith

1. Build via CLI

DocSmith ships with a standalone binary at vendor/bin/docsmith:

vendor/bin/docsmith build --source=md --output=docs --title="Package Docs"

2. Build via PHP API

You can also run builds directly within PHP build scripts using the static entry point or fluent builder:

use Docsmith\Docsmith;

Docsmith::make()
    ->source(__DIR__ . '/md')
    ->output(__DIR__ . '/dist')
    ->title('Acme Cache Docs')
    ->description('High-performance caching library for PHP.')
    ->accentColor('#ff2d20')
    ->accentColorDark('#ff6b61')
    ->siteUrl('https://acme.github.io/cache')
    ->repositoryUrl('https://github.com/acme/cache')
    ->rightSidebar()
    ->build();

Organizing Markdown Files

DocSmith maps your Markdown files directly to clean static URLs:

md/
├── index.md                    →  docs/index.html
├── installation.md             →  docs/installation/index.html
├── configuration.md            →  docs/configuration/index.html
└── usage/
    ├── basics.md               →  docs/usage/basics/index.html
    └── advanced.md             →  docs/usage/advanced/index.html

If your source directory does not contain an index.md, DocSmith automatically generates a clean landing page listing all available documentation sections.

Frontmatter Options

Each Markdown file can include YAML frontmatter to control page metadata and navigation:

---
title: Advanced Configuration
description: Fine-tune caching drivers, timeouts, and memory limits.
sidebar_label: Configuration
order: 3
hidden: false
---

# Advanced Configuration

• title: Page title displayed in browser tabs and navigation.
• description: Meta description used for SEO and search snippets.
• sidebar_label: Shorter label displayed in the sidebar menu.
• order: Numeric sort priority.
• hidden: When set to true, the page is rendered to HTML but omitted from the sidebar, search index, and previous/next pagination.

Customizing Sidebar Navigation Order

By default, pages appear in alphabetical or frontmatter-defined order. You can set an explicit sequence using navigationOrder():

Docsmith::make()
    ->source(__DIR__ . '/md')
    ->output(__DIR__ . '/dist')
    ->navigationOrder([
        'Introduction',
        'Installation',
        'Configuration',
        'Basic Usage',
        'Advanced Usage',
    ])
    ->build();

Entries can match page titles, sidebar_label properties, or relative Markdown paths. Unlisted pages retain their natural position after ordered items.

Polished Reading Experience

DocSmith generates standalone, zero-dependency HTML with built-in UX features:

1. Dual-Theme Syntax Highlighting

Code blocks are highlighted during static compilation using Phiki, emitting token styles for both light and dark backgrounds without client-side highlighting libraries:

use Acme\Cache\Repository;

$cache = new Repository(driver: 'redis');
$cache->set('user:42', $user, ttl: 3600);

Each code block includes a 1-click clipboard copy button.

2. Light and Dark Theme Modes

The site includes a theme toggle that automatically detects system color scheme preferences (prefers-color-scheme) and persists manual user selections via localStorage.

3. Responsive Navigation & Tables

• Mobile layouts include a sliding navigation drawer with touch backdrop support.
• Wide Markdown tables are automatically wrapped in <div class="table-scroll"> containers to prevent viewport overflow on smaller screens.
• An optional right sidebar (->rightSidebar()) extracts page headings into an active Table of Contents.

Built-In Search & Modal Overlay

DocSmith builds a static search-index.json during compilation containing page titles, descriptions, section headings, and content text:

• Sidebar Filter: Instantly filters sidebar navigation links as you type.
• Global Search Overlay: Press Cmd+K (macOS) or Ctrl+K (Windows/Linux) or click the search bar to launch a modal search dialog with full content matching.

Multi-Version Documentation

For libraries maintaining multiple major releases, DocSmith provides multi-version builds with a header version switcher:

Docsmith::make()
    ->source(__DIR__ . '/md')
    ->output(__DIR__ . '/dist')
    ->versions([
        'v1' => ['label' => 'v1.x', 'source' => __DIR__ . '/md/v1', 'default' => true],
        'v2' => ['label' => 'v2.x', 'source' => __DIR__ . '/md/v2'],
    ])
    ->build();

• The default version outputs directly to the root (/installation/index.html).
• Secondary versions output to versioned subpaths (/v2/installation/index.html).
• A version switcher dropdown is automatically rendered in the header navigation.

AI-Ready Documentation Exports

DocSmith automatically exports documentation in formats structured for LLMs, coding agents, and automated workflows:

AI exports are enabled by default and can be toggled using ->llmsExport(false).

Open Graph Social Cards

DocSmith can generate Open Graph preview images using Playwright and capturist:

Docsmith::make()
    ->source(__DIR__ . '/md')
    ->output(__DIR__ . '/docs')
    ->siteUrl('https://acme.github.io/cache')
    ->ogGeneratedAll() // Generates docs/og/cover.png
    ->build();

You can generate a single shared social cover or individual cards per page (->ogGeneratedPerPage()), with support for custom HTML card templates (->ogTemplate(...)).

Real-World Example: Package Documentation Script

Here is a complete build-docs.php script for a PHP package:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use Docsmith\Docsmith;

Docsmith::make()
    ->source(__DIR__ . '/docs')
    ->output(__DIR__ . '/dist')
    ->title('AuditLogger PHP')
    ->description('Immutable audit logging and security tracing for PHP applications.')
    ->accentColor('#0284c7')
    ->accentColorDark('#38bdf8')
    ->siteUrl('https://acme.github.io/audit-logger')
    ->repositoryUrl('https://github.com/acme/audit-logger')
    ->editBranch('main')
    ->rightSidebar()
    ->navigationOrder([
        'Getting Started',
        'Installation',
        'Configuration',
        'Logging Events',
        'Custom Formatters',
    ])
    ->build();

echo "Documentation built successfully in dist/\n";

Add a Composer shortcut to composer.json:

"scripts": {
    "docs:build": "@php build-docs.php"
}

Summary

DocSmith provides a focused, native PHP solution for turning Markdown into production-ready static documentation sites:

• Zero Node Runtime: Compiles complete HTML sites natively in PHP without requiring node modules or complex JavaScript build tools.
• Built-in Essentials: Includes dark mode, Phiki syntax highlighting, search index generation, mobile navigation, and LLM text exports out of the box.
• Hosting Agnostic: Generates clean static folders compatible with GitHub Pages (.nojekyll), Cloudflare Pages, Netlify, and Vercel.
• Live Documentation: View a live production example at mrpunyapal.github.io/docsmith.
• GitHub Repository: MrPunyapal/DocSmith

Laravel 13.25 upgrades php artisan dev with @laravel/multiplex to provide a tabbed terminal UI with process search, restarts, and log management.

Running composer run dev or php artisan dev manages multiple development processes in parallel, such as the PHP development server, queue workers, log streaming with Pail, and asset compilation with Vite.

Previously, all active processes wrote their output concurrently into a single shared scrolling terminal window, making it difficult to isolate specific server logs or track build errors.

Laravel 13.25 upgrades php artisan dev to use @laravel/multiplex as its terminal interface on supported platforms, giving each development process its own dedicated tab and interactive controls.

What the Multiplex UI Provides

The updated terminal interface organizes concurrent processes into distinct views and introduces several process management features:

• Tabbed process views: Each registered command (HTTP server, Vite, Queue, Pail) runs in its own tab, selectable with keyboard shortcuts.
• Searchable output: Filter and search through process logs directly in the terminal interface.
• Individual process restarts: Restart a specific process (such as a queue worker) without restarting your entire development environment.
• Log clearing: Clear the log buffer for any individual process window.
• Automatic crash recovery: Processes that fail or crash can automatically restart in the background.
• Exit log preservation: When stopping artisan dev, buffered logs from each process are printed to the main terminal so recent errors are preserved.

┌─────────────────────────────────────────────────────────┐
│  Laravel Dev                                            │
├──────────────┬──────────────────────────────────────────┤
│ ● Server     │                                          │
│ ● Queue      │   [active process output]                │
│ ● Pail       │                                          │
│ ● Vite       │   ...                                    │
├──────────────┴──────────────────────────────────────────┤
│ Search  │ Restart │ Clear │ ...                         │
└─────────────────────────────────────────────────────────┘

CLI Usage and Output Modes

You can run artisan dev with flags to customize output formatting and runtime behavior:

# Start all dev processes with tabbed Multiplex UI
composer run dev

# Or run directly via Artisan
php artisan dev

# Fall back to interleaved streaming output
php artisan dev --stream

# Prepend timestamps to log output lines
php artisan dev --timestamps

# Prevent crashed processes from automatically restarting
php artisan dev --no-restart

php artisan dev supports three distinct output modes:

1. tabs (default): Interactive tabbed interface powered by @laravel/multiplex.
2. stream: Traditional interleaved terminal stream where all process logs appear in one combined feed.
3. inline: Plain non-interactive output, activated automatically when running without an interactive TTY (such as in CI or scripted environments).

Configuring DevCommands in PHP

In addition to CLI flags, you can configure default development process behavior globally using the Illuminate\Foundation\DevCommands facade:

use Illuminate\Foundation\DevCommands;

// Configure runtime options introduced in Laravel 13.25
DevCommands::stream();
DevCommands::withTimestamps();
DevCommands::disableAutoRestart();
DevCommands::bufferSize(5000);

These configuration helpers complement existing process registration methods (such as DevCommands::register(), artisan(), node(), only(), and except()), allowing teams to enforce consistent local development defaults across an entire project.

Platform and Node.js Requirements

The @laravel/multiplex interface has specific platform prerequisites:

• Supported Platforms: macOS and Linux.
• Windows Support: On Windows environments, php artisan dev automatically falls back to concurrently streaming.
• Node.js Version: The Multiplex path requires Node.js v22.13 or newer.

Call env() only inside configuration files and use config() throughout your application code to prevent missing values when configuration is cached.

A foundational Laravel convention is keeping env() calls confined strictly to files in the config/ directory while reading settings across controllers, services, and models via config().

The Common Mistake

It is tempting to read environment variables directly inside application code:

// ❌ Don't call env() directly in application code
$stripeKey = env('STRIPE_KEY');

While this works during local development when .env is loaded on every request, it breaks in production when configuration caching is enabled.

The Laravel Way

Environment variables should be accessed inside configuration files, and application code should read from Laravel's configuration repository:

// config/services.php
return [
    'stripe' => [
        'key' => env('STRIPE_KEY'),
    ],
];

Application code then retrieves the setting through config():

// ✅ Read the configured value
$stripeKey = config('services.stripe.key');

The application does not need to know where the value originated; it accesses the value through Laravel's unified configuration repository.

Why config:cache Matters

In production, optimizing performance involves running:

php artisan config:cache

Once configuration is cached, Laravel combines all files in config/*.php into a single cached file and ignores the .env file during requests and Artisan commands.

When .env is not loaded:

• config('services.stripe.key') reads the compiled value from the configuration cache.
• Calling env('STRIPE_KEY') directly in application code bypasses the configuration cache and returns null, unless an external operating system environment variable of the same name is explicitly defined on the host server.

Enforce It with Pest

You can enforce this convention automatically using a Pest architecture test:

// tests/ArchitectureTest.php
arch('globals')
    ->expect(['env'])
    ->not->toBeUsed();

This test flags any direct env() usage in your application code before code is merged or deployed.

Catch It with Larastan

Larastan includes static analysis rules to detect env() usage outside configuration files.

The larastan.noEnvCallsOutsideOfConfig rule (enabled by default in Larastan 3.x) analyzes your codebase and reports violations:

Called 'env' outside of the config directory which returns null when the config is cached, use 'config'.

Quick Rule

.env → env() → config/*.php → config() → application code

• env() belongs in config/*.php files.
• config() belongs everywhere else in application code.

Laravel 13.25 adds Image::fromStream(), makes toFormat() public, and pairs with toResponse() to process uploaded images and return them directly as HTTP responses.

When handling user uploads, processing an image and returning a converted preview often involves reading files from streams rather than saving intermediate files to disk. Laravel 13.25 updates the Image API with stream support, making it straightforward to load, convert, and respond in a single flow.

Process an Uploaded Image

Here is a controller action that reads an uploaded image stream, converts it to WebP, and returns the converted image directly as an HTTP response:

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Image;

class ImagePreviewController extends Controller
{
    public function preview(Request $request): Response
    {
        // Create the image directly from the uploaded file stream.
        $image = Image::fromStream(
            $request->file('image')->readStream()
        );

        // Convert the image to WebP.
        $image->toFormat('webp');

        // Return the processed image as an HTTP response.
        return $image->toResponse();
    }
}

What Each Method Does

Image::fromStream()

Laravel 13.25 introduces Image::fromStream(), allowing you to instantiate an image directly from a readable stream resource such as $request->file('image')->readStream():

$image = Image::fromStream(
    $request->file('image')->readStream()
);

This reads the stream directly without requiring the uploaded file to be permanently stored on disk first.

toFormat()

In Laravel 13.25, toFormat() is now public on the image instance, allowing you to convert the in-memory image representation to a target format such as WebP, PNG, or JPEG:

$image->toFormat('webp');

Calling toFormat() updates the image format in memory without writing it to storage.

toResponse()

toResponse() converts the processed image into an Illuminate\Http\Response instance with the appropriate Content-Type header (such as image/webp):

return $image->toResponse();

The Flow

Uploaded file
    ↓
fromStream()
    ↓
toFormat('webp')
    ↓
toResponse()

This pattern is useful for on-the-fly preview endpoints, format conversion APIs, or serving dynamically formatted image responses directly from uploaded requests.

Use DB::getSchemaState()->load() to load large reference SQL dump files in seeders, with DB::unprepared(file_get_contents(...)) as a fallback for older Laravel versions.

When seeding large static reference datasets such as countries, states, cities, or timezones, writing thousands of individual Eloquent create() or insert() calls adds unnecessary overhead. Developers frequently store these datasets as raw .sql files inside their repository and load them during database seeding.

The Common Approach

A standard way to execute an external SQL file is reading its contents into PHP memory and executing the raw query buffer with DB::unprepared():

use Illuminate\Support\Facades\DB;

DB::unprepared(
    file_get_contents(database_path('seeders/sql/world.sql'))
);

This approach works by having file_get_contents() read the entire SQL dump into a PHP string variable, which is then passed to PDO via DB::unprepared(). For very large SQL files, loading the entire file into PHP memory first can consume significant memory allocations.

Prefer SchemaState When Available

In Laravel versions that support schema state inspection, you can load the SQL file using DB::getSchemaState()->load():

use Illuminate\Support\Facades\DB;

DB::getSchemaState()->load(
    database_path('seeders/sql/world.sql')
);

Instead of requiring application code to read the complete SQL file into a PHP string in memory, getSchemaState()->load() delegates the file path directly to Laravel's database-specific schema state implementation.

Older Laravel Projects

For projects running on older Laravel versions where DB::getSchemaState()->load() is not available, DB::unprepared(file_get_contents(...)) remains a reliable and practical solution. There is no need to restructure working seeders on older installations unless you encounter memory limits during data loading.

Example Seeder

Here is how a dedicated reference dataset seeder looks using the preferred approach:

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\DB;

class WorldSeeder extends Seeder
{
    public function run(): void
    {
        DB::getSchemaState()->load(
            database_path('seeders/sql/world.sql')
        );
    }
}

If your project requires compatibility with older Laravel releases, the fallback pattern can be used inside the same seeder:

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\DB;

class WorldSeeder extends Seeder
{
    public function run(): void
    {
        DB::unprepared(
            file_get_contents(
                database_path('seeders/sql/world.sql')
            )
        );
    }
}

Use isDirty() and isClean() before saving to inspect unsaved in-memory mutations, and use wasChanged() and getOriginal() after saving to verify persisted changes and access previous values.

When updating Eloquent models, tracking whether specific attributes have changed depends on whether the model has already been saved to the database. Laravel provides dedicated helper methods tailored for checking model state before and after saving.

Inspecting Changes Before Saving

Before calling save(), changes exist only in memory on the model instance.

• isDirty(): Returns true if any attribute (or a specified attribute) has been modified since the model was loaded from the database.
• isClean(): The inverse of isDirty(). Returns true if an attribute remains unchanged.

$user->name = 'Punyapal';

// Before saving: check current unsaved changes
$user->isDirty('name');  // true
$user->isClean('email'); // true

Inspecting Changes After Saving

Once save() executes, the model synchronizes its in-memory attributes with the database. At this point, calling isDirty() returns false because there are no longer any unsaved modifications.

To inspect what changed during the save operation, use wasChanged() and getOriginal():

• wasChanged(): Returns true if an attribute was updated during the most recent save() call.
• getOriginal(): Retrieves the attribute value as it was before mutations or before the save occurred.

$user->save();

// After saving: check what changed during the last save
$user->wasChanged('name');  // true
$user->wasChanged('email'); // false

// Retrieve the original value
$user->getOriginal('name'); // previous name

Practical Example: Email Verification & Notifications

A common practical use case is resetting email verification when an email address changes and sending a verification notification after saving:

use App\Models\User;

$user = User::find(1);
$user->email = 'new-email@example.com';

// 1. Before saving: reset verification timestamp if email changed
if ($user->isDirty('email')) {
    $user->email_verified_at = null;
}

$user->save();

// 2. After saving: send verification notification only if email changed
if ($user->wasChanged('email')) {
    $user->sendEmailVerificationNotification();
}

This pattern ensures that:

1. isDirty('email') modifies companion in-memory attributes so both columns are written in a single database UPDATE query.
2. wasChanged('email') triggers external side effects (like sending emails) only after the changes have been successfully persisted.

Key Takeaways

• Use isDirty() and isClean() prior to persistence to conditionally run validation or assign companion attributes.
• Use wasChanged() inside model events, observers, or service classes after calling save() to dispatch notifications only when relevant fields change.
• Pass attribute names as arguments (for example, isDirty('email') or wasChanged('email')) to check specific columns rather than the entire model.
• Use getOriginal('column') when you need the previous value for audit logging or old-vs-new comparison.

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.

A categorized reference of the most useful constants in PHP with descriptions, error masks, and sample outputs for PHP 8.3 and PHP 8.4.

PHP provides built-in constants for filesystem operations, compile-time metadata, runtime environment information, error levels, and stream handles. These constants are available globally without importing namespaces or requiring setup.

Filesystem and Path Constants

Magic Compile-Time Constants

Magic constants are resolved at compile time, introducing zero runtime performance overhead:

PHP Environment and System Limits

Error Reporting Masks

File Upload Error Codes

When processing $_FILES['upload']['error'], compare against these constants instead of magic numbers:

CLI Stream Constants

Available automatically in Command Line Interface (CLI) scripts:

Summary

• Use PHP_OS_FAMILY instead of comparing against individual PHP_OS strings for cross-platform compatibility.
• Use UPLOAD_ERR_* constants when handling file uploads for descriptive error checking.
• Leverage magic constants (__DIR__, __CLASS__, __METHOD__) for zero-overhead compile-time introspection.

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.

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.

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.

A reference guide to scalar, compound, special, user-defined, union, and intersection types in modern PHP.

PHP features a gradual and expressive type system. From scalar type declarations introduced in PHP 7 to union types in PHP 8.0, intersection types in PHP 8.1, and standalone true, false, and null types in PHP 8.2, PHP provides reliable type safety at runtime and compile time.

1. Atomic and Scalar Types

Scalar types represent basic primitive values:

// Scalar Types
$active   = true;              // bool (or literal true / false)
$quantity = 42;                // int
$price    = 19.99;             // float
$name     = 'Punyapal';        // string

// Built-in Special Types
$empty    = null;              // null
$items    = [1, 2, 3];         // array
$payload  = new stdClass();    // object
$handle   = fopen('php://memory', 'r+'); // resource

2. Special Return Types

PHP supports specialized return types that describe function termination and inheritance contexts:

// void: Function executes without returning a value
function logMessage(string $msg): void
{
    echo $msg;
}

// never: Function always exits or throws an exception, never finishing normally
function abortWithError(string $error): never
{
    throw new RuntimeException($error);
}

// Relative Class Types
class Model
{
    // self: Returns an instance of the exact class where the method is defined
    public function createSelf(): self
    {
        return new self();
    }

    // static: Returns an instance of the calling class (respects Late Static Binding)
    public static function make(): static
    {
        return new static();
    }
}

class User extends Model
{
    // parent: References the immediate parent class
    public function getBaseModel(): parent
    {
        return new parent();
    }
}

3. User-Defined Types

Types created within application domain code:

// Interfaces
interface Notifiable
{
    public function notify(): void;
}

// Concrete Classes
class Invoice implements Notifiable
{
    public function notify(): void {}
}

// Backed & Pure Enums (PHP 8.1+)
enum OrderStatus: string
{
    case Draft = 'draft';
    case Paid  = 'paid';
}

4. Callables and Invocations

// Closure or invokable class instance
function executeTask(callable $task): void
{
    $task();
}

executeTask(fn () => print("Task completed\n"));

5. Composite Types: Unions and Intersections

Union Types (A|B)

Allows an argument or return value to satisfy any of the listed types:

function findUser(int|string $identifier): ?User
{
    return is_int($identifier)
        ? User::find($identifier)
        : User::where('email', $identifier)->first();
}

Intersection Types (A&B)

Requires an object to satisfy all listed interfaces simultaneously:

interface HasId { public function getId(): int; }
interface HasName { public function getName(): string; }

function displayEntity(HasId&HasName $entity): string
{
    return "#{$entity->getId()}: {$entity->getName()}";
}

Disjunctive Normal Form (DNF) Types (PHP 8.2+)

Combines Union and Intersection types using parentheses:

// Accepts (HasId AND HasName) OR null
function formatRecord((HasId&HasName)|null $record): string
{
    return $record ? displayEntity($record) : 'Anonymous';
}

6. Top Types: mixed and iterable

// mixed: Equivalent to array|bool|callable|int|float|null|object|resource|string
function debugValue(mixed $value): void
{
    var_dump($value);
}

// iterable: Accepts both arrays and objects implementing Traversable (like Generators or Collections)
function processBatch(iterable $items): void
{
    foreach ($items as $item) {
        // ...
    }
}

Summary

• Use scalar and atomic types (int, string, bool, float) for basic primitives.
• Use void when no value is returned, and never for methods that always terminate or throw.
• Use static return types for fluent chaining and late static binding in parent classes.
• Use Union types (int|string) and Intersection types (InterfaceA&InterfaceB) for precise polymorphic contracts.
• Use iterable to accept both arrays and Traversable collections directly.

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.

Refactor fat controller methods by moving multi-step transactions, file storage, and third-party integrations into invokable Action classes.

When a controller handles file uploads, payment transactions, database record creation, and email notifications in a single method, testing individual business steps becomes difficult and duplicates logic across CLI commands or API endpoints.

Moving domain logic into dedicated, invokable Action classes creates modular, reusable application layers.

Fat Controller (Anti-Pattern)

public function store(StoreOrderRequest $request)
{
    // ❌ Fat controller mixing validation, billing, file storage, and events
    $payment = Stripe::charges()->create([...]);
    $order = Order::create([...]);
    $invoicePdf = PDF::generate($order);
    Storage::disk('s3')->put("invoices/{$order->id}.pdf", $invoicePdf);
    Mail::to($request->user())->send(new OrderConfirmation($order));

    return to_route('orders.show', $order);
}

Refactored Action Class

namespace App\Actions\Orders;

use App\Models\Order;
use App\Models\User;
use Illuminate\Support\Facades\DB;

class CreateOrderAction
{
    public function __construct(
        protected PaymentGateway $gateway,
        protected InvoiceGenerator $invoices
    ) {}

    public function execute(User $user, array $orderData, string $paymentToken): Order
    {
        return DB::transaction(function () use ($user, $orderData, $paymentToken) {
            $charge = $this->gateway->charge($user, $orderData['total'], $paymentToken);
            $order = $user->orders()->create([...$orderData, 'transaction_id' => $charge->id]);
            $this->invoices->generateAndStore($order);

            return $order;
        });
    }
}

Skinny Controller

public function store(StoreOrderRequest $request, CreateOrderAction $action)
{
    $order = $action->execute(
        $request->user(),
        $request->validated(),
        $request->input('payment_token')
    );

    return to_route('orders.show', $order)->with('success', 'Order created.');
}

Summary

• Action classes isolate core business rules from HTTP transport details.
• Reusable across web controllers, API endpoints, queue workers, and Artisan commands.
• Easily testable with isolated unit test mocks.

A complete reference guide to Laravel community naming conventions across models, controllers, migrations, relationships, routes, views, enums, and tests.

Following standard naming conventions allows Laravel's internal reflection engines (including route model binding, Eloquent relation resolution, and migration schema builders) to function automatically without manual configuration.

Complete Naming Conventions Cheat Sheet

Why Conventions Matter

1. Automatic Relation Resolution: Eloquent infers foreign keys and pivot tables automatically without requiring manual string parameters.
2. Implicit Route Model Binding: Type-hinting Article $article on /articles/{article} resolves the model with zero controller boilerplate.
3. Consistency: Engineers moving between Laravel projects immediately know where files live and how methods are named.

Summary

• Eliminates redundant $table, $primaryKey, and relationship foreign key parameters.
• Guarantees predictable codebase navigation across development teams.
• Follows standard PHP-FIG PSR-12 and Laravel framework conventions.

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.

Automatically broadcast WebSocket events to private user channels whenever a database notification is saved using an observer on Laravel's DatabaseNotification model.

Laravel's notification system supports both database persistence (via: ['database']) and real-time broadcasting (via: ['broadcast']). However, configuring notifications to broadcast simultaneously often duplicates payload formatting and requires configuring separate broadcast channels for each notification class.

By attaching an observer to Laravel's underlying DatabaseNotification model, you can automatically broadcast every database notification in real time over private channels with zero per-notification boilerplate.

1. Register the Observer in AppServiceProvider

namespace App\Providers;

use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Notifications\DatabaseNotification;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        DatabaseNotification::observe(new class {
            public function created(DatabaseNotification $notification): void
            {
                broadcast(new class($notification) {
                    public function __construct(
                        public DatabaseNotification $notification
                    ) {}

                    public function broadcastOn(): PrivateChannel
                    {
                        // Derives channel from notifiable type (e.g. 'users.42')
                        $type = strtolower(class_basename(str($this->notification->notifiable_type)->plural()));
                        return new PrivateChannel("{$type}.{$this->notification->notifiable_id}");
                    }

                    public function broadcastAs(): string
                    {
                        return 'DatabaseNotificationCreated';
                    }
                });
            }
        });
    }
}

2. Listening with Laravel Echo (Frontend)

In your client-side JavaScript or Alpine.js component, subscribe to the user's private channel:

Echo.private(`users.${userId}`)
    .listen('.DatabaseNotificationCreated', (e) => {
        console.log('New notification received:', e.notification);
    });

3. Listening in Livewire Components

In Livewire 3 components, use the #[On] attribute:

namespace App\Livewire;

use Livewire\Attributes\On;
use Livewire\Component;

class NotificationBell extends Component
{
    #[On('echo-private:users.{userId},.DatabaseNotificationCreated')]
    public function onNotificationReceived(array $payload): void
    {
        $this->dispatch('refreshNotifications');
    }
}

Summary

• Observe DatabaseNotification::created to automatically broadcast real-time events for every stored database notification.
• Eliminates the need to duplicate broadcast payload definitions in individual notification classes.
• Directly integrates with Laravel Echo, Livewire, and Vue/React frontend architectures.

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.

Replace cumbersome ternary operators in HTML form inputs with Laravel's @checked and @selected Blade directives.

Conditionally adding checked or selected attributes to checkboxes, radio buttons, and select dropdowns usually requires repetitive inline PHP or ternary expressions:

<!-- Old verbose syntax -->
<input type="checkbox" name="active" value="1" {{ old('active', $user->is_active) ? 'checked' : '' }}>

<option value="pro" {{ old('plan', $user->plan) === 'pro' ? 'selected' : '' }}>Pro</option>

Laravel provides @checked and @selected to express this cleanly.

Using @checked for Checkboxes and Radio Buttons

<input 
    type="checkbox" 
    name="newsletter" 
    value="1" 
    @checked(old('newsletter', $user->subscribed_to_newsletter)) 
/>

If the evaluated expression is truthy, Laravel outputs checked="checked". If falsy, nothing is rendered.

Using @selected for Dropdown Options

<select name="status">
    <option value="draft" @selected(old('status', $post->status) === 'draft')>Draft</option>
    <option value="published" @selected(old('status', $post->status) === 'published')>Published</option>
    <option value="archived" @selected(old('status', $post->status) === 'archived')>Archived</option>
</select>

Also: @disabled and @readonly

Laravel also provides @disabled and @readonly directives:

<button type="submit" @disabled($cart->isEmpty())>
    Checkout
</button>

Summary

• Eliminates verbose ternary operators in HTML templates.
• Automatically handles boolean truth-testing and outputs appropriate HTML attributes.
• Works across checkboxes (@checked), select menus (@selected), and buttons (@disabled).

Add human-readable display labels to PHP 8.1+ enums automatically using a lightweight HasLabel trait without maintaining manual match statements.

When using backed Enums in Laravel models and Blade views, you often need a formatted, user-friendly label (such as displaying "Partially Paid and Refunded" for PaymentStatus::PartiallyPaidAndRefunded).

Maintaining manual match ($this) methods across dozens of application enums is repetitive. A lightweight trait can derive clean titles automatically while allowing custom overrides when needed.

The HasLabel Trait

namespace App\Traits;

trait HasLabel
{
    public function label(): string
    {
        // Convert case name (e.g. PARTIALLY_REFUNDED or PartiallyRefunded) to Title Case
        $clean = str_replace('_', ' ', $this->name);

        // Convert camelCase / PascalCase boundaries to spaced words
        $spaced = preg_replace('/(?<!^)[A-Z]/', ' $0', $clean);

        return ucwords(strtolower(trim($spaced)));
    }
}

Applying the Trait to Enums

namespace App\Enums;

use App\Traits\HasLabel;

enum PaymentStatus: int
{
    use HasLabel;

    case PENDING = 1;
    case FAILED = 2;
    case REFUNDED = 3;
    case PARTIALLY_REFUNDED = 4;
    case PARTIALLY_PAID = 5;
    case PAID = 6;
    case PARTIALLY_PAID_AND_REFUNDED = 7;
}

Usage in Controllers and Blade Views

use App\Enums\PaymentStatus;

PaymentStatus::PENDING->label();
// Output: "Pending"

PaymentStatus::PARTIALLY_REFUNDED->label();
// Output: "Partially Refunded"

PaymentStatus::PARTIALLY_PAID_AND_REFUNDED->label();
// Output: "Partially Paid And Refunded"

In Blade templates:

<span class="badge">
    {{ $order->payment_status->label() }}
</span>

Overriding Specific Labels

If a specific case requires specialized branding or wording that differs from the automated title, override the method:

enum InvoiceStatus: string
{
    use HasLabel;

    case DRAFT = 'draft';
    case SENT = 'sent';
    case OVERDUE = 'overdue';

    public function label(): string
    {
        return match ($this) {
            self::OVERDUE => 'Action Required: Overdue',
            default => $this->defaultLabel(),
        };
    }
}

Summary

• Use a HasLabel trait to generate consistent, human-friendly titles from enum case names automatically.
• Eliminates boilerplate match expressions across project enums.
• Easily customizable for specific localized or marketing terminology when needed.

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.

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.