Laravel View Xray Laravel Package

Getting Started

• Treat this as a throwaway diagnostic, not a dependency. Install it on a branch you're willing to delete, as a dev-only package:

  composer require beyondcode/laravel-view-xray --dev
  

  The package is archived and its last release targets the Laravel 6/7/8 era. If Composer resolution fails on Laravel 9+, do not wrestle the solver — decide between a fork and the View::composer('*') fallback described below.
• Package auto-discovery registers BeyondCode\ViewXray\ViewXrayServiceProvider, so there is usually no config/app.php edit. Confirm it loaded via php artisan about or by checking bootstrap/cache/packages.php.
• Publish the config and read it before enabling anything. This is where the enable flag and editor command live:

  php artisan vendor:publish --provider="BeyondCode\ViewXray\ViewXrayServiceProvider"
  

  Inspect config/view-xray.php, then set VIEW_XRAY_ENABLED=true in your local .env only. Never put it in a shared .env.example.
• Clear caches whenever you toggle the flag or the config, or the old value silently sticks:

  php artisan config:clear && php artisan view:clear
  

• First use case: load a page, hover the page and look for the overlay labels showing each view's file path, and click a label to jump to that Blade file in your editor. Start on a page with a deep @include/<x-...> tree — a layout plus several partials — where the mapping is genuinely unclear. That is the moment the tool earns its keep; the simplest pages tell you nothing new.

Implementation Patterns

• Feature-to-template mapping. When you need to know which partial owns a UI region before editing it, hover rather than grep. This is faster than searching for class names or copy text across resources/views and is the single most common day-to-day use.
• Defect triage. For "this layout looks wrong on one page" bugs, identify the responsible partial first, then trace the data feeding it. It collapses the usual archaeology of @extends/@section/@include chains.
• Refactor verification. Before and after extracting a partial or converting an @include into an anonymous component, confirm the same file is still rendering the same region. Attribution that changes shape between the two states is a fast signal you moved a boundary.
• Legacy audit / onboarding. Walk the pages that matter during a migration or ownership transfer and build a view inventory and dependency map as you go. That artifact outlives the tool and is often the more valuable output.
• Editor wiring. Point the config's editor-open command at your editor (code -g for VS Code, phpstorm URL scheme, etc.) so a click opens the file. This is the difference between a nice overlay and a real time saver — get it right on day one.
• Pair, don't replace. Xray answers "where did this HTML come from?" — nothing about queries, timing, or exceptions. Keep Debugbar, Telescope, Clockwork, or Ray for that. Use Xray only for view provenance and Debugbar for everything else.
• Local gating as a habit. Env-flag the tool off, and where it matters, IP-allowlist it. Verify dev dependencies are excluded from deploy artifacts so the package can never ship to a shared environment.

Gotchas and Tips

• Archived software is your problem. No upstream fixes will come. Any Laravel upgrade, PHP bump, or middleware signature change is a maintenance question you now own. Assume drift is the default.
• Response injection is fragile. The overlay needs a normal HTML response to inject into. It can silently fail on streamed responses, JSON API responses, responses with a pre-set Content-Length, CSP-restricted pages, or anything a later middleware replaces. If you see nothing, suspect your middleware stack and security headers before blaming the package.
• It does not follow partial DOM swaps. Livewire, HTMX, Turbo, and Inertia render after the initial response, so the injection only ever covers the first full-page HTML. On those surfaces the tool is more misleading than helpful.
• Attribution can be subtly wrong. Compiled views, heavily component-driven templates, and cached Blade can produce labels that point at the wrong file or region. Treat the overlay as a strong hint, not ground truth, before you scope work against it.
• Line numbers drift. Always pair the file path with a fresh view:clear before trusting a line reference, especially after structural refactors.
• Stale config is the classic trap. Toggling VIEW_XRAY_ENABLED or editing the config without config:clear leaves you debugging a setting you never applied. Same for view:cache in local workflows.
• Exposure is the serious failure mode. Enabled outside local, this leaks absolute filesystem paths and an editor-open endpoint. Hard-gate to local, avoid shared staging, and confirm .env values are not committed or inherited.
• Extension point: the fallback logger. When the package won't install or misbehaves, a small view-composer logger reproduces the essential signal and you control it:

  View::composer('*', function ($view) {
      logger()->debug('view', ['name' => $view->getName(), 'path' => $view->getPath()]);
  });
  

  This is your exit ramp — keep it in the README so nobody is blocked when the package breaks.
• Document the exit. Set a removal trigger tied to the next Laravel major, name an owner if you fork, and treat the whole thing as time-boxed. Zero dependents and a 2020 release date mean the value is real but the support burden is entirely yours.