Sourcemaps Lookup Laravel Package

Product Decisions This Supports

• Error Tracking & Debugging: Enables symbolicating JavaScript errors in production (e.g., Sentry, Rollbar, or custom error monitoring) by mapping minified stack traces back to original source files/lines. Directly supports feature parity with frontend tools like SourceMap in Chrome DevTools.
• Developer Experience (DX) Tools: Powers IDE plugins, coverage reports, or "Go to Definition" features in editor extensions by resolving generated → original positions (e.g., for TypeScript/JSX in PHP-based tooling).
• Performance Optimization: Justifies build vs. buy for teams handling large-scale JS bundles (e.g., 6MB+ maps) where existing solutions (e.g., axy/sourcemap) are slower or memory-inefficient.
• Roadmap for Source Maps in PHP Ecosystem:
  • Phase 1: Basic stack-trace resolution (core lookup()).
  • Phase 2: Scope-aware debugging (via scopeAt()) to match browser devtools.
  • Phase 3: Integration with existing PHP error handlers (e.g., Monolog, Laravel’s debugbar).
• Use Cases:
  • Error Monitoring: Attach original source context to errors in production.
  • Editor Tooling: Backend for VS Code/Laravel IDE Helpers to resolve JS/TS files.
  • Testing: Generate human-readable stack traces from minified test outputs.
  • Security: Audit third-party dependencies by ignoring ignoreList-marked sources.

When to Consider This Package

Adopt if:

• Your PHP backend processes JavaScript errors (e.g., from frontend frameworks like React/Vue) and needs to resolve stack traces to original source files.
• You work with large source maps (>1MB) and require low-latency lookups (e.g., <5ms for 20 frames).
• Your team already uses PHP for debugging tooling (e.g., Laravel apps with frontend JS) and wants to avoid reinventing the wheel.
• You need scope resolution (e.g., identifying enclosing functions/classes) as a preview feature, with plans to migrate to native scopes when bundlers support it.

Look elsewhere if:

• You need to generate/merge source maps (this package is read-only).
• Your source maps are indexed/sectioned (v3+ feature not supported; file an issue if critical).
• You’re using Source Map v2 or v4 (only v3 is supported).
• You require external source fetching (only inlined sourcesContent is supported).
• Your primary use case is editor tooling (e.g., real-time symbol navigation) where latency for cold starts is unacceptable (cache maps aggressively).
• You’re in a non-PHP environment (e.g., Node.js already has native source-map support).

How to Pitch It (Stakeholders)

For Executives: "This package lets us automatically resolve minified JavaScript errors back to their original source files in PHP, just like Chrome DevTools does for frontend developers. For example, if a user reports an error in our React app, we can now show them the exact line in their original App.tsx—not just a minified bundle.js:42:17. This directly improves debugging velocity for our frontend team and user support quality, while keeping the heavy lifting in PHP (no Node.js dependencies). Benchmarks show it handles 6MB source maps in ~4ms, making it viable for production error tracking at scale. The MIT license and Spatie’s track record mean low risk."

For Engineering: *"This is a drop-in replacement for axy/sourcemap but optimized for PHP’s strengths:

• Lazy parsing: Only decodes mappings for lines you query (memory-efficient for large maps).
• Scope resolution: Preview feature (scopeAt()) to identify enclosing functions/classes, matching browser devtools.
• Bulk lookup support: Cache maps by URL to avoid redundant parsing (critical for stack traces with duplicate frames).
• Strict v3 compliance: Handles edge cases like ignoreList, sourceRoot, and null sources correctly. Use case: Plug this into your error handler (e.g., Sentry, Laravel’s debugbar) to replace eval()-based source maps or manual regex hacks. Example:

$map = SourceMapLookup::fromFile(storage_path('bundle.js.map'));
$position = $map->lookup($errorLine, $errorColumn);
$context = $map->sourceLines($position->sourceFileIndex, $position->sourceLine - 5, $position->sourceLine + 5);

Tradeoff: No write/merge support, but that’s intentional—this is the fastest read-only v3 parser for PHP."*