Probe Laravel Package

Getting Started

• Install as a dev-only Composer dependency, then run php artisan probe:install. Treat Probe as a local/staging tool first; confirm the generated config, routes, middleware, and service-provider environment gating before opening the UI.
• Look first at the registered Probe route/middleware and the generated config. Verify it is disabled outside local/dev and that any impersonation or cookie-decryption features are appropriately restricted.
• First use case: open the Probe UI, select a simple GET endpoint such as a users index route, inspect the discovered URI parameters and auth badge, dispatch the request, and review the response plus telemetry. This validates route discovery, transport, and profiler capture in one pass.
• For versioned APIs, start with the top-bar version switcher and a known versioned route prefix. For protected APIs, use the auth badges and, if applicable, a disposable local Sanctum user for one-click impersonation.

Implementation Patterns

• Route-first exploration: Rely on Laravel’s route collection rather than annotations. Use Probe for quick manual contract checks, parameter discovery, and response inspection during feature work.
• Version-aware workflows: Keep API version signals consistent across route prefixes, route names, controller namespaces, middleware, and docblocks. The version switcher is most useful when those conventions are deliberate rather than mixed.
• Auth persona testing: Use the visual auth badges to confirm whether routes are public, session-protected, Sanctum-protected, API-key-protected, bearer-token-protected, or basic-auth-protected. Use one-click Sanctum impersonation with dedicated development users, not real user accounts.
• Schema-driven payloads: Let Probe derive request bodies from FormRequests, inline $request->validate(), and Spatie Laravel Data. Use the generated faker examples as starting payloads, then adjust for domain constraints and custom rules.
• Transport choice: Use in-process dispatch through the Laravel HTTP Kernel for fast local iteration and to avoid artisan serve worker deadlocks. Switch to standard HTTP transport when debugging behavior that depends on the real HTTP stack, such as headers, middleware ordering, throttling, or CORS.
• Safe mutation testing: Use Dry Run for POST, PUT, and DELETE exploration. It is useful for inspecting validation, authorization, and SQL behavior before deciding whether to persist changes.
• Telemetry-assisted debugging: After dispatch, inspect captured SQL queries with timings and connection info, application logs, dumped variables, and decrypted cookies. This is the main day-to-day advantage over a plain REST client.
• Exploration-to-test workflow: Turn a useful request/response pair into a Pest feature test, then move it into the test suite and harden assertions, factories, authentication setup, and fakes. Treat generated tests as scaffolding, not final coverage.
• Export and documentation flow: Use probe:export for OpenAPI, Postman, or Scribe catalog output, and probe:scribe-sync when maintaining Scribe docs. Review exports before committing them because generated artifacts can expose internal routes, payload examples, or auth assumptions.
• Team integration: Standardize on dev seed data and disposable personas so Probe requests are reproducible. Pair it with existing debugging tools rather than replacing Telescope, Laravel logs, or Pest for automated coverage.

Gotchas and Tips

• Early-stage package: v0.1.0 is an initial release. Pin the version, review changelogs before upgrading, and avoid depending on internal APIs or generated file formats until they stabilize.
• Production exposure is the main risk: Probe includes request dispatch, auth impersonation, cookie decryption, and telemetry. Enforce dev-only registration and authorization at the middleware/config level, and verify it in a production-like environment.
• Dry Run is not a universal rollback: Database transaction rollback will not undo queued jobs, mail, file storage, cache writes, external API calls, or other non-transactional side effects. Use it for database-centric exploration, not as a guarantee of safety.
• In-process dispatch differs from real HTTP: It is convenient and avoids local server worker issues, but it may bypass or reorder behavior tied to the actual HTTP server. Use standard HTTP transport when diagnosing transport-level issues.
• Impersonation needs guardrails: One-click Sanctum impersonation is powerful. Restrict it to local/dev, use disposable users, and avoid real tokens or production identities.
• Version detection is heuristic: URI paths, prefixes, route names, controller namespaces, middleware, and docblocks can conflict. If routes are grouped incorrectly, normalize naming/prefix conventions and check the route list before blaming the UI.
• Validation reflection has limits: Custom rules, conditional validation, Rule::when, and dynamically composed rules may not produce a complete schema. Manually adjust payloads for complex endpoints.
• Cookie inspection depends on app encryption: Decrypted cookie display relies on the correct APP_KEY and cookie configuration. Mismatched keys or encrypted session cookies may appear opaque.
• Telemetry can capture sensitive data: SQL, logs, dumps, cookies, and generated tests/exports can contain secrets or personal data. Scrub before sharing and avoid pointing Probe at production data.
• Clear caches when discovery looks stale: Route and config caching can make the UI appear out of date during development. Clear caches after changing route registration, middleware, or Probe configuration.
• Generated Pest tests need review: Confirm authentication, factories, database state, assertions, and cleanup. A generated test that reproduces a request is not automatically a good regression test.
• Exports are artifacts, not source of truth: Review OpenAPI/Postman/Scribe output for internal routes, inaccurate examples, and auth leakage before committing or publishing.