Source Span Laravel Package

Getting Started

• This package is a low-level utility for representing source locations and spans — it’s a dependency of scssphp/scssphp but can be used independently for tooling, diagnostics, or custom SCSS/Sass compilers.
• Start by installing via Composer: composer require scssphp/source-span.
• The core classes are SourceSpan and SourceFile. A SourceSpan represents a contiguous slice of text in a SourceFile, with start/end positions (line/column-based).
• First use case: map errors or warnings back to original source when compiling SCSS.

Implementation Patterns

• Use SourceFile::create() to represent a source file by name and contents.
• Construct SourceSpan objects via SourceSpan::create($file, $start, $end) — positions are Position objects (with line, column, byteOffset).
• Ideal for building diagnostic tools: emit SourceSpan instances alongside error messages (e.g., in custom Sass functions or custom rule linters).
• Common pattern: integrate with custom SCSS compiler plugins or AST processors that need to track and report precise locations (e.g., @error messages or IDE language server integrations).
• When working with source maps or transformations, SourceSpan can be mapped to original sources using position remapping logic.

Gotchas and Tips

• SourceSpan is immutable — always create new instances when positions change.
• Positions use 1-based line and column indices — verify alignment with your parser or editor (many tools use 0-based internally, leading to off-by-one bugs).
• SourceSpan::toString() returns the substring content; use getSourceCode() to access full source if needed.
• The package is minimal — no built-in pretty-printing or error rendering — implement your own formatter (or extend with php-http/message-factory for HTTP diagnostics).
• Check for null spans (e.g., optional metadata) and validate that spans are within file bounds before rendering to avoid runtime exceptions.
• As a standalone utility, ensure your higher-level compiler or tool manages span lifetimes and file references carefully — especially if reusing SourceFile instances across multiple compilations.