scssphp

scssphp is a full SCSS-to-CSS compiler written entirely in PHP, requiring no native sass binary, no Node.js toolchain, and no compiled extension. It parses SCSS source into an AST, evaluates variables, mixins, functions, control directives, and Sass modules (@use/@forward), and serializes the result to CSS, with optional source-map generation. It is widely used as the styling engine behind PHP CMSes, static-site generators, and frameworks that need to compile stylesheets at request time or build time without shelling out to an external process.

The project tracks the official Dart Sass reference implementation closely (via the shared sass-spec test suite pulled in as a dev dependency) and aims for close behavioral parity, while remaining a drop-in Composer dependency that runs anywhere PHP runs.

What You Get

• A Compiler class (src/Compiler.php) exposing compileString()/compileFile() for turning SCSS source into CSS
• Full SCSS language support: variables, nesting, mixins, functions, control flow (@if/@each/@for), and the module system (@use/@forward)
• Source map generation via SourceMap\Builder for mapping compiled CSS back to original SCSS lines
• Pluggable importer and logger interfaces (src/Importer, src/Logger) for custom file resolution and warning/error handling
• A value/AST layer (src/Value, src/Ast, src/Evaluation) modeled closely on Dart Sass’s internal architecture for spec-level compatibility

Common Use Cases

• Compiling SCSS to CSS inside PHP-based CMSes or frameworks without a Node.js build step
• Runtime theme/stylesheet compilation where users submit custom SCSS to be rendered live
• Static site generators or build pipelines written in PHP that need SCSS support
• Environments where installing a native Sass binary or Node toolchain isn’t feasible (shared hosting, minimal containers)

Under The Hood

Architecture — scssphp mirrors Dart Sass’s own internal pipeline rather than being a from-scratch reimplementation: SCSS source is parsed into an AST (src/Ast, split into Sass, Css, and Selector subtrees), then walked by visitor classes (src/Visitor) that perform evaluation (src/Evaluation), producing CSS AST nodes that a Serializer (src/Serializer) turns into output text. Compiler (src/Compiler.php, ~850 lines) is the orchestrating entry point wiring parser, evaluator, importer chain, and logger together, and optionally driving SourceMap\Builder to emit a source map alongside the CSS. Custom file resolution goes through the Importer interface, and diagnostics/warnings go through a swappable Logger interface rather than being hard-coded to STDERR. Tech Stack — Pure PHP 8.1+, PSR-4 autoloaded under ScssPhp\ScssPhp, with runtime dependencies on scssphp/source-span (its own source-location package), league/uri/league/uri-interfaces for URL handling in @import/@use resolution, and symfony/filesystem. Requires the ctype, json, and mbstring PHP extensions. Static analysis is enforced via PHPStan (including a deprecation-rules pass). Code Quality — 277 source files under src/ and a substantial test suite under tests/ (PHPUnit-based), including SassSpecTest.php which runs the shared sass/sass-spec conformance suite pulled from the upstream Sass project — the same behavioral spec used to validate Dart Sass — plus framework-integration tests against real-world stylesheets (Bootstrap, Bulma, Foundation, Bourbon) to catch regressions against real SCSS in the wild. API Design — The primary surface is small (Compiler::compileString()/compileFile() returning a CompilationResult), with extensibility exposed through well-defined interfaces (ImporterInterface, LoggerInterface) rather than requiring subclassing internals, keeping typical integration to a few lines of code.