Psysh Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require psy/psysh --dev
   

   Add to composer.json under require-dev to avoid deployment.

2. First Use:

   vendor/bin/psysh
   

   Or integrate with Laravel via php artisan tinker (uses PsySH under the hood).

3. First Command:

   >>> $user = new App\Models\User;
   >>> $user->name
   

Where to Look First

• Usage Wiki for core commands (help, ls, doc, edit).
• Magic Variables for $_, $_E, $_S (last result, exception, stack trace).
• Shell Integration for !bash commands.

First Use Case: Debugging a Laravel Query

>>> $users = User::where('active', true)->get();
>>> $users->count()
=> 42
>>> $users->first()->toArray()
=> ["id" => 1, "name" => "John", ...]

Implementation Patterns

Daily Workflows

1. Interactive Debugging:

   >>> $order = Order::find(1);
   >>> $order->items->sum('price') // Calculate total
   => 99.99
   >>> $order->items->where('quantity', '>', 2) // Filter
   

2. Quick Testing:

   >>> use App\Services\PaymentService;
   >>> $service = new PaymentService();
   >>> $service->process($order) // Test logic
   

3. Shell Integration:

   >>> !ls -la // Run shell commands
   >>> !composer dump-autoload // Trigger Composer tasks
   

Laravel-Specific Patterns

• Artisan Integration:

  >>> \Artisan::call('migrate');
  

• Service Container Access:

  >>> $mailer = app('mailer');
  >>> $mailer->send(...);
  

• Model Introspection:

  >>> $user = new User();
  >>> $user-> // Tab-complete methods
  >>> doc User::find() // View method docs
  

Advanced Patterns

1. Code Reloading (with uopz): Edit app/Helpers.php, then in PsySH:

   >>> my_helper() // Changes reflect immediately
   

2. Custom Commands: Extend via Psy\Command\Command:

   namespace App\Psy;
   use Psy\Command\Command;
   
   class MyCommand extends Command {
       public function handle() {
           $this->output->writeln("Hello from custom command!");
       }
   }
   

   Register in .psysh.php:

   return [
       'commands' => [\App\Psy\MyCommand::class],
   ];
   

3. Configuration: Create .psysh.php in project root:

   return [
       'useExperimentalReadline' => true,
       'theme' => 'monokai',
   ];
   

Gotchas and Tips

Pitfalls

1. Trust Restrictions:

   • PsySH v0.12.19+ requires explicit trust for .psysh.php or local autoloads.
   • Fix: Run psysh --trust-project or set 'trustProject' => 'always' in config.

2. Code Reloading Limits:

   • Cannot reload:
     • New class methods.
     • Class properties/inheritance.
   • Workaround: Use yolo for risky reloads:

     >>> yolo !! // Force reload last command
     

3. Experimental Readline:

   • May cause instability on older PHP versions.
   • Debug: Run psysh --no-experimental-readline if issues arise.

4. Magic Variables Overwrite:

   • $_ (last result) is overwritten by new expressions.
   • Tip: Use $_E (exception) or $_S (stack trace) for debugging.

Debugging Tips

1. Inspect Stack Traces:

   >>> $_S // View full stack trace
   >>> $_E->getTraceAsString() // Exception trace
   

2. Enable Verbose Mode:

   >>> config('verbosity', 2) // Increase verbosity
   

3. Clear Screen:

   >>> cls // Clear terminal (or Ctrl+L)
   

4. History Navigation:

   • Ctrl+R for reverse search.
   • Filter history with partial commands, then Up/Down to select.

Extension Points

1. Custom Themes:

   • Extend Psy\Theme\Theme or use existing themes (e.g., monokai).
   • Example: Add to .psysh.php:

     'theme' => 'custom-theme',
     

2. Output Formatting:

   • Override Psy\Output\OutputFormatter for custom rendering.
   • Example: Disable compact output:

     'compactOutput' => false,
     

3. Clipboard Integration:

   • Configure clipboard commands:

     'clipboardCommand' => 'pbcopy', // macOS
     'useOsc52Clipboard' => true,   // SSH terminals
     

   • Copy results:

     >>> $result = some_function();
     >>> copy // Copies $result to clipboard
     

Performance Quirks

1. Large Data Dumping:

   • Use --no-pager to avoid pagination:

     psysh --no-pager
     

   • Tip: Limit output with array_slice():

     >>> (new Collection($users))->slice(0, 10)->toArray()
     

2. Experimental Readline Overhead:

   • Disable if laggy:

     'useExperimentalReadline' => false,
     

Security Notes

1. Restricted Mode:

   • Untrusted projects block .psysh.php and local autoloads.
   • Bypass: Use --trust-project or set 'trustProject' => 'always'.

2. CVE-2026-25129:

   • Upgrade to v0.12.19+ to mitigate config poisoning risks.

Pro Tips

1. Edit and Reload:

   >>> edit User // Opens User.php in editor
   >>> // Make changes, save, and switch back to PsySH
   >>> $user = new User(); // Reloaded changes
   

2. Shell Aliases: Add to ~/.bashrc:

   alias psyl='vendor/bin/psysh --trust-project'
   

3. Tab Completion:

   • Works for magic methods (@method in docblocks).
   • Example:

     >>> $user-> // Tab-completes magic methods like `offsetGet`
     

4. Semicolon Suppression:

   >>> $result = some_function(); // Returns $result
   >>> some_function(); // Suppresses return (v0.12.22+)