Looking up a position | sourcemaps-lookup | Spatie

 SPATIE

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

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Sourcemaps-lookup](https://spatie.be/docs/sourcemaps-lookup/v1)  Basic-usage  Looking up a position

 Version   v1

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

  Looking up a position
- [ 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)

 Looking up a position
=====================

###  On this page

1. [ Loading a source map ](#content-loading-a-source-map)
2. [ Looking up a position ](#content-looking-up-a-position)
3. [ The ](#content-the-position-object)
4. [ When ](#content-when-lookup-returns-null)

Loading a source map
--------------------------------------------------------------------------------------------------------------------

You can construct a `SourceMapLookup` from a file path, a raw JSON string, or an already decoded array.

```
use Spatie\SourcemapsLookup\SourceMapLookup;

// From a file path (reads and decodes).
$map = SourceMapLookup::fromFile('/path/to/bundle.js.map');

// From a JSON string (for example, contents already in memory).
$map = SourceMapLookup::fromJson($json);

// From an array (for example, when you already decoded the JSON).
$map = SourceMapLookup::fromArray($data);
```

Construction is cheap. The raw `mappings` string is stored but not parsed until you actually call `lookup()`. Only the lines you touch are decoded.

Looking up a position
-----------------------------------------------------------------------------------------------------------------------

```
$position = $map->lookup(line: 42, column: 17);
```

`$line` is **1-based** (matches stack trace conventions). `$column` is **0-based** (matches the Source Map v3 spec and browsers).

The call returns a `Position` object, or `null` if no mapping applies for that coordinate (see below).

The lookup returns the last mapping on the given line whose generated column is less than or equal to `$column`, following the standard Source Map v3 lookup semantics.

The `Position` object
-------------------------------------------------------------------------------------------------------------------

```
readonly class Position
{
    public int $sourceLine;          // 1-based
    public int $sourceColumn;        // 0-based
    public ?string $sourceFileName;  // resolved with sourceRoot when present, null if spec-null
    public int $sourceFileIndex;     // index into sources[] / sourcesContent[]
    public ?string $name;            // symbol name, or null for 4-field mappings
}
```

When the source map has a `sourceRoot`, `sourceFileName` is returned as `sourceRoot . sources[i]`. The package does not further resolve relative paths. If you need absolute URLs, do that in your caller.

When `lookup()` returns `null`
--------------------------------------------------------------------------------------------------------------------------------------

`lookup()` returns `null` in three cases, all of which mean "no original source for this position":

1. No mappings exist for the requested line.
2. No mapping on the line has `generatedColumn