Laravel Web Tinker Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-web-tinker --dev
   php artisan web-tinker:install
   

   This publishes the assets (Vue.js frontend) and config file.

2. First Use: Visit /tinker in your local Laravel environment (enabled by default for APP_ENV=local). No additional configuration is required for basic usage.

3. Key Features Out of the Box:

   • Dark/Light Mode: Auto-detects user preference or use theme: 'dark' in config.
   • Output Formatting: Includes a PrefixDateTime modifier to timestamp outputs (configurable via output_modifier).
   • Session Support: Built-in middleware for EncryptCookies and StartSession.

Implementation Patterns

Daily Workflow Integration

1. Debugging Queries:

   // Directly in the browser console (via /tinker):
   User::where('active', true)->count();
   

   • Useful for ad-hoc SQL debugging without opening a terminal.

2. Testing Logic Snippets:

   // Test a helper function:
   $result = formatPrice(1234.56);
   dump($result);
   

   • Avoid creating temporary test files for one-off checks.

3. Environment-Specific Logic:

   // Check config values dynamically:
   config('app.debug');
   

   • Verify environment variables or cached config without restarting the server.

4. Seeding Data:

   // Run a seeder method interactively:
   $seeder = new UserSeeder();
   $seeder->run();
   

   • Useful for partial seeding or debugging seeders.

5. Integration with Artisan Commands:

   // Test a command's logic:
   $command = new OptimizeCommand();
   $command->handle();
   

   • Validate command logic before committing changes.

Advanced Patterns

1. Custom Output Modifiers: Create a modifier to format outputs (e.g., JSON):

   // app/OutputModifiers/CustomJsonModifier.php
   namespace App\OutputModifiers;
   use Spatie\WebTinker\OutputModifiers\OutputModifier;
   
   class CustomJsonModifier implements OutputModifier {
       public function modify(string $output = ''): string {
           return json_encode(json_decode($output), JSON_PRETTY_PRINT);
       }
   }
   

   Update config:

   'output_modifier' => \App\OutputModifiers\CustomJsonModifier::class,
   

2. Middleware Customization: Restrict access to specific users:

   // config/web-tinker.php
   'middleware' => [
       \Illuminate\Session\Middleware\StartSession::class,
       \App\Http\Middleware\CheckUserRole::class, // Custom middleware
   ],
   

3. PsySH Configuration: Override default PsySH behavior (e.g., disable history):

   // config/web-tinker.php
   'config_file' => '.psyshrc',
   

   Create .psyshrc in your project root:

   Psy\Configuration::getInstance()->setOption('history', false);
   

4. Dark Mode Toggle: Force dark mode for all users:

   // config/web-tinker.php
   'theme' => 'dark',
   

Gotchas and Tips

Pitfalls

1. Security Risks:

   • Never enable in production (enabled: true in config). The package executes arbitrary PHP code.
   • Restrict access: Always use middleware (e.g., Authorize) or IP filtering if enabling in staging.

2. Docker Hanging Requests:

   • Use the latest version (1.10.2+) to avoid infinite loops in Docker. If issues persist, ensure your container has proper signal handling.

3. Output Formatting Quirks:

   • HTML Injection: The package sanitizes output by default (since v1.9.1). If you need raw output, disable sanitization in the frontend (not recommended).
   • Whitespace/Comments: Input code is stripped of comments before execution (since v1.3.1). Avoid relying on inline comments for logic.

4. PsySH Configuration Conflicts:

   • Custom .psyshrc files may conflict with Laravel’s Tinker. Test thoroughly after changes.
   • Tip: Use php artisan tinker in parallel to verify behavior.

5. Middleware Order:

   • The package adds EncryptCookies and StartSession middleware. If you override the list, ensure session middleware is included for user-specific access control.

Debugging Tips

1. Empty Output?:

   • Check for PHP errors in Laravel logs (storage/logs/laravel.log). Web Tinker may silently fail if the underlying PsySH execution errors.
   • Verify the route exists:

     php artisan route:list | grep tinker
     

2. Slow Performance:

   • Web Tinker runs in a synchronous loop. For heavy operations, offload work to queues or use Artisan::call() in the terminal instead.

3. Dark Mode Not Applying:

   • Clear browser cache or check for CSS conflicts. The theme is stored in localStorage and persists across sessions.

4. Custom Modifier Not Working:

   • Ensure the class implements Spatie\WebTinker\OutputModifiers\OutputModifier and is autoloaded (add to composer.json if needed).

Extension Points

1. Custom Commands: Add a button to run predefined commands:

   // resources/js/web-tinker.js (published by the package)
   // Extend the Vue component to add a custom button
   methods: {
       runCustomCommand() {
           this.execute('User::all()->count();');
       }
   }
   

2. API Integration: Use the /tinker endpoint as a lightweight API for trusted internal tools:

   // Example: Create a route to proxy Tinker output
   Route::post('/api/tinker', function (Request $request) {
       $output = \Spatie\WebTinker\WebTinker::execute($request->input('code'));
       return response()->json(['output' => $output]);
   })->middleware('trusted');
   

3. Logging Execution: Extend the Authorize middleware to log Tinker usage:

   // app/Http/Middleware/LogWebTinker.php
   public function handle($request, Closure $next) {
       \Log::info('WebTinker accessed by ' . auth()->id());
       return $next($request);
   }
   

   Add to config:

   'middleware' => [
       \App\Http\Middleware\LogWebTinker::class,
       // ...
   ],
   

4. Multi-Tenancy: Override the Authorize middleware to scope Tinker to the current tenant:

   // app/Http/Middleware/Authorize.php (override Spatie's middleware)
   public function handle($request, Closure $next) {
       if (!auth()->check() || !auth()->user()->can('viewWebTinker')) {
           abort(403);
       }
       // Set tenant context
       app()->setLocale(Tenant::find(auth()->id())->locale);
       return $next($request);
   }