Ray Laravel Package

Product Decisions This Supports

• Build vs. buy for internal developer tooling. spatie/ray is the free, MIT-licensed client library; the cost is the Ray desktop app (paid per-developer license, free trial capped at 20 messages per session). This is a "buy the app, adopt the free library" decision, not a build decision — no credible case exists for engineering an internal replacement.
• Standardizing the debugging workflow across the stack. The pitch is syntax parity: the same debug call works in Laravel, vanilla PHP, JavaScript, and other frameworks. A PM can frame this as one debugging tool and one mental model instead of dd(), var_dump(), console.log(), browser devtools, and log tailing as separate rituals.
• DX / engineering-productivity roadmap prioritization. If your roadmap has a "developer experience" or "delivery velocity" theme, this is a cheap, low-risk line item with an obvious before/after. It competes well against larger platform investments because the cost is a seat license and an afternoon of setup.
• Codebase hygiene as a policy decision. The package ecosystem ships a PHPStan rule to detect ray() calls and a Rector rule to remove them (changelog 1.41.0 and 1.37.1). That converts "should we allow debug calls in the repo?" from a style argument into an enforceable CI gate — a concrete decision a PM can own with engineering.
• Onboarding and ramp-time investment. New hires on a Laravel codebase spend a disproportionate share of week one re-learning how to inspect queries, payloads, and data shapes. A familiar, low-friction debugging surface shortens that loop and reduces "ask a senior dev to pair-debug" interruptions, which is a measurable drain on senior engineers.
• AI-assisted development workflow. The README calls out an MCP server for viewing and interacting with output that AI tooling sends to Ray. If AI coding assistants are on your roadmap, this is a decision input about whether inspection of AI-generated runtime behavior lives inside the same tool your engineers already use.
• Explicitly not a customer-facing feature. This earns no roadmap slot, no launch, no marketing moment, and no SLA. It should be budgeted and evaluated as internal tooling — the success metric is cycle time on defects, not adoption by end users.
• Incident-prevention framing. Debug statements left in a codebase are a real (if low-frequency) production risk. Deciding on a standard tool plus a lint rule to strip calls before merge is a genuine reliability lever, not just a comfort feature.

When to Consider This Package

Adopt when:

• The backend is PHP or Laravel and debugging pain is a recurring, named complaint in retros or 1:1s — not a hypothetical.
• Engineers debug primarily on local machines or long-lived dev environments where a desktop app can receive messages.
• Per-seat license budget is available and procurement won't stall on a modest, single-vendor purchase.
• You want cross-language consistency (PHP + JS) and a single inspection surface rather than framework-specific tools.
• You're prepared to pair adoption with the PHPStan/Rector rules so debug calls don't accumulate in the repo.

Look elsewhere when:

• The real need is production observability. Ray is a local debugging aid. Sentry, an APM, or structured logging solves a different problem; don't let a cheap dev tool substitute for it.
• No license budget or procurement friction exists. The library alone is inert without the app. If the trial's 20-message-per-session cap will be hit daily and purchasing is slow, the rollout will quietly die.
• The team is already invested in Xdebug + IDE, Laravel Telescope, or Laravel Debugbar. Telescope and Debugbar are free and framework-native; asking engineers to abandon muscle memory for a paid tool needs a clear delta, not a marginal one.
• Environments are ephemeral, containerized, or CI-first. Any tool that assumes a long-lived desktop listener is a poor fit for short-lived workers, queue jobs in containers, or teams debugging primarily through CI logs.
• Security posture forbids new outbound debug channels. Some regulated environments won't sanction a local HTTP channel for arbitrary payloads, even dev-only.
• The org is not PHP-first. A JavaScript-majority team is served by browser devtools at zero cost; the PHP library adds nothing.
• Vendor concentration is a stated concern. Spatie maintains this actively (frequent releases through 2026, PHP 8.5 and Laravel 12/13 compatibility work), but it is a small commercial vendor. Mitigate by noting that the library is MIT and removal is composer remove plus a Rector pass.
• Run a pilot first. 3–5 engineers for two sprints before an org-wide purchase; measure defect turnaround and anecdotal friction, then decide on seats.

How to Pitch It (Stakeholders)

To executives: This is a small, per-seat purchase of a developer tool, paired with a free MIT library. It does not touch the product, the customer experience, or the architecture. The expected return is faster defect turnaround and less senior-engineer time burned on "help me debug this" interruptions. The downside is bounded: the library is free, the trial is free, removal is a single dependency drop, and the package is actively maintained (releases through late 2026, with explicit support for current PHP and Laravel versions). Approve a small pilot, not an org-wide commitment.

To engineering leadership: It gives you two things you currently lack — a consistent inspection surface across PHP and JS, and an enforceable rule to keep debug calls out of the codebase. Query inspection, performance measurement, and execution pausing live in one place, with PHPStan and Rector rules available to police it in CI. Config ships as a standard Laravel ray.php, and the library has no production role — it should be disabled outside local/dev by config, which we make an explicit rollout requirement.

To the engineers: It's the instant feedback of dump() and console.log() without the browser tab, the log file, or the re-run. It's the same call syntax you already know, extended to arrays, HTML, queries, Markdown, and traces, with pause-and-step control when you need it. If you don't like it after two sprints, we remove it and the codebase is unchanged.

Risks to name up front: license cost scales per developer seat; the value hinges entirely on the desktop app being installed and running; the tool is single-vendor and commercial even though the client library is open source. None of these are blockers, but all three should appear in the approval memo so nobody is surprised later.