Psysh Laravel Package

Technical Evaluation

Architecture Fit

PsySH is a runtime REPL (Read-Eval-Print Loop) for PHP, designed to provide an interactive debugging and development environment. For a Laravel-based application, it fits well as:

• A local development tool for rapid iteration, debugging, and exploration of the application state.
• A replacement for tinker (Laravel’s built-in REPL) with advanced features like syntax-aware autocompletion, multi-line editing, and experimental readline.
• A complement to Laravel’s debugging tools (e.g., dd(), dump(), and log()) by allowing live inspection and manipulation of objects, variables, and application state.

Key Strengths: ✅ Deep PHP integration – Works seamlessly with Laravel’s dependency injection, service container, and Eloquent models. ✅ Advanced autocompletion – Syntax-aware, type-aware, and runtime-value-aware completions (e.g., $user-> suggests actual methods/properties). ✅ Multi-line editing & syntax highlighting – Improves productivity for complex queries or debugging sessions. ✅ Hot code reloading (with uopz) – Allows live modification of functions/methods without restarting the REPL. ✅ Security improvements – Restricted Mode prevents arbitrary code execution from untrusted .psysh.php files (critical for shared environments).

Potential Gaps: ⚠ Not a production tool – PsySH is not designed for server-side execution; it’s strictly a development aid. ⚠ Terminal-dependent – Some features (e.g., clipboard integration, experimental readline) require specific terminal support. ⚠ Learning curve – While intuitive, advanced features (e.g., yolo for unsafe reloading, custom exception details) may require documentation.

Integration Feasibility

PsySH integrates with Laravel via:

1. Composer (require psy/psysh).
2. Artisan Command (Laravel’s built-in REPL wrapper).
3. Custom Configuration (.psysh.php for project-specific settings).

Laravel-Specific Considerations:

• Service Container Access – PsySH inherits Laravel’s container, allowing direct access to bound services (e.g., $app->make('UserRepository')).
• Eloquent & Query Builder – Full support for querying databases interactively.
• Middleware & Routing – Can inspect resolved middleware or simulate requests via Route::current() or app('router').
• Event Listeners – Can trigger events dynamically (e.g., event(new UserRegistered($user))).

Example Workflow:

# Start PsySH in a Laravel project
php artisan psy

# Inspect a user
$user = App\Models\User::find(1);
$user->posts()->count();

# Modify a model method live (with uopz)
yolo $user->getFullName() => $user->name . ' ' . $user->last_name;

Feasibility Score: 9/10

• Low-risk integration (MIT license, no breaking changes in recent versions).
• Backward-compatible with Laravel Tinker (can replace it entirely).
• Minimal performance overhead (only active during REPL sessions).

Technical Risk

Critical Path:

• Security hardening (Restricted Mode must be enabled by default in Laravel integration).
• Performance testing (ensure no slowdowns in CI or production-like environments).

Key Questions for TPM

1. Replacement Strategy

   • Should PsySH replace Laravel Tinker entirely, or run side-by-side for feature parity?
   • How will we handle deprecation of tinker if we switch?

2. Configuration Management

   • Should .psysh.php be auto-generated in new Laravel projects with sensible defaults?
   • How will we handle team-specific configurations (e.g., custom themes, aliases)?

3. CI/CD & Testing

   • Should PsySH be pre-installed in dev containers (Docker, Vagrant)?
   • How will we test REPL interactions in automated workflows?

4. User Adoption

   • What training is needed for teams unfamiliar with REPLs?
   • Should we bundle PsySH-specific docs in Laravel’s official documentation?

5. Long-Term Maintenance

   • How will we handle upstream PsySH updates (e.g., breaking changes in v1.0)?
   • Should we fork PsySH to add Laravel-specific features (e.g., laravel: namespace commands)?

Integration Approach

Stack Fit

PsySH is optimized for:

• Laravel 10/11 (Symfony 6.4+/7.x compatible).
• PHP 8.1+ (best compatibility with recent features).
• Terminal-based workflows (VS Code, iTerm, Windows Terminal).

Compatibility Matrix:

Migration Path

Phase 1: Pilot (Dev Teams Only)

1. Add PsySH to composer.json:

   composer require psy/psysh --dev
   

2. Alias tinker to psy (optional):

   alias tinker='php artisan psy'
   

3. Test in local dev environments (no production impact).

Phase 2: Default Integration

1. Update Laravel’s artisan command:
   • Modify vendor/laravel/framework/src/Illuminate/Foundation/Console/Kernel.php to include PsySH as a default REPL.
   • Example PR: Laravel’s Tinker Integration.
2. Add .psysh.php template:

   // config/psysh.php (auto-generated)
   return [
       'trustProject' => 'prompt',
       'useExperimentalReadline' => env('PSYSH_EXPERIMENTAL_READLINE', false),
       'theme' => 'laravel', // Custom theme
   ];
   

3. Document migration:
   • Guide users on key differences (e.g., ;; for semicolon suppression, yolo for unsafe reloads).

Phase 3: Deprecation (Optional)

• Deprecate tinker in Laravel 12+ with a warning:

  php artisan tinker
  # Warning: `tinker` is deprecated. Use `php artisan psy` instead.
  

Compatibility

Fallback Plan:

• If PsySH fails (e.g., missing ext-readline), fall back to a basic REPL with a warning.

**