Valet Laravel Package

Getting Started

Minimal Setup

1. Installation:

   brew install laravel/valet/valet
   valet install
   

   • Runs valet install to configure Nginx, DnsMasq, and PHP (if not already installed).
   • Automatically links Valet to your system’s PATH.

2. First Project:

   mkdir ~/Sites/my-project && cd ~/Sites/my-project
   composer create-project laravel/laravel .
   valet link
   

   • Creates a new Laravel project in ~/Sites/ (Valet’s default directory).
   • valet link generates a my-project.test domain and configures Nginx.

3. Access Your Site: Open https://my-project.test in your browser. Valet handles SSL via Let’s Encrypt (automatically).

Key Commands

Where to Look First

• Valet Docs: https://laravel.com/docs/valet (official guide).
• Troubleshooting: valet doctor (diagnoses common issues like PHP/Nginx misconfigurations).
• Custom Configs: ~/.valet/Nginx/ (override default Nginx templates).

Implementation Patterns

Daily Workflow

1. Project Setup:

   # Create and link a new project
   mkdir ~/Sites/api && cd $_
   composer create-project laravel/laravel .
   valet link
   valet secure
   

   • Use valet link early to avoid manual domain/hosts file management.

2. PHP Version Management:

   # List available PHP versions
   valet php
   
   # Switch globally or per-project
   valet use php@8.2       # Global
   echo "extension=redis" >> ~/.valet/php/php8.2.ini  # Per-project PHP.ini
   

   • Store project-specific PHP configs in .valet-php.ini (auto-loaded).

3. Environment-Specific Configs:

   • Use .env files as usual (Valet ignores them by default).
   • Override Nginx configs for specific sites:

     valet trust
     # Edit ~/Sites/my-project/public/Nginx.conf
     

   • Example: Custom cache paths or proxy settings.

4. Database & Services:

   • Pair with Laravel Sail for Dockerized databases:

     sail up -d
     valet link  # Works alongside Sail
     

   • For non-Docker setups, use valet db (if configured via ~/.valet/MySQL/).

5. Collaboration:

   • Share sites publicly:

     valet share  # Outputs: https://my-project.test.lndo.site
     

   • Use valet trust to allow local sites to access external APIs (e.g., Stripe).

Integration Tips

• Laravel Mix/Vite: Valet handles HTTPS, so mix/vite dev servers work out-of-the-box with https://my-project.test.

  // vite.config.js
  server: {
    https: true,
  }
  

• Queue Workers: Use valet queue:work (if using Laravel’s queue system) or integrate with Supervisor:

  echo_supervisord_conf | sudo tee /etc/supervisord.conf
  sudo supervisorctl reread
  sudo supervisorctl update
  

• CI/CD: Mock Valet in pipelines by using *.test domains in tests (e.g., http://test-site.test). Example in phpunit.xml:

  <env name="APP_URL" value="https://test-site.test"/>
  

• Monorepos: Use valet link with subdirectories:

  cd ~/Sites/monorepo/api
  valet link api.test
  cd ../frontend
  valet link frontend.test
  

Gotchas and Tips

Common Pitfalls

1. DNS Caching:

   • After valet link, wait 10–30 seconds for DnsMasq to propagate.
   • Clear cache if domains fail:

     sudo killall -HUP mDNSResponder
     

2. PHP Version Conflicts:

   • Ensure PHP CLI and FPM versions match:

     valet php  # Check installed versions
     valet use php@8.2 && valet restart
     

   • Debug with:

     valet php --version
     php -v  # Should match
     

3. Port Conflicts:

   • Valet uses ports 80/443. If another service (e.g., Docker) blocks them:

     valet secure --port=8080  # Custom port
     

   • Check for conflicts:

     lsof -i :80
     

4. SSL Issues:

   • valet secure may fail if:
     • Let’s Encrypt rate limits are hit (wait 7 days).
     • Firewall blocks port 443:

       sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /usr/local/bin/valet
       

   • Renew certs manually:

     valet certs:prune  # Clean old certs
     valet secure
     

5. Nginx Misconfigurations:

   • Overriding Nginx.conf can break routing. Use valet trust sparingly.
   • Reset to defaults:

     valet reset
     

Debugging

• Logs:

  valet logs  # Streams Nginx/PHP-FPM
  tail -f /usr/local/var/log/nginx/error.log
  

• Network Issues:

  ping my-project.test  # Should resolve to 127.0.0.1
  curl -v http://my-project.test
  

• PHP Errors: Enable error display in ~/.valet/php/php.ini:

  display_errors = On
  display_startup_errors = On
  

Pro Tips

1. Aliases: Add to ~/.zshrc or ~/.bashrc:

   alias vlink='valet link'
   alias vopen='valet open'
   alias vlogs='valet logs --tail=50'
   

2. Project Templates: Use valet new to scaffold projects with preconfigured PHP/Nginx:

   valet new my-project --template=laravel
   

3. Custom Domains: Extend beyond .test:

   valet link my-project.local
   # Edit ~/.valet/Dnsmasqfile to add custom TLDs
   

4. Performance:

   • Disable unused PHP extensions to reduce memory usage:

     valet php --disable-module=php_xdebug
     

   • Use valet restart --clear to reset Nginx cache.

5. Backup Sites:

   valet backup my-project.test ~/backups/
   valet restore ~/backups/my-project.test ~/Sites/
   

6. Extending Valet:

   • Add custom commands via ~/.valet/commands/ (e.g., valet my:task).
   • Hook into Valet’s lifecycle with ~/.valet/ValetServiceProvider.php.

7. Docker Integration:

   • Use valet link with Docker volumes:

     # Mount host directory to container
     docker run -v ~/Sites/my-project:/var/www/html ...
     valet link  # Works with containerized apps