Web Server Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require symfony/web-server-bundle
   

   Add to config/bundles.php (Symfony) or ensure it’s auto-loaded (Laravel via composer.json extras).

2. First Use Case: Run the built-in server for local development:

   php artisan serve
   

   • Laravel auto-detects the bundle; no extra config needed.
   • Access http://localhost:8000 (default port).

3. Where to Look:

   • Commands: php artisan list → serve command.
   • Config: Check config/app.php for trusted_proxies (if using reverse proxies).
   • Docs: Symfony Web Server Bundle (core logic applies).

Implementation Patterns

Workflows

1. Local Development:

   • Replace php -S localhost:8000 with php artisan serve for:
     • Automatic reloading (Symfony’s watch mode).
     • Trusted proxy support (e.g., Docker, VPNs).
   • Example:

     php artisan serve --port=8080 --host=0.0.0.0
     

2. CI/CD/Testing:

   • Use in pipelines for lightweight HTTP testing:

     php artisan serve --no-tls & sleep 2 && curl http://localhost:8000/api/health
     

   • Tip: Combine with symfony/process for async testing.

3. Customization:

   • Environment-Specific Hosts:

     // config/app.php
     'web_server' => [
         'host' => env('APP_HOST', 'localhost'),
         'port' => env('APP_PORT', 8000),
     ],
     

   • Middleware: Extend Symfony\Component\WebServer\Command (advanced).

4. Integration with Laravel:

   • Route Caching:

     php artisan route:cache && php artisan serve
     

   • Queue Workers: Run server in one terminal, queues in another:

     php artisan serve --port=8001 &
     php artisan queue:work
     

Gotchas and Tips

Pitfalls

1. Port Conflicts:

   • Error: Address already in use.
   • Fix: Use --port or lsof -i :8000 to kill existing processes.

2. Trusted Proxies:

   • Issue: TRUSTED_PROXIES env var ignored if not set in Laravel’s trustedProxies config.
   • Fix:

     // config/app.php
     'trusted_proxies' => ['127.0.0.1', '::1'], // Add local IPs if using Docker
     

3. TLS/HTTPS:

   • Limitation: Built-in server lacks TLS. Use mkcert or Nginx for HTTPS locally.
   • Workaround:

     mkcert -install && mkcert localhost && php artisan serve --tls
     

4. Performance:

   • Warning: Not for production. Use Nginx/PHP-FPM in APP_ENV=production.

Debugging

1. Logs:

   • Check storage/logs/laravel.log for server errors (e.g., missing routes).
   • Enable verbose mode:

     php artisan serve --verbose
     

2. Environment Variables:

   • Common Pitfall: APP_URL must match the server’s host/port.
   • Fix:

     APP_URL=http://localhost:8000
     

Extension Points

1. Custom Commands:

   • Extend the serve command by publishing and modifying:

     php artisan vendor:publish --tag=web-server-bundle
     

   • Override Symfony\Component\WebServer\Command\ServerCommand.

2. Proxy Integration:

   • Use TRUSTED_PROXIES to simulate remote requests:

     TRUSTED_PROXIES=192.168.1.100 php artisan serve
     

3. Docker:

   • Bind-mount the server port:

     # docker-compose.yml
     services:
       app:
         ports:
           - "8000:8000"