Laravel Visit Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require spatie/laravel-visit
   php artisan visit:install
   

   • Publishes the config file (config/visit.php) with default settings.

2. First Use Case:

   php artisan visit /dashboard
   

   • Opens the /dashboard route in your browser (if --browser flag is used) and displays a colorized HTML/JSON response in the terminal.
   • Without flags, it only shows the response in the terminal.

3. Key Configurations:

   • Check config/visit.php for default settings like:
     • browser: Whether to open the page in the browser (true/false).
     • auth: Default user to authenticate as (e.g., auth:user).
     • headers: Custom headers to include in requests.
     • timeout: Request timeout in seconds.

Implementation Patterns

Core Workflows

1. Visiting Routes by Name:

   php artisan visit admin.dashboard
   

   • Uses Laravel’s route naming system for cleaner CLI commands.

2. Authentication:

   • Default User: Set in config/visit.php:

     'auth' => [
         'user' => 'auth:user', // Uses the `auth:user` artisan command
     ],
     

   • Dynamic Auth: Override via CLI:

     php artisan visit /profile --auth=admin:password
     

3. Custom Headers:

   • Add headers in config/visit.php:

     'headers' => [
         'X-Custom-Header' => 'value',
     ],
     

   • Override via CLI:

     php artisan visit /api --header="Authorization: Bearer token"
     

4. Browser Integration:

   php artisan visit /dashboard --browser
   

   • Opens the page in the default browser (requires config/visit.browser = true).

5. JSON Responses:

   php artisan visit /api/users --json
   

   • Colorizes JSON output for readability.

6. Session Persistence:

   • Use --session to persist session data across requests:

     php artisan visit /dashboard --session
     

Integration Tips

1. Testing Workflows:

   • Use visit in CI/CD pipelines to visually inspect rendered pages or API responses.
   • Example: Add to phpunit.xml as a post-test hook:

     <postTestCommands>
         <command>php artisan visit /dashboard --json > last-test-response.json</command>
     </postTestCommands>
     

2. Debugging Middleware:

   • Bypass middleware temporarily for debugging:

     php artisan visit /admin --middleware=web
     

   • Or disable all middleware:

     php artisan visit /admin --no-middleware
     

3. Customizing Output:

   • Extend the output format by publishing and modifying the resources/views/vendor/visit/results.blade.php template.

4. API Testing:

   • Test API endpoints with auth and headers:

     php artisan visit /api/v1/users --auth=api --header="Accept: application/json"
     

5. Localization:

   • Override language for multilingual apps:

     php artisan visit /dashboard --locale=es
     

Gotchas and Tips

Pitfalls

1. Session Conflicts:

   • If using --session, ensure no other processes (e.g., Laravel queues) interfere with session storage.
   • Fix: Clear sessions between tests:

     php artisan session:clear
     

2. Middleware Overrides:

   • Disabling middleware (--no-middleware) may bypass critical security checks (e.g., CSRF). Use cautiously in production-like environments.

3. Browser Flag Limitations:

   • The --browser flag relies on the system’s default browser. On headless servers (e.g., CI), this will fail silently.
   • Workaround: Use --json or redirect output to a file for CI pipelines.

4. Route Caching:

   • If routes are cached (php artisan route:cache), ensure the visit command runs after caching or clears the cache first:

     php artisan route:clear && php artisan visit /dashboard
     

5. Auth User Resolution:

   • The auth:user command must resolve a valid user. If no user is found, the request will fail.
   • Debug: Run php artisan auth:user separately to verify.

Debugging

1. Verbose Mode: Enable debug output for HTTP requests:

   php artisan visit /dashboard --verbose
   

2. Inspect Headers: Dump request/response headers:

   php artisan visit /dashboard --dump-headers
   

3. Network Issues:

   • If requests hang, check the timeout setting in config/visit.php (default: 30 seconds).
   • For slow APIs, increase it:

     'timeout' => 60,
     

4. Colorized Output Issues:

   • If colors don’t render in the terminal, ensure your terminal supports ANSI colors or force raw output:

     php artisan visit /dashboard --no-colors
     

Extension Points

1. Custom Commands: Extend the VisitCommand class to add domain-specific logic. Publish the command:

   php artisan vendor:publish --tag="visit-commands"
   

   Then modify app/Console/Commands/VisitCommand.php.

2. Pre/Post-Request Hooks: Use Laravel’s registering and registered events in EventServiceProvider to hook into the VisitCommand lifecycle.

3. Custom Response Handlers: Override how responses are processed by modifying the handleResponse method in the published command class.

4. Environment-Specific Configs: Use Laravel’s environment configs to switch behaviors:

   'auth' => env('VISIT_AUTH_USER', 'auth:user'),
   

5. Proxy Support: Configure proxy settings in config/visit.php for behind-firewall setups:

   'proxy' => [
       'http'  => 'tcp://proxy.example.com:8080',
       'https' => 'tcp://proxy.example.com:8080',
   ],