Introduction | sourcemaps-lookup | Spatie

 SPATIE

sourcemaps-lookup
=================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Sourcemaps-lookup](https://spatie.be/docs/sourcemaps-lookup/v1)  Introduction

 Version   v1

 Other versions for crawler [v1](https://spatie.be/docs/sourcemaps-lookup/v1)

- [ Introduction ](https://spatie.be/docs/sourcemaps-lookup/v1/introduction)
- [ Support us ](https://spatie.be/docs/sourcemaps-lookup/v1/support-us)
- [ Requirements ](https://spatie.be/docs/sourcemaps-lookup/v1/requirements)
- [ Installation & setup ](https://spatie.be/docs/sourcemaps-lookup/v1/installation-setup)
- [ Benchmarks ](https://spatie.be/docs/sourcemaps-lookup/v1/benchmarks)
- [ Questions and issues ](https://spatie.be/docs/sourcemaps-lookup/v1/questions-issues)
- [ About us ](https://spatie.be/docs/sourcemaps-lookup/v1/about-us)
- [ Changelog ](https://spatie.be/docs/sourcemaps-lookup/v1/changelog)

Basic usage
-----------

- [ Looking up a position ](https://spatie.be/docs/sourcemaps-lookup/v1/basic-usage/looking-up-a-position)
- [ Reading inlined source content ](https://spatie.be/docs/sourcemaps-lookup/v1/basic-usage/reading-source-content)
- [ Error handling ](https://spatie.be/docs/sourcemaps-lookup/v1/basic-usage/error-handling)
- [ Complete example ](https://spatie.be/docs/sourcemaps-lookup/v1/basic-usage/complete-example)

Advanced usage
--------------

- [ Reverse lookup ](https://spatie.be/docs/sourcemaps-lookup/v1/advanced-usage/reverse-lookup)
- [ Resolving the enclosing scope ](https://spatie.be/docs/sourcemaps-lookup/v1/advanced-usage/resolving-the-enclosing-scope)
- [ Marking third-party sources ](https://spatie.be/docs/sourcemaps-lookup/v1/advanced-usage/marking-third-party-sources)
- [ Listing the source files ](https://spatie.be/docs/sourcemaps-lookup/v1/advanced-usage/listing-source-files)
- [ Tips for bulk lookups ](https://spatie.be/docs/sourcemaps-lookup/v1/advanced-usage/tips-for-bulk-lookups)
- [ Supported source map features ](https://spatie.be/docs/sourcemaps-lookup/v1/advanced-usage/supported-features)
- [ Under the hood ](https://spatie.be/docs/sourcemaps-lookup/v1/advanced-usage/under-the-hood)

  Sourcemaps-lookup
===================

 Fast and memory-efficient JavaScript source map lookup for PHP

### Useful links

- [Repository](https://github.com/spatie/sourcemaps-lookup)
- [Discussions](https://github.com/spatie/sourcemaps-lookup/discussions)

Introduction
------------

This package resolves JavaScript stack frame positions against a [Source Map v3](https://tc39.es/ecma426/) file. It returns the original source file, line, column, symbol name, and enclosing scope. It is tuned for stack frame resolution (for example, symbolicating JavaScript errors using an uploaded source map), and is narrowly focused on the read path. It does not write, merge, or transform maps.

```
use Spatie\SourcemapsLookup\SourceMapLookup;

$map = SourceMapLookup::fromFile('bundle.js.map');

// Resolve a generated position to its original source location.
$position = $map->lookup(42, 17);
echo $position->sourceFileName;  // "src/app.tsx"
echo $position->sourceLine;      // 1-based
echo $position->sourceColumn;    // 0-based

// Resolve the enclosing source-language scope.
$scope = $map->scopeAt(42, 17);
echo $scope->name;               // "onClick"
echo $scope->parent?->name;      // "DeeplyNestedTrigger"
```

Resolving 20 stack frames against a 6 MB production source map takes around 3.8 ms and uses about 18 MiB of memory on an Apple M1 Pro. See [Benchmarks](/docs/sourcemaps-lookup/v1/benchmarks) for the full picture.