Getting Started

Minimal Steps

Installation:
```
composer require psy/psysh
```
For Laravel projects, use laravel/tinker (built on PsySH) or install PsySH directly.
First Use:
```
vendor/bin/psysh
```
Or in Laravel:
```
php artisan tinker
```

First Command:

$user = App\Models\User::first();
$user->name; // Inspect property

Where to Look First

Usage Wiki – Covers magic variables ($_, $_E, $_S), history, and shell integration.
Magic Variables – Essential for debugging (e.g., $_ for last result, $_E for last exception).
Commands – List of built-in commands like ls, doc, edit, and copy.

First Use Case: Debugging a Laravel Model

// Load a model
$user = App\Models\User::find(1);

// Inspect properties
$user->name;

// Call a method interactively
$user->posts()->count();

// Use magic variables
$_ // Last result (count)
$_E // Last exception (if any)

Implementation Patterns

Daily Workflows

Interactive Debugging:

Use ls to list methods/properties of an object:

$user = App\Models\User::first();
ls($user); // Lists all methods/properties

Inspect with show:
```
show($user->posts); // Detailed output
```

Code Exploration:
- Use doc to view PHPDoc for a class/method:
```
doc(App\Models\User); // Shows class docblock
```
- Autocomplete with Tab (e.g., $user-> → press Tab to list methods).

Quick Tests:

Test snippets without writing a full script:

$valid = Validator::make(['email' => 'test@example.com'], ['email' => 'required|email']);
$valid->fails(); // Check validation
$_ // Last result (bool)

Shell Integration:

Use !! to execute shell commands:

!!ls -la // Lists files in the current directory

Pipe output to PsySH:

echo "<?php return 1 + 1;" | vendor/bin/psysh

Editing Code:
- Use edit to open a file in $EDITOR:
```
edit(app_path('Http/Controllers/UserController.php'));
```
- Hot Reloading (with uopz extension): Modify a file and switch back to PsySH—changes apply instantly.

Configuration:

Runtime config changes (e.g., disable syntax highlighting):
```
config('useSyntaxHighlighting', false);
```

Persistent config in .psysh.php (project root):

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

Integration Tips

Laravel: Use php artisan tinker (built on PsySH) for seamless integration with Laravel’s service container.
Custom Commands: Extend PsySH with custom commands by implementing Psy\Command\Command.
Autoloading: Ensure your project’s composer.json autoloads are visible in PsySH (check autoload_psr-4 in .psysh.php if needed).
Environment-Specific Config: Use PSYSH_CONFIG env var to point to a custom config file:
```
PSYSH_CONFIG=config/psysh-local.php vendor/bin/psysh
```

Gotchas and Tips

Pitfalls

Trust Project Warnings:
- PsySH v0.12.19+ requires explicit trust for local config (.psysh.php) or Composer autoloads in untrusted directories.
- Fix: Run vendor/bin/psysh --trust-project or set 'trustProject' => 'always' in config.
- Non-interactive contexts (e.g., CI/CD) may fail silently—use --no-trust-project to skip checks.
Hot Reloading Limitations:
- Does not work with:
  - New class methods/properties.
  - Changes to class inheritance or interfaces.
  - Static variables or conditional definitions (use yolo to bypass safety checks).
- Requires: uopz extension (pecl install uopz).
Experimental Readline:
- Enable with --experimental-readline or 'useExperimentalReadline' => true.
- Pros: Syntax-aware completions, multi-line editing, live syntax highlighting.
- Cons: May feel sluggish on older terminals; disable with config('useExperimentalReadline', false).
Magic Variables Overwritten:
- $_, $_E, $_S are overwritten on each command. Use show($_) to inspect the last result persistently.
Pager Issues:
- Output may hang if the pager (e.g., less) is closed early. Use --no-pager to disable:
```
vendor/bin/psysh --no-pager
```
Windows Line Endings:
- Use dos2unix or configure PsySH to handle CRLF line endings in .psysh.php:
```
'lineEnding' => "\n", // Force LF
```

Debugging Tips

Inspect PsySH State:
- Use psy\info() to check config, readline state, and environment:
```
psy\info();
```
- Run with --info flag for CLI output:
```
vendor/bin/psysh --info
```
Enable Verbose Mode:
- Debug issues with:
```
vendor/bin/psysh -vvv
```
- Or in-shell:
```
config('verbosity', 3);
```

Clipboard Issues:

If copy command fails, configure clipboardCommand in .psysh.php:

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

For SSH/remote terminals, use OSC 52:
```
'useOsc52Clipboard' => true,
```

Command Ambiguity:
- Prefix with ; to force PHP execution (e.g., ;config('key', 'value') instead of config('key', 'value')).
Performance:
- Disable syntax highlighting for large outputs:
```
config('useSyntaxHighlighting', false);
```
- Use compact output for deep objects:
```
config('compactOutput', true);
```

Extension Points

Custom Commands:

Create a class extending Psy\Command\Command:

namespace App\PsySH;
use Psy\Command\Command;

class MyCommand extends Command {
    public function __invoke() {
        $this->output->writeln('Hello from custom command!');
    }
}

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

Themes:
- Create a custom theme by extending Psy\Theme\Theme and add to .psysh.php:
```
'theme' => App\PsySH\CustomTheme::class,
```

Exception Details:

Add context to exceptions via exceptionDetails callback:

'exceptionDetails' => function (\Throwable $e) {
    return "Validation errors: " . json_encode($e->validator->errors());
},

Pre-Initialization:
- Run code before PsySH starts by defining PSYSH_PRE_INIT in .psysh.php:
```
'preInit' => [
    'App\PsySH\Bootstrap::init',
],
```

Pro Tips

Aliases:

Define shortcuts in .psysh.php:

'aliases' => [
    'u' => 'App\Models\User',
    'p' => 'App\Models\Post',
];

Now u::first() works instead of `App\Models

Psysh Laravel Package