Peep Laravel Package

Technical Evaluation

Peep v0.1.0-beta.1 is a full-stack debugging and inspection platform, not a narrow library. It ships four distinct delivery surfaces — a Composer client (shibbirweb/peep, PHP 7.1+), a separate viewer server (server/, requires PHP 8.5 / AMPHP v3), a Tauri desktop app with bundled PHP 8.5, and PHAR builds for both client and server — plus a webhook simulator and an SMTP/SMS capture layer. For a TPM, the critical evaluation question is not "does it work" but "how much of this surface are we willing to underwrite in our own delivery pipeline."

Architecture fit. The Laravel adapter (auto-discovered, Laravel 5.5 → 13) is the expected entry point and is consistent with how mature Laravel dev-tooling integrates (Telescope, Ray, Clockwork). Defaults are sensible: disabled in production. Bridges for PSR-3, Monolog 1–3, and VarDumper 3.4–8.x mean teams with mixed-stack PHP services (Symfony, Slim, WordPress) can standardise on one inspector rather than several. The protocol is versioned (docs/protocol.md), which is a genuine sign of intent to stay stable across client/viewer drift.

Integration feasibility. Composer install plus auto-discovery gets a Laravel app running in minutes. The friction is the viewer: it requires PHP 8.5, which is newer than most teams run in CI or on laptops. That is not a blocker if teams use the desktop app or the peep-server.phar, but it is the first thing a technical decision-maker needs to confirm. The global install (auto_prepend_file) is powerful for legacy or non-Composer apps, and correspondingly the highest-risk feature: it changes every script in a PHP installation. Treat it as an opt-in escape hatch, not a default.

Technical risk.

• Beta status plus enormous scope. v0.1.0-beta.1 introduces mail catching, SMS catching, a webhook simulator with signature generation, a desktop app with an update channel, a query-debugging control plane, and a wiki. Each of those is independently a product. The version number does not match the surface.
• Two-PHP-version split. The client supports 7.1+, the viewer demands 8.5. This is a real deployment constraint and needs to be surfaced in the integration design rather than discovered later.
• Update channels. A beta/stable update channel in the desktop app implies self-updating binaries on developer machines — a supply-chain and IT-policy conversation, not just a feature.
• Production safety is stated but depends on defaults we must verify: "disabled in production by default" is only good if the detection logic is correct across non-Laravel frameworks and custom environments.
• Security posture looks considered (Host header check, Origin check, required UI header, CSP, sandboxed HTML payloads, token for non-loopback) but should be independently reviewed before the viewer is allowed on any network interface beyond loopback.

Key questions before adoption.

1. Who maintains this, and what is the bus factor behind four delivery surfaces plus a desktop updater?
2. What is the supported PHP version floor for the viewer in the next 6 months — will 8.4 be added, or is 8.5 a hard requirement?
3. Is the Laravel adapter's production-detection logic documented and testable?
4. What is the deprecation and versioning policy for the protocol (v1 is stated — what guarantees accompany it)?
5. What is the upgrade path for the desktop app if the project is abandoned mid-stream?

Integration Approach

Stack fit. The natural home is a Laravel monorepo or platform team standardising debugging across a mixed backend estate. Value is highest where the team currently runs a combination of Ray (paid), Telescope (Laravel-only), Clockwork (browser-focused), and ad-hoc dd() — Peep consolidates most of that into one inspector with one wire protocol. It maps cleanly onto PHP 7.1–8.4 client-side, which covers the vast majority of live Laravel codebases. The viewer, however, is a PHP 8.5 runtime and should be treated as a separate operational concern, not "just another composer package."

Migration path. The migration is additive, not a replacement:

1. Dev-only entry point. Add shibbirweb/peep as a require-dev dependency in Laravel. Verify auto-discovery, verify the production-disabled default in a staging environment, and confirm the query/event/job watchers do not measurably regress boot time.
2. Viewer on developer machines first. Use the desktop app (bundled PHP 8.5) or peep-server.phar to avoid touching developer PHP versions. Confirm the port-conflict detection and clean Ctrl+C behaviour in the desktop environment before rolling out.
3. Team standard. Replace dd()/dump()/Ray calls opportunistically; use vendor/bin/peep-clean --fix and the PHPStan rule to surface and remove leftovers before merging. This is the highest-leverage step for reducing drift and is low-risk because it targets only known, safe patterns.
4. Extend to mail/SMS/webhook capture only after the core inspector is stable. The webhook simulator is genuinely useful but should be scoped as a second-phase capability.

Compatibility. Laravel 5.5 → 13 is broad but includes many end-of-life versions; the team should not assume EOL Laravel gets bug-fixes. Symfony, Slim, WordPress, and plain PHP are covered via the bridges and setup guides; those paths should be trialled on exactly one service before being generalised. Coexistence with Telescope is fine — they write to different transports — but running both is redundant and should be a transitional state only.

Sequencing recommendation. Do not adopt the global install (peep.phar install / auto_prepend_file) in phase one. It is the feature with the widest blast radius, changes every PHP script, and is hard to audit. Adopt it only if there is a concrete fleet of non-Composer apps that justify it, and then through a configuration-management mechanism, not a per-machine manual install.

Operational Impact

Maintenance. The project owns an unusually large amount of surface area for a beta: a PHP client with a strict compatibility range (7.1–8.5), a PHP 8.5-only AMPHP v3 server, a Svelte 5/Bun/Vite UI, a Tauri 2 desktop app for three platforms, two PHAR pipelines, a Packagist auto-publish workflow, and a full CI matrix (40 Laravel × PHP jobs). For an adopting organisation this matters less for what it costs the project and more for the support expectation it creates: any team that standardises on Peep must be prepared to upgrade across Laravel 5.5–13 and PHP 7.1–8.5 on the client, while managing a viewer that is only on 8.5.

Support surface. The wiki is comprehensive and CI-published — a good sign. The realistic support burden inside the organisation is the viewer lifecycle (installation, port conflicts, token configuration across Docker/VMs on Linux, desktop update channel policy) plus the query-debugging switches which run against live apps. The switches are a shared control plane between the viewer and running applications: teams need a clear rule about who may flip them and when, or debugging sessions will collide.

Scaling. Two concerns. First, the viewer is designed for developer use — a virtual list handling 10,000+ cards and SSE replay after reconnect is engineering for one developer's session, not for a shared team instance. Running a single viewer for a whole team is likely to contend on the card-per-project limit and the SQLite history. Second, the SQLite-backed history grows unbounded; retention should be configured before adoption. The client-side scaling is fine by design — short timeouts, 30-second skip after a closed viewer, roughly 3 ms per 100 calls — which is the correct engineering for a tool that must not slow the app it observes. Confirm those numbers on the team's own Laravel boot path.

Failure modes to plan for.

• Viewer down: client should silently skip (documented behaviour) — verify with the team's actual config, especially the Laravel adapter when MAIL_MAILER=peep is set. A mailer pointing at a dead viewer is a failure path worth rehearsing.
• Port collision / two viewers: the server detects an already-running viewer and a port used by another program, but developers will still hit this. Publish a one-liner for the team.
• Token misconfiguration: PEEP_TOKEN / Laravel token across Docker on Linux is a documented but easy-to-miss step; without it the viewer binds to loopback and developers on remote containers see nothing.
• Production leak: if the production-disabled default is overridden (e.g. a misconfigured env), the client will attempt to reach a viewer. Confirm the failure is silent and cheap.
• Desktop auto-update: a beta channel update shipping an unexpected change to a binary on a developer laptop is an IT-policy incident, not a bug. Decide the channel policy centrally.
• Global install drift: auto_prepend_file will silently follow whatever version is installed; "projects with Composer keep their own version" mitigates but does not eliminate version drift across a fleet.

Ramp-up. Realistic effort bands:

• Laravel developer, dev-only usage: under an hour on Composer plus the desktop app to first useful inspection; a day to be productive with query debugging, mail capture, and ->peep() on collections/strings/builders.
• Team lead / DevEx owner: 1–2 days to define the production-safety policy, the viewer topology (desktop vs PHAR vs internal server), the update channel, and the peep-clean rule in CI.
• Platform/security review: should be a separate gate. The viewer's security controls are stated and appear well-designed, but "listen beyond loopback with a token" is a policy decision that belongs to security, not to the adopting developer.
• Non-Composer estates: the global install and bridges need a dedicated owner and a rollback plan; budget a week for a first service, not a first day.

Overall recommendation. Adopt in development on Laravel teams now, with the viewer on developer machines via the desktop app, peep-clean + the PHPStan rule wired into CI, and production gating verified in staging. Defer the shared/internal viewer, global install, and mail/SMS/webhook integration until the project exits beta and the maintainership/roadmap questions are answered. Re-review the assessment at v0.1.0 stable or the first protocol breaking change, whichever comes first.