Psysh Laravel Package

Product Decisions This Supports

• Developer Productivity Roadmap:

  • Enable real-time debugging and interactive exploration of PHP applications, reducing reliance on verbose logging or external tools (e.g., Xdebug).
  • Accelerate onboarding for new engineers by providing an intuitive REPL for testing Laravel/PHP logic without writing full test cases.
  • Support hot code reloading (via uopz) to iterate on features faster during development, aligning with modern frontend frameworks’ live-reload capabilities.

• Build vs. Buy:

  • Buy: Replace ad-hoc debugging scripts or CLI-based debugging (e.g., php artisan tinker) with a standardized, feature-rich REPL that integrates seamlessly with Laravel’s ecosystem.
  • Build: Avoid reinventing a REPL from scratch; leverage PsySH’s existing integrations (e.g., Laravel Tinker) and customization (themes, commands, config) to tailor it to team workflows.

• Key Use Cases:

  • Debugging: Inspect variables, chain method calls, and test edge cases interactively (e.g., >>> $user->load('roles')->roles).
  • Prototyping: Quickly validate API responses, database queries, or business logic without committing to a full feature branch.
  • Education: Train junior devs on PHP/Laravel patterns via live coding sessions (e.g., >>> help, >>> doc User::find()).
  • Legacy Codebase Exploration: Reverse-engineer unfamiliar codebases by querying objects/methods directly (e.g., >>> $this->container->get('auth')).
  • CI/CD Debugging: Attach PsySH to failed test runs or deployment artifacts to diagnose issues post-mortem (via --cwd or Docker exec).

• Security & Compliance:

  • Mitigate risks of untrusted project configurations (e.g., .psysh.php files) via Restricted Mode, ensuring alignment with internal security policies.
  • Justify adoption by highlighting CVE-2026-25129 fixes and explicit trust prompts as compliance-enabling features.

When to Consider This Package

Adopt PsySH If:

• Your team frequently debugs PHP/Laravel applications and spends time writing one-off scripts or logging statements.
• You need a REPL with IDE-like features (autocompletion, syntax highlighting, docblock introspection) without relying on external tools (e.g., PHPStorm).
• Hot code reloading (via uopz) is a priority for rapid iteration, especially in monolithic applications.
• You want to standardize debugging workflows across the org, reducing reliance on tribal knowledge or disparate tools.
• Your stack includes Laravel (native integration via tinker) or Symfony, where PsySH’s command-line tools are battle-tested.
• Security is a concern: Restricted Mode and explicit trust mechanisms align with your policies for untrusted environments (e.g., shared hosting, CI pipelines).

Look Elsewhere If:

• Your team prefers GUI tools (e.g., PHPStorm, VS Code Debugger) over CLI-based debugging.
• You’re not using PHP/Laravel/Symfony: PsySH’s value is tied to these ecosystems (e.g., no native support for Python/JavaScript REPLs).
• Performance is critical: PsySH adds overhead for production environments (use only in dev/staging).
• Your org lacks CLI access (e.g., serverless functions, PaaS with restricted shells).
• You need advanced profiling (use Xdebug + IDE instead) or distributed debugging (e.g., Sentry, Datadog).

Alternatives to Evaluate:

How to Pitch It (Stakeholders)

For Executives (Business/ROI Focus):

*"PsySH is a developer productivity multiplier that cuts debugging time by 30–50% for PHP/Laravel teams. By standardizing an interactive REPL—similar to Python’s ipython or JavaScript’s Node REPL—we eliminate the friction of writing throwaway scripts or guessing at variable states. This directly impacts:

• Faster feature delivery: Hot code reloading (via uopz) lets devs test changes instantly without restarting containers or servers.
• Reduced onboarding time: New hires can explore the codebase interactively (e.g., >>> $user->toArray()) instead of wading through logs or documentation.
• Lower support costs: Centralized debugging reduces ‘works on my machine’ issues by giving teams a shared tool for troubleshooting.
• Security alignment: Restricted Mode and CVE fixes ensure we’re not introducing risks from untrusted configurations.

Cost: Free (MIT license), minimal setup. ROI: Measured in dev hours saved—equivalent to hiring 0.5 FTE for a mid-sized team. Let’s pilot it with the backend squad and measure debugging time before/after."*

For Engineering Leaders (Technical Fit):

*"PsySH solves three critical pain points in our PHP stack:

1. Debugging at Machine Speed: Replace var_dump() chains with a real REPL where you can inspect objects, chain methods, and test logic interactively (e.g., >>> $order->items()->where('status', 'shipped')->count()). Autocompletion and syntax highlighting reduce typos and speed up exploration.
2. Laravel-Native Integration: Since we use Laravel, artisan tinker is already a PsySH wrapper—this gives us consistency and access to all PsySH features (e.g., hot reloading, clipboard support).
3. Security Without Sacrifice: Restricted Mode prevents malicious .psysh.php files from executing arbitrary code, while the experimental readline (opt-in) offers better UX than ext-readline—no more fighting the shell for multi-line closures or history navigation.

Migration Path:

• Start with composer require psy/psysh and replace ad-hoc tinker usage with PsySH’s richer feature set.
• Enable hot reloading (uopz) for teams working on monolithic apps (e.g., legacy codebases).
• Pilot Restricted Mode in CI/CD to enforce trust policies for untrusted repos.

Risks:

• Minimal: PsySH is battle-tested (9.8K stars, used by Laravel). The experimental readline is opt-in and can be disabled.
• Mitigation: Start with the stable readline backend and gradually adopt experimental features as feedback comes in."*

For Developers (Day-to-Day Value):

*"PsySH turns your terminal into a PHP IDE. Here’s how it’ll change your workflow:

• No More var_dump() Hell: Inspect variables with >>> $user and get pretty-printed output with autocompletion. Chain methods like a pro: >>> $user->posts()->where('published', true)->count().
• Hot Reloading: Edit a method in User.php, switch back to PsySH, and your changes are live—no php artisan serve restart. (Requires uopz extension.)
• Autopilot Mode: Struggling with a complex object? Type $obj-> and see methods/properties in a menu. Fuzzy matching means asum autocompletes to array_sum.
• Clipboard Magic: Copy results to your clipboard with >>> $result; copy—no manual echo + Ctrl+C.
• Laravel Superpowers: Use >>> app() to inspect the container, or >>> route('profile') to debug routes.

Get Started:

1. Install: composer require psy/psysh
2. Run: ./vendor/bin/psysh (or php artisan tinker for Laravel)
3. Pro Tip: Add this to your .bashrc for instant access:

   alias psysh='[ -f vendor/bin/psysh ] && vendor/bin/psysh || php -a'
   

Slack Emoji: 🚀 (You’ll never go back to var_dump.)"