Psysh Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require psy/psysh
   

   For Laravel projects, PsySH is often pre-installed via laravel/tinker (which uses PsySH under the hood).

2. First Run:

   vendor/bin/psysh
   

   This launches an interactive REPL with access to your project’s autoloaded classes and functions.

3. First Use Case:

   • Debugging: Test a query builder result:

     >>> $users = User::where('active', true)->get();
     >>> $users->count()
     => 42
     

   • Inspecting Objects: Dive into a model’s relationships:

     >>> $user = User::first();
     >>> $user->posts
     => Collection {#324 ...}
     

Key Starting Points

• Magic Variables: $_ (last result), $_SERVER, $_ENV, etc.
• Commands: Type help or ? for built-in commands (e.g., ls, doc, edit).
• Configuration: Check ~/.psyshrc.php or .psysh.php in your project root for customizations.

Implementation Patterns

Daily Workflows

1. Debugging Logic:

   • Step-through Evaluation: Test snippets of logic interactively:

     >>> $total = 0;
     >>> for ($i = 0; $i < 10; $i++) {
     ...     $total += $i;
     ... }
     >>> $total
     => 45
     

   • Exception Handling: Catch and inspect exceptions:

     >>> try { User::find(999); } catch (\Exception $e) { $e }
     => Illuminate\Database\Eloquent\ModelNotFoundException {#324 ...}
     

2. Database Exploration:

   • Query Building: Craft queries dynamically:

     >>> $query = User::query();
     >>> $query->where('created_at', '>', now()->subDays(7));
     >>> $query->get()->count()
     => 15
     

   • Raw SQL: Execute raw queries and inspect results:

     >>> DB::select('SELECT * FROM users LIMIT 5');
     => array:5 [ ... ]
     

3. Testing APIs/Endpoints:

   • HTTP Requests: Use Http::get() or Http::post() to test API responses:

     >>> $response = Http::get('https://api.example.com/users');
     >>> $response->json()
     => ["data"=>[ ... ]]
     

4. Configuration Inspection:

   • Environment Variables: Access .env values:

     >>> config('app.debug')
     => true
     >>> env('APP_URL')
     => "https://example.com"
     

5. Artisan Commands:

   • Run Artisan: Execute commands programmatically:

     >>> Artisan::call('migrate:status');
     >>> Artisan::output()
     => "Migrations status: ..."
     

Integration Tips

• Laravel-Specific:

  • Use use App\Models\User; to auto-load models (or rely on Laravel’s autoloader).
  • Access the container directly:

    >>> app('db')->connection()->getPdo();
    

  • Event Listeners: Trigger events and inspect listeners:

    >>> event(new \App\Events\UserRegistered($user));
    

• Custom Helpers:

  • Add project-specific helpers to .psysh.php:

    // .psysh.php
    function dd(...$args) {
        \Psy\Output\Output::dumpAndDie(...$args);
    }
    

• History Management:

  • Use history to browse past commands.
  • Save sessions with save and reload with load.

• Multi-Line Editing:

  • Press Enter mid-statement to continue on the next line (with proper indentation).
  • Use Ctrl+D to exit multi-line input.

Gotchas and Tips

Pitfalls

1. Security:

   • Restricted Mode: PsySH now requires explicit trust for project-local configs (.psysh.php) and autoloads. If you see warnings about untrusted projects:
     • Use --trust-project flag or set 'trustProject' => 'always' in config.
     • Avoid running PsySH in directories you don’t control (e.g., public uploads).
   • CVE-2026-25129: Ensure you’re on v0.12.19+ or v0.11.23+ to avoid config poisoning.

2. Autoloading:

   • Missing Classes: If a class isn’t autoloaded, ensure:
     • Composer’s autoload.php is loaded (check psy\info()).
     • The class is in a psr-4 namespace or manually included.
   • Laravel-Specific: Use composer dump-autoload if classes are missing.

3. Output Quirks:

   • Semicolons: By default, statements ending with ; suppress output (like MATLAB). Use ;; if 'semicolonsSuppressReturn' => 'double' is set.
   • Multiline Strings: Use heredoc syntax (<<<EOD ... EOD) for cleaner output. Avoid """ for consistency.

4. Experimental Features:

   • Interactive Readline: Enable with --experimental-readline or 'useExperimentalReadline' => true. Opt-in due to potential bugs.
   • Syntax Highlighting: Disable with 'useSyntaxHighlighting' => false if it’s distracting.

5. Performance:

   • Hot Reloading: Requires the uopz extension. Not all code can be reloaded (e.g., class properties). Use yolo to bypass safety checks.
   • Memory Usage: Large objects (e.g., User::all()) may bloat the REPL. Use unset($var) to free memory.

Debugging Tips

1. Inspecting Variables:

   • Use var_dump() or print_r() for raw output:

     >>> var_dump($user);
     

   • Use Psy\Output\Output::dump() for colored, formatted output.

2. Command Not Found:

   • Prefix with \ to force PHP execution (e.g., \config instead of config).
   • Check psy\info() for loaded commands.

3. Terminal Issues:

   • Stuck Input: Press Ctrl+C to interrupt. If it doesn’t work, try Ctrl+\ or restart the shell.
   • Pager Problems: Disable with --no-pager if output is truncated.

4. Configuration Overrides:

   • Runtime config changes (e.g., config pager false) persist only for the current session.
   • Global config is stored in ~/.psyshrc.php or .psysh.php.

Extension Points

1. Custom Commands:

   • Create a class implementing Psy\Command\CommandInterface and register it in .psysh.php:

     $commands[] = new class implements \Psy\Command\CommandInterface {
         public function getName() { return 'mycmd'; }
         public function getDescription() { return 'My custom command'; }
         public function handle(\Psy\Shell $shell) {
             echo "Hello from mycmd!\n";
         }
     };
     

2. Themes:

   • Customize syntax highlighting by extending the theme in .psysh.php:

     'theme' => [
         'prompt' => '<fg=blue>psysh</> <fg=green>%s</>',
         'keywords' => ['<fg=yellow>'],
         'strings' => ['<fg=magenta>'],
     ];
     

3. Clipboard Integration:

   • Configure clipboard commands for copy:

     'clipboardCommand' => 'pbcopy', // macOS
     'clipboardCommand' => 'xclip -selection clipboard', // Linux
     

4. Exception Details:

   • Add context to exceptions via exceptionDetails:

     'exceptionDetails' => function (\Throwable $e) {
         return "File: {$e->getFile()}:{$e->getLine()}\n" . $e->getTraceAsString();
     };
     

5. Hot Reloading:

   • Whitelist risky files for yolo:

     'hotReload' => [
         'whitelist' => [__DIR__ . '/app/Helpers/*.php'],
     ];