scssphp/server

Server for on-the-fly .scss compilation

scssphp

https://scssphp.github.io/scssphp

scssphp is a compiler for SCSS written in PHP.

Checkout the homepage, https://scssphp.github.io/scssphp, for directions on how to use.

Running Tests

scssphp uses PHPUnit for testing.

Run the following command from the root directory to run every test:

vendor/bin/phpunit tests

There are several tests in the tests/ directory:

• ApiTest.php contains various unit tests that test the PHP interface.
• ExceptionTest.php contains unit tests that test for exceptions thrown by the parser and compiler.
• FailingTest.php contains tests reported in Github issues that demonstrate compatibility bugs.
• InputTest.php compiles every .scss file in the tests/inputs directory then compares to the respective .css file in the tests/outputs directory.
• SassSpecTest.php extracts tests from the sass/sass-spec repository.

When changing any of the tests in tests/inputs, the tests will most likely fail because the output has changed. Once you verify that the output is correct you can run the following command to rebuild all the tests:

BUILD=1 vendor/bin/phpunit tests

This will compile all the tests, and save results into tests/outputs. It also updates the list of excluded specs from sass-spec.

To enable the full sass-spec compatibility tests:

TEST_SASS_SPEC=1 vendor/bin/phpunit tests

Coding Standard

scssphp source conforms to PSR12.

Run the following command from the root directory to check the code for "sniffs".

vendor/bin/phpcs --standard=PSR12 --extensions=php bin src tests *.php

Static Analysis

scssphp uses phpstan for static analysis.

Run the following command from the root directory to analyse the codebase:

make phpstan

As most of the codebase is composed of legacy code which cannot be type-checked fully, the setup contains a baseline file with all errors we want to ignore. In particular, we ignore all errors related to not specifying the types inside arrays when these arrays correspond to the representation of Sass values and Sass AST nodes in the parser and compiler. When contributing, the proper process to deal with static analysis is the following:

1. Make your change in the codebase
2. Run make phpstan
3. Fix errors reported by phpstan when possible
4. Repeat step 2 and 3 until nothing gets fixed anymore at step 3
5. Run make phpstan-baseline to regenerate the phpstan baseline

Additions to the baseline will be reviewed to avoid ignoring errors that should have been fixed.

server's Issues

Refactor

Copied from: scssphp/scssphp#2

Rationale:

• the Server class is getting bloated
• the Server class has too many public functions:
  • compileFile() - always recompiles
  • checkedCompile() - compiles scss if cache doesn't exist
  • checkCachedCompile() - recompiles if necessary
  • serve() - the original purpose of this class

Identified candidate cache implementations:

• never - no caching; always (re)compiles
• read - read only if cache exists; doesn't create
• once - compiles only if cache doesn't exist
• surface/shallow - recompile if main .scss file changes (note: this has no current API equivalent)
• deep - recompile if main .scss file or any of its imports changes

Technical considerations:

• bust up the Server class
• Cache/*.php implementations
• "deep" should detect changes in setVariables() and setImportPaths()

Other changes:

• make Compiler cache aware (also, see existing importCache)
• stale file detection using algorithm instead of metadata leafo/scssphp#321
• parse tree cache leafo/scssphp#328
• register custom error handler leafo/scssphp#330
• register custom input finder leafo/scssphp#329
• option to set/override or remove comment "compiled by scssphp..." leafo/scssphp#477
• option to compress (gzip) output leafo/scssphp#483

State of the project

This project has not seen any recent activity. And it will be impacted by deprecations coming in scssphp 1.5.

This project should either be officially abandoned or be updated for new versions of scssphp.
However, I have absolutely no interest into maintaining this scssphp/server package myself. So I won't do the work of updating it myself.

/cc @robocoder

Caching problems

After having upgraded from 1.0.9 to 1.5.1, the caching no longer works as expected.

As an example - I have three files:

# a.scss
@import 'b';
@import 'c';

body {
    height: 100%;
}

# b.scss
body {
    height: 100%;
}

# c.scss
body {
    height: 100%;
}

This produces the following metafiles

# Version 1.5.1
a:3:{s:4:"etag";s:32:"601fc4bcc19b878a97a57ae8927cd4e5";s:7:"imports";a:2:{s:33:"/var/www/css/theme/othello/b.scss";i:1636627636;s:33:"/var/www/css/theme/othello/c.scss";i:1636627636;}s:4:"vars";i:2723407904;}

# Version 1.0.9
a:3:{s:4:"etag";s:32:"ce69e5d65310f5daaec2885e5d070987";s:7:"imports";a:3:{s:33:"/var/www/css/theme/othello/a.scss";i:1636627636;s:33:"/var/www/css/theme/othello/b.scss";i:1636627636;s:33:"/var/www/css/theme/othello/c.scss";i:1636627636;}s:4:"vars";i:2723407904;}

The version 1.0.9 also includes the a.scss file, but version 1.5.1 does not.

I can see that when

server/src/Server.php

Line 229 in 87599c4

'imports' => $this->makeParsedFilesFromIncludeFiles($result->getIncludedFiles()),

changed from $this->scss->getParsedFiles() to the current version, the original file isn't anymore a part of the returned filed.

I'd like to help and mostly need to know, whether the line https://github.com/scssphp/scssphp/blob/eba0633bf8a527738d2aca210b4a0cb182599c5d/src/CompilationResult.php#L54 ought to also include the originally parsed file, or if we should add it manually in this repository?

Best regards
/Jesper

PHP 8.2 fix

Due to some deprecatons in PHP v8.2, Server.php line # 215 needs to be changed to move the $ into the curly braces

        $css  = "/* compiled by scssphp $v on $t ({$elapsed}s) */\n\n" . $css;

instead of

        $css  = "/* compiled by scssphp $v on $t (${elapsed}s) */\n\n" . $css;

New version release?

Any chance of getting a new version released?
We are still very much using this library and it would be great to update with the latest changes.