Psysh Laravel Package

Product Decisions This Supports

• Build vs. buy for developer tooling: PsySH answers the recurring "should we build our own REPL/console for our PHP product?" question with a firm no. It is an MIT-licensed, ~9.8k-star, actively maintained runtime console that already powers the interactive layers of Laravel Tinker, Drush, and MediaWiki. Building an equivalent means re-implementing input editing, history, completion, output formatting, and shell integration — months of work for zero differentiation.
• Developer experience as a roadmap pillar: An embedded REPL shortens the loop between "I have a hypothesis about this object" and "I have the answer." This supports investment in onboarding tooling, internal documentation, and workshops, and gives a measurable DevEx win (time-to-first-successful-query for new engineers).
• Debugging strategy: PsySH positions as an interactive debugger alongside Xdebug/step-debuggers, not a replacement. It supports the decision to standardize on "poke at live state" workflows (inspect a service, call a repository method, replay a failing case) for the 80% of incidents where attaching a debugger is disproportionate.
• Framework / platform product surface: If you ship a PHP framework, CMS, or CLI, embedding PsySH is a differentiating feature you can market ("a real interactive console, out of the box") without owning the maintenance burden.
• Extensibility roadmap: A custom-command API, configurable themes, magic-variable conventions ($_), clipboard/pager support, and runtime config commands mean you can layer product-specific commands (e.g. tenant:inspect, queue:peek) on top rather than forking.
• Security posture and risk decisions: The upstream CVE-2026-25129 fix plus the new Restricted Mode / project-trust model (trustProject: prompt|always|never, PSYSH_TRUST_PROJECT, --trust-project) directly informs policy: whether a console may be run against untrusted working directories, whether it's permitted in production, and what your pinned-version floor must be.
• Support and incident-response tooling: A trusted, sandboxed console is a legitimate operational lever (read-only diagnosis, cache inspection, data correction) — provided the trust and access-control decisions are made deliberately rather than by accident.
• Buy-vs-extend on terminal UX: The experimental pure-PHP readline (syntax-aware completion, multi-line editing, Ctrl+R history search, pager) is a roadmap signal: the terminal experience is being actively improved upstream, so consuming it beats investing in a bespoke shell.
• Training and documentation content: The doc command, ls, show, and inline manual lookups make PsySH a teaching surface — supporting decisions to ship "learn the codebase in the console" guides.

When to Consider This Package

Adopt when:

• You maintain a PHP application, framework, or CLI and want an interactive console that already understands classes, docblocks (@method/@property included), and live runtime values.
• You need an embeddable REPL (a Shell you configure and drive programmatically), not just a standalone binary.
• Your team works in terminals and values history search, fuzzy/type-aware completion, and multi-line editing over GUI tooling.
• You are willing to pin versions and track security advisories — the trust/restricted-mode model is now a first-class part of the product and must be configured, not ignored.
• You want to extend the console with domain-specific commands instead of writing your own shell.

Look elsewhere or proceed with caution when:

• You need a full step debugger with breakpoints, variable watches, and stack inspection — pair PsySH with Xdebug rather than substituting it.
• You need a GUI or browser-based debugging experience.
• Your product is not PHP, or targets PHP versions outside the supported matrix.
• You require a hardened, multi-tenant execution sandbox: PsySH executes arbitrary code by design. If "run arbitrary PHP" is unacceptable in the target environment, this is the wrong tool, and no trust prompt makes it the right one.
• You need a stable public API contract — the project is still on 0.x; minor releases have shipped behavior changes (e.g. config/copy now resolving to shell commands before PHP functions) and features labeled experimental.
• You depend on long-term vendor support or a multi-maintainer bus factor; this is a focused, largely single-maintainer OSS project. Budget for the possibility of forking or pinning.

How to Pitch It (Stakeholders)

For executives (one paragraph): PsySH is a free, MIT-licensed, battle-tested interactive console for PHP — the engine behind Laravel Tinker and Drush, with nearly 10,000 GitHub stars and near-monthly releases. Adopting it gives our engineers a production-grade "talk to the running app" tool at effectively zero licensing cost and no build effort, and it lets us ship a developer console as a product feature rather than a maintenance liability. The main governance item is security hygiene: we pin a version at or above the Restricted Mode release and set an explicit trust policy so the console never loads config from untrusted directories.

For engineering leadership:

• Don't build. We would be re-implementing readline behavior, completion, output formatting, history, and shell integration — all areas where upstream is actively shipping (syntax-aware completion, pager, clipboard, runtime config).
• Integration is small. Instantiate a configured Shell, register product-specific commands, ship a thin binary. Upstream maintains downstream smoke tests for Laravel and MediaWiki, which lowers integration risk.
• What we own: version pinning, upgrade cadence, the trust/restricted-mode configuration, our custom commands, and the decision about where a console is allowed to run.

For security and platform:

• Require the patched floor (≥ v0.12.19 / v0.11.23) for the CWD configuration-poisoning fix.
• Set trustProject explicitly rather than relying on interactive prompts, and define whether consoles are permitted in production and under what guardrails.
• Treat non-interactive invocation as a distinct risk class; verify degraded-mode behavior in CI.

Risks to flag: 0.x versioning with occasional behavior changes; experimental features can shift; single-maintainer concentration; and the inherent reality that a REPL executes arbitrary code, which is a feature, not a defect — but must be scoped by policy.