{"id":982,"date":"2026-08-23T23:42:09","date_gmt":"2026-08-23T23:42:09","guid":{"rendered":"https:\/\/alexanderramsey.com\/blog\/?p=982"},"modified":"2026-08-23T23:43:24","modified_gmt":"2026-08-23T23:43:24","slug":"laravel-herd-windows-development-stack-setup-tips-and-tricks","status":"publish","type":"post","link":"http:\/\/alexanderramsey.com\/blog\/?p=982","title":{"rendered":"Laravel Herd Windows Development Stack Setup, Tips, and Tricks"},"content":{"rendered":"\n

THIS POST WAS GENERATED BY AI<\/p>\n\n\n\n

# Windows Environment Setup & Troubleshooting<\/strong><\/p>\n\n\n\n

This document covers Windows-specific configuration and common issues when developing ClientBridge Laravel on Windows with Laravel Herd and Git Bash.<\/p>\n\n\n\n

## Table of Contents<\/strong><\/p>\n\n\n\n

– [Laravel Herd Configuration](#laravel-herd-configuration)<\/p>\n\n\n\n

– [Git Bash Compatibility](#git-bash-compatibility)<\/p>\n\n\n\n

– [Common Issues](#common-issues)<\/p>\n\n\n\n

– [Environment Setup](#environment-setup)<\/p>\n\n\n\n\n\n\n\n

## Laravel Herd Configuration<\/strong><\/p>\n\n\n\n

### Overview<\/strong><\/p>\n\n\n\n

Laravel Herd is a native Windows application that provides PHP, Composer, and related tools. It installs in the user’s home directory under `.config\/herd\/`.<\/p>\n\n\n\n

**Installation Location:**<\/strong><\/p>\n\n\n\n

“`<\/p>\n\n\n\n

C:\\Users\\<username>\\.config\\herd\\<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Key Directories:**<\/strong><\/p>\n\n\n\n

– **PHP Binaries:**<\/strong> `~\/.config\/herd\/bin\/php84\/` (version number may vary)<\/p>\n\n\n\n

– **Herd Executables:**<\/strong> `~\/.config\/herd\/bin\/`<\/p>\n\n\n\n

– **Composer:**<\/strong> `~\/.config\/herd\/bin\/composer.bat`<\/p>\n\n\n\n

### Included Tools<\/strong><\/p>\n\n\n\n

Herd provides the following tools as Windows batch files (`.bat`):<\/p>\n\n\n\n

– `php.bat` – PHP CLI<\/p>\n\n\n\n

– `composer.bat` – Composer dependency manager<\/p>\n\n\n\n

– `laravel.bat` – Laravel installer<\/p>\n\n\n\n

– `herd.bat` – Herd management CLI<\/p>\n\n\n\n

## Git Bash Compatibility<\/strong><\/p>\n\n\n\n

### The Problem<\/strong><\/p>\n\n\n\n

Git Bash on Windows cannot execute `.bat` (batch) files directly through standard shell aliases. This causes issues when trying to use Herd-provided tools like Composer.<\/p>\n\n\n\n

**Symptom:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

$ composer –version<\/p>\n\n\n\n

bash: composer: command not found<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### The Solution<\/strong><\/p>\n\n\n\n

Create a `~\/.bashrc` file with bash functions that wrap the batch files using `cmd \/\/c`:<\/p>\n\n\n\n

**File Location:**<\/strong> `C:\\Users\\<username>\\.bashrc`<\/p>\n\n\n\n

**Contents:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Laravel Herd Aliases – please do not remove these lines<\/p>\n\n\n\n

alias php=”php.bat”<\/p>\n\n\n\n

alias herd=”herd.bat”<\/p>\n\n\n\n

alias laravel=”laravel.bat”<\/p>\n\n\n\n

# Composer function for Git Bash compatibility<\/p>\n\n\n\n

composer() {<\/p>\n\n\n\n

    cmd \/\/c “C:\\Users\\alexr\\.config\\herd\\bin\\composer.bat $*”<\/p>\n\n\n\n

}<\/p>\n\n\n\n

export -f composer<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Why This Works:**<\/strong><\/p>\n\n\n\n

1. Simple aliases work for PHP, Herd, and Laravel because they’re in the system PATH<\/p>\n\n\n\n

2. Composer requires a function because we need to pass arguments (`$*`) to the batch file<\/p>\n\n\n\n

3. `cmd \/\/c` executes a Windows command and returns to bash<\/p>\n\n\n\n

4. The double slash `\/\/` prevents Git Bash from converting to a Unix path<\/p>\n\n\n\n

5. `export -f composer` makes the function available to subshells<\/p>\n\n\n\n

### Making It Permanent<\/strong><\/p>\n\n\n\n

To load `.bashrc` automatically on every Git Bash session, create a `~\/.bash_profile`:<\/p>\n\n\n\n

**File Location:**<\/strong> `C:\\Users\\<username>\\.bash_profile`<\/p>\n\n\n\n

**Contents:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Load .bashrc if it exists<\/p>\n\n\n\n

if [ -f ~\/.bashrc ]; then<\/p>\n\n\n\n

    source ~\/.bashrc<\/p>\n\n\n\n

fi<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Manual Loading<\/strong><\/p>\n\n\n\n

If you don’t want to create `.bash_profile`, you can manually load the configuration in each session:<\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

source ~\/.bashrc<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

## Common Issues<\/strong><\/p>\n\n\n\n

### Issue: “Target class [<\/strong>auth] does not exist” After Git Pull<\/strong><\/p>\n\n\n\n

**Symptom:**<\/strong> Running `php artisan` commands fails with “Target class [auth] does not exist”<\/p>\n\n\n\n

**Root Cause:**<\/strong> The `bootstrap\/app.php` file contains an unguarded call to `auth()` in the exceptions context that executes before Laravel’s authentication system is fully bootstrapped during CLI commands. This often occurs after git pulls when changes revert previous fixes.<\/p>\n\n\n\n

**Solution:**<\/strong> Guard the `auth()` call in `bootstrap\/app.php`<\/p>\n\n\n\n

“`php<\/p>\n\n\n\n

\/\/ \u274c PROBLEMATIC CODE (causes CLI failures)<\/p>\n\n\n\n

$exceptions->context(fn () => [<\/p>\n\n\n\n

    ‘user_id’ => auth()->id() ?? null,<\/p>\n\n\n\n

    ‘env’ => app()->environment(),<\/p>\n\n\n\n

]);<\/p>\n\n\n\n

\/\/ \u2705 FIXED CODE (safe for CLI)<\/p>\n\n\n\n

$exceptions->context(fn () => [<\/p>\n\n\n\n

    ‘user_id’ => (function () {<\/p>\n\n\n\n

        try {<\/p>\n\n\n\n

            return function_exists(‘auth’) && app()->bound(‘auth’) ? auth()->id() : null;<\/p>\n\n\n\n

        } catch (\\Throwable $e) {<\/p>\n\n\n\n

            return null;<\/p>\n\n\n\n

        }<\/p>\n\n\n\n

    })(),<\/p>\n\n\n\n

    ‘env’ => app()->environment(),<\/p>\n\n\n\n

]);<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Prevention:**<\/strong> Always guard early auth calls in bootstrap files with existence checks and try\/catch blocks.<\/p>\n\n\n\n

### Issue: “Class ‘Laravel\\Boost\\BoostServiceProvider’ not found”<\/strong><\/p>\n\n\n\n

**Symptom:**<\/strong> Artisan commands fail with provider class not found errors after git pull or dependency changes.<\/p>\n\n\n\n

**Root Cause:**<\/strong> Composer autoload mappings are stale, or Laravel’s package discovery cache is outdated.<\/p>\n\n\n\n

**Solution Steps:**<\/strong><\/p>\n\n\n\n

1. **Create Required Directories**<\/strong> (if missing):<\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

mkdir -p storage\/framework\/views storage\/logs bootstrap\/cache<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

2. **Regenerate Autoload Files**<\/strong>:<\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

composer dump-autoload –optimize –no-scripts<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

3. **Clear Laravel Caches**<\/strong>:<\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

php artisan optimize:clear<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

4. **Regenerate Package Discovery**<\/strong>:<\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

php artisan package:discover –ansi<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

5. **Verify Provider Discovery**<\/strong>:<\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

php artisan tinker –execute=”var_export(class_exists(‘Laravel\\\\Boost\\\\BoostServiceProvider’));”<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Issue: Composer Script Failures During Install<\/strong><\/p>\n\n\n\n

**Symptom:**<\/strong> `composer install` or `composer dump-autoload` fails with “pre-autoload-dump event returned with error code 1”<\/p>\n\n\n\n

**Root Cause:**<\/strong> Composer scripts try to create directories that don’t exist or have permission issues during the pre-autoload-dump phase.<\/p>\n\n\n\n

**Solution:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Create directories manually first (prevents script failure)<\/p>\n\n\n\n

mkdir -p storage\/framework\/views storage\/framework\/cache storage\/framework\/sessions storage\/logs bootstrap\/cache<\/p>\n\n\n\n

# Then run composer install normally (script will now succeed)<\/p>\n\n\n\n

composer.bat install –optimize-autoloader<\/p>\n\n\n\n

# Alternative if still failing – bypass scripts entirely:<\/p>\n\n\n\n

composer dump-autoload –optimize –no-scripts<\/p>\n\n\n\n

php artisan optimize:clear && php artisan package:discover<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Issue: MissingAppKeyException After Environment Changes<\/strong><\/p>\n\n\n\n

**Symptom:**<\/strong> `MissingAppKeyException` errors in tests or application<\/p>\n\n\n\n

**Root Cause:**<\/strong> The `APP_KEY` in `.env` is missing or invalid after environment changes or fresh pulls.<\/p>\n\n\n\n

**Solution:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

php artisan key:generate<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Verification:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

php artisan config:show app.key<\/p>\n\n\n\n

# Should show: app.key …. base64:FBmJhkH6BD0AZ2UWtRosyN4Eaa372d2yuBUP79At1VU=<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Issue: Login Redirects to Wrong URLs (e.g., \/admin\/leads\/partial)<\/strong><\/p>\n\n\n\n

**Symptom:**<\/strong> After login, users are redirected to AJAX endpoints or partial views instead of proper dashboards.<\/p>\n\n\n\n

**Root Cause:**<\/strong> Laravel’s `redirect()->intended()` method stores the last attempted URL in the session. If users previously accessed partial views or AJAX endpoints, the login redirect uses those URLs.<\/p>\n\n\n\n

**Solution:**<\/strong> Clear intended URLs in the AuthenticatedSessionController:<\/p>\n\n\n\n

“`php<\/p>\n\n\n\n

public function store(LoginRequest $request): RedirectResponse<\/p>\n\n\n\n

{<\/p>\n\n\n\n

    $request->authenticate();<\/p>\n\n\n\n

    $request->session()->regenerate();<\/p>\n\n\n\n

    \/\/ Clear any intended URL to prevent unwanted redirects<\/p>\n\n\n\n

    $request->session()->forget(‘url.intended’);<\/p>\n\n\n\n

    \/\/ Force direct redirect based on user role<\/p>\n\n\n\n

    $user = auth()->user();<\/p>\n\n\n\n

    if ($user->role === ‘company_administrator’) {<\/p>\n\n\n\n

        return redirect()->route(‘admin.dashboard’);<\/p>\n\n\n\n

    } else {<\/p>\n\n\n\n

        return redirect()->route(‘dashboard’);<\/p>\n\n\n\n

    }<\/p>\n\n\n\n

}<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Session Debugging:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Clear all sessions to eliminate stored URLs<\/p>\n\n\n\n

php artisan tinker –execute=”DB::table(‘sessions’)->truncate();”<\/p>\n\n\n\n

# Check session count<\/p>\n\n\n\n

php artisan tinker –execute=”echo ‘Session count: ‘ . DB::table(‘sessions’)->count();”<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Issue: PSR-4 Autoloading Standard Violations<\/strong><\/p>\n\n\n\n

**Symptom:**<\/strong> “Class [Name] does not comply with psr-4 autoloading standard” during composer operations.<\/p>\n\n\n\n

**Example Fix:**<\/strong><\/p>\n\n\n\n

“`php<\/p>\n\n\n\n

\/\/ \u274c Missing namespace declaration<\/p>\n\n\n\n

<?php<\/p>\n\n\n\n

use Tests\\TestCase;<\/p>\n\n\n\n

class EmailDeliverabilityTest extends TestCase<\/p>\n\n\n\n

\/\/ \u2705 Proper namespace declaration<\/p>\n\n\n\n

<?php<\/p>\n\n\n\n

namespace Tests\\Feature;<\/p>\n\n\n\n

use Tests\\TestCase;<\/p>\n\n\n\n

class EmailDeliverabilityTest extends TestCase<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Issue: “composer: command not found”<\/strong><\/p>\n\n\n\n

**Cause:**<\/strong> Git Bash cannot execute `.bat` files directly through aliases.<\/p>\n\n\n\n

**Solution:**<\/strong> Use the bash function approach documented above.<\/p>\n\n\n\n

**Verification:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

$ composer –version<\/p>\n\n\n\n

Composer version 2.8.8 2025-04-04 16:56:46<\/p>\n\n\n\n

PHP version 8.4.7 (C:\\Users\\alexr\\.config\\herd\\bin\\php84\\php.exe)<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Issue: “php: command not found”<\/strong><\/p>\n\n\n\n

**Cause:**<\/strong> Herd’s PHP bin directory is not in your PATH.<\/p>\n\n\n\n

**Solution:**<\/strong><\/p>\n\n\n\n

1. Check if Herd is running (system tray icon)<\/p>\n\n\n\n

2. Restart Herd application<\/p>\n\n\n\n

3. Close and reopen Git Bash<\/p>\n\n\n\n

4. Verify PATH includes: `~\/.config\/herd\/bin\/php84\/`<\/p>\n\n\n\n

**Check PATH:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

echo $PATH | grep -o “.config\/herd\/bin\/php84”<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Issue: Laravel commands fail with “Class not found”<\/strong><\/p>\n\n\n\n

**Cause:**<\/strong> Autoloader is out of sync or dependencies are missing.<\/p>\n\n\n\n

**Solution:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

composer install<\/p>\n\n\n\n

composer dump-autoload<\/p>\n\n\n\n

php artisan config:clear<\/p>\n\n\n\n

php artisan cache:clear<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Issue: CRLF vs LF line endings<\/strong><\/p>\n\n\n\n

**Symptom:**<\/strong> Git warnings about CRLF\/LF conversions, scripts fail to execute.<\/p>\n\n\n\n

**Solution:**<\/strong> Configure Git to handle line endings properly:<\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# For this repository only<\/p>\n\n\n\n

git config core.autocrlf true<\/p>\n\n\n\n

# Globally for all repositories<\/p>\n\n\n\n

git config –global core.autocrlf true<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Alternative:**<\/strong> Use `.gitattributes` file (already in project):<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

* text=auto eol=lf<\/p>\n\n\n\n

*.bat text eol=crlf<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Issue: Permissions errors on storage\/logs<\/strong><\/p>\n\n\n\n

**Cause:**<\/strong> Windows file permissions differ from Unix.<\/p>\n\n\n\n

**Solution:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# These commands work in Git Bash<\/p>\n\n\n\n

chmod -R 775 storage<\/p>\n\n\n\n

chmod -R 775 bootstrap\/cache<\/p>\n\n\n\n

# Or use PHP to set permissions<\/p>\n\n\n\n

php artisan storage:link<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Issue: Symlinks not working<\/strong><\/p>\n\n\n\n

**Cause:**<\/strong> Windows requires administrator privileges to create symlinks.<\/p>\n\n\n\n

**Solution:**<\/strong><\/p>\n\n\n\n

1. Run Git Bash as Administrator<\/p>\n\n\n\n

2. Or enable Developer Mode in Windows Settings<\/p>\n\n\n\n

3. Then run: `php artisan storage:link`<\/p>\n\n\n\n

<\/p>\n\n\n\n

## Environment Setup<\/strong><\/p>\n\n\n\n

### Required Environment Variables<\/strong><\/p>\n\n\n\n

The following are set automatically by Herd but can be verified:<\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Check PHP version<\/p>\n\n\n\n

php –version<\/p>\n\n\n\n

# Check Composer version<\/p>\n\n\n\n

composer –version<\/p>\n\n\n\n

# Check Laravel installer<\/p>\n\n\n\n

laravel –version<\/p>\n\n\n\n

# Verify PATH includes Herd<\/p>\n\n\n\n

echo $PATH | grep herd<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Recommended Git Bash Configuration<\/strong><\/p>\n\n\n\n

**<\/strong>`~\/.bashrc`:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Laravel Herd Aliases<\/p>\n\n\n\n

alias php=”php.bat”<\/p>\n\n\n\n

alias herd=”herd.bat”<\/p>\n\n\n\n

alias laravel=”laravel.bat”<\/p>\n\n\n\n

# Composer function for Git Bash compatibility<\/p>\n\n\n\n

composer() {<\/p>\n\n\n\n

    cmd \/\/c “C:\\Users\\alexr\\.config\\herd\\bin\\composer.bat $*”<\/p>\n\n\n\n

}<\/p>\n\n\n\n

export -f composer<\/p>\n\n\n\n

# Laravel Artisan alias<\/p>\n\n\n\n

alias artisan=”php artisan”<\/p>\n\n\n\n

# Common shortcuts<\/p>\n\n\n\n

alias tinker=”php artisan tinker”<\/p>\n\n\n\n

alias migrate=”php artisan migrate”<\/p>\n\n\n\n

alias fresh=”php artisan migrate:fresh –seed”<\/p>\n\n\n\n

# Git shortcuts<\/p>\n\n\n\n

alias gs=”git status”<\/p>\n\n\n\n

alias gp=”git push”<\/p>\n\n\n\n

alias gl=”git log –oneline -10″<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### VSCode Integration<\/strong><\/p>\n\n\n\n

If using VSCode with Git Bash as the integrated terminal:<\/p>\n\n\n\n

**settings.json:**<\/strong><\/p>\n\n\n\n

“`json<\/p>\n\n\n\n

{<\/p>\n\n\n\n

    “terminal.integrated.defaultProfile.windows”: “Git Bash”,<\/p>\n\n\n\n

    “terminal.integrated.profiles.windows”: {<\/p>\n\n\n\n

        “Git Bash”: {<\/p>\n\n\n\n

            “path”: “C:\\\\Program Files\\\\Git\\\\bin\\\\bash.exe”,<\/p>\n\n\n\n

            “args”: [“-l”]<\/p>\n\n\n\n

        }<\/p>\n\n\n\n

    }<\/p>\n\n\n\n

}<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

The `-l` flag ensures it loads as a login shell, which sources `~\/.bash_profile` and `~\/.bashrc`.<\/p>\n\n\n\n

## Development Workflow<\/strong><\/p>\n\n\n\n

### Starting Development<\/strong><\/p>\n\n\n\n

1. **Ensure Herd is running**<\/strong> (check system tray)<\/p>\n\n\n\n

2. **Open Git Bash**<\/strong> in project directory<\/p>\n\n\n\n

3. **Load environment**<\/strong> (if not auto-loaded):<\/p>\n\n\n\n

   “`bash<\/p>\n\n\n\n

   source ~\/.bashrc<\/p>\n\n\n\n

   “`<\/p>\n\n\n\n

4. **Verify tools are available:**<\/strong><\/p>\n\n\n\n

   “`bash<\/p>\n\n\n\n

   php –version<\/p>\n\n\n\n

   composer –version<\/p>\n\n\n\n

   “`<\/p>\n\n\n\n

5. **Start development:**<\/strong><\/p>\n\n\n\n

   “`bash<\/p>\n\n\n\n

   php artisan serve<\/p>\n\n\n\n

   # Or use Herd’s built-in server (automatic)<\/p>\n\n\n\n

   “`<\/p>\n\n\n\n

### Deployment to VPS (Ubuntu\/Linux)<\/strong><\/p>\n\n\n\n

When deploying from Windows to Linux VPS, be aware of:<\/p>\n\n\n\n

1. **Line endings:**<\/strong> Ensure `.gitattributes` is properly configured<\/p>\n\n\n\n

2. **Path differences:**<\/strong> Windows uses backslashes, Linux uses forward slashes<\/p>\n\n\n\n

3. **Case sensitivity:**<\/strong> Linux filesystems are case-sensitive<\/p>\n\n\n\n

4. **Permissions:**<\/strong> Linux requires specific file permissions (775 for storage, 644 for files)<\/p>\n\n\n\n

5. **Batch files:**<\/strong> `.bat` files won’t work on Linux (use bash scripts instead)<\/p>\n\n\n\n

### Testing<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Run tests<\/p>\n\n\n\n

php artisan test<\/p>\n\n\n\n

# Or with Pest<\/p>\n\n\n\n

.\/vendor\/bin\/pest<\/p>\n\n\n\n

# Run specific test<\/p>\n\n\n\n

php artisan test –filter=BookingTest<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

## Quick Recovery Checklist After Git Pull<\/strong><\/p>\n\n\n\n

When encountering issues after `git pull` or major environment changes, follow this systematic approach:<\/p>\n\n\n\n

### 1. Verify Environment Basics<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Check PHP availability<\/p>\n\n\n\n

php -v<\/p>\n\n\n\n

# Check Composer availability  <\/p>\n\n\n\n

composer -V<\/p>\n\n\n\n

# Verify you’re in the project root<\/p>\n\n\n\n

pwd<\/p>\n\n\n\n

# Should show: \/c\/Users\/[username]\/Documents\/GitHub\/clientbridge-laravel<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### 2. Fix Bootstrap Authentication Issues<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Test basic artisan functionality<\/p>\n\n\n\n

php artisan –version<\/p>\n\n\n\n

# If you get “Target class [auth] does not exist”:<\/p>\n\n\n\n

# Check bootstrap\/app.php for unguarded auth() calls in exceptions context<\/p>\n\n\n\n

# Apply the guarded auth solution documented above<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### 3. Regenerate Dependencies & Caches<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Create required directories (if missing)<\/p>\n\n\n\n

mkdir -p storage\/framework\/views storage\/logs bootstrap\/cache<\/p>\n\n\n\n

# Regenerate autoload (bypass scripts if they fail)<\/p>\n\n\n\n

composer dump-autoload –optimize –no-scripts<\/p>\n\n\n\n

# Clear and regenerate ALL Laravel caches<\/p>\n\n\n\n

php artisan optimize:clear<\/p>\n\n\n\n

# Regenerate package discovery cache<\/p>\n\n\n\n

php artisan package:discover –ansi<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### 4. Handle Database & Application Keys<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Generate app key if missing (prevents MissingAppKeyException)<\/p>\n\n\n\n

php artisan key:generate<\/p>\n\n\n\n

# Run any pending migrations<\/p>\n\n\n\n

php artisan migrate<\/p>\n\n\n\n

# Clear sessions if experiencing login redirect issues<\/p>\n\n\n\n

php artisan tinker –execute=”DB::table(‘sessions’)->truncate();”<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### 5. Build Frontend Assets<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Install\/update NPM dependencies<\/p>\n\n\n\n

npm install<\/p>\n\n\n\n

# Build production assets<\/p>\n\n\n\n

npm run build<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### 6. Reinstall Development Tools<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Reinstall Laravel Boost MCP server for VS Code integration<\/p>\n\n\n\n

php artisan boost:install<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### 7. Final Verification Tests<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Test artisan commands work<\/p>\n\n\n\n

php artisan route:list | head -5<\/p>\n\n\n\n

# Test class autoloading<\/p>\n\n\n\n

php artisan tinker –execute=”var_export(class_exists(‘Laravel\\\\Boost\\\\BoostServiceProvider’));”<\/p>\n\n\n\n

# Test application key<\/p>\n\n\n\n

php artisan config:show app.key<\/p>\n\n\n\n

# Test basic authentication (if logged in)<\/p>\n\n\n\n

php artisan tinker –execute=”echo auth()->check() ? ‘Auth working’ : ‘Auth ready’;”<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

## Standard Troubleshooting Checklist<\/strong><\/p>\n\n\n\n

For general development issues:<\/p>\n\n\n\n

– [ ] Is Herd running? (Check system tray)<\/p>\n\n\n\n

– [ ] Did you source `~\/.bashrc`? Run: `source ~\/.bashrc`<\/p>\n\n\n\n

– [ ] Is PHP in PATH? Run: `which php.bat`<\/p>\n\n\n\n

– [ ] Is Composer working? Run: `composer –version`<\/p>\n\n\n\n

– [ ] Are dependencies installed? Run: `composer install`<\/p>\n\n\n\n

– [ ] Is `.env` file present? Run: `ls -la .env`<\/p>\n\n\n\n

– [ ] Are permissions correct? Run: `ls -la storage\/`<\/p>\n\n\n\n

– [ ] Bootstrap issues? Check: `bootstrap\/app.php` for unguarded auth calls<\/p>\n\n\n\n

– [ ] Clear caches: `php artisan optimize:clear`<\/p>\n\n\n\n

– [ ] Regenerate discovery: `php artisan package:discover`<\/p>\n\n\n\n

– [ ] Restart Herd application<\/p>\n\n\n\n

– [ ] Close and reopen Git Bash<\/p>\n\n\n\n

## Emergency Recovery Commands<\/strong><\/p>\n\n\n\n

**Full environment reset after major issues:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Complete recovery sequence (run in project root)<\/p>\n\n\n\n

mkdir -p storage\/framework\/views storage\/logs bootstrap\/cache<\/p>\n\n\n\n

composer dump-autoload –optimize –no-scripts<\/p>\n\n\n\n

php artisan optimize:clear<\/p>\n\n\n\n

php artisan package:discover –ansi<\/p>\n\n\n\n

php artisan key:generate<\/p>\n\n\n\n

php artisan migrate<\/p>\n\n\n\n

npm install && npm run build<\/p>\n\n\n\n

php artisan boost:install<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Debug specific issues:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Check authentication system<\/p>\n\n\n\n

php artisan tinker –execute=”var_export([<\/p>\n\n\n\n

    ‘auth_function_exists’ => function_exists(‘auth’),<\/p>\n\n\n\n

    ‘auth_bound’ => app()->bound(‘auth’),<\/p>\n\n\n\n

    ‘user_model_exists’ => class_exists(‘App\\\\Models\\\\User’)<\/p>\n\n\n\n

]);”<\/p>\n\n\n\n

# Verify critical service providers are discovered<\/p>\n\n\n\n

php artisan tinker –execute=”var_export([<\/p>\n\n\n\n

    ‘boost_provider’ => class_exists(‘Laravel\\\\Boost\\\\BoostServiceProvider’),<\/p>\n\n\n\n

    ‘mcp_provider’ => class_exists(‘Laravel\\\\Mcp\\\\Server\\\\McpServiceProvider’),<\/p>\n\n\n\n

    ‘breeze_provider’ => class_exists(‘Laravel\\\\Breeze\\\\BreezeServiceProvider’)<\/p>\n\n\n\n

]);”<\/p>\n\n\n\n

# Clear all caches and sessions completely<\/p>\n\n\n\n

php artisan optimize:clear && php artisan tinker –execute=”<\/p>\n\n\n\n

    DB::table(‘sessions’)->truncate();<\/p>\n\n\n\n

    echo ‘All caches and sessions cleared.’;<\/p>\n\n\n\n

“<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

## Additional Resources<\/strong><\/p>\n\n\n\n

– **Laravel Herd Documentation:**<\/strong> https:\/\/herd.laravel.com\/<\/p>\n\n\n\n

– **Git Bash Documentation:**<\/strong> https:\/\/git-scm.com\/docs<\/p>\n\n\n\n

– **Laravel Documentation:**<\/strong> https:\/\/laravel.com\/docs<\/p>\n\n\n\n

– **Composer Documentation:**<\/strong> https:\/\/getcomposer.org\/doc\/<\/p>\n\n\n\n

## Maintenance<\/strong><\/p>\n\n\n\n

### Updating Herd<\/strong><\/p>\n\n\n\n

Herd auto-updates, but you can manually check:<\/p>\n\n\n\n

1. Click Herd icon in system tray<\/p>\n\n\n\n

2. Select “Check for Updates”<\/p>\n\n\n\n

3. Restart Herd after update<\/p>\n\n\n\n

4. Verify PHP\/Composer versions: `php –version && composer –version`<\/p>\n\n\n\n

### Updating Composer<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

composer self-update<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Changing PHP Version<\/strong><\/p>\n\n\n\n

Herd supports multiple PHP versions:<\/p>\n\n\n\n

1. Right-click Herd icon in system tray<\/p>\n\n\n\n

2. Select PHP version (8.1, 8.2, 8.3, 8.4)<\/p>\n\n\n\n

3. Update `.bashrc` path if needed: `~\/.config\/herd\/bin\/php84\/` \u2192 `php83\/` etc.<\/p>\n\n\n\n

## Prevention Best Practices<\/strong><\/p>\n\n\n\n

### Before Git Pull<\/strong><\/p>\n\n\n\n

– [ ] Commit or stash local changes<\/p>\n\n\n\n

– [ ] Note any custom environment configurations<\/p>\n\n\n\n

– [ ] Backup `.env` file if it contains unique local settings<\/p>\n\n\n\n

### After Git Pull<\/strong><\/p>\n\n\n\n

– [ ] Run the Quick Recovery Checklist above<\/p>\n\n\n\n

– [ ] Check `bootstrap\/app.php` for reverted auth guards<\/p>\n\n\n\n

– [ ] Verify critical routes still work: `php artisan route:list | grep dashboard`<\/p>\n\n\n\n

– [ ] Test login functionality to ensure proper redirects<\/p>\n\n\n\n

### Code Practices<\/strong><\/p>\n\n\n\n

1. **Always guard early auth calls**<\/strong> in bootstrap contexts:<\/p>\n\n\n\n

   “`php<\/p>\n\n\n\n

   \/\/ Safe pattern for bootstrap files<\/p>\n\n\n\n

   ‘user_id’ => (function () {<\/p>\n\n\n\n

       try {<\/p>\n\n\n\n

           return function_exists(‘auth’) && app()->bound(‘auth’) ? auth()->id() : null;<\/p>\n\n\n\n

       } catch (\\Throwable $e) {<\/p>\n\n\n\n

           return null;<\/p>\n\n\n\n

       }<\/p>\n\n\n\n

   })(),<\/p>\n\n\n\n

   “`<\/p>\n\n\n\n

2. **Clear intended URLs**<\/strong> in login controllers:<\/p>\n\n\n\n

   “`php<\/p>\n\n\n\n

   \/\/ Prevent unwanted redirects after authentication<\/p>\n\n\n\n

   $request->session()->forget(‘url.intended’);<\/p>\n\n\n\n

   “`<\/p>\n\n\n\n

3. **Use proper namespaces**<\/strong> in test files:<\/p>\n\n\n\n

   “`php<\/p>\n\n\n\n

   <?php<\/p>\n\n\n\n

   namespace Tests\\Feature; \/\/ Always include namespace<\/p>\n\n\n\n

   “`<\/p>\n\n\n\n

4. **Regenerate caches**<\/strong> after dependency changes:<\/p>\n\n\n\n

   “`bash<\/p>\n\n\n\n

   composer dump-autoload –optimize<\/p>\n\n\n\n

   php artisan optimize:clear<\/p>\n\n\n\n

   php artisan package:discover<\/p>\n\n\n\n

   “`<\/p>\n\n\n\n

## Script Automation<\/strong><\/p>\n\n\n\n

### Setup Script for New Windows Environments<\/strong><\/p>\n\n\n\n

Create `scripts\/setup-herd-gitbash.sh` (already exists in project):<\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

#!\/bin\/bash<\/p>\n\n\n\n

# Sets up Git Bash to work with Laravel Herd on Windows<\/p>\n\n\n\n

BASHRC=”$HOME\/.bashrc”<\/p>\n\n\n\n

HERD_BIN=”$HOME\/.config\/herd\/bin”<\/p>\n\n\n\n

# Add PATH export for Herd binaries<\/p>\n\n\n\n

if ! grep -q “export PATH.*herd\/bin” “$BASHRC” 2>\/dev\/null; then<\/p>\n\n\n\n

    echo “” >> “$BASHRC”<\/p>\n\n\n\n

    echo “# Laravel Herd PATH” >> “$BASHRC”<\/p>\n\n\n\n

    echo “export PATH=\\”\\$HOME\/.config\/herd\/bin:\\$PATH\\”” >> “$BASHRC”<\/p>\n\n\n\n

    echo “Added Herd bin to PATH”<\/p>\n\n\n\n

else<\/p>\n\n\n\n

    echo “Herd PATH already configured”<\/p>\n\n\n\n

fi<\/p>\n\n\n\n

# Add aliases for .bat files<\/p>\n\n\n\n

ALIASES=(<\/p>\n\n\n\n

    “alias php=’php.bat'”<\/p>\n\n\n\n

    “alias composer=’composer.bat'”<\/p>\n\n\n\n

    “alias herd=’herd.bat'”<\/p>\n\n\n\n

    “alias laravel=’laravel.bat'”<\/p>\n\n\n\n

)<\/p>\n\n\n\n

for alias_cmd in “${ALIASES[@]}”; do<\/p>\n\n\n\n

    if ! grep -Fq “$alias_cmd” “$BASHRC” 2>\/dev\/null; then<\/p>\n\n\n\n

        echo “$alias_cmd” >> “$BASHRC”<\/p>\n\n\n\n

        echo “Added: $alias_cmd”<\/p>\n\n\n\n

    else<\/p>\n\n\n\n

        echo “Alias already exists: $alias_cmd”<\/p>\n\n\n\n

    fi<\/p>\n\n\n\n

done<\/p>\n\n\n\n

echo “Setup complete! Run ‘source ~\/.bashrc’ to apply changes.”<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

### Post-Pull Recovery Script<\/strong><\/p>\n\n\n\n

Consider creating `scripts\/post-pull-recovery.sh`:<\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

#!\/bin\/bash<\/p>\n\n\n\n

# Automated recovery after git pull<\/p>\n\n\n\n

echo “\ud83d\udd27 Starting post-pull recovery…”<\/p>\n\n\n\n

# Step 1: Create required directories<\/p>\n\n\n\n

echo “\ud83d\udcc1 Creating required directories…”<\/p>\n\n\n\n

mkdir -p storage\/framework\/views storage\/logs bootstrap\/cache<\/p>\n\n\n\n

# Step 2: Fix autoload issues<\/p>\n\n\n\n

echo “\ud83d\udd04 Regenerating autoload…”<\/p>\n\n\n\n

composer dump-autoload –optimize –no-scripts<\/p>\n\n\n\n

# Step 3: Clear Laravel caches<\/p>\n\n\n\n

echo “\ud83e\uddf9 Clearing Laravel caches…”<\/p>\n\n\n\n

php artisan optimize:clear<\/p>\n\n\n\n

# Step 4: Regenerate package discovery<\/p>\n\n\n\n

echo “\ud83d\udce6 Regenerating package discovery…”<\/p>\n\n\n\n

php artisan package:discover –ansi<\/p>\n\n\n\n

# Step 5: Generate app key if missing<\/p>\n\n\n\n

echo “\ud83d\udd11 Checking application key…”<\/p>\n\n\n\n

if ! php artisan config:show app.key | grep -q “base64:”; then<\/p>\n\n\n\n

    echo “Generating new application key…”<\/p>\n\n\n\n

    php artisan key:generate<\/p>\n\n\n\n

fi<\/p>\n\n\n\n

# Step 6: Run migrations<\/p>\n\n\n\n

echo “\ud83d\udcca Running migrations…”<\/p>\n\n\n\n

php artisan migrate –force<\/p>\n\n\n\n

# Step 7: Clear sessions<\/p>\n\n\n\n

echo “\ud83e\uddfc Clearing sessions…”<\/p>\n\n\n\n

php artisan tinker –execute=”DB::table(‘sessions’)->truncate(); echo ‘Sessions cleared’;”<\/p>\n\n\n\n

# Step 8: Build frontend<\/p>\n\n\n\n

echo “\ud83c\udfa8 Building frontend assets…”<\/p>\n\n\n\n

npm install<\/p>\n\n\n\n

npm run build<\/p>\n\n\n\n

echo “echo “\u2705 Recovery complete! Environment should now be ready.”<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

—<\/p>\n\n\n\n

## Windows-Specific Directory Permission Issues<\/strong><\/p>\n\n\n\n

### Issue: “bootstrap\\cache directory must be present and writable”<\/strong><\/p>\n\n\n\n

**Symptom:**<\/strong> Laravel fails with error: “The bootstrap\\cache directory must be present and writable.”<\/p>\n\n\n\n

**Root Cause:**<\/strong> Windows file system permissions or read-only attributes prevent Laravel from writing to the bootstrap\/cache directory.<\/p>\n\n\n\n

**Solutions (in order of preference):**<\/strong><\/p>\n\n\n\n

**Solution 1 – Remove Read-Only Attribute (RECOMMENDED):**<\/strong><\/p>\n\n\n\n

“`powershell<\/p>\n\n\n\n

# In PowerShell (no admin required)<\/p>\n\n\n\n

attrib -r +a .\\bootstrap\\cache<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Solution 2 – Create Directory with Proper Attributes:**<\/strong><\/p>\n\n\n\n

“`powershell<\/p>\n\n\n\n

# In PowerShell<\/p>\n\n\n\n

New-Item -Path “bootstrap\\cache” -ItemType Directory -Force<\/p>\n\n\n\n

attrib -r +a .\\bootstrap\\cache<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Solution 3 – Grant Full Permissions:**<\/strong><\/p>\n\n\n\n

“`powershell<\/p>\n\n\n\n

# In PowerShell as Administrator<\/p>\n\n\n\n

icacls “bootstrap\\cache” \/grant Everyone:F \/T<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Solution 4 – Use the Fix Script:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# In Git Bash<\/p>\n\n\n\n

bash scripts\/fix-bootstrap-cache.sh<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Verification:**<\/strong><\/p>\n\n\n\n

“`bash<\/p>\n\n\n\n

# Test write permissions<\/p>\n\n\n\n

touch bootstrap\/cache\/test.tmp<\/p>\n\n\n\n

rm bootstrap\/cache\/test.tmp<\/p>\n\n\n\n

“`<\/p>\n\n\n\n

**Notes:**<\/strong><\/p>\n\n\n\n

– The `attrib` command removes the read-only flag (`-r`) and sets the archive attribute (`+a`)<\/p>\n\n\n\n

– This is often needed after cloning a repository on Windows<\/p>\n\n\n\n

– The issue can also occur after extracting a ZIP archive<\/p>\n\n\n\n

– Antivirus software may sometimes interfere with directory creation<\/p>\n\n\n\n

<\/p>\n","protected":false},"excerpt":{"rendered":"

THIS POST WAS GENERATED BY AI # Windows Environment Setup & Troubleshooting This document covers Windows-specific configuration and common issues when developing ClientBridge Laravel on Windows with Laravel Herd and Git Bash. ## Table of Contents – [Laravel Herd Configuration](#laravel-herd-configuration) – [Git Bash Compatibility](#git-bash-compatibility) – [Common Issues](#common-issues) – [Environment Setup](#environment-setup)<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-982","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"http:\/\/alexanderramsey.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/982","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/alexanderramsey.com\/blog\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/alexanderramsey.com\/blog\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/alexanderramsey.com\/blog\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/alexanderramsey.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=982"}],"version-history":[{"count":5,"href":"http:\/\/alexanderramsey.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/982\/revisions"}],"predecessor-version":[{"id":2391,"href":"http:\/\/alexanderramsey.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/982\/revisions\/2391"}],"wp:attachment":[{"href":"http:\/\/alexanderramsey.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=982"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/alexanderramsey.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=982"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/alexanderramsey.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=982"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}