Psysh Laravel Package

Technical Evaluation

Architecture Fit

PsySH is a runtime REPL (Read-Eval-Print Loop) for PHP, designed to enhance developer productivity by providing an interactive debugging and exploration environment. For a Laravel-based application, it fits well as a complementary tool to Laravel Tinker (which is built on PsySH). Key alignment points:

• Laravel Compatibility: PsySH is the foundation of Laravel Tinker, ensuring seamless integration with Laravel’s ecosystem (e.g., Eloquent models, service containers, and Blade templates).
• PHP-Centric: Works natively with PHP’s runtime, making it ideal for inspecting variables, testing logic, and debugging without full application restarts.
• Modular Design: PsySH’s command system (e.g., ls, doc, show) aligns with Laravel’s introspection needs (e.g., inspecting routes, queues, or cached data).

Integration Feasibility

• Low-Coupling: PsySH can be integrated as a standalone CLI tool or embedded into Laravel’s artisan commands (e.g., php artisan psysh). No major architectural changes are required.
• Dependency Overlap: PsySH relies on Symfony’s Console component (already used in Laravel), reducing friction for dependency management.
• Configuration Flexibility: Supports project-specific configs (.psysh.php) and CLI flags, allowing customization for CI/CD or production-like environments (e.g., --no-pager for scripts).

Technical Risk

• Security: Recent fixes (e.g., CVE-2026-25129) highlight the need for Restricted Mode (trustProject) to mitigate risks from untrusted directories. Requires explicit trust management in CI/CD pipelines.
• Experimental Features: Features like interactive readline or hot code reloading (via uopz) may introduce instability. These should be opt-in and tested in staging.
• Performance: PsySH’s syntax-aware autocompletion and runtime reflection add overhead. Benchmark in high-traffic environments (e.g., Laravel Horizon workers).
• PHP Version Support: Tested up to PHP 8.3; ensure compatibility with Laravel’s supported versions (e.g., 8.2/8.3).

Key Questions

1. Use Case Prioritization:
   • Is PsySH needed for debugging, prototyping, or CI/CD scripting? Prioritize features accordingly (e.g., disable useExperimentalReadline in CI).
2. Security Hardening:
   • Should trustProject default to never in CI, with manual overrides for trusted repos?
3. Performance Impact:
   • How does PsySH’s reflection overhead affect Laravel’s boot time or request processing?
4. Alternatives:
   • Compare with Laravel Tinker (built-in) or PHP’s native php -a. Justify PsySH’s added value (e.g., better autocompletion, clipboard support).
5. Maintenance:
   • Who will manage PsySH updates (e.g., security patches)? Align with Laravel’s release cycle.

Integration Approach

Stack Fit

• Laravel Native: PsySH is the backbone of Laravel Tinker. Leverage existing integrations (e.g., php artisan tinker) or extend it via custom artisan commands.
• Symfony Console: PsySH’s dependency on Symfony Console ensures compatibility with Laravel’s CLI foundation.
• PHP Extensions: Requires ext-readline or ext-libedit for traditional readline (or use PsySH’s experimental pure-PHP readline for cross-platform consistency).

Migration Path

1. Pilot Phase:
   • Install PsySH globally (composer global require psy/psysh) or locally (composer require --dev psy/psysh).
   • Test in a non-production Laravel environment with a .psysh.php config to customize:

     return [
         'useExperimentalReadline' => true, // Opt-in for new features
         'trustProject' => 'prompt',       // Security best practice
         'clipboardCommand' => 'pbcopy',   // macOS clipboard support
     ];
     

2. Gradual Adoption:
   • Replace php artisan tinker with php artisan psysh for feature parity.
   • Add PsySH to composer.json scripts for CI/CD debugging:

     "scripts": {
         "debug": "psysh"
     }
     

3. Custom Integration:
   • Extend PsySH with Laravel-specific commands (e.g., route:list, queue:work --psysh) using PsySH’s command system.

Compatibility

• Laravel-Specific:
  • PsySH respects Laravel’s service container, allowing direct access to bound services (e.g., $app->make('auth')).
  • Works with Laravel’s helpers (e.g., route(), view()) and facades (e.g., Cache::remember()).
• Environment Awareness:
  • Use --cwd to run PsySH in the Laravel root, ensuring autoloading and config paths are correct.
  • Avoid running in production (disable in .env or via APP_ENV checks).

Sequencing

1. Pre-Deployment:
   • Add PsySH to composer.json and test in staging.
   • Configure .psysh.php for team-specific settings (e.g., themes, clipboard).
2. CI/CD:
   • Use PsySH for debugging failed tests or interactive debugging in GitHub Actions/GitLab CI:

     - name: Debug on failure
       if: failure()
       run: psysh --no-pager --trust-project=always
     

3. Production:
   • Never expose PsySH in production. Use feature flags or environment checks to block access:

     if (app()->environment('production')) {
         throw new RuntimeException('PsySH disabled in production.');
     }
     

Operational Impact

Maintenance

• Update Cadence: PsySH releases monthly. Align updates with Laravel’s minor releases to avoid breaking changes.
• Dependency Management:
  • Monitor Symfony Console updates (shared dependency).
  • Pin psy/psysh to a specific version in composer.json for stability.
• Security:
  • Subscribe to PsySH’s security advisories.
  • Audit .psysh.php files for malicious config (e.g., eval or shell_exec).

Support

• Developer Onboarding:
  • Document PsySH commands (e.g., help, doc, show) in the team’s debugging guide.
  • Highlight magic variables ($_, $_SERVER, $app) for Laravel-specific use cases.
• Troubleshooting:
  • Common issues:
    • Readline errors: Use --experimental-readline for cross-platform support.
    • Autoload failures: Ensure composer dump-autoload is run post-install.
    • Permission denied: Verify trustProject settings and directory permissions.
  • Provide a debug script to capture PsySH logs:

    PSYSH_LOG=1 psysh --no-pager > psysh-debug.log
    

Scaling

• Performance:
  • PsySH’s autocompletion and reflection add latency. Mitigate by:
    • Disabling useExperimentalReadline in CI.
    • Using --no-pager for scripted usage.
  • Avoid running PsySH in long-running processes (e.g., Laravel queues) due to memory leaks.
• Resource Usage:
  • PsySH’s hot code reloading (with uopz) increases memory usage. Disable in production-like environments.

Failure Modes

Ramp-Up

• Training:
  • Conduct a 30-minute workshop covering:
    • Basic REPL usage (e.g., ls App\Models, doc User).
    • Laravel-specific tricks (e.g., $user = User::first(); $user->load('posts')).
    • Debugging with var_dump, dd, and `