shell-leaderboard/docs/laravel-setup.md

Laravel Base Setup Guide

This guide covers setting up authentication, API, and base middleware for your Laravel application.

Quick Start

After installing Laravel and running make setup-tools, run:

make setup-laravel

This interactive script will:

1. Set up authentication (Breeze or Jetstream)
2. Configure Sanctum for API authentication
3. Create security middleware
4. Set up storage symlink

Authentication Options

This template focuses on Blade and Livewire - no JavaScript frameworks (Vue/React/Inertia). This keeps debugging simple and server-side.

Laravel Breeze + Blade (Recommended)

Best for: Most applications. Simple, fast, easy to debug.

Features:

• Login, registration, password reset
• Email verification
• Profile editing
• Tailwind CSS styling

composer require laravel/breeze --dev
php artisan breeze:install blade
php artisan migrate
npm install && npm run build

Laravel Breeze + Livewire

Best for: Apps needing reactive UI without JavaScript frameworks.

Same features as Blade, but with dynamic updates via Livewire.

composer require laravel/breeze --dev
php artisan breeze:install livewire
php artisan migrate
npm install && npm run build

Laravel Breeze API Only

Best for: When you want to build your own Blade views.

Provides API authentication endpoints, you build the frontend.

composer require laravel/breeze --dev
php artisan breeze:install api
php artisan migrate

Laravel Jetstream + Livewire (Full-featured)

Best for: SaaS applications needing teams, 2FA, API tokens.

Features:

• Profile management with photo upload
• Two-factor authentication
• API token management
• Team management (optional)
• Session management
• Browser session logout

composer require laravel/jetstream
php artisan jetstream:install livewire --teams
php artisan migrate
npm install && npm run build

API Authentication (Sanctum)

Laravel Sanctum provides:

• SPA authentication (cookie-based)
• API token authentication
• Mobile app authentication

Creating Tokens

// Create a token
$token = $user->createToken('api-token')->plainTextToken;

// Create with abilities
$token = $user->createToken('api-token', ['posts:read', 'posts:write'])->plainTextToken;

Authenticating Requests

# Using token
curl -H "Authorization: Bearer YOUR_TOKEN" https://your-app.com/api/user

# Using cookie (SPA)
# First get CSRF token from /sanctum/csrf-cookie

Token Abilities

// Check ability
if ($user->tokenCan('posts:write')) {
    // Can write posts
}

// In route middleware
Route::post('/posts', [PostController::class, 'store'])
    ->middleware('ability:posts:write');

Security Middleware

The setup script creates two middleware files:

ForceHttps

Redirects HTTP to HTTPS in production.

// Register in bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\App\Http\Middleware\ForceHttps::class);
})

SecurityHeaders

Adds security headers to all responses:

• X-Frame-Options
• X-Content-Type-Options
• X-XSS-Protection
• Referrer-Policy
• Permissions-Policy
• Strict-Transport-Security (production only)

// Register in bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\App\Http\Middleware\SecurityHeaders::class);
})

API Routes Template

An example API routes file is provided at src/routes/api.example.php.

Key patterns:

• Health check endpoint
• Protected routes with auth:sanctum
• Token management endpoints
• API versioning structure

CORS Configuration

If your API is consumed by a separate frontend:

1. Copy src/config/cors.php.example to config/cors.php
2. Update allowed_origins with your frontend URL
3. Set FRONTEND_URL in .env

FRONTEND_URL=https://your-frontend.com

Development Workflow

After Setup

# Start development
make up DB=mysql

# Run migrations
make artisan cmd='migrate'

# Create a user (tinker)
make tinker
# User::factory()->create(['email' => 'test@example.com'])

# Run tests
make test

# Fix code style
make lint

Common Tasks

# Create controller
make artisan cmd='make:controller Api/PostController --api'

# Create model with migration
make artisan cmd='make:model Post -m'

# Create form request
make artisan cmd='make:request StorePostRequest'

# Create resource
make artisan cmd='make:resource PostResource'

# Create policy
make artisan cmd='make:policy PostPolicy --model=Post'

Testing API

With curl

# Register (if using Breeze API)
curl -X POST http://localhost:8080/api/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Test","email":"test@test.com","password":"password","password_confirmation":"password"}'

# Login
curl -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@test.com","password":"password"}'

# Use token
curl http://localhost:8080/api/user \
  -H "Authorization: Bearer YOUR_TOKEN"

With Postman/Insomnia

1. Import the API collection (create from routes)
2. Set base URL to http://localhost:8080/api
3. Add Authorization header with Bearer token

Troubleshooting

CORS Errors

1. Check config/cors.php includes your frontend origin
2. Ensure supports_credentials is true if using cookies
3. Clear config cache: php artisan config:clear

401 Unauthorized

1. Check token is valid and not expired
2. Ensure auth:sanctum middleware is applied
3. For SPA: ensure CSRF cookie is set

Session Issues

1. Check SESSION_DOMAIN matches your domain
2. For subdomains, use .yourdomain.com
3. Ensure Redis is running for session storage