scssphp

https://scssphp.github.io/scssphp
Admin
scssphp is a compiler for Sass written in PHP that adds features like variables, mixins, imports,...
Tokens:9,294
Snippets:134
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install SCSSPHP using Composer

Source: https://scssphp.github.io/scssphp

Use Composer to install the SCSSPHP library. Ensure you are using a compatible PHP version (8.1 or above).

```bash
composer require scssphp/scssphp "^2.1.0"
```

--------------------------------

### Compile SCSS String to CSS

Source: https://scssphp.github.io/scssphp

Use the SCSSPHP Compiler class to compile SCSS code into CSS. This example demonstrates basic variable and function usage.

```php
require "vendor/autoload.php";

use ScssPhp\ScssPhp\Compiler;

$compiler = new Compiler();

echo $compiler->compileString(' 
  $color: #abc;
  div { color: lighten($color, 20%); }
')->getCss();

```

--------------------------------

### Handle SCSS Compilation Exceptions

Source: https://scssphp.github.io/scssphp/docs

Safely compile SCSS strings and catch potential exceptions to prevent sensitive data exposure in production environments. This example logs errors and outputs an empty string instead of the stack trace.

```php
use ScssPhp\ScssPhp\Compiler;

try {
    $compiler = new Compiler();

    echo $compiler->compileString($content)->getCss();
} catch (\Exception $e) {
    echo '';
    syslog(LOG_ERR, 'scssphp: Unable to compile content');
}

```

--------------------------------

### Migrating Legacy Function to Rest Argument

Source: https://scssphp.github.io/scssphp/docs/extending/custom-functions.html

Example of migrating a legacy function that did not declare arguments to a modern signature using a rest argument. This ensures compatibility and clearer argument handling.

```php
$compiler->registerFunction(
  'foo',
  function (array $args) use ($compiler) {
    $restArgument = $args[0];
    $positionalArgs = $restArgument[2];
    $keywordArgs = $compiler->getArgumentListKeywords($restArgument);
    // Do something to return a value
  },
  ['args...']
);

```

--------------------------------

### Registering a Modern Custom Function

Source: https://scssphp.github.io/scssphp/docs/extending/custom-functions.html

Implement a custom function with a strict signature `callable(array $args): Value`. Arguments are passed as a list of Sass values. This example registers an 'add-two' function that sums two numbers without units.

```php
use ScssPhp\ScssPhp\Compiler;
use ScssPhp\ScssPhp\Value\SassNumber;
use ScssPhp\ScssPhp\Value\Value;

$compiler = new Compiler();

$compiler->registerFunction(
  'add-two',
  /** @param list<Value> $args */
  function(array $args): Value {
    $number1 = $args[0]->assertNumber('number1');
    $number2 = $args[1]->assertNumber('number2');

    $number1->assertNoUnits('number1');
    $number2->assertNoUnits('number2');

    return SassNumber::create($number1->getValue() + $number2->getValue());
  },
  ['number1', 'number2']
);

$compiler->compileString('.ex1 { result: add-two(10, 10); }')->getCss();
$compiler->compileString('.ex1 { result: add-two($number1: 10, $number2: 10); }')->getCss();

```

--------------------------------

### Registering a Legacy Custom Function

Source: https://scssphp.github.io/scssphp/docs/extending/custom-functions.html

Register a custom function using the legacy approach where the callable receives a single argument: an array of Sass values. This example demonstrates an 'add-two' function similar to the modern version but uses legacy assertion methods.

```php
use ScssPhp\ScssPhp\Compiler;
use ScssPhp\ScssPhp\Node\Number;

$compiler = new Compiler();

$compiler->registerFunction(
  'add-two',
  function($args) use ($compiler) {
    $number1 = $compiler->assertNumber($args[0], 'number1');
    $number2 = $compiler->assertNumber($args[1], 'number2');

    $number1->assertNoUnits('number1');
    $number2->assertNoUnits('number2');

    return new Number($number1->getDimension() + $number2->getDimension(), '');
  },
  ['number1', 'number2']
);

$compiler->compileString('.ex1 { result: add-two(10, 10); }')->getCss();
$compiler->compileString('.ex1 { result: add-two($number1: 10, $number2: 10); }')->getCss();

```

--------------------------------

### Output Formatting Styles

Source: https://scssphp.github.io/scssphp/docs

Demonstrates the difference between EXPANDED and COMPRESSED output styles for SCSS compilation. Use setOutputStyle to configure.

```scss
/*! Comment */
.navigation {
    ul {
        line-height: 20px;
        color: blue;
        a {
            color: red;
        }
    }
}

.footer {
    .copyright {
        color: silver;
    }
}


```

```text
OutputStyle::EXPANDED:
/*! Comment */
.navigation ul {
  line-height: 20px;
  color: blue;
}
.navigation ul a {
  color: red;
}
.footer .copyright {
  color: silver;
}


```

```text
OutputStyle::COMPRESSED:
/* Comment*/.navigation ul{line-height:20px;color:blue;}.navigation ul a{color:red;}.footer .copyright{color:silver:}

```

--------------------------------

### Set Import Paths and Compile

Source: https://scssphp.github.io/scssphp/docs

Configures the compiler to search for imported SCSS files in a specified directory before compiling a string. Imports are resolved relative to these paths.

```php
use ScssPhp\ScssPhp\Compiler;

$compiler = new Compiler();
$compiler->setImportPaths('assets/stylesheets/');

// will search for 'assets/stylesheets/mixins.scss'
echo $compiler->compileString('@import "mixins.scss";')->getCss();

```

--------------------------------

### Enable Source Maps

Source: https://scssphp.github.io/scssphp/docs

Configures the compiler to generate source maps for debugging CSS. Source maps can be file-based or inlined. Options like sourceMapURL and sourceMapFilename can be set.

```php
use ScssPhp\ScssPhp\Compiler;

$compiler = new Compiler();
$compiler->setSourceMap(Compiler::SOURCE_MAP_FILE);
$compiler->setSourceMapOptions([
    // relative or full url to the above .map file
    'sourceMapURL' => './my-style.map',

    // (optional) relative or full url to the .css file
    'sourceMapFilename' => 'my-style.css',

    // partial path (server root) removed (normalized) to create a relative url
    'sourceMapBasepath' => '/var/www/vhost',

    // (optional) prepended to 'source' field entries for relocating source files
    'sourceRoot' => '/',
]);

$result = $compiler->compileString('@import "sub.scss";');

file_put_contents('/var/www/vhost/my-style.map', $result->getSourceMap());
file_put_contents('/var/www/vhost/my-style.css', $result->getCss());

// use Compiler::SOURCE_MAP_INLINE for inline (comment-based) source maps

```

--------------------------------

### Compile SCSS String

Source: https://scssphp.github.io/scssphp/docs

Compiles a string of SCSS code using the Compiler class. Throws SassException on error. Returns a CompilationResult object.

```php
use ScssPhp\ScssPhp\Compiler;

$compiler = new Compiler();

echo $compiler->compileString(
  '$color: #abc;
  div { color: lighten($color, 20%); }'
)->getCss();

```

--------------------------------

### Presetting SCSS Variables

Source: https://scssphp.github.io/scssphp/docs/extending/preset-variables.html

Use `replaceVariables` to set SCSS variables before compilation. The `!default` flag in SCSS prevents preset variables from being overridden if defined in the source. Variable names can be normalized.

```php
use ScssPhp\ScssPhp\Compiler;
use ScssPhp\ScssPhp\ValueConverter;

$compiler = new Compiler();
$compiler->replaceVariables(array(
    'var' => ValueConverter::parseValue('false'),
    'size' => ValueConverter::parseValue('25px'),
));

echo $compiler->compileString('$var: true !default; @debug $var;')->getCss();

```
Tokens:
Raw